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

package/dist/resources/extensions/gsd/prompts/guided-discuss-project.md

@@ -36,6 +36,8 @@ After the opening answer, classify project shape as **`simple`** or **`complex`*
 
 Persist the verdict through `gsd_summary_save` with `artifact_type: "PROJECT"` into `## Project Shape`; downstream `discuss-requirements`, `discuss-milestone`, and `discuss-slice` read the rendered projection.
 
+When the project is browser-facing (web app, SPA, static site with UI, Next/React/Vue, etc.), also record **`Web stack:`** under `## Project Shape` (framework + whether Playwright or browser UAT is expected). Downstream planning uses this to choose `browser-executable` / `runtime-executable` UAT instead of deferring UI proof to humans.
+
 ### Before deeper rounds
 
 Ground your questions in the **Preparation Context snapshot above** (stack, structure, greenfield/brownfield and framework signals) plus any prior `.planning/` or `.gsd/` artifacts — those are authoritative. **Do not survey the codebase** with `rg`/`find`/`scout` before asking; read a specific file only when a question's answer genuinely hinges on it.
@@ -103,7 +105,7 @@ Once the user confirms depth:
 
 1. Use the **Project** output template (inlined above).
 2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full project markdown as `content`; omit `milestone_id`. The tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`. Preserve the user's terms and framing.
-3. The `## Project Shape` section MUST contain `**Complexity:** simple` or `**Complexity:** complex` (matching the verdict you announced) plus a one-line `**Why:**` rationale. Downstream stages read this line.
+3. The `## Project Shape` section MUST contain `**Complexity:** simple` or `**Complexity:** complex` (matching the verdict you announced) plus a one-line `**Why:**` rationale. For browser-facing projects, also include `**Web stack:**` (framework and expected browser/Playwright UAT approach). Downstream stages read these lines.
 4. The `## Capability Contract` section MUST reference `.gsd/REQUIREMENTS.md` — that file does not yet exist; the next stage (`discuss-requirements`) will produce it.
 5. The `## Milestone Sequence` MUST list at least M001 with title and one-liner. Subsequent milestones may be listed as known intents; they will be elaborated in their own discuss-milestone stages.
 6. Do NOT use `artifact_type: "CONTEXT"` and do NOT pass `milestone_id: "PROJECT"`; that creates a fake milestone named PROJECT.

package/dist/resources/extensions/gsd/prompts/plan-milestone.md

@@ -47,6 +47,8 @@ If milestone research is inlined, trust it and skip redundant exploration. If fi
 
 Narrate decomposition reasoning in complete sentences: grouping, risk order, verification strategy.
 
+**Web apps:** when inlined Web App UAT guidance is present, set milestone `Verification Classes` → UAT to browser-observable acceptance (Playwright spec or `browser_*` checks). Order an early slice to add Playwright smoke scaffolding when the dependency is missing.
+
 Then:
 1. Use the **Roadmap** output template from the inlined context above
 2. {{skillActivation}}

package/dist/resources/extensions/gsd/prompts/plan-slice.md

@@ -41,10 +41,11 @@ If slice research is inlined, trust its architectural findings, but verify every
 3. Use the inlined Output Template sections already present in this prompt. Do not read template files from disk.
 4. {{skillActivation}} Record expected executor skills in each task plan's `skills_used` frontmatter.
 5. Define slice verification before tasks. Non-trivial slices need real tests or executable assertions; boundary contracts need contract-exercising checks. Tests must not read .gitignore/gitignored paths such as `.gsd/`, `.planning/`, or `.audits/`.
+   **Web apps:** when inlined Web App UAT guidance is present, follow it — add Playwright smoke scaffolding on the first UI slice if missing, name localhost preconditions, and plan verification commands that match browser-capable UAT modes at slice closeout.
 6. Include Threat Surface (Q3), Requirement Impact (Q4), proof level, observability, integration closure, Failure Modes (Q5), Load Profile (Q6), and Negative Tests (Q7) only where applicable.
 7. Right-size tasks. Simple slices can be one task; split only when context, ownership, or verification boundaries justify it.
 8. Task `verify` commands must be safe, simple commands. Do not use shell pipes, redirects, semicolons, backticks, command substitution, output trimming, or grep regex alternation with `|`. If multiple checks are needed, create a small test file and run it with `node --test` or a package test script, or use separate simple commands joined only with `&&`. For absence checks, verify a pattern does not exist with `! grep -q 'pattern' file` or `! rg -q 'pattern' file`; do not use `grep -c` or `rg -c` to assert zero matches because count commands exit 1 when they find zero matches, and the verification gate treats that as failure.
-9. Each task needs the exact `gsd_plan_slice.tasks[]` shape: `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. `description` should contain the Why / Do / Done-when narrative. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even when there is only one path (for example, `"inputs": ["src/index.ts"]`, never `"inputs": "src/index.ts"`). Use paths relative to `{{workingDirectory}}`; do not put absolute paths to the original checkout or any directory outside `{{workingDirectory}}` in `files`, `inputs`, `expectedOutput`, or verification commands. **`expectedOutput` must only list files the task actually creates or overwrites on disk.** Do NOT include files the task merely reads, verifies, tests, or describes — those belong in `inputs`, `verify`, `description`, or slice success criteria. If a task is a pure verification or test task that produces no new files, `expectedOutput` must be `[]`; if it writes a test-result log or assertion output file, list only that concrete file path. A file that does not yet exist on disk and is needed as an `input` must be produced by an earlier task's `expectedOutput` — if no prior task creates it, add a task before this one that does.
+9. Each task needs the exact `gsd_plan_slice.tasks[]` shape: `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. `description` should contain the Why / Do / Done-when narrative. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even when there is only one path (for example, `"inputs": ["src/index.ts"]`, never `"inputs": "src/index.ts"`). Use paths relative to `{{workingDirectory}}`; do not put absolute paths to the original checkout or any directory outside `{{workingDirectory}}` in `files`, `inputs`, `expectedOutput`, or verification commands. **`expectedOutput` must only list files the task actually creates or overwrites on disk.** Do NOT include files the task merely reads, verifies, tests, or describes — those belong in `inputs`, `verify`, `description`, or slice success criteria. If a task is a pure verification or test task that produces no new files, `expectedOutput` must be `[]`; if it writes a test-result log or assertion output file, list only that concrete file path. A file that does not yet exist on disk and is needed as an `input` must be produced by an earlier task's `expectedOutput` — if no prior task creates it, add a task before this one that does. Never list GSD planning artifacts — anything under `.gsd/`, `.planning/`, or `.audits/`, or artifact names like `M001-CONTEXT.md` / `S01-PLAN.md` — in `inputs`, `files`, or `expectedOutput`: their content is preloaded as context, and they are written by workflow tools, not by tasks.
 10. Persist with `gsd_plan_slice` using `milestoneId`, `sliceId`, `goal`, optional `successCriteria`/`proofLevel`/`integrationClosure`/`observabilityImpact`, and `tasks`. `gsd_plan_slice` handles task persistence transactionally and renders `{{outputPath}}` plus task plans; do not call `gsd_plan_task`. The DB-backed tool is the canonical write path. Do **not** rely on direct `PLAN.md` writes as the source of truth.
 11. Self-audit before finishing: goal/demo closure, requirement coverage, deliverable coverage audit (cross-check every file listed in CONTEXT.md `## Scope` / `### In Scope` against task `files` or `expectedOutput`), locked decisions, concrete paths, dependency order, wiring, scope size, proof truthfulness, feature completeness, and quality gates. Quality gates: non-trivial slices/tasks include specific Q3-Q7 coverage where applicable.
 12. If planning creates structural decisions, call `gsd_decision_save` for each; the tool persists the decision and regenerates `.gsd/DECISIONS.md`.

package/dist/resources/extensions/gsd/prompts/refine-slice.md

@@ -63,8 +63,9 @@ Then:
    - `{{taskPlanTemplatePath}}`
 2. {{skillActivation}} Record the installed skills you expect executors to use in each task plan's `skills_used` frontmatter.
 3. Define slice-level verification: the objective stopping condition. Plan real test files with real assertions; for simple slices, executable commands are fine.
+   **Web apps:** when inlined Web App UAT guidance is present, follow it for Playwright scaffolding and browser-capable verification commands.
 4. For non-trivial slices, plan observability / proof level / integration closure, threat surface, and requirement impact. Omit entirely for simple slices.
-5. Decompose the slice into tasks that fit one context window each. Every task passed to `gsd_plan_slice` must use the exact keys `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. Put Why / Do / Done-when detail in `description`. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even for one path (for example, `"expectedOutput": ["src/index.ts"]`, never `"expectedOutput": "src/index.ts"`). `expectedOutput` is path-only: list only files the task creates or overwrites, and use `[]` for pure verification tasks.
+5. Decompose the slice into tasks that fit one context window each. Every task passed to `gsd_plan_slice` must use the exact keys `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. Put Why / Do / Done-when detail in `description`. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even for one path (for example, `"expectedOutput": ["src/index.ts"]`, never `"expectedOutput": "src/index.ts"`). `expectedOutput` is path-only: list only files the task creates or overwrites, and use `[]` for pure verification tasks. Never list GSD planning artifacts — anything under `.gsd/`, `.planning/`, or `.audits/`, or artifact names like `M001-CONTEXT.md` / `S01-PLAN.md` — in `inputs`, `files`, or `expectedOutput`: their content is preloaded as context, and they are written by workflow tools, not by tasks.
 6. **Persist planning state through `gsd_plan_slice`.** Call it with the full payload. The tool writes to the DB and renders `{{outputPath}}` and `{{slicePath}}/tasks/T##-PLAN.md` automatically. Do NOT rely on direct `PLAN.md` writes.
 7. **Self-audit the plan.** If every task were completed exactly as written, the slice goal/demo should be true. Every must-have maps to a task. Inputs and Expected Output are backtick-wrapped file paths.
 8. If refinement produced structural decisions that diverge from the sketch, call `gsd_decision_save` for each; the tool persists the decision and regenerates `.gsd/DECISIONS.md`.

package/dist/resources/extensions/gsd/prompts/replan-slice.md

@@ -34,7 +34,7 @@ Consider these captures when rewriting the remaining tasks — they represent th
 
 1. Use the inlined blocker summary excerpt first. Read the full blocker task summary only if the excerpt is absent, marked truncated, or lacks the specific blocker evidence needed to replan.
 2. Analyze the remaining `[ ]` tasks in the slice plan. Determine which are still valid, which need modification, and which should be replaced.
-3. **Persist replan state through `gsd_replan_slice`.** Call it with: `milestoneId`, `sliceId`, `blockerTaskId`, `blockerDescription`, `whatChanged`, `updatedTasks` (array of task objects with taskId, title, description, estimate, files, verify, inputs, expectedOutput), `removedTaskIds` (array of task ID strings). The tool structurally enforces preservation of completed tasks, writes replan history to the DB, re-renders `{{planPath}}`, and renders `{{replanPath}}`. Preserve or update the Threat Surface and Requirement Impact sections if the replan changes the slice's security posture or requirement coverage.
+3. **Persist replan state through `gsd_replan_slice`.** Call it with: `milestoneId`, `sliceId`, `blockerTaskId`, `blockerDescription`, `whatChanged`, `updatedTasks` (array of task objects with taskId, title, description, estimate, files, verify, inputs, expectedOutput), `removedTaskIds` (array of task ID strings). Never list GSD planning artifacts — anything under `.gsd/`, `.planning/`, or `.audits/`, or artifact names like `M001-CONTEXT.md` / `S01-PLAN.md` — in `inputs`, `files`, or `expectedOutput`: their content is preloaded as context, and they are written by workflow tools, not by tasks. The tool structurally enforces preservation of completed tasks, writes replan history to the DB, re-renders `{{planPath}}`, and renders `{{replanPath}}`. Preserve or update the Threat Surface and Requirement Impact sections if the replan changes the slice's security posture or requirement coverage.
 4. If any incomplete task had a `T0x-PLAN.md`, remove or rewrite it to match the new task description.
 5. Do not commit manually — the system auto-commits your changes after this unit completes.
 

package/dist/resources/extensions/gsd/prompts/system.md

@@ -158,7 +158,7 @@ Fix root causes, not symptoms. If applying temporary mitigation, label it and pr
 - State uncertainty plainly: "Not sure this handles X - testing it." No performed confidence, no hedging paragraphs.
 - All user-visible narration must be grammatical English. Do not emit compressed planner notes like "Need inspect X". If it fits a commit comment or standup note, it is acceptable.
 - When debugging, stay curious. Problems are puzzles. Say what's interesting about the failure before reaching for fixes.
-- After completing a task, give a brief summary and 2-4 numbered next-step options; last option is always "Other". Omit the list for strict output formats.
+- After completing a task, give a brief summary and 2-4 numbered next-step options; last option is always "Other". Omit the list for strict output formats, or when the active workflow prompt already ends with its own explicit "Next steps:" handoff block — in that case follow the workflow's handoff and do not add a second list.
 
   If any next step is destructive/outward-facing, present it via `ask_user_questions` and wait for the user's answer before execution. Do not execute a next-step item from a prior plain-text numbered list without fresh confirmation.
 

package/dist/resources/extensions/gsd/provider-error-guidance.js

@@ -1,5 +1,6 @@
 /**
  * Actionable remediation hints when auto-mode pauses on provider/model errors.
+ * Render with formatGuidance from the Guidance module.
  */
 /** Map auto unit types to the `models:` key in PREFERENCES.md. */
 export function unitTypeToPrefsPhaseKey(unitType) {
@@ -91,8 +92,3 @@ export function resolveProviderErrorGuidance(input) {
     steps.push("Run /gsd next to resume the paused unit.");
     return { summary, steps };
 }
-/** Flatten guidance into a pause banner / notification string. */
-export function formatProviderErrorGuidance(guidance) {
-    const numbered = guidance.steps.map((step, index) => `${index + 1}. ${step}`).join("\n");
-    return `${guidance.summary}\n\n${numbered}`;
-}

package/dist/resources/extensions/gsd/provider-payload-policy.js

@@ -0,0 +1,83 @@
+/**
+ * Provider Payload Policy - ordered shaping of provider request payloads.
+ *
+ * The order is intentional:
+ * 1. observation budgeting masks old tool results in auto-mode,
+ * 2. display truncation caps tool-result text for every mode,
+ * 3. the protected Source Context Block is appended after truncation,
+ * 4. supported models receive the configured service tier.
+ */
+import { createObservationMask, createResponsesInputObservationMask, truncateContextResultMessages, truncateResponsesInputResultItems, } from "./context-masker.js";
+import { getSourceObservationStore, isAutoActive } from "./auto-runtime-state.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { getEffectiveServiceTier, supportsServiceTier } from "./service-tier.js";
+import { injectSourceContextBlockIntoPayload } from "./source-observations.js";
+const DEFAULT_OBSERVATION_MASK_TURNS = 8;
+const DEFAULT_TOOL_RESULT_MAX_CHARS = 800;
+export const DEFAULT_PROVIDER_PAYLOAD_POLICY_DEPS = {
+    isAutoActive,
+    loadContextManagementConfig: () => loadEffectiveGSDPreferences()?.preferences.context_management,
+    renderSourceContextBlock: () => getSourceObservationStore().renderActiveBlock(),
+    getEffectiveServiceTier,
+    supportsServiceTier,
+};
+export function applyProviderPayloadPolicy({ payload, modelId, deps: overrides, }) {
+    const deps = { ...DEFAULT_PROVIDER_PAYLOAD_POLICY_DEPS, ...overrides };
+    try {
+        applyContextManagement(payload, deps);
+    }
+    catch {
+        // Provider payload shaping should not block a request when optional
+        // context management preferences or adapters fail.
+    }
+    try {
+        applySourceContextBlock(payload, deps);
+    }
+    catch {
+        // Source observations are opportunistic; execution can continue without
+        // an injected block.
+    }
+    applyServiceTier(payload, modelId, deps);
+    return payload;
+}
+function applyContextManagement(payload, deps) {
+    const config = deps.loadContextManagementConfig();
+    applyObservationBudget(payload, config, deps.isAutoActive());
+    applyDisplayTruncation(payload, config);
+}
+function applyObservationBudget(payload, config, autoActive) {
+    if (!autoActive || config?.observation_masking === false)
+        return;
+    const keepTurns = config?.observation_mask_turns ?? DEFAULT_OBSERVATION_MASK_TURNS;
+    if (Array.isArray(payload.messages)) {
+        payload.messages = createObservationMask(keepTurns)(payload.messages);
+    }
+    if (Array.isArray(payload.input)) {
+        payload.input = createResponsesInputObservationMask(keepTurns)(payload.input);
+    }
+}
+function applyDisplayTruncation(payload, config) {
+    const maxChars = config?.tool_result_max_chars ?? DEFAULT_TOOL_RESULT_MAX_CHARS;
+    if (Array.isArray(payload.messages)) {
+        payload.messages = truncateContextResultMessages(payload.messages, maxChars);
+    }
+    if (Array.isArray(payload.input)) {
+        payload.input = truncateResponsesInputResultItems(payload.input, maxChars);
+    }
+}
+function applySourceContextBlock(payload, deps) {
+    if (!deps.isAutoActive())
+        return;
+    const sourceContextBlock = deps.renderSourceContextBlock();
+    if (!sourceContextBlock)
+        return;
+    Object.assign(payload, injectSourceContextBlockIntoPayload(payload, sourceContextBlock));
+}
+function applyServiceTier(payload, modelId, deps) {
+    if (!modelId)
+        return;
+    const tier = deps.getEffectiveServiceTier();
+    if (!tier || !deps.supportsServiceTier(modelId))
+        return;
+    payload.service_tier = tier;
+}

package/dist/resources/extensions/gsd/provider-switch-observer.js

@@ -92,7 +92,7 @@ function emitAudit(report) {
 }
 function emitNotification(report) {
     try {
-        appendNotification(summarize(report), "warning", "workflow-logger");
+        appendNotification(summarize(report), "warning", "workflow-logger", { kind: "provider-switch" });
     }
     catch {
         // Notification persistence is best-effort.

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

@@ -0,0 +1,87 @@
+// Project/App: gsd-pi
+// File Purpose: Publication module — push and draft-PR creation for a merged milestone (ADR-034).
+//
+// Publication is distinct from the merge verb: merging a milestone branch is a
+// Worktree Lifecycle concern (worktree, branch, lease, stash discipline);
+// publication needs only the resulting commit, a remote, and preferences.
+// Extracted from the tail of `mergeMilestoneToMain` (auto-worktree.ts) so it is
+// testable without a merge fixture and reachable from any closeout path.
+//
+// Publication failure is non-fatal to a completed local merge: every failure is
+// logged and reported in the result, never thrown.
+import { execFileSync } from "node:child_process";
+import { buildPullRequestEvidence, createDraftPullRequestFromEvidence, } from "./pull-request-process.js";
+import { logWarning } from "./workflow-logger.js";
+export function gitRemoteExists(basePath, remote) {
+    try {
+        execFileSync("git", ["remote", "get-url", remote], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Publish a merged milestone per preferences: push the integration branch
+ * (auto-push, suppressed when auto-PR owns the remote interaction) and/or
+ * push the milestone branch and open a draft PR (auto-PR).
+ */
+export function publishMilestone(request) {
+    const result = { pushed: false, prCreated: false };
+    if (request.nothingToCommit)
+        return result;
+    const { basePath, prefs } = request;
+    const remote = prefs.remote ?? "origin";
+    if (prefs.autoPush && !prefs.autoPr && gitRemoteExists(basePath, remote)) {
+        try {
+            execFileSync("git", ["push", remote, request.integrationBranch], {
+                cwd: basePath,
+                stdio: ["ignore", "pipe", "pipe"],
+                encoding: "utf-8",
+            });
+            result.pushed = true;
+        }
+        catch (err) {
+            // Push failure is non-fatal
+            logWarning("worktree", `git push failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // #2302: PR creation is not gated on pushed/auto-push.
+    if (prefs.autoPr && gitRemoteExists(basePath, remote)) {
+        try {
+            // Push the milestone branch to remote first
+            execFileSync("git", ["push", remote, request.milestoneBranch], {
+                cwd: basePath,
+                stdio: ["ignore", "pipe", "pipe"],
+                encoding: "utf-8",
+            });
+            const prEvidence = buildPullRequestEvidence({
+                milestoneId: request.milestoneId,
+                milestoneTitle: request.milestoneTitle,
+                changeType: "feat",
+                summaries: [...request.sliceSummaries],
+                testsRun: ["Auto-created after milestone merge. Run `npm run verify:merge` before marking this draft ready."],
+                rollbackNotes: ["Close the draft PR or revert the merge commit if review finds a behavior regression."],
+                how: "Generated by git.auto_pr after the milestone branch was pushed and merged locally.",
+            });
+            const prUrl = createDraftPullRequestFromEvidence(basePath, request.milestoneId, prEvidence, {
+                head: request.milestoneBranch,
+                base: prefs.prTargetBranch ?? request.integrationBranch,
+            });
+            if (!prUrl) {
+                throw new Error("gh pr create returned no URL");
+            }
+            result.prCreated = true;
+            result.prUrl = prUrl;
+        }
+        catch (err) {
+            // PR creation failure is non-fatal — gh may not be installed or authenticated
+            logWarning("worktree", `PR creation failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return result;
+}

package/dist/resources/extensions/gsd/pull-request-process.js

@@ -0,0 +1,13 @@
+// Project/App: gsd-pi
+// File Purpose: Process-level pull request policy for GSD-generated PRs.
+import { createDraftPR } from "./git-service.js";
+import { buildPrEvidence, } from "./pr-evidence.js";
+export function buildPullRequestEvidence(input) {
+    return buildPrEvidence({
+        ...input,
+        aiAssisted: false,
+    });
+}
+export function createDraftPullRequestFromEvidence(basePath, milestoneId, evidence, options, deps = { createDraftPR }) {
+    return deps.createDraftPR(basePath, milestoneId, evidence.title, evidence.body, options);
+}

package/dist/resources/extensions/gsd/quality-gate-closure.js

@@ -0,0 +1,109 @@
+// Project/App: gsd-pi
+// File Purpose: Canonical quality-gate closure from durable DB and artifact evidence.
+import { existsSync, readFileSync } from "node:fs";
+import { extractSection } from "./files.js";
+import { getGateDefinition } from "./gate-registry.js";
+import { getMilestoneSlices, getPendingGates, saveGateResult } from "./gsd-db.js";
+import { resolveSliceFile, resolveTaskFile } from "./paths.js";
+const GATE_SECTION_HEADINGS = {
+    Q3: ["Threat Surface", "Abuse Surface"],
+    Q4: ["Requirement Impact", "Broken Promises"],
+    Q5: ["Failure Modes"],
+    Q6: ["Load Profile"],
+    Q7: ["Negative Tests"],
+    Q8: ["Operational Readiness"],
+};
+function readFile(path) {
+    if (!path || !existsSync(path))
+        return null;
+    return readFileSync(path, "utf-8");
+}
+function firstSection(content, gateId) {
+    if (!content)
+        return null;
+    for (const heading of GATE_SECTION_HEADINGS[gateId] ?? []) {
+        const section = extractSection(content, heading);
+        if (section)
+            return section;
+    }
+    return null;
+}
+function evidenceArtifactContent(row, basePath) {
+    const def = getGateDefinition(row.gate_id);
+    switch (def?.ownerTurn) {
+        case "gate-evaluate":
+            return readFile(resolveSliceFile(basePath, row.milestone_id, row.slice_id, "PLAN"));
+        case "execute-task":
+            return readFile(resolveTaskFile(basePath, row.milestone_id, row.slice_id, row.task_id, "SUMMARY"));
+        case "complete-slice":
+            return readFile(resolveSliceFile(basePath, row.milestone_id, row.slice_id, "SUMMARY"));
+        default:
+            return null;
+    }
+}
+function closureEvidence(row, options) {
+    const def = getGateDefinition(row.gate_id);
+    if (!def)
+        return null;
+    if (def.ownerTurn === "validate-milestone" && options.milestoneValidationPassed) {
+        return {
+            verdict: "pass",
+            rationale: `${def.promptSection} covered by passing milestone validation`,
+            findings: "",
+        };
+    }
+    if (!options.artifactBasePath)
+        return null;
+    const section = firstSection(evidenceArtifactContent(row, options.artifactBasePath), row.gate_id);
+    if (section) {
+        return {
+            verdict: "pass",
+            rationale: `${def.promptSection} evidence found in durable artifact`,
+            findings: section,
+        };
+    }
+    if (!options.milestoneValidationPassed)
+        return null;
+    return {
+        verdict: "omitted",
+        rationale: `${def.promptSection} has no durable artifact section; milestone validation passed`,
+        findings: "",
+    };
+}
+function closeGate(row, evidence) {
+    saveGateResult({
+        milestoneId: row.milestone_id,
+        sliceId: row.slice_id,
+        gateId: row.gate_id,
+        taskId: row.task_id,
+        verdict: evidence.verdict,
+        rationale: evidence.rationale,
+        findings: evidence.findings,
+    });
+}
+export function closeQualityGatesFromEvidence(milestoneId, options = {}) {
+    const repaired = [];
+    const unresolved = [];
+    for (const slice of getMilestoneSlices(milestoneId)) {
+        const sliceId = slice.id;
+        for (const row of getPendingGates(milestoneId, sliceId)) {
+            if (!getGateDefinition(row.gate_id)) {
+                unresolved.push(row);
+                continue;
+            }
+            const evidence = closureEvidence(row, options);
+            if (!evidence) {
+                unresolved.push(row);
+                continue;
+            }
+            closeGate(row, evidence);
+            repaired.push({
+                gateId: row.gate_id,
+                sliceId: row.slice_id,
+                ...(row.task_id ? { taskId: row.task_id } : {}),
+                verdict: evidence.verdict,
+            });
+        }
+    }
+    return { repaired, unresolved };
+}

package/dist/resources/extensions/gsd/question-transport.js

@@ -0,0 +1,86 @@
+// Project/App: gsd-pi
+// File Purpose: Resolve how workflow units should ask the user for input.
+import { parseMcpToolName, toMcpToolName } from "./mcp-tool-name.js";
+function isWorkflowMcpServerName(serverName) {
+    const normalized = serverName.toLowerCase();
+    return normalized === "gsd" || normalized.includes("workflow");
+}
+export function usesWorkflowMcpTransport(authMode, baseUrl) {
+    return authMode === "externalCli" && typeof baseUrl === "string" && baseUrl.startsWith("local://");
+}
+export function hasAskUserQuestionsTool(activeTools) {
+    return activeTools.some((toolName) => {
+        if (toolName === "ask_user_questions")
+            return true;
+        const mcp = parseMcpToolName(toolName);
+        if (!mcp)
+            return false;
+        if (mcp.toolName === "ask_user_questions")
+            return true;
+        return mcp.toolName === "*" && isWorkflowMcpServerName(mcp.serverName);
+    });
+}
+function workflowMcpStructuredQuestionsEnabled(env = process.env) {
+    const value = env.GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS?.trim().toLowerCase();
+    return value !== "0" && value !== "false" && value !== "off";
+}
+export function resolveQuestionTransport(options) {
+    const questionToolAvailable = hasAskUserQuestionsTool(options.activeTools);
+    const usesWorkflowMcp = usesWorkflowMcpTransport(options.authMode, options.baseUrl);
+    if (!questionToolAvailable) {
+        return {
+            structuredQuestionsAvailable: "false",
+            questionToolAvailable,
+            usesWorkflowMcp,
+            reason: "question-tool-missing",
+        };
+    }
+    if (options.authMode === "externalCli" && !workflowMcpStructuredQuestionsEnabled(options.env)) {
+        return {
+            structuredQuestionsAvailable: "false",
+            questionToolAvailable,
+            usesWorkflowMcp,
+            reason: "workflow-mcp-disabled",
+        };
+    }
+    return {
+        structuredQuestionsAvailable: "true",
+        questionToolAvailable,
+        usesWorkflowMcp,
+        reason: "question-tool-available",
+    };
+}
+export function supportsStructuredQuestions(activeTools, options = {}) {
+    return resolveQuestionTransport({
+        ...options,
+        activeTools,
+    }).structuredQuestionsAvailable === "true";
+}
+export function resolveWorkflowQuestionToolSurface(options) {
+    const questionToolName = options.workflowServerName && !options.workflowExplicitlyBlocked
+        ? toMcpToolName(options.workflowServerName, "ask_user_questions")
+        : undefined;
+    const activeTools = [
+        ...options.exactWorkflowMcpTools,
+        ...options.workflowMcpTools,
+        ...(questionToolName ? [questionToolName] : []),
+    ];
+    const transport = resolveQuestionTransport({
+        activeTools,
+        authMode: "externalCli",
+        baseUrl: "local://claude-code",
+        env: options.env,
+    });
+    const exactQuestionToolAllowed = !!questionToolName && options.exactWorkflowMcpTools.includes(questionToolName);
+    const workflowQuestionsEnabled = transport.structuredQuestionsAvailable === "true" &&
+        (options.workflowMcpTools.length > 0 || exactQuestionToolAllowed);
+    const disallowedTools = options.workflowServerName && transport.questionToolAvailable && !workflowQuestionsEnabled
+        ? [toMcpToolName(options.workflowServerName, "ask_user_questions")]
+        : [];
+    return {
+        ...transport,
+        questionToolName,
+        workflowQuestionsEnabled,
+        disallowedTools,
+    };
+}

package/dist/resources/extensions/gsd/recovery-classification.js

@@ -1,7 +1,10 @@
 // Project/App: gsd-pi
 // File Purpose: ADR-015 Recovery Classification module for runtime failure taxonomy.
+import { isToolUnavailableError } from "./auto-tool-tracking.js";
 import { classifyError, isTransient } from "./error-classifier.js";
+import { recoveryRemediation } from "./guidance.js";
 import { ReconciliationFailedError } from "./state-reconciliation.js";
+import { IllegalPhaseTransitionError } from "./state-transition-matrix.js";
 export function classifyFailure(input) {
     const message = errorMessage(input.error);
     // ADR-017: ReconciliationFailedError is a typed throw from the State
@@ -9,96 +12,47 @@ export function classifyFailure(input) {
     // failureKind so the taxonomy stays consistent.
     const failureKind = input.error instanceof ReconciliationFailedError
         ? "reconciliation-drift"
-        : input.failureKind ?? inferFailureKind(message);
-    switch (failureKind) {
-        case "tool-schema":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Tool schema failure${unitSuffix(input)}: ${message}`,
-                exitReason: "tool-schema",
-                remediation: "Fix the Unit Tool Contract or tool schema before retrying.",
-            };
-        case "tool-contract":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Tool Contract failure${unitSuffix(input)}: ${message}`,
-                exitReason: "tool-contract",
-                remediation: "Fix the Unit Tool Contract or prompt so the Unit is only asked to use tools owned by its phase.",
-            };
-        case "deterministic-policy":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Deterministic policy failure${unitSuffix(input)}: ${message}`,
-                exitReason: "deterministic-policy",
-                remediation: "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
-            };
-        case "lifecycle-progression":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Lifecycle progression failure${unitSuffix(input)}: ${message}`,
-                exitReason: "lifecycle-progression",
-                remediation: "Route to the required owning Unit or restore the missing artifact before advancing lifecycle state.",
-            };
-        case "stale-worker":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Stale worker failure${unitSuffix(input)}: ${message}`,
-                exitReason: "stale-worker",
-                remediation: "Clear or reconcile the stale worker before dispatching another Unit.",
-            };
-        case "worktree-invalid":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Worktree invalid${unitSuffix(input)}: ${message}`,
-                exitReason: "worktree-invalid",
-                remediation: "Repair or recreate the milestone worktree before launching source-writing Units.",
-            };
-        case "verification-drift":
-            return {
-                failureKind,
-                action: "escalate",
-                reason: `Verification drift${unitSuffix(input)}: ${message}`,
-                exitReason: "verification-drift",
-                remediation: "Inspect the verification artifact and reconcile the state snapshot before resuming.",
-            };
-        case "reconciliation-drift":
-            return {
-                failureKind,
-                action: "escalate",
-                reason: `Reconciliation drift${unitSuffix(input)}: ${message}`,
-                exitReason: "reconciliation-drift",
-                remediation: "Inspect the persistent or repair-failed drift kinds reported by the State Reconciliation Module before resuming.",
-            };
-        case "provider": {
-            const providerClass = classifyError(message, input.retryAfterMs);
-            return {
-                failureKind,
-                action: isTransient(providerClass) ? "retry" : "escalate",
-                reason: message,
-                exitReason: `provider-${providerClass.kind}`,
-                remediation: isTransient(providerClass)
-                    ? "Retry after the provider/network condition clears."
-                    : "Inspect provider credentials, model entitlement, or request shape.",
-                providerClass: providerClass.kind,
-            };
-        }
-        case "runtime-unknown":
-            return {
-                failureKind,
-                action: "escalate",
-                reason: message,
-                exitReason: "runtime-unknown",
-                remediation: "Inspect the runtime error and add a dedicated classification if it is repeatable.",
-            };
+        : input.error instanceof IllegalPhaseTransitionError
+            ? "illegal-transition"
+            : input.failureKind ?? inferFailureKind(message);
+    if (failureKind === "provider") {
+        const providerClass = classifyError(message, input.retryAfterMs);
+        const transient = isTransient(providerClass);
+        return {
+            failureKind,
+            action: transient ? "retry" : "escalate",
+            reason: message,
+            exitReason: `provider-${providerClass.kind}`,
+            remediation: recoveryRemediation(transient ? "provider-transient" : "provider-permanent"),
+            providerClass: providerClass.kind,
+        };
     }
+    const { action, label } = FAILURE_TAXONOMY[failureKind];
+    return {
+        failureKind,
+        action,
+        reason: label ? `${label}${unitSuffix(input)}: ${message}` : message,
+        exitReason: failureKind,
+        remediation: recoveryRemediation(failureKind),
+    };
 }
+/** Per-kind action and reason label. Remediation lives in the Guidance module. */
+const FAILURE_TAXONOMY = {
+    "tool-schema": { action: "stop", label: "Tool schema failure" },
+    "tool-contract": { action: "stop", label: "Tool Contract failure" },
+    "tool-unavailable": { action: "retry", label: "Tool unavailable" },
+    "deterministic-policy": { action: "stop", label: "Deterministic policy failure" },
+    "lifecycle-progression": { action: "stop", label: "Lifecycle progression failure" },
+    "stale-worker": { action: "stop", label: "Stale worker failure" },
+    "worktree-invalid": { action: "stop", label: "Worktree invalid" },
+    "verification-drift": { action: "escalate", label: "Verification drift" },
+    "reconciliation-drift": { action: "escalate", label: "Reconciliation drift" },
+    "illegal-transition": { action: "escalate", label: "Illegal phase transition" },
+    "runtime-unknown": { action: "escalate", label: null },
+};
 function inferFailureKind(message) {
+    if (isToolUnavailableError(message))
+        return "tool-unavailable";
     if (/tool contract|auto-unit tool scope|phase-boundary gate|not permitted.*own/i.test(message))
         return "tool-contract";
     if (/lifecycle progression|required artifact|missing .*assessment|missing .*closeout|cannot legally (?:advance|progress)/i.test(message))