gsd-pi 2.78.1-dev.b0759e59b → 2.78.1-dev.e9d88a536

package/README.md

@@ -310,7 +310,9 @@ This is what makes GSD different. Run it, walk away, come back to built software
 /gsd auto
 ```
 
-Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`, determines the next unit of work, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode reads disk state again and dispatches the next unit.
+Auto mode is a state machine driven by the GSD database at the project root. It derives the next unit of work from authoritative SQLite state, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode persists the result to the database, refreshes markdown projections such as `STATE.md`, and dispatches the next unit.
+
+The database is authoritative for milestones, slices, tasks, requirements, decisions, summaries, and completion status. Markdown under `.gsd/` is a rendered projection for review, prompts, and git-friendly history; it is not a runtime fallback unless you explicitly run a recovery/import command. In worktree mode, project-root DB state remains authoritative and worktree markdown projections are not synced back as state.
 
 **What happens under the hood:**
 
@@ -499,6 +501,7 @@ Every dispatch is carefully constructed. The LLM never wastes tool calls on orie
 
 | Artifact           | Purpose                                                         |
 | ------------------ | --------------------------------------------------------------- |
+| `gsd.db`           | Authoritative runtime state for hierarchy and completion        |
 | `PROJECT.md`       | Living doc — what the project is right now                      |
 | `REQUIREMENTS.md`  | Project-level capability contract and out-of-scope list         |
 | `DECISIONS.md`     | Append-only register of architectural decisions                 |
@@ -506,7 +509,7 @@ Every dispatch is carefully constructed. The LLM never wastes tool calls on orie
 | `RUNTIME.md`       | Runtime context — API endpoints, env vars, services (v2.39)     |
 | `runtime/research-decision.json` | Deep-mode marker for project research vs skip       |
 | `research/*.md`    | Optional deep-mode project research: stack, features, architecture, pitfalls |
-| `STATE.md`         | Quick-glance dashboard — always read first                      |
+| `STATE.md`         | Quick-glance dashboard rendered from the database                |
 | `M001-ROADMAP.md`  | Milestone plan with slice checkboxes, risk levels, dependencies |
 | `M001-CONTEXT.md`  | User decisions from the discuss phase                           |
 | `M001-RESEARCH.md` | Codebase and ecosystem research                                 |
@@ -708,7 +711,7 @@ The best practice for working in teams is to ensure unique milestone names acros
 .gsd/completed-units*.json
 # State manifest — workflow state for recovery
 .gsd/state-manifest.json
-# Derived state cache — regenerated from plan/roadmap files on disk
+# Derived state projection — regenerated from the authoritative database
 .gsd/STATE.md
 # Per-developer token/cost accumulator
 .gsd/metrics.json
@@ -720,7 +723,7 @@ The best practice for working in teams is to ensure unique milestone names acros
 .gsd/worktrees/
 # Parallel orchestration IPC and worker status
 .gsd/parallel/
-# SQLite database and WAL sidecars — checkpoint state, forensics data
+# SQLite database and WAL sidecars — authoritative runtime state, local only
 .gsd/gsd.db*
 # Daily-rotated event journal — structured event log for forensics
 .gsd/journal/
@@ -785,7 +788,7 @@ gsd (CLI binary)
 - **`pkg/` shim directory** — `PI_PACKAGE_DIR` points here (not project root) to avoid Pi's theme resolution collision with our `src/` directory. Contains only `piConfig` and theme assets.
 - **Two-file loader pattern** — `loader.ts` sets all env vars with zero SDK imports, then dynamic-imports `cli.ts` which does static SDK imports. This ensures `PI_PACKAGE_DIR` is set before any SDK code evaluates.
 - **Always-overwrite sync** — `npm update -g` takes effect immediately. Bundled extensions and agents are synced to `~/.gsd/agent/` on every launch, not just first run.
-- **State lives on disk** — `.gsd/` is the source of truth. Auto mode reads it, writes it, and advances based on what it finds. No in-memory state survives across sessions.
+- **DB-authoritative state** — the project-root GSD database is the runtime source of truth. `.gsd/` markdown files are rendered projections for review, prompt context, and git history. No in-memory state survives across sessions.
 
 ---
 

package/dist/headless-recover.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Headless Recover — `gsd headless recover`
+ *
+ * Non-interactive parallel of the `/gsd recover` slash command. Clears the
+ * milestones / slices / tasks tables and re-imports them from the on-disk
+ * markdown projections (ROADMAP.md, PLAN.md, SUMMARY.md, …) via
+ * migrateHierarchyToDb. Mutating: this is the one headless subcommand that
+ * writes to the DB. Required for CI / automation flows that need to
+ * reconcile DB state from markdown without launching an LLM session or a
+ * TTY-bound interactive runtime.
+ *
+ * Output: `gsd-recover: recovered <N>M/<N>S/<N>T hierarchy\n` to stderr on
+ * success — same marker emitted by handleRecover (commands-maintenance.ts)
+ * so callers can distinguish the success path from a silent no-op.
+ *
+ * Exit codes:
+ *   0 — recovery succeeded
+ *   1 — `.gsd/` missing, DB could not be opened, or migration threw
+ */
+export interface RecoverResult {
+    exitCode: number;
+}
+export declare function handleRecover(basePath: string): Promise<RecoverResult>;

package/dist/headless-recover.js

@@ -0,0 +1,93 @@
+// gsd-pi — Headless Recover entrypoint
+/**
+ * Headless Recover — `gsd headless recover`
+ *
+ * Non-interactive parallel of the `/gsd recover` slash command. Clears the
+ * milestones / slices / tasks tables and re-imports them from the on-disk
+ * markdown projections (ROADMAP.md, PLAN.md, SUMMARY.md, …) via
+ * migrateHierarchyToDb. Mutating: this is the one headless subcommand that
+ * writes to the DB. Required for CI / automation flows that need to
+ * reconcile DB state from markdown without launching an LLM session or a
+ * TTY-bound interactive runtime.
+ *
+ * Output: `gsd-recover: recovered <N>M/<N>S/<N>T hierarchy\n` to stderr on
+ * success — same marker emitted by handleRecover (commands-maintenance.ts)
+ * so callers can distinguish the success path from a silent no-op.
+ *
+ * Exit codes:
+ *   0 — recovery succeeded
+ *   1 — `.gsd/` missing, DB could not be opened, or migration threw
+ */
+import { createJiti } from '@mariozechner/jiti';
+import { fileURLToPath } from 'node:url';
+import { resolveGsdAgentExtensionsDir, shouldUseAgentExtensionsDir } from './headless-query.js';
+import { resolveBundledGsdExtensionModule } from './bundled-resource-path.js';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+const jiti = createJiti(fileURLToPath(import.meta.url), { interopDefault: true, debug: false });
+const agentExtensionsDir = resolveGsdAgentExtensionsDir();
+const { useAgentDir } = shouldUseAgentExtensionsDir({ env: process.env });
+const gsdExtensionPath = (...segments) => useAgentDir
+    ? resolveAgentExtensionModule(agentExtensionsDir, segments)
+    : resolveBundledGsdExtensionModule(import.meta.url, segments.join('/'));
+function resolveAgentExtensionModule(agentDir, segments) {
+    const requested = join(agentDir, ...segments);
+    if (existsSync(requested))
+        return requested;
+    if (segments.length === 1 && segments[0].endsWith('.ts')) {
+        const jsPath = join(agentDir, segments[0].replace(/\.ts$/, '.js'));
+        if (existsSync(jsPath))
+            return jsPath;
+    }
+    return requested;
+}
+async function loadExtensionModules() {
+    const stateModule = await jiti.import(gsdExtensionPath('state.ts'), {});
+    const dbModule = await jiti.import(gsdExtensionPath('gsd-db.ts'), {});
+    const importerModule = await jiti.import(gsdExtensionPath('md-importer.ts'), {});
+    const dynamicToolsModule = await jiti.import(gsdExtensionPath('bootstrap/dynamic-tools.ts'), {});
+    return {
+        ensureDbOpen: dynamicToolsModule.ensureDbOpen,
+        isDbAvailable: dbModule.isDbAvailable,
+        clearEngineHierarchy: dbModule.clearEngineHierarchy,
+        transaction: dbModule.transaction,
+        migrateHierarchyToDb: importerModule.migrateHierarchyToDb,
+        invalidateStateCache: stateModule.invalidateStateCache,
+    };
+}
+export async function handleRecover(basePath) {
+    const gsdDir = join(basePath, '.gsd');
+    if (!existsSync(gsdDir)) {
+        process.stderr.write(`[headless] recover: no .gsd/ directory at ${basePath}\n`);
+        return { exitCode: 1 };
+    }
+    let modules;
+    try {
+        modules = await loadExtensionModules();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[headless] recover: failed to load extension modules: ${msg}\n`);
+        return { exitCode: 1 };
+    }
+    const opened = await modules.ensureDbOpen(basePath);
+    if (!opened || !modules.isDbAvailable()) {
+        process.stderr.write(`[headless] recover: failed to open or create the GSD database at ${basePath}\n`);
+        return { exitCode: 1 };
+    }
+    let counts;
+    try {
+        counts = modules.transaction(() => {
+            modules.clearEngineHierarchy();
+            return modules.migrateHierarchyToDb(basePath);
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[headless] recover failed: ${msg}\n`);
+        return { exitCode: 1 };
+    }
+    modules.invalidateStateCache();
+    process.stderr.write(`gsd-recover: recovered ${counts.milestones}M/${counts.slices}S/${counts.tasks}T hierarchy\n`);
+    return { exitCode: 0 };
+}

package/dist/headless.js

@@ -265,6 +265,15 @@ async function runHeadlessOnce(options, restartCount) {
         const result = await handleQuery(process.cwd());
         return { exitCode: result.exitCode, interrupted: false };
     }
+    // Recover: rebuild DB hierarchy from on-disk markdown projections, no RPC
+    // child needed. This is the one mutating headless subcommand — required for
+    // CI / automation that needs to reconcile DB state from markdown without
+    // launching an interactive TTY-bound runtime.
+    if (options.command === 'recover') {
+        const { handleRecover } = await import('./headless-recover.js');
+        const result = await handleRecover(process.cwd());
+        process.exit(result.exitCode);
+    }
     // Doctor: read-only health check, no RPC child needed (#4904 live-regression).
     // The interactive `/gsd doctor` command lives in the GSD extension; this CLI
     // path lets non-interactive callers (CI, recovery scripts, the live-regression

package/dist/help-text.js

@@ -156,6 +156,7 @@ const SUBCOMMAND_HELP = {
         '  gsd headless --answers answers.json auto              With pre-supplied answers',
         '  gsd headless --events agent_end,extension_ui_request auto   Filtered event stream',
         '  gsd headless query                              Instant JSON state snapshot',
+        '  gsd headless recover                            Rebuild DB hierarchy from markdown (mutating)',
         '',
         'Exit codes: 0 = success, 1 = error/timeout, 10 = blocked, 11 = cancelled',
     ].join('\n'),

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-44db11fcd2543b94
+d371193140538b9c

package/dist/resources/extensions/browser-tools/tools/intent.js

@@ -1,5 +1,4 @@
 import { Type } from "@sinclair/typebox";
-import { StringEnum } from "@gsd/pi-ai";
 import { diffCompactStates } from "../core.js";
 import { setLastActionBeforeState, setLastActionAfterState, } from "../state.js";
 // ---------------------------------------------------------------------------
@@ -15,6 +14,14 @@ const INTENTS = [
     "auth_action",
     "back_navigation",
 ];
+function StringEnum(values, options) {
+    return Type.Unsafe({
+        type: "string",
+        enum: values,
+        ...(options?.description && { description: options.description }),
+        ...(options?.default && { default: options.default }),
+    });
+}
 // ---------------------------------------------------------------------------
 // Scoring evaluate script — runs entirely in-browser via page.evaluate()
 // ---------------------------------------------------------------------------

package/dist/resources/extensions/gsd/auto-dispatch.js

@@ -9,7 +9,7 @@
  * without modifying orchestration code.
  */
 import { loadFile, extractUatType, loadActiveOverrides } from "./files.js";
-import { isDbAvailable, getMilestoneSlices, getPendingGates, markAllGatesOmitted, getMilestone, updateMilestoneStatus } from "./gsd-db.js";
+import { isDbAvailable, getMilestoneSlices, getPendingGates, markAllGatesOmitted, getMilestone } from "./gsd-db.js";
 import { isClosedStatus } from "./status-guards.js";
 import { extractVerdict, isAcceptableUatVerdict } from "./verdict-parser.js";
 import { gsdRoot, resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveTaskFile, relSliceFile, buildMilestoneFileName, } from "./paths.js";
@@ -19,7 +19,6 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "
 import { logWarning, logError } from "./workflow-logger.js";
 import { join } from "node:path";
 import { hasImplementationArtifacts } from "./auto-recovery.js";
-import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { buildDiscussMilestonePrompt, buildDiscussProjectPrompt, buildDiscussRequirementsPrompt, buildResearchDecisionPrompt, buildResearchProjectPrompt, buildResearchMilestonePrompt, buildPlanMilestonePrompt, buildResearchSlicePrompt, buildPlanSlicePrompt, buildRefineSlicePrompt, buildExecuteTaskPrompt, buildCompleteSlicePrompt, buildCompleteMilestonePrompt, buildValidateMilestonePrompt, buildReplanSlicePrompt, buildRunUatPrompt, buildReassessRoadmapPrompt, buildRewriteDocsPrompt, buildReactiveExecutePrompt, buildGateEvaluatePrompt, buildParallelResearchSlicesPrompt, checkNeedsReassessment, checkNeedsRunUat, } from "./auto-prompts.js";
 import { resolveModelWithFallbacksForUnit } from "./preferences-models.js";
 import { resolveUokFlags } from "./uok/flags.js";
@@ -720,13 +719,9 @@ export const DISPATCH_RULES = [
         // while a slice is still `is_sketch=1`, fall through to a standard
         // plan-slice so the loop doesn't dead-end.
         //
-        // Note on the flag-OFF downgrade: plan-slice does not explicitly clear
-        // `is_sketch`. After it writes PLAN.md, the auto-heal in state.ts's
-        // `deriveStateFromDb` (via `autoHealSketchFlags`) flips the flag on the
-        // next iteration. That implicit coupling is the sole mechanism that
-        // reconciles `is_sketch=1` on the plan-slice path — do not remove the
-        // auto-heal without either adding an explicit `setSliceSketchFlag(..., false)`
-        // call here or doing so inside the plan-slice tool handler.
+        // Note on the flag-OFF downgrade: DB slice metadata is authoritative.
+        // PLAN.md is only a projection, so plan-slice/refine-slice handlers must
+        // explicitly clear `is_sketch` when a sketch becomes a full plan.
         name: "refining → refine-slice",
         match: async ({ state, mid, midTitle, basePath, prefs, sessionContextWindow, modelRegistry, sessionProvider }) => {
             if (state.phase !== "refining")
@@ -1037,14 +1032,6 @@ export const DISPATCH_RULES = [
                     return { action: "skip" };
                 }
             }
-            const existingSummary = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            let summaryOutcome = "unknown";
-            if (existingSummary) {
-                const summaryContent = await loadFile(existingSummary);
-                if (summaryContent) {
-                    summaryOutcome = classifyMilestoneSummaryContent(summaryContent);
-                }
-            }
             // Safety guard (#2675): block completion when VALIDATION verdict is
             // needs-remediation. The state machine treats needs-remediation as
             // terminal (to prevent validate-milestone loops per #832), but
@@ -1121,45 +1108,6 @@ export const DISPATCH_RULES = [
             catch (err) { /* fall through — don't block on DB errors */
                 logWarning("dispatch", `verification class check failed: ${err instanceof Error ? err.message : String(err)}`);
             }
-            // Disk/DB mismatch handling (#4658): SUMMARY presence alone is not enough.
-            // Apply post-gate policy:
-            // - success summary: reconcile DB and skip re-dispatch
-            // - failure summary: pause/fail-closed
-            // - unknown summary: pause/fail-closed
-            if (existingSummary) {
-                const milestone = isDbAvailable() ? getMilestone(mid) : null;
-                const status = milestone?.status ?? (isDbAvailable() ? "missing" : "unavailable");
-                if (summaryOutcome === "success") {
-                    if (!isDbAvailable()) {
-                        logWarning("dispatch", `Milestone ${mid} SUMMARY indicates completion while DB is unavailable — skipping duplicate complete-milestone dispatch`);
-                        return { action: "skip" };
-                    }
-                    try {
-                        updateMilestoneStatus(mid, "complete", new Date().toISOString());
-                        logWarning("dispatch", `Milestone ${mid} SUMMARY indicates completion while DB status was "${status}" — reconciled DB to complete (#4658)`);
-                        return { action: "skip" };
-                    }
-                    catch (err) {
-                        return {
-                            action: "stop",
-                            level: "warning",
-                            reason: `Milestone ${mid} SUMMARY indicates completion but DB reconciliation failed (${err instanceof Error ? err.message : String(err)}). Auto-mode paused for manual review.`,
-                        };
-                    }
-                }
-                if (summaryOutcome === "failure") {
-                    return {
-                        action: "stop",
-                        level: "warning",
-                        reason: `Milestone ${mid} has a failure-path SUMMARY while DB status is "${status}". Auto-mode will not promote completion from failure artifacts. Re-run complete-milestone only after blockers are resolved and verification passes.`,
-                    };
-                }
-                return {
-                    action: "stop",
-                    level: "warning",
-                    reason: `Milestone ${mid} has an ambiguous SUMMARY while DB status is "${status}". Auto-mode paused instead of promoting completion from file presence alone.`,
-                };
-            }
             return {
                 action: "dispatch",
                 unitType: "complete-milestone",

package/dist/resources/extensions/gsd/auto-post-unit.js

@@ -1,6 +1,6 @@
 /**
  * Post-unit processing for auto-loop — auto-commit, doctor run,
- * state rebuild, worktree sync, DB dual-write, hooks, triage, and
+ * state rebuild, projection checks, DB tool closeout, hooks, triage, and
  * quick-task dispatch.
  *
  * Split into two functions called sequentially by auto-loop with
@@ -24,7 +24,7 @@ import { runTurnGitAction, } from "./git-service.js";
 import { verifyExpectedArtifact, resolveExpectedArtifactPath, writeBlockerPlaceholder, diagnoseExpectedArtifact, } from "./auto-recovery.js";
 import { regenerateIfMissing } from "./workflow-projections.js";
 import { syncStateToProjectRoot } from "./auto-worktree.js";
-import { isDbAvailable, getTask, getSlice, getMilestone, updateTaskStatus, updateSliceStatus, _getAdapter } from "./gsd-db.js";
+import { isDbAvailable, getTask, getSlice, getMilestone, updateTaskStatus, _getAdapter } from "./gsd-db.js";
 import { renderPlanCheckboxes } from "./markdown-renderer.js";
 import { consumeSignal } from "./session-status-io.js";
 import { checkPostUnitHooks, isRetryPending, consumeRetryTrigger, persistHookState, resolveHookArtifactPath, } from "./post-unit-hooks.js";
@@ -109,9 +109,8 @@ import { autoCommitCurrentBranch } from "./worktree.js";
  * the completion tool. A "rogue" file is one that exists on disk but has
  * no corresponding DB row with status "complete".
  *
- * This is a safety-net diagnostic (D003). The existing migrateFromMarkdown()
- * in postUnitPostVerification() eventually ingests rogue files, but explicit
- * detection provides immediate diagnostics so operators know the prompt failed.
+ * This is a safety-net diagnostic (D003). Runtime detection never imports
+ * markdown into the DB; explicit migration/import/recovery commands own that.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function hasNonEmptyFields(row, fields) {
@@ -145,15 +144,7 @@ export function detectRogueFileWrites(unitType, unitId, basePath) {
             return [];
         const dbRow = getSlice(mid, sid);
         if (!dbRow || dbRow.status !== "complete") {
-            // Auto-remediate: SUMMARY exists on disk but DB is stale — sync DB to
-            // match filesystem instead of reporting as rogue (#3633).
-            try {
-                updateSliceStatus(mid, sid, "complete", new Date().toISOString());
-            }
-            catch {
-                // If DB update fails, fall back to rogue detection so the issue is visible
-                rogues.push({ path: summaryPath, unitType, unitId });
-            }
+            rogues.push({ path: summaryPath, unitType, unitId });
         }
     }
     else if (unitType === "plan-milestone") {
@@ -628,7 +619,7 @@ export async function postUnitPreVerification(pctx, opts) {
                         ctx.ui.notify(`slice-cadence merge conflict in ${sid}: ${err.conflictedFiles.join(", ")}. ` +
                             `Resolve manually on main and run \`/gsd auto\` to resume.`, "error");
                         // Stop auto AND signal the outer postUnit flow to exit early.
-                        // Without the flag, subsequent hooks (triage, rogue detection,
+                        // Without the flag, subsequent hooks (triage,
                         // DB writes) would keep running against a conflicted main
                         // checkout after the loop was already told to stop.
                         const { stopAuto } = await import("./auto.js");
@@ -648,7 +639,7 @@ export async function postUnitPreVerification(pctx, opts) {
                 }
             });
             // Exit early after stopAuto so the rest of post-unit processing
-            // (triage, rogue detection, hook dispatch, DB writes) doesn't run
+            // (triage, hook dispatch, DB writes) doesn't run
             // against a conflicted main checkout. Return "dispatched" to match
             // the convention used by other stop/pauseAuto paths in this function
             // (see signal handling earlier: stop/pause also return "dispatched").
@@ -689,17 +680,6 @@ export async function postUnitPreVerification(pctx, opts) {
                 logError("engine", "triage resolution failed", { error: err.message });
             }
         }
-        // Rogue file detection — safety net for LLM bypassing completion tools (D003)
-        try {
-            const rogueFiles = detectRogueFileWrites(s.currentUnit.type, s.currentUnit.id, s.basePath);
-            for (const rogue of rogueFiles) {
-                logWarning("engine", "rogue file write detected", { path: rogue.path, unitId: rogue.unitId });
-                ctx.ui.notify(`Rogue file write detected: ${rogue.path}`, "warning");
-            }
-        }
-        catch (e) {
-            debugLog("postUnit", { phase: "rogue-detection", error: String(e) });
-        }
         // ── Safety harness: post-unit validation ──
         try {
             const { loadEffectiveGSDPreferences } = await import("./preferences.js");

package/dist/resources/extensions/gsd/auto-start.js

@@ -649,19 +649,12 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         const gsdDbPath = resolveProjectRootDbPath(s.basePath);
         const gsdDirPath = join(s.basePath, ".gsd");
         if (existsSync(gsdDirPath) && !existsSync(gsdDbPath)) {
-            const hasDecisions = existsSync(join(gsdDirPath, "DECISIONS.md"));
-            const hasRequirements = existsSync(join(gsdDirPath, "REQUIREMENTS.md"));
-            const hasMilestones = existsSync(join(gsdDirPath, "milestones"));
             try {
                 const { openDatabase: openDb } = await import("./gsd-db.js");
                 openDb(gsdDbPath);
-                if (hasDecisions || hasRequirements || hasMilestones) {
-                    const { migrateFromMarkdown } = await import("./md-importer.js");
-                    migrateFromMarkdown(s.basePath);
-                }
             }
             catch (err) {
-                logError("engine", `auto-migration failed: ${err.message}`);
+                logError("engine", `failed to initialize project database: ${err.message}`);
             }
         }
         if (existsSync(gsdDbPath) && !isDbAvailable()) {