@tuan_son.dinh/gsd 2.6.0

package/src/resources/extensions/gsd/tests/worktree.test.ts

@@ -0,0 +1,264 @@
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+
+import {
+  autoCommitCurrentBranch,
+  detectWorktreeName,
+  ensureSliceBranch,
+  getActiveSliceBranch,
+  getCurrentBranch,
+  getSliceBranchName,
+  isOnSliceBranch,
+  mergeSliceToMain,
+  parseSliceBranch,
+  SLICE_BRANCH_RE,
+  switchToMain,
+} from "../worktree.ts";
+import { deriveState } from "../state.ts";
+import { indexWorkspace } from "../workspace-index.ts";
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition: boolean, message: string): void {
+  if (condition) passed++;
+  else {
+    failed++;
+    console.error(`  FAIL: ${message}`);
+  }
+}
+
+function assertEq<T>(actual: T, expected: T, message: string): void {
+  if (JSON.stringify(actual) === JSON.stringify(expected)) passed++;
+  else {
+    failed++;
+    console.error(`  FAIL: ${message} — expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+  }
+}
+
+function run(command: string, cwd: string): string {
+  return execSync(command, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+}
+
+const base = mkdtempSync(join(tmpdir(), "gsd-branch-test-"));
+run("git init -b main", base);
+run("git config user.name 'Pi Test'", base);
+run("git config user.email 'pi@example.com'", base);
+mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks"), { recursive: true });
+writeFileSync(join(base, "README.md"), "hello\n", "utf-8");
+writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"), `# M001: Demo\n\n## Slices\n- [ ] **S01: Slice One** \`risk:low\` \`depends:[]\`\n  > After this: demo works\n`, "utf-8");
+writeFileSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md"), `# S01: Slice One\n\n**Goal:** Demo\n**Demo:** Demo\n\n## Must-Haves\n- done\n\n## Tasks\n- [ ] **T01: Implement** \`est:10m\`\n  do it\n`, "utf-8");
+run("git add .", base);
+run("git commit -m 'chore: init'", base);
+
+async function main(): Promise<void> {
+  console.log("\n=== ensureSliceBranch ===");
+  const created = ensureSliceBranch(base, "M001", "S01");
+  assert(created, "branch created on first ensure");
+  assertEq(getCurrentBranch(base), "gsd/M001/S01", "switched to slice branch");
+
+  console.log("\n=== idempotent ensure ===");
+  const secondCreate = ensureSliceBranch(base, "M001", "S01");
+  assertEq(secondCreate, false, "branch not recreated on second ensure");
+  assertEq(getCurrentBranch(base), "gsd/M001/S01", "still on slice branch");
+
+  console.log("\n=== getActiveSliceBranch ===");
+  assertEq(getActiveSliceBranch(base), "gsd/M001/S01", "getActiveSliceBranch returns current slice branch");
+
+  console.log("\n=== state surfaces active branch ===");
+  const state = await deriveState(base);
+  assertEq(state.activeBranch, "gsd/M001/S01", "state exposes active branch");
+
+  console.log("\n=== workspace index surfaces branch ===");
+  const index = await indexWorkspace(base);
+  const slice = index.milestones[0]?.slices[0];
+  assertEq(slice?.branch, "gsd/M001/S01", "workspace index exposes branch");
+
+  console.log("\n=== autoCommitCurrentBranch ===");
+  // Clean — should return null
+  const cleanResult = autoCommitCurrentBranch(base, "execute-task", "M001/S01/T01");
+  assertEq(cleanResult, null, "returns null for clean repo");
+
+  // Make dirty
+  writeFileSync(join(base, "dirty.txt"), "uncommitted\n", "utf-8");
+  const dirtyResult = autoCommitCurrentBranch(base, "execute-task", "M001/S01/T01");
+  assert(dirtyResult !== null, "returns commit message for dirty repo");
+  assert(dirtyResult!.includes("M001/S01/T01"), "commit message includes unit id");
+  assertEq(run("git status --short", base), "", "repo is clean after auto-commit");
+
+  console.log("\n=== switchToMain ===");
+  switchToMain(base);
+  assertEq(getCurrentBranch(base), "main", "switched back to main");
+  assertEq(getActiveSliceBranch(base), null, "getActiveSliceBranch returns null on main");
+
+  console.log("\n=== mergeSliceToMain ===");
+  // Switch back to slice, make a change, switch to main, merge
+  ensureSliceBranch(base, "M001", "S01");
+  writeFileSync(join(base, "README.md"), "hello from slice\n", "utf-8");
+  run("git add README.md", base);
+  run("git commit -m 'feat: slice change'", base);
+  switchToMain(base);
+
+  const merge = mergeSliceToMain(base, "M001", "S01", "Slice One");
+  assertEq(merge.branch, "gsd/M001/S01", "merge reports branch");
+  assertEq(getCurrentBranch(base), "main", "still on main after merge");
+  assert(readFileSync(join(base, "README.md"), "utf-8").includes("slice"), "main got squashed content");
+  assert(merge.deletedBranch, "branch was deleted");
+
+  // Verify branch is actually gone
+  const branches = run("git branch", base);
+  assert(!branches.includes("gsd/M001/S01"), "slice branch no longer exists");
+
+  console.log("\n=== switchToMain auto-commits dirty files ===");
+  // Set up S02
+  mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S02", "tasks"), { recursive: true });
+  writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"), [
+    "# M001: Demo", "", "## Slices",
+    "- [x] **S01: Slice One** `risk:low` `depends:[]`", "  > Done",
+    "- [ ] **S02: Slice Two** `risk:low` `depends:[]`", "  > Demo 2",
+  ].join("\n") + "\n", "utf-8");
+  run("git add .", base);
+  run("git commit -m 'chore: add S02'", base);
+
+  ensureSliceBranch(base, "M001", "S02");
+  writeFileSync(join(base, "feature.txt"), "new feature\n", "utf-8");
+  // Don't commit — switchToMain should auto-commit
+  switchToMain(base);
+  assertEq(getCurrentBranch(base), "main", "switched to main despite dirty files");
+
+  // Verify the commit happened on the slice branch
+  ensureSliceBranch(base, "M001", "S02");
+  assert(readFileSync(join(base, "feature.txt"), "utf-8").includes("new feature"), "dirty file was committed on slice branch");
+  switchToMain(base);
+
+  // Now merge S02
+  const mergeS02 = mergeSliceToMain(base, "M001", "S02", "Slice Two");
+  assert(readFileSync(join(base, "feature.txt"), "utf-8").includes("new feature"), "main got feature from auto-committed branch");
+  assertEq(mergeS02.deletedBranch, true, "S02 branch deleted");
+
+  console.log("\n=== getSliceBranchName ===");
+  assertEq(getSliceBranchName("M001", "S01"), "gsd/M001/S01", "branch name format correct");
+  assertEq(getSliceBranchName("M001", "S01", null), "gsd/M001/S01", "null worktree = plain branch");
+  assertEq(getSliceBranchName("M001", "S01", "my-wt"), "gsd/my-wt/M001/S01", "worktree-namespaced branch");
+
+  console.log("\n=== parseSliceBranch ===");
+  const plain = parseSliceBranch("gsd/M001/S01");
+  assert(plain !== null, "parses plain branch");
+  assertEq(plain!.worktreeName, null, "plain branch has no worktree name");
+  assertEq(plain!.milestoneId, "M001", "plain branch milestone");
+  assertEq(plain!.sliceId, "S01", "plain branch slice");
+
+  const namespaced = parseSliceBranch("gsd/feature-auth/M001/S01");
+  assert(namespaced !== null, "parses worktree-namespaced branch");
+  assertEq(namespaced!.worktreeName, "feature-auth", "worktree name extracted");
+  assertEq(namespaced!.milestoneId, "M001", "namespaced branch milestone");
+  assertEq(namespaced!.sliceId, "S01", "namespaced branch slice");
+
+  const invalid = parseSliceBranch("main");
+  assertEq(invalid, null, "non-slice branch returns null");
+
+  const worktreeBranch = parseSliceBranch("worktree/foo");
+  assertEq(worktreeBranch, null, "worktree/ prefix is not a slice branch");
+
+  console.log("\n=== SLICE_BRANCH_RE ===");
+  assert(SLICE_BRANCH_RE.test("gsd/M001/S01"), "regex matches plain branch");
+  assert(SLICE_BRANCH_RE.test("gsd/my-wt/M001/S01"), "regex matches worktree branch");
+  assert(!SLICE_BRANCH_RE.test("main"), "regex rejects main");
+  assert(!SLICE_BRANCH_RE.test("gsd/"), "regex rejects bare gsd/");
+  assert(!SLICE_BRANCH_RE.test("worktree/foo"), "regex rejects worktree/foo");
+
+  console.log("\n=== detectWorktreeName ===");
+  assertEq(detectWorktreeName("/projects/myapp"), null, "no worktree in plain path");
+  assertEq(detectWorktreeName("/projects/myapp/.gsd/worktrees/feature-auth"), "feature-auth", "detects worktree name");
+  assertEq(detectWorktreeName("/projects/myapp/.gsd/worktrees/my-wt/subdir"), "my-wt", "detects worktree with subdir");
+
+  // ── Regression: slice branch from non-main working branch ───────────
+  // Reproduces the bug where planning artifacts committed to a working
+  // branch (e.g. "developer") are lost when the slice branch is created
+  // from "main" which doesn't have them.
+  console.log("\n=== ensureSliceBranch from non-main working branch ===");
+  const base2 = mkdtempSync(join(tmpdir(), "gsd-branch-base-test-"));
+  run("git init -b main", base2);
+  run("git config user.name 'Pi Test'", base2);
+  run("git config user.email 'pi@example.com'", base2);
+  writeFileSync(join(base2, "README.md"), "hello\n", "utf-8");
+  run("git add .", base2);
+  run("git commit -m 'chore: init'", base2);
+
+  // Create a "developer" branch with planning artifacts (like the real scenario)
+  run("git checkout -b developer", base2);
+  mkdirSync(join(base2, ".gsd", "milestones", "M001", "slices", "S01", "tasks"), { recursive: true });
+  writeFileSync(join(base2, ".gsd", "milestones", "M001", "M001-CONTEXT.md"), "# M001 Context\nGoal: fix eslint\n", "utf-8");
+  writeFileSync(join(base2, ".gsd", "milestones", "M001", "M001-ROADMAP.md"), [
+    "# M001: ESLint Cleanup", "", "## Slices",
+    "- [ ] **S01: Config Fix** `risk:low` `depends:[]`", "  > Fix config",
+  ].join("\n") + "\n", "utf-8");
+  run("git add .", base2);
+  run("git commit -m 'docs(M001): context and roadmap'", base2);
+
+  // Verify main does NOT have the artifacts
+  const mainRoadmap = run("git show main:.gsd/milestones/M001/M001-ROADMAP.md 2>&1 || echo MISSING", base2);
+  assert(mainRoadmap.includes("MISSING") || mainRoadmap.includes("does not exist"), "main branch lacks roadmap");
+
+  // Now create slice branch from developer — should inherit artifacts
+  assertEq(getCurrentBranch(base2), "developer", "on developer branch before ensure");
+  const created3 = ensureSliceBranch(base2, "M001", "S01");
+  assert(created3, "slice branch created from developer");
+  assertEq(getCurrentBranch(base2), "gsd/M001/S01", "switched to slice branch");
+
+  // The critical assertion: planning artifacts must exist on the slice branch
+  assert(existsSync(join(base2, ".gsd", "milestones", "M001", "M001-ROADMAP.md")), "roadmap exists on slice branch");
+  assert(existsSync(join(base2, ".gsd", "milestones", "M001", "M001-CONTEXT.md")), "context exists on slice branch");
+
+  // Verify deriveState sees the correct phase (not pre-planning)
+  const state2 = await deriveState(base2);
+  assertEq(state2.phase, "planning", "deriveState sees planning phase on slice branch");
+  assert(state2.activeSlice !== null, "active slice found");
+  assertEq(state2.activeSlice!.id, "S01", "active slice is S01");
+
+  rmSync(base2, { recursive: true, force: true });
+
+  // ── Slice branch from another slice branch falls back to main ───────
+  console.log("\n=== ensureSliceBranch from slice branch falls back to main ===");
+  const base3 = mkdtempSync(join(tmpdir(), "gsd-branch-chain-test-"));
+  run("git init -b main", base3);
+  run("git config user.name 'Pi Test'", base3);
+  run("git config user.email 'pi@example.com'", base3);
+  mkdirSync(join(base3, ".gsd", "milestones", "M001", "slices", "S01", "tasks"), { recursive: true });
+  mkdirSync(join(base3, ".gsd", "milestones", "M001", "slices", "S02", "tasks"), { recursive: true });
+  writeFileSync(join(base3, "README.md"), "hello\n", "utf-8");
+  writeFileSync(join(base3, ".gsd", "milestones", "M001", "M001-ROADMAP.md"), [
+    "# M001: Demo", "", "## Slices",
+    "- [ ] **S01: First** `risk:low` `depends:[]`", "  > first",
+    "- [ ] **S02: Second** `risk:low` `depends:[]`", "  > second",
+  ].join("\n") + "\n", "utf-8");
+  run("git add .", base3);
+  run("git commit -m 'chore: init'", base3);
+
+  ensureSliceBranch(base3, "M001", "S01");
+  assertEq(getCurrentBranch(base3), "gsd/M001/S01", "on S01 slice branch");
+
+  // Creating S02 while on S01 should NOT chain from S01 — should use main
+  const created4 = ensureSliceBranch(base3, "M001", "S02");
+  assert(created4, "S02 branch created");
+  assertEq(getCurrentBranch(base3), "gsd/M001/S02", "switched to S02");
+
+  // S02 should be based on main, not on gsd/M001/S01
+  const s02Base = run("git merge-base main gsd/M001/S02", base3);
+  const mainHead = run("git rev-parse main", base3);
+  assertEq(s02Base, mainHead, "S02 is based on main, not on S01 slice branch");
+
+  rmSync(base3, { recursive: true, force: true });
+
+  rmSync(base, { recursive: true, force: true });
+  console.log(`\nResults: ${passed} passed, ${failed} failed`);
+  if (failed > 0) process.exit(1);
+  console.log("All tests passed ✓");
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

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

@@ -0,0 +1,159 @@
+// GSD Extension — Core Type Definitions
+// Types consumed by state derivation, file parsing, and status display.
+// Pure interfaces — no logic, no runtime dependencies.
+
+// ─── Enums & Literal Unions ────────────────────────────────────────────────
+
+export type RiskLevel = 'low' | 'medium' | 'high';
+export type Phase = 'pre-planning' | 'discussing' | 'researching' | 'planning' | 'executing' | 'verifying' | 'summarizing' | 'advancing' | 'completing-milestone' | 'replanning-slice' | 'complete' | 'paused' | 'blocked';
+export type ContinueStatus = 'in_progress' | 'interrupted' | 'compacted';
+
+// ─── Roadmap (Milestone-level) ─────────────────────────────────────────────
+
+export interface RoadmapSliceEntry {
+  id: string;          // e.g. "S01"
+  title: string;       // e.g. "Types + File I/O + Git Operations"
+  risk: RiskLevel;
+  depends: string[];   // e.g. ["S01", "S02"]
+  done: boolean;
+  demo: string;        // the "After this:" sentence
+}
+
+export interface BoundaryMapEntry {
+  fromSlice: string;   // e.g. "S01"
+  toSlice: string;     // e.g. "S02" or "terminal"
+  produces: string;    // raw text block of what this slice produces
+  consumes: string;    // raw text block of what it consumes (or "nothing")
+}
+
+export interface Roadmap {
+  title: string;       // e.g. "M001: GSD Extension — Hierarchical Planning with Auto Mode"
+  vision: string;
+  successCriteria: string[];
+  slices: RoadmapSliceEntry[];
+  boundaryMap: BoundaryMapEntry[];
+}
+
+// ─── Slice Plan ────────────────────────────────────────────────────────────
+
+export interface TaskPlanEntry {
+  id: string;          // e.g. "T01"
+  title: string;       // e.g. "Core Type Definitions"
+  description: string;
+  done: boolean;
+  estimate: string;    // e.g. "30m", "2h" — informational only
+  files?: string[];    // e.g. ["types.ts", "files.ts"] — extracted from "- Files:" subline
+  verify?: string;     // e.g. "run tests" — extracted from "- Verify:" subline
+}
+
+export interface SlicePlan {
+  id: string;          // e.g. "S01"
+  title: string;       // from the H1
+  goal: string;
+  demo: string;
+  mustHaves: string[]; // top-level must-have bullet points
+  tasks: TaskPlanEntry[];
+  filesLikelyTouched: string[];
+}
+
+// ─── Summary (Task & Slice level) ──────────────────────────────────────────
+
+export interface SummaryRequires {
+  slice: string;
+  provides: string;
+}
+
+export interface SummaryFrontmatter {
+  id: string;
+  parent: string;
+  milestone: string;
+  provides: string[];
+  requires: SummaryRequires[];
+  affects: string[];
+  key_files: string[];
+  key_decisions: string[];
+  patterns_established: string[];
+  drill_down_paths: string[];
+  observability_surfaces: string[];
+  duration: string;
+  verification_result: string;
+  completed_at: string;
+  blocker_discovered: boolean;
+}
+
+export interface FileModified {
+  path: string;
+  description: string;
+}
+
+export interface Summary {
+  frontmatter: SummaryFrontmatter;
+  title: string;
+  oneLiner: string;
+  whatHappened: string;
+  deviations: string;
+  filesModified: FileModified[];
+}
+
+// ─── Continue-Here ─────────────────────────────────────────────────────────
+
+export interface ContinueFrontmatter {
+  milestone: string;
+  slice: string;
+  task: string;
+  step: number;
+  totalSteps: number;
+  status: ContinueStatus;
+  savedAt: string;
+}
+
+export interface Continue {
+  frontmatter: ContinueFrontmatter;
+  completedWork: string;
+  remainingWork: string;
+  decisions: string;
+  context: string;
+  nextAction: string;
+}
+
+// ─── GSD State (Derived Dashboard) ────────────────────────────────────────
+
+export interface ActiveRef {
+  id: string;
+  title: string;
+}
+
+export interface MilestoneRegistryEntry {
+  id: string;
+  title: string;
+  status: 'complete' | 'active' | 'pending';
+  /** Milestone IDs that must be complete before this milestone becomes active. Populated from CONTEXT.md YAML frontmatter. */
+  dependsOn?: string[];
+}
+
+export interface RequirementCounts {
+  active: number;
+  validated: number;
+  deferred: number;
+  outOfScope: number;
+  blocked: number;
+  total: number;
+}
+
+export interface GSDState {
+  activeMilestone: ActiveRef | null;
+  activeSlice: ActiveRef | null;
+  activeTask: ActiveRef | null;
+  phase: Phase;
+  recentDecisions: string[];
+  blockers: string[];
+  nextAction: string;
+  activeBranch?: string;
+  registry: MilestoneRegistryEntry[];
+  requirements?: RequirementCounts;
+  progress?: {
+    milestones: { done: number; total: number };
+    slices?: { done: number; total: number };
+    tasks?: { done: number; total: number };
+  };
+}

package/src/resources/extensions/gsd/unit-runtime.ts

@@ -0,0 +1,184 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import {
+  gsdRoot,
+  relSliceFile,
+  relTaskFile,
+  resolveSliceFile,
+  resolveTaskFile,
+} from "./paths.ts";
+import { loadFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.ts";
+
+export type UnitRuntimePhase =
+  | "dispatched"
+  | "wrapup-warning-sent"
+  | "timeout"
+  | "recovered"
+  | "finalized"
+  | "paused"
+  | "skipped";
+
+export interface ExecuteTaskRecoveryStatus {
+  planPath: string;
+  summaryPath: string;
+  summaryExists: boolean;
+  taskChecked: boolean;
+  nextActionAdvanced: boolean;
+  mustHaveCount: number;
+  mustHavesMentionedInSummary: number;
+}
+
+export interface AutoUnitRuntimeRecord {
+  version: 1;
+  unitType: string;
+  unitId: string;
+  startedAt: number;
+  updatedAt: number;
+  phase: UnitRuntimePhase;
+  wrapupWarningSent: boolean;
+  timeoutAt: number | null;
+  lastProgressAt: number;
+  progressCount: number;
+  lastProgressKind: string;
+  recovery?: ExecuteTaskRecoveryStatus;
+  recoveryAttempts?: number;
+  lastRecoveryReason?: "idle" | "hard";
+}
+
+function runtimeDir(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "units");
+}
+
+function runtimePath(basePath: string, unitType: string, unitId: string): string {
+  return join(runtimeDir(basePath), `${unitType}-${unitId.replace(/[\/]/g, "-")}.json`);
+}
+
+export function writeUnitRuntimeRecord(
+  basePath: string,
+  unitType: string,
+  unitId: string,
+  startedAt: number,
+  updates: Partial<AutoUnitRuntimeRecord> = {},
+): AutoUnitRuntimeRecord {
+  const dir = runtimeDir(basePath);
+  mkdirSync(dir, { recursive: true });
+  const path = runtimePath(basePath, unitType, unitId);
+  const prev = readUnitRuntimeRecord(basePath, unitType, unitId);
+  const next: AutoUnitRuntimeRecord = {
+    version: 1,
+    unitType,
+    unitId,
+    startedAt,
+    updatedAt: Date.now(),
+    phase: updates.phase ?? prev?.phase ?? "dispatched",
+    wrapupWarningSent: updates.wrapupWarningSent ?? prev?.wrapupWarningSent ?? false,
+    timeoutAt: updates.timeoutAt ?? prev?.timeoutAt ?? null,
+    lastProgressAt: updates.lastProgressAt ?? prev?.lastProgressAt ?? Date.now(),
+    progressCount: updates.progressCount ?? prev?.progressCount ?? 0,
+    lastProgressKind: updates.lastProgressKind ?? prev?.lastProgressKind ?? "dispatch",
+    recovery: updates.recovery ?? prev?.recovery,
+    recoveryAttempts: updates.recoveryAttempts ?? prev?.recoveryAttempts ?? 0,
+    lastRecoveryReason: updates.lastRecoveryReason ?? prev?.lastRecoveryReason,
+  };
+  writeFileSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
+  return next;
+}
+
+export function readUnitRuntimeRecord(basePath: string, unitType: string, unitId: string): AutoUnitRuntimeRecord | null {
+  const path = runtimePath(basePath, unitType, unitId);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as AutoUnitRuntimeRecord;
+  } catch {
+    return null;
+  }
+}
+
+export function clearUnitRuntimeRecord(basePath: string, unitType: string, unitId: string): void {
+  const path = runtimePath(basePath, unitType, unitId);
+  if (existsSync(path)) unlinkSync(path);
+}
+
+/**
+ * Return all runtime records currently on disk for `basePath`.
+ * Returns an empty array if the runtime directory does not exist.
+ */
+export function listUnitRuntimeRecords(basePath: string): AutoUnitRuntimeRecord[] {
+  const dir = runtimeDir(basePath);
+  if (!existsSync(dir)) return [];
+  const results: AutoUnitRuntimeRecord[] = [];
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith(".json")) continue;
+    try {
+      const raw = readFileSync(join(dir, file), "utf-8");
+      const record = JSON.parse(raw) as AutoUnitRuntimeRecord;
+      results.push(record);
+    } catch {
+      // Skip malformed files
+    }
+  }
+  return results;
+}
+
+export async function inspectExecuteTaskDurability(
+  basePath: string,
+  unitId: string,
+): Promise<ExecuteTaskRecoveryStatus | null> {
+  const [mid, sid, tid] = unitId.split("/");
+  if (!mid || !sid || !tid) return null;
+
+  const planAbs = resolveSliceFile(basePath, mid, sid, "PLAN");
+  const summaryAbs = resolveTaskFile(basePath, mid, sid, tid, "SUMMARY");
+  const stateAbs = join(gsdRoot(basePath), "STATE.md");
+
+  const planPath = relSliceFile(basePath, mid, sid, "PLAN");
+  const summaryPath = relTaskFile(basePath, mid, sid, tid, "SUMMARY");
+
+  const planContent = planAbs ? await loadFile(planAbs) : null;
+  const stateContent = existsSync(stateAbs) ? readFileSync(stateAbs, "utf-8") : "";
+  const summaryExists = !!(summaryAbs && existsSync(summaryAbs));
+
+  const escapedTid = tid.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const taskChecked = !!planContent && new RegExp(`^- \\[[xX]\\] \\*\\*${escapedTid}:`, "m").test(planContent);
+  const nextActionAdvanced = !new RegExp(`Execute ${tid}\\b`).test(stateContent);
+
+  // Must-have coverage: load task plan and count mentions in summary
+  let mustHaveCount = 0;
+  let mustHavesMentionedInSummary = 0;
+
+  const taskPlanAbs = resolveTaskFile(basePath, mid, sid, tid, "PLAN");
+  if (taskPlanAbs) {
+    const taskPlanContent = await loadFile(taskPlanAbs);
+    if (taskPlanContent) {
+      const mustHaves = parseTaskPlanMustHaves(taskPlanContent);
+      mustHaveCount = mustHaves.length;
+      if (mustHaveCount > 0 && summaryExists && summaryAbs) {
+        const summaryContent = await loadFile(summaryAbs);
+        if (summaryContent) {
+          mustHavesMentionedInSummary = countMustHavesMentionedInSummary(mustHaves, summaryContent);
+        }
+      }
+    }
+  }
+
+  return {
+    planPath,
+    summaryPath,
+    summaryExists,
+    taskChecked,
+    nextActionAdvanced,
+    mustHaveCount,
+    mustHavesMentionedInSummary,
+  };
+}
+
+export function formatExecuteTaskRecoveryStatus(status: ExecuteTaskRecoveryStatus): string {
+  const missing = [] as string[];
+  if (!status.summaryExists) missing.push(`summary missing (${status.summaryPath})`);
+  if (!status.taskChecked) missing.push(`task checkbox unchecked in ${status.planPath}`);
+  if (!status.nextActionAdvanced) missing.push("state next action still points at the timed-out task");
+  if (status.mustHaveCount > 0 && status.mustHavesMentionedInSummary < status.mustHaveCount) {
+    missing.push(`must-have gap: ${status.mustHavesMentionedInSummary} of ${status.mustHaveCount} must-haves addressed in summary`);
+  }
+  return missing.length > 0 ? missing.join("; ") : "all durable task artifacts present";
+}