[demo] missing_docs drift-watch: resolve oz CLI drift (GA docs + gated deferral)#279
Merged
hongyi-chen merged 2 commits intoJun 30, 2026
Merged
Conversation
…, oz provider) Demonstrates the missing_docs drift-watch loop end to end on real drift. The audit flagged 15 undocumented `oz` subcommands; this resolves all of them according to each command's GA rollout status: - GA (NamedAgents): document the `oz agent` named-agent management group (list/get/create/update/delete + `oz agent skills`) and fix the existing `oz agent list` entry, which incorrectly described skill listing. - GA (ConversationApi): document `oz run conversation get` and the `oz run message` inbox commands (list/read/watch/send/mark-delivered). - Non-GA (ProviderCommand = dogfood): defer the whole `oz provider` group via `gated:ProviderCommand` so it auto-surfaces for docs when it goes GA. All command flags drafted from crates/warp_cli source (agent.rs, task.rs, provider.rs). CLI audit now reports 0 gaps; cli_commands gated_non_ga = 14. Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
I'm starting a first review of this pull request. I cancelled the in-progress review run because this pull request was closed. Powered by Oz |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this is
A live drift-detection demo for the
missing_docsskill (stacked on #201). It runs the skill's drift-watch loop on real, current drift in theozCLI and resolves every finding according to each command's GA rollout status — including the newgated:<Flag>deferral mechanism from #201.This is the "actual drift-detection test" requested: the audit found 15 undocumented CLI subcommands, and this PR closes all of them.
The drift the audit detected
python3 .agents/skills/missing_docs/scripts/audit_docs.py --category cliflagged 15 undocumentedozsubcommands across three command groups:oz agent get/create/update/delete/skillsoz run conversation/conversation get/message(+watch/send/list/read/mark-delivered)oz provider setup/listHow each group was resolved (by rollout status)
The skill defers non-GA surfaces and documents GA ones. Statuses were confirmed via the audit's own
compute_flag_statusesagainstcrates/warp_features:NamedAgents= ga → documented theoz agentnamed-agent management group in the CLI reference, drafted flag-by-flag fromcrates/warp_cli/src/agent.rs. Also fixed an existing bug: the oldoz agent listentry incorrectly described listing skills with--repo(that behavior is actuallyoz agent skills).ConversationApi= ga → documentedoz run conversation getand theoz run messageinbox commands, drafted fromcrates/warp_cli/src/task.rs.ProviderCommand= dogfood (non-GA) → deferred the wholeoz providergroup viagated:ProviderCommandin the surface map. It is intentionally undocumented while non-GA and will auto-surface as a finding onceProviderCommandgoes GA. This is the core demonstration of the gated mechanism on real drift.Validation
audit_docs.py --category cli→ 0 gaps (was 15).accounting:cli_commands.finding: 0,gated_non_ga: 14(11 Agent Memory + 3oz provider),map_hygiene: 0,unaccounted: {}.suggest_reviewers.py) for the documented sources (crates/warp_cli/*) → @bnavetta, @ianhodge.The remaining gaps in the full audit (18 API spec gaps, 29 LOW terminology) are pre-existing and unrelated to this change.
Files changed
src/content/docs/reference/cli/index.mdx— GA command docs +oz agent listbug fix..agents/skills/missing_docs/references/feature_surface_map.md—oz providergroup deferred viagated:ProviderCommand.Conversation: https://staging.warp.dev/conversation/c5ce6a1a-81a4-4a04-92d9-8d587693be12
Run: https://oz.staging.warp.dev/runs/019f19e2-f981-725b-b383-bc7ea01adb6a
Plans:
This PR was generated with Oz.