audit-docs-commands

Metadata

Description

## Description
COMMANDS.md is the canonical CLI reference. Cross-check every command + flag against `wg --help-all` and per-command `--help` output. Identify missing commands, missing flags, stale flags, wrong descriptions.

## Baseline

Determine baseline = last commit that touched this file by a human (heuristic: commits NOT authored by an agent — agent commits have agent IDs in commit messages; human commits do not). If unclear, fall back to 2026-04-12 (date of prior doc-sync-audit doc).

Audit scope = ALL changes to wg behavior / commands / config / state-machine / etc. SINCE that baseline. Not just today. Look at git log between baseline and HEAD.

## Output (no source/doc changes)
Post findings via \`wg log <this-task-id>\` as a structured list of deltas. Each delta = one specific update needed in the audited file. Format:

  - **Section X:** <what is currently said vs what should be said, with citation>
  - **Missing:** <feature/command/concept not mentioned>
  - **Stale:** <reference to removed or superseded thing>
  - **Inconsistent:** <conflicts with another doc — note which>

The synthesis task (doc-sync-audit) reads all audit logs and applies updates. This task DOES NOT MODIFY FILES.

## Validation
- [ ] Baseline commit identified (cite SHA or fall back to 2026-04-12 with reasoning)
- [ ] Delta list posted via wg log with structured entries
- [ ] No source / doc modifications — audit only

Depends on

• done quality-pass-doc
• done .assign-audit-docs-commands

Required by

• done doc-sync-audit

Log

• 2026-04-30T02:05:06.324653681+00:00 Task paused
• 2026-04-30T02:06:52.168184812+00:00 Task published
• 2026-04-30T02:07:26.824904873+00:00 Lightweight assignment: agent=Default Evaluator (31847164), exec_mode=light, context_scope=task, reason=Evaluator role with 0.86 score and 377 audit tasks is ideal for systematic cross-check of documentation against CLI behavior; read-only exploration matches task's no-modification requirement.
• 2026-04-30T02:14:16.644919623+00:00 Spawned by coordinator --executor claude --model sonnet
• 2026-04-30T02:14:29.202446092+00:00 Starting audit of docs/COMMANDS.md vs wg --help-all output
• 2026-04-30T02:18:59.139068523+00:00 Baseline: commit 801275ddb (2026-04-21) — human commit 'refactor: rip the autonomous coordinator heartbeat'. Audit covers all CLI changes since that date. Findings ready to post.
• 2026-04-30T02:19:23.053223036+00:00 FINDINGS PART 1 — Stale flags (removed from CLI but still in COMMANDS.md): - **Stale (wg add):** --verify <CRITERIA> flag documented in 'wg add' options table (line ~55) but removed from CLI. wg add --help shows no --verify flag. - **Stale (wg add):** --verify-timeout <DUR> documented in 'wg add' options table (line ~63) but not in CLI. - **Stale (wg edit):** --verify <CRITERIA> documented in 'wg edit' options table (line ~154) but removed from CLI. wg edit --help shows no --verify. - **Stale (wg compact):** Entire section 'wg compact' (~lines 3905-3918) documents a command that no longer exists. 'wg compact' was retired (commit 2422b05b4 'retire .compact-N and .archive-N cycle scaffolding'). Error: 'unrecognized subcommand compact'. - **Stale (wg service start):** --no-coordinator-agent documented as the canonical flag; it is now the legacy alias. Canonical flag is --no-chat-agent. - **Stale (wg service):** create-coordinator / delete-coordinator / archive-coordinator / stop-coordinator / interrupt-coordinator are documented as canonical subcommands. They are now legacy aliases; canonical names are create-chat / delete-chat / archive-chat / stop-chat / interrupt-chat. - **Stale (wg config):** --coordinator-executor documented as canonical; it is now a legacy alias. Canonical is --dispatcher-executor. --coordinator-model is now an alias; canonical is buried in the help text.
• 2026-04-30T02:19:40.869555632+00:00 FINDINGS PART 2 — Missing flags on existing documented commands: - **Missing (wg add):** --no-tier-escalation — 'Opt out of tier escalation on retry for this task' - **Missing (wg add):** -p, --priority <PRIORITY> — 'Task priority (higher = more important). Accepts a number or name: critical (100), high (50), normal (10), low (5), idle (0)'. COMMANDS.md has no priority flag on add (only wg reprioritize, which itself is missing from docs). - **Missing (wg add):** --subtask — 'Create as a blocking subtask: child is created, parent waits for child to complete' - **Missing (wg done):** --ignore-unmerged-worktree — 'Defer worktree merge: mark done even if worktree branch cannot be cleanly merged, creating a .merge-<id> task for later resolution' - **Missing (wg done):** --full-smoke — 'Run every scenario in the smoke manifest, not just those owned by this task' - **Missing (wg done):** --skip-smoke — 'Bypass the smoke gate. Loud-warns; refused for agents unless WG_SMOKE_AGENT_OVERRIDE=1 is exported' - **Missing (wg list):** --cron — 'Only show cron-scheduled tasks' - **Missing (wg list):** --all — 'Show all tasks including dot-prefixed system tasks (hidden by default)' - **Missing (wg gc):** --worktrees — 'GC orphaned agent worktrees under .wg-worktrees/ instead of graph tasks' - **Missing (wg gc):** --apply — 'With --worktrees: actually remove matched worktrees' - **Missing (wg gc):** --force — 'With --worktrees: also remove worktrees that have uncommitted changes' - **Missing (wg viz):** --all changed semantics — docs say 'Include done tasks (default: only open tasks)' but help says 'Show all tasks including fully-done trees (default: active trees only)'. Minor wording difference. - **Missing (wg config):** --merged — explicit flag for showing effective merged config - **Missing (wg config):** --no-reload — undocumented new config flag - **Missing (wg config):** --dispatcher-executor — canonical (replaces --coordinator-executor) - **Missing (wg config):** --reset, --route, --keep-keys, --dry-run, --yes — new config reset workflow flags - **Missing (wg service start):** --no-chat-agent canonical flag (--no-coordinator-agent documented as primary is now the alias)
• 2026-04-30T02:19:59.184903631+00:00 FINDINGS PART 3 — Missing commands (in wg --help-all but not in COMMANDS.md): - **Missing:** wg nex — Full-featured interactive agentic REPL for coding. Flags: -m/--model, -e/--endpoint, --system-prompt, --max-turns, -c/--chatty, -v/--verbose, -r/--read-only, --resume, --role, --chat-id, --chat, --autonomous, --no-mcp, --eval-mode, --idle-timeout-secs, --minimal-tools - **Missing:** wg secret — Manage secrets (API keys) in the credential store. Subcommands: set, get, list, rm, check, backend - **Missing:** wg reprioritize — Change a task's priority level (critical, high, normal, low, idle). Args: <TASK> <PRIORITY> - **Missing:** wg html — Render workgraph as static, clickable HTML viewer. Flags: --out, --public-only, --all, --chat, --since - **Missing:** wg recover — Batch-recover from credit-exhaustion / mass-failure. Flags: --yes, --filter, --set-model, --set-endpoint, --keep-agency, --max-attempts, --reason - **Missing:** wg migrate — One-shot graph migration. Subcommands: chat-rename, retire-compact-archive, config, secrets - **Missing:** wg agent-guide — Print universal agent/chat-agent role contract - **Missing:** wg which — Print workgraph directory path wg would use (resolver debugging) - **Missing:** wg coordinator — Manage coordinator sessions. Subcommands: list, archive, restore - **Missing:** wg executors — List executors wg knows about, which are usable, and binary paths. Flags: --all - **Missing:** wg incomplete — Mark a task as incomplete (retryable). Flags: --reason - **Missing:** wg insert — Insert a new task at a position relative to an existing target. Args: <POSITION> <TARGET>. Flags: --title, -d, --id, --splice, --replace-edges - **Missing:** wg reap — Reap dead/done/failed agents from the registry. Flags: --dry-run, --older-than - **Missing:** wg rescue — Rescue a failed task by inserting a replacement. Args: <TARGET>. Flags: -d/--description, --title, --id, --from-eval - **Missing:** wg reset — Bulk-reset a subgraph. Args: <SEED>. Flags: --seeds, --direction, --also-strip-meta, --dry-run, --yes - **Missing:** wg session — Manage nex chat sessions. Subcommands: list, attach, new, fork, alias, rm, release, status, check - **Missing:** wg tui-nex — Interactive agentic TUI (ratatui-based nex) - **Missing:** wg tui-pty — PTY-embedded nex TUI (spawns wg nex as PTY child) - **Missing:** wg worktree — Manage agent worktrees. Subcommands: list, archive, gc
• 2026-04-30T02:20:15.194905582+00:00 FINDINGS PART 4 — Service subcommands renamed + new subcommands, and wg chat expansion: Section: Service Commands - **Section wg service:** New canonical subcommand names (old names are legacy aliases): - create-coordinator → create-chat (alias: create-coordinator) - delete-coordinator → delete-chat (alias: delete-coordinator) - archive-coordinator → archive-chat (alias: archive-coordinator) - stop-coordinator → stop-chat (alias: stop-coordinator) - interrupt-coordinator → interrupt-chat (alias: interrupt-coordinator) - **Missing (wg service):** set-executor — 'Hot-swap a chat agent executor and/or model'. Args: <ID>. Flags: --executor, -m/--model - **Missing (wg service):** purge-chats — 'Bulk-purge all chat agents'. Flags: --include-active - **Missing (wg service):** create-chat flags: --executor, -m/--model, -e/--endpoint (per-chat overrides beyond just --name) Section: Communication Commands / wg chat - **Section wg chat:** wg chat now has a full set of subcommands not in COMMANDS.md: create, list, show, attach, send, stop, resume, archive, delete. The current docs treat chat as only a message-sending command, missing the lifecycle management subcommands. - **Missing (wg chat create):** New way to create chats: --name, --executor, -m/--model, -e/--endpoint (richer than wg service create-coordinator) Inconsistency: COMMANDS.md documents wg service create-coordinator and wg service delete-coordinator etc., but these are now aliases. The new chat management surface is primarily through wg chat <subcommand> and wg service <chat-subcommand>.
• 2026-04-30T02:20:40.518786935+00:00 FINDINGS PART 5 — Additional section-level issues and inconsistencies: - **Inconsistent:** Table of Contents includes a 'Trace Commands' section. The deprecated wg trace aliases for function management (extract, list-functions, etc.) note in the Trace Commands section at line ~1033 still reads 'old names still work as hidden aliases' — this is fine but the NOTE itself should clarify these are trace-function aliases (wg trace extract, wg trace instantiate, wg trace list-functions, wg trace show-function, wg trace bootstrap, wg trace make-adaptive). The actual CLI confirms 'wg trace' only has show, export, import subcommands now. - **Inconsistent:** COMMANDS.md wg chat docs (~line 2891) shows only flag-based interaction. wg chat help-all shows it is now a dual-mode command: positional [MESSAGE] mode AND subcommand mode (create, list, show, attach, send, stop, resume, archive, delete). The docs are missing the subcommand tree entirely. - **Missing (wg add):** COMMANDS.md table documents --verify <CRITERIA> but the feedback from CLAUDE.md explicitly says 'wg add --verify flag is rejected — CLAUDE.md template is stale; put criteria under ## Validation in -d body'. The flag is genuinely removed from the CLI. Doc must remove it. - **Missing:** The Global Options section (~line 4192) is missing '--alphabetical' flag (listed in --help-all as '-a, --alphabetical Sort commands alphabetically'). - **Missing:** COMMANDS.md has no section for 'wg spawn-task', 'wg claude-handler', 'wg codex-handler' — these are internal/bridge commands that likely don't need public docs, but should be noted. - **Stale (wg agent run):** Section heading at line ~2028 says 'wg agent run — Run the autonomous agent loop (wake/check/work/sleep cycle)'. The --interval flag description says 'Sleep interval between iterations' — this matches the CLI help. No issue here. - **Section gap:** There is no 'Worktree Management' section in COMMANDS.md despite wg worktree being a documented public command. - **Section gap:** There is no section for wg nex despite it being the primary interactive coding assistant. - **Section gap:** There is no section for wg session despite it being needed for managing nex chat sessions.
• 2026-04-30T02:20:52.544892333+00:00 VALIDATION: - [x] Baseline commit identified: 801275ddb (2026-04-21) — 'refactor: rip the autonomous coordinator heartbeat', the last human-authored commit touching docs/COMMANDS.md (all earlier recent commits have agent task IDs in parentheses) - [x] Delta list posted via wg log in Parts 1-5 above, structured as: Stale / Missing / Inconsistent with section citations - [x] No source / doc modifications made — audit only
• 2026-04-30T02:20:57.976643832+00:00 Task pending eval (agent reported done; awaiting `.evaluate-*` to score)
• 2026-04-30T02:23:09.564207282+00:00 PendingEval → Done (evaluator passed; downstream unblocks)