@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

package/dist/resources/extensions/gsd/recovery-classification.js

@@ -3,6 +3,7 @@
 import { isToolUnavailableError } from "./auto-tool-tracking.js";
 import { classifyError, isTransient } from "./error-classifier.js";
 import { recoveryRemediation } from "./guidance.js";
+import { isTerminalToolSurfaceError } from "./tool-surface-readiness.js";
 import { ReconciliationFailedError } from "./state-reconciliation.js";
 import { IllegalPhaseTransitionError } from "./state-transition-matrix.js";
 export function classifyFailure(input) {
@@ -51,6 +52,13 @@ const FAILURE_TAXONOMY = {
     "runtime-unknown": { action: "escalate", label: null },
 };
 function inferFailureKind(message) {
+    // A terminal tool-surface failure (workflow MCP server in failed/needs-auth/
+    // disabled) will not self-heal, so it must escalate rather than retry the
+    // same model into the per-unit cost cap. Checked before the generic
+    // tool-unavailable branch, which matches the same readiness prefix and
+    // would otherwise route it to retry. See #783.
+    if (isTerminalToolSurfaceError(message))
+        return "runtime-unknown";
     if (isToolUnavailableError(message))
         return "tool-unavailable";
     if (/tool contract|auto-unit tool scope|phase-boundary gate|not permitted.*own/i.test(message))

package/dist/resources/extensions/gsd/redact-secrets.js

@@ -0,0 +1,37 @@
+// redact-secrets.ts
+// Best-effort redaction of secret-shaped substrings before persisting free text
+// (exec-sandbox output, activity-log session entries) to disk under .gsd/, which
+// the secret scanner skips. Patterns mirror scripts/secret-scan.mjs.
+const PLACEHOLDER = "«redacted»";
+// Each secret shape. Global flag so replace() catches every occurrence in a line.
+// Order is not significant — matches are replaced independently.
+const PATTERNS = [
+    /AKIA[0-9A-Z]{16}/g, // AWS access key id
+    /(api[_-]?key|apikey|api[_-]?secret)[ \t]*[:=][ \t]*['"][0-9a-zA-Z_./-]{20,}['"]/gi,
+    /(secret|token|password|passwd|pwd|credential)[ \t]*[:=][ \t]*['"][^\s'"]{8,}['"]/gi,
+    /(authorization|bearer)[ \t]*[:=][ \t]*['"][^\s'"]{8,}['"]/gi,
+    /Bearer[ \t]+[0-9a-zA-Z._-]{8,}/g, // Authorization: Bearer <token> (unquoted)
+    /-----BEGIN\s+(RSA|DSA|EC|OPENSSH|PGP)\s+PRIVATE\s+KEY-----[\s\S]*?-----END\s+(RSA|DSA|EC|OPENSSH|PGP)\s+PRIVATE\s+KEY-----/g,
+    /(mysql|postgres|postgresql|mongodb|redis|amqp|mssql):\/\/[^\s'"]{8,}/gi,
+    /gh[pousr]_[0-9a-zA-Z]{36,}/g, // GitHub token
+    /glpat-[0-9a-zA-Z-]{20,}/g, // GitLab token
+    /xox[baprs]-[0-9a-zA-Z-]{10,}/g, // Slack token
+    /hooks\.slack\.com\/services\/T[0-9A-Z]{8,}\/B[0-9A-Z]{8,}\/[0-9a-zA-Z]{20,}/g,
+    /AIza[0-9A-Za-z_-]{35}/g, // Google API key
+    /[sr]k_(live|test)_[0-9a-zA-Z]{20,}/g, // Stripe key
+    /sk-(ant-)?[0-9a-zA-Z_-]{20,}/g, // OpenAI / Anthropic style key
+    /npm_[0-9a-zA-Z]{36,}/g, // npm token
+    /(secret|key|token|password)[ \t]*[:=][ \t]*['"]?[0-9a-f]{32,}['"]?/gi, // hex secret
+];
+/**
+ * Replace secret-shaped substrings in `text` with a placeholder, preserving the
+ * surrounding content. Pure and safe to call per log line. The placeholder
+ * contains no quote/brace/backslash, so redacting a JSON string keeps it valid.
+ */
+export function redactSecrets(text) {
+    let out = text;
+    for (const pattern of PATTERNS) {
+        out = out.replace(pattern, PLACEHOLDER);
+    }
+    return out;
+}

package/dist/resources/extensions/gsd/repo-identity.js

@@ -328,6 +328,22 @@ export function externalProjectsRoot() {
     const base = process.env.GSD_STATE_DIR || gsdHome();
     return join(base, "projects");
 }
+/**
+ * Check whether this project already has authoritative external state.
+ *
+ * Used by legacy `.gsd/` migration to avoid re-copying a re-materialized local
+ * directory over newer state when an already-migrated symlink was replaced.
+ */
+export function externalStateAlreadyExistsForProject(basePath) {
+    const base = process.env.GSD_STATE_DIR || gsdHome();
+    const computedPath = join(base, "projects", repoIdentity(basePath));
+    if (hasProjectState(computedPath))
+        return true;
+    const markerId = readGsdIdMarker(resolveGitRoot(basePath));
+    if (!markerId)
+        return false;
+    return hasProjectState(join(base, "projects", markerId));
+}
 // ─── Numbered Variant Cleanup ────────────────────────────────────────────────
 /**
  * macOS collision pattern: `.gsd 2`, `.gsd 3`, `.gsd 4`, etc.

package/dist/resources/extensions/gsd/repository-registry.js

@@ -5,6 +5,11 @@ import { isAbsolute, relative, resolve } from "node:path";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { resolveGsdPathContract } from "./paths.js";
 export function defaultRepositoryTargets(registry) {
+    // In parent mode, default to the declared child repositories so work is
+    // attributed to the repo it touches — not silently to the root "project".
+    if (registry.mode === "parent") {
+        return registry.repositories.filter((repo) => repo.id !== "project").map((repo) => repo.id);
+    }
     const project = registry.byId.get("project");
     if (project)
         return [project.id];
@@ -51,7 +56,7 @@ function resolveGitWorkingTreeRoot(basePath) {
 export function createRepositoryRegistry(basePath, workspacePrefs) {
     const contract = resolveGsdPathContract(basePath);
     const projectRoot = contract.isWorktree
-        ? resolveGitWorkingTreeRoot(contract.workRoot) ?? contract.projectRoot
+        ? resolveGitWorkingTreeRoot(contract.workRoot) ?? contract.workRoot
         : contract.projectRoot;
     const mode = workspacePrefs?.mode ?? "project";
     const repoMap = new Map();

package/dist/resources/extensions/gsd/roadmap-slices.js

@@ -202,7 +202,7 @@ export function parseRoadmapSlices(content) {
     const checkboxItems = slicesSection.split("\n");
     let currentSlice = null;
     for (const line of checkboxItems) {
-        const cbMatch = line.match(/^\s*-\s+\[([ xX])\]\s+\*\*([\w.]+):\s+(.+?)\*\*\s*(.*)/);
+        const cbMatch = line.match(/^\s*-\s+\[([ xX])\]\s+\*\*([\w.-]+):\s+(.+?)\*\*\s*(.*)/);
         if (cbMatch) {
             if (currentSlice)
                 slices.push(currentSlice);

package/dist/resources/extensions/gsd/root-write-leak-guard.js

@@ -4,9 +4,15 @@ import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { GSD_RUNTIME_PATTERNS } from "./gitignore.js";
 const MAX_SYNC_FINGERPRINT_BYTES = 1_500_000_000;
+const ROOT_RUNTIME_PATH_PREFIXES = Array.from(new Set(GSD_RUNTIME_PATTERNS.map((pattern) => {
+    const path = pattern.replace(/\/+$/, "");
+    const slash = path.indexOf("/");
+    return slash === -1 ? path : path.slice(0, slash);
+})));
 function isRootRuntimePath(path) {
-    return path === ".gsd" || path.startsWith(".gsd/");
+    return ROOT_RUNTIME_PATH_PREFIXES.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
 }
 function fileFingerprint(rootPath, relPath) {
     const absPath = join(rootPath, relPath);
@@ -36,12 +42,14 @@ export function captureRootDirtySnapshot(rootPath) {
         if (!line.trim())
             continue;
         const code = line.slice(0, 2);
+        if (code !== "??")
+            continue;
         const path = line.slice(3).replace(/^"|"$/g, "");
         if (!path || isRootRuntimePath(path))
             continue;
         snapshot.set(path, {
             path,
-            status: code.trim() || code,
+            status: code,
             fingerprint: fileFingerprint(rootPath, path),
         });
     }
@@ -52,7 +60,7 @@ export function detectRootWriteLeak(input) {
     const leaked = [];
     for (const entry of after.values()) {
         const prior = input.before?.get(entry.path);
-        if (!prior || prior.status !== entry.status || prior.fingerprint !== entry.fingerprint) {
+        if (!prior || prior.fingerprint !== entry.fingerprint) {
             leaked.push(entry);
         }
     }

package/dist/resources/extensions/gsd/safe-fs.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, cpSync } from "node:fs";
+import { existsSync, mkdirSync, cpSync, statSync } from "node:fs";
 import { dirname } from "node:path";
 import { logWarning } from "./workflow-logger.js";
 /**
@@ -40,7 +40,28 @@ export function safeCopyRecursive(src, dst, opts) {
         return false;
     try {
         mkdirSync(dirname(dst), { recursive: true });
-        cpSync(src, dst, { ...opts, recursive: true });
+        const userFilter = opts?.filter;
+        cpSync(src, dst, {
+            ...opts,
+            recursive: true,
+            filter: (srcPath, dstPath) => {
+                if (existsSync(dstPath)) {
+                    try {
+                        const srcStat = statSync(srcPath);
+                        const dstStat = statSync(dstPath);
+                        if (srcStat.isDirectory() !== dstStat.isDirectory()) {
+                            logWarning("fs", `recursive copy skipped type collision: ${srcPath} → ${dstPath}`);
+                            return false;
+                        }
+                    }
+                    catch (err) {
+                        logWarning("fs", `recursive copy skipped unreadable path: ${srcPath} → ${dstPath}: ${err.message}`);
+                        return false;
+                    }
+                }
+                return userFilter ? userFilter(srcPath, dstPath) : true;
+            },
+        });
         return true;
     }
     catch (err) {

package/dist/resources/extensions/gsd/safety/content-validator.js

@@ -29,7 +29,8 @@ export function validateContent(unitType, artifactPath) {
         return [];
     }
 }
-const TASK_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*T\d+:|#{2,4}\s+T\d+\b)/gm;
+// Matches both legacy "**T01: title**" and flat-phase "**T01**: title" checkbox formats.
+const TASK_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*T\d+(?:\*\*)?:|#{2,4}\s+T\d+\b)/gm;
 const SLICE_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*S\d+:|#{2,4}\s+S\d+\b)/gm;
 const VALIDATORS = {
     "plan-slice": validatePlanSlice,

package/dist/resources/extensions/gsd/safety/destructive-guard.js

@@ -20,14 +20,21 @@ const DESTRUCTIVE_PATTERNS = [
     { pattern: /\baws\s+\w+\s+(delete|create|put|remove|terminate)\b/i, label: "AWS mutation" },
     { pattern: /\bkubectl\s+(delete|apply)\b/i, label: "kubectl mutation" },
 ];
+function stripQuotedAndComments(command) {
+    return command
+        .replace(/"(?:[^"\\]|\\.)*"/g, '""')
+        .replace(/'(?:[^'\\]|\\.)*'/g, "''")
+        .replace(/(^|\s)#.*$/g, "$1");
+}
 /**
  * Classify a bash command for destructive operations.
  * Returns the list of matched destructive pattern labels.
  */
 export function classifyCommand(command) {
+    const commandToClassify = stripQuotedAndComments(command);
     const labels = [];
     for (const { pattern, label } of DESTRUCTIVE_PATTERNS) {
-        if (pattern.test(command)) {
+        if (pattern.test(commandToClassify)) {
             // Deduplicate labels (e.g., two force-push patterns)
             if (!labels.includes(label))
                 labels.push(label);

package/dist/resources/extensions/gsd/safety/evidence-collector.js

@@ -27,10 +27,14 @@ const EXECUTION_TOOL_NAMES = new Set([
 const MCP_EXECUTION_TOOL_RE = /^mcp__.+__gsd_(?:uat_)?exec(?:_search)?$/;
 // ─── Module State ───────────────────────────────────────────────────────────
 let unitEvidence = [];
+let lastWritePath = null;
+let lastWriteSig = null;
 // ─── Public API ─────────────────────────────────────────────────────────────
 /** Reset all evidence for a new unit. Call at unit start. */
 export function resetEvidence() {
     unitEvidence = [];
+    lastWritePath = null;
+    lastWriteSig = null;
 }
 /** Get a read-only view of all evidence collected for the current unit. */
 export function getEvidence() {
@@ -95,10 +99,15 @@ function isEvidenceArray(data) {
 export function saveEvidenceToDisk(basePath, milestoneId, sliceId, taskId) {
     try {
         const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+        const body = JSON.stringify(unitEvidence, null, 2) + "\n";
+        if (path === lastWritePath && body === lastWriteSig)
+            return;
         mkdirSync(dirname(path), { recursive: true });
         const tmp = `${path}.tmp.${randomBytes(4).toString("hex")}`;
-        writeFileSync(tmp, JSON.stringify(unitEvidence, null, 2) + "\n", "utf-8");
+        writeFileSync(tmp, body, "utf-8");
         renameSync(tmp, path);
+        lastWritePath = path;
+        lastWriteSig = body;
     }
     catch {
         // Non-fatal — don't let persistence failures break unit execution
@@ -112,6 +121,8 @@ export function saveEvidenceToDisk(basePath, milestoneId, sliceId, taskId) {
  */
 export function loadEvidenceFromDisk(basePath, milestoneId, sliceId, taskId) {
     try {
+        lastWritePath = null;
+        lastWriteSig = null;
         const path = evidencePath(basePath, milestoneId, sliceId, taskId);
         if (!existsSync(path))
             return;
@@ -136,6 +147,10 @@ export function clearEvidenceFromDisk(basePath, milestoneId, sliceId, taskId) {
         if (existsSync(path)) {
             unlinkSync(path);
         }
+        if (path === lastWritePath) {
+            lastWritePath = null;
+            lastWriteSig = null;
+        }
     }
     catch {
         // Non-fatal

package/dist/resources/extensions/gsd/safety/evidence-cross-ref.js

@@ -38,8 +38,26 @@ export function crossReferenceEvidence(claimedEvidence, actualEvidence) {
             });
             continue;
         }
+        // A shell-spawn/infra failure means the command never ran (e.g. on Windows
+        // `gsd_exec runtime=bash` resolves to a WSL with no /bin/bash). The LLM
+        // typically recovers by re-running via another runtime, and that genuine
+        // run may not even be in the match set. Such a failure is inconclusive, not
+        // a falsified pass — exclude it before judging the exit code.
+        const commandRuns = matches.filter((m) => !isInfraSpawnFailure(m));
+        if (commandRuns.length === 0) {
+            if (claimed.exitCode === 0) {
+                mismatches.push({
+                    severity: "warning",
+                    claimed,
+                    actual: latestMatch(matches),
+                    reason: `Matched execution failed to spawn (infrastructure error, not a command failure); ` +
+                        `treating as inconclusive`,
+                });
+            }
+            continue;
+        }
         // Exit code mismatch: LLM claims success but actual command failed
-        const match = latestMatch(matches);
+        const match = latestMatch(commandRuns);
         if (claimed.exitCode === 0 && match.exitCode !== 0) {
             mismatches.push({
                 severity: "error",
@@ -51,6 +69,30 @@ export function crossReferenceEvidence(claimedEvidence, actualEvidence) {
     }
     return mismatches;
 }
+/**
+ * Runtime-spawn / shell-infra failure signatures. When a bash-runtime call
+ * fails to *spawn* (rather than the command running and exiting non-zero), the
+ * recorded exitCode is an ordinary non-zero but the output carries one of these
+ * markers. Such a call is not evidence that a verification failed.
+ */
+const INFRA_SPAWN_FAILURE_SIGNATURES = [
+    /execvpe\([^)]*\)\s+failed/i, // WSL: execvpe(/bin/bash) failed: No such file or directory
+    /WSL \(.*\) ERROR/i, // WSL relay error banner
+    /command not found:\s*(?:bash|sh|zsh|dash|fish|ash|ksh|wsl)\b/i, // missing shell interpreter only
+];
+/**
+ * True when a non-zero bash call looks like a shell-spawn/infra failure (the
+ * command never started) rather than a real command failure. A successful run
+ * (exitCode 0) is never an infra failure.
+ */
+function isInfraSpawnFailure(call) {
+    if (call.exitCode === 0)
+        return false;
+    const snippet = call.outputSnippet ?? "";
+    if (snippet.length === 0)
+        return false;
+    return INFRA_SPAWN_FAILURE_SIGNATURES.some((re) => re.test(snippet));
+}
 // ─── Internals ──────────────────────────────────────────────────────────────
 /**
  * Verification evidence rows are append-only across retries, but a task

package/dist/resources/extensions/gsd/safety/file-change-validator.js

@@ -44,8 +44,11 @@ export function validateFileChanges(basePath, expectedOutput, plannedFiles, file
     const actualFiles = getChangedFilesFromLastCommit(basePath);
     if (!actualFiles)
         return null;
-    // Filter out .gsd/ internal files — only validate project source files
-    const projectFiles = actualFiles.filter(f => !f.startsWith(".gsd/") && !f.startsWith(".gsd\\"));
+    // Filter out GSD-internal paths — only validate project source files.
+    const projectFiles = actualFiles.filter((f) => !f.startsWith(".gsd/") &&
+        !f.startsWith(".gsd\\") &&
+        !f.startsWith(".gsd-backups/") &&
+        !f.startsWith(".gsd-backups\\"));
     // Normalize expected paths (strip leading ./ or /)
     const normalizedExpected = new Set([...allExpected].map((f) => normalizePlannedFileReference(f).replace(/^\.\//, "").replace(/^\//, "")));
     // Build allowlist matchers once (dot: true so patterns like `**/.hidden` work).

package/dist/resources/extensions/gsd/service-tier.js

@@ -9,7 +9,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { saveFile } from "./files.js";
-import { getGlobalGSDPreferencesPath, loadEffectiveGSDPreferences, loadGlobalGSDPreferences, } from "./preferences.js";
+import { clearGSDPreferencesCache, getGlobalGSDPreferencesPath, loadEffectiveGSDPreferences, loadGlobalGSDPreferences, } from "./preferences.js";
 import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
 const SERVICE_TIER_SCOPE_NOTE = "Only affects gpt-5.4 models, regardless of provider.";
 // ─── Gating ──────────────────────────────────────────────────────────────────
@@ -125,6 +125,7 @@ async function writeGlobalServiceTier(ctx, tier) {
             body = preserved;
     }
     await saveFile(path, `---\n${frontmatter}---${body}`);
+    clearGSDPreferencesCache();
     await ctx.waitForIdle();
     await ctx.reload();
 }

package/dist/resources/extensions/gsd/session-forensics.js

@@ -176,11 +176,21 @@ export function extractTrace(entries) {
     }
     // Flush any pending tool calls that never got results (crash mid-tool)
     for (const [, pending] of pendingTools) {
+        const missingResultError = `Tool call ${pending.name} started but no toolResult was recorded`;
         toolCalls.push({
             name: pending.name,
             input: redactInput(pending.name, pending.input),
-            isError: false,
+            result: "missing tool result (stream/tool-call abort before execution)",
+            isError: true,
         });
+        errors.push(missingResultError);
+        // Mark the matching commandsRun entry as failed so it is consistent with
+        // the isError: true on the tool call above (bash/bg_shell only).
+        if (pending.name === "bash" || pending.name === "bg_shell") {
+            const lastCmd = findLast(commandsRun, c => c.command === String(pending.input.command));
+            if (lastCmd)
+                lastCmd.failed = true;
+        }
     }
     return {
         toolCalls,

package/dist/resources/extensions/gsd/session-lock.js

@@ -604,6 +604,12 @@ function isLockFileOwnedByCurrentProcess(lp) {
     const existing = readExistingLockData(lp);
     return existing?.pid === process.pid;
 }
+const _retrySleepView = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) {
+    if (!(ms > 0))
+        return;
+    Atomics.wait(_retrySleepView, 0, 0, ms);
+}
 export function readExistingLockDataWithRetry(lp, options) {
     const maxAttempts = options?.maxAttempts ?? 3;
     const delayMs = options?.delayMs ?? 200;
@@ -612,12 +618,7 @@ export function readExistingLockDataWithRetry(lp, options) {
         if (data !== null)
             return data;
         if (attempt < maxAttempts) {
-            // Synchronous busy-wait — onCompromised runs in a sync callback context
-            // and the delays are short (200ms default).
-            const start = Date.now();
-            while (Date.now() - start < delayMs) {
-                // busy-wait
-            }
+            sleepSync(delayMs);
         }
     }
     return null;

package/dist/resources/extensions/gsd/skills/gsd-headless/SKILL.md

@@ -211,17 +211,15 @@ All state lives in `.gsd/` as markdown files (version-controllable):
 
 ```
 .gsd/
-  milestones/M001/
-    M001-CONTEXT.md      # Requirements, scope, decisions
-    M001-ROADMAP.md      # Slices with tasks, dependencies, checkboxes
-    M001-SUMMARY.md      # Completion summary
-    slices/S01/
-      S01-PLAN.md        # Task list
-      S01-SUMMARY.md     # Slice summary with frontmatter
-      tasks/T01-PLAN.md  # Individual task spec
+  phases/01-foundation/
+    01-CONTEXT.md        # Requirements, scope, decisions
+    01-ROADMAP.md        # Slices with tasks, dependencies, checkboxes
+    01-SUMMARY.md        # Completion summary
+    01-01-PLAN.md        # First slice task list
+    01-01-SUMMARY.md     # First slice summary with frontmatter
 ```
 
-State is derived from files on disk — checkboxes in ROADMAP.md are the source of truth for completion.
+Runtime state is stored in the project-root database; markdown files are reviewable projections written under `.gsd/phases/`. Legacy projects may still resolve to `.gsd/milestones/<MID>/` until migrated.
 
 ## All Headless Commands
 
@@ -240,3 +238,6 @@ Quick reference — see [references/commands.md](references/commands.md) for the
 | `skip` / `undo` | Unit control |
 | `doctor` | Health check + auto-fix |
 | `steer <desc>` | Hard-steer plan mid-execution |
+| `explore` / `spike` / `sketch` | Prompt-driven ideation and experiment workflows |
+| `map-codebase` / `docs-update` / `graphify` | Codebase documentation and knowledge workflows |
+| `code-review` / `review` / `audit-*` / `verify-work` | Review, audit, and UAT workflows |

package/dist/resources/extensions/gsd/skills/gsd-headless/references/commands.md

@@ -22,6 +22,7 @@ All commands can be run via `gsd headless [command]`.
 | `status` | Progress dashboard (TUI overlay — useful interactively, not for parsing) |
 | `visualize` | Workflow visualizer (deps, metrics, timeline) |
 | `history` | Execution history (supports --cost, --phase, --model, limit) |
+| `codebase` | Manage `.gsd/CODEBASE.md`; parent workspaces include declared child repositories under repo-labeled sections |
 
 ## Unit Control
 
@@ -50,6 +51,57 @@ All commands can be run via `gsd headless [command]`.
 | `inspect` | Show SQLite DB diagnostics (schema, row counts) |
 | `forensics` | Post-mortem investigation of auto-mode failures |
 
+## Additional Prompt-Driven Workflows
+
+These commands dispatch native GSD prompts adapted to the milestone, slice, and `.gsd/` model. Use them as `gsd headless <command> [args...]`.
+
+| Command | Description |
+|---------|-------------|
+| `explore` | Socratic ideation before committing an idea |
+| `spike` | Focused throwaway experiment (`--quick`, `--text`, or frontier mode) |
+| `sketch` | UI/design exploration with throwaway HTML mockups |
+| `map-codebase` | Generate structured codebase docs under `.gsd/codebase/` |
+| `docs-update` | Generate, update, or verify docs against live code |
+| `graphify` | Build, query, inspect, or diff `.gsd/knowledge/` |
+| `stats` | Show project statistics, milestone state, git metrics, and timeline |
+| `progress` | Summarize recent work; can route `--next` or `--do "..."` |
+| `health` | Check `.gsd/` integrity (`--repair`, `--context`) |
+| `surface` | Manage surfaced skills and extensions |
+| `code-review` | Review changed source diff-first for bugs, security, and quality |
+| `review` | Peer-review recent work across reviewer perspectives |
+| `audit-milestone` | Verify a milestone met its definition of done |
+| `audit-uat` | Audit outstanding UAT/verification items |
+| `audit-fix` | Classify and remediate audit findings |
+| `ui-review` | Run a six-pillar frontend visual audit |
+| `secure-phase` | Verify threat mitigations |
+| `validate-phase` | Fill validation and test coverage gaps |
+| `verify-work` | Run conversational UAT |
+| `plan-review-convergence` | Iterate a plan through review cycles |
+| `discuss-phase` | Gather milestone or slice context through questions |
+| `plan-phase` | Create a detailed slice plan |
+| `execute-phase` | Execute slice tasks with wave support |
+| `spec-phase` | Clarify what a milestone delivers |
+| `mvp-phase` | Plan a vertical MVP milestone |
+| `ui-phase` | Produce a `UI-SPEC` |
+| `ai-integration-phase` | Produce an `AI-SPEC` |
+| `ultraplan-phase` | Run extended planning and review |
+| `autonomous` | Run remaining lifecycle work continuously |
+| `pause-work` | Create a pause handoff |
+| `resume-work` | Resume work with restored context |
+| `manager` | Manage multiple milestones from a command-center workflow |
+| `phase` | Manage milestone queue ordering |
+| `thread` | Manage persistent context threads |
+| `workstreams` | Route workstream actions through `parallel` |
+| `workspace` | Route workspace actions through `worktree` |
+| `milestone-summary` | Generate a project or milestone summary |
+| `review-backlog` | Review and promote backlog items |
+| `inbox` | Triage GitHub issues and PRs |
+| `import` | Ingest external plans with conflict detection |
+| `ingest-docs` | Bootstrap or merge `.gsd/` state from docs |
+| `profile-user` | Generate and persist a developer profile |
+| `settings` | Configure workflow toggles and model profile |
+| `ns-context`, `ns-ideate`, `ns-manage`, `ns-project`, `ns-review`, `ns-workflow` | Namespace-grouping names that redirect to `help` |
+
 ## Phases
 
 GSD workflows progress through these phases:

package/dist/resources/extensions/gsd/state/derive/cache.js

@@ -0,0 +1,28 @@
+// Project/App: gsd-pi
+// File Purpose: deriveState memoization cache and telemetry.
+const CACHE_TTL_MS = 100;
+let _stateCache = null;
+let _telemetry = { dbDeriveCount: 0 };
+export function getDeriveTelemetry() {
+    return { ..._telemetry };
+}
+export function resetDeriveTelemetry() {
+    _telemetry = { dbDeriveCount: 0 };
+}
+export function incrementDbDeriveCount() {
+    _telemetry.dbDeriveCount++;
+}
+export function invalidateStateCache() {
+    _stateCache = null;
+}
+export function readCachedDeriveState(cacheKey) {
+    if (_stateCache &&
+        _stateCache.basePath === cacheKey &&
+        Date.now() - _stateCache.timestamp < CACHE_TTL_MS) {
+        return _stateCache.result;
+    }
+    return null;
+}
+export function writeCachedDeriveState(cacheKey, result) {
+    _stateCache = { basePath: cacheKey, result, timestamp: Date.now() };
+}

package/dist/resources/extensions/gsd/state/derive/db-open.js

@@ -0,0 +1,39 @@
+// Project/App: gsd-pi
+// File Purpose: Workflow DB open helpers for state derivation.
+import { getAllMilestones, isDbAvailable, setMilestoneQueueOrder } from '../../gsd-db.js';
+import { openExistingWorkflowDatabase } from '../../db-workspace.js';
+import { loadQueueOrder, sortByQueueOrder } from '../../queue-order.js';
+export function syncQueueOrderProjectionToDb(basePath) {
+    const queueOrder = loadQueueOrder(basePath);
+    if (!queueOrder)
+        return;
+    const currentIds = getAllMilestones().map((m) => m.id);
+    const desiredIds = sortByQueueOrder(currentIds, queueOrder);
+    if (currentIds.length === desiredIds.length && currentIds.every((id, i) => id === desiredIds[i]))
+        return;
+    setMilestoneQueueOrder(desiredIds);
+}
+export function ensureExistingWorkflowDbOpen(basePath) {
+    const opened = isDbAvailable() || openExistingWorkflowDatabase(basePath).ok;
+    if (opened)
+        syncQueueOrderProjectionToDb(basePath);
+    return opened;
+}
+export function buildDbUnavailableState() {
+    return {
+        activeMilestone: null,
+        activeSlice: null,
+        activeTask: null,
+        phase: "pre-planning",
+        recentDecisions: [],
+        blockers: ["DB unavailable — runtime markdown state derivation is disabled"],
+        nextAction: "Open or create the canonical GSD database before deriving workflow state. If this project only has markdown state, run /gsd migrate explicitly.",
+        registry: [],
+        requirements: { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 },
+        progress: { milestones: { done: 0, total: 0 } },
+    };
+}
+export function getRequestedMilestoneLock() {
+    const lock = process.env.GSD_MILESTONE_LOCK?.trim();
+    return lock || undefined;
+}