@opengsd/gsd-pi 1.3.0-dev.eed73bea → 1.4.0-dev.5fc22c6f

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

@@ -19,7 +19,7 @@ import { logWarning } from "./workflow-logger.js";
 import { DEFAULT_TOKEN_PROFILE, resolveProfileDefaults as _resolveProfileDefaults, VALID_TOKEN_PROFILES, resolveDisabledModelProvidersFromPreferences, } from "./preferences-models.js";
 import { nativeHasCommittedHead, nativeIsRepo } from "./native-git-bridge.js";
 import { KNOWN_PREFERENCE_KEYS, MODE_DEFAULTS, formatSkillRef, } from "./preferences-types.js";
-import { validatePreferences } from "./preferences-validation.js";
+import { crossAxisPreferenceWarnings, validatePreferences } from "./preferences-validation.js";
 import { gsdHome } from "./gsd-home.js";
 // ─── Re-exports: validation ─────────────────────────────────────────────────
 export { validatePreferences } from "./preferences-validation.js";
@@ -203,6 +203,7 @@ function effectivePreferencesCacheKey(basePath, opts) {
         project: projectPreferencesCandidatePaths(basePath).map(preferencesFileSignature),
         availableModelIds: opts?.availableModelIds ?? null,
         preferredModelId: opts?.preferredModelId ?? null,
+        skipProfileDefaults: opts?.skipProfileDefaults === true,
     });
 }
 function cloneLoadedPreferences(loaded) {
@@ -264,7 +265,7 @@ export function loadEffectiveGSDPreferences(basePath, opts) {
     else {
         profileForDefaults = DEFAULT_TOKEN_PROFILE;
     }
-    if (profileForDefaults) {
+    if (profileForDefaults && !opts?.skipProfileDefaults) {
         const profileDefaults = _resolveProfileDefaults(profileForDefaults, opts?.availableModelIds, result.preferences.dynamic_routing, opts?.preferredModelId);
         const defaultsToApply = explicitProfile
             ? profileDefaults
@@ -282,9 +283,35 @@ export function loadEffectiveGSDPreferences(basePath, opts) {
         };
     }
     result = stripInheritedPlanningDepth(result, projectHasPlanningDepth);
+    result = appendCrossAxisPreferenceWarnings(result);
     cacheEffectivePreferences(cacheKey, result);
     return result;
 }
+function appendCrossAxisPreferenceWarnings(loaded) {
+    const crossWarnings = crossAxisPreferenceWarnings(loaded.preferences);
+    const existingMessages = new Set([
+        ...(loaded.warnings ?? []),
+        ...(loaded.diagnostics ?? []).map((diagnostic) => diagnostic.message),
+    ]);
+    const newWarnings = crossWarnings.filter((message) => !existingMessages.has(message));
+    if (newWarnings.length === 0)
+        return loaded;
+    return {
+        ...loaded,
+        warnings: [...(loaded.warnings ?? []), ...newWarnings],
+        diagnostics: [
+            ...(loaded.diagnostics ?? []),
+            ...newWarnings.map((message) => ({
+                path: loaded.path,
+                scope: loaded.scope,
+                severity: "warning",
+                kind: "validation",
+                message,
+                sanitized: true,
+            })),
+        ],
+    };
+}
 function withoutProfilePhaseDefaults(defaults) {
     if (defaults.phases === undefined)
         return defaults;

package/dist/resources/extensions/gsd/prompts/code-review.md

@@ -16,18 +16,20 @@ You are running the GSD **code-review** workflow — review source files changed
 
 1. **Determine the file set.** Use the explicit `--files` list if provided. Otherwise derive the changed source files from the active slice's recent commits / SUMMARY, or fall back to the git diff against the base branch. Exclude `.gsd/`, lockfiles, generated/vendored code, and docs unless `--files` names them.
 
-2. **Review each file** at the requested depth:
+2. **Gather diff-first context.** Run `git diff` for the file set (or the relevant commit range) and use that as the primary review evidence. Use `read` only when the diff is insufficient — new/untracked files, truncated hunks, or missing surrounding context needed for a finding. Do **not** read every changed file when the diff already covers the edits. If the Tool Call Loop Guard blocks a tool, stop calling tools for the rest of this turn and continue in text.
+
+3. **Review at the requested depth:**
    - **quick** — bugs, security, and correctness only.
    - **standard** (default) — quick + maintainability, error handling, edge cases.
    - **deep** — standard + performance, concurrency, API design, test coverage gaps.
 
    Ground every finding in the actual code with file path + line reference. Categorize each by severity (critical / warning / nit) and type (bug, security, quality, performance).
 
-3. **Write the review.** Produce `.gsd/reviews/{{reviewId}}-REVIEW.md` with the findings table and per-finding detail (location, issue, suggested fix).
+4. **Write the review.** Produce `.gsd/reviews/{{reviewId}}-REVIEW.md` with the findings table and per-finding detail (location, issue, suggested fix).
 
-4. **Present results.** Summarize counts by severity and list the critical findings first.
+5. **Present results.** Summarize counts by severity and list the critical findings first.
 
-5. **Fix mode** (only when `--fix` is set): for each finding that is safely auto-fixable (deterministic, no behavior change beyond the fix), apply it. After each fix batch, run the project's tests. Commit atomically with the finding IDs referenced in the message. Do not auto-apply findings that are ambiguous or that change public behavior — surface those for a human decision instead.
+6. **Fix mode** (only when `--fix` is set): for each finding that is safely auto-fixable (deterministic, no behavior change beyond the fix), apply it. After each fix batch, run the project's tests. Commit atomically with the finding IDs referenced in the message. Do not auto-apply findings that are ambiguous or that change public behavior — surface those for a human decision instead.
 
 ## Success criteria
 

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

@@ -104,8 +104,8 @@ If the preference is off, ignore this section and plan every slice fully.
 
 If the roadmap has one slice, also plan S01 and its tasks inline:
 
-1. After `gsd_plan_milestone` returns, call `gsd_plan_slice` for S01 with full task breakdown.
-2. Use inlined **Slice Plan** and **Task Plan** templates for tool parameters.
+1. After `gsd_plan_milestone` returns, call `gsd_plan_slice` for S01 with slice metadata only; omit `tasks`.
+2. Then call `gsd_plan_task` once per S01 task. Use inlined **Slice Plan** and **Task Plan** templates for tool parameters.
 3. Keep simple slices lean. Omit Proof Level, Integration Closure, and Observability if all would be "none"; executable verification commands are enough.
 
 Do **not** write plan files manually; use DB-backed tools so state stays consistent.

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

@@ -32,6 +32,8 @@ Before planning, validate roadmap assumptions against code and dependency summar
 
 If slice research is inlined, trust its architectural findings, but verify every concrete file path you place in task `inputs` or `expectedOutput` against the current tree or prior/same-task outputs. Explore enough code to confirm paths, boundaries, and verification. Executors later get only task plans, slice excerpt, and prior summaries, so put required paths, steps, inputs, and outputs in task plans.
 
+{{repoRegistry}}
+
 {{executorContextConstraints}}
 
 ## Planning Rules
@@ -45,8 +47,8 @@ If slice research is inlined, trust its architectural findings, but verify every
 6. Include Threat Surface (Q3), Requirement Impact (Q4), proof level, observability, integration closure, Failure Modes (Q5), Load Profile (Q6), and Negative Tests (Q7) only where applicable.
 7. Right-size tasks. Simple slices can be one task; split only when context, ownership, or verification boundaries justify it.
 8. Task `verify` commands must be safe, simple commands. Do not use shell pipes, redirects, semicolons, backticks, command substitution, output trimming, or grep regex alternation with `|`. If multiple checks are needed, create a small test file and run it with `node --test` or a package test script, or use separate simple commands joined only with `&&`. For absence checks, verify a pattern does not exist with `! grep -q 'pattern' file` or `! rg -q 'pattern' file`; do not use `grep -c` or `rg -c` to assert zero matches because count commands exit 1 when they find zero matches, and the verification gate treats that as failure.
-9. Each task needs the exact `gsd_plan_slice.tasks[]` shape: `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. `description` should contain the Why / Do / Done-when narrative. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even when there is only one path (for example, `"inputs": ["src/index.ts"]`, never `"inputs": "src/index.ts"`). Use paths relative to `{{workingDirectory}}`; do not put absolute paths to the original checkout or any directory outside `{{workingDirectory}}` in `files`, `inputs`, `expectedOutput`, or verification commands. **`expectedOutput` must only list files the task actually creates or overwrites on disk.** Do NOT include files the task merely reads, verifies, tests, or describes — those belong in `inputs`, `verify`, `description`, or slice success criteria. If a task is a pure verification or test task that produces no new files, `expectedOutput` must be `[]`; if it writes a test-result log or assertion output file, list only that concrete file path. A file that does not yet exist on disk and is needed as an `input` must be produced by an earlier task's `expectedOutput` — if no prior task creates it, add a task before this one that does. Never list GSD planning artifacts — anything under `.gsd/`, `.planning/`, or `.audits/`, or artifact names like `M001-CONTEXT.md` / `S01-PLAN.md` — in `inputs`, `files`, or `expectedOutput`: their content is preloaded as context, and they are written by workflow tools, not by tasks.
-10. Persist with `gsd_plan_slice` using `milestoneId`, `sliceId`, `goal`, optional `successCriteria`/`proofLevel`/`integrationClosure`/`observabilityImpact`, and `tasks`. `gsd_plan_slice` handles task persistence transactionally and renders `{{outputPath}}` plus task plans; do not call `gsd_plan_task`. The DB-backed tool is the canonical write path. Do **not** rely on direct `PLAN.md` writes as the source of truth.
+9. Each task persisted with `gsd_plan_task` needs the exact shape: `milestoneId`, `sliceId`, `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. In a parent workspace (when a Declared Repositories block is present above), also set `targetRepositories` to the repository id(s) the task touches. `description` should contain the Why / Do / Done-when narrative. Any npm package name in a task description's install/add instructions (`npm install`, `yarn add`, `pnpm add`) or in `require('...')` or `import ... from '...'` code examples is subject to pre-execution registry validation; reference only packages that exist on the public npm registry, and remove or correct any package name that is not real. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even when there is only one path (for example, `"inputs": ["src/index.ts"]`, never `"inputs": "src/index.ts"`). Use paths relative to `{{workingDirectory}}`; do not put absolute paths to the original checkout or any directory outside `{{workingDirectory}}` in `files`, `inputs`, `expectedOutput`, or verification commands. **`expectedOutput` must only list files the task actually creates or overwrites on disk.** Do NOT include files the task merely reads, verifies, tests, or describes — those belong in `inputs`, `verify`, `description`, or slice success criteria. If a task is a pure verification or test task that produces no new files, `expectedOutput` must be `[]`; if it writes a test-result log or assertion output file, list only that concrete file path. A file that does not yet exist on disk and is needed as an `input` must be produced by an earlier task's `expectedOutput` — if no prior task creates it, add a task before this one that does. Never list GSD planning artifacts — anything under `.gsd/`, `.planning/`, or `.audits/`, or artifact names like `M001-CONTEXT.md` / `S01-PLAN.md` — in `inputs`, `files`, or `expectedOutput`: their content is preloaded as context, and they are written by workflow tools, not by tasks.
+10. Persist incrementally through DB-backed tools. First call `gsd_plan_slice` with `milestoneId`, `sliceId`, `goal`, and optional `successCriteria`/`proofLevel`/`integrationClosure`/`observabilityImpact` (and `targetRepositories` in a parent workspace, to set the slice-wide default); omit `tasks` for this metadata call. Then call `gsd_plan_task` once per task, using the task shape above. Each successful tool call saves progress and re-renders `{{outputPath}}` from DB. The DB-backed tools are the canonical write path. Do **not** rely on direct `PLAN.md` writes as the source of truth.
 11. Self-audit before finishing: goal/demo closure, requirement coverage, deliverable coverage audit (cross-check every file listed in CONTEXT.md `## Scope` / `### In Scope` against task `files` or `expectedOutput`), locked decisions, concrete paths, dependency order, wiring, scope size, proof truthfulness, feature completeness, and quality gates. Quality gates: non-trivial slices/tasks include specific Q3-Q7 coverage where applicable.
 12. If planning creates structural decisions, call `gsd_decision_save` for each; the tool persists the decision and regenerates `.gsd/DECISIONS.md`.
 13. {{commitInstruction}}
@@ -55,6 +57,6 @@ The slice directory already exists. Do not mkdir.
 
 **Autonomous execution:** no human is available. Do not call `ask_user_questions` or `secure_env_collect`; make reasonable assumptions and document them.
 
-**You MUST call `gsd_plan_slice` to persist planning state before finishing, unless the stale-path safety rule above stops the unit before safe planning can occur.**
+**You MUST call `gsd_plan_slice` and then `gsd_plan_task` once for each planned task before finishing, unless the stale-path safety rule above stops the unit before safe planning can occur.**
 
 When done, say: "Slice {{sliceId}} planned." Say this exactly once — if you already said it in a prior message, do not repeat it.

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/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/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);

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/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/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/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
 

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
 
@@ -66,7 +67,7 @@ These commands dispatch native GSD prompts adapted to the milestone, slice, and
 | `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 for bugs, security, and quality |
+| `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 |

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;
+}