audit-claude-md

Metadata

Description

## Description
Per reorg-separate-universal, CLAUDE.md is now layer-2 (workgraph-as-a-project). Audit for: any remaining layer-1 universal-role content that should move to agent-guide; accuracy of dev recipes (cargo install path); current model spec recipes; agency-task pinning section.

## 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-claude-md

Required by

• done doc-sync-audit

Log

• 2026-04-30T02:05:06.422204278+00:00 Task paused
• 2026-04-30T02:08:01.640510286+00:00 Task published
• 2026-04-30T02:08:32.919758284+00:00 Lightweight assignment: agent=Careful Programmer (f5143935), exec_mode=light, context_scope=full, reason=Careful Programmer's attention to detail and proven track record (0.78 score, 364 tasks) suit documentation audit requirements; will read CLAUDE.md, git history, and command specs to identify stale/missing/inconsistent content.
• 2026-04-30T02:14:13.353938422+00:00 Spawned by coordinator --executor claude --model sonnet
• 2026-04-30T02:14:19.870979683+00:00 Starting audit: checking messages and baseline commit
• 2026-04-30T02:18:25.066246676+00:00 Baseline identified: 0e4bbf036 (2026-04-24, human commit 'chore: gitignore .workgraph/, mark CLAUDE.md as configured'). All 9 CLAUDE.md commits since then are agent-authored. Compiling delta list now.
• 2026-04-30T02:19:15.839662840+00:00 AUDIT FINDINGS — CLAUDE.md (workgraph repo layer-2 guide) ## Baseline Commit: 0e4bbf036 (2026-04-24) — human commit 'chore: gitignore .workgraph/, mark CLAUDE.md as configured' Fallback would have been 2026-04-12 but this human commit is unambiguous. All 9 subsequent CLAUDE.md commits are agent-authored (most recent: 9de67a5e3 reorg-separate-universal agent-1160, 2026-04-29). ## Delta List ### Missing - **Missing — Named profiles section:** After implement-named-profiles (agent-1018, 2026-04-28), the Service Configuration section should document `wg profile use <name>` as a high-level alternative to manual `wg config -m`. Three built-in profiles exist: `claude` (opus worker), `codex` (gpt-5.5), `nex` (in-process endpoint). Example missing from doc: `wg profile use claude` or `wg profile use nex`. The `wg profile` command offers `use`, `show`, `list`, `create`, `edit`, `diff`, `init-starters`, `refresh` subcommands — none are mentioned anywhere in CLAUDE.md. - **Missing — wg secret for API key management:** After implement-wg-secret (agent-1070, 2026-04-27) and fix-wg-secret (agent-1073), `wg secret set/get/list/rm/check` manages API keys in a credential store. Agents/developers configuring openrouter or nex providers need to know about this. Not mentioned in CLAUDE.md. Particularly relevant next to the `openrouter:` model example. - **Missing — wg config lint command:** `wg config lint` was added as a read-only companion to `wg migrate config`. CLAUDE.md says 'run `wg migrate config --dry-run`' for inspection, but the dedicated `wg config lint` subcommand (per `wg config --help`) is the correct modern read-only path. - **Missing — wg config init --route option:** `wg config init` now accepts `--route <ROUTE>` with values `claude-cli` (default), `codex-cli`, `openrouter`, `local`, `nex-custom`. CLAUDE.md says `wg config init --global` without mentioning the route parameter that makes init useful for non-claude setups. - **Missing — wg config -m auto-reload behavior:** Per `wg config --help`, `wg config -m/-e` now sends a reconfigure IPC to the running daemon automatically (hot-reload). The `--no-reload` flag skips this. CLAUDE.md describes manual restart workflows that are now unnecessary — the daemon auto-reloads on config write. ### Stale - **Stale — 'one release' deprecation promise on local:/oai-compat: prefixes:** The Service Configuration section says these deprecated aliases 'keep working for one release with a stderr warning'. This 'one release' promise has persisted through at least commits e7210494c (simplify-executor-taxonomy, agent-687), 7555800b4 (fix-codex-cli, agent-998), and a7002f765 (fix-model-prefix, agent-1118). The feedback_skip_backcompat_ceremony.md memory says this project has effectively one user and should do hard renames, not deprecation windows. The doc should either remove the 'one release' promise (just say 'legacy aliases, route to same handler') or note they are still present in current code. - **Stale — 'one release' deprecation promise on --executor/-x flag:** Same issue — the deprecation warning for `--executor` / `-x` has been 'one release away' since simplify-executor-taxonomy. The cli.rs docstring says 'Kept for one release with a deprecation warning so existing scripts keep working'. Technically accurate in code but creates a misleading expectation of imminent removal. - **Stale — Coverage list in intro does not include profiles or secrets:** The intro lists what CLAUDE.md covers: (1) wg usage, (2) dev/rebuild, (3) service config recipes, (4) agency-task pinning. Named profiles and secrets management are now also workgraph-repo-specific topics appropriate for this doc but not listed. ### Inconsistent - **Inconsistent — [dispatcher].executor vs [coordinator].executor terminology:** CLAUDE.md says '[agent].executor / [dispatcher].executor config keys are deprecated'. In config.rs (line 28): 'canonical TOML key: [dispatcher]; legacy alias: [coordinator]'. So [dispatcher] is the CANONICAL name and [coordinator] is the legacy alias — both are deprecated fields within those sections. The CLAUDE.md phrasing is ambiguous about which is canonical. Cross-ref: docs/config-ux-design.md likely has the canonical explanation. - **Inconsistent — openrouter model example uses claude-opus-4-7 but code uses claude-sonnet-4-6:** CLAUDE.md shows `openrouter:anthropic/claude-opus-4-7`. The config.rs test at line 2353 uses `openrouter:anthropic/claude-sonnet-4-6`. The example should match what a typical user would configure (sonnet is more cost-effective for standard work; opus is expensive). Recommend aligning the example with what `wg profile init-starters` would write. ### Accurate (no change needed) - Development section (cargo install --path .) — accurate - wg config init --global — valid subcommand syntax confirmed - wg migrate config --dry-run / --all — confirmed correct from help output - wg setup interactive wizard — still exists - Agency tasks pinned to claude:haiku — confirmed in src/service/llm.rs - src/dispatch/handler_for_model.rs reference — file still exists - WG_EXECUTOR_TYPE and WG_MODEL env vars still sent to agents — confirmed in src/dispatch/plan.rs - codex:gpt-5.5 example — matches profile/named.rs (gpt-5.5 is premium codex tier)
• 2026-04-30T02:19:22.861611054+00:00 Validation: baseline commit identified (0e4bbf036, 2026-04-24). Delta list posted via wg log with structured entries covering 5 Missing, 3 Stale, 2 Inconsistent items. No source/doc files modified. All validation criteria met.
• 2026-04-30T02:19:24.723654333+00:00 Task pending eval (agent reported done; awaiting `.evaluate-*` to score)
• 2026-04-30T02:22:01.073655147+00:00 PendingEval → Done (evaluator passed; downstream unblocks)