@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.5457a158

package/dist/resources/extensions/gsd/pre-execution-checks.js

@@ -20,6 +20,7 @@ import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { isAbsolute, relative, resolve } from "node:path";
 import { validateVerificationCommand } from "./verification-gate.js";
+import { FRAMEWORK_METADATA_DIRS, PLANNING_ARTIFACT_NAME_RE } from "./paths.js";
 const NPM_COMMAND = process.platform === "win32" ? "npm.cmd" : "npm";
 function inputExistsOnDisk(normalizedFile, basePath, context) {
     if (existsSync(resolve(basePath, normalizedFile)))
@@ -510,6 +511,10 @@ export function checkFilePathConsistency(tasks, basePath, context) {
                 continue;
             if (!shouldValidateInputAsPath(file))
                 continue;
+            // Planning-artifact references are owned by checkPlanningArtifactReferences,
+            // which reports a precise removal message instead of "doesn't exist".
+            if (isPlanningArtifactReference(file, basePath, context))
+                continue;
             // Normalize path for consistent comparison
             const normalizedFile = toComparisonPath(file, basePath);
             if (containsGlobPattern(normalizedFile))
@@ -546,6 +551,71 @@ export function checkFilePathConsistency(tasks, basePath, context) {
     }
     return results;
 }
+// ─── Planning Artifact Reference Check ───────────────────────────────────────
+function isFrameworkMetadataPath(normalizedFile) {
+    return normalizedFile.split("/").some((segment) => FRAMEWORK_METADATA_DIRS.includes(segment.toLowerCase()));
+}
+/**
+ * True when a task IO entry references a GSD planning artifact.
+ *
+ * Task inputs are source files only — planning artifacts are projections of DB
+ * state that the framework preloads as composed context (see CONTEXT.md "Task
+ * Input"). Two triggers, deliberately different in strictness:
+ *
+ * - Any path entering framework-owned metadata (.gsd/, .planning/, .audits/)
+ *   is always a violation, even when the file exists.
+ * - A bare artifact-style basename (M001-CONTEXT.md, S01-PLAN.md, …) is a
+ *   violation only when it does NOT resolve to a real file. When such a file
+ *   genuinely exists in the source tree (e.g. a fixture), it is a source file
+ *   and stays legal; a path with directory components is likewise left to the
+ *   ordinary existence checks.
+ */
+function isPlanningArtifactReference(rawEntry, basePath, context) {
+    if (!shouldValidateInputAsPath(rawEntry))
+        return false;
+    const normalized = toComparisonPath(rawEntry, basePath);
+    if (isFrameworkMetadataPath(normalized))
+        return true;
+    return (!normalized.includes("/") &&
+        PLANNING_ARTIFACT_NAME_RE.test(normalized) &&
+        !inputExistsOnDisk(normalized, basePath, context));
+}
+/**
+ * Block GSD planning artifacts in task IO fields (inputs, files, expectedOutput).
+ *
+ * For inputs/files the violation smuggles a projection into the executor's
+ * preloaded source context; for expectedOutput it promises a write the runtime
+ * write-gate would reject mid-execution. Both get a precise message so the
+ * planning retry steers toward *removing* the reference, not creating the file.
+ * checkFilePathConsistency and checkTaskOrdering skip entries this check owns.
+ */
+export function checkPlanningArtifactReferences(tasks, basePath, context) {
+    const results = [];
+    for (const task of tasks) {
+        const fields = [
+            { label: "inputs", entries: task.inputs },
+            { label: "files", entries: task.files },
+            { label: "expectedOutput", entries: task.expected_output },
+        ];
+        for (const { label, entries } of fields) {
+            for (const file of entries) {
+                if (!isPlanningArtifactReference(file, basePath, context))
+                    continue;
+                const message = label === "expectedOutput"
+                    ? `Task ${task.id} lists '${file}' in expectedOutput — GSD planning artifacts are written by workflow tools (e.g. gsd_summary_save), never by tasks; remove it`
+                    : `Task ${task.id} lists '${file}' in ${label} — GSD planning artifacts are projections preloaded as context, never task ${label}; remove it`;
+                results.push({
+                    category: "file",
+                    target: file,
+                    passed: false,
+                    message,
+                    blocking: true,
+                });
+            }
+        }
+    }
+    return results;
+}
 // ─── Task Ordering Check ─────────────────────────────────────────────────────
 /**
  * Detect impossible task ordering: task N reads a file that task N+M creates.
@@ -583,6 +653,10 @@ export function checkTaskOrdering(tasks, basePath, context) {
                 continue;
             if (!shouldValidateInputAsPath(file))
                 continue;
+            // Owned by checkPlanningArtifactReferences — avoid a duplicate sequence
+            // finding on top of the removal message.
+            if (isPlanningArtifactReference(file, basePath, context))
+                continue;
             const normalizedFile = toComparisonPath(file, basePath);
             if (containsGlobPattern(normalizedFile))
                 continue;
@@ -611,6 +685,21 @@ export function checkTaskOrdering(tasks, basePath, context) {
     }
     return results;
 }
+// ─── Shared Path-Check Composition ───────────────────────────────────────────
+/**
+ * The synchronous path-shaped checks, in order. One list shared by the
+ * plan-persist gate (gsd_plan_slice) and the dispatch gate
+ * (runPreExecutionChecks) so the two cannot drift — the checks coordinate
+ * ownership of planning-artifact entries via isPlanningArtifactReference
+ * skips, which only works when they run as a set.
+ */
+export function runTaskPathChecks(tasks, basePath, context) {
+    return [
+        ...checkPlanningArtifactReferences(tasks, basePath, context),
+        ...checkFilePathConsistency(tasks, basePath, context),
+        ...checkTaskOrdering(tasks, basePath, context),
+    ];
+}
 /**
  * Extract function signatures from code blocks in task description.
  * Uses heuristic regex — not an AST parser.
@@ -741,11 +830,10 @@ export async function runPreExecutionChecks(tasks, basePath, context) {
     const startTime = Date.now();
     const allChecks = [];
     // Run sync checks first
-    const fileChecks = checkFilePathConsistency(tasks, basePath, context);
-    const orderingChecks = checkTaskOrdering(tasks, basePath, context);
+    const pathChecks = runTaskPathChecks(tasks, basePath, context);
     const contractChecks = checkInterfaceContracts(tasks, basePath);
     const verificationChecks = checkVerificationCommands(tasks);
-    allChecks.push(...fileChecks, ...orderingChecks, ...contractChecks, ...verificationChecks);
+    allChecks.push(...pathChecks, ...contractChecks, ...verificationChecks);
     // Run async package checks
     const packageChecks = await checkPackageExistence(tasks, basePath);
     allChecks.push(...packageChecks);

package/dist/resources/extensions/gsd/preferences-models.js

@@ -11,6 +11,7 @@ import { join } from "node:path";
 import { gsdHome } from "./gsd-home.js";
 import { canonicalModelForTier, defaultRoutingConfig, resolveModelForTier } from "./model-router.js";
 import { loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
+import { getUnitPhaseChain } from "./unit-registry.js";
 /**
  * Resolve which model ID to use for a given auto-mode unit type.
  * Returns undefined if no model preference is set for this unit type.
@@ -29,53 +30,18 @@ export function resolveModelForUnit(unitType) {
  * (`resolveThinkingLevelForUnit`) so the two never drift (ADR-026).
  */
 export function phaseChainForUnit(unitType) {
-    switch (unitType) {
-        case "research-milestone":
-        case "research-slice":
-        // Deep-mode project research orchestrator. Reads PROJECT.md / REQUIREMENTS.md
-        // and fans out research subagents. Routes to the research bucket.
-        case "research-project":
-            return ["research"];
-        case "plan-milestone":
-        case "plan-slice":
-        case "refine-slice":
-        case "replan-slice":
-            return ["planning"];
-        // Deep-mode project-level discussion units route to the same model bucket
-        // as milestone-level discussion (interactive interview style). Workflow
-        // preferences and research-decision are tiny ask_user_questions style units
-        // that share the discuss bucket because they are conversational. All fall
-        // back to planning when no `discuss` bucket is set.
-        case "discuss-milestone":
-        case "discuss-slice":
-        case "discuss-project":
-        case "discuss-requirements":
-        case "workflow-preferences":
-        case "research-decision":
-            return ["discuss", "planning"];
-        case "execute-task":
-        case "reactive-execute":
-            return ["execution"];
-        case "execute-task-simple":
-            return ["execution_simple", "execution"];
-        case "complete-slice":
-        case "complete-milestone":
-        case "worktree-merge":
-            return ["completion"];
-        case "run-uat":
-            return ["uat", "completion"];
-        case "reassess-roadmap":
-        case "rewrite-docs":
-        case "gate-evaluate":
-        case "validate-milestone":
-            return ["validation", "planning"];
-        default:
-            // Subagent unit types (e.g., "subagent", "subagent/scout")
-            if (unitType === "subagent" || unitType.startsWith("subagent/")) {
-                return ["subagent"];
-            }
-            return undefined;
+    // Unit types declare their chain on their Unit Descriptor (ADR-033).
+    const declared = getUnitPhaseChain(unitType);
+    if (declared)
+        return [...declared];
+    // Dispatch types without a Unit Descriptor.
+    if (unitType === "worktree-merge")
+        return ["completion"];
+    // Subagent unit types (e.g., "subagent", "subagent/scout")
+    if (unitType === "subagent" || unitType.startsWith("subagent/")) {
+        return ["subagent"];
     }
+    return undefined;
 }
 /**
  * Find the phase bucket whose `models` entry wins the chain for a unit, plus

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

@@ -699,6 +699,20 @@ export function getIsolationMode(basePath) {
         return "branch";
     return "none"; // default — no isolation, work on current branch
 }
+/**
+ * Resolve the isolation mode a unit actually runs under. A session whose
+ * worktree isolation has degraded (worktree creation failed) falls back to
+ * the milestone branch in the project root, so configured "worktree" becomes
+ * effective "branch". A stranded-work recovery session likewise runs under
+ * the adopted mode (`strandedRecoveryIsolationMode`) rather than the
+ * configured one until the recovered milestone merges — adopting the
+ * milestone branch in the project root is intentional, not degraded.
+ */
+export function resolveEffectiveUnitIsolationMode(configuredMode, isolationDegraded, strandedRecoveryIsolationMode = null) {
+    if (configuredMode === "worktree" && isolationDegraded)
+        return "branch";
+    return strandedRecoveryIsolationMode ?? configuredMode;
+}
 export function resolveParallelConfig(prefs) {
     return {
         enabled: prefs?.parallel?.enabled ?? false,

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

@@ -45,7 +45,7 @@ If slice research is inlined, trust its architectural findings, but verify every
 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

@@ -65,7 +65,7 @@ Then:
 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/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-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/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))

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.