@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.84c56d87

package/dist/resources/extensions/gsd/roadmap-slices.js

@@ -191,9 +191,15 @@ export function parseRoadmapSlices(content) {
             const riskMatch = rest.match(/`risk:(\w+)`/);
             const risk = (riskMatch ? riskMatch[1] : "low");
             const depsMatch = rest.match(/`depends:\[([^\]]*)\]`/);
-            const depends = depsMatch && depsMatch[1].trim()
-                ? expandDependencies(depsMatch[1].split(",").map(s => s.trim()))
+            // Recovery fallback: double-bracket form `[[id]]` from serialized bracket-wrapped IDs
+            const fallbackDepsMatch = depsMatch ? null : rest.match(/`depends:\[(\[(?:[^\]]*)\](?:,\[(?:[^\]]*)\])*)\]`/);
+            const rawDepContent = (depsMatch ?? fallbackDepsMatch)?.[1] ?? "";
+            const SLICE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+            const RANGE_RE = /^[A-Za-z]+\d+(?:-|\.\.)[A-Za-z]+\d+$/;
+            const rawDepParts = rawDepContent.trim()
+                ? rawDepContent.replace(/\[|\]/g, "").split(",").map(s => s.trim()).filter(s => SLICE_ID_RE.test(s) || RANGE_RE.test(s))
                 : [];
+            const depends = expandDependencies(rawDepParts);
             // ADR-011: the renderer writes a `[sketch]` badge for sketch slices.
             // Parse it back so the is_sketch flag survives a markdown → DB re-import
             // (e.g. /gsd recover); otherwise the flag was silently lost.

package/dist/resources/extensions/gsd/safety/evidence-collector.js

@@ -21,9 +21,10 @@ const EXECUTION_TOOL_NAMES = new Set([
     "functions.exec_command",
     "gsd_exec",
     "gsd_exec_search",
+    "gsd_uat_exec",
     "powershell",
 ]);
-const MCP_EXECUTION_TOOL_RE = /^mcp__.+__gsd_exec(?:_search)?$/;
+const MCP_EXECUTION_TOOL_RE = /^mcp__.+__gsd_(?:uat_)?exec(?:_search)?$/;
 // ─── Module State ───────────────────────────────────────────────────────────
 let unitEvidence = [];
 // ─── Public API ─────────────────────────────────────────────────────────────
@@ -146,11 +147,18 @@ export function clearEvidenceFromDisk(basePath, milestoneId, sliceId, taskId) {
  * Exit codes and output are filled in by recordToolResult after execution.
  */
 export function recordToolCall(toolCallId, toolName, input) {
+    // Idempotent by toolCallId: native tools reach this via both
+    // tool_execution_start and tool_call; external (pre-executed) tools only
+    // via tool_execution_start. First recording wins.
+    if (unitEvidence.some(e => e.toolCallId === toolCallId))
+        return;
     if (isExecutionToolName(toolName)) {
         unitEvidence.push({
             kind: "bash",
             toolCallId,
-            command: String(input.command ?? input.cmd ?? input.query ?? ""),
+            // gsd_exec / gsd_uat_exec carry the script body in `script` (or `code`);
+            // bash-style tools use `command`/`cmd`; gsd_exec_search uses `query`.
+            command: String(input.command ?? input.script ?? input.cmd ?? input.code ?? input.query ?? ""),
             exitCode: -1,
             outputSnippet: "",
             timestamp: Date.now(),
@@ -185,9 +193,34 @@ export function recordToolResult(toolCallId, toolName, result, isError) {
     if (entry.kind === "bash") {
         const text = extractResultText(result);
         entry.outputSnippet = text.slice(0, 500);
-        const exitMatch = text.match(/Command exited with code (\d+)/);
-        entry.exitCode = exitMatch ? Number(exitMatch[1]) : (isError ? 1 : 0);
+        entry.exitCode = resolveExitCode(text, isError);
+    }
+}
+/**
+ * Resolve the exit code from a tool result's text. Handles the bash tool's
+ * prose marker, the gsd_exec / gsd_uat_exec JSON envelope (`"exit_code": N`),
+ * and a last-resort read of the run's persisted `.gsd/exec/<id>.meta.json`
+ * (covers truncated result text).
+ */
+function resolveExitCode(text, isError) {
+    const proseMatch = text.match(/Command exited with code (\d+)/);
+    if (proseMatch)
+        return Number(proseMatch[1]);
+    const jsonMatch = text.match(/"exit_code"\s*:\s*(-?\d+)/);
+    if (jsonMatch)
+        return Number(jsonMatch[1]);
+    const metaMatch = text.match(/"meta_path"\s*:\s*"([^"]+)"/);
+    if (metaMatch) {
+        try {
+            const meta = JSON.parse(readFileSync(metaMatch[1], "utf-8"));
+            if (typeof meta.exit_code === "number")
+                return meta.exit_code;
+        }
+        catch {
+            // Fall through to the isError heuristic
+        }
     }
+    return isError ? 1 : 0;
 }
 // ─── Internals ──────────────────────────────────────────────────────────────
 function extractResultText(result) {

package/dist/resources/extensions/gsd/safety/evidence-cross-ref.js

@@ -80,8 +80,13 @@ function findMatches(claimedCommand, bashCalls) {
     const exact = bashCalls.filter(b => b.command.trim() === normalized);
     if (exact.length > 0)
         return exact;
-    // Substring match: claimed is contained in actual or actual in claimed
-    const substring = bashCalls.filter(b => b.command.includes(normalized) || normalized.includes(b.command));
+    // Substring match: claimed is contained in actual or actual in claimed.
+    // A claimed verification command typically appears verbatim inside a
+    // larger gsd_exec script body (cd prefix, multi-line scripts), so
+    // script-containing-claim is the common direction. Blank-command entries
+    // must be excluded — `"x".includes("")` is true, so they'd match anything.
+    const substring = bashCalls.filter(b => b.command.trim().length > 0 &&
+        (b.command.includes(normalized) || normalized.includes(b.command)));
     if (substring.length > 0)
         return substring;
     // Token match: split on whitespace and check significant overlap

package/dist/resources/extensions/gsd/safety/file-change-validator.js

@@ -17,6 +17,16 @@ import { logWarning } from "../workflow-logger.js";
 const _require = createRequire(import.meta.url);
 const picomatch = _require("picomatch");
 // ─── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Build the effective allowlist for a unit's file-change audit.
+ *
+ * When GSD manages .gitignore (manage_gitignore unset or true), ensureGitignore()
+ * appends baseline patterns at auto-start and the edit rides into the task's
+ * auto-commit — so .gitignore changes must not be attributed to the task.
+ */
+export function effectiveFileChangeAllowlist(baseAllowlist, manageGitignore) {
+    return manageGitignore === false ? baseAllowlist : [...baseAllowlist, ".gitignore"];
+}
 /**
  * Validate file changes after auto-commit for an execute-task unit.
  * Returns null if task data is unavailable or DB is not loaded.

package/dist/resources/extensions/gsd/slice-parallel-orchestrator.js

@@ -19,7 +19,8 @@ import { isAbsolute, join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gsdRoot } from "./paths.js";
 import { createWorktree, worktreePath, removeWorktree } from "./worktree-manager.js";
-import { runWorktreePostCreateHook, syncGsdStateToWorktree } from "./auto-worktree.js";
+import { runWorktreePostCreateHook, syncGsdStateToWorktreeByScope } from "./auto-worktree.js";
+import { createWorkspace, scopeMilestone } from "./workspace.js";
 import { writeSessionStatus, } from "./session-status-io.js";
 import { hasFileConflict } from "./slice-parallel-conflict.js";
 import { getErrorMessage } from "./error-utils.js";
@@ -108,7 +109,7 @@ function createSliceWorktree(basePath, milestoneId, sliceId) {
     if (hookError) {
         throw new Error(`slice worktree post-create hook failed (${wtName}): ${hookError}`);
     }
-    syncGsdStateToWorktree(basePath, wtPath);
+    syncGsdStateToWorktreeByScope(scopeMilestone(createWorkspace(basePath), milestoneId), scopeMilestone(createWorkspace(wtPath), milestoneId));
     if (!existsSync(join(wtPath, ".gsd"))) {
         throw new Error(`slice worktree preflight failed (${wtName}): missing .gsd in worktree`);
     }

package/dist/resources/extensions/gsd/state-transition-matrix.js

@@ -99,6 +99,44 @@ export const STATE_TRANSITION_MATRIX = [
 export function findTransition(from, event) {
     return STATE_TRANSITION_MATRIX.find((entry) => (entry.from === from || entry.from === "*") && entry.event === event);
 }
+/**
+ * Edge-keyed legality check for the Phase Transition Invariant (ADR-030).
+ * `advance()` derives the next Phase and asserts the (from → to) edge here.
+ *
+ * The matrix is an assertion, not a decision-maker — `deriveState` already
+ * chose the Phase. A self-edge is trivially legal (no transition to assert). An
+ * edge is legal when some matrix entry permits it, honoring the `*` wildcard
+ * rows (e.g. any → blocked via manual-block, any → executing via
+ * retryable-failure).
+ *
+ * Note: the matrix is currently a sparse hardening spec, not a complete
+ * legal-edge graph, so `advance()` consumes this in advisory mode (telemetry
+ * only). It must be expanded to cover every edge `deriveState` emits before
+ * enforcement flips on.
+ */
+export function isLegalEdge(from, to) {
+    if (from === to)
+        return true;
+    return STATE_TRANSITION_MATRIX.some((entry) => (entry.from === from || entry.from === "*") && entry.to === to);
+}
+/**
+ * Thrown when an illegal derived Phase edge survives reconciliation. Carries
+ * both endpoints so Recovery Classification can report them. Recognized by
+ * class in `classifyFailure` and mapped to the `illegal-transition` kind.
+ */
+export class IllegalPhaseTransitionError extends Error {
+    // Explicit fields, not constructor parameter properties — strip-types
+    // consumers (workspace-index subprocess, integration tests) reject the
+    // parameter-property syntax with ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX.
+    from;
+    to;
+    constructor(from, to) {
+        super(`Illegal phase transition ${from} -> ${to} survived reconciliation`);
+        this.name = "IllegalPhaseTransitionError";
+        this.from = from;
+        this.to = to;
+    }
+}
 export function validateTransitionMatrix(requiredEvents) {
     const seen = new Set();
     const duplicateKeys = [];

package/dist/resources/extensions/gsd/state.js

@@ -18,28 +18,11 @@ import { logWarning } from './workflow-logger.js';
 import { extractVerdict } from './verdict-parser.js';
 import { detectPendingEscalation } from './escalation.js';
 import { isTerminalMilestoneSummaryContent } from './milestone-summary-classifier.js';
-import { isDbAvailable, wasDbOpenAttempted, getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, getRequirementCounts, getLatestAssessmentByScope, getPendingGateCountForTurn, } from './gsd-db.js';
+import { isDbAvailable, getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, getRequirementCounts, getLatestAssessmentByScope, getPendingGateCountForTurn, } from './gsd-db.js';
+import { wasWorkflowDatabaseOpenAttempted } from './db-workspace.js';
 import { formatCompletePhaseNextAction, countUnmappedActiveRequirements } from './requirements-backlog.js';
-function formatNeedsAttentionBlocker(milestoneId) {
-    return [
-        `Milestone ${milestoneId} is blocked because milestone validation returned needs-attention.`,
-        `Fix options:`,
-        `1. Review the validation details: \`/gsd status\``,
-        `2. If you fixed the missing evidence or issue, re-run milestone validation: \`/gsd validate-milestone\``,
-        `3. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
-        `4. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
-        `After validation or override passes, run \`/gsd auto\` to complete and merge the milestone.`,
-    ].join("\n");
-}
-function formatNeedsRemediationBlocker(milestoneId) {
-    return [
-        `Milestone ${milestoneId} is blocked because milestone validation returned needs-remediation, but all slices are complete.`,
-        `Fix options:`,
-        `1. Run \`/gsd dispatch reassess\` to add remediation slices, then run \`/gsd auto\``,
-        `2. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
-        `3. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
-    ].join("\n");
-}
+import { classifyMilestoneReadiness, readinessNeedsDiscussion, } from './milestone-readiness.js';
+import { needsAttentionBlockerGuidance as formatNeedsAttentionBlocker, needsRemediationBlockerGuidance as formatNeedsRemediationBlocker, } from './guidance.js';
 /**
  * A "ghost" milestone directory contains only META.json (and no substantive
  * files like CONTEXT, CONTEXT-DRAFT, ROADMAP, or SUMMARY).  These appear when
@@ -301,7 +284,7 @@ export async function deriveState(basePath, opts) {
         _telemetry.dbDeriveCount++;
     }
     else {
-        if (wasDbOpenAttempted()) {
+        if (wasWorkflowDatabaseOpenAttempted()) {
             logWarning("state", "DB unavailable — refusing implicit markdown state derivation");
         }
         result = {
@@ -396,6 +379,12 @@ async function buildRegistryAndFindActive(basePath, milestones, completeMileston
         const title = stripMilestonePrefix(m.title) || m.id;
         const hasContext = !!resolveMilestoneFile(basePath, m.id, "CONTEXT");
         const hasDraftContext = !hasContext && !!resolveMilestoneFile(basePath, m.id, "CONTEXT-DRAFT");
+        const readiness = classifyMilestoneReadiness({
+            status: m.status,
+            hasContext,
+            hasDraftContext,
+            sliceCount: slices.length,
+        });
         if (!activeMilestoneFound) {
             const deps = m.depends_on;
             const depsUnmet = deps.some(dep => !completeMilestoneIds.has(dep));
@@ -403,9 +392,9 @@ async function buildRegistryAndFindActive(basePath, milestones, completeMileston
                 registry.push({ id: m.id, title, status: 'pending', dependsOn: deps });
                 continue;
             }
-            if (m.status === 'queued' && slices.length === 0 && !hasContext) {
+            if (readiness.kind === 'queued-shell') {
                 if (!firstDeferredQueuedShell) {
-                    firstDeferredQueuedShell = { id: m.id, title, deps, hasDraftContext };
+                    firstDeferredQueuedShell = { id: m.id, title, deps, hasDraftContext: readiness.hasDraftContext };
                 }
                 registry.push({ id: m.id, title, status: 'pending', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
                 continue;
@@ -417,7 +406,7 @@ async function buildRegistryAndFindActive(basePath, milestones, completeMileston
                 registry.push({ id: m.id, title, status: 'active', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
                 continue;
             }
-            if ((m.status === 'needs-discussion' && !hasContext) || hasDraftContext)
+            if (readinessNeedsDiscussion(readiness))
                 activeMilestoneHasDraft = true;
             activeMilestone = { id: m.id, title };
             activeMilestoneSlices = slices;

package/dist/resources/extensions/gsd/status-guards.js

@@ -1,16 +1,64 @@
 /**
- * Status predicates for GSD state-machine guards.
+ * Status predicates and the canonical status vocabulary for GSD state-machine
+ * guards (ADR-030).
  *
- * The DB stores status as free-form strings. Three values indicate
- * "closed": "complete" (canonical), "done" (legacy / alias),
- * "closed" (legacy/imported), and
- * "skipped" (user-directed skip via rethink or backtrack).
- * Every inline `status === "complete" || status === "done"` should
- * use isClosedStatus() instead.
+ * The DB column is free-form `string` so legacy/imported rows still load. Three
+ * raw values besides canonical "complete"/"skipped" indicate "closed": "done"
+ * (legacy alias), "closed" (legacy/imported), and "skipped" (user-directed skip
+ * via rethink or backtrack). `RAW_CLOSED_STATUSES` is the single source for both
+ * `isClosedStatus()` and the SQL terminal-status fragment
+ * (`db/sql-constants.ts` derives `TERMINAL_STATUS_SQL` from it), replacing the
+ * prior independent definitions.
+ *
+ * `toStatus()` is the single seam where a free-form string becomes the canonical
+ * `Status` vocabulary; the Status Transition Core writes canonical, so the store
+ * converges over time without a forced migration.
+ */
+/**
+ * Canonical, normalized entity-status vocabulary across milestones, slices, and
+ * tasks — the single source for both the `Status` type and the runtime
+ * membership set. The in-memory domain speaks `Status`; the DB column stays
+ * free-form.
+ */
+export const CANONICAL_STATUSES = [
+    "pending", "queued", "active", "parked", "in_progress", "blocked", "complete", "skipped", "deferred",
+];
+const CANONICAL_STATUS_SET = new Set(CANONICAL_STATUSES);
+/**
+ * Raw status values that mean a unit is closed — the single source of truth.
+ * Includes legacy/imported aliases ("done", "closed") alongside canonical
+ * "complete"/"skipped" because the DB column is free-form and older rows /
+ * imports still carry them. Order matters: `TERMINAL_STATUS_SQL` is derived
+ * from this array verbatim.
+ */
+export const RAW_CLOSED_STATUSES = ["complete", "done", "skipped", "closed"];
+const RAW_CLOSED_SET = new Set(RAW_CLOSED_STATUSES);
+/** Free-form aliases mapped to their canonical Status on read. */
+const ALIAS_TO_CANONICAL = {
+    done: "complete",
+    closed: "complete",
+    planned: "pending",
+    "in-progress": "in_progress",
+};
+/**
+ * Normalize a free-form DB status string into the canonical `Status`
+ * vocabulary. Maps known aliases (done/closed → complete, planned → pending,
+ * in-progress → in_progress). An unrecognized/legacy value is **quarantined** —
+ * preserved verbatim rather than silently remapped to a wrong canonical state —
+ * so reads never fail and reconciliation/telemetry can surface it.
  */
+export function toStatus(raw) {
+    const value = raw.trim();
+    if (CANONICAL_STATUS_SET.has(value))
+        return value;
+    const alias = ALIAS_TO_CANONICAL[value];
+    if (alias)
+        return alias;
+    return value;
+}
 /** Returns true when a milestone, slice, or task status indicates closure. */
 export function isClosedStatus(status) {
-    return status === "complete" || status === "done" || status === "skipped" || status === "closed";
+    return RAW_CLOSED_SET.has(status);
 }
 /** Returns true when a slice status indicates it was deferred by a decision. */
 export function isDeferredStatus(status) {

package/dist/resources/extensions/gsd/stop-notice.js

@@ -0,0 +1,57 @@
+// Project/App: gsd-pi
+// File Purpose: Stop Notice module — single owner of the auto/step-mode
+// stop/pause notice vocabulary. Both sides of the wire live here: the
+// formatters that produce the canonical prefixes (used by stopAuto/pauseAuto)
+// and the classifiers that recognize them (used by the headless host to pick
+// exit codes). Wording changes in this file keep emitter and detector in
+// lockstep; round-trip tests enforce it.
+/** A reason string of the form "Blocked: …" marks a blocked stop. */
+export function isBlockedStopReason(reason) {
+    return /^Blocked:\s*/i.test(reason ?? "");
+}
+/** Strip the "Blocked: " marker for display. */
+export function stopNoticeDisplayReason(reason) {
+    return (reason ?? "").replace(/^Blocked:\s*/i, "").trim();
+}
+export function stopNoticeKind(reason) {
+    return isBlockedStopReason(reason) ? "blocked" : "stopped";
+}
+/** Canonical stop-notice prefix: "Auto-mode blocked — reason" / "Auto-mode stopped". */
+export function formatStopNoticePrefix(reason) {
+    const displayReason = stopNoticeDisplayReason(reason);
+    const prefix = stopNoticeKind(reason) === "blocked" ? "Auto-mode blocked" : "Auto-mode stopped";
+    return displayReason ? `${prefix} — ${displayReason}` : prefix;
+}
+// ─── Classification (headless host side) ────────────────────────────────
+// The canonical lowercase prefixes the headless event loop recognizes in
+// notify messages. Emitters above and ad-hoc emitters elsewhere must start
+// their terminal notices with one of these.
+export const PAUSED_NOTICE_PREFIXES = ["auto-mode paused", "step-mode paused"];
+export const TERMINAL_NOTICE_PREFIXES = [
+    "auto-mode stopped",
+    "step-mode stopped",
+    "auto-mode complete",
+    "no active milestone",
+    "auto-mode idle",
+];
+/** Manual-resolution notices emitted before auto-mode can formally pause/stop. */
+export function isManualResolutionNotice(message) {
+    return (message.includes("resolve manually and re-run /gsd auto") ||
+        message.includes("resolve conflicts manually and run /gsd auto to resume") ||
+        message.includes("resolve and run /gsd auto to resume"));
+}
+export function isPauseNotice(message) {
+    return PAUSED_NOTICE_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+export function isTerminalNotice(message) {
+    return TERMINAL_NOTICE_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+/** Pauses that do not require operator intervention in headless mode. */
+export function isNonBlockingPauseNotice(message) {
+    return message.includes("idempotent advance: unit already active");
+}
+export function isBlockedNoticeMessage(message) {
+    return (message.includes("blocked:") ||
+        (isPauseNotice(message) && !isNonBlockingPauseNotice(message)) ||
+        isManualResolutionNotice(message));
+}

package/dist/resources/extensions/gsd/templates/plan.md

@@ -46,6 +46,13 @@
      For simple projects or scripts:
      - Executable verification commands (bash assertions, curl checks, etc.) are sufficient
 
+     For browser-facing web apps (React, Next, Vue, Vite, static HTML, etc.):
+     - Prefer `npx playwright test <spec>` in Verification when `@playwright/test` exists
+     - If Playwright is not set up yet, the first UI slice should add `playwright.config.ts`,
+       a minimal smoke spec (for example `e2e/smoke.spec.ts`), and a safe verify command
+     - Slice closeout UAT must declare `browser-executable` or `runtime-executable` — not
+       `artifact-driven` — when checks navigate to localhost or exercise the live UI
+
      If the project has no test framework and the work is non-trivial,
      the first task should set one up. A test runner costs 2 minutes
      and pays for itself immediately.

package/dist/resources/extensions/gsd/templates/project.md

@@ -20,6 +20,7 @@
 
 - **Complexity:** {{simple | complex}}
 - **Why:** {{one-line rationale citing the signals that decided it}}
+- **Web stack:** {{browser-facing framework or "not a web UI" — e.g. Next.js + Playwright, static HTML, N/A for CLI/API-only}}
 
 ## Current State
 

package/dist/resources/extensions/gsd/templates/roadmap.md

@@ -42,7 +42,7 @@
 - Contract verification: {{tests / shell verifiers / fixtures / artifact checks}}
 - Integration verification: {{real subsystem interaction that must be exercised, or none}}
 - Operational verification: {{service lifecycle / restart / reconnect / supervision / deploy-install behavior, or none}}
-- UAT / human verification: {{what needs real human judgment, or none}}
+- UAT / human verification: {{what needs real human judgment, or none — for web apps prefer browser-executable / runtime-executable Playwright checks over deferring UI proof to humans}}
 
 ## Milestone Definition of Done
 

package/dist/resources/extensions/gsd/templates/uat.md

@@ -5,9 +5,13 @@
 
 ## UAT Type
 
-- UAT mode: {{artifact-driven | live-runtime | human-experience | mixed}}
+- UAT mode: {{artifact-driven | browser-executable | runtime-executable | live-runtime | human-experience | mixed}}
 - Why this mode is sufficient: {{reason}}
 
+<!-- Web apps: never use artifact-driven when steps open a browser, navigate to localhost,
+     or capture screenshots. Use browser-executable (browser_* tools) or runtime-executable
+     (npx playwright test). Name dev-server preconditions below. -->
+
 ## Preconditions
 
 {{whatMustBeTrueBeforeTesting — server running, data seeded, etc.}}

package/dist/resources/extensions/gsd/tool-contract.js

@@ -4,6 +4,17 @@ import { resolveManifest, } from "./unit-context-manifest.js";
 import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
 import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
 import { WHOLE_FILE_OBSERVATION_MAX_BYTES, WHOLE_FILE_OBSERVATION_MAX_LINES, } from "./source-observations.js";
+export function compileUnitContextContract(unitType) {
+    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) {
     const manifest = resolveManifest(unitType);
     const surfaceContract = getUnitToolSurfaceContract(unitType);
@@ -25,6 +36,7 @@ export function compileUnitToolContract(unitType) {
             detail: `${unitType} has no closeout workflow tool`,
         };
     }
+    const promptContext = buildPromptContextContract(unitType, manifest);
     return {
         ok: true,
         contract: {
@@ -33,10 +45,8 @@ export function compileUnitToolContract(unitType) {
             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",
@@ -44,15 +54,49 @@ export function compileUnitToolContract(unitType) {
                 ...(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, manifest) {
+    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, sourceObservations) {
+    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, artifacts) {
+    return `${label}:${artifacts.length > 0 ? artifacts.join(",") : "none"}`;
+}
 function sourceObservationContractForUnit(unitType) {
     if (unitType !== "execute-task")
         return { mode: "none" };

package/dist/resources/extensions/gsd/tool-presentation-plan.js

@@ -1,7 +1,10 @@
 // Project/App: gsd-pi
 // File Purpose: Resolve phase-aware tool surfaces for GSD model presentations.
 import { RUN_UAT_BROWSER_TOOL_NAMES, RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_TOOL_PRESENTATION_PLAN_ID, RUN_UAT_WORKFLOW_TOOL_NAMES, } from "./unit-tool-contracts.js";
+import { toMcpToolName } from "./mcp-tool-name.js";
+import { createToolSurfaceSnapshot } from "./tool-surface-snapshot.js";
 import { uatTypeIncludesBrowser } from "./uat-policy.js";
+import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
 export { RUN_UAT_BROWSER_TOOL_NAMES, RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_TOOL_PRESENTATION_PLAN_ID, RUN_UAT_WORKFLOW_TOOL_NAMES, } from "./unit-tool-contracts.js";
 export const RUN_UAT_FORBIDDEN_TOOL_NAMES = [
     "edit",
@@ -21,43 +24,12 @@ export const RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES = [
     "Glob",
     "Grep",
 ];
-const WORKFLOW_ALIAS_TO_CANONICAL = {
-    gsd_save_decision: "gsd_decision_save",
-    gsd_update_requirement: "gsd_requirement_update",
-    gsd_save_requirement: "gsd_requirement_save",
-    gsd_save_summary: "gsd_summary_save",
-    gsd_generate_milestone_id: "gsd_milestone_generate_id",
-    gsd_milestone_plan: "gsd_plan_milestone",
-    gsd_slice_plan: "gsd_plan_slice",
-    gsd_task_plan: "gsd_plan_task",
-    gsd_slice_replan: "gsd_replan_slice",
-    gsd_complete_slice: "gsd_slice_complete",
-    gsd_milestone_complete: "gsd_complete_milestone",
-    gsd_milestone_validate: "gsd_validate_milestone",
-    gsd_roadmap_reassess: "gsd_reassess_roadmap",
-    gsd_complete_task: "gsd_task_complete",
-    gsd_reopen_task: "gsd_task_reopen",
-    gsd_reopen_slice: "gsd_slice_reopen",
-    gsd_reopen_milestone: "gsd_milestone_reopen",
-};
 export function canonicalWorkflowToolName(toolName) {
-    const mcp = parseMcpToolName(toolName);
-    const baseName = mcp?.tool ?? toolName;
-    return WORKFLOW_ALIAS_TO_CANONICAL[baseName] ?? baseName;
-}
-export function parseMcpToolName(toolName) {
-    if (!toolName.startsWith("mcp__"))
-        return null;
-    const toolSeparator = toolName.indexOf("__", "mcp__".length);
-    if (toolSeparator < 0)
-        return null;
-    return {
-        server: toolName.slice("mcp__".length, toolSeparator),
-        tool: toolName.slice(toolSeparator + 2),
-    };
+    return canonicalWorkflowSurfaceToolName(toolName);
 }
+export { parseMcpToolName } from "./mcp-tool-name.js";
 export function toWorkflowMcpToolName(serverName, toolName) {
-    return `mcp__${serverName}__${canonicalWorkflowToolName(toolName)}`;
+    return toMcpToolName(serverName, canonicalWorkflowToolName(toolName));
 }
 function dedupe(values) {
     return [...new Set(values)];
@@ -134,6 +106,14 @@ export function resolveToolPresentationPlan(options) {
             ? toWorkflowMcpToolName(workflowServerName, name)
             : name)
         : allowedToolNames;
+    const toolSurface = createToolSurfaceSnapshot({
+        source: "presentation-plan",
+        phase: options.phase,
+        modelFacingToolNames: options.availableToolNames ?? requested,
+        registeredToolNames: options.availableToolNames ?? requested,
+        scopedToolNames: allowedToolNames,
+        presentedToolNames,
+    });
     if (options.phase === "run-uat") {
         for (const forbidden of RUN_UAT_FORBIDDEN_TOOL_NAMES) {
             addBlockedTool(blockedToolNames, forbidden, "forbidden during run-uat");
@@ -148,5 +128,6 @@ export function resolveToolPresentationPlan(options) {
         blockedToolNames,
         aliases,
         diagnostics: [],
+        toolSurface,
     };
 }