gsd-pi 2.28.0-dev.4009980 → 2.28.0-dev.704ded6

package/dist/resources/extensions/gsd/tests/verification-gate.test.ts

@@ -581,7 +581,7 @@ test("formatFailureContext: formats a single failure with command, exit code, st
   const result: import("../types.ts").VerificationResult = {
     passed: false,
     checks: [
-      { command: "npm run lint", exitCode: 1, stdout: "", stderr: "error: unused var", durationMs: 500 },
+      { command: "npm run lint", exitCode: 1, stdout: "", stderr: "error: unused var", durationMs: 500, blocking: true },
     ],
     discoverySource: "preference",
     timestamp: Date.now(),
@@ -598,9 +598,9 @@ test("formatFailureContext: formats multiple failures", () => {
   const result: import("../types.ts").VerificationResult = {
     passed: false,
     checks: [
-      { command: "npm run lint", exitCode: 1, stdout: "", stderr: "lint error", durationMs: 100 },
-      { command: "npm run test", exitCode: 2, stdout: "", stderr: "test failure", durationMs: 200 },
-      { command: "npm run typecheck", exitCode: 0, stdout: "ok", stderr: "", durationMs: 50 },
+      { command: "npm run lint", exitCode: 1, stdout: "", stderr: "lint error", durationMs: 100, blocking: true },
+      { command: "npm run test", exitCode: 2, stdout: "", stderr: "test failure", durationMs: 200, blocking: true },
+      { command: "npm run typecheck", exitCode: 0, stdout: "ok", stderr: "", durationMs: 50, blocking: true },
     ],
     discoverySource: "preference",
     timestamp: Date.now(),
@@ -619,7 +619,7 @@ test("formatFailureContext: truncates stderr longer than 2000 chars", () => {
   const result: import("../types.ts").VerificationResult = {
     passed: false,
     checks: [
-      { command: "big-err", exitCode: 1, stdout: "", stderr: longStderr, durationMs: 100 },
+      { command: "big-err", exitCode: 1, stdout: "", stderr: longStderr, durationMs: 100, blocking: true },
     ],
     discoverySource: "preference",
     timestamp: Date.now(),
@@ -634,8 +634,8 @@ test("formatFailureContext: returns empty string when all checks pass", () => {
   const result: import("../types.ts").VerificationResult = {
     passed: true,
     checks: [
-      { command: "npm run lint", exitCode: 0, stdout: "ok", stderr: "", durationMs: 100 },
-      { command: "npm run test", exitCode: 0, stdout: "ok", stderr: "", durationMs: 200 },
+      { command: "npm run lint", exitCode: 0, stdout: "ok", stderr: "", durationMs: 100, blocking: true },
+      { command: "npm run test", exitCode: 0, stdout: "ok", stderr: "", durationMs: 200, blocking: true },
     ],
     discoverySource: "preference",
     timestamp: Date.now(),
@@ -663,6 +663,7 @@ test("formatFailureContext: caps total output at 10,000 chars", () => {
       stdout: "",
       stderr: "e".repeat(1000), // 1000 chars each, 20 * ~1050 (with formatting) > 10,000
       durationMs: 100,
+      blocking: true,
     });
   }
   const result: import("../types.ts").VerificationResult = {
@@ -1077,3 +1078,131 @@ test("dependency-audit: subdirectory package.json does not trigger audit", () =>
   assert.equal(npmAuditCalled, false, "subdirectory dependency files should not trigger audit");
   assert.deepStrictEqual(result, []);
 });
+
+// ─── Non-Blocking Discovery Tests ────────────────────────────────────────────
+
+test("non-blocking: package-json discovered commands failing → result.passed is still true", () => {
+  const tmp = makeTempDir("vg-nb-pkg-fail");
+  try {
+    writeFileSync(
+      join(tmp, "package.json"),
+      JSON.stringify({ scripts: { lint: "eslint .", test: "vitest" } }),
+    );
+    // These commands will fail because eslint/vitest don't exist in the temp dir
+    const result = runVerificationGate({
+      basePath: tmp,
+      unitId: "T01",
+      cwd: tmp,
+      // No preference commands — discovery falls through to package.json
+    });
+    assert.equal(result.discoverySource, "package-json");
+    assert.ok(result.checks.length > 0, "should have discovered package.json checks");
+    assert.equal(result.passed, true, "package-json failures should not block the gate");
+    for (const check of result.checks) {
+      assert.equal(check.blocking, false, "package-json checks should be non-blocking");
+    }
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("non-blocking: preference commands failing → result.passed is false", () => {
+  const tmp = makeTempDir("vg-nb-pref-fail");
+  try {
+    const result = runVerificationGate({
+      basePath: tmp,
+      unitId: "T01",
+      cwd: tmp,
+      preferenceCommands: ["sh -c 'exit 1'"],
+    });
+    assert.equal(result.discoverySource, "preference");
+    assert.equal(result.passed, false, "preference failures should block the gate");
+    assert.equal(result.checks[0].blocking, true, "preference checks should be blocking");
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("non-blocking: task-plan commands failing → result.passed is false", () => {
+  const tmp = makeTempDir("vg-nb-tp-fail");
+  try {
+    const result = runVerificationGate({
+      basePath: tmp,
+      unitId: "T01",
+      cwd: tmp,
+      taskPlanVerify: "sh -c 'exit 1'",
+    });
+    assert.equal(result.discoverySource, "task-plan");
+    assert.equal(result.passed, false, "task-plan failures should block the gate");
+    assert.equal(result.checks[0].blocking, true, "task-plan checks should be blocking");
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("non-blocking: blocking field is set correctly based on discovery source", () => {
+  const tmp = makeTempDir("vg-nb-field");
+  try {
+    // preference → blocking
+    const prefResult = runVerificationGate({
+      basePath: tmp,
+      unitId: "T01",
+      cwd: tmp,
+      preferenceCommands: ["echo ok"],
+    });
+    assert.equal(prefResult.checks[0].blocking, true);
+
+    // task-plan → blocking
+    const tpResult = runVerificationGate({
+      basePath: tmp,
+      unitId: "T01",
+      cwd: tmp,
+      taskPlanVerify: "echo ok",
+    });
+    assert.equal(tpResult.checks[0].blocking, true);
+
+    // package-json → non-blocking
+    writeFileSync(
+      join(tmp, "package.json"),
+      JSON.stringify({ scripts: { test: "echo ok" } }),
+    );
+    const pkgResult = runVerificationGate({
+      basePath: tmp,
+      unitId: "T01",
+      cwd: tmp,
+    });
+    assert.equal(pkgResult.checks[0].blocking, false);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("non-blocking: formatFailureContext only includes blocking failures", () => {
+  const result: import("../types.ts").VerificationResult = {
+    passed: true,
+    checks: [
+      { command: "npm run lint", exitCode: 1, stdout: "", stderr: "lint warning", durationMs: 100, blocking: false },
+      { command: "npm run test", exitCode: 1, stdout: "", stderr: "test error", durationMs: 200, blocking: true },
+      { command: "npm run typecheck", exitCode: 1, stdout: "", stderr: "type error", durationMs: 50, blocking: false },
+    ],
+    discoverySource: "preference",
+    timestamp: Date.now(),
+  };
+  const output = formatFailureContext(result);
+  assert.ok(output.includes("`npm run test`"), "should include blocking failure");
+  assert.ok(!output.includes("npm run lint"), "should not include non-blocking failure");
+  assert.ok(!output.includes("npm run typecheck"), "should not include non-blocking failure");
+});
+
+test("non-blocking: formatFailureContext returns empty when only non-blocking failures exist", () => {
+  const result: import("../types.ts").VerificationResult = {
+    passed: true,
+    checks: [
+      { command: "npm run lint", exitCode: 1, stdout: "", stderr: "lint warning", durationMs: 100, blocking: false },
+      { command: "npm run test", exitCode: 1, stdout: "", stderr: "test warning", durationMs: 200, blocking: false },
+    ],
+    discoverySource: "package-json",
+    timestamp: Date.now(),
+  };
+  assert.equal(formatFailureContext(result), "", "should return empty when only non-blocking failures");
+});

package/dist/resources/extensions/gsd/types.ts

@@ -55,6 +55,7 @@ export interface VerificationCheck {
   stdout: string;
   stderr: string;
   durationMs: number;
+  blocking: boolean;     // true for preference/task-plan sources, false for package-json (advisory only)
 }
 
 /** A runtime error captured from bg-shell processes or browser console */

package/dist/resources/extensions/gsd/verification-evidence.ts

@@ -20,6 +20,7 @@ export interface EvidenceCheckJSON {
   exitCode: number;
   durationMs: number;
   verdict: "pass" | "fail";
+  blocking: boolean;
 }
 
 export interface RuntimeErrorJSON {
@@ -80,6 +81,7 @@ export function writeVerificationJSON(
       exitCode: check.exitCode,
       durationMs: check.durationMs,
       verdict: check.exitCode === 0 ? "pass" : "fail",
+      blocking: check.blocking,
     })),
     ...(retryAttempt !== undefined ? { retryAttempt } : {}),
     ...(maxRetries !== undefined ? { maxRetries } : {}),

package/dist/resources/extensions/gsd/verification-gate.ts

@@ -112,7 +112,9 @@ const MAX_FAILURE_CONTEXT_CHARS = 10_000;
  * Returns an empty string when all checks pass or the checks array is empty.
  */
 export function formatFailureContext(result: VerificationResult): string {
-  const failures = result.checks.filter((c) => c.exitCode !== 0);
+  // Only include blocking failures in retry context — non-blocking (advisory) failures
+  // should not be injected into retry prompts to avoid noise pollution.
+  const failures = result.checks.filter((c) => c.exitCode !== 0 && c.blocking);
   if (failures.length === 0) return "";
 
   const blocks: string[] = [];
@@ -256,6 +258,10 @@ export function runVerificationGate(options: RunVerificationGateOptions): Verifi
     };
   }
 
+  // Commands from preference and task-plan sources are blocking;
+  // package-json discovered commands are advisory (non-blocking).
+  const blocking = source === "preference" || source === "task-plan";
+
   const checks: VerificationCheck[] = [];
 
   for (const command of commands) {
@@ -291,11 +297,16 @@ export function runVerificationGate(options: RunVerificationGateOptions): Verifi
       stdout: truncate(result.stdout, MAX_OUTPUT_BYTES),
       stderr,
       durationMs,
+      blocking,
     });
   }
 
+  // Gate passes if all blocking checks pass (non-blocking failures are advisory)
+  const blockingChecks = checks.filter(c => c.blocking);
+  const passed = blockingChecks.length === 0 || blockingChecks.every(c => c.exitCode === 0);
+
   return {
-    passed: checks.every(c => c.exitCode === 0),
+    passed,
     checks,
     discoverySource: source,
     timestamp,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-pi",
-  "version": "2.28.0-dev.4009980",
+  "version": "2.28.0-dev.704ded6",
   "description": "GSD — Get Shit Done coding agent",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "configDir": ".gsd"
   },
   "engines": {
-    "node": ">=20.6.0"
+    "node": ">=22.0.0"
   },
   "packageManager": "npm@10.9.3",
   "scripts": {
@@ -117,7 +117,7 @@
     "zod-to-json-schema": "^3.24.6"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^24.12.0",
     "@types/picomatch": "^4.0.2",
     "c8": "^11.0.0",
     "jiti": "^2.6.1",

package/packages/pi-coding-agent/scripts/copy-assets.cjs

@@ -1,24 +1,55 @@
 #!/usr/bin/env node
-const { mkdirSync, cpSync } = require('fs');
+const { mkdirSync, cpSync, copyFileSync, readdirSync } = require('fs');
+const { join } = require('path');
+
+/**
+ * Recursive directory copy using copyFileSync — workaround for cpSync failures
+ * on Windows paths containing non-ASCII characters (#1178).
+ */
+function safeCpSync(src, dest, options) {
+  try {
+    cpSync(src, dest, options);
+  } catch {
+    if (options && options.recursive) {
+      copyDirRecursive(src, dest, options && options.filter);
+    } else {
+      copyFileSync(src, dest);
+    }
+  }
+}
+
+function copyDirRecursive(src, dest, filter) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (filter && !filter(srcPath)) continue;
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath, filter);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
 
 // Theme assets
 mkdirSync('dist/modes/interactive/theme', { recursive: true });
-cpSync('src/modes/interactive/theme', 'dist/modes/interactive/theme', {
+safeCpSync('src/modes/interactive/theme', 'dist/modes/interactive/theme', {
   recursive: true,
   filter: (s) => !s.endsWith('.ts'),
 });
 
 // Export HTML templates and vendor files
 mkdirSync('dist/core/export-html/vendor', { recursive: true });
-cpSync('src/core/export-html/template.html', 'dist/core/export-html/template.html');
-cpSync('src/core/export-html/template.css', 'dist/core/export-html/template.css');
-cpSync('src/core/export-html/template.js', 'dist/core/export-html/template.js');
-cpSync('src/core/export-html/vendor', 'dist/core/export-html/vendor', {
+safeCpSync('src/core/export-html/template.html', 'dist/core/export-html/template.html');
+safeCpSync('src/core/export-html/template.css', 'dist/core/export-html/template.css');
+safeCpSync('src/core/export-html/template.js', 'dist/core/export-html/template.js');
+safeCpSync('src/core/export-html/vendor', 'dist/core/export-html/vendor', {
   recursive: true,
   filter: (s) => !s.endsWith('.ts'),
 });
 
 // LSP defaults
 mkdirSync('dist/core/lsp', { recursive: true });
-cpSync('src/core/lsp/defaults.json', 'dist/core/lsp/defaults.json');
-cpSync('src/core/lsp/lsp.md', 'dist/core/lsp/lsp.md');
+safeCpSync('src/core/lsp/defaults.json', 'dist/core/lsp/defaults.json');
+safeCpSync('src/core/lsp/lsp.md', 'dist/core/lsp/lsp.md');

package/src/resources/extensions/gsd/auto-recovery.ts

@@ -36,6 +36,7 @@ import {
   clearPathCache,
   resolveGsdRootFile,
 } from "./paths.js";
+import { isValidationTerminal } from "./state.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { dirname, join } from "node:path";
@@ -137,6 +138,21 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
   if (!absPath) return false;
   if (!existsSync(absPath)) return false;
 
+  // validate-milestone must have a VALIDATION file with a terminal verdict
+  // (pass, needs-attention, or needs-remediation). Without this check, a
+  // VALIDATION file with missing/malformed frontmatter or an unrecognized
+  // verdict is treated as "complete" by the artifact check but deriveState
+  // still returns phase:"validating-milestone" (because isValidationTerminal
+  // returns false), creating an infinite skip loop that hits the lifetime cap.
+  if (unitType === "validate-milestone") {
+    try {
+      const validationContent = readFileSync(absPath, "utf-8");
+      if (!isValidationTerminal(validationContent)) return false;
+    } catch {
+      return false;
+    }
+  }
+
   // plan-slice must produce a plan with actual task entries, not just a scaffold.
   // The plan file may exist from a prior discussion/context step with only headings
   // but no tasks. Without this check the artifact is considered "complete" and the
@@ -211,7 +227,7 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
         try {
           const roadmapContent = readFileSync(roadmapFile, "utf-8");
           const roadmap = parseRoadmap(roadmapContent);
-          const slice = roadmap.slices.find(s => s.id === sid);
+          const slice = (roadmap.slices ?? []).find(s => s.id === sid);
           if (slice && !slice.done) return false;
         } catch {
           // Corrupt/unparseable roadmap — fail verification so the unit

package/src/resources/extensions/gsd/auto-start.ts

@@ -415,7 +415,7 @@ export async function bootstrapAutoSession(
   ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
   ctx.ui.setFooter(hideFooter);
   const modeLabel = s.stepMode ? "Step-mode" : "Auto-mode";
-  const pendingCount = state.registry.filter(m => m.status !== 'complete' && m.status !== 'parked').length;
+  const pendingCount = (state.registry ?? []).filter(m => m.status !== 'complete' && m.status !== 'parked').length;
   const scopeMsg = pendingCount > 1
     ? `Will loop through ${pendingCount} milestones.`
     : "Will loop until milestone complete.";

package/src/resources/extensions/gsd/auto-verification.ts

@@ -105,19 +105,39 @@ export async function runPostUnitVerification(
     const completionKey = `${s.currentUnit.type}/${s.currentUnit.id}`;
 
     if (result.checks.length > 0) {
-      const passCount = result.checks.filter(c => c.exitCode === 0).length;
-      const total = result.checks.length;
+      const blockingChecks = result.checks.filter(c => c.blocking);
+      const advisoryChecks = result.checks.filter(c => !c.blocking);
+      const blockingPassCount = blockingChecks.filter(c => c.exitCode === 0).length;
+      const advisoryFailCount = advisoryChecks.filter(c => c.exitCode !== 0).length;
+
       if (result.passed) {
-        ctx.ui.notify(`Verification gate: ${passCount}/${total} checks passed`);
+        let msg = blockingChecks.length > 0
+          ? `Verification gate: ${blockingPassCount}/${blockingChecks.length} blocking checks passed`
+          : `Verification gate: passed (no blocking checks)`;
+        if (advisoryFailCount > 0) {
+          msg += ` (${advisoryFailCount} advisory warning${advisoryFailCount > 1 ? "s" : ""})`;
+        }
+        ctx.ui.notify(msg);
+        // Log advisory warnings to stderr for visibility
+        if (advisoryFailCount > 0) {
+          const advisoryFailures = advisoryChecks.filter(c => c.exitCode !== 0);
+          process.stderr.write(`verification-gate: ${advisoryFailCount} advisory (non-blocking) failure(s)\n`);
+          for (const f of advisoryFailures) {
+            process.stderr.write(`  [advisory] ${f.command} exited ${f.exitCode}\n`);
+          }
+        }
       } else {
-        const failures = result.checks.filter(c => c.exitCode !== 0);
-        const failNames = failures.map(f => f.command).join(", ");
+        const blockingFailures = blockingChecks.filter(c => c.exitCode !== 0);
+        const failNames = blockingFailures.map(f => f.command).join(", ");
         ctx.ui.notify(`Verification gate: FAILED — ${failNames}`);
-        process.stderr.write(`verification-gate: ${total - passCount}/${total} checks failed\n`);
-        for (const f of failures) {
+        process.stderr.write(`verification-gate: ${blockingFailures.length}/${blockingChecks.length} blocking checks failed\n`);
+        for (const f of blockingFailures) {
           process.stderr.write(`  ${f.command} exited ${f.exitCode}\n`);
           if (f.stderr) process.stderr.write(`  stderr: ${f.stderr.slice(0, 500)}\n`);
         }
+        if (advisoryFailCount > 0) {
+          process.stderr.write(`verification-gate: ${advisoryFailCount} additional advisory (non-blocking) failure(s)\n`);
+        }
       }
     }
 

package/src/resources/extensions/gsd/auto-worktree-sync.ts

@@ -36,6 +36,12 @@ export function syncProjectRootToWorktree(projectRoot: string, worktreePath: str
   // has newer artifacts (e.g. slices that don't exist in the worktree yet)
   safeCopyRecursive(join(prGsd, "milestones", milestoneId), join(wtGsd, "milestones", milestoneId))
 
+  // Copy living documents from project root to worktree so agents have the
+  // latest decisions, requirements, project state, and knowledge.
+  for (const doc of ["DECISIONS.md", "REQUIREMENTS.md", "PROJECT.md", "KNOWLEDGE.md"]) {
+    safeCopy(join(prGsd, doc), join(wtGsd, doc), { force: true });
+  }
+
   // Delete worktree gsd.db so it rebuilds from the freshly synced files.
   // Stale DB rows are the root cause of the infinite skip loop (#853).
   try {
@@ -89,6 +95,14 @@ export function syncStateToProjectRoot(worktreePath: string, projectRoot: string
   // worktree. If the next session resolves basePath before worktree re-entry,
   // selfHeal can't find or clear the stale record (#769).
   safeCopyRecursive(join(wtGsd, "runtime", "units"), join(prGsd, "runtime", "units"), { force: true })
+
+  // 5. Living documents — decisions, requirements, project description, knowledge.
+  // Agents update these during slice execution. Without syncing, a new session
+  // reads stale copies from the project root, losing architectural decisions,
+  // requirement status updates, and accumulated knowledge (#1168).
+  for (const doc of ["DECISIONS.md", "REQUIREMENTS.md", "PROJECT.md", "KNOWLEDGE.md"]) {
+    safeCopy(join(wtGsd, doc), join(prGsd, doc), { force: true });
+  }
 }
 
 // ─── Resource Staleness ───────────────────────────────────────────────────

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

@@ -877,7 +877,7 @@ async function showStepWizard(
     : "previous unit";
 
   if (!mid || state.phase === "complete") {
-    const incomplete = state.registry.filter(m => m.status !== "complete" && m.status !== "parked");
+    const incomplete = (state.registry ?? []).filter(m => m.status !== "complete" && m.status !== "parked");
     if (incomplete.length > 0 && state.phase !== "complete" && state.phase !== "blocked" && state.phase !== "pre-planning") {
       const ids = incomplete.map(m => m.id).join(", ");
       const diag = `basePath=${s.basePath}, milestones=[${state.registry.map(m => `${m.id}:${m.status}`).join(", ")}], phase=${state.phase}`;
@@ -1171,7 +1171,7 @@ async function dispatchNextUnit(
       }
     }
 
-    const pendingIds = state.registry
+    const pendingIds = (state.registry ?? [])
       .filter(m => m.status !== "complete")
       .map(m => m.id);
     pruneQueueOrder(s.basePath, pendingIds);
@@ -1186,7 +1186,7 @@ async function dispatchNextUnit(
       await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
     }
 
-    const incomplete = state.registry.filter(m => m.status !== "complete" && m.status !== "parked");
+    const incomplete = (state.registry ?? []).filter(m => m.status !== "complete" && m.status !== "parked");
     if (incomplete.length === 0) {
       // Genuinely all complete (parked milestones excluded) — merge milestone branch to main before stopping (#962)
       if (s.currentMilestoneId && isInAutoWorktree(s.basePath) && s.originalBasePath) {
@@ -1439,6 +1439,23 @@ async function dispatchNextUnit(
 
   await runSecretsGate();
 
+  // ── Interactive discussion gate ──
+  // If the active milestone needs discussion (has CONTEXT-DRAFT.md but no roadmap),
+  // stop auto-mode and route to the interactive discussion flow. The guided-flow
+  // handles needs-discussion correctly — it just needs to be called instead of
+  // letting the dispatch table fire "needs-discussion → stop" (#1170).
+  if (state.phase === "needs-discussion") {
+    if (s.currentUnit) {
+      await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+    }
+    const cmdCtx = s.cmdCtx!;
+    const basePath = s.basePath;
+    await stopAuto(ctx, pi, `${mid}: ${midTitle} needs discussion before planning.`);
+    const { showSmartEntry } = await import("./guided-flow.js");
+    await showSmartEntry(cmdCtx, pi, basePath);
+    return;
+  }
+
   // ── Dispatch table ──
   const dispatchResult = await resolveDispatch({ basePath: s.basePath, mid, midTitle: midTitle!, state, prefs,
   });

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

@@ -4,6 +4,7 @@
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { writeFileSync, mkdirSync } from "node:fs";
 import { join, basename } from "node:path";
+import { exec } from "node:child_process";
 import {
   getLedger, getProjectTotals, aggregateByPhase, aggregateBySlice,
   aggregateByModel, formatCost, formatTokenCount, loadLedgerFromDisk,
@@ -12,6 +13,28 @@ import type { UnitMetrics } from "./metrics.js";
 import { gsdRoot } from "./paths.js";
 import { formatDuration, fileLink } from "../shared/mod.js";
 
+/**
+ * Open a file in the user's default browser.
+ * Uses platform-specific commands: `open` (macOS), `xdg-open` (Linux), `start` (Windows).
+ * Non-blocking, non-fatal — failures are silently ignored.
+ */
+export function openInBrowser(filePath: string): void {
+  const cmd =
+    process.platform === "darwin" ? "open" :
+    process.platform === "win32" ? "start" :
+    "xdg-open";
+
+  // On Windows, `start` needs an empty title argument when the path has spaces
+  const args = process.platform === "win32"
+    ? `"" "${filePath}"`
+    : `"${filePath}"`;
+
+  exec(`${cmd} ${args}`, (err) => {
+    // Non-fatal — if the browser can't be opened, the file path is still shown
+    if (err) void err;
+  });
+}
+
 /**
  * Write an export file directly, without requiring an ExtensionCommandContext.
  * Used by the visualizer overlay export tab.
@@ -167,10 +190,12 @@ export async function handleExport(args: string, ctx: ExtensionCommandContext, b
           paths.push(bn(outPath));
         }
 
+        const indexPath = join(gsdRoot(basePath), "reports", "index.html");
         ctx.ui.notify(
-          `Generated ${paths.length} report snapshot${paths.length !== 1 ? "s" : ""}:\n${paths.map(p => `  ${p}`).join("\n")}\nBrowse all reports: .gsd/reports/index.html`,
+          `Generated ${paths.length} report snapshot${paths.length !== 1 ? "s" : ""}:\n${paths.map(p => `  ${p}`).join("\n")}\nOpening reports index in browser...`,
           "success",
         );
+        openInBrowser(indexPath);
       } else {
         // Single report for the active milestone (existing behavior)
         const doneSlices = data.milestones.reduce((s, m) => s + m.slices.filter(sl => sl.done).length, 0);
@@ -194,9 +219,10 @@ export async function handleExport(args: string, ctx: ExtensionCommandContext, b
           phase: data.phase,
         });
         ctx.ui.notify(
-          `HTML report saved: .gsd/reports/${bn(outPath)}\nBrowse all reports: .gsd/reports/index.html`,
+          `HTML report saved: .gsd/reports/${bn(outPath)}\nOpening in browser...`,
           "success",
         );
+        openInBrowser(outPath);
       }
     } catch (err) {
       ctx.ui.notify(

package/src/resources/extensions/gsd/tests/validate-milestone.test.ts

@@ -290,6 +290,61 @@ test("verifyExpectedArtifact fails when VALIDATION.md is missing", () => {
   }
 });
 
+test("verifyExpectedArtifact rejects VALIDATION with missing frontmatter", () => {
+  const base = makeTmpBase();
+  try {
+    // A VALIDATION file without frontmatter should be treated as incomplete —
+    // matching what deriveState expects. Without this, the artifact check passes
+    // but deriveState still returns validating-milestone, causing the hard skip loop.
+    writeValidation(base, "M001", "# Validation\nNo frontmatter here.");
+    clearPathCache();
+    clearParseCache();
+    const result = verifyExpectedArtifact("validate-milestone", "M001", base);
+    assert.equal(result, false, "VALIDATION without frontmatter should fail verification");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("verifyExpectedArtifact rejects VALIDATION with missing verdict field", () => {
+  const base = makeTmpBase();
+  try {
+    writeValidation(base, "M001", "---\nremediation_round: 0\n---\n\n# Validation");
+    clearPathCache();
+    clearParseCache();
+    const result = verifyExpectedArtifact("validate-milestone", "M001", base);
+    assert.equal(result, false, "VALIDATION without verdict field should fail verification");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("verifyExpectedArtifact rejects VALIDATION with unrecognized verdict", () => {
+  const base = makeTmpBase();
+  try {
+    writeValidation(base, "M001", "---\nverdict: unknown-value\nremediation_round: 0\n---\n\n# Validation");
+    clearPathCache();
+    clearParseCache();
+    const result = verifyExpectedArtifact("validate-milestone", "M001", base);
+    assert.equal(result, false, "VALIDATION with unrecognized verdict should fail verification");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("verifyExpectedArtifact passes VALIDATION with needs-attention verdict", () => {
+  const base = makeTmpBase();
+  try {
+    writeValidation(base, "M001", "---\nverdict: needs-attention\nremediation_round: 0\n---\n\n# Validation\nNeeds attention.");
+    clearPathCache();
+    clearParseCache();
+    const result = verifyExpectedArtifact("validate-milestone", "M001", base);
+    assert.equal(result, true, "VALIDATION with needs-attention verdict should pass verification");
+  } finally {
+    cleanup(base);
+  }
+});
+
 // ─── diagnoseExpectedArtifact ─────────────────────────────────────────────
 
 test("diagnoseExpectedArtifact returns validation path for validate-milestone", () => {