gsd-pi 2.32.0 → 2.33.0-dev.bafba33

package/README.md

@@ -24,21 +24,24 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.29
-
-- **Node.js 24 LTS** — CI, Docker, and package config all upgraded to Node 24 (Krypton)
-- **`searchExcludeDirs` setting** — blacklist directories from `@` file autocomplete (e.g., `node_modules`, `dist`)
-- **Automated releases** — prod-release now auto-generates changelogs, bumps versions, and publishes to npm
-- **`/gsd logs`** — browse activity, debug, and metrics logs from within a session
-- **Configurable screenshots** — browser-tools now support custom resolution, format, and quality
-- **Pre-commit secret scanning** — automatic detection of hardcoded secrets in CI and locally
-- **Per-project MCP config** — `.gsd/mcp.json` for project-scoped MCP server definitions
-- **API request metrics** — track request counts for Copilot/subscription users
-- **`/gsd keys`** — full API key lifecycle management (list, add, remove, test, rotate, doctor)
-- **Advisory verification gate** — auto-discovered checks (lint/test from package.json) no longer doom-loop on pre-existing errors
-- **Worktree living doc sync** — DECISIONS, REQUIREMENTS, PROJECT, and KNOWLEDGE now sync between worktree and project root
-- **Windows non-ASCII path support** — `cpSync` fallback for usernames with special characters
-- **`needs-discussion` routing** — milestones with draft context now route to the interactive discussion flow instead of stopping
+## What's New in v2.32
+
+- **Simplified pipeline** — research merged into planning, mechanical completion (ADR-003)
+- **Always-on health widget** — 🟢🟡🔴 traffic-light indicator in the progress widget and visualizer health tab
+- **Environment health checks** — progress scoring and status integration for auto-mode
+- **Extension registry** — user-managed enable/disable for bundled and custom extensions
+- **Built-in skill authoring** — create and distribute custom skills from within GSD
+- **Workflow templates** — right-sized workflows for every task type (research, plan, execute, complete)
+- **AWS Bedrock auth** — automatic credential refresh via the new `aws-auth` extension
+- **`-w` / `--worktree` CLI flag** — launch isolated worktree sessions from the command line
+- **Native MCP client** — replaced MCPorter with a built-in MCP client for better reliability
+- **External state directory** — `.gsd/` now lives in `~/.gsd/projects/` with a symlink (ADR-002)
+- **Model health indicator** — live health status based on error trends and consecutive failures
+- **Quick-task branch cleanup** — `/gsd quick` branches auto-merge back after completion
+- **Windows EPERM fallback** — migration rename uses copy+delete when NTFS blocks rename
+- **Worktree identity fix** — stable project hash across worktrees and main repo
+- **Crash recovery guidance** — actionable next-step messages based on what was interrupted
+- **UAT verdict gating** — non-PASS verdicts now block slice progression instead of being ignored
 
 See the full [Changelog](./CHANGELOG.md) for details.
 
@@ -65,6 +68,7 @@ Full documentation is available in the [`docs/`](./docs/) directory:
 - **[Visualizer](./docs/visualizer.md)** — workflow visualizer with stats and discussion status
 - **[Remote Questions](./docs/remote-questions.md)** — route decisions to Slack or Discord when human input is needed
 - **[Dynamic Model Routing](./docs/dynamic-model-routing.md)** — complexity-based model selection and budget pressure
+- **[Pipeline Simplification (ADR-003)](./docs/ADR-003-pipeline-simplification.md)** — merged research into planning, mechanical completion
 - **[Migration from v1](./docs/migration.md)** — `.planning` → `.gsd` migration
 
 ---
@@ -141,12 +145,12 @@ The iron rule: **a task must fit in one context window.** If it can't, it's two
 Each slice flows through phases automatically:
 
 ```
-Research → Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice
-                                                                      ↓ (all slices done)
-                                                              Validate Milestone → Complete Milestone
+Plan (with integrated research) → Execute (per task) → Complete → Reassess Roadmap → Next Slice
+                                                                                      ↓ (all slices done)
+                                                                              Validate Milestone → Complete Milestone
 ```
 
-**Research** scouts the codebase and relevant docs. **Plan** decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded — then runs configured verification commands (lint, test, etc.) with auto-fix retries. **Complete** writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
+**Plan** scouts the codebase, researches relevant docs, and decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded — then runs configured verification commands (lint, test, etc.) with auto-fix retries. **Complete** writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
 
 ### `/gsd auto` — The Main Event
 
@@ -326,6 +330,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `gsd headless [cmd]`    | Run `/gsd` commands without TUI (CI, cron, scripts)             |
 | `gsd headless query`    | Instant JSON snapshot — state, next dispatch, costs (no LLM)    |
 | `gsd --continue` (`-c`) | Resume the most recent session for the current directory        |
+| `gsd --worktree` (`-w`) | Launch an isolated worktree session for the active milestone    |
 | `gsd sessions`          | Interactive session picker — browse and resume any saved session |
 
 ---
@@ -483,7 +488,7 @@ See the full [Token Optimization Guide](./docs/token-optimization.md) for detail
 
 ### Bundled Tools
 
-GSD ships with 16 extensions, all loaded automatically:
+GSD ships with 18 extensions, all loaded automatically:
 
 | Extension              | What it provides                                                                                                       |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
@@ -503,6 +508,8 @@ GSD ships with 16 extensions, all loaded automatically:
 | **Secure Env Collect** | Masked secret collection without manual .env editing                                                                   |
 | **Remote Questions**   | Route decisions to Slack/Discord when human input is needed in headless/CI mode                                         |
 | **Universal Config**   | Discover and import MCP servers and rules from other AI coding tools                                                    |
+| **AWS Auth**           | Automatic Bedrock credential refresh for AWS-hosted models                                                              |
+| **TTSR**               | Tool-use type-safe runtime validation                                                                                   |
 
 ### Bundled Agents
 

package/dist/resource-loader.js

@@ -1,7 +1,7 @@
 import { DefaultResourceLoader } from '@gsd/pi-coding-agent';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
-import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { chmodSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { compareSemver } from './update-check.js';
@@ -118,7 +118,12 @@ export function getNewerManagedResourceVersion(agentDir, currentVersion) {
 function makeTreeWritable(dirPath) {
     if (!existsSync(dirPath))
         return;
-    const stats = statSync(dirPath);
+    // Use lstatSync to avoid following symlinks into immutable filesystems
+    // (e.g., Nix store on NixOS/nix-darwin). Symlinks don't carry their own
+    // permissions and their targets may be read-only by design (#1298).
+    const stats = lstatSync(dirPath);
+    if (stats.isSymbolicLink())
+        return;
     const isDir = stats.isDirectory();
     const currentMode = stats.mode & 0o777;
     // Ensure owner-write; for directories also ensure owner-exec so they remain traversable.
@@ -127,7 +132,12 @@ function makeTreeWritable(dirPath) {
         newMode |= 0o100;
     }
     if (newMode !== currentMode) {
-        chmodSync(dirPath, newMode);
+        try {
+            chmodSync(dirPath, newMode);
+        }
+        catch {
+            // Non-fatal — may fail on read-only filesystems or insufficient permissions
+        }
     }
     if (isDir) {
         for (const entry of readdirSync(dirPath, { withFileTypes: true })) {

package/dist/resources/extensions/gsd/auto-dashboard.ts

@@ -20,6 +20,7 @@ import { parseRoadmap, parsePlan } from "./files.js";
 import { readFileSync, existsSync } from "node:fs";
 import { truncateToWidth, visibleWidth } from "@gsd/pi-tui";
 import { makeUI, GLYPH, INDENT } from "../shared/mod.js";
+import { parseUnitId } from "./unit-id.js";
 
 // ─── Dashboard Data ───────────────────────────────────────────────────────────
 
@@ -372,8 +373,9 @@ export function updateProgressWidget(
         lines.push("");
 
         const isHook = unitType.startsWith("hook/");
+        const hookParsed = isHook ? parseUnitId(unitId) : undefined;
         const target = isHook
-          ? (unitId.split("/").pop() ?? unitId)
+          ? (hookParsed!.task ?? hookParsed!.slice ?? unitId)
           : (task ? `${task.id}: ${task.title}` : unitId);
         const actionLeft = `${pad}${theme.fg("accent", "▸")} ${theme.fg("accent", verb)}  ${theme.fg("text", target)}`;
         const tierTag = tierBadge ? theme.fg("dim", `[${tierBadge}] `) : "";

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

@@ -65,6 +65,28 @@ export function resetRewriteCircuitBreaker(): void {
   rewriteAttemptCount = 0;
 }
 
+/**
+ * Guard for accessing activeSlice/activeTask in dispatch rules.
+ * Returns a stop action if the expected ref is null (corrupt state).
+ */
+function requireSlice(state: GSDState): { sid: string; sTitle: string } | DispatchAction {
+  if (!state.activeSlice) {
+    return { action: "stop", reason: `Phase "${state.phase}" but no active slice — run /gsd doctor.`, level: "error" };
+  }
+  return { sid: state.activeSlice.id, sTitle: state.activeSlice.title };
+}
+
+function requireTask(state: GSDState): { sid: string; sTitle: string; tid: string; tTitle: string } | DispatchAction {
+  if (!state.activeSlice || !state.activeTask) {
+    return { action: "stop", reason: `Phase "${state.phase}" but no active slice/task — run /gsd doctor.`, level: "error" };
+  }
+  return { sid: state.activeSlice.id, sTitle: state.activeSlice.title, tid: state.activeTask.id, tTitle: state.activeTask.title };
+}
+
+function isStopAction(v: unknown): v is DispatchAction {
+  return typeof v === "object" && v !== null && "action" in v;
+}
+
 // ─── Rules ────────────────────────────────────────────────────────────────
 
 const DISPATCH_RULES: DispatchRule[] = [
@@ -93,8 +115,9 @@ const DISPATCH_RULES: DispatchRule[] = [
     name: "summarizing → complete-slice",
     match: async ({ state, mid, midTitle, basePath }) => {
       if (state.phase !== "summarizing") return null;
-      const sid = state.activeSlice!.id;
-      const sTitle = state.activeSlice!.title;
+      const sliceRef = requireSlice(state);
+      if (isStopAction(sliceRef)) return sliceRef as DispatchAction;
+      const { sid, sTitle } = sliceRef;
       return {
         action: "dispatch",
         unitType: "complete-slice",
@@ -222,8 +245,9 @@ const DISPATCH_RULES: DispatchRule[] = [
       if (state.phase !== "planning") return null;
       // Phase skip: skip research when preference or profile says so
       if (prefs?.phases?.skip_research || prefs?.phases?.skip_slice_research) return null;
-      const sid = state.activeSlice!.id;
-      const sTitle = state.activeSlice!.title;
+      const sliceRef = requireSlice(state);
+      if (isStopAction(sliceRef)) return sliceRef as DispatchAction;
+      const { sid, sTitle } = sliceRef;
       const researchFile = resolveSliceFile(basePath, mid, sid, "RESEARCH");
       if (researchFile) return null; // has research, fall through
       // Skip slice research for S01 when milestone research already exists —
@@ -242,8 +266,9 @@ const DISPATCH_RULES: DispatchRule[] = [
     name: "planning → plan-slice",
     match: async ({ state, mid, midTitle, basePath }) => {
       if (state.phase !== "planning") return null;
-      const sid = state.activeSlice!.id;
-      const sTitle = state.activeSlice!.title;
+      const sliceRef = requireSlice(state);
+      if (isStopAction(sliceRef)) return sliceRef as DispatchAction;
+      const { sid, sTitle } = sliceRef;
       return {
         action: "dispatch",
         unitType: "plan-slice",
@@ -256,8 +281,9 @@ const DISPATCH_RULES: DispatchRule[] = [
     name: "replanning-slice → replan-slice",
     match: async ({ state, mid, midTitle, basePath }) => {
       if (state.phase !== "replanning-slice") return null;
-      const sid = state.activeSlice!.id;
-      const sTitle = state.activeSlice!.title;
+      const sliceRef = requireSlice(state);
+      if (isStopAction(sliceRef)) return sliceRef as DispatchAction;
+      const { sid, sTitle } = sliceRef;
       return {
         action: "dispatch",
         unitType: "replan-slice",
@@ -270,8 +296,9 @@ const DISPATCH_RULES: DispatchRule[] = [
     name: "executing → execute-task (recover missing task plan → plan-slice)",
     match: async ({ state, mid, midTitle, basePath }) => {
       if (state.phase !== "executing" || !state.activeTask) return null;
-      const sid = state.activeSlice!.id;
-      const sTitle = state.activeSlice!.title;
+      const sliceRef = requireSlice(state);
+      if (isStopAction(sliceRef)) return sliceRef as DispatchAction;
+      const { sid, sTitle } = sliceRef;
       const tid = state.activeTask.id;
 
       // Guard: if the slice plan exists but the individual task plan files are
@@ -296,8 +323,9 @@ const DISPATCH_RULES: DispatchRule[] = [
     name: "executing → execute-task",
     match: async ({ state, mid, basePath }) => {
       if (state.phase !== "executing" || !state.activeTask) return null;
-      const sid = state.activeSlice!.id;
-      const sTitle = state.activeSlice!.title;
+      const sliceRef = requireSlice(state);
+      if (isStopAction(sliceRef)) return sliceRef as DispatchAction;
+      const { sid, sTitle } = sliceRef;
       const tid = state.activeTask.id;
       const tTitle = state.activeTask.title;
 

package/dist/resources/extensions/gsd/auto-idempotency.ts

@@ -18,6 +18,7 @@ import {
 import { resolveMilestoneFile } from "./paths.js";
 import { MAX_CONSECUTIVE_SKIPS, MAX_LIFETIME_DISPATCHES } from "./auto/session.js";
 import type { AutoSession } from "./auto/session.js";
+import { parseUnitId } from "./unit-id.js";
 
 export interface IdempotencyContext {
   s: AutoSession;
@@ -54,7 +55,7 @@ export function checkIdempotency(ictx: IdempotencyContext): IdempotencyResult {
       s.unitConsecutiveSkips.set(idempotencyKey, skipCount);
       if (skipCount > MAX_CONSECUTIVE_SKIPS) {
         // Cross-check: verify the unit's milestone is still active (#790)
-        const skippedMid = unitId.split("/")[0];
+        const skippedMid = parseUnitId(unitId).milestone;
         const skippedMilestoneComplete = skippedMid
           ? !!resolveMilestoneFile(basePath, skippedMid, "SUMMARY")
           : false;
@@ -110,7 +111,7 @@ export function checkIdempotency(ictx: IdempotencyContext): IdempotencyResult {
     const skipCount2 = (s.unitConsecutiveSkips.get(idempotencyKey) ?? 0) + 1;
     s.unitConsecutiveSkips.set(idempotencyKey, skipCount2);
     if (skipCount2 > MAX_CONSECUTIVE_SKIPS) {
-      const skippedMid2 = unitId.split("/")[0];
+      const skippedMid2 = parseUnitId(unitId).milestone;
       const skippedMilestoneComplete2 = skippedMid2
         ? !!resolveMilestoneFile(basePath, skippedMid2, "SUMMARY")
         : false;

package/dist/resources/extensions/gsd/auto-observability.ts

@@ -12,6 +12,7 @@ import {
   formatValidationIssues,
 } from "./observability-validator.js";
 import type { ValidationIssue } from "./observability-validator.js";
+import { parseUnitId } from "./unit-id.js";
 
 export async function collectObservabilityWarnings(
   ctx: ExtensionContext,
@@ -22,10 +23,7 @@ export async function collectObservabilityWarnings(
   // Hook units have custom artifacts — skip standard observability checks
   if (unitType.startsWith("hook/")) return [];
 
-  const parts = unitId.split("/");
-  const mid = parts[0];
-  const sid = parts[1];
-  const tid = parts[2];
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
 
   if (!mid || !sid) return [];
 

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

@@ -61,6 +61,7 @@ import {
 } from "./auto-dashboard.js";
 import { join } from "node:path";
 import { STATE_REBUILD_MIN_INTERVAL_MS } from "./auto-constants.js";
+import { parseUnitId } from "./unit-id.js";
 
 /**
  * Initialize a unit dispatch: stamp the current time, set `s.currentUnit`,
@@ -134,8 +135,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
       let taskContext: TaskCommitContext | undefined;
 
       if (s.currentUnit.type === "execute-task") {
-        const parts = s.currentUnit.id.split("/");
-        const [mid, sid, tid] = parts;
+        const { milestone: mid, slice: sid, task: tid } = parseUnitId(s.currentUnit.id);
         if (mid && sid && tid) {
           const summaryPath = resolveTaskFile(s.basePath, mid, sid, tid, "SUMMARY");
           if (summaryPath) {
@@ -167,8 +167,8 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
 
     // Doctor: fix mechanical bookkeeping
     try {
-      const scopeParts = s.currentUnit.id.split("/").slice(0, 2);
-      const doctorScope = scopeParts.join("/");
+      const { milestone, slice } = parseUnitId(s.currentUnit.id);
+      const doctorScope = slice ? `${milestone}/${slice}` : milestone;
       const sliceTerminalUnits = new Set(["complete-slice", "run-uat"]);
       const effectiveFixLevel = sliceTerminalUnits.has(s.currentUnit.type) ? "all" as const : "task" as const;
       const report = await runGSDDoctor(s.basePath, { fix: true, scope: doctorScope, fixLevel: effectiveFixLevel });
@@ -348,7 +348,7 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
   // instead of dispatching LLM sessions for complete-slice / validate-milestone.
   if (s.currentUnit?.type === "execute-task" && !s.stepMode) {
     try {
-      const [mid, sid] = s.currentUnit.id.split("/");
+      const { milestone: mid, slice: sid } = parseUnitId(s.currentUnit.id);
       if (mid && sid) {
         const state = await deriveState(s.basePath);
         if (state.phase === "summarizing" && state.activeSlice?.id === sid) {

package/dist/resources/extensions/gsd/auto-prompts.ts

@@ -189,30 +189,52 @@ export async function inlineGsdRootFile(
 // ─── DB-Aware Inline Helpers ──────────────────────────────────────────────
 
 /**
- * Inline decisions with optional milestone scoping from the DB.
- * Falls back to filesystem via inlineGsdRootFile when DB unavailable or empty.
+ * Shared DB-fallback pattern: attempt a DB query via the context-store, format
+ * the result, and fall back to the filesystem file when the DB is unavailable
+ * or the query yields no results.
+ *
+ * @param base       Project root for filesystem fallback
+ * @param label      Section heading (e.g. "Decisions")
+ * @param filename   Filesystem fallback file (e.g. "decisions.md")
+ * @param queryDb    Async callback receiving the dynamically-imported
+ *                   context-store module. Returns formatted markdown or null.
  */
-export async function inlineDecisionsFromDb(
-  base: string, milestoneId?: string, scope?: string, level?: InlineLevel,
+async function inlineFromDbOrFile(
+  base: string,
+  label: string,
+  filename: string,
+  queryDb: (cs: typeof import("./context-store.js")) => string | null,
 ): Promise<string | null> {
-  const inlineLevel = level ?? resolveInlineLevel();
   try {
     const { isDbAvailable } = await import("./gsd-db.js");
     if (isDbAvailable()) {
-      const { queryDecisions, formatDecisionsForPrompt } = await import("./context-store.js");
-      const decisions = queryDecisions({ milestoneId, scope });
-      if (decisions.length > 0) {
-        // Use compact format for non-full levels to save ~35% tokens
-        const formatted = inlineLevel !== "full"
-          ? formatDecisionsCompact(decisions)
-          : formatDecisionsForPrompt(decisions);
-        return `### Decisions\nSource: \`.gsd/DECISIONS.md\`\n\n${formatted}`;
+      const contextStore = await import("./context-store.js");
+      const content = queryDb(contextStore);
+      if (content) {
+        return `### ${label}\nSource: \`.gsd/${filename.toUpperCase().replace(/\.MD$/i, "")}.md\`\n\n${content}`;
       }
     }
   } catch {
     // DB not available — fall through to filesystem
   }
-  return inlineGsdRootFile(base, "decisions.md", "Decisions");
+  return inlineGsdRootFile(base, filename, label);
+}
+
+/**
+ * Inline decisions with optional milestone scoping from the DB.
+ * Falls back to filesystem via inlineGsdRootFile when DB unavailable or empty.
+ */
+export async function inlineDecisionsFromDb(
+  base: string, milestoneId?: string, scope?: string, level?: InlineLevel,
+): Promise<string | null> {
+  const inlineLevel = level ?? resolveInlineLevel();
+  return inlineFromDbOrFile(base, "Decisions", "decisions.md", (cs) => {
+    const decisions = cs.queryDecisions({ milestoneId, scope });
+    if (decisions.length === 0) return null;
+    return inlineLevel !== "full"
+      ? formatDecisionsCompact(decisions)
+      : cs.formatDecisionsForPrompt(decisions);
+  });
 }
 
 /**
@@ -223,23 +245,13 @@ export async function inlineRequirementsFromDb(
   base: string, sliceId?: string, level?: InlineLevel,
 ): Promise<string | null> {
   const inlineLevel = level ?? resolveInlineLevel();
-  try {
-    const { isDbAvailable } = await import("./gsd-db.js");
-    if (isDbAvailable()) {
-      const { queryRequirements, formatRequirementsForPrompt } = await import("./context-store.js");
-      const requirements = queryRequirements({ sliceId });
-      if (requirements.length > 0) {
-        // Use compact format for non-full levels to save ~40% tokens
-        const formatted = inlineLevel !== "full"
-          ? formatRequirementsCompact(requirements)
-          : formatRequirementsForPrompt(requirements);
-        return `### Requirements\nSource: \`.gsd/REQUIREMENTS.md\`\n\n${formatted}`;
-      }
-    }
-  } catch {
-    // DB not available — fall through to filesystem
-  }
-  return inlineGsdRootFile(base, "requirements.md", "Requirements");
+  return inlineFromDbOrFile(base, "Requirements", "requirements.md", (cs) => {
+    const requirements = cs.queryRequirements({ sliceId });
+    if (requirements.length === 0) return null;
+    return inlineLevel !== "full"
+      ? formatRequirementsCompact(requirements)
+      : cs.formatRequirementsForPrompt(requirements);
+  });
 }
 
 /**
@@ -249,19 +261,9 @@ export async function inlineRequirementsFromDb(
 export async function inlineProjectFromDb(
   base: string,
 ): Promise<string | null> {
-  try {
-    const { isDbAvailable } = await import("./gsd-db.js");
-    if (isDbAvailable()) {
-      const { queryProject } = await import("./context-store.js");
-      const content = queryProject();
-      if (content) {
-        return `### Project\nSource: \`.gsd/PROJECT.md\`\n\n${content}`;
-      }
-    }
-  } catch {
-    // DB not available — fall through to filesystem
-  }
-  return inlineGsdRootFile(base, "project.md", "Project");
+  return inlineFromDbOrFile(base, "Project", "project.md", (cs) => {
+    return cs.queryProject();
+  });
 }
 
 // ─── Skill Discovery ──────────────────────────────────────────────────────

package/dist/resources/extensions/gsd/auto-recovery.ts

@@ -42,6 +42,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "
 import { atomicWriteSync } from "./atomic-write.js";
 import { loadJsonFileOrNull } from "./json-persistence.js";
 import { dirname, join } from "node:path";
+import { parseUnitId } from "./unit-id.js";
 
 // ─── Artifact Resolution & Verification ───────────────────────────────────────
 
@@ -49,9 +50,7 @@ import { dirname, join } from "node:path";
  * Resolve the expected artifact for a unit to an absolute path.
  */
 export function resolveExpectedArtifactPath(unitType: string, unitId: string, base: string): string | null {
-  const parts = unitId.split("/");
-  const mid = parts[0]!;
-  const sid = parts[1];
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
   switch (unitType) {
     case "research-milestone": {
       const dir = resolveMilestonePath(base, mid);
@@ -78,7 +77,6 @@ export function resolveExpectedArtifactPath(unitType: string, unitId: string, ba
       return dir ? join(dir, buildSliceFileName(sid!, "UAT-RESULT")) : null;
     }
     case "execute-task": {
-      const tid = parts[2];
       const dir = resolveSlicePath(base, mid, sid!);
       return dir && tid ? join(dir, "tasks", buildTaskFileName(tid, "SUMMARY")) : null;
     }
@@ -167,10 +165,7 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
 
   // execute-task must also have its checkbox marked [x] in the slice plan
   if (unitType === "execute-task") {
-    const parts = unitId.split("/");
-    const mid = parts[0];
-    const sid = parts[1];
-    const tid = parts[2];
+    const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
     if (mid && sid && tid) {
       const planAbs = resolveSliceFile(base, mid, sid, "PLAN");
       if (planAbs && existsSync(planAbs)) {
@@ -187,9 +182,7 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
   // but omitted T{tid}-PLAN.md files would be marked complete, causing execute-task
   // to dispatch with a missing task plan (see issue #739).
   if (unitType === "plan-slice") {
-    const parts = unitId.split("/");
-    const mid = parts[0];
-    const sid = parts[1];
+    const { milestone: mid, slice: sid } = parseUnitId(unitId);
     if (mid && sid) {
       try {
         const planContent = readFileSync(absPath, "utf-8");
@@ -213,9 +206,8 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
   // state machine keeps returning the same complete-slice unit (roadmap still shows
   // the slice incomplete), so dispatchNextUnit recurses forever.
   if (unitType === "complete-slice") {
-    const parts = unitId.split("/");
-    const mid = parts[0];
-    const sid = parts[1];
+    const { milestone: mid, slice: sid } = parseUnitId(unitId);
+
     if (mid && sid) {
       const dir = resolveSlicePath(base, mid, sid);
       if (dir) {
@@ -268,9 +260,7 @@ export function writeBlockerPlaceholder(unitType: string, unitId: string, base:
 }
 
 export function diagnoseExpectedArtifact(unitType: string, unitId: string, base: string): string | null {
-  const parts = unitId.split("/");
-  const mid = parts[0];
-  const sid = parts[1];
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
   switch (unitType) {
     case "research-milestone":
       return `${relMilestoneFile(base, mid!, "RESEARCH")} (milestone research)`;
@@ -281,7 +271,6 @@ export function diagnoseExpectedArtifact(unitType: string, unitId: string, base:
     case "plan-slice":
       return `${relSliceFile(base, mid!, sid!, "PLAN")} (slice plan)`;
     case "execute-task": {
-      const tid = parts[2];
       return `Task ${tid} marked [x] in ${relSliceFile(base, mid!, sid!, "PLAN")} + summary written`;
     }
     case "complete-slice":
@@ -539,10 +528,7 @@ export async function selfHealRuntimeRecords(
  * These are shown when automatic reconciliation is not possible.
  */
 export function buildLoopRemediationSteps(unitType: string, unitId: string, base: string): string | null {
-  const parts = unitId.split("/");
-  const mid = parts[0];
-  const sid = parts[1];
-  const tid = parts[2];
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
   switch (unitType) {
     case "execute-task": {
       if (!mid || !sid || !tid) break;

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

@@ -63,6 +63,8 @@ import { debugLog, enableDebug, isDebugEnabled, getDebugLogPath } from "./debug-
 import type { AutoSession } from "./auto/session.js";
 import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
+import { getErrorMessage } from "./error-utils.js";
+import { parseUnitId } from "./unit-id.js";
 
 export interface BootstrapDeps {
   shouldUseWorktreeIsolation: () => boolean;
@@ -138,7 +140,7 @@ export async function bootstrapAutoSession(
   if (crashLock && crashLock.pid !== process.pid) {
     // We already hold the session lock, so no concurrent session is running.
     // The crash lock is from a dead process — recover context from it.
-    const recoveredMid = crashLock.unitId.split("/")[0];
+    const recoveredMid = parseUnitId(crashLock.unitId).milestone;
     const milestoneAlreadyComplete = recoveredMid
       ? !!resolveMilestoneFile(base, recoveredMid, "SUMMARY")
       : false;
@@ -201,11 +203,11 @@ export async function bootstrapAutoSession(
         if (!midMatch) continue;
         const mid = midMatch[1];
         if (resolveMilestoneFile(base, mid, "SUMMARY")) {
-          try { unlinkSync(join(runtimeUnitsDir, file)); } catch (e) { debugLog("stale-unit-cleanup-failed", { file, error: e instanceof Error ? e.message : String(e) }); }
+          try { unlinkSync(join(runtimeUnitsDir, file)); } catch (e) { debugLog("stale-unit-cleanup-failed", { file, error: getErrorMessage(e) }); }
         }
       }
     }
-  } catch (e) { debugLog("stale-unit-dir-cleanup-failed", { error: e instanceof Error ? e.message : String(e) }); }
+  } catch (e) { debugLog("stale-unit-dir-cleanup-failed", { error: getErrorMessage(e) }); }
 
   let state = await deriveState(base);
 
@@ -343,7 +345,7 @@ export async function bootstrapAutoSession(
       registerSigtermHandler(s.originalBasePath);
     } catch (err) {
       ctx.ui.notify(
-        `Auto-worktree setup failed: ${err instanceof Error ? err.message : String(err)}. Continuing in project root.`,
+        `Auto-worktree setup failed: ${getErrorMessage(err)}. Continuing in project root.`,
         "warning",
       );
     }
@@ -435,7 +437,7 @@ export async function bootstrapAutoSession(
     }
   } catch (err) {
     ctx.ui.notify(
-      `Secrets check error: ${err instanceof Error ? err.message : String(err)}. Continuing without secrets.`,
+      `Secrets check error: ${getErrorMessage(err)}. Continuing without secrets.`,
       "warning",
     );
   }
@@ -453,7 +455,7 @@ export async function bootstrapAutoSession(
         ctx.ui.notify("Removed stale .git/index.lock from prior crash.", "info");
       }
     }
-  } catch (e) { debugLog("git-lock-cleanup-failed", { error: e instanceof Error ? e.message : String(e) }); }
+  } catch (e) { debugLog("git-lock-cleanup-failed", { error: getErrorMessage(e) }); }
 
   // Pre-flight: validate milestone queue
   try {

package/dist/resources/extensions/gsd/auto-stuck-detection.ts

@@ -39,6 +39,7 @@ import {
 import type { AutoSession } from "./auto/session.js";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { parseUnitId } from "./unit-id.js";
 
 export interface StuckContext {
   s: AutoSession;
@@ -99,7 +100,7 @@ export async function checkStuckAndRecover(sctx: StuckContext): Promise<StuckRes
 
     // Final reconciliation pass for execute-task
     if (unitType === "execute-task") {
-      const [mid, sid, tid] = unitId.split("/");
+      const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
       if (mid && sid && tid) {
         const status = await inspectExecuteTaskDurability(basePath, unitId);
         if (status) {
@@ -168,7 +169,7 @@ export async function checkStuckAndRecover(sctx: StuckContext): Promise<StuckRes
     // Adaptive self-repair: each retry attempts a different remediation step.
     if (unitType === "execute-task") {
       const status = await inspectExecuteTaskDurability(basePath, unitId);
-      const [mid, sid, tid] = unitId.split("/");
+      const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
       if (status && mid && sid && tid) {
         if (status.summaryExists && !status.taskChecked) {
           const repaired = skipExecuteTask(basePath, mid, sid, tid, status, "self-repair", 0);