Metadata
| Status | done |
|---|---|
| Assigned | agent-1215 |
| Agent identity | f51439356729d112a6c404803d88015d5b44832c6c584c62b96732b63c2b0c7e |
| Model | claude:opus |
| Created | 2026-04-30T02:05:27.868068116+00:00 |
| Started | 2026-04-30T02:14:16.973956148+00:00 |
| Completed | 2026-04-30T02:19:22.982371328+00:00 |
| Tags | fix,docs,audit,sweep, eval-scheduled |
| Eval score | 0.87 |
| └ blocking impact | 0.90 |
| └ completeness | 0.90 |
| └ coordination overhead | 0.90 |
| └ correctness | 0.85 |
| └ downstream usability | 0.88 |
| └ efficiency | 0.80 |
| └ intent fidelity | 0.73 |
| └ style adherence | 0.85 |
Description
Description
Per reorg-separate-universal these are contributor-only docs explaining design rationale. Audit each file for: presence of contributor-only header note, accurate description of CURRENT behavior (some designs may be superseded — flag those), references to legacy names. List which files need a header added, which describe superseded behavior, which need updates to reflect what actually shipped.
Output
Post findings via `wg log `. Structured list of items found. NO file modifications — audit only. Synthesis task applies fixes.
Validation
- Findings posted via wg log
- Specific file:line citations where possible
- No source / doc modifications
Depends on
Required by
Log
- 2026-04-30T02:05:27.852782925+00:00 Task paused
- 2026-04-30T02:10:06.392493494+00:00 Task published
- 2026-04-30T02:10:41.100457698+00:00 Lightweight assignment: agent=Careful Programmer (f5143935), exec_mode=light, context_scope=task, reason=Careful Programmer's systematic approach and high performance (0.78, 364 tasks) suit thorough documentation audit; light mode for read-only file analysis; can identify superseded designs by understanding current implementation.
- 2026-04-30T02:14:16.973968551+00:00 Spawned by coordinator --executor claude --model opus
- 2026-04-30T02:14:31.191412546+00:00 Starting audit. docs/design/ has 89 files, docs/designs/ has 5 files. Reading READMEs and reorg-separate-universal context first.
- 2026-04-30T02:17:03.153128033+00:00 === AUDIT FINDINGS (1/5): SCOPE & DUAL-DIRECTORY ISSUE === There are TWO directories with related but disjoint content: - docs/designs/ (plural) — 5 files, created/touched by reorg-separate-universal (commit 9de67a5e3): README.md, quality-pass.md, chat-message-ordering-and-delivery.md, failed-dep-triage.md, tui-iteration-history-and-viz-selfloop.md - docs/design/ (singular) — 89 .md files + 6 PDFs, the historical store; UNTOUCHED by reorg-separate-universal The README at docs/designs/README.md:1-37 declares 'this directory' as the contributor docs layer-3, but 89 of the 94 design files actually live next door at docs/design/. The reorg added the header note but did not migrate or even reference docs/design/. Recommendation for synthesis task: pick ONE canonical location. Either (a) consolidate into docs/designs/ and delete docs/design/, or (b) keep docs/design/ and rewrite the README/CLAUDE.md references that point to docs/designs/. CLAUDE.md (project root) and src/text/agent_guide.md should both be checked for references to either path.
- 2026-04-30T02:17:12.759747071+00:00 === AUDIT FINDINGS (2/5): CONTRIBUTOR-ONLY HEADER STATUS === Files that ALREADY have the contributor-only header (2 of 94): - docs/designs/README.md:3-14 (full directory README) - docs/designs/quality-pass.md:3-7 (added by reorg-separate-universal) Files MISSING the header note (92 of 94): In docs/designs/ (plural, 3 files missing): - docs/designs/chat-message-ordering-and-delivery.md (line 1: starts with '# Design: ...') - docs/designs/failed-dep-triage.md (line 1: starts with '# Design: ...') - docs/designs/tui-iteration-history-and-viz-selfloop.md (line 1: starts with '# Design: ...') In docs/design/ (singular, ALL 89 .md files missing): - Confirmed via grep -r 'Contributor doc|Contributor Only|hacking on workgraph' docs/design/ → No files found. - Examples include high-traffic docs: agent-lifecycle.md, agent-isolation-decision.md, agent-isolation-implementation.md, bare-coordinator.md, cycle-aware-graph.md, design-deliberation-synthesis.md, federation-architecture.md, native-executor.md, sessions-as-identity.md, etc. Synthesis approach: a 5-line block prepended after the H1 (matching the quality-pass.md template) is the minimum fix. Can be added as a single batch sed/script across all 92 files since the wording is invariant.
- 2026-04-30T02:17:35.882860906+00:00 === AUDIT FINDINGS (3/5): LEGACY NAME REFERENCES === (A) 'local:' / 'oai-compat:' deprecated model prefixes (per CLAUDE.md these are aliases for nex: with stderr warnings; wg migrate config rewrites them): - docs/design/cross-repo-communication.md:299 — 'reference to local:task-id' (this is a federation task-id, not the deprecated prefix; OK as-is — flag only on inspection) - docs/design/provider-model-naming.md:59 — table entry '| local:whatever | local | native | whatever |' — this row encodes the legacy mapping; should be relabeled or annotated as historical now that nex: is canonical - 6 other files showed regex hits but mostly for the unrelated word 'local' or '--executor' references — see (C) (B) 'amplifier' executor references (13 files): amplifier still exists as ExecutorConfig in src/service/executor.rs:1545 (built-in), but per CLAUDE.md the model spec (claude:/codex:/nex:/openrouter:) is the single source of truth and there is NO amplifier: prefix. Many design docs still treat amplifier as a first-class executor sibling of claude/codex. Files: docs/design/external-executor-class.md (line 1 title, lines 14, 32, 89, 167), docs/design/sessions-as-identity-rollout.md:70, docs/design/sessions-as-identity.md:79,282, docs/design/generic-executor-design.md:16,98, docs/design/smooth-integration.md:364, docs/design/message-discipline-design.md:262, docs/design/coordinator-as-regular-agent.md:30, docs/design/native-executor.md:13,61, docs/design/self-hosting-architecture.md:222, docs/design/agent-message-queue.md:285,287, docs/design/provider-model-naming.md:330, docs/design/nex-executor-improvements.md:36,211,222,226, docs/design/executor-weight-tiers.md:19,260, docs/design/nex-as-coordinator.md (multiple). Recommendation: leave content unchanged but flag as historical via the contributor header. Active status for amplifier should be reaffirmed by user before any rewriting. (C) Deprecated '--executor' / '-x' flag and [agent].executor / [dispatcher].executor config keys (per CLAUDE.md these are deprecated for one release with warnings; model spec is the new source of truth): Files with --executor / executor= references: docs/design/pdf-binary-failure-handling.md, sessions-as-identity-rollout.md, external-executor-class.md, nex-executor-improvements.md, nex-as-coordinator.md, provider-model-naming.md, generic-executor-design.md. Recommendation: not strictly 'wrong' but stale; synthesis task should add a footnote to provider-model-naming.md acknowledging the prefix-based router superseded executor=. (D) '--verify' flag (per memory feedback_wg_add_no_verify_flag: --verify was rejected; criteria go under '## Validation' in -d body): 6 files: docs/design/llm-verification-gate.md, verify-deprecation-plan.md (this doc IS the deprecation plan, so OK), screencast-repertoire.md, screencast-freshness-pipeline.md, demo-medley-catalog.md, agent-isolation-implementation.md. Recommendation: verify-deprecation-plan.md should self-mark as 'plan executed; verify is gone'; screencast docs likely teach legacy flag usage and need updates.
- 2026-04-30T02:18:37.439625837+00:00 === AUDIT FINDINGS (4/5): LIKELY-SUPERSEDED / SHIPPED DESIGNS === These designs self-declare 'shipped' or describe behavior visible in current code/CLAUDE.md. Synthesis task should add a 'STATUS: SHIPPED' / 'STATUS: HISTORICAL' marker rather than rewriting bodies: Self-declared shipped or with explicit phase-complete markers: - docs/design/cycle-aware-graph.md:5 — '**Status:** Implemented (all four phases complete)' - docs/design/native-graph-iteration.md:325 — 'Status: Done (iteration 3 of 3)' - docs/design/spec-vx-integration-impl.md:298 — 'Status: done' Recent shipped per git log / CLAUDE.md / src code: - docs/design/coordinator-as-regular-agent.md (Status: Design Mar 2026) — coordinator-as-graph-citizen pattern shipped via .compact-0 task; CLAUDE.md memory references this. Mark historical. - docs/design/coordinator-as-graph-citizen.pdf (no .md) — PDF only, also shipped. - docs/design/bare-coordinator.md (Status: Design) — superseded by the shipped coordinator behavior; mark historical. - docs/design/spec-edge-rename.md:6 — 'Phase 2 of cycle-aware-graph.md'; cycle-aware says all four phases done → spec-edge-rename SHIPPED. - docs/design/spec-cycle-integration.md:4 — 'Ready for implementation'; cycle features now shipped → mark SHIPPED. - docs/design/cycle-delay-semantics.md, cycle-edge-viz.md, outbound-edge-viz.md — cycle visualization features visible in 'wg cycles' / 'wg viz'; mark SHIPPED. - docs/design/loop-convergence.md (Feb 19), reopen-on-new-dep.md (Feb 26) — early DAG/cycle docs; behavior shipped (wg done --converged exists per agent guide). SHIPPED. - docs/design/phantom-edge-prevention.md (Apr 7) — feedback_phantom_edge_analysis exists in docs/research/; behavior shipped. SHIPPED. - docs/design/wg-wait-design.md — 'wg wait' command exists at src/commands/wait.rs. SHIPPED. - docs/design/agent-isolation-decision.md / agent-isolation-implementation.md — git-worktree isolation shipped (CLAUDE.md memory + agent guide). SHIPPED. - docs/design/dangling-dependency-resolution.md (Mar 4) — likely shipped via sweep/reconciliation work (CLAUDE.md mentions 'Sweep command + reconciliation' shipped). - docs/design/mandatory-validation.md — '## Validation' section enforcement shipped (visible in agent_guide.md). SHIPPED. - docs/design/unified-lifecycle-state-machine.md — task lifecycle states shipped per CLAUDE.md ('open → in-progress → done/failed/abandoned/blocked/waiting'). SHIPPED. - docs/design/model-cost-tracking.md — wg cost / cost.rs exists in src/commands/. SHIPPED. - docs/design/model-config-propagation.md — coordinator.model cascade is documented in CLAUDE.md. SHIPPED. - docs/design/model-endpoint-key-ux.md — wg setup wizard shipped. SHIPPED. - docs/design/provenance-system.md (Feb 21, has 'Status Quo' header rather than implementation status) — provenance is partially shipped; status section needs updating to reflect what actually shipped. Currently in-flight or proposed (NOT superseded): - docs/design/external-executor-class.md (proposed 2026-04-18) - docs/design/nex-executor-improvements.md (proposed 2026-04-18, revised) - docs/design/nex-as-coordinator.md (Apr 18) - docs/design/unified-path-forward.md (Apr 16) — plan of action; partially executed - docs/design/sessions-as-identity.md / sessions-as-identity-rollout.md (Apr 19) — recent rollout plan - docs/design/llm-verification-gate.md (Apr 22) — recent - docs/design/pdf-binary-failure-handling.md (Apr 28) — current - docs/design/chat-agent-persistence.md (Apr 29) — most recent - docs/design/tui-multiplexing-concurrent-access.md (Apr 28) — current - docs/designs/quality-pass.md — already has header; in-flight pattern - docs/designs/failed-dep-triage.md — current pattern guide Demo / screencast / non-feature docs (probably out of scope for header treatment but flagging for consistency): - docs/design/hero-screencast-scenarios.md, hero-screencast-storyboard-v2.md, heroview-screencast-v2-script.md - docs/design/screencast-freshness-pipeline.md, screencast-interaction-flow.md, screencast-repertoire.md - docs/design/demo-medley-catalog.md, blog-setup-recommendation.md - docs/design/nex-web-access-status-2026-04-16.md — dated status snapshot PDF-only or PDF+MD pairs (likely contributor reference; flag for header on the .md): agent-lifecycle.pdf+md, coordinator-as-graph-citizen.pdf (no md), design-deliberation-synthesis.pdf+md, liveness-detection.pdf+md, provenance-system.pdf+md, smooth-integration.pdf+md.
- 2026-04-30T02:18:58.647054419+00:00 === AUDIT FINDINGS (5/5): SUMMARY & RECOMMENDATIONS FOR doc-sync-audit === Counts: - Total design markdown files: 94 (89 in docs/design/ + 5 in docs/designs/) - Files WITH contributor-only header: 2 (docs/designs/README.md, docs/designs/quality-pass.md) - Files MISSING contributor-only header: 92 - Files with self-declared 'Implemented'/'Done'/'Complete' markers: 3 (cycle-aware-graph.md, native-graph-iteration.md, spec-vx-integration-impl.md) - Files describing demonstrably shipped behavior (status field still says 'Design'/'Proposed'/'Ready'): ~17 (see finding 4 list) - Files referencing legacy 'amplifier' executor: 13 (amplifier still exists internally; flag, don't rewrite) - Files referencing deprecated --executor / executor= keys: 7 (treat as historical) - Files referencing deprecated --verify flag: 6 (verify-deprecation-plan.md self-deprecates) - Files referencing deprecated 'local:' / 'oai-compat:' model prefixes (substantive, not coincidental word matches): 1 confirmed substantive (provider-model-naming.md:59 table row) - PDFs without .md companions: 1 (coordinator-as-graph-citizen.pdf) Recommended synthesis-task ordering (for doc-sync-audit): 1. Decide singular-vs-plural directory: pick docs/designs/ (matches the new README) and either git-mv docs/design/* into it OR the inverse. This is the highest-leverage fix; once one canonical location exists, every downstream link / reference becomes consistent. 2. Add the 5-line contributor-only header (matching quality-pass.md template) to all 92 markdown files lacking it. Programmatic — same prepended block, after the H1. 3. Update status fields on the ~17 shipped designs from 'Design'/'Proposed'/'Ready' to 'SHIPPED' or 'Historical' — minimal surgery, just replace the status line. 4. Add a single-line 'Note: this prefix is deprecated; see CLAUDE.md model-spec convention' to provider-model-naming.md:59 row, and a 1-line top-level footnote to the 6 --verify-referencing files (or just rely on the contributor header to absorb all such concerns). 5. Leave amplifier references alone — amplifier still exists per src/service/executor.rs:1545 and CLAUDE.md project memory; only flag if user later confirms amplifier is being removed. NO FILES MODIFIED. Audit complete per task validation: findings posted via wg log; specific file:line citations included; no source / doc modifications.
- 2026-04-30T02:19:22.551788397+00:00 Validated: task-specific criteria met — (1) findings posted via 5 wg log entries, (2) specific file:line citations included throughout (e.g., quality-pass.md:3-7, provider-model-naming.md:59, cycle-aware-graph.md:5, native-graph-iteration.md:325), (3) no source/doc modifications — git status unchanged from session start (same untracked .wg, .workgraph.*, and bug-*.md files as at start).
- 2026-04-30T02:19:22.982393008+00:00 Task pending eval (agent reported done; awaiting `.evaluate-*` to score)
- 2026-04-30T02:21:35.434903905+00:00 PendingEval → Done (evaluator passed; downstream unblocks)