@opengsd/gsd-pi 1.2.0-dev.fbdca60b → 1.3.0-dev.65546769

package/src/resources/extensions/gsd/prompts/verify-work.md

@@ -0,0 +1,24 @@
+You are running the GSD **verify-work** workflow — validate built features through conversational UAT.
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Load what was built.** Read the target slice/milestone plan and SUMMARY to understand what features were delivered and what their acceptance criteria are.
+
+2. **Draft a UAT script.** Turn each acceptance criterion into a concrete, observable test step the human can perform (or that you can perform via tooling where possible). Group by feature; order so earlier steps set up later ones.
+
+3. **Walk through the script conversationally.** Present one step (or a small group) at a time. For each, record the outcome: `pass`, `fail` (with what happened), `blocked` (with the blocker), or `skipped` (intentionally). Do not advance past a fail without acknowledging it.
+
+4. **Where you can self-verify** (deterministic checks: type checks, tests, lint, schema), run them and include the result alongside the human step.
+
+5. **Produce the verdict.** After all steps: `pass` (all criteria met), `needs-attention` (some steps failed but none blocking), or `needs-remediation` (a blocking failure). Record the UAT outcome against the slice via the appropriate gsd-pi mechanism.
+
+## Success criteria
+
+- Every acceptance criterion becomes a concrete, observable step.
+- Outcomes are recorded honestly — fails are not hidden.
+- Deterministic checks are run where possible, not just asked about.
+- The final verdict maps to a canonical gsd-pi outcome.

package/src/resources/extensions/gsd/prompts/workspace.md

@@ -0,0 +1,22 @@
+You are running the GSD **workspace** workflow — manage isolated workspace environments for parallel or experimental work.
+
+## Action
+
+{{action}}
+
+## Process
+
+A workspace is an isolated environment backed by a git worktree. Map workspace actions onto worktrees:
+
+- **--list / list** (default): show all worktrees with state (current, merged, clean, dirty) — `/gsd worktree list`.
+- **--remove <name>**: remove a worktree — `/gsd worktree remove`.
+- **--merge <name>**: merge a worktree — `/gsd worktree merge`.
+- **--clean / clean**: clean stale worktree records — `/gsd worktree clean`.
+
+Route every structural action to `/gsd worktree` rather than hand-managing git worktrees.
+
+## Success criteria
+
+- Listing reflects canonical worktree state.
+- Structural actions route to `/gsd worktree`, keeping state canonical.
+- Removing a dirty worktree is guarded (confirm first).

package/src/resources/extensions/gsd/prompts/workstreams.md

@@ -0,0 +1,24 @@
+You are running the GSD **workstreams** workflow — manage parallel workstreams that run multiple milestones concurrently with isolation.
+
+## Action
+
+{{action}}
+
+## Process
+
+A workstream is a parallel worker running its own milestone in its own branch/worktree. Map workstream actions onto parallel workers:
+
+- **list / status** (default): show all parallel workers — milestone, branch/worktree, progress, state (running/paused/done/failed).
+- **create / start**: start parallel workers for all eligible milestones (`/gsd parallel start`). Does not accept a milestone target; use `/gsd parallel start` directly to start all eligible milestones.
+- **switch**: focus the dashboard on the most active worker (`/gsd parallel watch`). Does not accept a milestone target; use `/gsd parallel watch` directly to monitor workers.
+- **progress**: show all workers' progress (`/gsd parallel status`). Does not accept a milestone target; use `/gsd parallel status` directly for worker status.
+- **pause / resume <milestone>**: pause or resume a worker (`/gsd parallel pause|resume`).
+- **complete <milestone>**: complete and merge a worker's milestone (`/gsd parallel merge`).
+
+Route every structural action to `/gsd parallel <subcommand>` rather than reimplementing worktree/merge logic.
+
+## Success criteria
+
+- Status reflects canonical parallel-worker state.
+- Structural actions route to `/gsd parallel`, not duplicates.
+- Unknown milestones list the valid options rather than failing silently.

package/src/resources/extensions/gsd/provider-error-guidance.ts

@@ -60,6 +60,34 @@ function defaultAlternateModel(provider: string | undefined, modelId: string | u
   return undefined;
 }
 
+function isGeminiCliDeprecatedError(errorMsg: string): boolean {
+  return (
+    /IneligibleTierError/i.test(errorMsg)
+    || /UNSUPPORTED_CLIENT/i.test(errorMsg)
+    || /no longer supported for Gemini Code Assist for individuals/i.test(errorMsg)
+    || /migrate to the Antigravity suite/i.test(errorMsg)
+  );
+}
+
+function resolveGeminiCliDeprecationGuidance(input: ProviderErrorGuidanceInput): ProviderErrorGuidance {
+  const { provider, modelId, unitType } = input;
+  const modelLabel =
+    provider && modelId ? `${provider}/${modelId}` : modelId ?? provider ?? "google-gemini-cli";
+  const unitSuffix = unitType ? ` during ${unitType}` : "";
+
+  return {
+    summary:
+      `Provider error on ${modelLabel}${unitSuffix}. ` +
+      "Google no longer supports Gemini CLI for individual-tier users — migrate to Antigravity CLI.",
+    steps: [
+      "Install Antigravity CLI: curl -fsSL https://antigravity.google/cli/install.sh | bash",
+      "Run `agy` in a terminal and complete authentication.",
+      "In GSD, run `/login` and select Antigravity, or restart GSD to auto-migrate when `agy` is on PATH.",
+      "Run /gsd next to resume the paused unit.",
+    ],
+  };
+}
+
 /**
  * Build concrete next steps for a provider/model rejection pause.
  */
@@ -73,6 +101,10 @@ export function resolveProviderErrorGuidance(input: ProviderErrorGuidanceInput):
     hasConfiguredFallbacks,
   } = input;
 
+  if (isGeminiCliDeprecatedError(errorMsg)) {
+    return resolveGeminiCliDeprecationGuidance(input);
+  }
+
   const modelLabel =
     provider && modelId ? `${provider}/${modelId}` : modelId ?? provider ?? "current model";
   const phaseKey = unitTypeToPrefsPhaseKey(unitType);

package/src/resources/extensions/gsd/queue-order.ts

@@ -64,8 +64,9 @@ export function loadQueueOrder(basePath: string): string[] | null {
 }
 
 /**
- * Save a custom queue order. The DB sequence is canonical when a DB
- * connection is open; QUEUE-ORDER.json remains a compatibility projection.
+ * Save a custom queue order. When the DB connection is open, mirror the order
+ * into milestone sequence; QUEUE-ORDER.json remains the durable file contract
+ * for prompt-driven flows such as /gsd rethink.
  */
 export function saveQueueOrder(basePath: string, order: string[]): void {
   if (isDbAvailable()) {

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

@@ -4,6 +4,7 @@
 import { isToolUnavailableError } from "./auto-tool-tracking.js";
 import { classifyError, isTransient, type ErrorClass } from "./error-classifier.js";
 import { recoveryRemediation } from "./guidance.js";
+import { isTerminalToolSurfaceError } from "./tool-surface-readiness.js";
 import { ReconciliationFailedError } from "./state-reconciliation.js";
 import { IllegalPhaseTransitionError } from "./state-transition-matrix.js";
 
@@ -94,6 +95,12 @@ const FAILURE_TAXONOMY: Record<
 };
 
 function inferFailureKind(message: string): RecoveryFailureKind {
+  // A terminal tool-surface failure (workflow MCP server in failed/needs-auth/
+  // disabled) will not self-heal, so it must escalate rather than retry the
+  // same model into the per-unit cost cap. Checked before the generic
+  // tool-unavailable branch, which matches the same readiness prefix and
+  // would otherwise route it to retry. See #783.
+  if (isTerminalToolSurfaceError(message)) return "runtime-unknown";
   if (isToolUnavailableError(message)) return "tool-unavailable";
   if (/tool contract|auto-unit tool scope|phase-boundary gate|not permitted.*own/i.test(message)) return "tool-contract";
   if (/lifecycle progression|required artifact|missing .*assessment|missing .*closeout|cannot legally (?:advance|progress)/i.test(message)) return "lifecycle-progression";

package/src/resources/extensions/gsd/roadmap-slices.ts

@@ -201,7 +201,7 @@ export function parseRoadmapSlices(content: string): RoadmapSliceEntry[] {
   let currentSlice: RoadmapSliceEntry | null = null;
 
   for (const line of checkboxItems) {
-    const cbMatch = line.match(/^\s*-\s+\[([ xX])\]\s+\*\*([\w.]+):\s+(.+?)\*\*\s*(.*)/);
+    const cbMatch = line.match(/^\s*-\s+\[([ xX])\]\s+\*\*([\w.-]+):\s+(.+?)\*\*\s*(.*)/);
     if (cbMatch) {
       if (currentSlice) slices.push(currentSlice);
 

package/src/resources/extensions/gsd/safety/content-validator.ts

@@ -46,7 +46,8 @@ export function validateContent(
 
 type ContentValidatorFn = (content: string) => ContentViolation[];
 
-const TASK_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*T\d+:|#{2,4}\s+T\d+\b)/gm;
+// Matches both legacy "**T01: title**" and flat-phase "**T01**: title" checkbox formats.
+const TASK_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*T\d+(?:\*\*)?:|#{2,4}\s+T\d+\b)/gm;
 const SLICE_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*S\d+:|#{2,4}\s+S\d+\b)/gm;
 
 const VALIDATORS: Record<string, ContentValidatorFn> = {

package/src/resources/extensions/gsd/safety/evidence-cross-ref.ts

@@ -66,8 +66,28 @@ export function crossReferenceEvidence(
       continue;
     }
 
+    // A shell-spawn/infra failure means the command never ran (e.g. on Windows
+    // `gsd_exec runtime=bash` resolves to a WSL with no /bin/bash). The LLM
+    // typically recovers by re-running via another runtime, and that genuine
+    // run may not even be in the match set. Such a failure is inconclusive, not
+    // a falsified pass — exclude it before judging the exit code.
+    const commandRuns = matches.filter((m) => !isInfraSpawnFailure(m));
+    if (commandRuns.length === 0) {
+      if (claimed.exitCode === 0) {
+        mismatches.push({
+          severity: "warning",
+          claimed,
+          actual: latestMatch(matches),
+          reason:
+            `Matched execution failed to spawn (infrastructure error, not a command failure); ` +
+            `treating as inconclusive`,
+        });
+      }
+      continue;
+    }
+
     // Exit code mismatch: LLM claims success but actual command failed
-    const match = latestMatch(matches);
+    const match = latestMatch(commandRuns);
     if (claimed.exitCode === 0 && match.exitCode !== 0) {
       mismatches.push({
         severity: "error",
@@ -81,6 +101,30 @@ export function crossReferenceEvidence(
   return mismatches;
 }
 
+/**
+ * Runtime-spawn / shell-infra failure signatures. When a bash-runtime call
+ * fails to *spawn* (rather than the command running and exiting non-zero), the
+ * recorded exitCode is an ordinary non-zero but the output carries one of these
+ * markers. Such a call is not evidence that a verification failed.
+ */
+const INFRA_SPAWN_FAILURE_SIGNATURES: readonly RegExp[] = [
+  /execvpe\([^)]*\)\s+failed/i,   // WSL: execvpe(/bin/bash) failed: No such file or directory
+  /WSL \(.*\) ERROR/i,            // WSL relay error banner
+  /command not found:\s*(?:bash|sh|zsh|dash|fish|ash|ksh|wsl)\b/i, // missing shell interpreter only
+];
+
+/**
+ * True when a non-zero bash call looks like a shell-spawn/infra failure (the
+ * command never started) rather than a real command failure. A successful run
+ * (exitCode 0) is never an infra failure.
+ */
+function isInfraSpawnFailure(call: BashEvidence): boolean {
+  if (call.exitCode === 0) return false;
+  const snippet = call.outputSnippet ?? "";
+  if (snippet.length === 0) return false;
+  return INFRA_SPAWN_FAILURE_SIGNATURES.some((re) => re.test(snippet));
+}
+
 // ─── Internals ──────────────────────────────────────────────────────────────
 
 /**

package/src/resources/extensions/gsd/service-tier.ts

@@ -13,6 +13,7 @@ import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { existsSync, readFileSync } from "node:fs";
 import { saveFile } from "./files.js";
 import {
+  clearGSDPreferencesCache,
   getGlobalGSDPreferencesPath,
   loadEffectiveGSDPreferences,
   loadGlobalGSDPreferences,
@@ -153,6 +154,7 @@ async function writeGlobalServiceTier(
   }
 
   await saveFile(path, `---\n${frontmatter}---${body}`);
+  clearGSDPreferencesCache();
   await ctx.waitForIdle();
   await ctx.reload();
 }

package/src/resources/extensions/gsd/session-lock.ts

@@ -22,6 +22,7 @@ import { join, dirname } from "node:path";
 import { gsdRoot, normalizeRealPath } from "./paths.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { markWorkerStoppingByPid } from "./db/auto-workers.js";
+import { logWarning } from "./workflow-logger.js";
 
 const _require = createRequire(import.meta.url);
 
@@ -223,15 +224,17 @@ function createLockCompromisedHandler(lockFilePath: string): () => void {
   return () => {
     const elapsed = Date.now() - _lockAcquiredAt;
     if (elapsed < 1_800_000) {
-      process.stderr.write(
-        `[gsd] Lock heartbeat caught up after ${Math.round(elapsed / 1000)}s — long LLM call, no action needed.\n`,
+      logWarning(
+        "session",
+        `Lock heartbeat caught up after ${Math.round(elapsed / 1000)}s — long LLM call, no action needed.`,
       );
       return;
     }
     const existing = readExistingLockDataWithRetry(lockFilePath);
     if (existing && existing.pid === process.pid) {
-      process.stderr.write(
-        `[gsd] Lock heartbeat mismatch after ${Math.round(elapsed / 1000)}s — lock file still owned by PID ${process.pid}, treating as false positive.\n`,
+      logWarning(
+        "session",
+        `Lock heartbeat mismatch after ${Math.round(elapsed / 1000)}s — lock file still owned by PID ${process.pid}, treating as false positive.`,
       );
       return;
     }
@@ -476,9 +479,7 @@ export function getSessionLockStatus(basePath: string): SessionLockStatus {
       try {
         const result = acquireSessionLock(basePath);
         if (result.acquired) {
-          process.stderr.write(
-            `[gsd] Lock recovered after onCompromised — lock file PID matched, re-acquired.\n`,
-          );
+          logWarning("session", "Lock recovered after onCompromised — lock file PID matched, re-acquired.");
           return { valid: true, recovered: true };
         }
       } catch {
@@ -697,6 +698,12 @@ export interface RetryOptions {
   delayMs?: number;
 }
 
+const _retrySleepView = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms: number): void {
+  if (!(ms > 0)) return;
+  Atomics.wait(_retrySleepView, 0, 0, ms);
+}
+
 export function readExistingLockDataWithRetry(
   lp: string,
   options?: RetryOptions,
@@ -708,12 +715,7 @@ export function readExistingLockDataWithRetry(
     const data = readExistingLockData(lp);
     if (data !== null) return data;
     if (attempt < maxAttempts) {
-      // Synchronous busy-wait — onCompromised runs in a sync callback context
-      // and the delays are short (200ms default).
-      const start = Date.now();
-      while (Date.now() - start < delayMs) {
-        // busy-wait
-      }
+      sleepSync(delayMs);
     }
   }
   return null;

package/src/resources/extensions/gsd/skills/gsd-headless/SKILL.md

@@ -240,3 +240,6 @@ Quick reference — see [references/commands.md](references/commands.md) for the
 | `skip` / `undo` | Unit control |
 | `doctor` | Health check + auto-fix |
 | `steer <desc>` | Hard-steer plan mid-execution |
+| `explore` / `spike` / `sketch` | Prompt-driven ideation and experiment workflows |
+| `map-codebase` / `docs-update` / `graphify` | Codebase documentation and knowledge workflows |
+| `code-review` / `review` / `audit-*` / `verify-work` | Review, audit, and UAT workflows |

package/src/resources/extensions/gsd/skills/gsd-headless/references/commands.md

@@ -50,6 +50,57 @@ All commands can be run via `gsd headless [command]`.
 | `inspect` | Show SQLite DB diagnostics (schema, row counts) |
 | `forensics` | Post-mortem investigation of auto-mode failures |
 
+## Additional Prompt-Driven Workflows
+
+These commands dispatch native GSD prompts adapted to the milestone, slice, and `.gsd/` model. Use them as `gsd headless <command> [args...]`.
+
+| Command | Description |
+|---------|-------------|
+| `explore` | Socratic ideation before committing an idea |
+| `spike` | Focused throwaway experiment (`--quick`, `--text`, or frontier mode) |
+| `sketch` | UI/design exploration with throwaway HTML mockups |
+| `map-codebase` | Generate structured codebase docs under `.gsd/codebase/` |
+| `docs-update` | Generate, update, or verify docs against live code |
+| `graphify` | Build, query, inspect, or diff `.gsd/knowledge/` |
+| `stats` | Show project statistics, milestone state, git metrics, and timeline |
+| `progress` | Summarize recent work; can route `--next` or `--do "..."` |
+| `health` | Check `.gsd/` integrity (`--repair`, `--context`) |
+| `surface` | Manage surfaced skills and extensions |
+| `code-review` | Review changed source for bugs, security, and quality |
+| `review` | Peer-review recent work across reviewer perspectives |
+| `audit-milestone` | Verify a milestone met its definition of done |
+| `audit-uat` | Audit outstanding UAT/verification items |
+| `audit-fix` | Classify and remediate audit findings |
+| `ui-review` | Run a six-pillar frontend visual audit |
+| `secure-phase` | Verify threat mitigations |
+| `validate-phase` | Fill validation and test coverage gaps |
+| `verify-work` | Run conversational UAT |
+| `plan-review-convergence` | Iterate a plan through review cycles |
+| `discuss-phase` | Gather milestone or slice context through questions |
+| `plan-phase` | Create a detailed slice plan |
+| `execute-phase` | Execute slice tasks with wave support |
+| `spec-phase` | Clarify what a milestone delivers |
+| `mvp-phase` | Plan a vertical MVP milestone |
+| `ui-phase` | Produce a `UI-SPEC` |
+| `ai-integration-phase` | Produce an `AI-SPEC` |
+| `ultraplan-phase` | Run extended planning and review |
+| `autonomous` | Run remaining lifecycle work continuously |
+| `pause-work` | Create a pause handoff |
+| `resume-work` | Resume work with restored context |
+| `manager` | Manage multiple milestones from a command-center workflow |
+| `phase` | Manage milestone queue ordering |
+| `thread` | Manage persistent context threads |
+| `workstreams` | Route workstream actions through `parallel` |
+| `workspace` | Route workspace actions through `worktree` |
+| `milestone-summary` | Generate a project or milestone summary |
+| `review-backlog` | Review and promote backlog items |
+| `inbox` | Triage GitHub issues and PRs |
+| `import` | Ingest external plans with conflict detection |
+| `ingest-docs` | Bootstrap or merge `.gsd/` state from docs |
+| `profile-user` | Generate and persist a developer profile |
+| `settings` | Configure workflow toggles and model profile |
+| `ns-context`, `ns-ideate`, `ns-manage`, `ns-project`, `ns-review`, `ns-workflow` | Namespace-grouping names that redirect to `help` |
+
 ## Phases
 
 GSD workflows progress through these phases:

package/src/resources/extensions/gsd/state-reconciliation/drift/artifact-db.ts

@@ -213,13 +213,21 @@ function detectArtifactDbStatusDriftForMilestone(
 
     for (const task of tasks) {
       if (isClosedStatus(task.status)) continue;
-      const diskTaskSummary = resolveTaskFile(
+      // Flat-phase: task summaries live in the phase dir as TID-SUMMARY.md
+      let diskTaskSummary = resolveTaskFile(
         basePath,
         milestoneId,
         slice.id,
         task.id,
         "SUMMARY",
       );
+      if (!diskTaskSummary) {
+        const phaseDir = resolveMilestonePath(basePath, milestoneId);
+        if (phaseDir) {
+          const flatSummary = join(phaseDir, `${task.id}-SUMMARY.md`);
+          if (existsSync(flatSummary)) diskTaskSummary = flatSummary;
+        }
+      }
       if (!diskTaskSummary || !existsSync(diskTaskSummary)) continue;
       addUniqueDrift(drifts, seen, {
         kind: "artifact-db-status-divergence",
@@ -302,12 +310,35 @@ function detectDiskSliceIdDivergenceForMilestone(
   const milestonePath = resolveMilestonePath(basePath, milestoneId);
   if (!milestonePath) return [];
 
-  const slicesDir = join(milestonePath, "slices");
-  if (!existsSync(slicesDir)) return [];
-
   const knownSliceIds = new Set(getMilestoneSlices(milestoneId).map((slice) => slice.id));
   const drifts: DiskSliceIdDivergenceDrift[] = [];
 
+  // Flat-phase: scan phase dir for plan files (NN-MM-PLAN.md) where MM
+  // doesn't match any known slice. Each plan file's slice id is S<MM>.
+  try {
+    for (const entry of readdirSync(milestonePath)) {
+      const planMatch = entry.match(/^\d+-(\d+)-PLAN\.md$/i);
+      if (!planMatch) continue;
+      const planNum = parseInt(planMatch[1]!, 10);
+      const sliceId = `S${String(planNum).padStart(2, "0")}`;
+      if (knownSliceIds.has(sliceId)) continue;
+      drifts.push({
+        kind: "disk-slice-id-divergence",
+        milestoneId,
+        sliceId,
+        sliceDir: join(milestonePath, entry),
+        disposition: "block-meaningful",
+        reason: `plan file ${entry} references unknown ${sliceId}`,
+      });
+    }
+  } catch {
+    // unreadable phase dir
+  }
+
+  // Legacy: scan slices/ subdir for unknown slice dirs
+  const slicesDir = join(milestonePath, "slices");
+  if (!existsSync(slicesDir)) return drifts;
+
   for (const entry of readdirSync(slicesDir)) {
     const sliceDir = join(slicesDir, entry);
     try {
@@ -410,6 +441,27 @@ function quarantineSliceDir(record: DiskSliceIdDivergenceDrift, basePath: string
   renameSync(record.sliceDir, target);
 }
 
+export function completedMilestoneReopenedGuidance(
+  record: Pick<CompletedMilestoneReopenedDrift, "milestoneId" | "dbStatus" | "completedDispatchAt">,
+): string {
+  const when = record.completedDispatchAt ?? "time unknown";
+  const intro =
+    `Milestone ${record.milestoneId} has completed closeout dispatch history (${when}) ` +
+    `but DB status is still ${record.dbStatus}.`;
+
+  if (isClosedStatus(record.dbStatus)) {
+    return (
+      `${intro} Use gsd_milestone_reopen for ${record.milestoneId} to redo this milestone, then run /gsd next.`
+    );
+  }
+
+  return (
+    `${intro} Finish closeout with \`/gsd dispatch complete-milestone ${record.milestoneId}\`, ` +
+    `review with \`/gsd status ${record.milestoneId}\`, then run /gsd next. ` +
+    "Running /gsd next again before fixing this will pause immediately."
+  );
+}
+
 function diskSliceIdDivergenceGuidance(record: DiskSliceIdDivergenceDrift): string {
   const quarantineExample = `.gsd/quarantine/milestones/${record.milestoneId}/slices/${record.sliceId}-manual-review`;
   return (
@@ -444,11 +496,7 @@ export function repairArtifactDbDrift(
   }
 
   if (record.kind === "completed-milestone-reopened") {
-    throw new Error(
-      `Milestone ${record.milestoneId} has completed complete-milestone dispatch history` +
-        ` (${record.completedDispatchAt ?? "time unknown"}) but the DB status is ${record.dbStatus}. ` +
-        "Refusing to plan it again without an explicit reopen or recovery.",
-    );
+    throw new Error(completedMilestoneReopenedGuidance(record));
   }
 
   throw new Error(
@@ -472,11 +520,7 @@ export function describeArtifactDbDriftBlocker(
   }
 
   if (record.kind === "completed-milestone-reopened") {
-    return (
-      `Milestone ${record.milestoneId} has completed complete-milestone dispatch history` +
-      ` (${record.completedDispatchAt ?? "time unknown"}) but the DB status is ${record.dbStatus}. ` +
-      "Refusing to plan it again without an explicit reopen or recovery."
-    );
+    return completedMilestoneReopenedGuidance(record);
   }
 
   return (

package/src/resources/extensions/gsd/state-reconciliation/drift/completion.ts

@@ -20,9 +20,11 @@ import {
 } from "../../gsd-db.js";
 import {
   resolveMilestoneFile,
+  resolveMilestonePath,
   resolveSliceFile,
   resolveTaskFile,
 } from "../../paths.js";
+import { join } from "node:path";
 import type { GSDState } from "../../types.js";
 import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
 
@@ -103,13 +105,23 @@ function collectMilestoneCompletionDrift(
     for (const task of getSliceTasks(mid, slice.id)) {
       if (!COMPLETE_STATUSES.has(task.status)) continue;
       if (task.completed_at !== null) continue;
-      const taskSummary = resolveTaskFile(
+      // Flat-phase: task summaries live in the phase dir as TID-SUMMARY.md.
+      // Legacy: resolveTaskFile returns the tasks/TID/TID-SUMMARY.md path.
+      let taskSummary = resolveTaskFile(
         ctx.basePath,
         mid,
         slice.id,
         task.id,
         "SUMMARY",
       );
+      // Flat-phase fallback: check the phase dir directly
+      if (!taskSummary) {
+        const phaseDir = resolveMilestonePath(ctx.basePath, mid);
+        if (phaseDir) {
+          const flatSummary = join(phaseDir, `${task.id}-SUMMARY.md`);
+          if (existsSync(flatSummary)) taskSummary = flatSummary;
+        }
+      }
       if (taskSummary && existsSync(taskSummary)) {
         drifts.push({
           kind: "missing-completion-timestamp",
@@ -170,7 +182,15 @@ export function repairMissingCompletionTimestamp(
       task.completed_at !== null ||
       !COMPLETE_STATUSES.has(task.status)
     ) return;
-    const summary = resolveTaskFile(ctx.basePath, mid, sid, tid, "SUMMARY");
+    // Flat-phase: task summaries live in the phase dir as TID-SUMMARY.md
+    let summary = resolveTaskFile(ctx.basePath, mid, sid, tid, "SUMMARY");
+    if (!summary) {
+      const phaseDir = resolveMilestonePath(ctx.basePath, mid);
+      if (phaseDir) {
+        const flatSummary = join(phaseDir, `${tid}-SUMMARY.md`);
+        if (existsSync(flatSummary)) summary = flatSummary;
+      }
+    }
     const ts = summary ? summaryMtimeIso(summary) : null;
     if (!ts) return;
     updateTaskStatus(mid, sid, tid, task.status, ts);

package/src/resources/extensions/gsd/state-reconciliation/drift/external-markdown-edit.ts

@@ -0,0 +1,105 @@
+// Project/App: gsd-pi
+// File Purpose: ADR-017 drift handler for external (gsd-core) markdown edits.
+//
+// gsd-pi's DB is canonical, but .gsd/*.md is the inter-tool contract. When
+// gsd-core edits a projection file, this handler detects the sha drift vs the
+// recorded baseline in .gsd/.compat.json and re-imports the affected entities
+// into the DB. The next renderAllFromDb pass re-projects; the write-time
+// invalidation hook then refreshes the marker entry, closing the loop.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  computeProjectionSha,
+  readCompatMarker,
+  writeCompatMarker,
+} from "../../compat/compat-marker.js";
+import { logWarning } from "../../workflow-logger.js";
+import type { GSDState } from "../../types.js";
+import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
+
+type ExternalMarkdownEditDrift = Extract<
+  DriftRecord,
+  { kind: "external-markdown-edit" }
+>;
+
+/**
+ * Detect sha drift between the marker baseline and current file contents.
+ *
+ * - Missing marker → no records (the broader /gsd recover flow handles a
+ *   cold-start; this handler only fires when we have a baseline to compare).
+ * - Missing file on disk → no record (other handlers cover missing artifacts).
+ * - Sha match → no record (gsd-pi's own write or no change).
+ * - Sha mismatch → one record per drifted file, scoped to its recorded entities.
+ */
+function detectExternalMarkdownEdit(
+  _state: GSDState,
+  ctx: DriftContext,
+): ExternalMarkdownEditDrift[] {
+  const marker = readCompatMarker(ctx.basePath);
+  const entries = Object.entries(marker.projections);
+  if (entries.length === 0) return [];
+
+  const records: ExternalMarkdownEditDrift[] = [];
+  for (const [projectionPath, entry] of entries) {
+    const abs = join(ctx.basePath, ".gsd", projectionPath);
+    if (!existsSync(abs)) continue;
+    const actual = computeProjectionSha(readFileSync(abs, "utf-8"));
+    if (actual === entry.sha) continue;
+    records.push({
+      kind: "external-markdown-edit",
+      projectionPath,
+      expectedSha: entry.sha,
+      actualSha: actual,
+      entities: entry.entities,
+    });
+  }
+  return records;
+}
+
+/**
+ * Idempotent repair: re-import hierarchy for the affected entities from
+ * markdown into the DB, then update the marker entry so the next detect pass
+ * sees the file as expected. migrateHierarchyToDb is itself idempotent
+ * (upsert), so re-running this repair after a successful one is a no-op.
+ */
+async function repairExternalMarkdownEdit(
+  record: ExternalMarkdownEditDrift,
+  ctx: DriftContext,
+): Promise<void> {
+  try {
+    // Dynamic imports break a module-init cycle: this handler ← registry ←
+    // state.ts ← guided-flow.ts ← md-importer.ts ← (this handler's old static
+    // import). Deferring to repair time keeps module load cycle-free.
+    const { migrateHierarchyToDb } = await import("../../md-importer.js");
+    const { invalidateStateCache } = await import("../../state.js");
+    // Scoped re-import. migrateHierarchyToDb walks the whole tree but is a
+    // cheap upsert; per-entity scoping would require decomposing it, which is
+    // out of scope for v1. The cost is bounded by tree size and runs at most
+    // once per reconcile pass (MAX_PASSES=2).
+    migrateHierarchyToDb(ctx.basePath);
+    invalidateStateCache();
+  } catch (err) {
+    logWarning(
+      "reconcile",
+      `external-markdown-edit repair failed for ${record.projectionPath}: ${(err as Error).message}`,
+    );
+    throw err;
+  }
+
+  // Refresh the marker so a second pass (cap=2 reconcile) doesn't re-fire.
+  const marker = readCompatMarker(ctx.basePath);
+  marker.projections[record.projectionPath] = {
+    sha: record.actualSha,
+    entities: record.entities,
+  };
+  marker.lastProjectedAt = new Date().toISOString();
+  writeCompatMarker(ctx.basePath, marker);
+}
+
+export const externalMarkdownEditHandler: DriftHandler<ExternalMarkdownEditDrift> = {
+  kind: "external-markdown-edit",
+  detect: detectExternalMarkdownEdit,
+  repair: repairExternalMarkdownEdit,
+};