@opengsd/gsd-pi 1.1.1-dev.a5a2de8 → 1.1.1-dev.b2556262

package/dist/resources/extensions/gsd/guided-flow.js

@@ -865,7 +865,10 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
                     ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
                     : undefined,
             baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
-            activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
+            // Guided flow starts the MCP workflow server as part of dispatch, so the
+            // parent session's activeTools doesn't include MCP tools yet. The MCP
+            // launch config check (detectWorkflowMcpLaunchConfig) is the right gate
+            // here — not whether MCP tools are pre-registered in the parent session.
         });
         if (compatibilityError) {
             ctx.ui.notify(compatibilityError, "error");

package/dist/resources/extensions/gsd/markdown-renderer.js

@@ -11,9 +11,9 @@
 import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { logWarning } from "./workflow-logger.js";
 import { isClosedStatus } from "./status-guards.js";
-import { join, relative } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { createRequire } from "node:module";
-import { getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getTask, getSlice, getArtifact, insertArtifact, getGateResults, } from "./gsd-db.js";
+import { getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getTask, getSlice, insertArtifact, getGateResults, } from "./gsd-db.js";
 import { resolveDir, resolveFile, resolveSliceFile, resolveSlicePath, gsdProjectionRoot, gsdRoot, buildMilestoneFileName, buildTaskFileName, buildSliceFileName, } from "./paths.js";
 import { saveFile, clearParseCache } from "./files.js";
 import { invalidateStateCache } from "./state.js";
@@ -78,18 +78,6 @@ function sanitizeInlineRoadmapText(value) {
         .replace(/\s+/g, " ")
         .trim();
 }
-/**
- * Load artifact content from the DB. Markdown projections are not authoritative
- * during runtime; when the artifact row is missing, callers regenerate from DB
- * rows instead of patching disk fallback content and storing it back.
- */
-function loadArtifactContent(artifactPath) {
-    const artifact = getArtifact(artifactPath);
-    if (artifact && artifact.full_content) {
-        return artifact.full_content;
-    }
-    return null;
-}
 function resolveRoadmapProjectionPath(basePath, milestoneId) {
     const projectionMilestonesDir = join(gsdProjectionRoot(basePath), "milestones");
     const milestoneDirName = resolveDir(projectionMilestonesDir, milestoneId) ?? milestoneId;
@@ -324,7 +312,7 @@ function renderSlicePlanMarkdown(slice, tasks, gates = []) {
     }
     return `${lines.join("\n").trimEnd()}\n`;
 }
-export async function renderPlanFromDb(basePath, milestoneId, sliceId) {
+export async function renderPlanFromDb(basePath, milestoneId, sliceId, outputPath) {
     const slice = getSlice(milestoneId, sliceId);
     if (!slice) {
         throw new Error(`slice ${milestoneId}/${sliceId} not found`);
@@ -333,9 +321,9 @@ export async function renderPlanFromDb(basePath, milestoneId, sliceId) {
     if (tasks.length === 0) {
         throw new Error(`no tasks found for ${milestoneId}/${sliceId}`);
     }
-    const slicePath = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId);
-    mkdirSync(slicePath, { recursive: true });
-    const absPath = join(slicePath, `${sliceId}-PLAN.md`);
+    const defaultPlanPath = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId, `${sliceId}-PLAN.md`);
+    const absPath = outputPath ?? defaultPlanPath;
+    mkdirSync(dirname(absPath), { recursive: true });
     const artifactPath = toArtifactPath(absPath, basePath);
     const sliceGates = getGateResults(milestoneId, sliceId, "slice");
     const content = renderSlicePlanMarkdown(slice, tasks, sliceGates);
@@ -406,48 +394,24 @@ export async function renderRoadmapCheckboxes(basePath, milestoneId) {
 /**
  * Render plan checkbox states from DB.
  *
- * For each task in the slice, sets [x] if status === 'done',
- * [ ] otherwise. Bidirectional.
+ * Compatibility wrapper for legacy callers that used to patch plan checkboxes
+ * in-place. Plans are now fully regenerated from DB rows (mirroring
+ * renderRoadmapCheckboxes) so the projection always reflects the complete
+ * current task set and statuses. The previous regex-patch approach reused the
+ * cached PLAN artifact as the render input, which silently dropped tasks added
+ * to the DB after the artifact was first written — producing a lossy
+ * projection (the 4S/0T-vs-5S/13T drift class). The artifacts table is an
+ * output sink, never a render input.
  *
  * @returns true if the plan was written, false on skip/error
  */
-export async function renderPlanCheckboxes(basePath, milestoneId, sliceId) {
+export async function renderPlanCheckboxes(basePath, milestoneId, sliceId, outputPath) {
     const tasks = getSliceTasks(milestoneId, sliceId);
     if (tasks.length === 0) {
         process.stderr.write(`markdown-renderer: no tasks found for ${milestoneId}/${sliceId}\n`);
         return false;
     }
-    const absPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
-    const artifactPath = absPath ? toArtifactPath(absPath, basePath) : null;
-    let content = null;
-    if (artifactPath) {
-        content = loadArtifactContent(artifactPath);
-    }
-    if (!content) {
-        await renderPlanFromDb(basePath, milestoneId, sliceId);
-        return true;
-    }
-    // Apply checkbox patches for each task
-    let updated = content;
-    for (const task of tasks) {
-        const isDone = isClosedStatus(task.status);
-        const tid = task.id;
-        if (isDone) {
-            // Set [x]
-            updated = updated.replace(new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${tid}:`, "m"), `$1[x] **${tid}:`);
-        }
-        else {
-            // Set [ ]
-            updated = updated.replace(new RegExp(`^(\\s*-\\s+)\\[x\\]\\s+\\*\\*${tid}:`, "mi"), `$1[ ] **${tid}:`);
-        }
-    }
-    if (!absPath)
-        return false;
-    await writeAndStore(absPath, artifactPath, updated, {
-        artifact_type: "PLAN",
-        milestone_id: milestoneId,
-        slice_id: sliceId,
-    });
+    await renderPlanFromDb(basePath, milestoneId, sliceId, outputPath);
     return true;
 }
 // ─── Task Summary Rendering ───────────────────────────────────────────────
@@ -584,6 +548,18 @@ export async function renderAllFromDb(basePath) {
             }
         }
     }
+    // Re-project root DECISIONS.md from the authoritative decision records so a
+    // full DB → markdown re-projection (recover, rebuild) also heals decisions
+    // drift — e.g. a worktree merge that accepted one branch's DECISIONS.md while
+    // the DB holds the union of both branches' decisions.
+    try {
+        const { regenerateDecisionsMarkdown } = await import("./db-writer.js");
+        await regenerateDecisionsMarkdown(basePath);
+        result.rendered++;
+    }
+    catch (err) {
+        result.errors.push(`decisions: ${err.message}`);
+    }
     return result;
 }
 /**
@@ -659,8 +635,16 @@ export function detectStaleRenders(basePath) {
                     for (const task of tasks) {
                         const isDoneInDb = isClosedStatus(task.status);
                         const planTask = parsed.tasks.find((t) => t.id === task.id);
-                        if (!planTask)
+                        if (!planTask) {
+                            // DB has a task the plan markdown lacks: the projection is
+                            // lossy (e.g. tasks added after the PLAN artifact was first
+                            // written). Flag it so the plan is re-rendered from DB rows.
+                            stale.push({
+                                path: planPath,
+                                reason: `${task.id} exists in DB but is missing in plan`,
+                            });
                             continue;
+                        }
                         if (isDoneInDb && !planTask.done) {
                             stale.push({
                                 path: planPath,

package/dist/resources/extensions/gsd/md-importer.js

@@ -3,9 +3,9 @@
 // then upserts everything into the SQLite database.
 //
 // Exports: parseDecisionsTable, parseRequirementsSections, migrateFromMarkdown
-import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { upsertDecision, upsertRequirement, insertArtifact, insertMilestone, insertSlice, insertTask, openDatabase, transaction, updateSliceStatus, _getAdapter, } from './gsd-db.js';
+import { upsertDecision, upsertRequirement, insertArtifact, insertMilestone, insertSlice, insertTask, openDatabase, transaction, updateMilestoneStatus, updateSliceStatus, _getAdapter, } from './gsd-db.js';
 import { resolveGsdRootFile, resolveMilestoneFile, resolveSliceFile, resolveTasksDir, milestonesDir, gsdRoot, resolveTaskFiles, } from './paths.js';
 import { findMilestoneIds } from './guided-flow.js';
 import { parseRoadmap, parsePlan } from './parsers-legacy.js';
@@ -13,6 +13,26 @@ import { parseContextDependsOn } from './files.js';
 import { logWarning } from './workflow-logger.js';
 // ─── DECISIONS.md Parser ───────────────────────────────────────────────────
 const VALID_MADE_BY = new Set(['human', 'agent', 'collaborative']);
+const IMPORT_COMPLETE_STATUSES = new Set(['complete', 'done']);
+/**
+ * Completion timestamp for an entity imported as complete: the SUMMARY.md mtime
+ * when one exists (deterministic, matches the completion drift handler), else
+ * the import time. Crucially this never returns null, so a complete entity is
+ * never left with completed_at=null — which would otherwise be permanent,
+ * undetectable drift when no SUMMARY file is present.
+ */
+function importCompletionTimestamp(summaryPath) {
+    if (summaryPath && existsSync(summaryPath)) {
+        try {
+            return statSync(summaryPath).mtime.toISOString();
+        }
+        catch (err) {
+            // Fall through to import time.
+            logWarning('projection', `summary mtime read failed for ${summaryPath}: ${err.message}`);
+        }
+    }
+    return new Date().toISOString();
+}
 /**
  * Parse a DECISIONS.md markdown table into Decision objects (without seq).
  * Detects `(amends DXXX)` in the Decision column to build supersession info.
@@ -493,6 +513,14 @@ export function migrateHierarchyToDb(basePath) {
                 boundaryMapMarkdown: boundaryMapSection,
             },
         });
+        // insertMilestone never sets completed_at; backfill it now for milestones
+        // imported as complete so the DB is internally coherent immediately after
+        // import (rather than relying on a later reconciliation pass that can't even
+        // see the drift when no SUMMARY file exists).
+        if (IMPORT_COMPLETE_STATUSES.has(milestoneStatus)) {
+            const summaryPath = resolveMilestoneFile(basePath, milestoneId, 'SUMMARY');
+            updateMilestoneStatus(milestoneId, milestoneStatus, importCompletionTimestamp(summaryPath));
+        }
         counts.milestones++;
         // Parse roadmap for slices
         if (!roadmap)
@@ -517,10 +545,17 @@ export function migrateHierarchyToDb(basePath) {
                 depends: sliceEntry.depends,
                 demo: sliceEntry.demo,
                 sequence: si + 1, // Preserve roadmap parse order (#3356)
+                isSketch: sliceEntry.isSketch ?? false, // ADR-011: preserve the `[sketch]` flag on re-import
                 planning: {
                     goal: plan?.goal ?? '',
                 },
             });
+            // insertSlice never sets completed_at; backfill it for slices imported as
+            // complete (same rationale as milestones above).
+            if (IMPORT_COMPLETE_STATUSES.has(sliceStatus)) {
+                const sliceSummary = resolveSliceFile(basePath, milestoneId, sliceEntry.id, 'SUMMARY');
+                updateSliceStatus(milestoneId, sliceEntry.id, sliceStatus, importCompletionTimestamp(sliceSummary));
+            }
             counts.slices++;
             // Insert tasks from parsed plan
             if (!plan)
@@ -572,7 +607,7 @@ export function migrateHierarchyToDb(basePath) {
                 });
                 if (allTasksDone && hasSliceSummary) {
                     if (_getAdapter()) {
-                        updateSliceStatus(milestoneId, sliceEntry.id, 'complete');
+                        updateSliceStatus(milestoneId, sliceEntry.id, 'complete', importCompletionTimestamp(sliceSummaryPath));
                         process.stderr.write(`gsd-migrate: ${milestoneId}/${sliceEntry.id} all tasks + slice summary complete — upgrading slice to complete\n`);
                     }
                 }

package/dist/resources/extensions/gsd/migration-auto-check.js

@@ -6,59 +6,117 @@ import { milestonesDir, resolveMilestoneFile, resolveSliceFile, } from "./paths.
 function zeroCounts() {
     return { milestones: 0, slices: 0, tasks: 0 };
 }
+function emptyScan() {
+    return { counts: zeroCounts(), milestones: new Set(), slices: new Set(), tasks: new Set() };
+}
 function sameCounts(a, b) {
     return a.milestones === b.milestones && a.slices === b.slices && a.tasks === b.tasks;
 }
-export function countMarkdownHierarchy(basePath) {
+function setsEqual(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const value of a)
+        if (!b.has(value))
+            return false;
+    return true;
+}
+function scanIdentitiesMatch(a, b) {
+    return (setsEqual(a.milestones, b.milestones) &&
+        setsEqual(a.slices, b.slices) &&
+        setsEqual(a.tasks, b.tasks));
+}
+/** True if any element of `a` is absent from `b`. */
+function hasExtra(a, b) {
+    for (const value of a)
+        if (!b.has(value))
+            return true;
+    return false;
+}
+function scanHasExtraIdentities(a, b) {
+    return (hasExtra(a.milestones, b.milestones) ||
+        hasExtra(a.slices, b.slices) ||
+        hasExtra(a.tasks, b.tasks));
+}
+/**
+ * True when the DB holds any milestone/slice/task identity the markdown lacks —
+ * i.e. a `/gsd recover --confirm` (markdown → DB) would DELETE authoritative DB
+ * rows. This is identity-based, so it catches equal-count divergence (e.g. DB
+ * slice `S99` vs markdown `S01`) that a cardinality-only check misses. Used by
+ * the recover data-loss guard.
+ */
+export function recoverWouldDeleteDbRows(basePath) {
+    return scanHasExtraIdentities(scanDbHierarchy(), scanMarkdownHierarchy(basePath));
+}
+export function scanMarkdownHierarchy(basePath) {
     const root = milestonesDir(basePath);
     if (!existsSync(root))
-        return zeroCounts();
-    const counts = zeroCounts();
+        return emptyScan();
+    const scan = emptyScan();
     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");
+        // Use the CANONICAL milestone id (e.g. "M001" or "M001-a1b2c3"), matching
+        // scanDbHierarchy's milestone.id — not the raw directory name, which may
+        // carry a legacy descriptor (e.g. "M001-some-descriptor"). The canonical id
+        // both keys the identity sets AND resolves files correctly: resolveFile's
+        // prefix/legacy-pattern matching handles the descriptor dir either way.
+        const milestoneId = entry.name.match(/^(M\d+(?:-[a-z0-9]{6})?)/)?.[1] ?? entry.name;
+        scan.counts.milestones++;
+        scan.milestones.add(milestoneId);
+        const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
         if (!roadmapPath || !existsSync(roadmapPath))
             continue;
         const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
-        counts.slices += roadmap.slices.length;
+        scan.counts.slices += roadmap.slices.length;
         for (const slice of roadmap.slices) {
-            const planPath = resolveSliceFile(basePath, entry.name, slice.id, "PLAN");
+            scan.slices.add(`${milestoneId}/${slice.id}`);
+            const planPath = resolveSliceFile(basePath, milestoneId, slice.id, "PLAN");
             if (!planPath || !existsSync(planPath))
                 continue;
             const plan = parsePlan(readFileSync(planPath, "utf-8"));
-            counts.tasks += plan.tasks.length;
+            scan.counts.tasks += plan.tasks.length;
+            for (const task of plan.tasks) {
+                scan.tasks.add(`${milestoneId}/${slice.id}/${task.id}`);
+            }
         }
     }
-    return counts;
+    return scan;
 }
-export function countDbHierarchy() {
+export function scanDbHierarchy() {
     if (!isDbAvailable())
-        return zeroCounts();
-    const counts = zeroCounts();
+        return emptyScan();
+    const scan = emptyScan();
     const milestones = getAllMilestones();
-    counts.milestones = milestones.length;
+    scan.counts.milestones = milestones.length;
     for (const milestone of milestones) {
+        scan.milestones.add(milestone.id);
         const slices = getMilestoneSlices(milestone.id);
-        counts.slices += slices.length;
+        scan.counts.slices += slices.length;
         for (const slice of slices) {
-            counts.tasks += getSliceTasks(milestone.id, slice.id).length;
+            scan.slices.add(`${milestone.id}/${slice.id}`);
+            const tasks = getSliceTasks(milestone.id, slice.id);
+            scan.counts.tasks += tasks.length;
+            for (const task of tasks) {
+                scan.tasks.add(`${milestone.id}/${slice.id}/${task.id}`);
+            }
         }
     }
-    return counts;
+    return scan;
+}
+export function countMarkdownHierarchy(basePath) {
+    return scanMarkdownHierarchy(basePath).counts;
+}
+export function countDbHierarchy() {
+    return scanDbHierarchy().counts;
 }
 export async function checkMarkdownHierarchyAgainstDb(basePath) {
-    const markdown = countMarkdownHierarchy(basePath);
-    if (sameCounts(markdown, zeroCounts())) {
-        return {
-            action: "none",
-            reason: "no-markdown",
-            markdown,
-            beforeDb: zeroCounts(),
-            afterDb: zeroCounts(),
-        };
-    }
+    const markdownScan = scanMarkdownHierarchy(basePath);
+    const markdown = markdownScan.counts;
+    // Always open the DB before deciding. An empty markdown tree does NOT imply
+    // an empty project — the DB may hold authoritative rows whose markdown was
+    // lost, which is itself recoverable drift. The previous early return here
+    // skipped the DB entirely and silently hid a populated-DB/empty-markdown
+    // project.
     const opened = await ensureDbOpen(basePath);
     if (!opened || !isDbAvailable()) {
         throw new Error(`failed to open or create the GSD database at ${basePath}`);
@@ -67,11 +125,49 @@ export async function checkMarkdownHierarchyAgainstDb(basePath) {
     // server in another process. Reopen before comparing so startup does not
     // warn from a stale long-lived SQLite handle.
     refreshOpenDatabaseFromDisk();
-    const beforeDb = countDbHierarchy();
-    if (sameCounts(markdown, beforeDb)) {
+    const dbScan = scanDbHierarchy();
+    const beforeDb = dbScan.counts;
+    const markdownEmpty = sameCounts(markdown, zeroCounts());
+    const dbEmpty = sameCounts(beforeDb, zeroCounts());
+    // Genuinely empty project: nothing on disk, nothing in the DB.
+    if (markdownEmpty && dbEmpty) {
+        return { action: "none", reason: "no-markdown", markdown, beforeDb, afterDb: beforeDb };
+    }
+    // In sync only when both cardinalities AND identities agree. Identity
+    // comparison catches drift the counts miss (e.g. a slice deleted from the DB
+    // and a different one added nets to the same count but is real divergence,
+    // and a missing PLAN.md vs DB tasks shows up as a task-identity gap).
+    if (sameCounts(markdown, beforeDb) && scanIdentitiesMatch(markdownScan, dbScan)) {
         return { action: "none", reason: "in-sync", markdown, beforeDb, afterDb: beforeDb };
     }
-    const reason = sameCounts(beforeDb, zeroCounts()) ? "db-empty" : "count-mismatch";
+    // Choose the SAFE repair direction by IDENTITY, not cardinality. Recover
+    // imports markdown → DB and DELETES any DB row markdown lacks, so it must
+    // never be recommended when the DB holds identities the markdown is missing —
+    // including equal-count divergence (DB `S99` vs markdown `S01`), which a
+    // count-only check would wrongly route to recover. Whenever the DB holds rows
+    // markdown lacks, the correct repair is to re-project from the DB (rebuild).
+    const dbHasExtra = scanHasExtraIdentities(dbScan, markdownScan);
+    const countsLine = `Markdown planning artifacts (${markdown.milestones}M/${markdown.slices}S/${markdown.tasks}T) ` +
+        `do not match the authoritative DB (${beforeDb.milestones}M/${beforeDb.slices}S/${beforeDb.tasks}T). `;
+    // The DB holds rows markdown lacks (richer, identity-diverged, or markdown
+    // entirely missing): re-project from the DB. Recover here would destroy data.
+    if (dbHasExtra) {
+        return {
+            action: "recovery-required",
+            reason: markdownEmpty ? "markdown-missing" : "count-mismatch",
+            markdown,
+            beforeDb,
+            afterDb: beforeDb,
+            recoveryCommand: "/gsd rebuild markdown",
+            message: countsLine +
+                "The DB holds rows the markdown lacks, so the markdown projection is stale. " +
+                "Run `/gsd rebuild markdown` to re-project from the authoritative DB. " +
+                "Do NOT run `/gsd recover --confirm` here — it would delete the extra DB rows.",
+        };
+    }
+    // DB is empty (or markdown is strictly richer): markdown is the surviving
+    // source to import.
+    const reason = dbEmpty ? "db-empty" : "count-mismatch";
     return {
         action: "recovery-required",
         reason,
@@ -79,8 +175,7 @@ export async function checkMarkdownHierarchyAgainstDb(basePath) {
         beforeDb,
         afterDb: beforeDb,
         recoveryCommand: "/gsd recover --confirm",
-        message: `Markdown planning artifacts (${markdown.milestones}M/${markdown.slices}S/${markdown.tasks}T) ` +
-            `do not match the authoritative DB (${beforeDb.milestones}M/${beforeDb.slices}S/${beforeDb.tasks}T). ` +
+        message: countsLine +
             "Runtime startup will not import markdown automatically; run `/gsd recover --confirm` if markdown should repopulate the database.",
     };
 }

package/dist/resources/extensions/gsd/parsers-legacy.js

@@ -46,11 +46,34 @@ registerCacheClearCallback(clearLegacyParseCache);
 export function parseRoadmap(content) {
     return cachedParse(content, 'roadmap', _parseRoadmapImpl);
 }
+/**
+ * ADR-011: the roadmap renderer writes a `[sketch]` badge for sketch slices,
+ * but the native parser does not surface it. Re-scan the markdown and set
+ * isSketch on the matching slice so the flag survives a markdown → DB re-import
+ * (e.g. /gsd recover) instead of being silently dropped.
+ */
+function applySketchFlags(roadmap, content) {
+    const sketchIds = new Set();
+    for (const line of content.split("\n")) {
+        if (!/\[sketch\]/i.test(line))
+            continue;
+        const m = line.match(/\*\*([\w.]+):/);
+        if (m)
+            sketchIds.add(m[1]);
+    }
+    if (sketchIds.size === 0)
+        return;
+    for (const slice of roadmap.slices) {
+        if (sketchIds.has(slice.id))
+            slice.isSketch = true;
+    }
+}
 function _parseRoadmapImpl(content) {
     const stopTimer = debugTime("parse-roadmap");
     // Try native parser first for better performance
     const nativeResult = nativeParseRoadmap(content);
     if (nativeResult) {
+        applySketchFlags(nativeResult, content);
         stopTimer({ native: true, slices: nativeResult.slices.length, boundaryEntries: nativeResult.boundaryMap.length });
         debugCount("parseRoadmapCalls");
         return nativeResult;

package/dist/resources/extensions/gsd/planner-handoff.js

@@ -0,0 +1,98 @@
+// Project/App: gsd-pi
+// File Purpose: Optional gsd-planner handoff after milestone planning.
+import { spawn as spawnChild } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
+export const PLANNER_HANDOFF_RULE_NAME = "planning review handoff -> gsd-planner";
+export const GSD_PLANNER_COMMAND = "gsd-planner";
+function handoffDir(basePath) {
+    return join(gsdRoot(basePath), "runtime", "planner-handoffs");
+}
+function safeMilestoneFileSegment(milestoneId) {
+    return milestoneId.replace(/[^A-Za-z0-9._-]/g, "_") || "unknown";
+}
+function handoffMarkerPath(basePath, milestoneId) {
+    return join(handoffDir(basePath), `${safeMilestoneFileSegment(milestoneId)}.json`);
+}
+export function hasPlannerHandoffBeenOffered(basePath, milestoneId) {
+    return existsSync(handoffMarkerPath(basePath, milestoneId));
+}
+export function markPlannerHandoffOffered(basePath, milestoneId, source = "auto") {
+    mkdirSync(handoffDir(basePath), { recursive: true });
+    writeFileSync(handoffMarkerPath(basePath, milestoneId), JSON.stringify({
+        milestoneId,
+        source,
+        offeredAt: new Date().toISOString(),
+    }, null, 2) + "\n", "utf-8");
+}
+export function buildGsdPlannerSpawnPlan(input) {
+    const args = ["--project", input.basePath];
+    const milestoneId = input.milestoneId?.trim();
+    if (milestoneId)
+        args.push("--milestone", milestoneId);
+    args.push(...(input.extraArgs ?? []));
+    return {
+        command: GSD_PLANNER_COMMAND,
+        args,
+        cwd: input.basePath,
+    };
+}
+function quoteArg(arg) {
+    return /^[A-Za-z0-9_./:=@+-]+$/.test(arg) ? arg : JSON.stringify(arg);
+}
+export function formatGsdPlannerCommand(plan) {
+    return [plan.command, ...plan.args].map(quoteArg).join(" ");
+}
+export async function launchGsdPlanner(input, deps = {}) {
+    const plan = buildGsdPlannerSpawnPlan(input);
+    const spawn = deps.spawn ?? spawnChild;
+    let child;
+    try {
+        child = spawn(plan.command, plan.args, {
+            cwd: plan.cwd,
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+    }
+    catch (err) {
+        return {
+            status: "failed",
+            plan,
+            error: err instanceof Error ? err : new Error(String(err)),
+        };
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        child.once("error", (err) => {
+            settle({
+                status: "failed",
+                plan,
+                error: err instanceof Error ? err : new Error(String(err)),
+            });
+        });
+        child.once("spawn", () => {
+            child.unref();
+            settle({ status: "launched", plan });
+        });
+    });
+}
+export function formatPlannerHandoffPauseReason(milestoneId) {
+    return [
+        `Milestone ${milestoneId} is planned. Review or customize the plan before implementation if needed.`,
+        `Run /gsd planner to launch ${GSD_PLANNER_COMMAND}, or run /gsd auto to continue without planner changes.`,
+    ].join(" ");
+}
+export function formatPlannerLaunchUnavailable(plan, error) {
+    return [
+        `Could not launch ${GSD_PLANNER_COMMAND}: ${error.message}`,
+        `Install ${GSD_PLANNER_COMMAND} or run it manually: ${formatGsdPlannerCommand(plan)}`,
+    ].join("\n");
+}

package/dist/resources/extensions/gsd/planning-path-scope.js

@@ -10,6 +10,12 @@ function isInsideBase(basePath, candidate) {
 function isInsideAnyBase(bases, candidate) {
     return bases.some((base) => isInsideBase(base, candidate));
 }
+function resolvesInsideRoot(root, candidate) {
+    const resolvedCandidate = isAbsolute(candidate)
+        ? resolve(candidate)
+        : resolve(root, candidate);
+    return isInsideBase(root, resolvedCandidate);
+}
 /**
  * Planning IO fields are execution contracts. Absolute paths are only safe when
  * they stay inside the active working directory; in worktree mode, an absolute
@@ -25,13 +31,25 @@ export function validatePlanningPathScope(basePath, fields, allowedAbsoluteRoots
             if (!shouldValidatePlanningPathReference(trimmed))
                 continue;
             const candidate = normalizePlannedFileReference(raw);
-            const resolvedCandidate = isAbsolute(candidate)
-                ? resolve(candidate)
-                : resolve(basePath, candidate);
-            if (isInsideAnyBase(absoluteRoots, resolvedCandidate))
+            if (isAbsolute(candidate)) {
+                if (isInsideAnyBase(absoluteRoots, resolve(candidate)))
+                    continue;
+            }
+            else if (absoluteRoots.some((root) => resolvesInsideRoot(root, candidate))) {
                 continue;
+            }
             return `${field} contains path outside allowed repository roots: ${candidate}. Use a path within one of: ${absoluteRoots.join(", ")}.`;
         }
     }
     return null;
 }
+export function validatePathOnlyPlanningFields(fields) {
+    for (const { field, values } of fields) {
+        for (const raw of values) {
+            if (shouldValidatePlanningPathReference(raw))
+                continue;
+            return `${field} must contain only file paths; invalid entry: ${raw}`;
+        }
+    }
+    return null;
+}

package/dist/resources/extensions/gsd/pre-execution-checks.js

@@ -405,6 +405,14 @@ export function shouldValidatePlanningPathReference(raw) {
         return false;
     return shouldValidateInputAsPath(raw);
 }
+export function extractPlanningPathReference(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed || NON_PATH_SENTINEL_RE.test(trimmed))
+        return null;
+    if (!shouldValidateInputAsPath(trimmed))
+        return null;
+    return extractPathFromAnnotation(trimmed);
+}
 function shouldValidateInputAsPath(raw) {
     const trimmed = raw.trim();
     if (!trimmed)
@@ -421,7 +429,8 @@ function shouldValidateInputAsPath(raw) {
         return false;
     if (SCP_PATTERN.test(candidate))
         return false;
-    if (/^`+[^`]+`+/.test(trimmed)) {
+    const explicitlyWrappedPath = /^`+[^`]+`+/.test(trimmed) || /^(["'])([^"']+)\1$/.test(trimmed);
+    if (explicitlyWrappedPath && looksLikePathOrUrl(candidate)) {
         return true;
     }
     if (!/\s/.test(candidate)) {
@@ -431,7 +440,6 @@ function shouldValidateInputAsPath(raw) {
         candidate.startsWith("./") ||
         candidate.startsWith("../") ||
         candidate.startsWith("~/") ||
-        /[\\/]/.test(candidate) ||
         /[*?[\]{}]/.test(candidate));
 }
 function isRuntimeOnlyInput(raw) {