fix(docs): name /trekplan where the text sent readers to a reference document, and give the reference documents read-only tools

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

agents/brief-reviewer.md

@@ -201,7 +201,7 @@ review as a quality gate and need per-dimension granularity.
 
 Produce **two artifacts in this order**:
 
-1. A prose report (for humans and for `planning-orchestrator` Phase 1b).
+1. A prose report (for humans and for /trekplan Phase 4b).
 2. A final fenced `json` block with per-dimension numeric scores (for callers
    that gate on machine-readable output, such as `/trekbrief` Phase 4).
 

agents/planning-orchestrator.md

@@ -3,7 +3,7 @@ name: planning-orchestrator
 description: Reference document, not a spawnable capability — documents the /trekplan planning workflow that runs inline in main context (full rationale, CC-2.1.172 history, and phase map in body).
 model: opus
 color: cyan
-tools: ["Read", "Glob", "Grep", "Write", "Edit", "Bash"]
+tools: ["Read", "Glob", "Grep"]
 ---
 
 <!-- Phase mapping: orchestrator → command

agents/research-orchestrator.md

@@ -3,7 +3,7 @@ name: research-orchestrator
 description: Reference document, not a spawnable capability — documents the /trekresearch workflow that runs inline in main context (full rationale, CC-2.1.172 history, and phase map in body).
 model: opus
 color: cyan
-tools: ["Read", "Glob", "Grep", "Write", "Edit", "Bash"]
+tools: ["Read", "Glob", "Grep"]
 ---
 
 <!-- Phase mapping: orchestrator → command

agents/review-orchestrator.md

@@ -3,7 +3,7 @@ name: review-orchestrator
 description: Reference document, not a spawnable capability — documents the /trekreview workflow that runs inline in main context (full rationale, CC-2.1.172 history, and phase map in body).
 model: opus
 color: red
-tools: ["Read", "Glob", "Grep", "Write", "Edit", "Bash"]
+tools: ["Read", "Glob", "Grep"]
 ---
 
 <!-- Phase mapping: orchestrator → command

agents/session-decomposer.md

@@ -43,8 +43,8 @@ Extract from the plan:
 
 **Manifest handling:**
 - If `plan_version: 1.7` or later AND any step is missing a Manifest block:
-  STOP with error "Plan claims v1.7 but step N lacks Manifest. Re-run
-  planning-orchestrator." Do not attempt to synthesize.
+  STOP with error "Plan claims v1.7 but step N lacks Manifest.
+  Re-run /trekplan." Do not attempt to synthesize.
 - If no `plan_version` marker is present: treat as legacy v1.6. Synthesize
   minimal manifests from `Files:` (expected_paths) and the Checkpoint commit
   message (commit_message_pattern escaped). Mark output session specs with

commands/trekbrief.md

@@ -1096,7 +1096,7 @@ before continuing.
 
 ### Step 6e — Report completion
 
-When the planning-orchestrator finishes, present:
+When /trekplan finishes, present:
 
 ```
 ## Ultrabrief + Ultraresearch + Voyage Complete (auto mode)

commands/trekexecute.md

@@ -236,7 +236,7 @@ mode; absence or <1.7 as legacy mode.
 - If any step is missing its Manifest, or YAML is malformed, STOP with:
   ```
   Error: plan_version=1.7 but step {N} has invalid/missing Manifest.
-  Re-run planning-orchestrator — plan is not executable.
+  Re-run /trekplan — the plan is not executable.
   ```
 
 **Legacy mode (no plan_version, or < 1.7):**
@@ -334,11 +334,11 @@ Reason: {specific error from Phase 2}
 {if format not recognized}:
   Detected heading format: {e.g. "### Fase 1:", "## Phase 1"}
   Expected: "### Step N: <description>"
-  Fix: re-run /trekplan — planning-orchestrator must emit v1.7 format
+  Fix: re-run /trekplan — the plan must use v1.7 format
 
 {if missing manifest}:
   Step {N} has no Manifest block (plan_version=1.7 requires one per step)
-  Fix: re-run /trekplan — planning-orchestrator must include manifest YAML
+  Fix: re-run /trekplan — every step needs a Manifest YAML block
 
 {if malformed YAML or invalid regex}:
   Step {N}: {specific YAML/regex error}
@@ -582,7 +582,7 @@ These sessions cannot safely run in parallel.
 Fix the Execution Strategy in the plan, or use --fg for sequential execution.
 ```
 
-Stop execution. This is a defense-in-depth check — the planning-orchestrator
+Stop execution. This is a defense-in-depth check — /trekplan's validator
 should have prevented this, but verifying at execution time catches plans
 that were manually edited or have bugs.
 

docs/HANDOVER-CONTRACTS.md

@@ -148,7 +148,7 @@ with `BRIEF_INVALID_MODEL`.
 
 **Producer:** `/trekresearch` Phase 7 (synthesis + brief writer).
 
-**Consumer:** `/trekplan` Phase 1 (project-dir auto-discovery) + `planning-orchestrator` (consumes findings as context).
+**Consumer:** `/trekplan` Phase 1 (project-dir auto-discovery) + `/trekplan` Phase 3 and Phase 7 (consumes findings as context).
 
 **Path conventions:**
 - Project-dir mode: `.claude/projects/{YYYY-MM-DD}-{slug}/research/{NN}-{topic-slug}.md` (sorted by filename).
@@ -189,7 +189,7 @@ Optional: `## Local Context`, `## External Knowledge`, `## Triangulation`, `## S
 
 **Producer:** external opt-in architect plugin (no longer publicly distributed).
 
-**Consumer:** `/trekplan` Phase 1 (architecture-discovery) + `planning-orchestrator` Phase 7 (cross-reference architecture-note as priors during synthesis).
+**Consumer:** `/trekplan` Phase 1 (architecture-discovery) + `/trekplan` Phase 7 (cross-reference architecture-note as priors during synthesis).
 
 **Path conventions:**
 - Canonical: `{project_dir}/architecture/overview.md`
@@ -221,7 +221,7 @@ The validator (`lib/validators/architecture-discovery.mjs`) is intentionally min
 
 ## Handover 4 — `plan.md` → execute
 
-**Producer:** `planning-orchestrator` Phase 5 (plan synthesis) + Phase 5.5 (schema self-check via `plan-validator --strict`).
+**Producer:** `/trekplan` Phase 8 (plan synthesis, then the schema self-check via `plan-validator --strict`).
 
 **Consumer:** `/trekexecute` Phase 2 (plan parsing) + `--validate` mode.
 
@@ -280,7 +280,7 @@ prose form (relaxed in S26 so the template's prose emission parses).
 
 **Validation strategy:**
 
-The strongest validation in the entire pipeline. Phase 5.5 (planning-orchestrator) **must** run `plan-validator --strict` before handing the plan to plan-critic. `--validate` mode of `/trekexecute` runs the same check + `progress-validator`.
+The strongest validation in the entire pipeline. `/trekplan` Phase 8 **must** run `plan-validator --strict` before handing the plan to plan-critic. `--validate` mode of `/trekexecute` runs the same check + `progress-validator`.
 
 | Code | Meaning | Recovery |
 |---|---|---|

docs/architecture.md

@@ -19,7 +19,7 @@ Imported from `CLAUDE.md` via pointer.
 Wiring points (replaces previous prose-grep instructions):
 - `/trekbrief` Phase 4g → `brief-validator` (post-write sanity check)
 - `/trekplan` Phase 1 → `brief-validator --soft`, `research-validator --dir`, `architecture-discovery`
-- `planning-orchestrator` Phase 5.5 → `plan-validator --strict` (replaces 3 `grep -cE` calls)
+- `/trekplan` Phase 8 → `plan-validator --strict` (replaces 3 `grep -cE` calls)
 - `/trekexecute --validate` → `plan-validator --strict` + `progress-validator`
 
 Tests under `tests/**/*.test.mjs` (~290 tests, 0 deps). `npm test` is the fork-readiness gate. v3.4.0 adds: synthetic determinism fixtures (`tests/synthetic/plan-run-*.md` + `review-run-*.md` + companion `*-determinism.test.mjs` enforcing Jaccard ≥ 0.833 SC7 floor) and hook baseline regression pins (`tests/hooks/{path-guard,bash-guard}.test.mjs` exercising `pre-write-executor.mjs` + `pre-bash-executor.mjs` denylist BLOCK paths).

tests/lib/fix-round-4-5a-prose.test.mjs

@@ -170,3 +170,67 @@ test('helpers: line and bash are the shared line-runner pair', () => {
   assert.equal(r.status, 0);
   assert.equal(r.stdout, ROOT);
 });
+
+// --- #2 ----------------------------------------------------------------------------
+// planning-orchestrator.md is a reference document that nothing runs; the text
+// that sent a reader to it ("re-run", "must emit", "should have prevented",
+// Consumer/Producer) now names /trekplan.
+
+test('[#2] /trekexecute never sends anyone to re-run the planning reference document', () => {
+  const text = flat(read('commands/trekexecute.md'));
+  assert.doesNotMatch(text, /re-run planning-orchestrator/i, 'still says to re-run planning-orchestrator');
+  assert.doesNotMatch(text, /planning-orchestrator must/i, 'still says planning-orchestrator must emit or include');
+  assert.doesNotMatch(text, /planning-orchestrator should have prevented/i, 'still says planning-orchestrator should have prevented this');
+  assert.match(text, /Re-run \/trekplan — the plan is not executable\./);
+  assert.match(text, /Fix: re-run \/trekplan — the plan must use v1\.7 format/);
+  assert.match(text, /Fix: re-run \/trekplan — every step needs a Manifest YAML block/);
+  assert.match(text, /\/trekplan's validator should have prevented this/);
+});
+
+test('[#2] sibling: commands/trekbrief.md names /trekplan as what finishes', () => {
+  const text = flat(read('commands/trekbrief.md'));
+  assert.doesNotMatch(text, /When the planning-orchestrator finishes/);
+  assert.match(text, /When \/trekplan finishes/);
+});
+
+test('[#2] sibling: agents/brief-reviewer.md names /trekplan Phase 4b as its reader', () => {
+  const text = flat(read('agents/brief-reviewer.md'));
+  assert.doesNotMatch(text, /`planning-orchestrator` Phase 1b/);
+  assert.match(text, /\/trekplan Phase 4b/);
+});
+
+test('[#2] sibling: docs/HANDOVER-CONTRACTS.md has /trekplan, not planning-orchestrator, as Consumer, Producer and the one that must run', () => {
+  const text = read('docs/HANDOVER-CONTRACTS.md');
+  assert.doesNotMatch(text, /^\*\*(Consumer|Producer):\*\*[^\n]*planning-orchestrator/m, 'planning-orchestrator is still a Consumer or Producer');
+  assert.doesNotMatch(text, /planning-orchestrator\)? \*\*must\*\* run/, 'planning-orchestrator is still the one that must run the validator');
+  const lines = text.split('\n');
+  for (const want of [
+    '**Consumer:** `/trekplan` Phase 1 (project-dir auto-discovery) + `/trekplan` Phase 3 and Phase 7 (consumes findings as context).',
+    '**Consumer:** `/trekplan` Phase 1 (architecture-discovery) + `/trekplan` Phase 7 (cross-reference architecture-note as priors during synthesis).',
+    '**Producer:** `/trekplan` Phase 8 (plan synthesis, then the schema self-check via `plan-validator --strict`).',
+  ]) assert.ok(lines.includes(want), `missing line: ${want}`);
+  assert.match(text, /`\/trekplan` Phase 8 \*\*must\*\* run `plan-validator --strict` before handing the plan to plan-critic\./);
+});
+
+test('[#2] sibling: docs/architecture.md names /trekplan Phase 8 as the plan-validator caller', () => {
+  const text = read('docs/architecture.md');
+  assert.doesNotMatch(text, /`planning-orchestrator` Phase 5\.5/);
+  assert.match(text, /^- `\/trekplan` Phase 8 → `plan-validator --strict` \(replaces 3 `grep -cE` calls\)$/m);
+});
+
+// --- #26 ---------------------------------------------------------------------------
+
+test('[#26] session-decomposer says to re-run /trekplan, not the planning reference document', () => {
+  const text = flat(read('agents/session-decomposer.md'));
+  assert.doesNotMatch(text, /Re-run planning-orchestrator/i);
+  assert.match(text, /Re-run \/trekplan\./);
+});
+
+test('[#26] the three reference documents hold read-only tools', () => {
+  for (const name of ['planning-orchestrator', 'research-orchestrator', 'review-orchestrator']) {
+    const fm = readFrontmatterFields(read(`agents/${name}.md`));
+    assert.ok(fm.ok, fm.error);
+    assert.deepEqual(fm.fields.tools.value, ['Read', 'Glob', 'Grep'], `${name}: tools must be Read, Glob, Grep`);
+    assert.equal(fm.fields.model.value, 'opus', `${name}: model stays opus`);
+  }
+});