@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.4813ead6

package/src/resources/extensions/gsd/tests/workflow-mcp.test.ts

@@ -17,9 +17,11 @@ import {
   getRequiredWorkflowToolsForAutoUnit,
   getRequiredWorkflowToolsForGuidedUnit,
   resolveWorkflowMcpProjectRoot,
+  isWorkflowMcpSurfaceTool,
   supportsStructuredQuestions,
   usesWorkflowMcpTransport,
 } from "../workflow-mcp.ts";
+import { DB_WORKFLOW_TOOL_NAMES } from "../workflow-tool-surface.ts";
 
 const MCP_STDIO_TIMEOUT_MS = 90_000;
 
@@ -109,6 +111,18 @@ test("workflow MCP capability surface includes native legacy gsd aliases", () =>
   assert.equal(err, null);
 });
 
+test("workflow MCP capability surface includes every shared workflow contract tool", () => {
+  for (const name of DB_WORKFLOW_TOOL_NAMES) {
+    assert.equal(isWorkflowMcpSurfaceTool(name), true, `${name} should be in workflow MCP surface`);
+  }
+});
+
+test("workflow MCP capability surface preserves session and read tools outside DB contracts", () => {
+  for (const name of ["gsd_execute", "gsd_status", "gsd_progress", "gsd_doctor", "gsd_graph"]) {
+    assert.equal(isWorkflowMcpSurfaceTool(name), true, `${name} should stay in workflow MCP surface`);
+  }
+});
+
 test("deep project setup units declare required workflow MCP tools", () => {
   assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("discuss-project"), [
     "ask_user_questions",
@@ -615,23 +629,47 @@ test("usesWorkflowMcpTransport matches local externalCli providers", () => {
   assert.equal(usesWorkflowMcpTransport("oauth", "local://custom"), false);
 });
 
-test("supportsStructuredQuestions disables local workflow MCP questions unless explicitly enabled", () => {
+test("supportsStructuredQuestions recognizes workflow MCP question tools", () => {
   assert.equal(
     supportsStructuredQuestions(["ask_user_questions"], {
       authMode: "externalCli",
       baseUrl: "local://claude-code",
       env: {},
     }),
-    false,
+    true,
   );
   assert.equal(
     supportsStructuredQuestions(["mcp__gsd-workflow__ask_user_questions"], {
       authMode: "externalCli",
       baseUrl: "local://claude-code",
-      env: { GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS: "1" } as NodeJS.ProcessEnv,
+      env: {},
+    }),
+    true,
+  );
+  assert.equal(
+    supportsStructuredQuestions(["mcp__gsd-workflow__*"], {
+      authMode: "externalCli",
+      baseUrl: "local://claude-code",
+      env: {},
     }),
     true,
   );
+  assert.equal(
+    supportsStructuredQuestions(["mcp__gsd-browser__*"], {
+      authMode: "externalCli",
+      baseUrl: "local://claude-code",
+      env: {},
+    }),
+    false,
+  );
+  assert.equal(
+    supportsStructuredQuestions(["mcp__gsd-workflow__ask_user_questions"], {
+      authMode: "externalCli",
+      baseUrl: "local://claude-code",
+      env: { GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS: "0" } as NodeJS.ProcessEnv,
+    }),
+    false,
+  );
   assert.equal(
     supportsStructuredQuestions(["ask_user_questions"], {
       authMode: "oauth",
@@ -648,6 +686,39 @@ test("supportsStructuredQuestions disables local workflow MCP questions unless e
   );
 });
 
+test("supportsStructuredQuestions gates non-local externalCli providers", () => {
+  assert.equal(
+    supportsStructuredQuestions(["ask_user_questions"], {
+      authMode: "externalCli",
+      env: {},
+    }),
+    true,
+  );
+  assert.equal(
+    supportsStructuredQuestions(["ask_user_questions"], {
+      authMode: "externalCli",
+      baseUrl: "https://api.example.com",
+      env: {},
+    }),
+    true,
+  );
+  assert.equal(
+    supportsStructuredQuestions(["ask_user_questions"], {
+      authMode: "externalCli",
+      env: { GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS: "0" } as NodeJS.ProcessEnv,
+    }),
+    false,
+  );
+  assert.equal(
+    supportsStructuredQuestions(["ask_user_questions"], {
+      authMode: "externalCli",
+      baseUrl: "https://api.example.com",
+      env: { GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS: "0" } as NodeJS.ProcessEnv,
+    }),
+    false,
+  );
+});
+
 test("transport compatibility passes when required tools fit current MCP surface", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",
@@ -835,7 +906,7 @@ test("transport compatibility now allows replan-slice over workflow MCP surface"
   assert.equal(error, null);
 });
 
-test("transport compatibility rejects MCP tools not connected in active tool surface", () => {
+test("transport compatibility accepts workflow MCP tools absent from parent active tool surface", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",
     ["gsd_summary_save"],
@@ -850,10 +921,10 @@ test("transport compatibility rejects MCP tools not connected in active tool sur
     },
   );
 
-  assert.match(error ?? "", /requires gsd_summary_save/);
+  assert.equal(error, null);
 });
 
-test("transport compatibility checks all required tools against active tool surface", () => {
+test("transport compatibility still checks non-MCP tools against parent active tool surface", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",
     ["gsd_summary_save", "secure_env_collect"],
@@ -868,9 +939,54 @@ test("transport compatibility checks all required tools against active tool surf
     },
   );
 
-  assert.match(error ?? "", /requires.*(?:gsd_summary_save|secure_env_collect)/);
-  assert.match(error ?? "", /gsd_summary_save/);
-  assert.match(error ?? "", /secure_env_collect/);
+  assert.match(error ?? "", /requires secure_env_collect/);
+  assert.doesNotMatch(error ?? "", /gsd_summary_save/);
+});
+
+test("transport compatibility allows plan-slice MCP tools when parent surface is scoped (regression #457)", () => {
+  const error = getWorkflowTransportSupportError(
+    "claude-code",
+    getRequiredWorkflowToolsForAutoUnit("plan-slice"),
+    {
+      projectRoot: "/tmp/project",
+      env: { GSD_WORKFLOW_MCP_COMMAND: "node" },
+      surface: "auto-mode",
+      unitType: "plan-slice",
+      authMode: "externalCli",
+      baseUrl: "local://claude-code",
+      activeTools: [
+        "ScheduleWakeup",
+        "ToolSearch",
+        "ask_user_questions",
+        "async_bash",
+        "await_job",
+        "bash",
+        "bg_shell",
+        "cancel_job",
+        "capture_thought",
+        "discover_configs",
+        "edit",
+        "fetch_page",
+        "get_library_docs",
+        "gsd_checkpoint_db",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_milestone_status",
+        "gsd_resume",
+        "mcp_call",
+        "mcp_discover",
+        "mcp_servers",
+        "memory_query",
+        "read",
+        "resolve_library",
+        "secure_env_collect",
+        "subagent",
+        "write",
+      ],
+    },
+  );
+
+  assert.equal(error, null);
 });
 
 test("transport compatibility still blocks units whose MCP tools are not exposed", () => {
@@ -895,6 +1011,7 @@ test("discuss-milestone guided flow does not abort when all required tools are o
   // Guided flow starts the workflow MCP server as part of dispatch, so the
   // parent session active-tool list is not authoritative for MCP tools.
   const discussMilestoneTools = [
+    "ask_user_questions",
     "gsd_summary_save",
     "gsd_requirement_save",
     "gsd_requirement_update",

package/src/resources/extensions/gsd/tests/workspace-git-preflight.test.ts

@@ -109,6 +109,21 @@ test("ensureWorkspaceGitReadyForPath blocks product file conflicts", async () =>
   }
 });
 
+test("ensureWorkspaceGitReadyForPath does not block on staged files with trailing whitespace", async () => {
+  // Regression test for #599: git diff --check exits non-zero for whitespace
+  // errors as well as conflict markers. Staged files from auto-generated code
+  // often have trailing whitespace; these must not trigger the conflict gate.
+  const base = makeTempRepo("gsd-ws-git-whitespace-");
+  try {
+    writeFileSync(join(base, "app.ts"), "const x = 1;   \n"); // trailing whitespace
+    git(base, "add", "app.ts");
+    const ready = await ensureWorkspaceGitReadyForPath(base);
+    assert.equal(ready.ok, true, "trailing whitespace in staged files must not block");
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("isWorkspaceGitAllowedCommand allowlists doctor, closeout, and dispatch complete-milestone", () => {
   assert.equal(isWorkspaceGitAllowedCommand("doctor"), true);
   assert.equal(isWorkspaceGitAllowedCommand("doctor fix"), true);

package/src/resources/extensions/gsd/tests/worktree-manager.test.ts

@@ -121,6 +121,27 @@ describe("createWorktree", () => {
     run("git rev-parse --git-dir", info.path);
     assert.ok(!existsSync(join(info.path, "orphan.txt")), "stale file removed by recovery");
   });
+
+  test("removes stale worktree directory with .git file not registered with git and recreates", () => {
+    // Simulate the scenario from issue #590: removeWorktree() failed to delete
+    // the directory (e.g. EPERM on Windows) but git worktree prune cleaned up
+    // the registry — leaving an orphaned directory with a .git *file* (not
+    // directory) that git no longer knows about.
+    const staleDir = worktreePath(base, "M010");
+    mkdirSync(staleDir, { recursive: true });
+    // Write a .git file (worktree gitdir pointer) — not a directory
+    writeFileSync(join(staleDir, ".git"), "gitdir: ../../../../.git/worktrees/M010\n", "utf-8");
+    writeFileSync(join(staleDir, "orphan.txt"), "stale leftover\n", "utf-8");
+
+    // createWorktree must detect the orphan (not in git worktree list), clean it
+    // up, and succeed — not throw GSD_STALE_STATE as if it were a live conflict.
+    const info = createWorktree(base, "M010");
+    assert.strictEqual(info.name, "M010");
+    assert.ok(existsSync(info.path));
+    assert.ok(existsSync(join(info.path, ".git")), "recovered worktree has .git marker");
+    run("git rev-parse --git-dir", info.path);
+    assert.ok(!existsSync(join(info.path, "orphan.txt")), "stale file removed by recovery");
+  });
 });
 
 describe("createWorktree — duplicate rejection", () => {

package/src/resources/extensions/gsd/tests/worktree-projection-writers.test.ts

@@ -171,7 +171,7 @@ test("validate-milestone invoked from the project root writes VALIDATION under t
   const projectProjection = join(projectRoot, ".gsd", "milestones", MID, "M001-VALIDATION.md");
   assert.equal(result.validationPath, expected);
   assert.equal(existsSync(expected), true);
-  assert.equal(existsSync(projectProjection), false);
+  assert.equal(existsSync(projectProjection), true, "VALIDATION should mirror to project root for consistent reads");
 });
 
 test("complete-milestone writes SUMMARY under the active worktree projection", async (t) => {

package/src/resources/extensions/gsd/tests/worktree-safety.test.ts

@@ -150,6 +150,30 @@ describe("Worktree Safety module", () => {
     assert.equal(result.kind, "safe");
   });
 
+  test("accepts project root for source-writing Unit when isolation mode is branch", () => {
+    const safety = createWorktreeSafetyModule({
+      existsSync: () => true,
+      lstatSync: () => ({ isFile: () => false }),
+      listRegisteredWorktrees: () => [{ path: projectRoot, branch: "milestone/M001" }],
+      getCurrentBranch: () => "milestone/M001",
+    });
+
+    const result = safety.validateUnitRoot({
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+      writeScope: "source-writing",
+      projectRoot,
+      unitRoot: projectRoot,
+      milestoneId: "M001",
+      isolationMode: "branch",
+      expectedBranch: "milestone/M001",
+    });
+
+    assert.equal(result.ok, true);
+    assert.equal(result.kind, "safe");
+    assert.equal(result.branch, "milestone/M001");
+  });
+
   test("rejects non-project root for source-writing Unit when isolation mode is none", () => {
     const safety = createWorktreeSafetyModule({
       existsSync: () => true,

package/src/resources/extensions/gsd/tests/worktree-telemetry.test.ts

@@ -18,6 +18,7 @@ import {
   emitWorktreeOrphaned,
   emitAutoExit,
   emitCanonicalRootRedirect,
+  autoExitReasonForTerminalOutcome,
   normalizeAutoExitReason,
   summarizeWorktreeTelemetry,
   percentile,
@@ -117,6 +118,27 @@ test("normalizeAutoExitReason maps new buckets and ignores casing", () => {
   }
 });
 
+test("autoExitReasonForTerminalOutcome maps typed terminal outcomes", () => {
+  assert.equal(
+    autoExitReasonForTerminalOutcome({
+      code: "all-complete",
+      displayReason: "All milestones complete",
+      allMilestonesComplete: true,
+    }),
+    "all-complete",
+  );
+  assert.equal(
+    autoExitReasonForTerminalOutcome({
+      code: "settlement-blocked",
+      displayReason: "Milestone complete, merge blocked",
+      nextAction: "Retry closeout",
+      milestoneId: "M001",
+      allMilestonesComplete: false,
+    }),
+    "blocked",
+  );
+});
+
 test("summarizeWorktreeTelemetry only counts unmerged exits from active worktrees", (t) => {
   const base = makeTmpBase();
   t.after(() => cleanup(base));

package/src/resources/extensions/gsd/tests/write-gate-planning-unit.test.ts

@@ -9,7 +9,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { join, sep } from 'node:path';
 
-import { GSD_PHASE_SCOPE_DISPLAY_REASON } from '../auto-unit-tool-scope.ts';
+import { GSD_PHASE_SCOPE_DISPLAY_REASON, GSD_SECTION_CLOSE_GATE_DISPLAY_REASON } from '../auto-unit-tool-scope.ts';
 import { ALLOWED_PLANNING_DISPATCH_AGENTS, shouldBlockPlanningUnit } from '../bootstrap/write-gate.ts';
 import { extractSubagentAgentClasses } from '../bootstrap/subagent-input.ts';
 import { isDeterministicPolicyError } from '../auto-tool-tracking.ts';
@@ -377,14 +377,26 @@ test('auto-unit scope: execute-task allows only its task completion lifecycle to
   );
   assert.strictEqual(allowed.block, false);
 
+  // execute-task closes gates from summary sections, so gsd_save_gate_result gets
+  // the softer deterministic redirect instead of the normal HARD BLOCK wall.
   const blocked = shouldBlockPlanningUnit('gsd_save_gate_result', '', BASE, 'execute-task', ALL);
   assert.strictEqual(blocked.block, true);
-  assert.match(blocked.reason!, /HARD BLOCK/);
+  assert.doesNotMatch(blocked.reason!, /HARD BLOCK/);
   assert.match(blocked.reason!, /gsd_save_gate_result/);
-  assert.strictEqual(blocked.displayReason, GSD_PHASE_SCOPE_DISPLAY_REASON);
+  assert.match(blocked.reason!, /summary sections/);
+  assert.strictEqual(blocked.displayReason, GSD_SECTION_CLOSE_GATE_DISPLAY_REASON);
   assert.strictEqual(isDeterministicPolicyError(blocked.reason!), true);
 });
 
+test('auto-unit scope: section-close gate units get the calm gsd_save_gate_result redirect', () => {
+  for (const unit of ['execute-task', 'complete-slice', 'validate-milestone']) {
+    const r = shouldBlockPlanningUnit('gsd_save_gate_result', '', BASE, unit, ALL);
+    assert.strictEqual(r.block, true, `${unit} should still block the call`);
+    assert.doesNotMatch(r.reason!, /HARD BLOCK/, `${unit} should use the calm redirect`);
+    assert.strictEqual(isDeterministicPolicyError(r.reason!), true, `${unit} redirect must stay deterministic`);
+  }
+});
+
 test('auto-unit scope: execute-task blocks sibling task completion', () => {
   const r = shouldBlockPlanningUnit(
     'gsd_complete_task',

package/src/resources/extensions/gsd/tests/write-gate.test.ts

@@ -340,6 +340,8 @@ test('write-gate: reopening a gate revokes its previous verified approval', () =
 // ═══════════════════════════════════════════════════════════════════════
 
 import {
+  applyAskUserQuestionsGateResult,
+  formatPendingAskUserQuestionsGateMessage,
   isGateQuestionId,
   shouldBlockPendingGate,
   shouldBlockPendingGateBash,
@@ -379,6 +381,83 @@ test('write-gate: pending gate lifecycle (set, get, clear)', () => {
   assert.strictEqual(getPendingGate(), null, 'clearDiscussionFlowState clears pending gate');
 });
 
+test('write-gate: applyAskUserQuestionsGateResult keeps cancelled pending gate waiting', () => {
+  const base = join(tmpdir(), `gsd-write-gate-ask-waiting-${randomUUID()}`);
+  const gateId = 'depth_verification_M001_confirm';
+
+  try {
+    mkdirSync(base, { recursive: true });
+    clearDiscussionFlowState(base);
+    setPendingGate(gateId, base);
+
+    const result = applyAskUserQuestionsGateResult({
+      basePath: base,
+      questions: [{
+        id: gateId,
+        options: [{ label: 'Confirm depth (Recommended)' }, { label: 'Needs adjustment' }],
+      }],
+      details: { cancelled: true, interrupted: true },
+    });
+
+    assert.deepEqual(result, {
+      status: 'waiting',
+      pendingGateId: gateId,
+      interrupted: true,
+    });
+    assert.strictEqual(getPendingGate(base), gateId, 'cancelled question must leave gate pending');
+    assert.strictEqual(isMilestoneDepthVerified('M001', base), false, 'cancelled question must not verify depth');
+    assert.match(
+      formatPendingAskUserQuestionsGateMessage(gateId, true),
+      /Re-call ask_user_questions with the same gate question id/,
+    );
+  } finally {
+    clearDiscussionFlowState(base);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test('write-gate: applyAskUserQuestionsGateResult verifies confirmed pending gate', () => {
+  const base = join(tmpdir(), `gsd-write-gate-ask-verified-${randomUUID()}`);
+  const gateId = 'depth_verification_M001_confirm';
+  const confirmLabel = 'Confirm depth (Recommended)';
+
+  try {
+    mkdirSync(base, { recursive: true });
+    clearDiscussionFlowState(base);
+    setPendingGate(gateId, base);
+
+    const result = applyAskUserQuestionsGateResult({
+      basePath: base,
+      questions: [{
+        id: gateId,
+        options: [{ label: confirmLabel }, { label: 'Needs adjustment' }],
+      }],
+      details: {
+        response: {
+          answers: {
+            [gateId]: { selected: confirmLabel },
+          },
+        },
+      },
+    });
+
+    assert.deepEqual(result, {
+      status: 'verified',
+      gateId,
+      milestoneId: 'M001',
+    });
+    assert.strictEqual(getPendingGate(base), null, 'confirmed gate must clear pending state');
+    assert.strictEqual(isMilestoneDepthVerified('M001', base), true, 'confirmed gate must verify milestone depth');
+    assert.ok(
+      loadWriteGateSnapshot(base).verifiedApprovalGates?.includes(gateId) ?? false,
+      'confirmed gate must record verified approval',
+    );
+  } finally {
+    clearDiscussionFlowState(base);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 // ─── Scenario 21: shouldBlockPendingGate blocks non-safe tools when gate is pending ──
 
 test('write-gate: shouldBlockPendingGate blocks write/edit during pending gate', () => {

package/src/resources/extensions/gsd/tool-contract.ts

@@ -4,8 +4,10 @@
 import {
   resolveManifest,
   type ArtifactKey,
+  type ComputedArtifactId,
   type ContextModePolicy,
   type ToolsPolicy,
+  type UnitContextManifest,
 } from "./unit-context-manifest.js";
 import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
 import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
@@ -21,6 +23,7 @@ export interface UnitToolContract {
   requiredWorkflowTools: readonly string[];
   forbiddenWorkflowTools: readonly { name: string; reason: string }[];
   promptObligations: readonly string[];
+  promptContext: UnitPromptContextContract;
   validationRules: readonly string[];
   closeoutTools: readonly string[];
   sourceObservations: UnitSourceObservationContract;
@@ -31,6 +34,22 @@ export interface UnitToolContract {
   };
 }
 
+export interface UnitPromptContextContract {
+  unitType: string;
+  contextMode: ContextModePolicy;
+  toolsPolicy: ToolsPolicy;
+  obligations: readonly string[];
+  sourceObservations: UnitSourceObservationContract;
+  artifacts: {
+    inline: readonly ArtifactKey[];
+    excerpt: readonly ArtifactKey[];
+    onDemand: readonly ArtifactKey[];
+    computed: readonly ComputedArtifactId[];
+    prepend: readonly ComputedArtifactId[];
+  };
+  maxSystemPromptChars: number;
+}
+
 export type UnitSourceObservationContract =
   | { mode: "none" }
   | {
@@ -45,6 +64,22 @@ export type ToolContractResult =
   | { ok: true; contract: UnitToolContract }
   | { ok: false; reason: "unknown-unit-type" | "missing-closeout-tool"; detail: string };
 
+export type UnitContextContractResult =
+  | { ok: true; contract: UnitPromptContextContract }
+  | { ok: false; reason: "unknown-unit-type"; detail: string };
+
+export function compileUnitContextContract(unitType: string): UnitContextContractResult {
+  const manifest = resolveManifest(unitType);
+  if (!manifest) {
+    return {
+      ok: false,
+      reason: "unknown-unit-type",
+      detail: `No Unit manifest is registered for ${unitType}`,
+    };
+  }
+  return { ok: true, contract: buildPromptContextContract(unitType, manifest) };
+}
+
 export function compileUnitToolContract(unitType: string): ToolContractResult {
   const manifest = resolveManifest(unitType);
   const surfaceContract = getUnitToolSurfaceContract(unitType);
@@ -71,6 +106,8 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
     };
   }
 
+  const promptContext = buildPromptContextContract(unitType, manifest);
+
   return {
     ok: true,
     contract: {
@@ -79,10 +116,8 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
       toolsPolicy: manifest.tools,
       requiredWorkflowTools,
       forbiddenWorkflowTools,
-      promptObligations: [
-        `context-mode:${manifest.contextMode}`,
-        `tools-policy:${manifest.tools.mode}`,
-      ],
+      promptObligations: promptContext.obligations,
+      promptContext,
       validationRules: [
         "unit-manifest-present",
         "workflow-tool-surface-present",
@@ -90,16 +125,59 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
         ...(unitType === "execute-task" ? ["source-observation-contract-present"] : []),
       ],
       closeoutTools,
-      sourceObservations: sourceObservationContractForUnit(unitType),
+      sourceObservations: promptContext.sourceObservations,
       artifacts: {
-        inline: manifest.artifacts.inline,
-        excerpt: manifest.artifacts.excerpt,
-        onDemand: manifest.artifacts.onDemand,
+        inline: promptContext.artifacts.inline,
+        excerpt: promptContext.artifacts.excerpt,
+        onDemand: promptContext.artifacts.onDemand,
       },
     },
   };
 }
 
+function buildPromptContextContract(
+  unitType: string,
+  manifest: UnitContextManifest,
+): UnitPromptContextContract {
+  const sourceObservations = sourceObservationContractForUnit(unitType);
+  return {
+    unitType,
+    contextMode: manifest.contextMode,
+    toolsPolicy: manifest.tools,
+    obligations: promptContextObligations(manifest, sourceObservations),
+    sourceObservations,
+    artifacts: {
+      inline: manifest.artifacts.inline,
+      excerpt: manifest.artifacts.excerpt,
+      onDemand: manifest.artifacts.onDemand,
+      computed: manifest.artifacts.computed ?? [],
+      prepend: manifest.prepend ?? [],
+    },
+    maxSystemPromptChars: manifest.maxSystemPromptChars,
+  };
+}
+
+function promptContextObligations(
+  manifest: UnitContextManifest,
+  sourceObservations: UnitSourceObservationContract,
+): string[] {
+  const obligations = [
+    `context-mode:${manifest.contextMode}`,
+    `tools-policy:${manifest.tools.mode}`,
+    artifactObligation("context-inline", manifest.artifacts.inline),
+    artifactObligation("context-excerpt", manifest.artifacts.excerpt),
+    artifactObligation("context-on-demand", manifest.artifacts.onDemand),
+  ];
+  if (sourceObservations.mode !== "none") {
+    obligations.push(`source-observations:${sourceObservations.mode}`);
+  }
+  return obligations;
+}
+
+function artifactObligation(label: string, artifacts: readonly ArtifactKey[]): string {
+  return `${label}:${artifacts.length > 0 ? artifacts.join(",") : "none"}`;
+}
+
 function sourceObservationContractForUnit(unitType: string): UnitSourceObservationContract {
   if (unitType !== "execute-task") return { mode: "none" };
   return {