gsd-pi 2.78.1-dev.82bcf6b71 → 2.78.1-dev.84c045fd2

package/README.md

@@ -310,7 +310,9 @@ This is what makes GSD different. Run it, walk away, come back to built software
 /gsd auto
 ```
 
-Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`, determines the next unit of work, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode reads disk state again and dispatches the next unit.
+Auto mode is a state machine driven by the GSD database at the project root. It derives the next unit of work from authoritative SQLite state, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode persists the result to the database, refreshes markdown projections such as `STATE.md`, and dispatches the next unit.
+
+The database is authoritative for milestones, slices, tasks, requirements, decisions, summaries, and completion status. Markdown under `.gsd/` is a rendered projection for review, prompts, and git-friendly history; it is not a runtime fallback unless you explicitly run a recovery/import command. In worktree mode, project-root DB state remains authoritative and worktree markdown projections are not synced back as state.
 
 **What happens under the hood:**
 
@@ -318,7 +320,7 @@ Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`,
 
 2. **Context pre-loading** — The dispatch prompt includes inlined task plans, slice plans, prior task summaries, dependency summaries, roadmap excerpts, and decisions register. The LLM starts with everything it needs instead of spending tool calls reading files.
 
-3. **Git isolation** — When `git.isolation` is set to `worktree` or `branch`, each milestone runs on its own `milestone/<MID>` branch (in a worktree or in-place). All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit. The default is `none` (work on the current branch), configurable via preferences.
+3. **Git isolation** — When `git.isolation` is set to `worktree` or `branch`, each milestone runs on its own `milestone/<MID>` branch (in a worktree or in-place). All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit. The default is `none` (work on the current branch), configurable via preferences. If `worktree` is configured in a repo with no committed `HEAD`, GSD temporarily behaves as `none` until the first commit exists because git worktrees need a committed start point.
 
 4. **Crash recovery** — A lock file tracks the current unit. If the session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context. Parallel orchestrator state is persisted to disk with PID liveness detection, so multi-worker sessions survive crashes too. In headless mode, crashes trigger automatic restart with exponential backoff (default 3 attempts).
 
@@ -450,6 +452,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd`                  | Step mode — executes one unit at a time, pauses between each                  |
 | `/gsd next`             | Explicit step mode (same as bare `/gsd`)                                      |
 | `/gsd auto`             | Autonomous mode — researches, plans, executes, commits, repeats               |
+| `/gsd new-project [--deep]` | Bootstrap a project with staged project-level discovery                  |
 | `/gsd quick`            | Execute a quick task with GSD guarantees, skip planning overhead              |
 | `/gsd stop`             | Stop auto mode gracefully                                                     |
 | `/gsd steer`            | Hard-steer plan documents during execution                                    |
@@ -498,11 +501,15 @@ Every dispatch is carefully constructed. The LLM never wastes tool calls on orie
 
 | Artifact           | Purpose                                                         |
 | ------------------ | --------------------------------------------------------------- |
+| `gsd.db`           | Authoritative runtime state for hierarchy and completion        |
 | `PROJECT.md`       | Living doc — what the project is right now                      |
+| `REQUIREMENTS.md`  | Project-level capability contract and out-of-scope list         |
 | `DECISIONS.md`     | Append-only register of architectural decisions                 |
 | `KNOWLEDGE.md`     | Cross-session rules, patterns, and lessons learned              |
 | `RUNTIME.md`       | Runtime context — API endpoints, env vars, services (v2.39)     |
-| `STATE.md`         | Quick-glance dashboard — always read first                      |
+| `runtime/research-decision.json` | Deep-mode marker for project research vs skip       |
+| `research/*.md`    | Optional deep-mode project research: stack, features, architecture, pitfalls |
+| `STATE.md`         | Quick-glance dashboard rendered from the database                |
 | `M001-ROADMAP.md`  | Milestone plan with slice checkboxes, risk levels, dependencies |
 | `M001-CONTEXT.md`  | User decisions from the discuss phase                           |
 | `M001-RESEARCH.md` | Codebase and ecosystem research                                 |
@@ -598,6 +605,7 @@ auto_report: true
 | Setting                           | What it controls                                                                                      |
 | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
 | `models.*`                        | Per-phase model selection — string for a single model, or `{model, fallbacks}` for automatic failover |
+| `planning_depth`                  | `light` / `deep` — opt into staged project discovery before milestone planning                         |
 | `skill_discovery`                 | `auto` / `suggest` / `off` — how GSD finds and applies skills                                         |
 | `auto_supervisor.*`               | Timeout thresholds for auto mode supervision                                                          |
 | `budget_ceiling`                  | USD ceiling — auto mode pauses when reached                                                           |
@@ -606,7 +614,7 @@ auto_report: true
 | `skill_rules`                     | Situational rules for skill routing                                                                   |
 | `skill_staleness_days`            | Skills unused for N days get deprioritized (default: 60, 0 = disabled)                                |
 | `unique_milestone_ids`            | Uses unique milestone names to avoid clashes when working in teams of people                          |
-| `git.isolation`                   | `none` (default), `worktree`, or `branch` — enable worktree or branch isolation for milestone work    |
+| `git.isolation`                   | `none` (default), `worktree`, or `branch` — enable worktree or branch isolation for milestone work. `worktree` requires a committed `HEAD`; zero-commit repos temporarily run as `none`    |
 | `git.manage_gitignore`            | Set `false` to prevent GSD from modifying `.gitignore`                                                |
 | `verification_commands`           | Array of shell commands to run after task execution (e.g., `["npm run lint", "npm run test"]`)        |
 | `verification_auto_fix`           | Auto-retry on verification failures (default: true)                                                   |
@@ -703,7 +711,7 @@ The best practice for working in teams is to ensure unique milestone names acros
 .gsd/completed-units*.json
 # State manifest — workflow state for recovery
 .gsd/state-manifest.json
-# Derived state cache — regenerated from plan/roadmap files on disk
+# Derived state projection — regenerated from the authoritative database
 .gsd/STATE.md
 # Per-developer token/cost accumulator
 .gsd/metrics.json
@@ -715,7 +723,7 @@ The best practice for working in teams is to ensure unique milestone names acros
 .gsd/worktrees/
 # Parallel orchestration IPC and worker status
 .gsd/parallel/
-# SQLite database and WAL sidecars — checkpoint state, forensics data
+# SQLite database and WAL sidecars — authoritative runtime state, local only
 .gsd/gsd.db*
 # Daily-rotated event journal — structured event log for forensics
 .gsd/journal/
@@ -780,7 +788,7 @@ gsd (CLI binary)
 - **`pkg/` shim directory** — `PI_PACKAGE_DIR` points here (not project root) to avoid Pi's theme resolution collision with our `src/` directory. Contains only `piConfig` and theme assets.
 - **Two-file loader pattern** — `loader.ts` sets all env vars with zero SDK imports, then dynamic-imports `cli.ts` which does static SDK imports. This ensures `PI_PACKAGE_DIR` is set before any SDK code evaluates.
 - **Always-overwrite sync** — `npm update -g` takes effect immediately. Bundled extensions and agents are synced to `~/.gsd/agent/` on every launch, not just first run.
-- **State lives on disk** — `.gsd/` is the source of truth. Auto mode reads it, writes it, and advances based on what it finds. No in-memory state survives across sessions.
+- **DB-authoritative state** — the project-root GSD database is the runtime source of truth. `.gsd/` markdown files are rendered projections for review, prompt context, and git history. No in-memory state survives across sessions.
 
 ---
 

package/dist/cli-auto-routing.d.ts

@@ -0,0 +1 @@
+export declare function shouldRedirectAutoToHeadless(subcommand: string | undefined, stdinIsTTY: boolean | undefined, stdoutIsTTY: boolean | undefined): boolean;

package/dist/cli-auto-routing.js

@@ -0,0 +1,5 @@
+export function shouldRedirectAutoToHeadless(subcommand, stdinIsTTY, stdoutIsTTY) {
+    if (subcommand !== 'auto')
+        return false;
+    return stdinIsTTY !== true || stdoutIsTTY !== true;
+}

package/dist/cli.js

@@ -9,6 +9,7 @@ import { shouldRunOnboarding, runOnboarding } from './onboarding.js';
 import chalk from 'chalk';
 import { checkForUpdates } from './update-check.js';
 import { shouldBypassManagedResourceMismatchGate } from './cli-policy.js';
+import { shouldRedirectAutoToHeadless } from './cli-auto-routing.js';
 import { printHelp, printSubcommandHelp } from './help-text.js';
 import { applySecurityOverrides } from './security-overrides.js';
 import { validateConfiguredModel } from './startup-model-validation.js';
@@ -409,10 +410,10 @@ function flushPendingProviderRegistrations(resourceLoader, modelRegistry) {
     }
     runtime.pendingProviderRegistrations = [];
 }
-// `gsd auto [args...]` — shorthand for `gsd headless auto [args...]` (#2732)
-// Without this, `gsd auto` falls through to the interactive TUI which hangs
-// when stdin/stdout are piped (non-TTY environments).
-if (cliFlags.messages[0] === 'auto') {
+// `gsd auto [args...]` with piped stdin/stdout — shorthand for
+// `gsd headless auto [args...]` (#2732). Keep terminal TTY launches in the
+// interactive path so Warp/iTerm/Terminal retain foreground ownership.
+if (shouldRedirectAutoToHeadless(cliFlags.messages[0], process.stdin.isTTY, process.stdout.isTTY)) {
     await runHeadlessFromAuto(buildHeadlessAutoArgs(cliFlags));
 }
 // ---------------------------------------------------------------------------
@@ -656,16 +657,6 @@ if (!cliFlags.worktree && !isPrintMode) {
 }
 markStartup('worktreeStatusBanner');
 // ---------------------------------------------------------------------------
-// Auto-redirect: `gsd auto` with piped stdout → headless mode (#2732)
-// When stdout is not a TTY (e.g. `gsd auto | cat`, `gsd auto > file`),
-// the TUI cannot render and the process hangs. Redirect to headless mode
-// which handles non-interactive output gracefully.
-// ---------------------------------------------------------------------------
-if (cliFlags.messages[0] === 'auto' && !process.stdout.isTTY) {
-    process.stderr.write('[gsd] stdout is not a terminal — running auto-mode in headless mode.\n');
-    await runHeadlessFromAuto(cliFlags.messages.slice(1));
-}
-// ---------------------------------------------------------------------------
 // Interactive mode — normal TTY session
 // ---------------------------------------------------------------------------
 await ensureRtkBootstrap();

package/dist/headless-recover.d.ts

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

package/dist/headless-recover.js

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

package/dist/headless.js

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

package/dist/help-text.js

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

package/dist/loader.js

@@ -113,9 +113,21 @@ const { Module } = await import('module');
 Module._initPaths?.();
 // GSD_VERSION — expose package version so extensions can display it
 process.env.GSD_VERSION = gsdVersion;
-// GSD_BIN_PATH — absolute path to this loader (dist/loader.js), used by patched subagent
-// to spawn gsd instead of pi when dispatching workflow tasks
-process.env.GSD_BIN_PATH = process.argv[1];
+// GSD_BIN_PATH — absolute path to the CLI entrypoint, used by patched
+// subagent/parallel workers to spawn gsd instead of pi when dispatching
+// workflow tasks. In source-dev mode this must remain scripts/dev-cli.js, not
+// src/loader.ts, because child processes need the --import resolve-ts wrapper.
+const invokedBinPath = process.argv[1];
+const sourceLoaderPath = join(gsdRoot, 'src', 'loader.ts');
+const devCliPath = process.env.GSD_DEV_CLI_PATH?.trim() || join(gsdRoot, 'scripts', 'dev-cli.js');
+const explicitCliPath = process.env.GSD_CLI_PATH?.trim() || process.env.GSD_BIN_PATH?.trim();
+const isSourceLoader = invokedBinPath && resolve(invokedBinPath) === sourceLoaderPath;
+const rawGsdBinPath = explicitCliPath || (isSourceLoader && existsSync(devCliPath) ? devCliPath : invokedBinPath);
+const resolvedGsdBinPath = rawGsdBinPath ? resolve(rawGsdBinPath) : undefined;
+process.env.GSD_BIN_PATH = resolvedGsdBinPath;
+if (!process.env.GSD_CLI_PATH) {
+    process.env.GSD_CLI_PATH = resolvedGsdBinPath;
+}
 // GSD_WORKFLOW_PATH — absolute path to bundled GSD-WORKFLOW.md, used by patched gsd extension
 // when dispatching workflow prompts. Prefers dist/resources/ (stable, set at build time)
 // over src/resources/ (live working tree) — see resource-loader.ts for rationale.

package/dist/resource-loader.js

@@ -711,29 +711,38 @@ function migrateSkillsToEcosystemDir(agentDir) {
 export function hasStaleCompiledExtensionSiblings(extensionsDir, sourceDir = bundledExtensionsDir) {
     if (!existsSync(extensionsDir))
         return false;
-    const sourceFiles = existsSync(sourceDir)
-        ? new Set(readdirSync(sourceDir, { withFileTypes: true })
-            .filter((entry) => entry.isFile())
-            .map((entry) => entry.name))
-        : new Set();
-    for (const entry of readdirSync(extensionsDir, { withFileTypes: true })) {
-        if (!entry.isFile())
-            continue;
-        if (!entry.name.endsWith('.ts') && !entry.name.endsWith('.js'))
-            continue;
-        const siblingName = entry.name.endsWith('.ts')
-            ? entry.name.replace(/\.ts$/, '.js')
-            : entry.name.replace(/\.js$/, '.ts');
-        if (!existsSync(join(extensionsDir, siblingName)))
+    const sourceFiles = collectRelativeFiles(sourceDir);
+    const installedFiles = collectRelativeFiles(extensionsDir);
+    for (const relPath of installedFiles) {
+        if (!relPath.endsWith('.ts') && !relPath.endsWith('.js'))
             continue;
-        if (sourceFiles.has(entry.name) && sourceFiles.has(siblingName))
+        if (sourceFiles.has(relPath))
             continue;
-        if (sourceFiles.has(entry.name) || sourceFiles.has(siblingName)) {
+        const bundledSibling = relPath.endsWith('.ts')
+            ? relPath.replace(/\.ts$/, '.js')
+            : relPath.replace(/\.js$/, '.ts');
+        if (sourceFiles.has(bundledSibling))
             return true;
-        }
     }
     return false;
 }
+function collectRelativeFiles(rootDir) {
+    const files = new Set();
+    if (!existsSync(rootDir))
+        return files;
+    const visit = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const entryPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                visit(entryPath);
+                continue;
+            }
+            files.add(relative(rootDir, entryPath).replaceAll('\\', '/'));
+        }
+    };
+    visit(rootDir);
+    return files;
+}
 /**
  * Constructs a DefaultResourceLoader that loads extensions from both
  * ~/.gsd/agent/extensions/ (GSD's default) and ~/.pi/agent/extensions/ (pi's default).

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

@@ -1 +1 @@
-38cf2a787658e575
+858bd1ba482d00d8

package/dist/resources/GSD-WORKFLOW.md

@@ -542,74 +542,61 @@ If files disagree, **pause and surface to the user**:
 
 ---
 
-## Git Strategy: Branch-Per-Slice with Squash Merge
+## Git Strategy: Sequential Commits with Optional Milestone Isolation
 
-**Principle:** Main is always clean and working. Each slice gets an isolated branch. The user never runs a git command — the agent handles everything.
+**Principle:** GSD keeps work atomic and recoverable. By default, work happens on the current branch. If `git.isolation` is set to `worktree` or `branch`, a milestone branch is used and merged back to the recorded integration branch when the milestone completes. The user never runs a git command — the agent handles everything.
 
-### Branch Lifecycle
+### Isolation Modes
 
-1. **Slice starts** → create branch `gsd/M001/S01` from main
-2. **Per-task commits** on the branch — atomic, descriptive, bisectable
-3. **Slice completes** → squash merge to main as one clean commit
-4. **Branch deleted** — squash commit on main is the permanent record
+| Mode | Where work happens | Branch behavior |
+|------|--------------------|-----------------|
+| `none` (default) | Project root | Current branch, no isolation branch |
+| `worktree` | `.gsd/worktrees/<MID>/` | `milestone/<MID>` branch in a git worktree |
+| `branch` | Project root | `milestone/<MID>` branch checked out in place |
 
-### What Main Looks Like
+In all modes, slices and tasks commit sequentially on the active branch; there are no per-slice branches. The integration branch is captured when the milestone starts, so stale `git.main_branch` preferences do not redirect merge-back.
 
-```
-feat(M001/S03): milestone and slice discuss commands
-feat(M001/S02): extension scaffold and command routing
-feat(M001/S01): file I/O foundation
-```
+### Milestone Lifecycle
 
-One commit per slice. Individually revertable. Reads like a changelog.
+1. **Milestone starts** → capture the current integration branch.
+2. **Optional isolation** → create `milestone/M001` only when `git.isolation` is `worktree` or `branch`.
+3. **Per-task commits** — atomic, descriptive, bisectable.
+4. **Slice completes** → write slice summary, UAT script, roadmap checkbox, and milestone summary.
+5. **Milestone completes** → if isolated, squash-merge the milestone branch back to the captured integration branch and clean up the worktree/branch.
 
-### What the Branch Looks Like
+### What History Looks Like
 
 ```
-gsd/M001/S01:
-  test(S01/T03): round-trip tests passing
-  feat(S01/T03): file writer with round-trip fidelity
-  feat(S01/T02): markdown parser for plan files
-  feat(S01/T01): core types and interfaces
-  docs(S01): add slice plan
+feat: core type definitions
+feat: markdown parser for plan files
+fix: handle empty state rebuild
 ```
 
+In `none` mode these commits land directly on the current branch. In isolated modes they land on `milestone/<MID>` and are squashed back at milestone completion.
+
 ### Commit Conventions
 
 | When | Format | Example |
 |------|--------|---------|
-| Task completed | `{type}(S01/T02): <one-liner from summary>` | Type inferred from title (`feat`, `fix`, `test`, etc.) |
-| Plan/docs committed | `docs(S01): add slice plan` | Planning artifacts |
-| Slice squash to main | `type(M001/S01): <slice title>` | Type inferred from title |
-| State rebuild | `chore(S01/T02): auto-commit after state-rebuild` | Bookkeeping only |
+| Task completed | `{type}: <one-liner from summary>` | Type inferred from title (`feat`, `fix`, `test`, etc.) |
+| State rebuild | `chore: auto-commit after state-rebuild` | Bookkeeping only |
+| Milestone squash | `{type}: <milestone title>` | Type inferred from title |
 
 The system reads the task summary after execution and builds a meaningful commit message:
-- **Subject**: `{type}({sliceId}/{taskId}): {one-liner}` — the one-liner from the summary frontmatter
+- **Subject**: `{type}: {one-liner}` — the one-liner from the summary frontmatter, sanitized to one line
 - **Type**: Inferred from the task title and one-liner (`feat`, `fix`, `test`, `refactor`, `docs`, `perf`, `chore`)
 - **Body**: Key files from the summary frontmatter (up to 8 files listed)
+- **Trailers**: `GSD-Task: S##/T##`; if GitHub sync linked an issue, `Resolves #N`
 
 Commit types: `feat`, `fix`, `test`, `refactor`, `docs`, `perf`, `chore`
 
-### Squash Merge Message
-
-```
-feat(M001/S01): file I/O foundation
-
-Agent can parse, format, load, and save all GSD file types with round-trip fidelity.
-
-Tasks completed:
-- T01: core types and interfaces
-- T02: markdown parser for plan files
-- T03: file writer with round-trip fidelity
-```
-
 ### Rollback
 
 | Problem | Fix |
 |---------|-----|
-| Bad task | `git reset --hard HEAD~1` to previous commit on the branch |
-| Bad slice | `git revert <squash commit>` on main |
-| UAT failure after merge | Fix tasks on `gsd/M001/S01-fix` branch, squash as `fix(M001/S01): <fix>` |
+| Bad task | Revert the task commit on the active branch |
+| Bad milestone squash | Revert the squash commit on the integration branch |
+| UAT failure after merge | Create follow-up fix tasks in the current or next milestone |
 
 ---
 

package/dist/resources/extensions/async-jobs/job-manager.js

@@ -159,6 +159,10 @@ export class AsyncJobManager {
             this.evictionTimers.delete(id);
             this.jobs.delete(id);
         }, this.evictionMs);
+        // Eviction is housekeeping; it should not keep short-lived test/CLI
+        // processes alive after the real work has finished.
+        if (typeof timer === "object" && "unref" in timer)
+            timer.unref();
         this.evictionTimers.set(id, timer);
     }
     evictOldest() {

package/dist/resources/extensions/bg-shell/bg-shell-lifecycle.js

@@ -6,6 +6,7 @@ import { truncateToWidth, visibleWidth, } from "@gsd/pi-tui";
 import { processes, pendingAlerts, pushAlert, cleanupAll, cleanupSessionProcesses, persistManifest, loadManifest, pruneDeadProcesses, } from "./process-manager.js";
 import { formatUptime, getBgShellLiveCwd, resolveBgShellPersistenceCwd } from "./utilities.js";
 import { formatTokenCount } from "../shared/format-utils.js";
+import { homedir } from "node:os";
 export function registerBgShellLifecycle(pi, state) {
     function syncLatestCtxCwd() {
         if (!state.latestCtx)
@@ -177,8 +178,8 @@ export function registerBgShellLifecycle(pi, state) {
                 render(width) {
                     // ── Line 1: pwd (branch) [session]  ...  bg status ──
                     let pwd = getBgShellLiveCwd(state.latestCtx?.cwd);
-                    const home = process.env.HOME || process.env.USERPROFILE;
-                    if (home && pwd.startsWith(home)) {
+                    const home = homedir();
+                    if (pwd.startsWith(home)) {
                         pwd = `~${pwd.slice(home.length)}`;
                     }
                     const branch = footerData.getGitBranch();

package/dist/resources/extensions/bg-shell/utilities.js

@@ -32,6 +32,7 @@ export function restoreWindowsVTInput() {
 }
 // ── Time Formatting ────────────────────────────────────────────────────────
 import { formatDuration } from "../shared/mod.js";
+import { homedir } from "node:os";
 export const formatUptime = formatDuration;
 export function formatTimeAgo(timestamp) {
     return formatDuration(Date.now() - timestamp) + " ago";
@@ -48,7 +49,7 @@ export function getBgShellLiveCwd(cachedCwd, pathExists = existsSync, getCwd = (
     }
     catch {
         const projectRoot = deriveProjectRootFromAutoWorktree(cachedCwd);
-        const home = process.env.HOME || process.env.USERPROFILE;
+        const home = homedir();
         const fallbacks = [projectRoot, cachedCwd, home, "/"].filter((candidate) => Boolean(candidate));
         for (const candidate of fallbacks) {
             if (candidate !== "/" && !pathExists(candidate))

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

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

package/dist/resources/extensions/claude-code-cli/stream-adapter.js

@@ -860,6 +860,21 @@ export function createClaudeCodeCanUseToolHandler(ui) {
                             }];
                     }
                 }
+                else if (!perms || (Array.isArray(perms) && perms.length === 0)) {
+                    // Non-Bash tool with no SDK-supplied suggestions. Without a
+                    // fallback rule the SDK would return `behavior: "allow"`
+                    // with no `updatedPermissions`, so "Always Allow" silently
+                    // fails to persist for tools whose input varies per call
+                    // (e.g. AskUserQuestion with different `questions` payloads).
+                    // A bare `{ toolName }` rule matches any input.
+                    perms = [{
+                            type: "addRules",
+                            rules: [{ toolName }],
+                            behavior: "allow",
+                            destination: "localSettings",
+                        }];
+                    notifyLabel = toolName;
+                }
                 // Notify with the resolved pattern (label already previewed it)
                 if (notifyLabel) {
                     ui.notify(`Saved: ${notifyLabel}`, "info");
@@ -1019,13 +1034,13 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
     const { reasoning, ...sdkExtraOptions } = extraOptions;
     const mcpServers = buildWorkflowMcpServers();
     const permissionMode = overrides?.permissionMode ?? "bypassPermissions";
-    // Globally unblock all tools. Users reported that the `acceptEdits` default
-    // plus a narrow allowlist silently declined most Bash/Agent/WebFetch calls
-    // when `extensionUIContext` wasn't threaded through. Default to
-    // bypassPermissions and an empty disallow list so every tool — including
-    // `AskUserQuestion` and every `mcp__*` workflow tool — is auto-approved.
+    // Globally unblock the tools GSD expects Claude Code to run. When the
+    // workflow MCP server is available, prefer its `ask_user_questions` tool over
+    // Claude Code's native `AskUserQuestion`; the MCP path carries stable IDs and
+    // routes responses through the GSD elicitation bridge.
     // Opt back into gated mode with GSD_CLAUDE_CODE_PERMISSION_MODE=acceptEdits.
-    const disallowedTools = [];
+    const workflowMcpTools = mcpServers ? Object.keys(mcpServers).map((serverName) => `mcp__${serverName}__*`) : [];
+    const disallowedTools = workflowMcpTools.length > 0 ? ["AskUserQuestion"] : [];
     const allowedTools = [
         "Read",
         "Write",
@@ -1036,8 +1051,7 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
         "Agent",
         "WebFetch",
         "WebSearch",
-        "AskUserQuestion",
-        ...(mcpServers ? Object.keys(mcpServers).map((serverName) => `mcp__${serverName}__*`) : []),
+        ...(workflowMcpTools.length > 0 ? workflowMcpTools : ["AskUserQuestion"]),
     ];
     const supportsAdaptive = modelSupportsAdaptiveThinking(modelId);
     const effort = reasoning && supportsAdaptive

package/dist/resources/extensions/github-sync/cli.js

@@ -5,6 +5,7 @@
  * Uses `execFileSync` (not `execSync`) for safety.
  */
 import { execFileSync } from "node:child_process";
+import { GIT_NO_PROMPT_ENV } from "../gsd/git-constants.js";
 function ok(data) {
     return { ok: true, data };
 }
@@ -261,6 +262,7 @@ export function ghPushBranch(cwd, branch, setUpstream = true) {
             encoding: "utf-8",
             stdio: ["ignore", "pipe", "pipe"],
             timeout: 30_000,
+            env: GIT_NO_PROMPT_ENV,
         });
         return ok(undefined);
     }
@@ -275,6 +277,7 @@ export function ghCreateBranch(cwd, branch, from) {
             encoding: "utf-8",
             stdio: ["ignore", "pipe", "pipe"],
             timeout: 10_000,
+            env: GIT_NO_PROMPT_ENV,
         });
         return ok(undefined);
     }