gsd-pi 2.80.0 → 2.81.0

package/src/resources/extensions/gsd/prompts/triage-captures.md

@@ -2,7 +2,7 @@ You are triaging user-captured thoughts during a GSD session.
 
 ## UNIT: Triage Captures
 
-The user captured thoughts during execution using `/gsd capture`. Your job is to classify each capture, present your proposals, get user confirmation, and update CAPTURES.md with the final classifications.
+The user captured thoughts with `/gsd capture`. Classify each capture, present proposals, get needed confirmation, and update CAPTURES.md with final classifications.
 
 ## Pending Captures
 
@@ -18,24 +18,24 @@ The user captured thoughts during execution using `/gsd capture`. Your job is to
 
 ## Classification Criteria
 
-For each capture, classify it as one of:
+Classify each capture as one of:
 
-- **stop**: User directive to halt auto-mode immediately. Use when the user says "stop", "halt", "abort", "don't continue", "pause", or otherwise wants execution to cease. Auto-mode will pause after the current unit completes. Examples: "stop running", "halt execution", "don't continue".
-- **backtrack**: User directive to abandon the current milestone and return to a previous one. The user believes earlier milestones missed critical features or need rework. Include the target milestone ID (e.g., M003) in the Resolution field. Auto-mode will pause and write a regression marker. Examples: "restart from M003", "go back to milestone 3", "M004 and M005 failed, restart from M003".
-- **quick-task**: Small, self-contained, no downstream impact. Can be done in minutes without modifying the plan. Examples: fix a typo, add a missing import, tweak a config value.
-- **inject**: Belongs in the current slice but wasn't planned. Needs a new task added to the slice plan. Examples: add error handling to a module being built, add a missing test case for current work.
-- **defer**: Belongs in a future slice or milestone. Not urgent for current work. Examples: performance optimization, feature that depends on unbuilt infrastructure, nice-to-have enhancement.
-- **replan**: Changes the shape of remaining work in the current slice. Existing incomplete tasks may need rewriting. Examples: "the approach is wrong, we need to use X instead of Y", discovering a fundamental constraint.
-- **note**: Informational only. No action needed right now. Good context for future reference. Examples: "remember that the API has a rate limit", observations about code quality.
+- **stop**: Halt/pause auto-mode immediately after the current unit. Examples: "stop", "halt", "abort", "don't continue".
+- **backtrack**: Abandon current milestone and return to an earlier one. Include target milestone ID (e.g., M003) in Resolution. Auto-mode pauses and writes a regression marker.
+- **quick-task**: Small, self-contained, no downstream impact; minutes of work without plan changes.
+- **inject**: Belongs in current slice but was not planned; needs a new task.
+- **defer**: Belongs in a future slice/milestone; not urgent for current work.
+- **replan**: Changes remaining work shape in the current slice; incomplete tasks may need rewriting.
+- **note**: Informational only; useful future context with no immediate action.
 
 ## Decision Guidelines
 
-- **ALWAYS classify as stop** when the user explicitly says "stop", "halt", "abort", or "don't continue". Never shoe-horn a stop directive into "replan" or "note".
-- **ALWAYS classify as backtrack** when the user references returning to a previous milestone, restarting from an earlier point, or abandoning current milestone work. Include the target milestone ID in the Resolution field (e.g., "Backtrack to M003").
+- **ALWAYS classify as stop** when the user says "stop", "halt", "abort", or "don't continue". Never shoe-horn stop into "replan" or "note".
+- **ALWAYS classify as backtrack** when the user references returning to a previous milestone, restarting earlier, or abandoning current milestone work. Include target milestone ID in Resolution (e.g., "Backtrack to M003").
 - Prefer **quick-task** when the work is clearly small and self-contained.
 - Prefer **inject** over **replan** when only a new task is needed, not rewriting existing ones.
 - Prefer **defer** over **inject** when the work doesn't belong in the current slice's scope.
-- Use **replan** only when remaining incomplete tasks in the *current slice* need to change — not for cross-milestone issues.
+- Use **replan** only when remaining incomplete tasks in the *current slice* need to change, not for cross-milestone issues.
 - Use **note** for observations that don't require action.
 - When unsure between quick-task and inject, consider: will this take more than 10 minutes? If yes, inject.
 
@@ -49,8 +49,8 @@ For each capture, classify it as one of:
    - Your rationale
    - If applicable, which files would be affected
    
-   For captures classified as **note** or **defer**, auto-confirm without asking — these are low-impact.
-   For captures classified as **stop** or **backtrack**, auto-confirm without asking — these are urgent user directives that must be honored immediately.
+   Auto-confirm **note** and **defer** because they are low-impact.
+   Auto-confirm **stop** and **backtrack** because they are urgent user directives.
    For captures classified as **quick-task**, **inject**, or **replan**, ask the user to confirm or choose a different classification. **Non-bypassable:** If `ask_user_questions` fails, errors, or the user does not respond, you MUST re-ask — never auto-confirm these classifications without explicit user approval.
 
 3. **Update** `.gsd/CAPTURES.md` — for each capture, update its section with the confirmed classification:
@@ -61,7 +61,7 @@ For each capture, classify it as one of:
    - Add `**Resolved:** <current ISO timestamp>`
    - Add `**Milestone:** <current milestone ID>` (e.g., `**Milestone:** M003`)
 
-4. **Summarize** what was triaged: how many captures, what classifications were assigned, and what actions are pending (e.g., "2 quick-tasks ready for execution, 1 deferred to S03").
+4. **Summarize** count, assigned classifications, and pending actions (e.g., "2 quick-tasks ready, 1 deferred to S03").
 
 **Important:** Do NOT execute any resolutions. Only classify and update CAPTURES.md. Resolution execution happens separately (in auto-mode dispatch or manually by the user).
 

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -1,20 +1,20 @@
-# Milestone Validation — Parallel Review
+# Milestone Validation - Parallel Review
 
-You are the validation orchestrator for **{{milestoneId}} — {{milestoneTitle}}**.
+You are the validation orchestrator for **{{milestoneId}} - {{milestoneTitle}}**.
 
 ## Working Directory
 
-Your working directory is `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
+Work in `{{workingDirectory}}`. All reads, writes, and shell commands MUST stay relative to it. Do NOT `cd` elsewhere.
 
 ## Mission
 
-Dispatch 3 independent parallel reviewers, then synthesize their findings into the final VALIDATION verdict.
+Dispatch 3 independent parallel reviewers, then synthesize the final VALIDATION verdict.
 
-This is remediation round {{remediationRound}}. If this is round 0, this is the first validation pass. If > 0, prior validation found issues and remediation slices were added and executed — verify those remediation slices resolved the issues.
+Remediation round: {{remediationRound}}. Round 0 is the first pass; later rounds must verify remediation slices resolved prior findings.
 
 ## Context
 
-All relevant context has been preloaded below — the roadmap, all slice summaries, assessment results, requirements, decisions, and project context are inlined. Start working immediately without re-reading these files.
+Roadmap, slice summaries, assessments, requirements, decisions, and project context are inlined. Start immediately.
 
 {{inlinedContext}}
 
@@ -22,29 +22,29 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 
 ## Execution Protocol
 
-### Step 1 — Dispatch Parallel Reviewers
+### Step 1 - Dispatch Parallel Reviewers
 
 Call `subagent` with `tasks: [...]` containing ALL THREE reviewers simultaneously:
 
-**Reviewer A — Requirements Coverage**
-Prompt: "Review milestone {{milestoneId}} requirements coverage. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/REQUIREMENTS.md` (or equivalent requirements file). For each requirement, check the slice SUMMARY files in `.gsd/{{milestoneId}}/` to determine if it is: COVERED (clearly demonstrated), PARTIAL (mentioned but not fully demonstrated), or MISSING (no evidence). Output a markdown table with columns: Requirement | Status | Evidence. End with a one-line verdict: PASS if all covered, NEEDS-ATTENTION if partials exist, FAIL if any missing."
+**Reviewer A - Requirements Coverage**
+Prompt: "Review milestone {{milestoneId}} requirements coverage. Working directory: {{workingDirectory}}. Read `.gsd/REQUIREMENTS.md` or use the inlined requirements context. For each requirement, check slice SUMMARY files under `.gsd/milestones/{{milestoneId}}/slices/` and mark COVERED, PARTIAL, or MISSING. Output table: Requirement | Status | Evidence. End with one-line verdict: PASS if all covered, NEEDS-ATTENTION if partials exist, FAIL if any missing."
 
-**Reviewer B — Cross-Slice Integration**
-Prompt: "Review milestone {{milestoneId}} cross-slice integration. Working directory: {{workingDirectory}}. Read `{{roadmapPath}}` and find the boundary map (produces/consumes contracts). For each boundary, check that the producing slice's SUMMARY confirms it produced the artifact, and the consuming slice's SUMMARY confirms it consumed it. Output a markdown table: Boundary | Producer Summary | Consumer Summary | Status. End with a one-line verdict: PASS if all boundaries honored, NEEDS-ATTENTION if any gaps."
+**Reviewer B - Cross-Slice Integration**
+Prompt: "Review milestone {{milestoneId}} cross-slice integration. Working directory: {{workingDirectory}}. Read `{{roadmapPath}}` and find the boundary map (produces/consumes contracts). For each boundary, confirm producer SUMMARY produced the artifact and consumer SUMMARY consumed it. Output table: Boundary | Producer Summary | Consumer Summary | Status. End with one-line verdict: PASS if all boundaries honored, NEEDS-ATTENTION if any gaps."
 
-**Reviewer C — Assessment & Acceptance Criteria**
-Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/CONTEXT.md` for acceptance criteria. Check for ASSESSMENT files in each slice directory. Verify each acceptance criterion maps to either a passing assessment result or clear SUMMARY evidence. Then review the inlined milestone verification classes from planning. For each non-empty planned class, output a markdown table: Class | Planned Check | Evidence | Verdict. Use the exact class names `Contract`, `Integration`, `Operational`, and `UAT` whenever those classes are present. If no verification classes were planned, say that explicitly. Output two sections: `Acceptance Criteria` with a checklist `[ ] Criterion | Evidence`, and `Verification Classes` with the table. End with a one-line verdict: PASS if all criteria and verification classes are covered, NEEDS-ATTENTION if gaps exist."
+**Reviewer C - Assessment & Acceptance Criteria**
+Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/milestones/{{milestoneId}}/{{milestoneId}}-CONTEXT.md` for criteria. Check slice SUMMARY/UAT files under `.gsd/milestones/{{milestoneId}}/slices/`. Verify each criterion maps to passing evidence. Then review inlined milestone verification classes. For each non-empty planned class, output table: Class | Planned Check | Evidence | Verdict. Use the exact class names `Contract`, `Integration`, `Operational`, and `UAT` whenever those classes are present. If no verification classes were planned, say that explicitly. Output sections `Acceptance Criteria` with checklist `[ ] Criterion | Evidence`, and `Verification Classes` with the table. End with one-line verdict: PASS if all criteria and classes are covered, NEEDS-ATTENTION if gaps exist."
 
-### Step 2 — Synthesize Findings
+### Step 2 - Synthesize Findings
 
-After all reviewers complete, aggregate their verdicts:
-- If ALL reviewers say PASS → overall verdict: `pass`
-- If any reviewer says NEEDS-ATTENTION → overall verdict: `needs-attention`
-- If any reviewer says FAIL → overall verdict: `needs-remediation`
+Aggregate reviewer verdicts:
+- ALL PASS -> `pass`
+- Any NEEDS-ATTENTION -> `needs-attention`
+- Any FAIL -> `needs-remediation`
 
-### Step 3 — Persist Validation
+### Step 3 - Persist Validation
 
-Prepare the validation content you will pass to `gsd_validate_milestone`. Do **not** manually write `{{validationPath}}` — the DB-backed tool is the canonical write path and renders the validation file for you.
+Prepare validation content for `gsd_validate_milestone`. Do **not** manually write `{{validationPath}}` - the DB-backed tool is the canonical write path and renders the file.
 
 ```markdown
 ---
@@ -65,7 +65,7 @@ reviewers: 3
 <paste Reviewer C output>
 
 ## Synthesis
-<2-3 sentences summarizing overall findings and verdict rationale>
+<2-3 sentence verdict rationale>
 
 ## Remediation Plan
 <if verdict is not pass: specific actions required>
@@ -74,14 +74,14 @@ reviewers: 3
 Call `gsd_validate_milestone` with the camelCase fields `milestoneId`, `verdict`, `remediationRound`, `successCriteriaChecklist`, `sliceDeliveryAudit`, `crossSliceIntegration`, `requirementCoverage`, `verdictRationale`, and `remediationPlan` when needed. If you include verification-class analysis, pass it in `verificationClasses`.
 Extract the `Verification Classes` subsection from Reviewer C and pass it verbatim in `verificationClasses` so the persisted validation output uses the canonical class names `Contract`, `Integration`, `Operational`, and `UAT`.
 
-**DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — the engine owns the WAL connection. Use `gsd_milestone_status` to read milestone and slice state. All data you need is already inlined in the context above or accessible via the `gsd_*` tools. Direct DB access corrupts the WAL and bypasses tool-level validation.
+**DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` - the engine owns the WAL connection. Use `gsd_milestone_status` for milestone and slice state. Data is already inlined or available via `gsd_*` tools. Direct DB access risks WAL corruption and bypasses validation.
 
 If verdict is `needs-remediation`:
-- Use `gsd_reassess_roadmap` to add the remediation slices instead of editing `{{roadmapPath}}` manually
+- Use `gsd_reassess_roadmap` to add remediation slices instead of editing `{{roadmapPath}}` manually.
 - Those slices will be planned and executed before validation re-runs
 
 **You MUST call `gsd_validate_milestone` before finishing. Do not manually write `{{validationPath}}`.**
 
-**File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+**File system safety:** When scanning milestone directories, use `ls` or `find` first. Never pass a directory path such as `tasks/` or `slices/` directly to `read`; it only accepts files.
 
 When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>."

package/src/resources/extensions/gsd/prompts/worktree-merge.md

@@ -1,16 +1,16 @@
-You are merging changes from worktree **{{worktreeName}}** (branch `{{worktreeBranch}}`) into target branch `{{mainBranch}}`.
+You are merging worktree **{{worktreeName}}** (branch `{{worktreeBranch}}`) into target branch `{{mainBranch}}`.
 
 ## Working Directory
 
-Your current working directory has been set to the **main project tree** at `{{mainTreePath}}`. You are on the `{{mainBranch}}` branch. All git and file commands run from here.
+Your CWD is the **main project tree** at `{{mainTreePath}}` on `{{mainBranch}}`. Run all git and file commands here.
 
-- **Main tree (CWD):** `{{mainTreePath}}` — this is where you run `git merge`, read main-branch files, and commit
-- **Worktree directory:** `{{worktreePath}}` — the worktree's working copy; read files here to inspect worktree versions before merging
+- **Main tree (CWD):** `{{mainTreePath}}` — run `git merge`, read main files, commit.
+- **Worktree directory:** `{{worktreePath}}` — inspect worktree versions before merging.
 - **Worktree branch:** `{{worktreeBranch}}`
 
 ## Context
 
-The worktree was created as a parallel workspace. It may contain code changes, new milestones, updated roadmaps, new plans, research, decisions, or other artifacts that need to be merged into the target branch.
+The worktree may contain code, milestones, roadmaps, plans, research, decisions, requirements, or other artifacts to merge.
 
 ### Commit History (worktree)
 
@@ -43,50 +43,50 @@ The worktree was created as a parallel workspace. It may contain code changes, n
 
 ## Your Task
 
-Analyze the changes and guide the merge. Follow these steps exactly:
+Analyze and guide the merge exactly:
 
 ### Step 1: Categorize Changes
 
-Classify each changed file:
+Classify each changed file.
 
 **Code changes:**
-- **New source files** — new modules, components, utilities, tests
-- **Modified source files** — changes to existing code
+- **New source files** — modules, components, utilities, tests.
+- **Modified source files** — existing code changes.
 - **Config changes** — package.json, tsconfig, build config, etc.
-- **Deleted files** — removed source or config files
+- **Deleted files** — removed source/config.
 
 **GSD artifact changes:**
-- **New milestones** — entirely new M###/ directories with roadmaps
-- **New slices/tasks** — new planning artifacts within existing milestones
-- **Updated roadmaps** — modifications to existing M###-ROADMAP.md files
-- **Updated plans** — modifications to existing slice or task plans
-- **Research/context** — new or updated RESEARCH.md, CONTEXT.md files
+- **New milestones** — new M###/ directories with roadmaps.
+- **New slices/tasks** — planning artifacts inside existing milestones.
+- **Updated roadmaps** — changed M###-ROADMAP.md files.
+- **Updated plans** — changed slice/task plans.
+- **Research/context** — new or updated RESEARCH.md, CONTEXT.md.
 - **Decisions** — changes to DECISIONS.md
 - **Requirements** — changes to REQUIREMENTS.md
 - **Other** — anything else
 
 ### Step 2: Conflict Assessment
 
-For each **modified** file, check whether the main branch version has also changed since the worktree branched off. Flag any files where both branches have diverged — these need manual reconciliation.
+For each **modified** file, check whether main also changed since the worktree branched. Flag diverged files for manual reconciliation.
 
 To compare versions:
-- **Main-branch version:** read the file at its normal path (your CWD is the main tree)
-- **Worktree version:** read the file at `{{worktreePath}}/<relative-path>`
-- Use `git merge-base {{mainBranch}} {{worktreeBranch}}` to find the common ancestor if needed
+- **Main version:** read normal path from CWD.
+- **Worktree version:** read `{{worktreePath}}/<relative-path>`.
+- Use `git merge-base {{mainBranch}} {{worktreeBranch}}` if needed.
 
 Classify each modified file:
-- **Clean merges** — main hasn't changed, worktree changes can apply directly
-- **Conflicts** — both branches changed the same file; needs reconciliation
-- **Stale changes** — worktree modified a file that main has since replaced or removed
+- **Clean merges** — main unchanged; apply worktree changes directly.
+- **Conflicts** — both changed same file; reconcile.
+- **Stale changes** — main replaced/removed a file the worktree modified.
 
 ### Step 3: Merge Strategy
 
-Present a merge plan to the user:
+Present a merge plan:
 
-1. For **clean merges**: list files that will merge without conflict
-2. For **conflicts**: show both versions side-by-side and propose a reconciled version
-3. For **new files**: confirm they should be added to the main branch
-4. For **removed files**: confirm the removals are intentional
+1. **Clean merges:** files expected to merge without conflict.
+2. **Conflicts:** show both versions side-by-side and propose reconciliation.
+3. **New files:** confirm they should be added.
+4. **Removed files:** confirm removals are intentional.
 
 Ask the user to confirm the merge plan before proceeding.
 
@@ -97,17 +97,17 @@ Ask the user to confirm the merge plan before proceeding.
 Once the user has explicitly confirmed, run all commands from `{{mainTreePath}}` (your CWD):
 
 1. Ensure you are on the target branch: `git checkout {{mainBranch}}`
-2. If there are conflicts requiring manual reconciliation, apply the reconciled versions first
+2. If conflicts require manual reconciliation, apply reconciled versions first
 3. Run `git merge --squash {{worktreeBranch}}` to bring in all changes
-4. Review the staged changes — if any reconciled files need adjustment, apply them now
+4. Review staged changes; adjust reconciled files if needed
 5. Commit with message: `merge(worktree/{{worktreeName}}): <summary of what was merged>`
 6. Report what was merged
 
 ### Step 5: Cleanup Prompt
 
 After a successful merge, ask the user whether to:
-- **Remove the worktree** — delete the worktree directory and the `{{worktreeBranch}}` branch
-- **Keep the worktree** — leave it for continued parallel work
+- **Remove the worktree** — delete the worktree directory and `{{worktreeBranch}}`.
+- **Keep the worktree** — leave it for continued parallel work.
 
 If the user chooses to remove it, run these commands from `{{mainTreePath}}`:
 ```
@@ -119,7 +119,7 @@ git branch -D {{worktreeBranch}}
 
 ## Important
 
-- Never silently discard changes from either branch
-- When in doubt about a conflict, show both versions and ask the user
-- Preserve all GSD artifact formatting conventions (frontmatter, section structure, checkbox states)
-- If the worktree introduced new milestone IDs that conflict with main, flag this immediately
+- Never silently discard changes from either branch.
+- When in doubt, show both versions and ask.
+- Preserve GSD artifact formatting: frontmatter, sections, checkbox states.
+- If new milestone IDs conflict with main, flag immediately.

package/src/resources/extensions/gsd/quick.ts

@@ -10,8 +10,8 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
 import { GitServiceImpl, runGit } from "./git-service.js";
@@ -77,6 +77,40 @@ function ensureQuickDir(basePath: string, taskNum: number, slug: string): string
   return taskDir;
 }
 
+function isPathInside(parent: string, child: string): boolean {
+  const rel = relative(parent, child);
+  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function isExternalGsdRoot(basePath: string, root: string): boolean {
+  try {
+    return !isPathInside(realpathSync(basePath), realpathSync(root));
+  } catch {
+    return !isPathInside(basePath, root);
+  }
+}
+
+export function buildQuickCommitInstruction(basePath: string, root: string): string {
+  const externalState = isExternalGsdRoot(basePath, root);
+  if (externalState) {
+    return [
+      "Commit repo changes atomically, but do not stage or commit `.gsd/quick/...`:",
+      "   - `.gsd/` resolves outside this git repository, so Git cannot stage quick-task summary files from the project repo.",
+      "   - Write the quick summary file directly at the requested path; that file is persisted by GSD external state.",
+      "   - Stage and commit only implementation/test/docs files that live inside the repository.",
+      "   - If the task only writes quick-task research/summary files and no repository files changed, do not run `git commit`; report that there was nothing in the project repo to commit.",
+    ].join("\n");
+  }
+
+  return [
+    "Commit your changes atomically:",
+    "   - Use conventional commit messages (feat:, fix:, refactor:, etc.)",
+    "   - Stage only relevant files — never commit secrets or runtime files.",
+    "   - Commit logical units separately if the task involves distinct changes.",
+    "   - Quick tasks run outside the auto-mode lifecycle — there is no system auto-commit, so commit directly here.",
+  ].join("\n");
+}
+
 function quickReturnStatePath(basePath: string): string {
   return join(gsdRoot(basePath), "runtime", "quick-return.json");
 }
@@ -246,6 +280,7 @@ export async function handleQuick(
     taskDir: taskDirRel,
     branch: actualBranch,
     summaryPath,
+    commitInstruction: buildQuickCommitInstruction(basePath, root),
     date,
     taskNum: String(taskNum),
     slug,

package/src/resources/extensions/gsd/recovery-classification.ts

@@ -0,0 +1,122 @@
+// Project/App: GSD-2
+// File Purpose: ADR-015 Recovery Classification module for runtime failure taxonomy.
+
+import { classifyError, isTransient, type ErrorClass } from "./error-classifier.js";
+
+export type RecoveryFailureKind =
+  | "tool-schema"
+  | "deterministic-policy"
+  | "stale-worker"
+  | "worktree-invalid"
+  | "verification-drift"
+  | "provider"
+  | "runtime-unknown";
+
+export type RecoveryAction = "retry" | "escalate" | "stop";
+
+export interface RecoveryClassificationInput {
+  error: unknown;
+  unitType?: string;
+  unitId?: string;
+  failureKind?: RecoveryFailureKind;
+  retryAfterMs?: number;
+}
+
+export interface RecoveryClassification {
+  failureKind: RecoveryFailureKind;
+  action: RecoveryAction;
+  reason: string;
+  exitReason: string;
+  remediation: string;
+  providerClass?: ErrorClass["kind"];
+}
+
+export function classifyFailure(input: RecoveryClassificationInput): RecoveryClassification {
+  const message = errorMessage(input.error);
+  const failureKind = 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 "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 "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 "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.",
+      };
+  }
+}
+
+function inferFailureKind(message: string): RecoveryFailureKind {
+  if (/schema|invalid.*tool|tool.*invalid|enum/i.test(message)) return "tool-schema";
+  if (/deterministic policy|policy rejection|write gate|blocked by policy/i.test(message)) return "deterministic-policy";
+  if (/stale worker|stale lock|worker.*stale/i.test(message)) return "stale-worker";
+  if (/worktree|\.git|unit root|git metadata/i.test(message)) return "worktree-invalid";
+  if (/verification drift|assessment drift|state drift/i.test(message)) return "verification-drift";
+
+  const providerClass = classifyError(message);
+  return providerClass.kind === "unknown" ? "runtime-unknown" : "provider";
+}
+
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  return String(error ?? "unknown runtime failure");
+}
+
+function unitSuffix(input: RecoveryClassificationInput): string {
+  if (!input.unitType && !input.unitId) return "";
+  return ` for ${input.unitType ?? "unit"} ${input.unitId ?? ""}`.trimEnd();
+}

package/src/resources/extensions/gsd/safety/evidence-collector.ts

@@ -50,6 +50,15 @@ export interface FileEditEvidence {
 
 export type EvidenceEntry = BashEvidence | FileWriteEvidence | FileEditEvidence;
 
+const EXECUTION_TOOL_NAMES = new Set([
+  "bash",
+  "Bash",
+  "gsd_exec",
+  "gsd_exec_search",
+  "mcp__gsd-workflow__gsd_exec",
+  "mcp__gsd-workflow__gsd_exec_search",
+]);
+
 // ─── Module State ───────────────────────────────────────────────────────────
 
 let unitEvidence: EvidenceEntry[] = [];
@@ -188,11 +197,11 @@ export function clearEvidenceFromDisk(
  * Exit codes and output are filled in by recordToolResult after execution.
  */
 export function recordToolCall(toolCallId: string, toolName: string, input: Record<string, unknown>): void {
-  if (toolName === "bash" || toolName === "Bash") {
+  if (EXECUTION_TOOL_NAMES.has(toolName)) {
     unitEvidence.push({
       kind: "bash",
       toolCallId,
-      command: String(input.command ?? ""),
+      command: String(input.command ?? input.cmd ?? input.query ?? ""),
       exitCode: -1,
       outputSnippet: "",
       timestamp: Date.now(),

package/src/resources/extensions/gsd/slice-cadence.ts

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Slice-cadence merge and milestone resquash git operations.
 /**
  * Slice-cadence collapse — #4765.
  *
@@ -40,6 +42,7 @@ import { logWarning } from "./workflow-logger.js";
 import { emitSliceMerged, emitMilestoneResquash } from "./worktree-telemetry.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+import { getMilestone, getSlice, isDbAvailable } from "./gsd-db.js";
 
 /**
  * Auto-worktree milestone branch name. Must match autoWorktreeBranch() in
@@ -72,6 +75,50 @@ function cleanupMergeArtifacts(projectRoot: string): void {
   }
 }
 
+function stripKnownIdPrefix(value: string | undefined | null, id: string): string | undefined {
+  const raw = String(value ?? "").trim();
+  if (!raw) return undefined;
+  const lower = raw.toLowerCase();
+  const idLower = id.toLowerCase();
+  if (lower.startsWith(`${idLower}:`)) return raw.slice(id.length + 1).trim() || undefined;
+  return raw;
+}
+
+function getSliceMergeNames(milestoneId: string, sliceId: string): {
+  milestoneTitle?: string;
+  sliceTitle?: string;
+} {
+  if (!isDbAvailable()) return {};
+  return {
+    milestoneTitle: stripKnownIdPrefix(getMilestone(milestoneId)?.title, milestoneId),
+    sliceTitle: stripKnownIdPrefix(getSlice(milestoneId, sliceId)?.title, sliceId),
+  };
+}
+
+function buildSliceMergeCommitMessage(milestoneId: string, sliceId: string, milestoneBranch: string): string {
+  const names = getSliceMergeNames(milestoneId, sliceId);
+  const sliceLabel = names.sliceTitle ?? sliceId;
+  const subject = `feat: ${sliceLabel} - ${sliceId} of ${milestoneId} (slice-cadence)`;
+  const body = [
+    `Slice: ${sliceId}${names.sliceTitle ? ` - ${names.sliceTitle}` : ""}`,
+    `Milestone: ${milestoneId}${names.milestoneTitle ? ` - ${names.milestoneTitle}` : ""}`,
+    `GSD-Slice: ${sliceId}`,
+    `GSD-Milestone: ${milestoneId}`,
+    `Branch: ${milestoneBranch}`,
+  ];
+  return `${subject}\n\n${body.join("\n")}`;
+}
+
+function buildMilestoneResquashCommitMessage(milestoneId: string, sliceCount: number): string {
+  const milestoneTitle = isDbAvailable()
+    ? stripKnownIdPrefix(getMilestone(milestoneId)?.title, milestoneId)
+    : undefined;
+  const subject = milestoneTitle
+    ? `feat: ${milestoneTitle} (${milestoneId}, ${sliceCount} slices re-squashed)`
+    : `feat: ${milestoneId} (${sliceCount} slices re-squashed)`;
+  return `${subject}\n\nMilestone: ${milestoneId}${milestoneTitle ? ` - ${milestoneTitle}` : ""}\nGSD-Milestone: ${milestoneId}`;
+}
+
 function advanceMilestoneBranch(
   projectRoot: string,
   worktreeCwd: string,
@@ -227,7 +274,7 @@ export function mergeSliceToMain(
     // Commit the squash with a slice-scoped message
     const commitSha = nativeCommit(
       projectRoot,
-      `gsd: merge ${sliceId} of ${milestoneId} (slice-cadence)`,
+      buildSliceMergeCommitMessage(milestoneId, sliceId, milestoneBranch),
     );
 
     // Advance the milestone branch to main so the next slice's commits start
@@ -327,7 +374,7 @@ export function resquashMilestoneOnMain(
 
     const newSha = nativeCommit(
       projectRoot,
-      `gsd: complete milestone ${milestoneId} (${sliceCount} slices re-squashed)`,
+      buildMilestoneResquashCommitMessage(milestoneId, sliceCount),
       { allowEmpty: true },
     );
 

package/src/resources/extensions/gsd/slice-parallel-orchestrator.ts

@@ -84,6 +84,27 @@ const SLICE_ORCHESTRATOR_STATE_FILE = "slice-orchestrator.json";
 const TMP_SUFFIX = ".tmp";
 export const SLICE_WORKER_AUTO_ARGS = ["headless", "--json", "auto"] as const;
 
+export function _resolveSliceParallelMaxWorkersForTest(maxWorkers?: number): number {
+  return maxWorkers ?? 2;
+}
+
+export function _buildSliceWorkerEnvForTest(
+  basePath: string,
+  milestoneId: string,
+  sliceId: string,
+  workerToken: string,
+  sourceEnv: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  return {
+    ...sourceEnv,
+    GSD_SLICE_LOCK: sliceId,
+    GSD_MILESTONE_LOCK: milestoneId,
+    GSD_PROJECT_ROOT: basePath,
+    GSD_PARALLEL_WORKER: "1",
+    GSD_SLICE_WORKER_TOKEN: workerToken,
+  };
+}
+
 interface PersistedSliceWorker {
   milestoneId: string;
   sliceId: string;
@@ -371,7 +392,7 @@ export async function startSliceParallel(
     return { started: [], errors: [{ sid: "all", error: "Cannot start slice-parallel from within a parallel worker" }] };
   }
 
-  const maxWorkers = opts.maxWorkers ?? 2;
+  const maxWorkers = _resolveSliceParallelMaxWorkersForTest(opts.maxWorkers);
   const budgetCeiling = opts.budgetCeiling;
 
   // Initialize orchestrator state
@@ -624,14 +645,7 @@ function spawnSliceWorker(
   try {
     child = spawn(process.execPath, [binPath, ...SLICE_WORKER_AUTO_ARGS], {
       cwd: worker.worktreePath,
-      env: {
-        ...process.env,
-        GSD_SLICE_LOCK: sliceId,
-        GSD_MILESTONE_LOCK: milestoneId,
-        GSD_PROJECT_ROOT: basePath,
-        GSD_PARALLEL_WORKER: "1",
-        GSD_SLICE_WORKER_TOKEN: worker.workerToken,
-      },
+      env: _buildSliceWorkerEnvForTest(basePath, milestoneId, sliceId, worker.workerToken),
       stdio: ["ignore", "pipe", "pipe"],
       detached: false,
     });