gsd-pi 2.80.0-dev.2848d9009 → 2.80.0-dev.42bd34838

package/src/resources/extensions/gsd/migration-auto-check.ts

@@ -0,0 +1,129 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+
+import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
+import {
+  clearEngineHierarchy,
+  getAllMilestones,
+  getMilestoneSlices,
+  getSliceTasks,
+  isDbAvailable,
+  transaction,
+} from "./gsd-db.js";
+import { migrateHierarchyToDb } from "./md-importer.js";
+import { parsePlan, parseRoadmap } from "./parsers-legacy.js";
+import {
+  milestonesDir,
+  resolveMilestoneFile,
+  resolveSliceFile,
+} from "./paths.js";
+import { invalidateStateCache } from "./state.js";
+
+export interface HierarchyCounts {
+  milestones: number;
+  slices: number;
+  tasks: number;
+}
+
+export interface MigrationAutoCheckResult {
+  action: "none" | "imported";
+  reason: "no-markdown" | "in-sync" | "db-empty" | "count-mismatch";
+  markdown: HierarchyCounts;
+  beforeDb: HierarchyCounts;
+  afterDb: HierarchyCounts;
+}
+
+function zeroCounts(): HierarchyCounts {
+  return { milestones: 0, slices: 0, tasks: 0 };
+}
+
+function sameCounts(a: HierarchyCounts, b: HierarchyCounts): boolean {
+  return a.milestones === b.milestones && a.slices === b.slices && a.tasks === b.tasks;
+}
+
+export function countMarkdownHierarchy(basePath: string): HierarchyCounts {
+  const root = milestonesDir(basePath);
+  if (!existsSync(root)) return zeroCounts();
+
+  const counts = zeroCounts();
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !/^M\d+/.test(entry.name)) continue;
+    counts.milestones++;
+
+    const roadmapPath = resolveMilestoneFile(basePath, entry.name, "ROADMAP");
+    if (!roadmapPath || !existsSync(roadmapPath)) continue;
+
+    const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
+    counts.slices += roadmap.slices.length;
+
+    for (const slice of roadmap.slices) {
+      const planPath = resolveSliceFile(basePath, entry.name, slice.id, "PLAN");
+      if (!planPath || !existsSync(planPath)) continue;
+      const plan = parsePlan(readFileSync(planPath, "utf-8"));
+      counts.tasks += plan.tasks.length;
+    }
+  }
+
+  return counts;
+}
+
+export function countDbHierarchy(): HierarchyCounts {
+  if (!isDbAvailable()) return zeroCounts();
+  const counts = zeroCounts();
+  const milestones = getAllMilestones();
+  counts.milestones = milestones.length;
+
+  for (const milestone of milestones) {
+    const slices = getMilestoneSlices(milestone.id);
+    counts.slices += slices.length;
+    for (const slice of slices) {
+      counts.tasks += getSliceTasks(milestone.id, slice.id).length;
+    }
+  }
+
+  return counts;
+}
+
+export async function autoImportMarkdownHierarchyIfDbMismatch(
+  basePath: string,
+): Promise<MigrationAutoCheckResult> {
+  const markdown = countMarkdownHierarchy(basePath);
+  if (sameCounts(markdown, zeroCounts())) {
+    return {
+      action: "none",
+      reason: "no-markdown",
+      markdown,
+      beforeDb: zeroCounts(),
+      afterDb: zeroCounts(),
+    };
+  }
+
+  const opened = await ensureDbOpen(basePath);
+  if (!opened || !isDbAvailable()) {
+    throw new Error(`failed to open or create the GSD database at ${basePath}`);
+  }
+
+  const beforeDb = countDbHierarchy();
+  if (sameCounts(markdown, beforeDb)) {
+    return { action: "none", reason: "in-sync", markdown, beforeDb, afterDb: beforeDb };
+  }
+
+  const reason = sameCounts(beforeDb, zeroCounts()) ? "db-empty" : "count-mismatch";
+  const imported = transaction(() => {
+    clearEngineHierarchy();
+    return migrateHierarchyToDb(basePath);
+  });
+  invalidateStateCache();
+
+  const afterDb = {
+    milestones: imported.milestones,
+    slices: imported.slices,
+    tasks: imported.tasks,
+  };
+  if (!sameCounts(markdown, afterDb)) {
+    throw new Error(
+      `migration auto-import verification failed: markdown ${markdown.milestones}M/${markdown.slices}S/${markdown.tasks}T, db ${afterDb.milestones}M/${afterDb.slices}S/${afterDb.tasks}T`,
+    );
+  }
+
+  return { action: "imported", reason, markdown, beforeDb, afterDb };
+}

package/src/resources/extensions/gsd/planning-path-scope.ts

@@ -0,0 +1,35 @@
+import { isAbsolute, relative, resolve } from "node:path";
+import { normalizePlannedFileReference } from "./files.js";
+
+export interface PlanningPathScopeField {
+  field: string;
+  values: string[];
+}
+
+function isInsideBase(basePath: string, candidate: string): boolean {
+  const base = resolve(basePath);
+  const abs = resolve(candidate);
+  const rel = relative(base, abs);
+  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/**
+ * Planning IO fields are execution contracts. Absolute paths are only safe when
+ * they stay inside the active working directory; in worktree mode, an absolute
+ * path to the original checkout makes executors edit the wrong tree.
+ */
+export function validatePlanningPathScope(
+  basePath: string,
+  fields: PlanningPathScopeField[],
+): string | null {
+  for (const { field, values } of fields) {
+    for (const raw of values) {
+      const candidate = normalizePlannedFileReference(raw);
+      if (!isAbsolute(candidate)) continue;
+      if (isInsideBase(basePath, candidate)) continue;
+      return `${field} contains absolute path outside working directory: ${candidate}. Use a path relative to ${basePath}.`;
+    }
+  }
+
+  return null;
+}

package/src/resources/extensions/gsd/preferences-types.ts

@@ -32,7 +32,7 @@ export interface ContextManagementConfig {
 /**
  * Opt-in tool-output sandboxing for sub-sessions. When enabled, the gsd_exec
  * MCP tool runs scripts in an isolated subprocess and returns only a short
- * digest to the calling agent's context window; full stdout/stderr persist
+ * digest to the calling agent's context window; capped stdout/stderr persist
  * in the project memory store and can be retrieved by id later.
  *
  * Inspired by mksglu/context-mode (Elastic License 2.0). This is an

package/src/resources/extensions/gsd/prompt-loader.ts

@@ -123,17 +123,42 @@ function warmCache(): void {
 }
 
 let warmCacheScheduled = false;
+let warmCacheRan = false;
+let warmCacheTimer: ReturnType<typeof setTimeout> | undefined;
+
+/**
+ * Synchronously snapshot the prompt/template tree into the cache.
+ *
+ * Safe to call immediately after `initResources()` because that function uses
+ * synchronous fs APIs — there is no race window that requires deferring the
+ * cache warm via setTimeout. Idempotent: subsequent calls are no-ops.
+ *
+ * Cancels the fallback `scheduleWarmCache` timer if it is still pending.
+ */
+export function primeCache(): void {
+  if (warmCacheRan) return;
+  if (warmCacheTimer) {
+    clearTimeout(warmCacheTimer);
+    warmCacheTimer = undefined;
+  }
+  warmCacheScheduled = true;
+  warmCacheRan = true;
+  warmCache();
+}
 
 function scheduleWarmCache(): void {
   if (warmCacheScheduled) return;
   warmCacheScheduled = true;
 
   const run = () => {
+    warmCacheTimer = undefined;
+    if (warmCacheRan) return;
+    warmCacheRan = true;
     warmCache();
   };
 
-  const timer = setTimeout(run, 1000);
-  timer.unref?.();
+  warmCacheTimer = setTimeout(run, 1000);
+  warmCacheTimer.unref?.();
 }
 
 // Snapshot the full prompt/template tree after import so extension startup only

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

@@ -29,14 +29,15 @@ Subagents report only; they do not write user source. Fold any findings into Dec
 
 ## Steps
 
-1. Use the **Milestone Summary** output template from the inlined context above
-2. {{skillActivation}}
-3. **Verify code changes exist.** Compare milestone work against the integration branch (`main`, `master`, or recorded branch), using merge-base as older revision and `HEAD` as newer. If the diff lists non-`.gsd/` files, pass. If `HEAD` equals the integration branch/merge-base, treat it as a self-diff retry: inspect milestone-scoped commit evidence (`GSD-Unit: {{milestoneId}}` or production `GSD-Task: Sxx/Tyy` trailers touching `.gsd/milestones/{{milestoneId}}/`) and verify those commits touched non-`.gsd/` files. Record **verification failure** only when neither source shows implementation files.
-4. Verify every **success criterion** from `{{roadmapPath}}`. If passing validation is present, summarize the validation evidence instead of re-auditing it; otherwise verify with evidence from summaries, tests, or observable behavior. Record unmet criteria as **verification failure**.
-5. Verify **definition of done**: all slices `[x]`, summaries exist, and integrations work. If passing validation is present, trust its integration/verification verdict unless inconsistent with current artifacts. Record unmet items as **verification failure**.
-6. If the roadmap includes a **Horizontal Checklist**, verify each item and note unchecked items in the summary.
-7. Fill the **Decision Re-evaluation** table: compare each key `.gsd/DECISIONS.md` decision from this milestone with what shipped, and flag decisions to revisit.
-8. Validate **requirement status transitions**. For each changed requirement, confirm evidence supports the new status. Requirements may move between Active, Validated, Deferred, Blocked, or Out of Scope only with proof.
+1. **Duplicate completion guard:** Call `gsd_milestone_status` for `{{milestoneId}}` before any durable writes. If the returned milestone **status is `complete`**, this is a stale or duplicate closeout turn: do NOT mutate requirements, do NOT refresh the project document, do NOT write LEARNINGS, and do NOT persist milestone completion again. Say: "Milestone {{milestoneId}} is already complete." and stop.
+2. Use the **Milestone Summary** output template from the inlined context above
+3. {{skillActivation}}
+4. **Verify code changes exist.** Compare milestone work against the integration branch (`main`, `master`, or recorded branch), using merge-base as older revision and `HEAD` as newer. If the diff lists non-`.gsd/` files, pass. If `HEAD` equals the integration branch/merge-base, treat it as a self-diff retry: inspect milestone-scoped commit evidence (`GSD-Unit: {{milestoneId}}` or production `GSD-Task: Sxx/Tyy` trailers touching `.gsd/milestones/{{milestoneId}}/`) and verify those commits touched non-`.gsd/` files. Record **verification failure** only when neither source shows implementation files.
+5. Verify every **success criterion** from `{{roadmapPath}}`. If passing validation is present, summarize the validation evidence instead of re-auditing it; otherwise verify with evidence from summaries, tests, or observable behavior. Record unmet criteria as **verification failure**.
+6. Verify **definition of done**: all slices `[x]`, summaries exist, and integrations work. If passing validation is present, trust its integration/verification verdict unless inconsistent with current artifacts. Record unmet items as **verification failure**.
+7. If the roadmap includes a **Horizontal Checklist**, verify each item and note unchecked items in the summary.
+8. Fill the **Decision Re-evaluation** table: compare each key `.gsd/DECISIONS.md` decision from this milestone with what shipped, and flag decisions to revisit.
+9. Validate **requirement status transitions**. For each changed requirement, confirm evidence supports the new status. Requirements may move between Active, Validated, Deferred, Blocked, or Out of Scope only with proof.
 
 **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`, inlined context, or `gsd_*` tools; never direct SQL.
 
@@ -53,13 +54,13 @@ Subagents report only; they do not write user source. Fold any findings into Dec
 
 **Success path** (all verifications passed):
 
-9. For each requirement whose status changed in step 8, call `gsd_requirement_update` with the requirement ID and updated `status` and `validation` fields — the tool regenerates `.gsd/REQUIREMENTS.md` automatically. Do this BEFORE completing the milestone so requirement updates are persisted.
-10. Update `.gsd/PROJECT.md`: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting milestone completion and current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh.
-11. Extract structured learnings from this milestone and persist them to the GSD memory store. Follow the procedure block immediately below — it writes `{{milestoneId}}-LEARNINGS.md` as the audit trail and persists Patterns, Lessons, and Decisions via `capture_thought` (categories: pattern, gotcha/convention, architecture). The memory store is the single source of truth for cross-session durable knowledge (ADR-013).
+10. For each requirement whose status changed in step 9, call `gsd_requirement_update` with the requirement ID and updated `status` and `validation` fields — the tool regenerates `.gsd/REQUIREMENTS.md` automatically. Do this BEFORE completing the milestone so requirement updates are persisted.
+11. Update `.gsd/PROJECT.md`: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting milestone completion and current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh.
+12. Extract structured learnings from this milestone and persist them to the GSD memory store. Follow the procedure block immediately below — it writes `{{milestoneId}}-LEARNINGS.md` as the audit trail and persists Patterns, Lessons, and Decisions via `capture_thought` (categories: pattern, gotcha/convention, architecture). The memory store is the single source of truth for cross-session durable knowledge (ADR-013).
 
 {{extractLearningsSteps}}
 
-12. **Persist completion through `gsd_complete_milestone`.** Call it with the parameters below. This must be the final persistent write in the unit. The tool updates the milestone status in the DB, renders `{{milestoneSummaryPath}}`, and validates all slices are complete.
+13. **Persist completion through `gsd_complete_milestone`.** Call it with the parameters below. This must be the final persistent write in the unit. The tool updates the milestone status in the DB, renders `{{milestoneSummaryPath}}`, and validates all slices are complete.
 
    **Required parameters:**
    - `milestoneId` (string) — Milestone ID (e.g. M001)
@@ -78,7 +79,7 @@ Subagents report only; they do not write user source. Fold any findings into Dec
    - `followUps` (string) — Follow-up items for future milestones
    - `deviations` (string) — Deviations from the original plan
 
-13. Do not commit manually — the system auto-commits your changes after this unit completes.
+14. Do not commit manually — the system auto-commits your changes after this unit completes.
 - Say: "Milestone {{milestoneId}} complete."
 
 **Important:** Do NOT skip code-change, success-criteria, or definition-of-done verification (steps 3-5). The summary must reflect verified outcomes. Verification failures block completion; there is no override. If a verification tool fails, errors, or returns unexpected output, treat it as failure.

package/src/resources/extensions/gsd/prompts/parallel-research-slices.md

@@ -16,7 +16,7 @@ Dispatch ALL slices simultaneously using the `subagent` tool in **parallel mode*
 
 1. Call `subagent` with `tasks: [...]` containing one entry per slice below
 2. Wait for ALL subagents to complete
-3. Verify each slice's RESEARCH file was written (check the `.gsd/{{mid}}/` directory)
+3. Verify each slice's RESEARCH file was written (check `.gsd/milestones/{{mid}}/slices/<slice-id>/`)
 4. If a subagent failed to write its RESEARCH file, retry it **once** individually
 5. If it fails a second time, write a partial RESEARCH file for that slice with a `## BLOCKER` section explaining the failure — do NOT retry again
 6. Report which slices completed research and which (if any) needed a blocker note

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

@@ -39,7 +39,7 @@ If slice research is inlined, trust it. Explore enough code to confirm paths, bo
 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/`.
 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. Each task needs a concrete title, Why / Files / Do / Verify / Done when, plus task-plan description, steps, must-haves, verification, inputs, and expected output. Inputs and Expected Output must include concrete backtick-wrapped paths; each task needs at least one output path.
+8. Each task needs a concrete title, Why / Files / Do / Verify / Done when, plus task-plan description, steps, must-haves, verification, inputs, and expected output. Inputs and Expected Output must include concrete backtick-wrapped paths; each task needs at least one output path. 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.
 9. Persist with `gsd_plan_slice` using goal, successCriteria, optional 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.
 10. Self-audit before finishing: goal/demo closure, requirement coverage, 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.
 11. If planning creates structural decisions, append them to `.gsd/DECISIONS.md`.

package/src/resources/extensions/gsd/prompts/quick-task.md

@@ -17,11 +17,7 @@ You are executing a GSD quick task — a lightweight, focused unit of work outsi
 5. Verify your work:
    - Run tests if applicable.
    - Verify both happy path and failure modes for non-trivial changes.
-6. 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.
+6. {{commitInstruction}}
 7. Write a brief summary to `{{summaryPath}}`:
    - Quick tasks operate outside the milestone/slice/task DB structure, so `gsd_summary_save` (which requires a `milestone_id`) cannot be used here. Write the file directly.
 

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

@@ -27,13 +27,13 @@ Roadmap, slice summaries, assessments, requirements, decisions, and project cont
 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. For each requirement, check slice SUMMARY files in `.gsd/{{milestoneId}}/` 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."
+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, 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 criteria. Check slice ASSESSMENT files. Verify each criterion maps to a passing assessment or clear SUMMARY 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."
+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
 

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/tests/auto-loop.test.ts

@@ -10,6 +10,8 @@ import {
   _resetPendingResolve,
   _hasPendingResolveForTest,
   _setActiveSession,
+  _setSessionSwitchInFlight,
+  _consumePendingSwitchCancellation,
   isSessionSwitchInFlight,
 } from "../auto/resolve.js";
 import { runUnit } from "../auto/run-unit.js";
@@ -206,6 +208,28 @@ test("runUnit returns cancelled when session creation fails", async () => {
   assert.equal(pi.calls.length, 0);
 });
 
+test("runUnit clears queued switch cancellation when session creation fails", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  const pi = makeMockPi();
+  const s = makeMockSession({
+    newSessionThrows: "connection refused",
+    onNewSessionStart: () => {
+      resolveAgentEndCancelled({
+        message: "Claude Code process aborted by user",
+        category: "aborted",
+        isTransient: false,
+      });
+    },
+  });
+
+  const result = await runUnit(ctx, pi, s, "task", "T01", "prompt");
+
+  assert.equal(result.status, "cancelled");
+  assert.equal(_consumePendingSwitchCancellation(), null);
+});
+
 test("runUnit returns cancelled when session creation times out", async () => {
   _resetPendingResolve();
 
@@ -221,6 +245,34 @@ test("runUnit returns cancelled when session creation times out", async () => {
   assert.equal(pi.calls.length, 0);
 });
 
+test("runUnit consumes a cancellation queued during session switch before dispatch", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  const pi = makeMockPi();
+  let cancellationQueued = false;
+  const s = makeMockSession({
+    newSessionDelayMs: 10,
+    onNewSessionStart: () => {
+      setTimeout(() => {
+        cancellationQueued = !resolveAgentEndCancelled({
+          message: "Claude Code process aborted by user",
+          category: "aborted",
+          isTransient: false,
+        });
+      }, 0);
+    },
+  });
+
+  const result = await runUnit(ctx, pi, s, "plan-slice", "M009/S01", "prompt");
+
+  assert.equal(cancellationQueued, true);
+  assert.equal(result.status, "cancelled");
+  assert.equal(result.errorContext?.category, "aborted");
+  assert.equal(result.errorContext?.message, "Claude Code process aborted by user");
+  assert.equal(pi.calls.length, 0, "queued switch cancellation must prevent prompt dispatch");
+});
+
 test("runUnit keeps the session-switch guard across a late newSession settlement", async () => {
   _resetPendingResolve();
   mock.timers.enable();
@@ -2089,6 +2141,25 @@ test("resolveAgentEndCancelled without args produces no errorContext field", asy
   assert.equal(resolved.errorContext, undefined, "errorContext must not be present when no args passed");
 });
 
+test("resolveAgentEndCancelled queues cancellation that arrives during session switch", () => {
+  _resetPendingResolve();
+
+  _setSessionSwitchInFlight(true);
+  const resolved = resolveAgentEndCancelled({
+    message: "Claude Code process aborted by user",
+    category: "aborted",
+    isTransient: false,
+  });
+
+  assert.equal(resolved, false);
+  const pending = _consumePendingSwitchCancellation();
+  assert.ok(pending?.errorContext, "queued cancellation should preserve errorContext");
+  assert.equal(pending.errorContext.category, "aborted");
+  assert.equal(pending.errorContext.message, "Claude Code process aborted by user");
+  assert.equal(_consumePendingSwitchCancellation(), null);
+  _resetPendingResolve();
+});
+
 // ─── #1571: artifact verification retry ──────────────────────────────────────
 
 test("autoLoop re-iterates when postUnitPreVerification returns retry (#1571)", async () => {

package/src/resources/extensions/gsd/tests/auto-phases-lifecycle.test.ts

@@ -1,17 +1,20 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
 
 import { runFinalize } from "../auto/phases.ts";
 import { AutoSession } from "../auto/session.ts";
+import { readUnitRuntimeRecord, writeUnitRuntimeRecord } from "../unit-runtime.ts";
 
-test("runFinalize clears currentUnit after successful finalize", async () => {
-  const s = new AutoSession();
-  s.basePath = "/tmp/gsd-finalize-current-unit";
-  s.currentUnit = {
-    type: "execute-task",
-    id: "M001/S01/T01",
-    startedAt: Date.now(),
-  };
+async function runSuccessfulFinalize(s: AutoSession) {
+  const unit = s.currentUnit;
+  assert.ok(unit, "test setup must provide currentUnit");
+
+  writeUnitRuntimeRecord(s.basePath, unit.type, unit.id, unit.startedAt, {
+    phase: "dispatched",
+  });
 
   const deps = {
     clearUnitTimeout() {},
@@ -26,7 +29,7 @@ test("runFinalize clears currentUnit after successful finalize", async () => {
     postUnitPostVerification: async () => "continue",
   };
 
-  const result = await runFinalize(
+  return runFinalize(
     {
       ctx: { ui: { notify() {} } },
       pi: {},
@@ -38,8 +41,8 @@ test("runFinalize clears currentUnit after successful finalize", async () => {
       nextSeq: () => 1,
     } as any,
     {
-      unitType: "execute-task",
-      unitId: "M001/S01/T01",
+      unitType: unit.type,
+      unitId: unit.id,
       prompt: "",
       finalPrompt: "",
       pauseAfterUatDispatch: false,
@@ -55,7 +58,47 @@ test("runFinalize clears currentUnit after successful finalize", async () => {
       consecutiveFinalizeTimeouts: 0,
     },
   );
+}
+
+test("runFinalize clears currentUnit after successful finalize", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-finalize-current-unit-"));
+  const s = new AutoSession();
+  s.basePath = base;
+  s.currentUnit = {
+    type: "execute-task",
+    id: "M001/S01/T01",
+    startedAt: Date.now(),
+  };
+
+  try {
+    const result = await runSuccessfulFinalize(s);
+
+    assert.equal(result.action, "next");
+    assert.equal(s.currentUnit, null);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("runFinalize marks unit runtime finalized after successful finalize", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-finalize-runtime-"));
+  const s = new AutoSession();
+  const startedAt = Date.now();
+  s.basePath = base;
+  s.currentUnit = {
+    type: "complete-milestone",
+    id: "M001",
+    startedAt,
+  };
+
+  try {
+    const result = await runSuccessfulFinalize(s);
+    const runtime = readUnitRuntimeRecord(base, "complete-milestone", "M001");
 
-  assert.equal(result.action, "next");
-  assert.equal(s.currentUnit, null);
+    assert.equal(result.action, "next");
+    assert.equal(runtime?.phase, "finalized");
+    assert.equal(runtime?.lastProgressKind, "finalize-success");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
 });

package/src/resources/extensions/gsd/tests/auto-recovery.test.ts

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 
-import { verifyExpectedArtifact, hasImplementationArtifacts, resolveExpectedArtifactPath, diagnoseExpectedArtifact, buildLoopRemediationSteps, writeBlockerPlaceholder } from "../auto-recovery.ts";
+import { verifyExpectedArtifact, hasImplementationArtifacts, resolveExpectedArtifactPath, diagnoseExpectedArtifact, buildLoopRemediationSteps, writeBlockerPlaceholder, refreshRecoveryDbForArtifact } from "../auto-recovery.ts";
 import { resolveMilestoneFile } from "../paths.ts";
 import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertGateRow, insertTask, getMilestoneCommitAttributionShas } from "../gsd-db.ts";
 import { clearParseCache } from "../files.ts";
@@ -175,6 +175,19 @@ test("resolveExpectedArtifactPath returns correct path for all slice-level types
   }
 });
 
+test("refreshRecoveryDbForArtifact treats missing execute-task DB rows as fatal mismatches", () => {
+  makeTmpProject();
+
+  const result = refreshRecoveryDbForArtifact("execute-task", "M001/S01/T01");
+
+  assert.deepEqual(result, {
+    ok: false,
+    fatal: true,
+    reason: "execute-task-artifact-db-missing",
+    message: "Stuck recovery found execute-task M001/S01/T01 artifacts, but no matching DB task row exists after refresh.",
+  });
+});
+
 // ─── diagnoseExpectedArtifact ─────────────────────────────────────────────
 
 test("diagnoseExpectedArtifact returns description for known types", () => {

package/src/resources/extensions/gsd/tests/compaction-snapshot.test.ts

@@ -29,7 +29,8 @@ test('buildSnapshot: renders memories, exec history, and active context', () =>
     memories: [
       { id: 'MEM001', category: 'gotcha', content: 'FTS5 needs Porter tokenizer', confidence: 0.9,
         source_unit_type: null, source_unit_id: null, created_at: '', updated_at: '',
-        superseded_by: null, hit_count: 0, scope: 'project', seq: 1, tags: [], structured_fields: null },
+        superseded_by: null, hit_count: 0, scope: 'project', seq: 1, tags: [], structured_fields: null,
+        last_hit_at: null },
     ],
     execHistory: [
       {
@@ -65,6 +66,7 @@ test('buildSnapshot: enforces the byte cap with a truncation marker', () => {
     seq: i,
     tags: [] as string[],
     structured_fields: null,
+    last_hit_at: null,
   }));
   const snap = buildSnapshot(
     { generatedAt: new Date(), memories: longMemories, execHistory: [] },
@@ -121,3 +123,14 @@ test('executeResume: reports friendly empty state when no snapshot exists', () =
     cleanup(base);
   }
 });
+
+test('executeResume: returns disabled error when context_mode.enabled=false', () => {
+  const base = freshBase();
+  try {
+    const result = executeResume({}, { baseDir: base, preferences: { context_mode: { enabled: false } } });
+    assert.equal(result.isError, true);
+    assert.equal((result.details as { error?: string }).error, 'context_mode_disabled');
+  } finally {
+    cleanup(base);
+  }
+});