@opengsd/gsd-pi 1.5.0 → 1.6.0-dev.aa7f94e8

package/dist/resources/extensions/gsd/browser-daemon-auto-prep.js

@@ -1,9 +1,16 @@
 import { execFileSync } from "node:child_process";
 import { resolve } from "node:path";
 import { resolveAmbientBrowserEngineResolution, resolveBrowserEngineResolution, } from "../browser-tools/engine/selection.js";
-import { resolveGsdBrowserCliAvailability, resolveGsdBrowserDaemonStartInvocation, } from "../shared/gsd-browser-cli.js";
+import { resolveGsdBrowserCliAvailability, resolveGsdBrowserDaemonStartInvocation, resolveGsdBrowserDaemonStopInvocation, } from "../shared/gsd-browser-cli.js";
 import { uatTypeIncludesBrowser } from "./uat-policy.js";
 const DEFAULT_DAEMON_START_TIMEOUT_MS = 30_000;
+const DEFAULT_DAEMON_STOP_TIMEOUT_MS = 15_000;
+/**
+ * Project roots whose gsd-browser daemon this process warmed via
+ * {@link prepareBrowserDaemonForUat}. Teardown only stops daemons we actually
+ * started, so non-browser auto-mode sessions never spawn a stray `daemon stop`.
+ */
+const warmedDaemonProjectRoots = new Set();
 function isEnvDisabled(value) {
     if (!value)
         return false;
@@ -77,7 +84,66 @@ export function prepareBrowserDaemonForUat(ctx) {
     if (!shouldWarmBrowserDaemonForUat(ctx))
         return null;
     const result = ensureBrowserDaemonStarted(ctx.projectRoot, { env: ctx.env });
-    if (result.ok)
+    if (result.ok) {
+        warmedDaemonProjectRoots.add(resolve(ctx.projectRoot));
         return null;
+    }
     return `Cannot dispatch browser-backed run-uat: gsd-browser daemon failed to start (${result.error}). Ensure Chrome/Chromium is installed, run \`gsd-browser daemon health\` with the project session flags from .mcp.json, or set GSD_BROWSER_PATH to a Chromium binary.`;
 }
+/**
+ * Best-effort stop of a gsd-browser session daemon warmed for browser UAT.
+ * Mirrors {@link ensureBrowserDaemonStarted}; returns the failure detail rather
+ * than throwing so teardown can stay non-fatal.
+ */
+export function stopBrowserDaemon(projectRoot, options = {}) {
+    const env = options.env ?? process.env;
+    const availability = resolveGsdBrowserCliAvailability(env);
+    if (!availability.available) {
+        return { ok: false, error: availability.detail };
+    }
+    let invocation;
+    try {
+        invocation = resolveGsdBrowserDaemonStopInvocation(projectRoot, env);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    try {
+        execFileSync(invocation.command, invocation.args, {
+            cwd: invocation.cwd,
+            env: { ...process.env, ...env, ...(invocation.env ?? {}) },
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: options.timeoutMs ?? DEFAULT_DAEMON_STOP_TIMEOUT_MS,
+            encoding: "utf-8",
+        });
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Tear down every gsd-browser daemon this process warmed for browser UAT,
+ * clearing the tracked set. Called on auto-mode loop exit so the Chrome process
+ * does not survive session/task completion (mirrors the warm-up preflight).
+ * Best-effort: returns the project roots whose stop failed for logging.
+ */
+export function teardownWarmedBrowserDaemons(options = {}) {
+    if (warmedDaemonProjectRoots.size === 0)
+        return [];
+    const failures = [];
+    for (const projectRoot of warmedDaemonProjectRoots) {
+        const result = stopBrowserDaemon(projectRoot, { env: options.env });
+        if (!result.ok) {
+            failures.push({ projectRoot, error: result.error });
+        }
+    }
+    warmedDaemonProjectRoots.clear();
+    return failures;
+}

package/dist/resources/extensions/gsd/codebase-generator.js

@@ -506,9 +506,15 @@ export function ensureCodebaseMapFresh(basePath, options, ensureOptions) {
     }
     const metadata = parseCodebaseMapMetadata(existing);
     const existingDescriptions = parseCodebaseMap(existing);
+    // Compare against the truncated count: when the repository has more tracked
+    // files than maxFiles, the map only lists the first maxFiles entries, so a
+    // stored fileCount above the cap (e.g. from an older map that recorded the
+    // full count) still matches the current truncated listing. Comparing raw
+    // values would flag "file-count-changed" on every turn, rewriting the
+    // timestamp and invalidating the provider KV cache prefix.
     const staleReason = !metadata ? "missing-metadata"
         : metadata.fingerprint !== fingerprint ? "files-changed"
-            : metadata.fileCount !== listed.files.length ? "file-count-changed"
+            : Math.min(metadata.fileCount, resolved.maxFiles) !== listed.files.length ? "file-count-changed"
                 : metadata.truncated !== listed.truncated ? "truncation-changed"
                     : undefined;
     if (!staleReason) {

package/dist/resources/extensions/gsd/commands-handlers.js

@@ -16,7 +16,7 @@ import { appendCapture, hasPendingCaptures, loadPendingCaptures } from "./captur
 import { appendOverride, appendKnowledge } from "./files.js";
 import { formatDoctorIssuesForPrompt, formatDoctorReport, formatDoctorReportJson, runGSDDoctor, selectDoctorScope, filterDoctorIssues, } from "./doctor.js";
 import { isAutoActive, checkRemoteAutoSession } from "./auto.js";
-import { getAutoWorktreePath } from "./auto-worktree.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { currentDirectoryRoot, projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { buildClaudeRuntimeFloorAdvisory } from "../../shared/claude-runtime-floor.js";

package/dist/resources/extensions/gsd/commands-workflow-templates.js

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { resolveByName, autoDetect, listTemplates, getTemplateInfo, loadWorkflowTemplate, loadRegistry, isLegacyWorkflowMode, } from "./workflow-templates.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
-import { createGitService, runGit } from "./git-service.js";
+import { createGitService, runGit, taskBranchArgs } from "./git-service.js";
 import { isAutoActive, isAutoPaused } from "./auto.js";
 import { getErrorMessage } from "./error-utils.js";
 import { resolvePlugin } from "./workflow-plugins.js";
@@ -349,7 +349,7 @@ export async function handleStart(args, ctx, pi) {
                     git.autoCommit("workflow-template", templateId, []);
                 }
                 catch { /* nothing to commit */ }
-                runGit(basePath, ["checkout", "-b", branchName]);
+                runGit(basePath, taskBranchArgs(basePath, branchName, current, git.getMainBranch()));
                 branchCreated = true;
             }
         }
@@ -481,7 +481,7 @@ export function dispatchMarkdownPhasePlugin(plugin, description, ctx, pi) {
                     git.autoCommit("workflow-template", templateId, []);
                 }
                 catch { /* nothing to commit */ }
-                runGit(basePath, ["checkout", "-b", branchName]);
+                runGit(basePath, taskBranchArgs(basePath, branchName, current, git.getMainBranch()));
                 branchCreated = true;
             }
         }

package/dist/resources/extensions/gsd/compat/compat-marker.js

@@ -98,6 +98,50 @@ export function writeCompatMarker(basePath, marker) {
     writeFileSync(tmp, JSON.stringify(marker, null, 2), "utf-8");
     renameSync(tmp, path);
 }
+/**
+ * Remove projection entries whose backing file no longer exists on disk.
+ *
+ * gsd-pi never deletes marker entries on its own: both drift detectors skip
+ * files missing from disk (`if (!existsSync(abs)) continue;`) and the write-time
+ * flush only ever adds or refreshes entries. So when a phase directory is
+ * renamed or removed (e.g. `phases/29-new-milestone-m029/` →
+ * `phases/29-frontend-code-debt-cleanup/`), the old projection paths linger in
+ * `.compat.json` forever as phantom entries pointing at directories that no
+ * longer exist (#1257). They never reconcile, and `.compat.json` keeps drifting
+ * from disk reality so `git status` stops being a reliable proxy for "did the
+ * engine touch my plans?".
+ *
+ * This prunes those orphaned entries across the `.gsd/` projections and the
+ * `.planning/` projections/passthrough maps. It is safe: a missing-file entry is
+ * inert (every detector already ignores it), and if the file is later
+ * re-projected the write-time flush / unseeded-file detection re-seeds an
+ * accurate baseline.
+ *
+ * Returns the number of entries removed; when nothing is orphaned the marker is
+ * left untouched (no needless write, no `lastProjectedAt` churn).
+ */
+export function pruneOrphanedProjectionEntries(basePath) {
+    if (!existsSync(compatMarkerPath(basePath)))
+        return 0;
+    const marker = readCompatMarker(basePath);
+    let removed = 0;
+    const pruneMap = (map, root) => {
+        for (const relPath of Object.keys(map)) {
+            if (!existsSync(join(basePath, root, relPath))) {
+                delete map[relPath];
+                removed++;
+            }
+        }
+    };
+    pruneMap(marker.projections, ".gsd");
+    if (marker.planning) {
+        pruneMap(marker.planning.projections, ".planning");
+        pruneMap(marker.planning.passthrough, ".planning");
+    }
+    if (removed > 0)
+        writeCompatMarker(basePath, marker);
+    return removed;
+}
 function quarantine(basePath, raw) {
     const path = compatMarkerPath(basePath);
     const badPath = `${path}.bad-${Date.now()}`;

package/dist/resources/extensions/gsd/config-overlay.js

@@ -121,8 +121,13 @@ function collectConfigSections(options) {
     if (prefs?.auto_supervisor) {
         const sup = resolveAutoSupervisorConfig();
         const supRows = [];
-        if (sup.model)
-            supRows.push({ label: "Model", value: sup.model });
+        if (sup.model) {
+            let modelVal = sup.model;
+            if (sup.modelFallbacks && sup.modelFallbacks.length > 0) {
+                modelVal += ` \u2192 ${sup.modelFallbacks.join(" \u2192 ")}`;
+            }
+            supRows.push({ label: "Model", value: modelVal });
+        }
         supRows.push({ label: "Soft timeout", value: `${sup.soft_timeout_minutes}m` });
         supRows.push({ label: "Idle timeout", value: `${sup.idle_timeout_minutes}m` });
         supRows.push({ label: "Stalled tool timeout", value: `${sup.stalled_tool_timeout_minutes}m` });

package/dist/resources/extensions/gsd/db/engine.js

@@ -801,3 +801,36 @@ export function getDb() {
 export function getDbOrNull() {
     return currentDb;
 }
+/**
+ * Confirm the open handle can actually write, not just that it opened.
+ *
+ * A schema-current database performs zero writes during open, so a handle that
+ * opened successfully but is not writable (read-only file, WAL/SHM permission
+ * mismatch, or a stale/moved handle → SQLITE_READONLY_DBMOVED) otherwise passes
+ * the open-only availability check and only fails much later at the first real
+ * write. The probe forces a genuine page write by re-writing the current
+ * `PRAGMA user_version` value back inside an IMMEDIATE transaction: a bare
+ * `BEGIN IMMEDIATE; ROLLBACK` is not sufficient because a moved handle does not
+ * fail until a page is actually dirtied. The value is unchanged, so the probe
+ * is idempotent, and the transaction is rolled back so nothing persists.
+ */
+export function probeDbWritable() {
+    const db = currentDb;
+    if (!db)
+        return { ok: false, detail: "No database is open." };
+    try {
+        const row = db.prepare("PRAGMA user_version").get();
+        const current = typeof row?.user_version === "number" ? row.user_version : 0;
+        db.exec("BEGIN IMMEDIATE");
+        try {
+            db.exec(`PRAGMA user_version = ${current}`);
+        }
+        finally {
+            db.exec("ROLLBACK");
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, detail: err.message };
+    }
+}

package/dist/resources/extensions/gsd/db/queries.js

@@ -218,7 +218,7 @@ export function getMilestone(id) {
 export function getActiveMilestoneFromDb() {
     if (!getDbOrNull())
         return null;
-    const row = getDbOrNull().prepare("SELECT * FROM milestones WHERE status NOT IN ('complete', 'done', 'skipped', 'closed', 'parked') ORDER BY id LIMIT 1").get();
+    const row = getDbOrNull().prepare(`SELECT * FROM milestones WHERE status NOT IN (${TERMINAL_STATUS_SQL}, 'parked') ORDER BY id LIMIT 1`).get();
     if (!row)
         return null;
     return rowToMilestone(row);
@@ -230,11 +230,11 @@ export function getActiveSliceFromDb(milestoneId) {
     // Uses json_each() to expand the JSON depends array and checks each dep is complete.
     const row = getDbOrNull().prepare(`SELECT s.* FROM slices s
      WHERE s.milestone_id = :mid
-       AND s.status NOT IN ('complete', 'done', 'skipped')
+       AND s.status NOT IN (${TERMINAL_STATUS_SQL})
        AND NOT EXISTS (
          SELECT 1 FROM json_each(s.depends) AS dep
          WHERE dep.value NOT IN (
-           SELECT id FROM slices WHERE milestone_id = :mid AND status IN ('complete', 'done', 'skipped')
+           SELECT id FROM slices WHERE milestone_id = :mid AND status IN (${TERMINAL_STATUS_SQL})
          )
        )
      ORDER BY s.sequence, s.id
@@ -246,7 +246,7 @@ export function getActiveSliceFromDb(milestoneId) {
 export function getActiveTaskFromDb(milestoneId, sliceId) {
     if (!getDbOrNull())
         return null;
-    const row = getDbOrNull().prepare("SELECT * FROM tasks WHERE milestone_id = :mid AND slice_id = :sid AND status NOT IN ('complete', 'done') ORDER BY sequence, id LIMIT 1").get({ ":mid": milestoneId, ":sid": sliceId });
+    const row = getDbOrNull().prepare(`SELECT * FROM tasks WHERE milestone_id = :mid AND slice_id = :sid AND status NOT IN (${TERMINAL_STATUS_SQL}) ORDER BY sequence, id LIMIT 1`).get({ ":mid": milestoneId, ":sid": sliceId });
     if (!row)
         return null;
     return rowToTask(row);
@@ -265,7 +265,7 @@ export function getParallelMonitorSliceProgress(milestoneId) {
        s.id AS id,
        s.status AS status,
        COUNT(t.id) AS total,
-       COALESCE(SUM(CASE WHEN t.status='complete' THEN 1 ELSE 0 END), 0) AS done
+       COALESCE(SUM(CASE WHEN t.status IN (${TERMINAL_STATUS_SQL}) THEN 1 ELSE 0 END), 0) AS done
      FROM slices s
      LEFT JOIN tasks t ON s.milestone_id=t.milestone_id AND s.id=t.slice_id
      WHERE s.milestone_id=:mid
@@ -417,7 +417,7 @@ export function getSliceScopedArtifacts(milestoneId, sliceId) {
 export function getActiveMilestoneIdFromDb() {
     if (!getDbOrNull())
         return null;
-    const row = getDbOrNull().prepare("SELECT id, status FROM milestones WHERE status NOT IN ('complete', 'done', 'skipped', 'closed', 'parked') ORDER BY id LIMIT 1").get();
+    const row = getDbOrNull().prepare(`SELECT id, status FROM milestones WHERE status NOT IN (${TERMINAL_STATUS_SQL}, 'parked') ORDER BY id LIMIT 1`).get();
     if (!row)
         return null;
     return rowToIdStatusSummary(row);
@@ -432,7 +432,7 @@ export function getSliceStatusSummary(milestoneId) {
 export function getActiveTaskIdFromDb(milestoneId, sliceId) {
     if (!getDbOrNull())
         return null;
-    const row = getDbOrNull().prepare("SELECT id, status, title FROM tasks WHERE milestone_id = :mid AND slice_id = :sid AND status NOT IN ('complete', 'done') ORDER BY sequence, id LIMIT 1").get({ ":mid": milestoneId, ":sid": sliceId });
+    const row = getDbOrNull().prepare(`SELECT id, status, title FROM tasks WHERE milestone_id = :mid AND slice_id = :sid AND status NOT IN (${TERMINAL_STATUS_SQL}) ORDER BY sequence, id LIMIT 1`).get({ ":mid": milestoneId, ":sid": sliceId });
     if (!row)
         return null;
     return rowToActiveTaskSummary(row);
@@ -443,8 +443,8 @@ export function getSliceTaskCounts(milestoneId, sliceId) {
         return emptyTaskStatusCounts();
     const row = getDbOrNull().prepare(`SELECT
        COUNT(*) as total,
-       SUM(CASE WHEN status IN ('complete', 'done') THEN 1 ELSE 0 END) as done,
-       SUM(CASE WHEN status NOT IN ('complete', 'done') THEN 1 ELSE 0 END) as pending
+       SUM(CASE WHEN status IN (${TERMINAL_STATUS_SQL}) THEN 1 ELSE 0 END) as done,
+       SUM(CASE WHEN status NOT IN (${TERMINAL_STATUS_SQL}) THEN 1 ELSE 0 END) as pending
      FROM tasks WHERE milestone_id = :mid AND slice_id = :sid`).get({ ":mid": milestoneId, ":sid": sliceId });
     return rowToTaskStatusCounts(row);
 }

package/dist/resources/extensions/gsd/db/writers/cascades.js

@@ -24,6 +24,17 @@ function requireDb() {
  * completion timestamps cleared, in one commit. Folds the hand-rolled
  * transaction-plus-cascade previously in tools/reopen-slice.ts. Guards run
  * inside the transaction (TOCTOU-safe).
+ *
+ * A closed slice is always reopenable. An open slice is only reopenable when it
+ * carries a completed-task state desync (#1205): a UAT→planning fallback can
+ * leave the slice "pending" while *all* its tasks stay "complete", which
+ * deadlocks every recovery path (plan-slice/replan-slice/complete-task all
+ * reject the still-closed tasks, and slice_reopen historically rejected the
+ * still-open slice). Resetting those tasks to pending gives the planner the
+ * clean slate it needs. An open slice that still has any unfinished
+ * (pending/in-progress) task is a normal in-flight slice, not the desync, and
+ * stays rejected as "slice-not-complete" so a full reset can't wipe its
+ * legitimate progress.
  */
 export function reopenSliceCascade(milestoneId, sliceId) {
     requireDb();
@@ -43,11 +54,18 @@ export function reopenSliceCascade(milestoneId, sliceId) {
             outcome = { ok: false, reason: "slice-not-found" };
             return;
         }
-        if (!isClosedStatus(slice.status)) {
+        const tasks = getSliceTasks(milestoneId, sliceId);
+        // A closed slice is always reopenable. An open slice is only the #1205
+        // desync when EVERY task is already closed (a UAT→planning fallback left the
+        // slice open with all tasks still "complete"). Requiring *all* tasks closed
+        // (not merely one) means a normal in-flight slice — which keeps at least one
+        // pending/in-progress task — is rejected, so a full reset can't wipe its
+        // legitimate progress.
+        const allTasksClosed = tasks.length > 0 && tasks.every((t) => isClosedStatus(t.status));
+        if (!isClosedStatus(slice.status) && !allTasksClosed) {
             outcome = { ok: false, reason: "slice-not-complete", status: slice.status };
             return;
         }
-        const tasks = getSliceTasks(milestoneId, sliceId);
         getDbOrNull().prepare(`UPDATE slices SET status = 'in_progress', completed_at = NULL WHERE milestone_id = :mid AND id = :sid`).run({ ":mid": milestoneId, ":sid": sliceId });
         getDbOrNull().prepare(`UPDATE tasks SET status = 'pending', completed_at = NULL WHERE milestone_id = :mid AND slice_id = :sid`).run({ ":mid": milestoneId, ":sid": sliceId });
         outcome = { ok: true, tasksReset: tasks.length };

package/dist/resources/extensions/gsd/db-adapter.js

@@ -11,19 +11,46 @@ export function normalizeDbRow(row) {
 export function normalizeDbRows(rows) {
     return rows.map((row) => normalizeDbRow(row));
 }
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+// node:sqlite accepts binding-object keys with or without the ':'/'@'/'$'
+// prefix, but better-sqlite3 accepts only bare keys — strip the prefix so
+// call sites written against node:sqlite also work on the fallback provider.
+function normalizeBindParams(params) {
+    return params.map((param) => {
+        if (!isPlainObject(param))
+            return param;
+        let changed = false;
+        const normalized = {};
+        for (const [key, value] of Object.entries(param)) {
+            if (key.length > 1 && (key[0] === ":" || key[0] === "@" || key[0] === "$")) {
+                normalized[key.slice(1)] = value;
+                changed = true;
+            }
+            else {
+                normalized[key] = value;
+            }
+        }
+        return changed ? normalized : param;
+    });
+}
 export function createDbAdapter(rawDb) {
     const db = rawDb;
     const stmtCache = new Map();
     function wrapStmt(raw) {
         return {
             run(...params) {
-                return raw.run(...params);
+                return raw.run(...normalizeBindParams(params));
             },
             get(...params) {
-                return normalizeDbRow(raw.get(...params));
+                return normalizeDbRow(raw.get(...normalizeBindParams(params)));
             },
             all(...params) {
-                return normalizeDbRows(raw.all(...params));
+                return normalizeDbRows(raw.all(...normalizeBindParams(params)));
             },
         };
     }

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -138,7 +138,7 @@ Diagnostics record the file path, scope (global/project), severity (error/warnin
   - `off` — skill discovery is disabled entirely.
 
 - `auto_supervisor`: configures the auto-mode supervisor that monitors agent progress and enforces timeouts. Keys:
-  - `model`: model ID to use for the supervisor process (defaults to the currently active model).
+  - `model`: model to use for the supervisor process (defaults to the currently active model). Accepts a bare model ID **or** the same `{ model, provider?, fallbacks? }` object form as `models.<phase>`, so it honors `fallbacks[]` on a transient provider trip.
   - `soft_timeout_minutes`: minutes before the supervisor issues a soft warning (default: 20).
   - `idle_timeout_minutes`: minutes of inactivity before the supervisor intervenes (default: 10).
   - `hard_timeout_minutes`: minutes before the supervisor forces termination (default: 30).
@@ -228,7 +228,7 @@ In `"parent"` mode, slice/task `targetRepositories` default to the declared chil
   - `enabled`: boolean — set `false` to force sequential task execution. Default: `true`.
   - `max_parallel`: number — maximum tasks to dispatch in one batch, range `1`-`8`. Default: `2`.
   - `isolation_mode`: `"same-tree"` — currently the only supported value.
-  - `subagent_model`: string — optional model override for reactive task subagents. Falls back to the `models.subagent` routing when omitted.
+  - `subagent_model`: optional model override for reactive task subagents. Accepts a bare model ID **or** the `{ model, provider?, fallbacks? }` object form (parity with `models.<phase>`). Falls back to the `models.subagent` routing when omitted.
 
 - `remote_questions`: route interactive questions to Slack/Discord for headless auto-mode. Keys:
   - `channel`: `"slack"` or `"discord"` — channel type.
@@ -326,7 +326,7 @@ In `"parent"` mode, slice/task `targetRepositories` default to the declared chil
   - `after`: string[] — unit types that trigger this hook (e.g., `["execute-task"]`).
   - `prompt`: string — prompt sent to the LLM. Supports `{milestoneId}`, `{sliceId}`, `{taskId}` substitutions.
   - `max_cycles`: number — max times this hook fires per trigger (default: 1, max: 10).
-  - `model`: string — optional model override.
+  - `model`: optional model override. Accepts a bare model ID **or** the same `{ model, provider?, fallbacks? }` object form as `models.<phase>`. With `fallbacks[]`, a transient trip of the primary provider falls back to the next entry instead of hard-failing the hook — which, for a `blocking` hook with `on_block: { action: pause }`, would otherwise pause the whole run.
   - `artifact`: string — expected output file name (relative to task/slice dir). Hook is skipped if file already exists (idempotent).
   - `criticality`: `"advisory"` or `"blocking"` — advisory preserves current best-effort behavior; blocking requires clean hook completion plus a valid outcome verdict before auto-mode advances. Default: `"advisory"`.
   - `retry_on`: string — if this file is produced instead of the artifact, re-run the trigger unit then re-run hooks.

package/dist/resources/extensions/gsd/doctor-engine-checks.js

@@ -3,7 +3,7 @@ import { isAbsolute, join, relative, sep } from "node:path";
 import { deleteArtifactByPath, getAllMilestones, getMilestoneSlices, getSliceTasks, isDbAvailable, isMemoriesFtsAvailable, repairTaskCompletionFromSummary, _getAdapter, } from "./gsd-db.js";
 import { MEMORIES_FTS_REBUILT_KEY } from "./db-memory-fts-schema.js";
 import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
-import { gsdProjectionRoot, gsdRoot, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "./paths.js";
+import { buildTaskFileName, gsdProjectionRoot, gsdRoot, resolveGsdPathContract, resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, } from "./paths.js";
 import { deriveState } from "./state.js";
 import { isClosedStatus } from "./status-guards.js";
 import { workflowEventLogPath } from "./workflow-event-ledger.js";
@@ -12,6 +12,7 @@ import { flushWorkflowProjections } from "./projection-flush.js";
 import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { parsePlan } from "./parsers-legacy.js";
 import { parseSummary } from "./files.js";
+import { LAYOUT_SEGMENTS } from "./layout-policy.js";
 const USER_AUTHORED_ARTIFACT_TYPES = new Set(["CONTEXT", "RESEARCH"]);
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -113,10 +114,10 @@ function isClearedByMilestoneShellProjectionFlush(basePath, issue, reRenderedMil
         return false;
     return issue.file === relativeFile(basePath, roadmapPath);
 }
-function artifactExistsOnDisk(basePath, artifactPath) {
-    return resolveArtifactDiskPath(basePath, artifactPath) !== null;
+function artifactExistsOnDisk(basePath, artifactPath, row) {
+    return resolveArtifactDiskPath(basePath, artifactPath, row) !== null;
 }
-function resolveArtifactDiskPath(basePath, artifactPath) {
+function resolveLiteralArtifactDiskPath(basePath, artifactPath) {
     const relativeArtifactPath = artifactPathRelativeToGsd(artifactPath);
     if (isAbsolute(relativeArtifactPath)) {
         return existsSync(relativeArtifactPath) ? relativeArtifactPath : null;
@@ -128,6 +129,48 @@ function resolveArtifactDiskPath(basePath, artifactPath) {
     }
     return null;
 }
+function relativeToGsdRoot(basePath, diskPath) {
+    for (const root of [gsdProjectionRoot(basePath), gsdRoot(basePath)]) {
+        if (!isPathInside(root, diskPath))
+            continue;
+        return relative(root, diskPath).split("\\").join("/");
+    }
+    return null;
+}
+function isFlatPhaseDiskPath(basePath, diskPath) {
+    return relativeToGsdRoot(basePath, diskPath)?.startsWith(`${LAYOUT_SEGMENTS.level1}/`) ?? false;
+}
+function hasFlatPhaseLayout(basePath) {
+    return existsSync(join(gsdProjectionRoot(basePath), LAYOUT_SEGMENTS.level1));
+}
+function resolveFlatPhaseArtifactDiskPath(basePath, row) {
+    if (!hasFlatPhaseLayout(basePath))
+        return null;
+    if (!row.milestone_id)
+        return null;
+    const artifactType = normalizedArtifactType(row.artifact_type);
+    if (!artifactType)
+        return null;
+    if (row.slice_id && row.task_id) {
+        const phaseDir = resolveMilestonePath(basePath, row.milestone_id);
+        if (!phaseDir || !isFlatPhaseDiskPath(basePath, phaseDir))
+            return null;
+        const candidate = join(phaseDir, buildTaskFileName(row.task_id, artifactType));
+        return existsSync(candidate) ? candidate : null;
+    }
+    const candidate = row.slice_id
+        ? resolveSliceFile(basePath, row.milestone_id, row.slice_id, artifactType)
+        : resolveMilestoneFile(basePath, row.milestone_id, artifactType);
+    return candidate && isFlatPhaseDiskPath(basePath, candidate) ? candidate : null;
+}
+function resolveArtifactDiskPath(basePath, artifactPath, row) {
+    if (row && isMilestonesArtifactPath(row.path)) {
+        const flatPath = resolveFlatPhaseArtifactDiskPath(basePath, row);
+        if (flatPath)
+            return flatPath;
+    }
+    return resolveLiteralArtifactDiskPath(basePath, artifactPath);
+}
 function taskExistsInPlan(basePath, milestoneId, sliceId, taskId) {
     const planPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
     if (!planPath || !existsSync(planPath))
@@ -156,7 +199,7 @@ function readTaskCompletionEvidenceFromSummary(basePath, row) {
     if (!row.task_status && Number(row.task_count) > 0 && !taskExistsInPlan(basePath, row.milestone_id, row.slice_id, row.task_id)) {
         return null;
     }
-    const diskPath = resolveArtifactDiskPath(basePath, row.path);
+    const diskPath = resolveArtifactDiskPath(basePath, row.path, { ...row, artifact_type: "SUMMARY" });
     if (!diskPath)
         return null;
     try {
@@ -256,6 +299,43 @@ function hasPresentMilestonesReplacement(basePath, row, artifactRows) {
         sameArtifactIdentity(row, other) &&
         artifactExistsOnDisk(basePath, other.path));
 }
+function hasPresentFlatPhaseReplacement(basePath, row, artifactRows) {
+    if (resolveFlatPhaseArtifactDiskPath(basePath, row))
+        return true;
+    return artifactRows.some((other) => other.path !== row.path &&
+        !isMilestonesArtifactPath(other.path) &&
+        sameArtifactIdentity(row, other) &&
+        artifactExistsOnDisk(basePath, other.path, other));
+}
+function hasNoFlatPhaseFileEquivalent(row) {
+    const artifactType = normalizedArtifactType(row.artifact_type);
+    if (row.slice_id && row.task_id) {
+        return artifactType === "PLAN" || artifactType === "SUMMARY";
+    }
+    return Boolean(row.slice_id && !row.task_id && artifactType === "SUMMARY");
+}
+function staleMilestonesArtifactRowFixable(basePath, row, artifactRows) {
+    if (!isMilestonesArtifactPath(row.path))
+        return false;
+    if (!hasFlatPhaseLayout(basePath))
+        return false;
+    if (hasPresentFlatPhaseReplacement(basePath, row, artifactRows))
+        return true;
+    return hasNoFlatPhaseFileEquivalent(row) && !resolveLiteralArtifactDiskPath(basePath, row.path);
+}
+function stalePhasesArtifactRowFixable(basePath, row, artifactRows) {
+    const issuePath = artifactPathRelativeToGsd(row.path);
+    return issuePath.startsWith(`${LAYOUT_SEGMENTS.level1}/`) && hasPresentMilestonesReplacement(basePath, row, artifactRows);
+}
+function staleArtifactRowFixable(basePath, row, artifactRows) {
+    return staleMilestonesArtifactRowFixable(basePath, row, artifactRows) ||
+        stalePhasesArtifactRowFixable(basePath, row, artifactRows);
+}
+function staleArtifactPruneMessage(row) {
+    return isMilestonesArtifactPath(row.path)
+        ? `pruned stale legacy artifact row ${row.path}`
+        : `pruned stale flat-phase artifact row ${row.path}`;
+}
 export async function checkEngineHealth(basePath, issues, fixesApplied, options) {
     const dbPath = resolveGsdPathContract(basePath).projectDb;
     if (!isDbAvailable() && existsSync(dbPath)) {
@@ -456,18 +536,20 @@ export async function checkEngineHealth(basePath, issues, fixesApplied, options)
              ORDER BY path`)
                     .all();
                 for (const row of artifactRows) {
-                    if (artifactExistsOnDisk(basePath, row.path))
-                        continue;
                     const unitId = artifactUnitId(row);
                     const issuePath = artifactPathRelativeToGsd(row.path);
-                    if (options?.repair && issuePath.startsWith("phases/") && hasPresentMilestonesReplacement(basePath, row, artifactRows)) {
+                    if (artifactExistsOnDisk(basePath, row.path))
+                        continue;
+                    if (options?.repair && staleArtifactRowFixable(basePath, row, artifactRows)) {
                         // Route the write through the Single Writer owner (gsd-db.ts) instead
                         // of issuing raw DELETE SQL here — doctor is a read-only consumer and
                         // the single-writer invariant forbids write SQL outside the allowlist.
                         deleteArtifactByPath(row.path);
-                        fixesApplied.push(`pruned stale flat-phase artifact row ${row.path}`);
+                        fixesApplied.push(staleArtifactPruneMessage(row));
                         continue;
                     }
+                    if (artifactExistsOnDisk(basePath, row.path, row))
+                        continue;
                     if (isUserAuthoredArtifactType(row.artifact_type)) {
                         const artifactType = normalizedArtifactType(row.artifact_type);
                         missingUserContentArtifacts.push({ path: issuePath, artifactType });
@@ -489,7 +571,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied, options)
                         unitId,
                         message: `Artifact ${issuePath} is recorded in the database as ${row.artifact_type || "UNKNOWN"} but no matching file exists on disk`,
                         file: issuePath,
-                        fixable: issuePath.startsWith("phases/") && hasPresentMilestonesReplacement(basePath, row, artifactRows),
+                        fixable: staleArtifactRowFixable(basePath, row, artifactRows),
                     });
                 }
             }
@@ -518,7 +600,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied, options)
                     .all();
                 const seen = new Set();
                 for (const row of rows) {
-                    if (!artifactExistsOnDisk(basePath, row.path))
+                    if (!artifactExistsOnDisk(basePath, row.path, row))
                         continue;
                     const reopenAt = latestExplicitReopenAt(basePath, row.milestone_id);
                     if (!isAfter(row.imported_at, reopenAt))