@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.738160b9

package/src/resources/extensions/gsd/tests/tool-call-loop-guard.test.ts

@@ -7,9 +7,11 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import {
   checkToolCallLoop,
+  recordToolCallLoopMutation,
   resetToolCallLoopGuard,
   disableToolCallLoopGuard,
   getToolCallLoopCount,
+  getToolCallCountForTool,
 } from '../bootstrap/tool-call-loop-guard.ts';
 
 
@@ -177,3 +179,209 @@ console.log('\n── Loop guard: nested key order is normalized ──');
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
+// Per-tool-name cap (#783 Brief C) — catches improvisation loops with varied args
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n── Loop guard: per-tool cap blocks varied-args improvisation (#783) ──');
+
+{
+  resetToolCallLoopGuard();
+
+  // A one-shot workflow tool called with DIFFERENT args each time (the reported
+  // improvisation pattern). The identical-signature streak alone would reset
+  // every call; the per-tool cap must catch it.
+  for (let i = 1; i <= 6; i++) {
+    const result = checkToolCallLoop('gsd_complete_milestone', { milestone: `M${i}` });
+    assert.ok(result.block === false, `one-shot call ${i} (varied args) should be allowed`);
+    assert.deepStrictEqual(getToolCallCountForTool('gsd_complete_milestone'), i, `per-tool count should be ${i}`);
+  }
+  // 7th call (cap 6 + 1) must be blocked by the per-tool guard.
+  const blocked = checkToolCallLoop('gsd_complete_milestone', { milestone: 'M7' });
+  assert.ok(blocked.block === true, '7th one-shot call (varied args) should be blocked by per-tool cap');
+  assert.ok(blocked.reason!.includes('repeated tool'), 'reason should identify the per-tool guard');
+  assert.ok(blocked.reason!.includes('gsd_complete_milestone'), 'reason should name the tool');
+  assert.ok(blocked.reason!.includes('7'), 'reason should mention the count');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Repeatable tools get the higher cap
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n── Loop guard: repeatable tools get the higher cap (#783) ──');
+
+{
+  resetToolCallLoopGuard();
+
+  // bash is repeatable: varied commands are legitimate up to the higher cap.
+  for (let i = 1; i <= 15; i++) {
+    const result = checkToolCallLoop('bash', { command: `echo ${i}` });
+    assert.ok(result.block === false, `bash call ${i} (varied args) should be allowed`);
+  }
+  // 16th call (cap 15 + 1) is blocked by the per-tool guard — this is the
+  // improvisation-through-bash case from the forensics (~51 calls).
+  const blocked = checkToolCallLoop('bash', { command: 'echo 16' });
+  assert.ok(blocked.block === true, '16th bash call (varied args) should be blocked by per-tool cap');
+  assert.ok(blocked.reason!.includes('cap 15'), 'reason should mention the repeatable cap');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Mutation progress decays per-tool counts (#1092)
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n── Loop guard: mutation progress decays per-tool counts (#1092) ──');
+
+{
+  resetToolCallLoopGuard();
+
+  // bash is called more than the repeatable cap, but each count is separated
+  // by a successful file mutation. Guard 2 should treat that as progress and
+  // avoid blocking the progressing unit.
+  for (let i = 1; i <= 20; i++) {
+    const result = checkToolCallLoop('bash', { command: `echo ${i}` });
+    assert.ok(result.block === false, `bash call ${i} after mutation progress should be allowed`);
+    assert.deepStrictEqual(getToolCallCountForTool('bash'), 1, `bash count should decay before call ${i}`);
+
+    const mutationTool = i % 2 === 0 ? 'write' : 'edit';
+    const mutation = checkToolCallLoop(mutationTool, {
+      path: `file-${i}.ts`,
+      content: `content ${i}`,
+    });
+    assert.ok(mutation.block === false, `${mutationTool} mutation ${i} should be allowed`);
+    recordToolCallLoopMutation(mutationTool);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Distinct read-only navigation calls are context gathering, not repeated-tool loops.
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n── Loop guard: distinct read-only navigation calls are not capped by per-tool count ──');
+
+{
+  const exemptTools = ['find', 'glob', 'grep', 'ls', 'read', 'search_and_read'];
+
+  for (const toolName of exemptTools) {
+    resetToolCallLoopGuard();
+
+    for (let i = 1; i <= 20; i++) {
+      const result = checkToolCallLoop(toolName, { path: `file-${i}.ts` });
+      assert.ok(result.block === false, `distinct ${toolName} call ${i} should be allowed`);
+    }
+
+    resetToolCallLoopGuard();
+    for (let i = 1; i <= 4; i++) {
+      const result = checkToolCallLoop(toolName, { path: 'same-file.ts' });
+      assert.ok(result.block === false, `identical ${toolName} call ${i} should be allowed`);
+    }
+
+    const blocked = checkToolCallLoop(toolName, { path: 'same-file.ts' });
+    assert.ok(blocked.block === true, `5th identical ${toolName} call should still be blocked`);
+    assert.ok(blocked.reason?.includes('identical args'), `${toolName} loops should be caught by Guard 1`);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Per-tool counts are independent per tool and reset together
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n── Loop guard: per-tool counts are independent and reset together (#783) ──');
+
+{
+  resetToolCallLoopGuard();
+
+  // Two different tools tracked separately.
+  for (let i = 0; i < 3; i++) checkToolCallLoop('read', { path: `f${i}` });
+  for (let i = 0; i < 3; i++) checkToolCallLoop('write', { path: `g${i}` });
+  assert.deepStrictEqual(getToolCallCountForTool('read'), 3, 'read tracked separately');
+  assert.deepStrictEqual(getToolCallCountForTool('write'), 3, 'write tracked separately');
+  assert.deepStrictEqual(getToolCallCountForTool('edit'), 0, 'uncalled tool reports 0');
+
+  resetToolCallLoopGuard();
+  assert.deepStrictEqual(getToolCallCountForTool('read'), 0, 'per-tool counts cleared on reset');
+  assert.deepStrictEqual(getToolCallCountForTool('write'), 0, 'per-tool counts cleared on reset');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Non-exempt repeatable tools from core-session-tools.ts get the higher cap.
+// Read-only navigation tools are exempted earlier; mutating/execution repeatable
+// tools (e.g. gsd_exec) must still trip the per-tool cap.
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n── Loop guard: non-exempt repeatable tools get high cap ──');
+
+{
+  for (const toolName of ['bg_shell', 'gsd_exec', 'write']) {
+    resetToolCallLoopGuard();
+
+    // Should allow up to 15 varied calls without blocking.
+    for (let i = 1; i <= 15; i++) {
+      const result = checkToolCallLoop(toolName, { arg: `v${i}` });
+      assert.ok(result.block === false, `${toolName} call ${i} (varied args) should be allowed`);
+    }
+    // 16th call with varied args must be blocked by the per-tool repeatable cap.
+    const blocked = checkToolCallLoop(toolName, { arg: 'v16' });
+    assert.ok(blocked.block === true, `${toolName}: 16th call must be blocked by repeatable cap`);
+    assert.ok(blocked.reason?.includes('cap 15'), `${toolName}: reason must mention cap 15`);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Non-repeatable tools excluded from INHERENTLY_REPEATABLE_TOOL_SET use the
+// default cap (6), not the repeatable cap (15).
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n── Loop guard: ToolSearch (excluded from repeatable set) hits default cap ──');
+
+{
+  // ToolSearch is in MINIMAL_AUTO_BASE but explicitly excluded from repeatable.
+  // It should hit the default cap of 6, not 15.
+  resetToolCallLoopGuard();
+  for (let i = 1; i <= 6; i++) {
+    const result = checkToolCallLoop('ToolSearch', { query: `q${i}` });
+    assert.ok(result.block === false, `ToolSearch call ${i} should be allowed`);
+  }
+  const blocked = checkToolCallLoop('ToolSearch', { query: 'q7' });
+  assert.ok(blocked.block === true, 'ToolSearch: 7th varied call must be blocked by default cap');
+  assert.ok(!blocked.reason?.includes('cap 15'), 'ToolSearch must NOT use the repeatable cap');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Block reasons instruct the model to stop tooling this turn
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n── Loop guard: block reasons tell model to respond in text ──');
+
+{
+  resetToolCallLoopGuard();
+
+  for (let i = 0; i < 4; i++) {
+    checkToolCallLoop('web_search', { query: 'same query' });
+  }
+  const identicalBlocked = checkToolCallLoop('web_search', { query: 'same query' });
+  assert.ok(identicalBlocked.block === true, 'identical-args guard should block');
+  assert.ok(
+    identicalBlocked.reason!.includes('respond to the user in text'),
+    'identical-args reason should tell the model to stop tooling',
+  );
+  assert.ok(
+    !identicalBlocked.reason!.includes('Try a different approach'),
+    'identical-args reason should not suggest retrying another tool',
+  );
+
+  resetToolCallLoopGuard();
+  for (let i = 0; i < 6; i++) {
+    checkToolCallLoop('gsd_complete_milestone', { milestone: `M${i}` });
+  }
+  const perToolBlocked = checkToolCallLoop('gsd_complete_milestone', { milestone: 'M7' });
+  assert.ok(perToolBlocked.block === true, 'per-tool guard should block');
+  assert.ok(
+    perToolBlocked.reason!.includes('respond to the user in text'),
+    'per-tool reason should tell the model to stop tooling',
+  );
+  assert.ok(
+    perToolBlocked.reason!.includes('Do not retry this tool'),
+    'per-tool reason should forbid retrying the blocked tool',
+  );
+}
+
+// ═══════════════════════════════════════════════════════════════════════════

package/src/resources/extensions/gsd/tests/tool-param-optionality.test.ts

@@ -13,6 +13,7 @@
 
 import { test } from "node:test";
 import assert from "node:assert/strict";
+import { SUMMARY_SAVE_CONTENT_MAX_LENGTH } from "@opengsd/contracts";
 import { registerDbTools } from "../bootstrap/db-tools.ts";
 import AjvModule from "ajv";
 
@@ -86,6 +87,31 @@ test("gsd_summary_save — validates UAT assessment params", () => {
   assert.strictEqual(valid, true, `UAT assessment params should validate but got errors: ${JSON.stringify(validate.errors)}`);
 });
 
+test("gsd_summary_save — content has a provider-safe maxLength", () => {
+  const tool = getTool("gsd_summary_save");
+  assert.ok(tool, "gsd_summary_save must be registered");
+
+  const contentSchema = tool.parameters.properties.content;
+  assert.strictEqual(contentSchema.maxLength, SUMMARY_SAVE_CONTENT_MAX_LENGTH);
+
+  const validAtLimit = validateSchema(tool, {
+    milestone_id: "M001",
+    artifact_type: "CONTEXT-DRAFT",
+    content: "x".repeat(SUMMARY_SAVE_CONTENT_MAX_LENGTH),
+  });
+  assert.deepEqual(validAtLimit, []);
+
+  const overLimit = validateSchema(tool, {
+    milestone_id: "M001",
+    artifact_type: "CONTEXT-DRAFT",
+    content: "x".repeat(SUMMARY_SAVE_CONTENT_MAX_LENGTH + 1),
+  });
+  assert.ok(
+    overLimit.some((error) => error.includes(`must NOT have more than ${SUMMARY_SAVE_CONTENT_MAX_LENGTH} characters`)),
+    `expected maxLength validation error, got: ${overLimit.join("; ")}`,
+  );
+});
+
 // ─── gsd_slice_complete: enrichment arrays must be optional ──────────────────
 
 test("gsd_slice_complete — enrichment arrays are optional", () => {
@@ -359,14 +385,17 @@ test("gsd_plan_slice — enrichment fields are optional", () => {
 
   const required = new Set(getRequiredProps(tool));
 
-  // Core fields
-  const coreRequired = ["milestoneId", "sliceId", "goal", "tasks"];
+  // Core fields. `tasks` is intentionally NOT here: incremental planning
+  // (#1027) lets gsd_plan_slice persist slice metadata only, then add tasks
+  // one at a time via gsd_plan_task, so tasks must be optional.
+  const coreRequired = ["milestoneId", "sliceId", "goal"];
   for (const field of coreRequired) {
     assert.ok(required.has(field), `core field "${field}" must be required`);
   }
 
-  // Enrichment fields
+  // Enrichment fields (plus tasks, optional for incremental planning).
   const enrichmentFields = [
+    "tasks",
     "successCriteria",
     "proofLevel",
     "integrationClosure",

package/src/resources/extensions/gsd/tests/undo.test.ts

@@ -10,6 +10,7 @@ import {
   handleUndo,
   handleUndoTask,
   handleResetSlice,
+  parseActivityLogFilename,
   uncheckTaskInPlan,
 } from "../undo.ts";
 import {
@@ -67,6 +68,37 @@ test("handleUndo without --force only warns and leaves completed units intact",
   }
 });
 
+test("handleUndo execute-task with --force reopens the task row and re-renders plan", async () => {
+  const base = makeTempDir("gsd-undo-execute-task");
+  try {
+    setupTaskFixture(base);
+    mkdirSync(join(base, ".gsd", "activity"), { recursive: true });
+    writeFileSync(
+      join(base, ".gsd", "activity", "001-execute-task-M001-S01-T01.jsonl"),
+      "",
+      "utf-8",
+    );
+
+    const { notifications, ctx } = makeCtx();
+    await handleUndo("--force", ctx, {} as any, base);
+
+    const task = getTask("M001", "S01", "T01");
+    assert.equal(task?.status, "pending");
+
+    const planContent = readFileSync(
+      join(base, ".gsd", "phases", "01-test", "01-01-PLAN.md"),
+      "utf-8",
+    );
+    assert.match(planContent, /\[ \] \*\*T01\*\*:/);
+
+    assert.equal(notifications[0]?.level, "success");
+    assert.match(notifications[0]?.message ?? "", /Unchecked task in PLAN/);
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 test("uncheckTaskInPlan flips a checked task back to unchecked", () => {
   const base = makeTempDir("gsd-undo-plan");
   try {
@@ -154,6 +186,48 @@ test("extractCommitShas ignores malformed commit tokens", () => {
   assert.deepEqual(extractCommitShas(content), ["1234567"]);
 });
 
+test("parseActivityLogFilename splits hyphenated unit types from their IDs", () => {
+  // Task-level: unit type and ID both contain hyphens.
+  assert.deepEqual(parseActivityLogFilename("001-execute-task-M001-S01-T01.jsonl"), {
+    unitType: "execute-task",
+    unitId: "M001-S01-T01",
+  });
+  // Variant must win over its shorter prefix ("execute-task").
+  assert.deepEqual(parseActivityLogFilename("002-execute-task-simple-M001-S02-T03.jsonl"), {
+    unitType: "execute-task-simple",
+    unitId: "M001-S02-T03",
+  });
+  // Milestone- and slice-shaped IDs.
+  assert.deepEqual(parseActivityLogFilename("003-research-milestone-M001.jsonl"), {
+    unitType: "research-milestone",
+    unitId: "M001",
+  });
+  assert.deepEqual(parseActivityLogFilename("004-plan-slice-M001-S01.jsonl"), {
+    unitType: "plan-slice",
+    unitId: "M001-S01",
+  });
+});
+
+test("parseActivityLogFilename accepts non-milestone-shaped unit IDs", () => {
+  // Regression (#1057): project-level units use IDs that do not start with
+  // "M<digit>". A milestone-shaped regex made /gsd undo bail out with
+  // "could not parse latest activity log" when one of these was most recent.
+  assert.deepEqual(parseActivityLogFilename("005-discuss-project-PROJECT.jsonl"), {
+    unitType: "discuss-project",
+    unitId: "PROJECT",
+  });
+  assert.deepEqual(parseActivityLogFilename("006-workflow-preferences-WORKFLOW-PREFS.jsonl"), {
+    unitType: "workflow-preferences",
+    unitId: "WORKFLOW-PREFS",
+  });
+});
+
+test("parseActivityLogFilename returns null for unrecognized names", () => {
+  assert.equal(parseActivityLogFilename("007-not-a-real-unit-M001.jsonl"), null);
+  assert.equal(parseActivityLogFilename("no-sequence-prefix.jsonl"), null);
+  assert.equal(parseActivityLogFilename("001-execute-task-M001-S01-T01.txt"), null);
+});
+
 // ─── handleUndoTask tests ────────────────────────────────────────────────────
 
 function makeCtx(): { notifications: Array<{ message: string; level: string }>; ctx: any } {

package/src/resources/extensions/gsd/tests/unit-context-composer.test.ts

@@ -8,6 +8,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import {
+  CONTEXT_MODE_GUIDANCE_BY_UNIT,
   composeContractedUnitContext,
   composeContextModeInstructions,
   composeInlinedContext,
@@ -141,9 +142,13 @@ test("Context Mode composer: nested output is compact single sentence", () => {
   assert.ok(!out.startsWith("## Context Mode"));
   assert.match(out, /^Context Mode \(verification lane\): /);
   assert.strictEqual(out.split(/\n/).length, 1);
-  assert.match(out, /`gsd_exec`/);
-  assert.match(out, /`gsd_exec_search`/);
-  assert.match(out, /`gsd_resume`/);
+  // Nested guidance is embedded into tester subagent prompts — it must instruct the tester
+  // to run verification and call gsd_save_gate_result, NOT to dispatch further subagents.
+  assert.doesNotMatch(out, /`subagent`/, "tester prompts must not be told to dispatch subagents");
+  assert.match(out, /`gsd_save_gate_result`/);
+  assert.doesNotMatch(out, /`gsd_exec`/);
+  assert.doesNotMatch(out, /`gsd_exec_search`/);
+  assert.doesNotMatch(out, /`gsd_resume`/);
   assert.ok(out.length < 240, `nested guidance should stay compact, got ${out.length} chars`);
 });
 
@@ -158,6 +163,53 @@ const laneLabelByMode: Record<string, string> = {
   triage: "triage",
 };
 
+const contextModeGuidanceOverrideExpectedTools: Record<string, readonly string[]> = {
+  "discuss-milestone": [
+    "ask_user_questions",
+    "gsd_summary_save",
+    "gsd_decision_save",
+    "gsd_requirement_save",
+    "gsd_requirement_update",
+    "gsd_plan_milestone",
+    "gsd_milestone_generate_id",
+  ],
+  "discuss-project": [
+    "ask_user_questions",
+    "gsd_summary_save",
+    "gsd_decision_save",
+    "gsd_requirement_save",
+  ],
+  "discuss-requirements": [
+    "ask_user_questions",
+    "gsd_requirement_save",
+    "gsd_summary_save",
+  ],
+  "discuss-slice": [
+    "ask_user_questions",
+    "gsd_summary_save",
+    "gsd_decision_save",
+  ],
+  "replan-slice": [
+    "gsd_replan_slice",
+    "gsd_decision_save",
+  ],
+  "reassess-roadmap": [
+    "gsd_milestone_status",
+    "gsd_reassess_roadmap",
+  ],
+  "run-uat": [
+    "gsd_uat_exec",
+    "gsd_resume",
+  ],
+  // research-project uses scout subagents that write .gsd/research/ files directly;
+  // the parent dispatches Task calls and verifies file outputs — no GSD save tools.
+  "research-project": [],
+  "gate-evaluate": [
+    "subagent",
+    "gsd_save_gate_result",
+  ],
+};
+
 test("Context Mode composer: every known eligible unit renders its configured lane and required tools", () => {
   for (const unitType of KNOWN_UNIT_TYPES) {
     const manifest = UNIT_MANIFESTS[unitType];
@@ -170,18 +222,65 @@ test("Context Mode composer: every known eligible unit renders its configured la
     assert.ok(out.startsWith("## Context Mode"), `${unitType} should render standalone Context Mode heading`);
     assert.match(out, new RegExp(`Lane: \\*\\*${laneLabelByMode[manifest.contextMode]} lane\\*\\*\\.`, "i"));
     const forbidden = getUnitToolSurfaceContract(unitType)?.forbiddenGsdTools ?? {};
-    if ("gsd_exec" in forbidden) {
-      // Units that forbid gsd_exec (run-uat) have it stripped from their
-      // Claude Code dispatch surface; guidance steering to it produces
-      // "No such tool available" loops in the dispatched agent.
-      assert.doesNotMatch(out, /`gsd_exec`/, `${unitType} forbids gsd_exec; guidance must not steer to it`);
+    const overrideExpectedTools = contextModeGuidanceOverrideExpectedTools[unitType];
+    if ("gsd_exec" in forbidden || overrideExpectedTools) {
+      // Unit overrides are the contract-specific exception to lane defaults.
+      // Steering to the lane default here can produce unavailable-tool loops.
+      assert.doesNotMatch(out, /`gsd_exec`/, `${unitType} guidance must not steer to gsd_exec`);
       assert.doesNotMatch(out, /`gsd_exec_search`/, `${unitType} guidance must not steer to gsd_exec_search`);
-      assert.match(out, /`gsd_uat_exec`/, `${unitType} guidance should steer to gsd_uat_exec instead`);
+      for (const toolName of overrideExpectedTools ?? []) {
+        assert.match(out, new RegExp(`\`${toolName}\``), `${unitType} guidance should mention ${toolName}`);
+      }
     } else {
       assert.match(out, /`gsd_exec`/, `${unitType} should mention gsd_exec`);
       assert.match(out, /`gsd_exec_search`/, `${unitType} should mention gsd_exec_search`);
     }
-    assert.match(out, /`gsd_resume`/, `${unitType} should mention gsd_resume`);
+    if (!overrideExpectedTools || overrideExpectedTools.includes("gsd_resume")) {
+      assert.match(out, /`gsd_resume`/, `${unitType} should mention gsd_resume`);
+    } else {
+      assert.doesNotMatch(out, /`gsd_resume`/, `${unitType} guidance must not steer to gsd_resume`);
+    }
+  }
+});
+
+test("Context Mode composer: discuss interview overrides stay within unit contracts", () => {
+  const discussUnits = [
+    "discuss-milestone",
+    "discuss-project",
+    "discuss-requirements",
+    "discuss-slice",
+  ];
+
+  for (const unitType of discussUnits) {
+    const guidance = CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType];
+    assert.ok(guidance, `${unitType} should have a Context Mode override`);
+    assert.doesNotMatch(guidance, /`gsd_exec`/, `${unitType} guidance must not mention gsd_exec`);
+    assert.doesNotMatch(guidance, /`gsd_exec_search`/, `${unitType} guidance must not mention gsd_exec_search`);
+    assert.doesNotMatch(guidance, /`gsd_resume`/, `${unitType} guidance must not mention gsd_resume`);
+
+    const expectedTools = contextModeGuidanceOverrideExpectedTools[unitType] ?? [];
+    assert.ok(expectedTools.length > 0, `${unitType} should declare expected override tools`);
+    const contract = getUnitToolSurfaceContract(unitType);
+    assert.ok(contract, `${unitType} should have a tool contract`);
+    const contractTools = new Set([
+      ...contract.allowedGsdTools,
+      ...contract.requiredWorkflowTools,
+    ]);
+
+    for (const toolName of expectedTools) {
+      assert.match(guidance, new RegExp(`\`${toolName}\``), `${unitType} guidance should mention ${toolName}`);
+      assert.ok(contractTools.has(toolName as UnitGsdToolName), `${unitType} contract should allow ${toolName}`);
+      const scope = shouldBlockAutoUnitToolCall(unitType, toolName);
+      assert.equal(scope.block, false, `${unitType} should not hard-block ${toolName}: ${scope.reason ?? ""}`);
+    }
+
+    const out = composeContextModeInstructions(unitType, { enabled: true, renderMode: "standalone" });
+    if (out) {
+      assert.match(out, /interview lane/i);
+      assert.doesNotMatch(out, /`gsd_exec`/);
+      assert.doesNotMatch(out, /`gsd_exec_search`/);
+      assert.doesNotMatch(out, /`gsd_resume`/);
+    }
   }
 });
 
@@ -195,8 +294,67 @@ test("Context Mode composer: run-uat guidance steers to gsd_uat_exec in both ren
   assert.doesNotMatch(standalone, /`gsd_exec`/);
 });
 
-test("Context Mode composer: slice planning and research guidance tools pass unit contracts", () => {
-  const affectedUnits = ["research-slice", "plan-slice", "refine-slice"];
+test("Context Mode composer: research-project guidance steers to scout orchestration", () => {
+  for (const renderMode of ["nested", "standalone"] as const) {
+    const out = composeContextModeInstructions("research-project", { enabled: true, renderMode });
+    assert.match(out, /research lane/i);
+    assert.match(out, /scout subagents/i);
+    assert.match(out, /\.gsd\/research\//);
+    assert.match(out, /STACK\.md/);
+    assert.match(out, /PITFALLS\.md/);
+    assert.doesNotMatch(out, /`gsd_summary_save`/);
+    assert.doesNotMatch(out, /`gsd_decision_save`/);
+    assert.doesNotMatch(out, /`gsd_exec`/);
+    assert.doesNotMatch(out, /`gsd_exec_search`/);
+    assert.doesNotMatch(out, /`gsd_resume`/);
+  }
+
+  const contract = getUnitToolSurfaceContract("research-project");
+  assert.deepEqual(contract?.allowedGsdTools, []);
+  assert.deepEqual(contract?.requiredWorkflowTools, []);
+  for (const toolName of ["gsd_summary_save", "gsd_decision_save"]) {
+    const scope = shouldBlockAutoUnitToolCall("research-project", toolName);
+    assert.equal(scope.block, true, `research-project should not allow ${toolName}`);
+  }
+});
+
+test("Context Mode composer: narrow planning guidance steers only to contracted tools", () => {
+  const cases = [
+    {
+      unitType: "replan-slice",
+      expectedTools: ["gsd_replan_slice", "gsd_decision_save"],
+    },
+    {
+      unitType: "reassess-roadmap",
+      expectedTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
+    },
+  ];
+  const disallowedTools = ["gsd_exec", "gsd_exec_search", "gsd_resume"];
+
+  for (const { unitType, expectedTools } of cases) {
+    for (const renderMode of ["nested", "standalone"] as const) {
+      const out = composeContextModeInstructions(unitType, { enabled: true, renderMode });
+      assert.match(out, /planning lane/i, `${unitType} should still render planning lane guidance`);
+      for (const toolName of expectedTools) {
+        assert.ok(out.includes(`\`${toolName}\``), `${unitType} guidance should mention ${toolName}`);
+      }
+      for (const toolName of disallowedTools) {
+        assert.ok(!out.includes(`\`${toolName}\``), `${unitType} guidance must not mention ${toolName}`);
+      }
+    }
+  }
+});
+
+test("Context Mode composer: lane guidance tools pass unit contracts", () => {
+  const affectedUnits = [
+    "research-milestone",
+    "research-slice",
+    "plan-slice",
+    "refine-slice",
+    "complete-slice",
+    "validate-milestone",
+    "complete-milestone",
+  ];
   const contextModeTools: UnitGsdToolName[] = ["gsd_exec", "gsd_exec_search", "gsd_resume"];
   const readOnlyOrientationTools: UnitGsdToolName[] = ["gsd_milestone_status", ...contextModeTools];
 
@@ -207,7 +365,10 @@ test("Context Mode composer: slice planning and research guidance tools pass uni
     for (const toolName of contextModeTools) {
       assert.ok(out.includes(`\`${toolName}\``), `${unitType} guidance should mention ${toolName}`);
     }
-    for (const toolName of readOnlyOrientationTools) {
+    const expectedContractTools = unitType === "research-milestone"
+      ? contextModeTools
+      : readOnlyOrientationTools;
+    for (const toolName of expectedContractTools) {
       assert.ok(allowed.has(toolName), `${unitType} contract should allow ${toolName}`);
       const scope = shouldBlockAutoUnitToolCall(unitType, toolName);
       assert.equal(scope.block, false, `${unitType} should not hard-block ${toolName}: ${scope.reason ?? ""}`);
@@ -357,13 +518,31 @@ test("#4782 phase 2: buildReassessRoadmapPrompt emits composer-shaped context wi
   assert.ok(!prompt.includes("Slice Context (from discussion)"));
 });
 
-test("execute-task prompt surfaces contract-declared on-demand slice research", async (t) => {
+test("execute-task prompt omits on-demand slice research when the artifact is absent", async (t) => {
+  const base = makeFixtureBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  seed(base, "M001");
+  writeArtifacts(base);
+
+  const prompt = await buildExecuteTaskPrompt("M001", "S01", "First", "T01", "Task", base);
+
+  assert.doesNotMatch(prompt, /## On-demand Context/);
+  assert.doesNotMatch(prompt, /\.gsd\/milestones\/M001\/slices\/S01\/S01-RESEARCH\.md/);
+});
+
+test("execute-task prompt surfaces on-demand slice research when the artifact exists", async (t) => {
   const base = makeFixtureBase();
   t.after(() => cleanup(base));
   invalidateAllCaches();
 
   seed(base, "M001");
   writeArtifacts(base);
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-RESEARCH.md"),
+    "# S01 Research\n",
+  );
 
   const prompt = await buildExecuteTaskPrompt("M001", "S01", "First", "T01", "Task", base);