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

package/dist/resources/extensions/gsd/recovery-classification.js

@@ -3,6 +3,7 @@
 import { isToolUnavailableError } from "./auto-tool-tracking.js";
 import { classifyError, isTransient } 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";
 export function classifyFailure(input) {
@@ -51,6 +52,13 @@ const FAILURE_TAXONOMY = {
     "runtime-unknown": { action: "escalate", label: null },
 };
 function inferFailureKind(message) {
+    // 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))

package/dist/resources/extensions/gsd/roadmap-slices.js

@@ -202,7 +202,7 @@ export function parseRoadmapSlices(content) {
     const checkboxItems = slicesSection.split("\n");
     let currentSlice = 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/dist/resources/extensions/gsd/safety/content-validator.js

@@ -29,7 +29,8 @@ export function validateContent(unitType, artifactPath) {
         return [];
     }
 }
-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 = {
     "plan-slice": validatePlanSlice,

package/dist/resources/extensions/gsd/safety/evidence-cross-ref.js

@@ -38,8 +38,26 @@ export function crossReferenceEvidence(claimedEvidence, actualEvidence) {
             });
             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",
@@ -51,6 +69,30 @@ export function crossReferenceEvidence(claimedEvidence, actualEvidence) {
     }
     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 = [
+    /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) {
+    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 ──────────────────────────────────────────────────────────────
 /**
  * Verification evidence rows are append-only across retries, but a task

package/dist/resources/extensions/gsd/service-tier.js

@@ -9,7 +9,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { saveFile } from "./files.js";
-import { getGlobalGSDPreferencesPath, loadEffectiveGSDPreferences, loadGlobalGSDPreferences, } from "./preferences.js";
+import { clearGSDPreferencesCache, getGlobalGSDPreferencesPath, loadEffectiveGSDPreferences, loadGlobalGSDPreferences, } from "./preferences.js";
 import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
 const SERVICE_TIER_SCOPE_NOTE = "Only affects gpt-5.4 models, regardless of provider.";
 // ─── Gating ──────────────────────────────────────────────────────────────────
@@ -125,6 +125,7 @@ async function writeGlobalServiceTier(ctx, tier) {
             body = preserved;
     }
     await saveFile(path, `---\n${frontmatter}---${body}`);
+    clearGSDPreferencesCache();
     await ctx.waitForIdle();
     await ctx.reload();
 }

package/dist/resources/extensions/gsd/session-lock.js

@@ -21,6 +21,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);
 // ─── Module State ───────────────────────────────────────────────────────────
 /** Release function from proper-lockfile — calling it releases the OS lock. */
@@ -175,12 +176,12 @@ function createLockCompromisedHandler(lockFilePath) {
     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;
         }
         _lockCompromised = true;
@@ -404,7 +405,7 @@ export function getSessionLockStatus(basePath) {
             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 };
                 }
             }
@@ -603,6 +604,12 @@ function isLockFileOwnedByCurrentProcess(lp) {
     const existing = readExistingLockData(lp);
     return existing?.pid === process.pid;
 }
+const _retrySleepView = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) {
+    if (!(ms > 0))
+        return;
+    Atomics.wait(_retrySleepView, 0, 0, ms);
+}
 export function readExistingLockDataWithRetry(lp, options) {
     const maxAttempts = options?.maxAttempts ?? 3;
     const delayMs = options?.delayMs ?? 200;
@@ -611,12 +618,7 @@ export function readExistingLockDataWithRetry(lp, options) {
         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/dist/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/dist/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/dist/resources/extensions/gsd/state-reconciliation/drift/artifact-db.js

@@ -140,7 +140,16 @@ function detectArtifactDbStatusDriftForMilestone(basePath, milestoneId) {
         for (const task of tasks) {
             if (isClosedStatus(task.status))
                 continue;
-            const diskTaskSummary = resolveTaskFile(basePath, milestoneId, slice.id, task.id, "SUMMARY");
+            // 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, {
@@ -218,11 +227,36 @@ function detectDiskSliceIdDivergenceForMilestone(basePath, milestoneId) {
     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 = [];
+    // 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 {
@@ -300,6 +334,17 @@ function quarantineSliceDir(record, basePath) {
     const target = join(quarantineDir, `${basename(record.sliceDir)}-${stamp}`);
     renameSync(record.sliceDir, target);
 }
+export function completedMilestoneReopenedGuidance(record) {
+    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) {
     const quarantineExample = `.gsd/quarantine/milestones/${record.milestoneId}/slices/${record.sliceId}-manual-review`;
     return (`Slice ID drift in ${record.milestoneId}: ${record.reason}. ` +
@@ -326,9 +371,7 @@ export function repairArtifactDbDrift(record, ctx) {
         return;
     }
     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(`Artifact/DB status drift in ${record.milestoneId}` +
         `${record.sliceId ? `/${record.sliceId}` : ""}` +
@@ -343,9 +386,7 @@ export function describeArtifactDbDriftBlocker(record) {
         return diskSliceIdDivergenceGuidance(record);
     }
     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 (`Artifact/DB status drift in ${record.milestoneId}` +
         `${record.sliceId ? `/${record.sliceId}` : ""}` +

package/dist/resources/extensions/gsd/state-reconciliation/drift/completion.js

@@ -7,7 +7,8 @@
 // same value).
 import { existsSync, statSync } from "node:fs";
 import { getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, isDbAvailable, updateMilestoneStatus, updateSliceStatus, updateTaskStatus, } from "../../gsd-db.js";
-import { resolveMilestoneFile, resolveSliceFile, resolveTaskFile, } from "../../paths.js";
+import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveTaskFile, } from "../../paths.js";
+import { join } from "node:path";
 const COMPLETE_STATUSES = new Set(["complete", "done"]);
 function summaryMtimeIso(path) {
     try {
@@ -67,7 +68,18 @@ function collectMilestoneCompletionDrift(mid, ctx, drifts) {
                 continue;
             if (task.completed_at !== null)
                 continue;
-            const taskSummary = resolveTaskFile(ctx.basePath, mid, slice.id, task.id, "SUMMARY");
+            // 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",
@@ -124,7 +136,16 @@ export function repairMissingCompletionTimestamp(record, ctx) {
             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;

package/dist/resources/extensions/gsd/state-reconciliation/drift/external-markdown-edit.js

@@ -0,0 +1,82 @@
+// 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";
+/**
+ * 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, ctx) {
+    const marker = readCompatMarker(ctx.basePath);
+    const entries = Object.entries(marker.projections);
+    if (entries.length === 0)
+        return [];
+    const records = [];
+    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, ctx) {
+    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.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 = {
+    kind: "external-markdown-edit",
+    detect: detectExternalMarkdownEdit,
+    repair: repairExternalMarkdownEdit,
+};

package/dist/resources/extensions/gsd/state-reconciliation/drift/external-planning-edit.js

@@ -0,0 +1,142 @@
+// Project/App: gsd-pi
+// File Purpose: ADR-017 drift handler for external (gsd-core) edits to .planning/.
+// Parallel to external-markdown-edit.ts. Detects sha drift between the compat
+// marker's planning.projections/passthrough and current .planning/ files.
+//
+// Modeled files (projections): re-imported via parsePlanningDirectory → DB.
+// Passthrough files (un-modeled docs): sha refreshed, content untouched.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { computeProjectionSha, readCompatMarker, writeCompatMarker, } from "../../compat/compat-marker.js";
+import { isPlanningPassthroughRelPath, walkPlanningRelPaths, } from "../../compat/planning-compat.js";
+import { logWarning } from "../../workflow-logger.js";
+function detectOne(ctx, entries, passthrough) {
+    const records = [];
+    for (const [projectionPath, entry] of Object.entries(entries)) {
+        const abs = join(ctx.basePath, ".planning", projectionPath);
+        if (!existsSync(abs))
+            continue; // missing-file drift is covered by other handlers
+        const actual = computeProjectionSha(readFileSync(abs, "utf-8"));
+        if (actual === entry.sha)
+            continue;
+        records.push({
+            kind: "external-planning-edit",
+            projectionPath,
+            expectedSha: entry.sha,
+            actualSha: actual,
+            entities: entry.entities,
+            passthrough,
+        });
+    }
+    return records;
+}
+function detectUnseededPlanningFiles(ctx, projections, passthrough) {
+    const planningDir = join(ctx.basePath, ".planning");
+    if (!existsSync(planningDir))
+        return [];
+    const records = [];
+    for (const relPath of walkPlanningRelPaths(planningDir)) {
+        const isPassthrough = isPlanningPassthroughRelPath(relPath);
+        const map = isPassthrough ? passthrough : projections;
+        if (map[relPath])
+            continue;
+        const abs = join(planningDir, relPath);
+        const actual = computeProjectionSha(readFileSync(abs, "utf-8"));
+        records.push({
+            kind: "external-planning-edit",
+            projectionPath: relPath,
+            expectedSha: "",
+            actualSha: actual,
+            entities: [],
+            passthrough: isPassthrough,
+        });
+    }
+    return records;
+}
+async function detectExternalPlanningEdit(_state, ctx) {
+    const marker = readCompatMarker(ctx.basePath);
+    if (!marker.planning?.active) {
+        // Not yet activated. Activation (layout parse + DB import) is owned by
+        // capturePlanningCompatIfNeeded, called from reconcileBeforeDispatch when
+        // !dryRun. detect() must never write the marker — it is called in both
+        // dry-run and non-dry-run contexts. In dry-run, preview unseeded files
+        // without persisting activation.
+        if (!ctx.dryRun)
+            return [];
+        const planningDir = join(ctx.basePath, ".planning");
+        if (!existsSync(planningDir))
+            return [];
+        try {
+            const { parsePlanningDirectory } = await import("../../migrate/parser.js");
+            const { detectPlanningLayout } = await import("../../migrate/layout-detect.js");
+            const parsed = await parsePlanningDirectory(planningDir);
+            const layout = detectPlanningLayout(parsed);
+            if (!layout)
+                return [];
+            return detectUnseededPlanningFiles(ctx, {}, {});
+        }
+        catch (e) {
+            logWarning("reconcile", `planning layout auto-detection failed: ${e.message}`);
+        }
+        return [];
+    }
+    const projections = marker.planning.projections;
+    const passthrough = marker.planning.passthrough;
+    const hasBaselines = Object.keys(projections).length > 0 || Object.keys(passthrough).length > 0;
+    return [
+        ...detectOne(ctx, projections, false),
+        ...detectOne(ctx, passthrough, true),
+        // No baseline yet (post-capture, pre-writePlanningDirectory): skip unseeded
+        // detection so every on-disk file is not treated as drift in the same pass.
+        ...(hasBaselines ? detectUnseededPlanningFiles(ctx, projections, passthrough) : []),
+    ];
+}
+async function repairExternalPlanningEdit(record, ctx) {
+    // Passthrough: never re-import (no DB model). Just refresh the sha.
+    if (record.passthrough) {
+        const marker = readCompatMarker(ctx.basePath);
+        marker.planning.passthrough[record.projectionPath] = {
+            sha: record.actualSha,
+            entities: record.entities,
+        };
+        marker.lastProjectedAt = new Date().toISOString();
+        writeCompatMarker(ctx.basePath, marker);
+        return;
+    }
+    // Modeled: re-import via the migrate read path. Dynamic imports break the
+    // module-init cycle (this handler ← registry ← state.ts ← guided-flow.ts
+    // ← md-importer.ts). parsePlanningDirectory reads .planning/; always
+    // transform + writeGSDDirectory so .gsd/ reflects the edited .planning/ file
+    // before migrateHierarchyToDb ingests it. In coexistence, .planning/ is the
+    // gsd-core native format and takes precedence: writing .gsd/ here propagates
+    // the edit that must survive future projections. external-markdown-edit (index
+    // 0) runs before this handler, so .gsd/-only drift is already imported first.
+    try {
+        const { parsePlanningDirectory } = await import("../../migrate/parser.js");
+        const { transformToGSD } = await import("../../migrate/transformer.js");
+        const { writeGSDDirectory } = await import("../../migrate/writer.js");
+        const { migrateHierarchyToDb } = await import("../../md-importer.js");
+        const { invalidateStateCache } = await import("../../state.js");
+        const parsed = await parsePlanningDirectory(join(ctx.basePath, ".planning"));
+        const gsdProject = transformToGSD(parsed);
+        await writeGSDDirectory(gsdProject, ctx.basePath);
+        migrateHierarchyToDb(ctx.basePath);
+        invalidateStateCache();
+    }
+    catch (err) {
+        logWarning("reconcile", `external-planning-edit repair failed for ${record.projectionPath}: ${err.message}`);
+        throw err;
+    }
+    const marker = readCompatMarker(ctx.basePath);
+    marker.planning.projections[record.projectionPath] = {
+        sha: record.actualSha,
+        entities: record.entities,
+    };
+    marker.lastProjectedAt = new Date().toISOString();
+    writeCompatMarker(ctx.basePath, marker);
+}
+export const externalPlanningEditHandler = {
+    kind: "external-planning-edit",
+    detect: detectExternalPlanningEdit,
+    repair: repairExternalPlanningEdit,
+};