audit-terminology-consistency

Metadata

Description

## Description
Per CLAUDE.md glossary the canonical terms are: dispatcher (daemon), chat agent (user-facing LLM session), worker agent (single-task spawned). Old terms: coordinator, orchestrator. Plus model prefixes: nex: (canonical) vs local: / oai-compat: (legacy). Plus profile name: nex (canonical) vs wgnext (legacy). Grep all docs for the legacy terms. List every occurrence with file:line. Also flag any inconsistency where one doc uses one term and another uses a different one for the same concept.

## Output
Post findings via \`wg log <task-id>\`. 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

• done quality-pass-doc
• done .assign-audit-terminology-consistency

Required by

• done doc-sync-audit

Log

• 2026-04-30T02:05:27.782248864+00:00 Task paused
• 2026-04-30T02:09:36.309603620+00:00 Task published
• 2026-04-30T02:20:01.761560416+00:00 Spawned by coordinator --executor amplifier --model opus
• 2026-04-30T02:20:04.745213828+00:00 Task marked as failed: Agent exited with code 1
• 2026-04-30T02:21:40.224537035+00:00 Task reset for retry from failed (attempt #2)
• 2026-04-30T02:21:50.495328067+00:00 Spawned by coordinator --executor amplifier --model sonnet
• 2026-04-30T02:21:53.314033227+00:00 Task marked as failed: Agent exited with code 1
• 2026-04-30T02:26:14.078300077+00:00 Task reset for retry from failed (attempt #3)
• 2026-04-30T02:26:20.040991136+00:00 Spawned by coordinator --executor claude --model sonnet
• 2026-04-30T02:26:31.237666269+00:00 Starting terminology audit - searching for legacy terms in docs
• 2026-04-30T02:29:48.178027740+00:00 Completed grepping all docs. Now compiling findings.
• 2026-04-30T02:31:17.582181874+00:00 TERMINOLOGY AUDIT FINDINGS — audit-terminology-consistency ## Canonical vs Legacy Term Map (from AGENTS.md + CLAUDE.md) | Canonical | Legacy (deprecated) | Scope | |---|---|---| | dispatcher | coordinator, orchestrator | the daemon / wg service start | | chat agent | coordinator, orchestrator | the persistent LLM UI session | | worker agent | (new; no legacy equivalent) | single-task spawned LLM process | | nex: | local:, oai-compat: | model prefix for in-process nex handler | | nex | wgnext | profile name | --- ## FINDING 1: SKILL.md uses 'coordinator' throughout as a role-noun (HIGH PRIORITY) File: .claude/skills/wg/SKILL.md Status: Does NOT use 'dispatcher', 'chat agent', or 'worker agent' at all. All references use the deprecated term 'coordinator'. Specific lines: - Line 14: `wg service start # Start the coordinator` → should say "Start the dispatcher" - Line 21: `You are a **coordinator**.` → should say "You are a **chat agent**." - Line 55: `### What you do NOT do as coordinator` → "as a chat agent" - Line 65: `As coordinator, review and finalize:` → "As chat agent," - Line 87: `the coordinator may send you messages` → "the dispatcher may send..." - Line 103: `let the coordinator dispatch them` → "let the dispatcher dispatch them" - Line 220: `pause/resume the entire coordinator` → "pause/resume the dispatcher" - Line 289: `coordinator skips it` → "dispatcher skips it" - Line 373: `wg service start | Start coordinator daemon` → "Start dispatcher daemon" - Line 377: `Pause coordinator (running agents continue...)` → "Pause dispatcher" - Line 378: `Resume coordinator dispatching` → "Resume dispatcher" - Line 386: `SIGSTOP all running agents and pause coordinator` → "pause dispatcher" - Line 387: `SIGCONT all frozen agents and resume coordinator` → "resume dispatcher" - Line 388: `Interrupt a coordinator's current generation` → "Interrupt a chat agent's..." - Line 444: `### Chat (coordinator interaction)` → "Chat (chat agent interaction)" - Line 448: `Send a message to the coordinator` → "Send a message to the chat agent" - Line 813: `coordinator config` in resolution chain — OK (config key name) - Line 828: `## Multi-coordinator support` → "## Multi-chat-agent support" - Line 834: `wg service stop-coordinator` — CLI command name (ok to keep) - Line 835: `wg service archive-coordinator` — CLI command name (ok to keep) Note: CLI subcommands like `stop-coordinator`, `archive-coordinator` are CLI surface names (not prose role-nouns) — they mirror the code and may intentionally retain legacy names pending a separate rename. --- ## FINDING 2: docs/AGENT-SERVICE.md uses 'coordinator' heavily, 'dispatcher' only once (HIGH) File: docs/AGENT-SERVICE.md Count: 53 uses of "coordinator", 1 use of "dispatcher" AGENTS.md/CLAUDE.md use "dispatcher" for the daemon and "chat agent" for the LLM session. Key role-noun uses that conflict with canonical terminology: - Line 42: "The daemon runs a coordinator tick" → "a dispatcher tick" - Line 85: "(user, coordinator, dependent-task agents)" → "(user, chat agent, ...)" - Line 171: "Show daemon status, uptime, coordinator state" → "dispatcher state" - Line 179: "pause the coordinator. Useful for halting work" → "pause the dispatcher" - Line 187: "Thaw all frozen agents...and resume the coordinator" → "dispatcher" - Line 208: "Pause the coordinator. Running agents continue" → "Pause the dispatcher" - Line 218: "Resume the coordinator and trigger an immediate tick" → "dispatcher" - Line 226: "Run a single coordinator tick and exit" → "dispatcher tick" - Line 245: "coordinator that's producing unwanted output" — chat agent context - Line 247: "Target a specific coordinator from wg chat" → "chat agent" - Line 261-265: "Coordinator tasks are preserved" → "Chat agent tasks" - Line 326: "When the coordinator spawns an agent" → "When the dispatcher spawns" - Line 393: "The coordinator detects dead agents" → "The dispatcher detects" - Line 431: "Agents can park a task...The coordinator evaluates" → "The dispatcher evaluates" - Line 442: "The coordinator detects and fails circular waits" → "The dispatcher detects" - Line 554: "the coordinator injects context" → "the dispatcher injects" - Line 562: "The coordinator drives a .compact-0 cycle task" → "The dispatcher drives" - Line 562: "this is the coordinator's self-introspection loop" — ambiguous: AGENT-GUIDE.md:793 correctly says "this is the chat agent's self-introspection loop" - Line 594-597: IPC pause/resume/freeze/thaw for "coordinator" → "dispatcher" - Line 602: "Send a chat message to the coordinator agent" → "chat agent" - Line 643: "Inline spawns (via coordinator.rs)" — source file reference, ok - Line 674: "cleanup performed by the coordinator on each tick" → "dispatcher" --- ## FINDING 3: src/commands/quickstart.rs uses 'coordinator' in user-facing output (HIGH) File: src/commands/quickstart.rs This file contains the text output of `wg quickstart`. Selected role-noun uses: - Line 13: `wg service start # Start the coordinator` → "Start the dispatcher" - Line 70: "Check if the coordinator is running" → "Check if the dispatcher is running" - Line 73: "the coordinator handles the rest" → "the dispatcher handles" - Line 75: "collide with the coordinator" → "collide with the dispatcher" - Line 81: `wg service start --max-agents 5 # Start coordinator` → "Start dispatcher" - Line 83: "The coordinator automatically spawns agents" → "The dispatcher automatically" - Line 88: "the coordinator handles this" → "dispatcher" - Line 92: `wg service pause # Pause coordinator` → "Pause dispatcher" - Line 93: `wg service resume # Resume coordinator` → "Resume dispatcher" - Line 167: "how much context the coordinator injects" → "dispatcher injects" (or "injected into agent prompt") - Line 193: `wg pause <task-id> # Pause task (coordinator skips it)` → "dispatcher skips" - Line 426: "The coordinator dispatches anything you add" → "The dispatcher dispatches" - Line 432-433: coordinator references → dispatcher - Line 441: "The coordinator spawns agents" → "The dispatcher spawns" - Line 444: `wg config --coordinator-executor amplifier` — config key, ok - Line 449: `[coordinator]: model = "..."` — config section, ok - Line 459: "coordinator model" in hierarchy — config key, ok --- ## FINDING 4: docs/AGENT-LIFECYCLE.md mixes 'coordinator' and 'dispatcher' for the daemon File: docs/AGENT-LIFECYCLE.md - Line 30: "Spawned by coordinator when tasks are ready" → "Spawned by dispatcher" - Line 321: "Coordinator periodic safety net — every dispatcher tick" — mixed in same sentence; canonical term used correctly for "tick" but "Coordinator" still leads - Line 460: `cargo test coordinator` — test command name, not a role-noun, OK - Line 644-646: "TUI coordinator tabs", "coordinator state" — could be "chat agent" or "chat session" --- ## FINDING 5: docs/AGENT-GUIDE.md uses legacy model prefixes without deprecation notice (MEDIUM) File: docs/AGENT-GUIDE.md - Line 668: `| local:qwen3-coder | nex (in-process) | OAI-compat | yes... |` — shows deprecated prefix as valid - Line 670: `| oai-compat:gpt-5 | nex (in-process) | OAI-compat | yes |` — shows deprecated prefix - Line 674: `wg config -m local:qwen3-coder -e http://127.0.0.1:8088` — example uses deprecated prefix Canonical form: `wg config -m nex:qwen3-coder -e http://127.0.0.1:8088` README.md and AGENTS.md correctly note local: and oai-compat: are deprecated. --- ## FINDING 6: docs/AGENT-SERVICE.md uses legacy model prefixes without deprecation notice (MEDIUM) File: docs/AGENT-SERVICE.md - Line 201: `wg service reload --model local:qwen3-coder` — deprecated prefix, no note - Line 285: `| local:qwen3-coder | native (in-process nex) | ... |` — deprecated - Line 287: `| oai-compat:gpt-5 / openai:gpt-5 | native ... |` — deprecated - Line 295: `wg config -m local:qwen3-coder -e http://127.0.0.1:8088` — deprecated All should use `nex:` prefix or note that `local:` and `oai-compat:` are deprecated aliases. --- ## FINDING 7: docs/AGENCY.md uses 'coordinator' as role-noun for dispatcher functions (MEDIUM) File: docs/AGENCY.md - Line 114: "The coordinator creates assign-{task} and evaluate-{task} meta-tasks" → "The dispatcher creates" - Line 126: "the coordinator creates .place-* meta-tasks" → "The dispatcher creates" - Line 133: "When auto_place is enabled, the coordinator creates .place-* tasks" → "dispatcher" - Line 133: "When auto_create is enabled, the coordinator invokes the creator agent" → "dispatcher" - Line 642: "the coordinator automatically trigger evolution cycles" → "dispatcher" - Line 648: "the coordinator's Phase 4.6 checks two triggers" → "dispatcher's Phase 4.6" - Line 653: "The coordinator creates a .evolve-* meta-task" → "The dispatcher creates" - Line 562: `coordinator` scope in wg evolve — this may be a CLI argument value, check - Line 629: "The evolver can modify the coordinator agent's behavior" — chat agent context - Line 638: "evolved-amendments.md is the primary output of coordinator prompt evolution" — chat agent context --- ## FINDING 8: README.md has mixed usage (LOWER — partly correct already) File: README.md - Line 212: "teaches AI assistants to use the service as a coordinator" — role-noun use - Line 360: `[dispatcher] # legacy alias [coordinator] still accepted` — correct (documents alias) - Line 481: "the coordinator marks it dead and unclaims its task" → "dispatcher marks" - Line 492: "the coordinator can automatically triage" → "dispatcher can" - Line 521: "Set coordinator default (applies to all auto-spawned agents)" — comment in config block, refers to config key `[coordinator]`, acceptable - Line 740: "For interactive conversation with the coordinator agent" → "chat agent" - Line 761: "coordinator are writing to the graph" → "dispatcher" --- ## FINDING 9: Cross-doc inconsistency — .compact-0 attribution AGENT-SERVICE.md:562: "this is the coordinator's self-introspection loop" AGENT-GUIDE.md:793: "this is the chat agent's self-introspection loop" → Conflict: same concept described with different terms. AGENT-GUIDE is correct per canonical terminology. --- ## FINDING 10: docs/design/* and docs/research/* use 'orchestrator' as role-noun These appear in design/research documents (not the primary user-facing docs): - docs/design/design-deliberation-synthesis.md:31,163,165,221,319 — "orchestrator" as role-noun - docs/research/git-worktrees-agent-isolation.md:443 — "orchestrator" as role-noun - docs/design/generic-executor-design.md:588 — "orchestrator-driven" - docs/design/dangling-dependency-resolution.md:106 — "user/orchestrator" - docs/design/message-discipline-design.md:273 — "it's the orchestrator" These are design/research docs; lower priority but still contribute to confusion. --- ## FINDING 11: docs/design-named-profiles.md correctly handles 'wgnext' legacy (OK) File: docs/design-named-profiles.md:440-442 Uses 'wgnext' only to document the migration path from wgnext → nex. This is correct documentation of the legacy-to-canonical transition. No fix needed. --- ## FINDING 12: docs/research/qwen3-nex-config.md uses deprecated model prefix in config examples File: docs/research/qwen3-nex-config.md - Line 190: `local:qwen3-coder-30b` as model spec - Line 132,140,151,160: `provider = "oai-compat"` in config examples (Research doc, lower priority) --- ## SUMMARY: High-Priority Fixes for Synthesis Task 1. **SKILL.md** — Replace all 'coordinator' role-noun uses with 'chat agent' (for the LLM session) and 'dispatcher' (for the daemon/service). This is the skill injected into every new chat-agent session, so it's the highest impact. 2. **docs/AGENT-SERVICE.md** — Replace 'coordinator' role-noun uses (≈40 instances) with 'dispatcher' or 'chat agent' as appropriate. The table in §Multi-coordinator uses 'coordinator session' which maps to the CLI names (wg service create-coordinator etc.) — those CLI command names may stay but prose description should update. 3. **src/commands/quickstart.rs** — Replace all 'coordinator' role-noun uses (≈15 instances) with 'dispatcher'. This is the `wg quickstart` output shown to every new agent. 4. **docs/AGENT-GUIDE.md:668-674** — Update example model specs from `local:qwen3-coder` and `oai-compat:gpt-5` to `nex:qwen3-coder` and `nex:gpt-5`, and add a note that the old prefixes are deprecated aliases. 5. **docs/AGENT-SERVICE.md:201,285,287,295** — Same as above for AGENT-SERVICE.md. 6. **docs/AGENCY.md** — Replace 'coordinator' with 'dispatcher' for daemon functions (auto_place, auto_create, evolution trigger). 7. **README.md:481,492,740,761** — Minor fixes: 'coordinator' → 'dispatcher'/'chat agent'. 8. **docs/AGENT-LIFECYCLE.md:30** — "Spawned by coordinator" → "Spawned by dispatcher" Medium priority (design/research docs): 9. docs/design/design-deliberation-synthesis.md — 'orchestrator' → 'dispatcher'/'chat agent' 10. docs/design/dangling-dependency-resolution.md:106 — 'orchestrator' → 'chat agent'/'dispatcher'
• 2026-04-30T02:31:28.578619286+00:00 Validated: findings posted via wg log with file:line citations. No source/doc modifications made. Covers all three term categories: role nouns (coordinator/orchestrator), model prefixes (local:/oai-compat:), and profile name (wgnext).
• 2026-04-30T02:31:37.157298569+00:00 Task pending eval (agent reported done; awaiting `.evaluate-*` to score)
• 2026-04-30T02:33:34.416254117+00:00 PendingEval → Done (evaluator passed; downstream unblocks)