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>

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`);
+  }
+});