@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.822c9439

package/dist/resources/extensions/gsd/milestone-reopen-events.js

@@ -1,11 +1,9 @@
-import { join } from "node:path";
-import { gsdRoot } from "./paths.js";
+import { workflowEventArchivePath, workflowEventLogPath } from "./workflow-event-ledger.js";
 import { readEvents } from "./workflow-events.js";
 export function latestExplicitReopenAt(basePath, milestoneId) {
-    const root = gsdRoot(basePath);
     const candidates = [
-        join(root, "event-log.jsonl"),
-        join(root, `event-log-${milestoneId}.jsonl.archived`),
+        workflowEventLogPath(basePath),
+        workflowEventArchivePath(basePath, milestoneId),
     ];
     let latest = null;
     for (const file of candidates) {

package/dist/resources/extensions/gsd/model-cost-table.js

@@ -13,6 +13,7 @@ export const BUNDLED_COST_TABLE = [
     { id: "claude-opus-4-6", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-04-16" },
     { id: "claude-opus-4-7", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-04-16" },
     { id: "claude-opus-4-8", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-05-28" },
+    { id: "claude-fable-5", inputPer1k: 0.010, outputPer1k: 0.050, updatedAt: "2026-06-09" },
     { id: "claude-sonnet-4-6", inputPer1k: 0.003, outputPer1k: 0.015, updatedAt: "2025-03-15" },
     { id: "claude-haiku-4-5", inputPer1k: 0.0008, outputPer1k: 0.004, updatedAt: "2025-03-15" },
     { id: "claude-sonnet-4-5-20250514", inputPer1k: 0.003, outputPer1k: 0.015, updatedAt: "2025-03-15" },

package/dist/resources/extensions/gsd/model-router.js

@@ -35,6 +35,7 @@ export const MODEL_CAPABILITY_TIER = {
     "claude-opus-4-6": "heavy",
     "claude-opus-4-7": "heavy",
     "claude-opus-4-8": "heavy",
+    "claude-fable-5": "heavy",
     "claude-3-opus-latest": "heavy",
     "gpt-4-turbo": "heavy",
     "gpt-5": "heavy",
@@ -61,6 +62,7 @@ const MODEL_COST_PER_1K_INPUT = {
     "claude-opus-4-6": 0.005,
     "claude-opus-4-7": 0.005,
     "claude-opus-4-8": 0.005,
+    "claude-fable-5": 0.010,
     "gpt-4o-mini": 0.00015,
     "gpt-4o": 0.0025,
     "gpt-4.1": 0.002,
@@ -94,6 +96,7 @@ export const MODEL_CAPABILITY_PROFILES = {
     "claude-opus-4-6": { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
     "claude-opus-4-7": { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
     "claude-opus-4-8": { coding: 97, debugging: 92, research: 87, reasoning: 97, speed: 30, longContext: 85, instruction: 92 },
+    "claude-fable-5": { coding: 97, debugging: 92, research: 87, reasoning: 97, speed: 30, longContext: 85, instruction: 92 },
     "claude-sonnet-4-6": { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
     "claude-sonnet-4-5-20250514": { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
     "claude-3-5-sonnet-latest": { coding: 82, debugging: 78, research: 72, reasoning: 78, speed: 62, longContext: 70, instruction: 82 },

package/dist/resources/extensions/gsd/notification-store.js

@@ -34,13 +34,16 @@ export function initNotificationStore(basePath) {
  * Append a notification entry to the store. Synchronous — safe to call
  * from the notify() shim which is declared void (not async).
  */
-export function appendNotification(message, severity, source = "notify") {
+export function appendNotification(message, severity, source = "notify", meta) {
     if (!_basePath)
         return;
     if (_suppressCount > 0)
         return;
     const persistedMessage = message.length > 500 ? message.slice(0, 500) + "…" : message;
-    const dedupKey = `${_basePath}:${severity}:${source}:${persistedMessage}`;
+    // Structured identity (kind + scope) keys dedup when present, so a rephrased
+    // message of the same event still dedups; otherwise fall back to the prose.
+    const identity = meta?.kind ? `${meta.kind}:${meta.scope ?? ""}` : persistedMessage;
+    const dedupKey = `${_basePath}:${severity}:${source}:${identity}`;
     const now = Date.now();
     const lastSeen = _recentMessageTimestamps.get(dedupKey);
     if (lastSeen !== undefined && now - lastSeen < DEDUP_WINDOW_MS)
@@ -59,6 +62,8 @@ export function appendNotification(message, severity, source = "notify") {
         message: persistedMessage,
         source,
         read: false,
+        ...(meta?.kind ? { kind: meta.kind } : {}),
+        ...(meta?.scope ? { scope: meta.scope } : {}),
     };
     try {
         const dir = join(_basePath, ".gsd");
@@ -77,12 +82,14 @@ export function appendNotification(message, severity, source = "notify") {
 }
 /**
  * Read all notification entries from disk. Returns newest-first.
+ * An optional filter narrows by structured identity (kind and/or scope).
  */
-export function readNotifications(basePath) {
+export function readNotifications(basePath, filter) {
     const bp = basePath ?? _basePath;
     if (!bp)
         return [];
-    return _readEntriesFromDisk(bp).reverse();
+    const entries = _readEntriesFromDisk(bp).filter((e) => (!filter?.kind || e.kind === filter.kind) && (!filter?.scope || e.scope === filter.scope));
+    return entries.reverse();
 }
 /**
  * Mark all notifications as read. Atomic rewrite via temp-file + rename.

package/dist/resources/extensions/gsd/parallel-merge.js

@@ -5,9 +5,9 @@
  * with safety checks for parallel execution context.
  */
 import { existsSync, readdirSync } from "node:fs";
-import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { resolveGsdPathContract } from "./paths.js";
+import { worktreePathFor, worktreesDirs } from "./worktree-placement.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 import { buildWorktreeLifecycleDeps } from "./auto.js";
 import { mergeMilestoneStandalone, } from "./worktree-lifecycle.js";
@@ -22,7 +22,7 @@ import { logWarning } from "./workflow-logger.js";
  * Returns true when milestones.status = 'complete' in project gsd.db.
  */
 export function isMilestoneCompleteInProjectDb(basePath, mid) {
-    const workRoot = join(basePath, ".gsd", "worktrees", mid);
+    const workRoot = worktreePathFor(basePath, mid);
     const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
     if (!existsSync(dbPath))
         return false;
@@ -41,16 +41,19 @@ export function isMilestoneCompleteInProjectDb(basePath, mid) {
  */
 function discoverDbCompletedMilestones(basePath) {
     const completed = new Set();
-    const worktreeDir = join(basePath, ".gsd", "worktrees");
-    try {
-        for (const entry of readdirSync(worktreeDir)) {
-            if (entry.startsWith("M") && isMilestoneCompleteInProjectDb(basePath, entry)) {
-                completed.add(entry);
+    for (const worktreeDir of worktreesDirs(basePath)) {
+        if (!existsSync(worktreeDir))
+            continue;
+        try {
+            for (const entry of readdirSync(worktreeDir)) {
+                if (entry.startsWith("M") && isMilestoneCompleteInProjectDb(basePath, entry)) {
+                    completed.add(entry);
+                }
             }
         }
-    }
-    catch (e) {
-        logWarning("parallel", `readdirSync for completed set failed: ${e.message}`);
+        catch (e) {
+            logWarning("parallel", `readdirSync for completed set failed: ${e.message}`);
+        }
     }
     return completed;
 }
@@ -88,7 +91,7 @@ export function determineMergeOrder(workers, order = "sequential", basePath) {
                 title: mid,
                 pid: 0,
                 process: null,
-                worktreePath: basePath ? join(basePath, ".gsd", "worktrees", mid) : "",
+                worktreePath: basePath ? worktreePathFor(basePath, mid) : "",
                 startedAt: 0,
                 state: "stopped",
                 cost: 0,

package/dist/resources/extensions/gsd/parallel-monitor-overlay.js

@@ -7,6 +7,7 @@ import { matchesKey, Key } from "@gsd/pi-tui";
 import { formatDuration } from "../shared/mod.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
 import { resolveGsdPathContract } from "./paths.js";
+import { worktreePathFor, worktreesDirs } from "./worktree-placement.js";
 import { renderBar, renderDialogFrame, renderKeyHints, renderProgressBar, safeLine, statusGlyph, } from "./tui/render-kit.js";
 // ─── Data Helpers ─────────────────────────────────────────────────────────
 function readJsonSafe(filePath) {
@@ -42,7 +43,6 @@ function tailRead(filePath, maxBytes) {
 }
 function discoverWorkers(basePath) {
     const parallelDir = join(basePath, ".gsd", "parallel");
-    const worktreeDir = join(basePath, ".gsd", "worktrees");
     const mids = new Set();
     if (existsSync(parallelDir)) {
         try {
@@ -56,7 +56,9 @@ function discoverWorkers(basePath) {
         }
         catch { /* skip */ }
     }
-    if (existsSync(worktreeDir)) {
+    for (const worktreeDir of worktreesDirs(basePath)) {
+        if (!existsSync(worktreeDir))
+            continue;
         try {
             for (const d of readdirSync(worktreeDir)) {
                 if (d.startsWith("M") && existsSync(join(worktreeDir, d, ".gsd", "auto.lock"))) {
@@ -68,8 +70,7 @@ function discoverWorkers(basePath) {
     }
     return [...mids].sort();
 }
-function querySliceProgress(basePath, mid) {
-    const workRoot = join(basePath, ".gsd", "worktrees", mid);
+function querySliceProgress(basePath, mid, workRoot = worktreePathFor(basePath, mid)) {
     const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
     if (!existsSync(dbPath))
         return [];
@@ -115,7 +116,7 @@ function extractCostFromNdjson(basePath, mid) {
     }
 }
 function queryRecentCompletions(basePath, mid) {
-    const workRoot = join(basePath, ".gsd", "worktrees", mid);
+    const workRoot = worktreePathFor(basePath, mid);
     const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
     if (!existsSync(dbPath))
         return [];
@@ -139,9 +140,12 @@ function collectWorkerData(basePath) {
     const parallelDir = join(basePath, ".gsd", "parallel");
     const workers = [];
     for (const mid of mids) {
+        // Resolve the worktree path once per worker per tick — this runs on a
+        // 5-second refresh interval and worktreePathFor probes the filesystem.
+        const workRoot = worktreePathFor(basePath, mid);
         const status = readJsonSafe(join(parallelDir, `${mid}.status.json`));
-        const lock = readJsonSafe(join(basePath, ".gsd", "worktrees", mid, ".gsd", "auto.lock"));
-        const slices = querySliceProgress(basePath, mid);
+        const lock = readJsonSafe(join(workRoot, ".gsd", "auto.lock"));
+        const slices = querySliceProgress(basePath, mid, workRoot);
         const pid = lock?.pid || status?.pid || 0;
         const alive = pid ? isPidAlive(pid) : false;
         // Heartbeat: prefer status.json if PID matches, else use file mtime

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

@@ -1,10 +1,22 @@
 // GSD Extension - Legacy Parsers
 // parseRoadmap() and parsePlan() extracted from files.ts.
-// Used only by: md-importer.ts (migration), state.ts (pre-migration fallback),
-// markdown-renderer.ts (detectStaleRenders disk-vs-DB comparison),
-// commands-maintenance.ts (cold-path branch cleanup), and tests.
 //
-// NOT used in the dispatch loop or any hot-path runtime code.
+// ADR-017: the DB is the single source of truth; `.gsd/*.md` files are
+// projections. These parsers may be imported ONLY for:
+//   - migration/import (md-importer, workflow-migration, migration-auto-check)
+//   - drift detection that compares both sources by design
+//     (state-reconciliation/drift, markdown-renderer stale-render detection)
+//   - explicit pre-migration / DB-unavailable fallbacks (state.ts,
+//     reactive-graph.ts, auto-recovery.ts)
+//   - diagnostics and display/telemetry-only surfaces (doctor,
+//     doctor-git-checks, workspace-index, visualizer-data, auto-prompts
+//     context text, commands-maintenance, milestone-closeout, github-sync)
+//   - tests
+//
+// Dispatch/gate/completion DECISION paths must NOT import this module — they
+// read the DB via gsd-db queries (e.g. getMilestoneSliceSummaries). Enforced
+// by tests/parsers-legacy-importers.test.ts; new importers must be added to
+// its allowlist with a one-line justification.
 import { extractSection, parseBullets, extractBoldField, extractAllSections, registerCacheClearCallback } from './files.js';
 import { splitFrontmatter } from '../shared/frontmatter.js';
 import { nativeParseRoadmap, nativeParsePlanFile } from './native-parser-bridge.js';

package/dist/resources/extensions/gsd/paths.js

@@ -16,7 +16,7 @@ import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree } from "./native-parser-bridge.js";
 import { DIR_CACHE_MAX } from "./constants.js";
 import { gsdHome } from "./gsd-home.js";
-import { isGsdWorktreePath, resolveExternalStateProjectGsdFromWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
+import { findWorktreeSegment, isGsdWorktreePath, resolveExternalStateProjectGsdFromWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
 // ─── Directory Listing Cache ──────────────────────────────────────────────────
 const dirEntryCache = new Map();
 const dirListCache = new Map();
@@ -139,6 +139,33 @@ export function clearPathCache() {
     nativeTreeBase = null;
 }
 // ─── Name Builders ─────────────────────────────────────────────────────────
+/** Directories owned by the GSD framework — metadata, never project source. */
+export const FRAMEWORK_METADATA_DIRS = [".gsd", ".planning", ".audits"];
+/**
+ * Every artifact suffix used with the name builders below — the single source
+ * for the `<ID>-<SUFFIX>.md` naming vocabulary. Extend this list when a new
+ * artifact type is introduced; consumers (md-importer walking, pre-execution
+ * artifact detection) pick it up from here.
+ */
+export const PLANNING_ARTIFACT_SUFFIXES = [
+    "CONTEXT",
+    "CONTEXT-DRAFT",
+    "ROADMAP",
+    "PLAN",
+    "REPLAN",
+    "SUMMARY",
+    "RESEARCH",
+    "VALIDATION",
+    "ASSESSMENT",
+    "UAT",
+    "DISCUSSION",
+    "EVAL-REVIEW",
+    "PARKED",
+    "VERIFICATION-FAILED",
+    "CONTINUE",
+];
+/** Matches a bare planning-artifact file name, e.g. "M001-CONTEXT.md", "S01-PLAN.md". */
+export const PLANNING_ARTIFACT_NAME_RE = new RegExp(`^[MST]\\d+-(${PLANNING_ARTIFACT_SUFFIXES.join("|")})\\.md$`, "i");
 /**
  * Build a milestone-level file name.
  * ("M001", "CONTEXT") → "M001-CONTEXT.md"
@@ -422,31 +449,17 @@ function assertNotGlobalGsdHome(basePath, result) {
  * When gsdRoot() is called with such a path, we must NOT walk up to the
  * project root's .gsd — each worktree manages its own .gsd state (#2594).
  *
- * Matches both forward-slash and platform-native separators to handle
- * Windows paths (path.sep = '\\') and normalized Unix paths.
+ * Layout matching is owned by worktree-root's findWorktreeSegment; this
+ * only adds the requirement that a non-empty worktree name follows the
+ * marker (the worktrees container dir itself is not a worktree).
  */
 function isInsideGsdWorktree(p) {
-    // Match /.gsd/worktrees/<name> where <name> is the final segment or
-    // followed by a separator. The <name> segment must be non-empty.
-    const sepFwd = "/";
-    const sepNative = "\\";
-    const markers = [
-        `${sepFwd}.gsd${sepFwd}worktrees${sepFwd}`,
-        `${sepNative}.gsd${sepNative}worktrees${sepNative}`,
-    ];
-    for (const marker of markers) {
-        const idx = p.indexOf(marker);
-        if (idx === -1)
-            continue;
-        // Verify there's a non-empty worktree name after the marker
-        const afterMarker = p.slice(idx + marker.length);
-        // The name is everything up to the next separator (or end of string)
-        const nameEnd = afterMarker.search(/[/\\]/);
-        const name = nameEnd === -1 ? afterMarker : afterMarker.slice(0, nameEnd);
-        if (name.length > 0)
-            return true;
-    }
-    return false;
+    const normalized = p.replaceAll("\\", "/");
+    const segment = findWorktreeSegment(normalized);
+    if (!segment)
+        return false;
+    const name = normalized.slice(segment.afterWorktrees).split("/")[0];
+    return name.length > 0;
 }
 function probeGsdRoot(rawBasePath) {
     const contract = resolveGsdPathContract(rawBasePath);

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

@@ -20,6 +20,7 @@ import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { isAbsolute, relative, resolve } from "node:path";
 import { validateVerificationCommand } from "./verification-gate.js";
+import { FRAMEWORK_METADATA_DIRS, PLANNING_ARTIFACT_NAME_RE } from "./paths.js";
 const NPM_COMMAND = process.platform === "win32" ? "npm.cmd" : "npm";
 function inputExistsOnDisk(normalizedFile, basePath, context) {
     if (existsSync(resolve(basePath, normalizedFile)))
@@ -510,6 +511,10 @@ export function checkFilePathConsistency(tasks, basePath, context) {
                 continue;
             if (!shouldValidateInputAsPath(file))
                 continue;
+            // Planning-artifact references are owned by checkPlanningArtifactReferences,
+            // which reports a precise removal message instead of "doesn't exist".
+            if (isPlanningArtifactReference(file, basePath, context))
+                continue;
             // Normalize path for consistent comparison
             const normalizedFile = toComparisonPath(file, basePath);
             if (containsGlobPattern(normalizedFile))
@@ -546,6 +551,71 @@ export function checkFilePathConsistency(tasks, basePath, context) {
     }
     return results;
 }
+// ─── Planning Artifact Reference Check ───────────────────────────────────────
+function isFrameworkMetadataPath(normalizedFile) {
+    return normalizedFile.split("/").some((segment) => FRAMEWORK_METADATA_DIRS.includes(segment.toLowerCase()));
+}
+/**
+ * True when a task IO entry references a GSD planning artifact.
+ *
+ * Task inputs are source files only — planning artifacts are projections of DB
+ * state that the framework preloads as composed context (see CONTEXT.md "Task
+ * Input"). Two triggers, deliberately different in strictness:
+ *
+ * - Any path entering framework-owned metadata (.gsd/, .planning/, .audits/)
+ *   is always a violation, even when the file exists.
+ * - A bare artifact-style basename (M001-CONTEXT.md, S01-PLAN.md, …) is a
+ *   violation only when it does NOT resolve to a real file. When such a file
+ *   genuinely exists in the source tree (e.g. a fixture), it is a source file
+ *   and stays legal; a path with directory components is likewise left to the
+ *   ordinary existence checks.
+ */
+function isPlanningArtifactReference(rawEntry, basePath, context) {
+    if (!shouldValidateInputAsPath(rawEntry))
+        return false;
+    const normalized = toComparisonPath(rawEntry, basePath);
+    if (isFrameworkMetadataPath(normalized))
+        return true;
+    return (!normalized.includes("/") &&
+        PLANNING_ARTIFACT_NAME_RE.test(normalized) &&
+        !inputExistsOnDisk(normalized, basePath, context));
+}
+/**
+ * Block GSD planning artifacts in task IO fields (inputs, files, expectedOutput).
+ *
+ * For inputs/files the violation smuggles a projection into the executor's
+ * preloaded source context; for expectedOutput it promises a write the runtime
+ * write-gate would reject mid-execution. Both get a precise message so the
+ * planning retry steers toward *removing* the reference, not creating the file.
+ * checkFilePathConsistency and checkTaskOrdering skip entries this check owns.
+ */
+export function checkPlanningArtifactReferences(tasks, basePath, context) {
+    const results = [];
+    for (const task of tasks) {
+        const fields = [
+            { label: "inputs", entries: task.inputs },
+            { label: "files", entries: task.files },
+            { label: "expectedOutput", entries: task.expected_output },
+        ];
+        for (const { label, entries } of fields) {
+            for (const file of entries) {
+                if (!isPlanningArtifactReference(file, basePath, context))
+                    continue;
+                const message = label === "expectedOutput"
+                    ? `Task ${task.id} lists '${file}' in expectedOutput — GSD planning artifacts are written by workflow tools (e.g. gsd_summary_save), never by tasks; remove it`
+                    : `Task ${task.id} lists '${file}' in ${label} — GSD planning artifacts are projections preloaded as context, never task ${label}; remove it`;
+                results.push({
+                    category: "file",
+                    target: file,
+                    passed: false,
+                    message,
+                    blocking: true,
+                });
+            }
+        }
+    }
+    return results;
+}
 // ─── Task Ordering Check ─────────────────────────────────────────────────────
 /**
  * Detect impossible task ordering: task N reads a file that task N+M creates.
@@ -583,6 +653,10 @@ export function checkTaskOrdering(tasks, basePath, context) {
                 continue;
             if (!shouldValidateInputAsPath(file))
                 continue;
+            // Owned by checkPlanningArtifactReferences — avoid a duplicate sequence
+            // finding on top of the removal message.
+            if (isPlanningArtifactReference(file, basePath, context))
+                continue;
             const normalizedFile = toComparisonPath(file, basePath);
             if (containsGlobPattern(normalizedFile))
                 continue;
@@ -611,6 +685,21 @@ export function checkTaskOrdering(tasks, basePath, context) {
     }
     return results;
 }
+// ─── Shared Path-Check Composition ───────────────────────────────────────────
+/**
+ * The synchronous path-shaped checks, in order. One list shared by the
+ * plan-persist gate (gsd_plan_slice) and the dispatch gate
+ * (runPreExecutionChecks) so the two cannot drift — the checks coordinate
+ * ownership of planning-artifact entries via isPlanningArtifactReference
+ * skips, which only works when they run as a set.
+ */
+export function runTaskPathChecks(tasks, basePath, context) {
+    return [
+        ...checkPlanningArtifactReferences(tasks, basePath, context),
+        ...checkFilePathConsistency(tasks, basePath, context),
+        ...checkTaskOrdering(tasks, basePath, context),
+    ];
+}
 /**
  * Extract function signatures from code blocks in task description.
  * Uses heuristic regex — not an AST parser.
@@ -741,11 +830,10 @@ export async function runPreExecutionChecks(tasks, basePath, context) {
     const startTime = Date.now();
     const allChecks = [];
     // Run sync checks first
-    const fileChecks = checkFilePathConsistency(tasks, basePath, context);
-    const orderingChecks = checkTaskOrdering(tasks, basePath, context);
+    const pathChecks = runTaskPathChecks(tasks, basePath, context);
     const contractChecks = checkInterfaceContracts(tasks, basePath);
     const verificationChecks = checkVerificationCommands(tasks);
-    allChecks.push(...fileChecks, ...orderingChecks, ...contractChecks, ...verificationChecks);
+    allChecks.push(...pathChecks, ...contractChecks, ...verificationChecks);
     // Run async package checks
     const packageChecks = await checkPackageExistence(tasks, basePath);
     allChecks.push(...packageChecks);

package/dist/resources/extensions/gsd/preferences-models.js

@@ -11,6 +11,7 @@ import { join } from "node:path";
 import { gsdHome } from "./gsd-home.js";
 import { canonicalModelForTier, defaultRoutingConfig, resolveModelForTier } from "./model-router.js";
 import { loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
+import { getUnitPhaseChain } from "./unit-registry.js";
 /**
  * Resolve which model ID to use for a given auto-mode unit type.
  * Returns undefined if no model preference is set for this unit type.
@@ -29,53 +30,18 @@ export function resolveModelForUnit(unitType) {
  * (`resolveThinkingLevelForUnit`) so the two never drift (ADR-026).
  */
 export function phaseChainForUnit(unitType) {
-    switch (unitType) {
-        case "research-milestone":
-        case "research-slice":
-        // Deep-mode project research orchestrator. Reads PROJECT.md / REQUIREMENTS.md
-        // and fans out research subagents. Routes to the research bucket.
-        case "research-project":
-            return ["research"];
-        case "plan-milestone":
-        case "plan-slice":
-        case "refine-slice":
-        case "replan-slice":
-            return ["planning"];
-        // Deep-mode project-level discussion units route to the same model bucket
-        // as milestone-level discussion (interactive interview style). Workflow
-        // preferences and research-decision are tiny ask_user_questions style units
-        // that share the discuss bucket because they are conversational. All fall
-        // back to planning when no `discuss` bucket is set.
-        case "discuss-milestone":
-        case "discuss-slice":
-        case "discuss-project":
-        case "discuss-requirements":
-        case "workflow-preferences":
-        case "research-decision":
-            return ["discuss", "planning"];
-        case "execute-task":
-        case "reactive-execute":
-            return ["execution"];
-        case "execute-task-simple":
-            return ["execution_simple", "execution"];
-        case "complete-slice":
-        case "complete-milestone":
-        case "worktree-merge":
-            return ["completion"];
-        case "run-uat":
-            return ["uat", "completion"];
-        case "reassess-roadmap":
-        case "rewrite-docs":
-        case "gate-evaluate":
-        case "validate-milestone":
-            return ["validation", "planning"];
-        default:
-            // Subagent unit types (e.g., "subagent", "subagent/scout")
-            if (unitType === "subagent" || unitType.startsWith("subagent/")) {
-                return ["subagent"];
-            }
-            return undefined;
+    // Unit types declare their chain on their Unit Descriptor (ADR-033).
+    const declared = getUnitPhaseChain(unitType);
+    if (declared)
+        return [...declared];
+    // Dispatch types without a Unit Descriptor.
+    if (unitType === "worktree-merge")
+        return ["completion"];
+    // Subagent unit types (e.g., "subagent", "subagent/scout")
+    if (unitType === "subagent" || unitType.startsWith("subagent/")) {
+        return ["subagent"];
     }
+    return undefined;
 }
 /**
  * Find the phase bucket whose `models` entry wins the chain for a unit, plus
@@ -196,8 +162,8 @@ export function resolveThinkingLevelForUnit(unitType) {
  * Returns `{ provider, id }` or `undefined` if no model preference is
  * configured.
  */
-export function resolveDefaultSessionModel(sessionProvider) {
-    const prefs = loadEffectiveGSDPreferences(undefined, { availableModelIds: [] });
+export function resolveDefaultSessionModel(sessionProvider, basePath) {
+    const prefs = loadEffectiveGSDPreferences(basePath, { availableModelIds: [] });
     const models = prefs?.preferences?.models;
     if (!models)
         return undefined;

package/dist/resources/extensions/gsd/preferences.js

@@ -699,6 +699,20 @@ export function getIsolationMode(basePath) {
         return "branch";
     return "none"; // default — no isolation, work on current branch
 }
+/**
+ * Resolve the isolation mode a unit actually runs under. A session whose
+ * worktree isolation has degraded (worktree creation failed) falls back to
+ * the milestone branch in the project root, so configured "worktree" becomes
+ * effective "branch". A stranded-work recovery session likewise runs under
+ * the adopted mode (`strandedRecoveryIsolationMode`) rather than the
+ * configured one until the recovered milestone merges — adopting the
+ * milestone branch in the project root is intentional, not degraded.
+ */
+export function resolveEffectiveUnitIsolationMode(configuredMode, isolationDegraded, strandedRecoveryIsolationMode = null) {
+    if (configuredMode === "worktree" && isolationDegraded)
+        return "branch";
+    return strandedRecoveryIsolationMode ?? configuredMode;
+}
 export function resolveParallelConfig(prefs) {
     return {
         enabled: prefs?.parallel?.enabled ?? false,

package/dist/resources/extensions/gsd/projection-flush.js

@@ -0,0 +1,7 @@
+// Project/App: gsd-pi
+// File Purpose: Single workflow projection flush seam for mutation exits.
+import { renderAllProjections } from "./workflow-projections.js";
+export async function flushWorkflowProjections(basePath, scope) {
+    await renderAllProjections(basePath, scope.milestoneId);
+    return { milestoneId: scope.milestoneId };
+}

package/dist/resources/extensions/gsd/prompts/complete-slice.md

@@ -24,7 +24,7 @@ Use `subagent` only when useful: reviewer, security, or tester. Apply findings b
 
 1. Use the inlined Slice Summary and UAT templates.
 2. {{skillActivation}}
-3. Run all slice-level verification through `gsd_exec` / Context Mode evidence; refresh current state if needed. Do not use direct `bash` for verification commands.
+3. Run all slice-level verification through `gsd_exec` / Context Mode evidence; refresh current state if needed. Do not use direct `bash` for verification commands. See the prepended **Tool Surface** block for unavailable tools.
 4. Complete only when every required check passes. If verification fails or source changes are needed, do **not** edit source files in this unit and do **not** call `gsd_slice_complete`.
 5. If verification fails:
    - Task-specific regressions: if the failure is in files the task touched and pre-task verification evidence shows it was absent before that task ran, call `gsd_task_reopen` with that task and reason.
@@ -36,7 +36,7 @@ Use `subagent` only when useful: reviewer, security, or tester. Apply findings b
 8. Address every Gate to Close. Q8 = **Operational Readiness**: health signal, failure signal, recovery, monitoring gaps. Omit empty sections.
 9. If requirement status changed, call `gsd_requirement_update`; do not write `.gsd/REQUIREMENTS.md` directly.
 10. Prepare `gsd_slice_complete` content with camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`.
-11. Draft concrete UAT with preconditions, steps, expected outcomes, edge cases, and UAT Type.
+11. Draft concrete UAT with preconditions, steps, expected outcomes, edge cases, and UAT Type. Declare the type as a bullet under a `## UAT Type` heading, exactly like `- UAT mode: browser-executable`.
     **Web apps:** when inlined Web App UAT guidance is present, declare `browser-executable` or `runtime-executable` (not `artifact-driven`) for localhost/browser/screenshot steps; include dev-server preconditions and name Playwright specs when they exist.
 12. Review the inlined task-summary excerpts for DECISIONS.md/KNOWLEDGE.md-worthy decisions and gotchas. Read full `*-SUMMARY.md` only if needed. Capture with `capture_thought`; do not append knowledge files.
 13. When verification passes, call `gsd_slice_complete`. The DB-backed tool is the canonical write path. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}`. Do not edit roadmap checkboxes.
@@ -49,4 +49,4 @@ Use `subagent` only when useful: reviewer, security, or tester. Apply findings b
 
 **You MUST call `gsd_slice_complete` with summary and UAT content only after verification passes.**
 
-When done, say: "Slice {{sliceId}} complete."
+When done, say: "Slice {{sliceId}} complete." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/execute-task.md

@@ -76,4 +76,4 @@ Keep about **{{verificationBudget}}** for verification and summary. If context i
 
 **You MUST call `gsd_task_complete` before finishing, including when the stale-path safety rule stops execution.**
 
-When done, say: "Task {{taskId}} complete."
+When done, say: "Task {{taskId}} complete." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/plan-milestone.md

@@ -118,4 +118,4 @@ If external API keys or secrets are required, use the inlined **Secrets Manifest
 
 If no external API keys or secrets are required, skip this step; do not create an empty manifest.
 
-When done, say: "Milestone {{milestoneId}} planned."
+When done, say: "Milestone {{milestoneId}} planned." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/plan-slice.md

@@ -45,7 +45,7 @@ If slice research is inlined, trust its architectural findings, but verify every
 6. Include Threat Surface (Q3), Requirement Impact (Q4), proof level, observability, integration closure, Failure Modes (Q5), Load Profile (Q6), and Negative Tests (Q7) only where applicable.
 7. Right-size tasks. Simple slices can be one task; split only when context, ownership, or verification boundaries justify it.
 8. Task `verify` commands must be safe, simple commands. Do not use shell pipes, redirects, semicolons, backticks, command substitution, output trimming, or grep regex alternation with `|`. If multiple checks are needed, create a small test file and run it with `node --test` or a package test script, or use separate simple commands joined only with `&&`. For absence checks, verify a pattern does not exist with `! grep -q 'pattern' file` or `! rg -q 'pattern' file`; do not use `grep -c` or `rg -c` to assert zero matches because count commands exit 1 when they find zero matches, and the verification gate treats that as failure.
-9. Each task needs the exact `gsd_plan_slice.tasks[]` shape: `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. `description` should contain the Why / Do / Done-when narrative. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even when there is only one path (for example, `"inputs": ["src/index.ts"]`, never `"inputs": "src/index.ts"`). Use paths relative to `{{workingDirectory}}`; do not put absolute paths to the original checkout or any directory outside `{{workingDirectory}}` in `files`, `inputs`, `expectedOutput`, or verification commands. **`expectedOutput` must only list files the task actually creates or overwrites on disk.** Do NOT include files the task merely reads, verifies, tests, or describes — those belong in `inputs`, `verify`, `description`, or slice success criteria. If a task is a pure verification or test task that produces no new files, `expectedOutput` must be `[]`; if it writes a test-result log or assertion output file, list only that concrete file path. A file that does not yet exist on disk and is needed as an `input` must be produced by an earlier task's `expectedOutput` — if no prior task creates it, add a task before this one that does.
+9. Each task needs the exact `gsd_plan_slice.tasks[]` shape: `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. `description` should contain the Why / Do / Done-when narrative. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even when there is only one path (for example, `"inputs": ["src/index.ts"]`, never `"inputs": "src/index.ts"`). Use paths relative to `{{workingDirectory}}`; do not put absolute paths to the original checkout or any directory outside `{{workingDirectory}}` in `files`, `inputs`, `expectedOutput`, or verification commands. **`expectedOutput` must only list files the task actually creates or overwrites on disk.** Do NOT include files the task merely reads, verifies, tests, or describes — those belong in `inputs`, `verify`, `description`, or slice success criteria. If a task is a pure verification or test task that produces no new files, `expectedOutput` must be `[]`; if it writes a test-result log or assertion output file, list only that concrete file path. A file that does not yet exist on disk and is needed as an `input` must be produced by an earlier task's `expectedOutput` — if no prior task creates it, add a task before this one that does. Never list GSD planning artifacts — anything under `.gsd/`, `.planning/`, or `.audits/`, or artifact names like `M001-CONTEXT.md` / `S01-PLAN.md` — in `inputs`, `files`, or `expectedOutput`: their content is preloaded as context, and they are written by workflow tools, not by tasks.
 10. Persist with `gsd_plan_slice` using `milestoneId`, `sliceId`, `goal`, optional `successCriteria`/`proofLevel`/`integrationClosure`/`observabilityImpact`, and `tasks`. `gsd_plan_slice` handles task persistence transactionally and renders `{{outputPath}}` plus task plans; do not call `gsd_plan_task`. The DB-backed tool is the canonical write path. Do **not** rely on direct `PLAN.md` writes as the source of truth.
 11. Self-audit before finishing: goal/demo closure, requirement coverage, deliverable coverage audit (cross-check every file listed in CONTEXT.md `## Scope` / `### In Scope` against task `files` or `expectedOutput`), locked decisions, concrete paths, dependency order, wiring, scope size, proof truthfulness, feature completeness, and quality gates. Quality gates: non-trivial slices/tasks include specific Q3-Q7 coverage where applicable.
 12. If planning creates structural decisions, call `gsd_decision_save` for each; the tool persists the decision and regenerates `.gsd/DECISIONS.md`.
@@ -57,4 +57,4 @@ The slice directory already exists. Do not mkdir.
 
 **You MUST call `gsd_plan_slice` to persist planning state before finishing, unless the stale-path safety rule above stops the unit before safe planning can occur.**
 
-When done, say: "Slice {{sliceId}} planned."
+When done, say: "Slice {{sliceId}} planned." Say this exactly once — if you already said it in a prior message, do not repeat it.