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

package/dist/resources/extensions/gsd/delegation-policy.js

@@ -0,0 +1,155 @@
+// Delegation policy — codifies which GSD MCP tools are safe to run as
+// background sub-agents while the foreground /gsd flow continues. Verdicts
+// are derived from the round-1 and round-2 evaluations recorded in this
+// branch's PR description; the rationale field on each entry preserves
+// the reason so future changes have to revisit the analysis explicitly.
+//
+// Default-deny: unknown tools are never backgroundable.
+//
+// ─── Tool-name vs unit-type namespaces ───────────────────────────────────
+// Entries are keyed by canonical MCP tool name (`gsd_*`). The optional
+// `unitType` field is a *secondary* index for the dispatcher's convenience
+// — it bridges this policy to `auto-dispatch.ts`' `DispatchAction.unitType`
+// values. The two namespaces are not 1:1:
+//
+//   - Some tools have no corresponding unit type (e.g. `gsd_doctor`,
+//     `gsd_plan_task`) and intentionally omit `unitType`.
+//   - Some unit types share a tool — e.g. `execute-task`, `execute-task-simple`,
+//     and `reactive-execute` all invoke `gsd_execute`. The current shape
+//     allows only one `unitType` per entry, so those units fall through to
+//     `getVerdictByUnitType() === null` (→ `backgroundable: false`) even
+//     though `gsd_execute` itself is GOOD. This is the intended default-deny
+//     posture until a future PR wires actual background dispatch and
+//     decides whether each unit-level orchestration is safe — the unit
+//     wraps a prompt, harness setup, and post-processing on top of the
+//     tool, and the tool's safety doesn't transfer automatically.
+//
+// Auto-dispatch produces 20 distinct unit types; only 5 are explicitly
+// classified here. The other 15 default-deny:
+//   complete-milestone, complete-slice, discuss-milestone, discuss-project,
+//   discuss-requirements, execute-task, execute-task-simple, gate-evaluate,
+//   reactive-execute, refine-slice, research-decision, research-milestone,
+//   research-project, research-slice, rewrite-docs, run-uat
+//
+// Adding a `unitType` mapping (or a future `unitTypes: string[]`) to an
+// existing entry is the place to lift any of these out of default-deny
+// when the analysis has been done.
+const POLICY = {
+    gsd_plan_slice: {
+        toolName: "gsd_plan_slice",
+        unitType: "plan-slice",
+        verdict: "good",
+        rationale: "Self-contained, no user prompts, atomic DB tx; existing slice-parallel-orchestrator pattern transfers cleanly.",
+        constraints: [
+            "Lock the slice from further user discussion once dispatched (context is frozen at dispatch time).",
+            "Foreground must not derive state for that slice while the transaction is in flight.",
+            "Foreground must await background completion before any tool reads the planned tasks/gates.",
+        ],
+    },
+    gsd_execute: {
+        toolName: "gsd_execute",
+        // No `unitType` set on purpose — the underlying tool is safe, but the
+        // unit-level orchestrations that invoke it (`execute-task`,
+        // `execute-task-simple`, `reactive-execute`) wrap additional prompt and
+        // harness work whose safety is a separate analysis. Default-deny those
+        // units until that analysis is recorded; adding `unitType` here would
+        // promote them silently.
+        verdict: "good",
+        rationale: "No DB writes; UUID-isolated stdout/stderr/meta files; existing reactive-execute parallel-subagent precedent.",
+    },
+    gsd_validate_milestone: {
+        toolName: "gsd_validate_milestone",
+        unitType: "validate-milestone",
+        verdict: "good",
+        rationale: "Verdict pre-computed by parallel reviewers; atomic DB tx plus isolated VALIDATION.md write; no user interaction.",
+    },
+    gsd_reassess_roadmap: {
+        toolName: "gsd_reassess_roadmap",
+        unitType: "reassess-roadmap",
+        verdict: "good",
+        rationale: "Narrower mutation scope than plan_milestone; structural guards prevent modification of completed slices.",
+    },
+    gsd_doctor: {
+        toolName: "gsd_doctor",
+        verdict: "risky",
+        rationale: "Diagnostic-only mode (fix=false) is safe to background; fix=true writes STATE.md/ROADMAP.md without session-lock coordination and can race the foreground flow.",
+        constraints: [
+            "Background only with fix=false (diagnostic-only).",
+            "Apply fixes synchronously, only when no foreground unit is dispatched.",
+        ],
+    },
+    gsd_plan_milestone: {
+        toolName: "gsd_plan_milestone",
+        unitType: "plan-milestone",
+        verdict: "risky",
+        rationale: "Inputs require CONTEXT.md from discuss-milestone, so initial questioning is already done by the time it can start; TOCTOU guards and projection coherence make concurrency unsafe.",
+    },
+    gsd_replan_slice: {
+        toolName: "gsd_replan_slice",
+        unitType: "replan-slice",
+        verdict: "risky",
+        rationale: "Blocks the replanning→executing state transition on a gate that waits for S##-REPLAN.md; background failure leaves the flow stuck.",
+    },
+    gsd_plan_task: {
+        toolName: "gsd_plan_task",
+        verdict: "no",
+        rationale: "plan-slice prompt explicitly forbids calling gsd_plan_task separately; per-task granularity multiplies manifest writes and projection re-renders with no payoff.",
+    },
+};
+// Alias map keyed on the secondary name; resolves to the canonical entry above.
+// Sourced from packages/mcp-server/src/workflow-tools.ts alias registrations
+// (gsd_milestone_validate, gsd_roadmap_reassess, gsd_slice_replan, gsd_task_plan).
+const ALIASES = {
+    gsd_milestone_validate: "gsd_validate_milestone",
+    gsd_roadmap_reassess: "gsd_reassess_roadmap",
+    gsd_slice_replan: "gsd_replan_slice",
+    gsd_task_plan: "gsd_plan_task",
+};
+function resolveCanonical(name) {
+    return ALIASES[name] ?? name;
+}
+export function getDelegationVerdict(toolName) {
+    return POLICY[resolveCanonical(toolName)] ?? null;
+}
+export function isBackgroundable(toolName) {
+    const entry = getDelegationVerdict(toolName);
+    return entry?.verdict === "good";
+}
+export function listBackgroundableTools() {
+    return Object.values(POLICY)
+        .filter((entry) => entry.verdict === "good")
+        .map((entry) => entry.toolName)
+        .sort();
+}
+export function getVerdictByUnitType(unitType) {
+    for (const entry of Object.values(POLICY)) {
+        if (entry.unitType === unitType)
+            return entry;
+    }
+    return null;
+}
+/**
+ * Annotates a dispatch action in place with `backgroundable: true` when its
+ * unitType has a `good` verdict in the policy. Stop/skip actions pass through
+ * unchanged. Default-deny: unknown unit types resolve to `false`.
+ *
+ * **Mutation contract.** The `backgroundable` field is written directly onto
+ * the passed action object. This is intentional — every dispatch path in
+ * `auto-dispatch.ts` constructs a fresh action object per `where(ctx)` /
+ * `evaluateDispatch(ctx)` invocation, so in-place mutation cannot leak across
+ * dispatch cycles. Future dispatch rules MUST follow that convention: never
+ * cache or share `DispatchAction` objects across calls. If you need to cache,
+ * either freeze the cached object (`Object.freeze`) and clone on read, or
+ * stop calling `annotateBackgroundable` on the shared instance. The annotator
+ * always recomputes from the policy on every call (no internal cache), so
+ * repeated invocations on the same object will overwrite stale values
+ * deterministically — see the `annotateBackgroundable recomputes on each call`
+ * test for the contract pin.
+ */
+export function annotateBackgroundable(action) {
+    if (action.action !== "dispatch")
+        return action;
+    const verdict = getVerdictByUnitType(action.unitType);
+    action.backgroundable = verdict?.verdict === "good";
+    return action;
+}

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

@@ -9,7 +9,7 @@ import { existsSync, openSync, readSync, closeSync, readdirSync, readFileSync, s
 import { dirname, join, parse as parsePath } from "node:path";
 import { homedir } from "node:os";
 import { gsdRoot } from "./paths.js";
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+import { gsdHome } from "./gsd-home.js";
 // ─── Project File Markers ───────────────────────────────────────────────────────
 export const PROJECT_FILES = [
     "package.json",
@@ -602,23 +602,23 @@ function detectVerificationCommands(basePath, detectedFiles, packageManager) {
  * Check if global GSD setup exists (has ~/.gsd/ with preferences).
  */
 export function hasGlobalSetup() {
-    return (existsSync(join(gsdHome, "PREFERENCES.md")) ||
-        existsSync(join(gsdHome, "preferences.md")));
+    return (existsSync(join(gsdHome(), "PREFERENCES.md")) ||
+        existsSync(join(gsdHome(), "preferences.md")));
 }
 /**
  * Check if this is the very first time GSD has been used on this machine.
  * Returns true if ~/.gsd/ doesn't exist or has no preferences or auth.
  */
 export function isFirstEverLaunch() {
-    if (!existsSync(gsdHome))
+    if (!existsSync(gsdHome()))
         return true;
     // If we have preferences, not first launch
-    if (existsSync(join(gsdHome, "PREFERENCES.md")) ||
-        existsSync(join(gsdHome, "preferences.md"))) {
+    if (existsSync(join(gsdHome(), "PREFERENCES.md")) ||
+        existsSync(join(gsdHome(), "preferences.md"))) {
         return false;
     }
     // If we have auth.json, not first launch (onboarding.ts already ran)
-    if (existsSync(join(gsdHome, "agent", "auth.json")))
+    if (existsSync(join(gsdHome(), "agent", "auth.json")))
         return false;
     // Check legacy path too
     const legacyPath = join(homedir(), ".pi", "agent", "gsd-preferences.md");

package/dist/resources/extensions/gsd/dispatch-guard.js

@@ -45,25 +45,21 @@ export function getPriorSliceCompletionBlocker(base, _mainBranch, unitType, unit
         // completion, which is wrong when the SUMMARY is a failure-path report
         // (verification FAILED, blocker placeholder, etc.). Resolve as follows:
         //   1. When DB is available and status is closed → skip (authoritative).
-        //   2. When SUMMARY exists but looks like a failure/blocker report →
-        //      do not short-circuit; fall through to the slice-level check so
-        //      the guard can still block dependents of an active milestone.
-        //   3. Otherwise (SUMMARY without failure markers) → skip. Preserves
-        //      the #1716 contract where a completed milestone with unchecked
-        //      remediation slices is still treated as done.
-        const summaryPath = resolveMilestoneFile(base, mid, "SUMMARY");
+        //   2. When DB is unavailable, legacy SUMMARY.md fallback may skip.
+        //      DB-backed projects must not treat SUMMARY.md as authoritative.
         if (isDbAvailable()) {
             const milestoneRow = getMilestone(mid);
             if (milestoneRow && isClosedStatus(milestoneRow.status))
                 continue;
         }
-        if (summaryPath) {
+        else {
+            const summaryPath = resolveMilestoneFile(base, mid, "SUMMARY");
             let summaryContent = null;
             try {
-                summaryContent = readFileSync(summaryPath, "utf-8");
+                summaryContent = summaryPath ? readFileSync(summaryPath, "utf-8") : null;
             }
             catch { /* ignore */ }
-            if (!summaryContent || classifyMilestoneSummaryContent(summaryContent) !== "failure") {
+            if (summaryContent && classifyMilestoneSummaryContent(summaryContent) !== "failure") {
                 continue;
             }
         }

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -87,7 +87,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   | `git.push_branches`    | `false`      | `true`       |
   | `git.pre_merge_check`  | `false`      | `true`       |
   | `git.merge_strategy`   | `"squash"`   | `"squash"`   |
-  | `git.isolation`        | `"worktree"` | `"worktree"` |
+  | `git.isolation`        | `"none"`     | `"none"`     |
   | `unique_milestone_ids` | `false`      | `true`       |
 
   Quick setup: `/gsd mode` (global) or `/gsd mode project` (project-level).
@@ -137,7 +137,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `commit_type`: string — override the conventional commit type prefix. Must be one of: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `build`, `style`. Default: inferred from diff content.
   - `main_branch`: string — the primary branch name for new git repos (e.g., `"main"`, `"master"`, `"trunk"`). Also used by `getMainBranch()` as the preferred branch when auto-detection is ambiguous. Default: `"main"`.
   - `merge_strategy`: `"squash"` or `"merge"` — controls how worktree branches are merged back. `"squash"` combines all commits into one; `"merge"` preserves individual commits. Default: `"squash"`.
-  - `isolation`: `"worktree"`, `"branch"`, or `"none"` — controls auto-mode git isolation strategy. `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root but creates a milestone branch (useful for submodule-heavy repos); `"none"` works directly on the current branch with no worktree or milestone branch (ideal for step-mode with hot reloads). Default: `"worktree"`.
+  - `isolation`: `"none"`, `"worktree"`, or `"branch"` — controls auto-mode git isolation strategy. `"none"` works directly on the current branch with no worktree or milestone branch (default, ideal for step-mode with hot reloads); `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root but creates a milestone branch (useful for submodule-heavy repos). `worktree` requires a committed `HEAD`; in a zero-commit repo, GSD temporarily treats it as `none` until the first commit exists. Default: `"none"`.
   - `manage_gitignore`: boolean — when `false`, GSD will not touch `.gitignore` at all. Useful when your project has a strictly managed `.gitignore` and you don't want GSD adding entries. Default: `true`.
   - `worktree_post_create`: string — script to run after a worktree is created (both auto-mode and manual `/worktree`). Receives `SOURCE_DIR` and `WORKTREE_DIR` as environment variables. Can be absolute or relative to project root. Runs with 30-second timeout. Failure is non-fatal (logged as warning). Default: none.
   - `auto_pr`: boolean — automatically create a GitHub pull request after a milestone branch is merged. Requires `gh` CLI to be installed. Default: `false`.
@@ -159,6 +159,8 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `token_profile`: `"budget"`, `"balanced"`, `"quality"`, or `"burn-max"` — coordinates model selection, phase skipping, and context compression. `budget` skips research/reassessment and uses cheaper models; `balanced` (default) skips research/reassessment to reduce token burn; `quality` prefers higher-quality models; `burn-max` keeps full-context defaults, disables downgrade routing, and keeps phase skips off.
 
+- `planning_depth`: `"light"` or `"deep"` — controls project-level discovery before milestone planning. `"light"` is the default milestone discussion flow. `"deep"` runs workflow preferences, project discussion, requirements discussion, a research-decision gate, and optional project research before milestone planning. Enable it with `/gsd new-project --deep`, `/gsd new-milestone --deep`, or by setting `planning_depth: deep` in project-local `.gsd/PREFERENCES.md`. Global `~/.gsd/PREFERENCES.md` does not opt every fresh repo into deep mode. Deep mode writes `.gsd/PROJECT.md`, `.gsd/REQUIREMENTS.md`, `.gsd/runtime/research-decision.json`, and, when research is approved, `.gsd/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, and `PITFALLS.md`.
+
 - `phases`: fine-grained control over which phases run. Usually set by `token_profile`, but can be overridden. Keys:
   - `skip_research`: boolean — skip milestone-level research. Default: `false`.
   - `reassess_after_slice`: boolean — run a dedicated roadmap-reassessment unit after each completed slice. Default: `false` (per ADR-003 §4). The plan-slice agent for the next slice performs JIT reassessment via a prompt preamble at zero additional token cost; a dedicated reassess session is opt-in. Set to `true` (e.g. via the `burn-max` profile) if you want the explicit session.
@@ -302,7 +304,7 @@ mode: solo
 ---
 ```
 
-Equivalent to setting `git.auto_push: true`, `git.push_branches: false`, `git.pre_merge_check: false`, `git.merge_strategy: squash`, `git.isolation: worktree`, `unique_milestone_ids: false`.
+Equivalent to setting `git.auto_push: true`, `git.push_branches: false`, `git.pre_merge_check: false`, `git.merge_strategy: squash`, `git.isolation: none`, `unique_milestone_ids: false`.
 
 **Team — unique IDs, push branches, pre-merge checks:**
 
@@ -313,7 +315,7 @@ mode: team
 ---
 ```
 
-Equivalent to setting `git.auto_push: false`, `git.push_branches: true`, `git.pre_merge_check: true`, `git.merge_strategy: squash`, `git.isolation: worktree`, `unique_milestone_ids: true`.
+Equivalent to setting `git.auto_push: false`, `git.push_branches: true`, `git.pre_merge_check: true`, `git.merge_strategy: squash`, `git.isolation: none`, `unique_milestone_ids: true`.
 
 **Mode with overrides — team mode but with auto-push:**
 

package/dist/resources/extensions/gsd/doctor-engine-checks.js

@@ -1,12 +1,12 @@
 import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { isDbAvailable, _getAdapter } from "./gsd-db.js";
-import { resolveMilestoneFile } from "./paths.js";
+import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
 import { deriveState } from "./state.js";
 import { readEvents } from "./workflow-events.js";
 import { renderAllProjections } from "./workflow-projections.js";
 export async function checkEngineHealth(basePath, issues, fixesApplied) {
-    const dbPath = join(basePath, ".gsd", "gsd.db");
+    const dbPath = resolveGsdPathContract(basePath).projectDb;
     if (!isDbAvailable() && existsSync(dbPath)) {
         issues.push({
             severity: "warning",

package/dist/resources/extensions/gsd/doctor-providers.js

@@ -16,7 +16,7 @@ import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getAuthPath, PROVIDER_REGISTRY } from "./key-manager.js";
-import { getHomeDir } from "./home-dir.js";
+import { homedir } from "node:os";
 // ── Provider routing constants ────────────────────────────────────────────────
 /**
  * Providers that use external CLI authentication (not API keys).
@@ -159,7 +159,7 @@ function isCliBinaryInPath(providerId) {
     return pathDirs.some(dir => executableNames.some(name => existsSync(join(dir, name))));
 }
 function modelsJsonPaths() {
-    const home = getHomeDir();
+    const home = homedir();
     return [
         join(home, ".gsd", "agent", "models.json"),
         // Keep parity with custom-provider discovery during auto bootstrap.

package/dist/resources/extensions/gsd/doctor-runtime-checks.js

@@ -11,6 +11,18 @@ import { readAllSessionStatuses, isSessionStale, removeSessionStatus } from "./s
 import { recoverFailedMigration } from "./migrate-external.js";
 import { splitCompletedKey } from "./forensics.js";
 import { findMilestoneIds } from "./milestone-ids.js";
+const MAX_UAT_ATTEMPTS = 3;
+function hasAssessmentVerdict(basePath, mid, sid) {
+    const assessmentPath = join(gsdRoot(basePath), "milestones", mid, "slices", sid, `${sid}-ASSESSMENT.md`);
+    if (!existsSync(assessmentPath))
+        return false;
+    try {
+        return /^\s*verdict\s*:\s*(PASS|FAIL|PARTIAL)\b/im.test(readFileSync(assessmentPath, "utf-8"));
+    }
+    catch {
+        return false;
+    }
+}
 export async function checkRuntimeHealth(basePath, issues, fixesApplied, shouldFix) {
     const root = gsdRoot(basePath);
     // ── Stale crash lock ──────────────────────────────────────────────────
@@ -175,6 +187,48 @@ export async function checkRuntimeHealth(basePath, issues, fixesApplied, shouldF
     catch {
         // Non-fatal — hook state check failed
     }
+    // ── Exhausted run-uat retry counters ──────────────────────────────────
+    try {
+        const runtimeDir = join(root, "runtime");
+        if (existsSync(runtimeDir)) {
+            const uatCounterPattern = /^uat-count-(M\d+)-(S\d+)\.json$/;
+            for (const fileName of readdirSync(runtimeDir)) {
+                const match = fileName.match(uatCounterPattern);
+                if (!match)
+                    continue;
+                const [, mid, sid] = match;
+                if (!mid || !sid || hasAssessmentVerdict(basePath, mid, sid))
+                    continue;
+                const filePath = join(runtimeDir, fileName);
+                let count = 0;
+                try {
+                    const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+                    count = typeof parsed.count === "number" ? parsed.count : 0;
+                }
+                catch {
+                    count = MAX_UAT_ATTEMPTS + 1;
+                }
+                if (count <= MAX_UAT_ATTEMPTS)
+                    continue;
+                issues.push({
+                    severity: "warning",
+                    code: "uat_retry_exhausted",
+                    scope: "slice",
+                    unitId: `${mid}/${sid}`,
+                    message: `run-uat for ${mid}/${sid} exhausted ${count - 1} retry attempt(s) without an ASSESSMENT verdict. Reset the retry counter after fixing the underlying UAT/tool issue, then rerun /gsd auto.`,
+                    file: `.gsd/runtime/${fileName}`,
+                    fixable: true,
+                });
+                if (shouldFix("uat_retry_exhausted")) {
+                    rmSync(filePath, { force: true });
+                    fixesApplied.push(`reset exhausted run-uat retry counter for ${mid}/${sid}`);
+                }
+            }
+        }
+    }
+    catch {
+        // Non-fatal — UAT retry counter check failed
+    }
     // ── Activity log bloat ────────────────────────────────────────────────
     try {
         const activityDir = join(root, "activity");

package/dist/resources/extensions/gsd/eval-review-schema.js

@@ -0,0 +1,208 @@
+/**
+ * EVAL-REVIEW frontmatter schema and parser.
+ *
+ * The auditor agent for `/gsd eval-review` writes a markdown file whose
+ * machine-readable contract lives entirely in YAML frontmatter. The body
+ * after the closing `---` is human-only prose and is never parsed by any
+ * consumer (the design response to a prior parser that used regex over LLM-generated
+ * prose and produced silent failures).
+ *
+ * This module owns:
+ *   - The TypeBox schema for the frontmatter (single source of truth).
+ *   - A small frontmatter extractor (locates the YAML block).
+ *   - The validated parser (`parseEvalReviewFrontmatter`).
+ *   - Pure helpers for derived fields the handler must recompute server-side
+ *     (overall score, severity counts) — we never trust LLM arithmetic.
+ *
+ * Consumers: `commands-eval-review.ts` (writer), `commands-ship.ts` (reader
+ * for the soft pre-ship warning), and a future `commands-eval-fix.ts`.
+ */
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { parse as parseYaml } from "yaml";
+// ─── Constants ────────────────────────────────────────────────────────────────
+/** Schema version literal embedded in every EVAL-REVIEW.md frontmatter. */
+export const EVAL_REVIEW_SCHEMA_VERSION = "eval-review/v1";
+/** Verdict values, ordered from worst to best for UI display purposes. */
+export const VERDICT_VALUES = [
+    "NOT_IMPLEMENTED",
+    "SIGNIFICANT_GAPS",
+    "NEEDS_WORK",
+    "PRODUCTION_READY",
+];
+/** Severity classifications used in `gaps[*].severity`. */
+export const SEVERITY_VALUES = ["blocker", "major", "minor"];
+/** Eval dimensions an auditor scores. `other` is the catch-all. */
+export const DIMENSION_VALUES = [
+    "observability",
+    "guardrails",
+    "tests",
+    "metrics",
+    "datasets",
+    "other",
+];
+/** Lower bound for any score in the schema. */
+export const MIN_SCORE = 0;
+/** Upper bound for any score in the schema. */
+export const MAX_SCORE = 100;
+/** Coverage's contribution to overall_score. See `docs/user-docs/eval-review.md` for rationale. */
+export const COVERAGE_WEIGHT = 0.6;
+/** Infrastructure's contribution to overall_score. See `docs/user-docs/eval-review.md` for rationale. */
+export const INFRASTRUCTURE_WEIGHT = 0.4;
+// ─── Schema ───────────────────────────────────────────────────────────────────
+const verdictSchema = Type.Union(VERDICT_VALUES.map((v) => Type.Literal(v)));
+const severitySchema = Type.Union(SEVERITY_VALUES.map((v) => Type.Literal(v)));
+const dimensionSchema = Type.Union(DIMENSION_VALUES.map((v) => Type.Literal(v)));
+/**
+ * One gap finding inside `gaps[]`. Every field is required — the prompt
+ * cannot emit a partial gap. `evidence` is mandatory; the anti-Goodhart
+ * guard depends on it.
+ */
+export const EvalReviewGap = Type.Object({
+    id: Type.String({ pattern: "^G\\d+$" }),
+    dimension: dimensionSchema,
+    severity: severitySchema,
+    description: Type.String({ minLength: 1 }),
+    evidence: Type.String({ minLength: 1 }),
+    suggested_fix: Type.String({ minLength: 1 }),
+});
+/** Severity histogram. The handler recomputes this from `gaps[]`. */
+export const EvalReviewCounts = Type.Object({
+    blocker: Type.Integer({ minimum: 0 }),
+    major: Type.Integer({ minimum: 0 }),
+    minor: Type.Integer({ minimum: 0 }),
+});
+/**
+ * The full frontmatter schema. Field order in the schema definition mirrors
+ * the order that the auditor prompt asks the LLM to emit, so a literal-eyeball
+ * comparison between this file and `prompts/eval-review.md` stays meaningful.
+ */
+export const EvalReviewFrontmatter = Type.Object({
+    schema: Type.Literal(EVAL_REVIEW_SCHEMA_VERSION),
+    verdict: verdictSchema,
+    coverage_score: Type.Integer({ minimum: MIN_SCORE, maximum: MAX_SCORE }),
+    infrastructure_score: Type.Integer({ minimum: MIN_SCORE, maximum: MAX_SCORE }),
+    overall_score: Type.Integer({ minimum: MIN_SCORE, maximum: MAX_SCORE }),
+    generated: Type.String({ pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$" }),
+    slice: Type.String({ pattern: "^S\\d+$" }),
+    milestone: Type.String({ minLength: 1 }),
+    gaps: Type.Array(EvalReviewGap),
+    counts: EvalReviewCounts,
+});
+// ─── Frontmatter extraction ───────────────────────────────────────────────────
+/**
+ * Locate the YAML block between two `---` lines and return its raw text.
+ *
+ * Tolerant to CRLF line endings. Does not interpret the YAML — that's the
+ * caller's job. The extractor only enforces the markdown frontmatter shape.
+ *
+ * @param raw - Full contents of an EVAL-REVIEW.md file.
+ * @returns `{ yaml }` with the inner YAML text on success, or `{ error }`
+ *   describing why the frontmatter could not be located.
+ */
+export function extractFrontmatterRaw(raw) {
+    const lines = raw.split(/\r?\n/);
+    if (lines[0] !== "---") {
+        return { error: "Missing opening `---` frontmatter delimiter on line 1" };
+    }
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i] === "---") {
+            return { yaml: lines.slice(1, i).join("\n") };
+        }
+    }
+    return { error: "Missing closing `---` frontmatter delimiter" };
+}
+/**
+ * Parse and validate the frontmatter of an EVAL-REVIEW.md file.
+ *
+ * Failure cases are exhaustive and deterministic:
+ *   - missing/unclosed frontmatter → `pointer: "/"`, message names the cause
+ *   - YAML syntax error → `pointer: "/"`, message contains "YAML"
+ *   - schema violation → `pointer` is the JSON-Pointer path of the bad field
+ *
+ * Body content after the closing `---` is never inspected. This is an
+ * response to a prior parser that used regex over the body and silently
+ * failed on prose / tables / numbered lists.
+ *
+ * @param raw - Full contents of an EVAL-REVIEW.md file.
+ * @returns A discriminated `ParseResult`.
+ */
+export function parseEvalReviewFrontmatter(raw) {
+    const fm = extractFrontmatterRaw(raw);
+    if ("error" in fm) {
+        return { ok: false, error: fm.error, pointer: "/" };
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(fm.yaml, { schema: "core" });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `YAML parse error: ${msg}`, pointer: "/" };
+    }
+    const schema = EvalReviewFrontmatter;
+    if (!Value.Check(schema, parsed)) {
+        const errs = [...Value.Errors(schema, parsed)];
+        const first = errs[0];
+        return {
+            ok: false,
+            error: `Schema validation failed: ${first?.message ?? "unknown error"}`,
+            pointer: first?.path ?? "/",
+        };
+    }
+    return { ok: true, data: parsed };
+}
+// ─── Derived fields ───────────────────────────────────────────────────────────
+/**
+ * Compute `overall_score` from the two component scores using the rubric
+ * weights documented in `docs/user-docs/eval-review.md`.
+ *
+ * The handler always recomputes this value rather than trusting whatever the
+ * LLM emitted in `overall_score`. If the LLM-emitted value disagrees with the
+ * recomputed one, the disagreement is logged and the recomputed value wins.
+ *
+ * Clamps the result into `[MIN_SCORE, MAX_SCORE]` defensively. Schema-validated
+ * inputs are already in range, but the helper is exported and may be called
+ * from a code path that bypasses the schema (tests, future tools); the clamp
+ * keeps the contract honest in those cases.
+ *
+ * @param coverage - integer 0..100 from the auditor's coverage assessment.
+ * @param infrastructure - integer 0..100 from the auditor's infra assessment.
+ * @returns rounded integer 0..100.
+ */
+export function computeOverallScore(coverage, infrastructure) {
+    const raw = Math.round(coverage * COVERAGE_WEIGHT + infrastructure * INFRASTRUCTURE_WEIGHT);
+    return Math.max(MIN_SCORE, Math.min(MAX_SCORE, raw));
+}
+/**
+ * Build the severity histogram for a list of gaps.
+ *
+ * Used by the handler to overwrite whatever the LLM put in `counts` —
+ * we recompute server-side rather than trust LLM arithmetic.
+ *
+ * @param gaps - validated gap list.
+ * @returns counts keyed by severity literal.
+ */
+export function deriveCounts(gaps) {
+    const counts = { blocker: 0, major: 0, minor: 0 };
+    for (const g of gaps)
+        counts[g.severity]++;
+    return counts;
+}
+/**
+ * Map a numeric overall_score to its verdict literal using the bands from
+ * Bands per `docs/user-docs/eval-review.md`: ≥80 PRODUCTION_READY, 60..79 NEEDS_WORK, 40..59 SIGNIFICANT_GAPS,
+ * <40 NOT_IMPLEMENTED.
+ *
+ * @param overall - integer 0..100.
+ * @returns a verdict literal.
+ */
+export function verdictForScore(overall) {
+    if (overall >= 80)
+        return "PRODUCTION_READY";
+    if (overall >= 60)
+        return "NEEDS_WORK";
+    if (overall >= 40)
+        return "SIGNIFICANT_GAPS";
+    return "NOT_IMPLEMENTED";
+}

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

@@ -10,7 +10,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join, dirname, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { getHomeDir } from "./home-dir.js";
+import { gsdHome } from "./gsd-home.js";
 import { extractTrace } from "./session-forensics.js";
 import { nativeParseJsonlTail } from "./native-parser-bridge.js";
 import { MAX_JSONL_BYTES, parseJSONL } from "./jsonl-utils.js";
@@ -30,6 +30,7 @@ import { loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPref
 import { showNextAction } from "../shared/tui.js";
 import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
 import { summarizeWorktreeTelemetry, percentile } from "./worktree-telemetry.js";
+import { homedir } from "node:os";
 // ─── Duplicate Detection ──────────────────────────────────────────────────────
 const DEDUP_PROMPT_SECTION = `
 ## Pre-Investigation: Duplicate Check (REQUIRED)
@@ -135,8 +136,7 @@ export async function handleForensics(args, ctx, pi) {
     // when import.meta.url resolves to the npm-global install path (Windows).
     let gsdSourceDir = dirname(fileURLToPath(import.meta.url));
     if (!existsSync(join(gsdSourceDir, "prompts"))) {
-        const gsdHome = process.env.GSD_HOME || join(getHomeDir(), ".gsd");
-        const fallback = join(gsdHome, "agent", "extensions", "gsd");
+        const fallback = join(gsdHome(), "agent", "extensions", "gsd");
         if (existsSync(join(fallback, "prompts")))
             gsdSourceDir = fallback;
     }
@@ -1115,7 +1115,13 @@ function redactForGitHub(text, basePath) {
     const pathRe = (p) => new RegExp(esc(p.replace(/\\/g, "/")).replace(/\//g, "[/\\\\]"), "gi");
     // Replace absolute paths
     result = result.replace(pathRe(basePath), ".");
-    result = result.replace(pathRe(getHomeDir()), "~");
+    // Redact GSD_HOME first (when it's outside ~), then OS home.
+    // Order matters: longer path must be replaced before the shorter prefix.
+    const gsdHomePath = gsdHome();
+    if (!gsdHomePath.startsWith(homedir())) {
+        result = result.replace(pathRe(gsdHomePath), "~/.gsd");
+    }
+    result = result.replace(pathRe(homedir()), "~");
     // Strip API key patterns
     result = result.replace(/sk-[a-zA-Z0-9]{20,}/g, "sk-***");
     result = result.replace(/Bearer\s+\S+/g, "Bearer ***");