gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.42ef05fbe

package/src/resources/extensions/gsd/detection.ts

@@ -10,8 +10,8 @@ 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";
+import { gsdHome } from "./gsd-home.js";
 
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 
 // ─── Types ──────────────────────────────────────────────────────────────────────
 
@@ -720,8 +720,8 @@ function detectVerificationCommands(
  */
 export function hasGlobalSetup(): boolean {
   return (
-    existsSync(join(gsdHome, "PREFERENCES.md")) ||
-    existsSync(join(gsdHome, "preferences.md"))
+    existsSync(join(gsdHome(), "PREFERENCES.md")) ||
+    existsSync(join(gsdHome(), "preferences.md"))
   );
 }
 
@@ -730,18 +730,18 @@ export function hasGlobalSetup(): boolean {
  * Returns true if ~/.gsd/ doesn't exist or has no preferences or auth.
  */
 export function isFirstEverLaunch(): boolean {
-  if (!existsSync(gsdHome)) return true;
+  if (!existsSync(gsdHome())) return true;
 
   // If we have preferences, not first launch
   if (
-    existsSync(join(gsdHome, "PREFERENCES.md")) ||
-    existsSync(join(gsdHome, "preferences.md"))
+    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"))) return false;
+  if (existsSync(join(gsdHome(), "agent", "auth.json"))) return false;
 
   // Check legacy path too
   const legacyPath = join(homedir(), ".pi", "agent", "gsd-preferences.md");

package/src/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 `.gsd/PREFERENCES.md`. 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/src/resources/extensions/gsd/doctor-providers.ts

@@ -17,7 +17,7 @@ import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getAuthPath, PROVIDER_REGISTRY, type ProviderCategory } from "./key-manager.js";
-import { getHomeDir } from "./home-dir.js";
+import { homedir } from "node:os";
 
 // ── Types ──────────────────────────────────────────────────────────────────────
 
@@ -195,7 +195,7 @@ function isCliBinaryInPath(providerId: string): boolean {
 }
 
 function modelsJsonPaths(): string[] {
-  const home = getHomeDir();
+  const home = homedir();
   return [
     join(home, ".gsd", "agent", "models.json"),
     // Keep parity with custom-provider discovery during auto bootstrap.

package/src/resources/extensions/gsd/eval-review-schema.ts

@@ -0,0 +1,243 @@
+/**
+ * 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, type Static, type TSchema } 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" as const;
+
+/** Verdict values, ordered from worst to best for UI display purposes. */
+export const VERDICT_VALUES = [
+  "NOT_IMPLEMENTED",
+  "SIGNIFICANT_GAPS",
+  "NEEDS_WORK",
+  "PRODUCTION_READY",
+] as const;
+
+/** Severity classifications used in `gaps[*].severity`. */
+export const SEVERITY_VALUES = ["blocker", "major", "minor"] as const;
+
+/** Eval dimensions an auditor scores. `other` is the catch-all. */
+export const DIMENSION_VALUES = [
+  "observability",
+  "guardrails",
+  "tests",
+  "metrics",
+  "datasets",
+  "other",
+] as const;
+
+/** 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,
+});
+
+/** Inferred TypeScript type for a validated frontmatter object. */
+export type EvalReviewFrontmatterT = Static<typeof EvalReviewFrontmatter>;
+/** Inferred TypeScript type for a single gap finding. */
+export type EvalReviewGapT = Static<typeof EvalReviewGap>;
+/** Inferred TypeScript type for the counts histogram. */
+export type EvalReviewCountsT = Static<typeof EvalReviewCounts>;
+/** One of the four allowed verdict literals. */
+export type Verdict = (typeof VERDICT_VALUES)[number];
+
+// ─── 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: string,
+): { yaml: string } | { error: string } {
+  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" };
+}
+
+// ─── Parser ───────────────────────────────────────────────────────────────────
+
+/** Discriminated result type returned by the parser. */
+export type ParseResult =
+  | { ok: true; data: EvalReviewFrontmatterT }
+  | { ok: false; error: string; pointer: string };
+
+/**
+ * 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: string): ParseResult {
+  const fm = extractFrontmatterRaw(raw);
+  if ("error" in fm) {
+    return { ok: false, error: fm.error, pointer: "/" };
+  }
+
+  let parsed: unknown;
+  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: TSchema = 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 as EvalReviewFrontmatterT };
+}
+
+// ─── 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: number, infrastructure: number): number {
+  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: readonly EvalReviewGapT[]): EvalReviewCountsT {
+  const counts: EvalReviewCountsT = { 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: number): Verdict {
+  if (overall >= 80) return "PRODUCTION_READY";
+  if (overall >= 60) return "NEEDS_WORK";
+  if (overall >= 40) return "SIGNIFICANT_GAPS";
+  return "NOT_IMPLEMENTED";
+}

package/src/resources/extensions/gsd/forensics.ts

@@ -12,7 +12,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 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, type ExecutionTrace } from "./session-forensics.js";
 import { nativeParseJsonlTail } from "./native-parser-bridge.js";
@@ -36,6 +36,7 @@ import { loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPref
 import { showNextAction } from "../shared/tui.js";
 import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
 import { summarizeWorktreeTelemetry, percentile, type WorktreeTelemetrySummary } from "./worktree-telemetry.js";
+import { homedir } from "node:os";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -244,8 +245,7 @@ export async function handleForensics(
   // 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;
   }
 
@@ -1307,7 +1307,13 @@ function redactForGitHub(text: string, basePath: string): string {
 
   // 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-***");

package/src/resources/extensions/gsd/gsd-db.ts

@@ -33,6 +33,7 @@ import { logError, logWarning } from "./workflow-logger.js";
 import type { StateManifest } from "./workflow-manifest.js";
 
 const _require = createRequire(import.meta.url);
+const BETTER_SQLITE3_PACKAGE = ["better", "sqlite3"].join("-");
 
 interface DbStatement {
   run(...params: unknown[]): unknown;
@@ -89,7 +90,7 @@ function loadProvider(): void {
   }
 
   try {
-    const mod = _require("better-sqlite3");
+    const mod = _require(BETTER_SQLITE3_PACKAGE);
     if (typeof mod === "function" || (mod && mod.default)) {
       providerModule = mod.default || mod;
       providerName = "better-sqlite3";
@@ -1303,7 +1304,7 @@ export function openDatabase(path: string): boolean {
     // node:sqlite loaded but failed to open this file — try better-sqlite3 as fallback.
     if (providerName === "node:sqlite") {
       try {
-        const mod = _require("better-sqlite3");
+        const mod = _require(BETTER_SQLITE3_PACKAGE);
         const Db = (mod && mod.default) ? mod.default : mod;
         if (typeof Db === "function") {
           rawDb = new Db(path);

package/src/resources/extensions/gsd/gsd-home.ts

@@ -0,0 +1,30 @@
+/**
+ * GSD home directory resolution.
+ *
+ * Exports gsdHome() which returns the GSD configuration directory,
+ * defaulting to ~/.gsd with a GSD_HOME env var override.
+ *
+ * For the user's home directory, use os.homedir() directly — it handles
+ * platform-specific env lookup (USERPROFILE on Windows, HOME on POSIX)
+ * with appropriate fallbacks.
+ *
+ * @see https://github.com/gsd-build/gsd-2/issues/5015
+ */
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+/**
+ * Resolve the GSD home directory (typically ~/.gsd).
+ *
+ * `GSD_HOME` env var overrides the default location.
+ * Falls back to `homedir()/.gsd`.
+ *
+ * Always returns an absolute, normalized path — `resolve()` canonicalizes
+ * any relative or non-canonical `GSD_HOME` value so downstream comparison
+ * and redaction sites don't have to.
+ */
+export function gsdHome(): string {
+  return process.env.GSD_HOME
+    ? resolve(process.env.GSD_HOME)
+    : join(homedir(), ".gsd");
+}