audit-wg-agent

Metadata

Description

## Description
The new universal role contract bundled per reorg-separate-universal. Audit for: completeness (covers chat/dispatcher/worker distinction, quality-pass workflow, validation requirement, smoke gate, cycle handling); accuracy vs current shipped behavior; reference to current command names not legacy.

## 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-wg-agent

Required by

• done doc-sync-audit

Log

• 2026-04-30T02:05:06.553823756+00:00 Task paused
• 2026-04-30T02:09:36.264336112+00:00 Task published
• 2026-04-30T02:09:58.120159650+00:00 Lightweight assignment: agent=Default Evaluator (31847164), exec_mode=light, context_scope=task, reason=Evaluator role with proven audit/review track record (0.86 score, 377 tasks) is ideal for documentation completeness and accuracy audit.
• 2026-04-30T02:19:11.752864090+00:00 Spawned by coordinator --executor amplifier --model sonnet
• 2026-04-30T02:19:15.512483195+00:00 Task marked as failed: Agent exited with code 1
• 2026-04-30T02:26:03.190900145+00:00 Task reset for retry from failed (attempt #2)
• 2026-04-30T02:26:09.212784023+00:00 Spawned by coordinator --executor claude --model sonnet
• 2026-04-30T02:26:25.318680685+00:00 Starting audit: checking messages, finding agent-guide file, identifying baseline commit
• 2026-04-30T02:33:07.501069072+00:00 Baseline: file src/text/agent_guide.md was created by agent-1160 in commit 9de67a5e3 (2026-04-29). Only one commit ever touched the file, and it was an agent commit. Falling back to 2026-04-12 per task instructions. Audit scope: all changes to wg behavior/commands/config/state-machine between 2026-04-12 and HEAD (~530 commits).
• 2026-04-30T02:33:37.012053144+00:00 DELTA LIST — src/text/agent_guide.md --- MISSING --- 1. Missing (Worker Agent Workflow, Step 7): wg incomplete command not listed as a valid outcome. Step 7 lists only wg done / wg done --converged / wg fail. Should add: 'wg incomplete <task-id> --reason ...' as a fourth outcome meaning 'work landed but needs another pass, retryable.' Distinct from wg fail (hard failure, abandon or escalate) and from pending-validation (awaiting evaluation). Incomplete tasks auto-retry up to max_incomplete_retries (default 3). Reference: quickstart INCOMPLETE STATUS section; add-incomplete-retryable commit (agent-288). 2. Missing (Worker Agent Workflow): wg retry command not mentioned. Workers and humans use 'wg retry <task-id>' to reset failed/incomplete/hung-in-progress tasks to open; supports --reason, --fresh (discard prior worktree), --preserve-session. Dispatcher respawns automatically. Reference: add-wg-retry commit (2026-04-27 agent-851); docs/AGENT-GUIDE.md section 1b. 3. Missing (new state machine, 2026-04-29): failed-pending-eval state not documented. When an agent exits without calling wg done AND auto_evaluate=true, the task enters failed-pending-eval instead of immediately failed. The evaluator can rescue the task (transition to done). Calling wg fail on a failed-pending-eval task forces terminal failure. Implication for workers: exiting without wg done is not equivalent to wg fail when auto-eval is enabled. Reference: implement-failed-pending merge (cae4cca540, 2026-04-29). 4. Missing (Worker Agent Workflow): wg wait command not mentioned. Workers can park themselves via 'wg wait <task-id> --until <condition>'. Supported conditions: task:X=done, timer:5m, message, human-input, file:path. Dispatcher auto-resumes when condition is met. More efficient than polling or retrying. Supports --checkpoint to record progress summary. Reference: quickstart TASK STATE COMMANDS; docs/AGENT-GUIDE.md section 4.1.4 and 7b/Wait. 5. Missing (Worker Agent Workflow): exec-mode not explained. Workers run with an exec-mode that limits available tools: full=all tools (default), light=read-only tools, bare=wg CLI only, shell=no LLM. Workers in light mode cannot write files. exec-mode is set at task creation (--exec-mode) and available via WG_EXEC_MODE env var. Reference: quickstart DISCOVERING & ADDING WORK; docs/AGENT-GUIDE.md section 7 Execution modes. --- STALE / INACCURATE --- 6. Inaccurate (Chat Agent Contract / Quality pass): '--before' is not a valid wg add dependency flag. Currently says 'wires every task in the batch to depend on it via --before or --after .quality-pass-<batch-id>'. There is no --before dependency flag in wg add (--place-before is a placement hint, not a dependency edge). The correct mechanism is: use wg edit <task-id> --add-after .quality-pass-<batch-id> on each batch task, or --after .quality-pass-<batch-id> at creation time. Reference: docs/designs/quality-pass.md; wg add --help. 7. Stale (Section 'Three Roles, One Vocabulary'): no migration path for legacy .coordinator-N task IDs. Currently says only 'Replaces the older coordinator terminology.' Should note that existing graphs may have .coordinator-N task IDs that can be rewritten with: wg migrate chat-rename. Reference: AGENTS.md glossary; wg migrate --help; fold-unclaim-semantics + wg-chat-as-first-class-entity merges. --- INCOMPLETE --- 8. Incomplete (Section 'Chat Agent Contract'): wg chat is now a first-class entity. Currently: 'Lives inside the wg TUI or in a terminal Claude Code / codex / nex session.' Now: chats are graph tasks (.chat-N) with a dedicated command set: wg chat create/list/show/attach/send/stop/resume/archive/delete. Multiple concurrent chat sessions supported. The service supervisor spawns a handler subprocess per active chat. Legacy wg service create-chat / stop-chat / archive-chat / delete-chat aliases exist in quickstart but the primary API is wg chat subcommands. Reference: wg-chat-as-first-class-entity merge (47bd268, 2026-04-27). 9. Incomplete (Section 'Cycles'): missing advanced cycle flags. Currently only mentions --max-iterations and wg done --converged. Missing: --no-converge (force all iterations; agents cannot signal early stop), --no-restart-on-failure (disable automatic cycle restart when a member fails; restart is on by default), --max-failure-restarts <N> (cap failure-triggered restarts, default 3). Reference: quickstart CYCLES; docs/AGENT-GUIDE.md section 2.5. 10. Incomplete (Section 'Environment Variables'): missing worktree env vars. Currently lists WG_TASK_ID, WG_AGENT_ID, WG_EXECUTOR_TYPE, WG_MODEL, WG_TIER. Missing (set for agents with worktree isolation per src/commands/spawn/execution.rs): WG_USER (current user identity), WG_WORKTREE_PATH / WG_BRANCH / WG_PROJECT_ROOT / WG_WORKTREE_ACTIVE (only set when worktree isolation is active; checked by wrapper to detect worktree escape). Reference: src/commands/spawn/execution.rs lines 594-639; docs/AGENT-GUIDE.md section 7 env vars table.
• 2026-04-30T02:33:51.362234930+00:00 Validated: (1) Baseline identified — 2026-04-12 fallback, cited SHA 9de67a5e3 with reasoning. (2) Delta list posted via wg log — 10 structured entries across Missing/Stale/Incomplete categories. (3) No source/doc modifications made — audit only.
• 2026-04-30T02:33:56.695036085+00:00 Task pending eval (agent reported done; awaiting `.evaluate-*` to score)
• 2026-04-30T02:35:31.410960210+00:00 PendingEval → Done (evaluator passed; downstream unblocks)