gsd-pi 2.27.0 → 2.28.0-dev.1ba624e

package/src/resources/extensions/gsd/tests/write-gate.test.ts

@@ -1,19 +1,31 @@
 /**
- * Unit tests for the CONTEXT.md write-gate (D031 guard chain).
+ * Unit tests for the CONTEXT.md write-gate.
  *
  * Exercises shouldBlockContextWrite() — a pure function that implements:
  *   (a) toolName !== "write" → pass
- *   (b) milestoneId null → pass (not in discussion)
+ *   (b) milestoneId null AND no queue phase → pass (not in any flow)
  *   (c) path doesn't match /M\d+-CONTEXT\.md$/ → pass
- *   (d) depthVerified → pass
- *   (e) else → block with actionable reason
+ *   (d) depthVerified → pass (backward compat for discussion flows)
+ *   (e) queuePhaseActive + per-milestone verified → pass
+ *   (f) queuePhaseActive + not verified → block
+ *   (g) else → block with actionable reason
+ *
+ * Also exercises per-milestone verification helpers:
+ *   markDepthVerified(), isDepthVerifiedFor()
  */
 
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { shouldBlockContextWrite } from '../index.ts';
+import {
+  shouldBlockContextWrite,
+  markDepthVerified,
+  isDepthVerifiedFor,
+  isDepthVerified,
+} from '../index.ts';
 
-// ─── Scenario 1: Blocks CONTEXT.md write during discussion without depth verification (absolute path) ──
+// ═══════════════════════════════════════════════════════════════════════════
+// Discussion flow tests (backward compatibility)
+// ═══════════════════════════════════════════════════════════════════════════
 
 test('write-gate: blocks CONTEXT.md write during discussion without depth verification (absolute path)', () => {
   const result = shouldBlockContextWrite(
@@ -26,8 +38,6 @@ test('write-gate: blocks CONTEXT.md write during discussion without depth verifi
   assert.ok(result.reason, 'should provide a reason');
 });
 
-// ─── Scenario 2: Blocks CONTEXT.md write during discussion without depth verification (relative path) ──
-
 test('write-gate: blocks CONTEXT.md write during discussion without depth verification (relative path)', () => {
   const result = shouldBlockContextWrite(
     'write',
@@ -39,9 +49,7 @@ test('write-gate: blocks CONTEXT.md write during discussion without depth verifi
   assert.ok(result.reason, 'should provide a reason');
 });
 
-// ─── Scenario 3: Allows CONTEXT.md write after depth verification ──
-
-test('write-gate: allows CONTEXT.md write after depth verification', () => {
+test('write-gate: allows CONTEXT.md write after depth verification (discussion flow)', () => {
   const result = shouldBlockContextWrite(
     'write',
     '/Users/dev/project/.gsd/milestones/M001/M001-CONTEXT.md',
@@ -52,71 +60,152 @@ test('write-gate: allows CONTEXT.md write after depth verification', () => {
   assert.strictEqual(result.reason, undefined, 'should have no reason');
 });
 
-// ─── Scenario 4: Allows CONTEXT.md write outside discussion phase (milestoneId null) ──
-
-test('write-gate: allows CONTEXT.md write outside discussion phase', () => {
+test('write-gate: allows CONTEXT.md write outside any flow (milestoneId null, no queue)', () => {
   const result = shouldBlockContextWrite(
     'write',
     '.gsd/milestones/M001/M001-CONTEXT.md',
     null,
     false,
+    false,
   );
-  assert.strictEqual(result.block, false, 'should not block outside discussion phase');
+  assert.strictEqual(result.block, false, 'should not block outside any flow');
 });
 
-// ─── Scenario 5: Allows non-CONTEXT.md writes during discussion ──
-
 test('write-gate: allows non-CONTEXT.md writes during discussion', () => {
-  // DISCUSSION.md
-  const r1 = shouldBlockContextWrite(
+  const r1 = shouldBlockContextWrite('write', '.gsd/milestones/M001/M001-DISCUSSION.md', 'M001', false);
+  assert.strictEqual(r1.block, false, 'DISCUSSION.md should pass');
+
+  const r2 = shouldBlockContextWrite('write', '.gsd/milestones/M001/slices/S01/S01-PLAN.md', 'M001', false);
+  assert.strictEqual(r2.block, false, 'slice plan should pass');
+
+  const r3 = shouldBlockContextWrite('write', 'src/index.ts', 'M001', false);
+  assert.strictEqual(r3.block, false, 'regular code file should pass');
+});
+
+test('write-gate: regex does not match slice context files (S01-CONTEXT.md)', () => {
+  const result = shouldBlockContextWrite(
     'write',
-    '.gsd/milestones/M001/M001-DISCUSSION.md',
+    '.gsd/milestones/M001/slices/S01/S01-CONTEXT.md',
     'M001',
     false,
   );
-  assert.strictEqual(r1.block, false, 'DISCUSSION.md should pass');
+  assert.strictEqual(result.block, false, 'S01-CONTEXT.md should not be blocked');
+});
 
-  // Slice file
-  const r2 = shouldBlockContextWrite(
+test('write-gate: blocked reason contains actionable instructions', () => {
+  const result = shouldBlockContextWrite(
     'write',
-    '.gsd/milestones/M001/slices/S01/S01-PLAN.md',
-    'M001',
+    '.gsd/milestones/M999/M999-CONTEXT.md',
+    'M999',
     false,
   );
-  assert.strictEqual(r2.block, false, 'slice plan should pass');
+  assert.strictEqual(result.block, true);
+  assert.ok(result.reason!.includes('depth_verification'), 'reason should mention depth_verification');
+  assert.ok(result.reason!.includes('ask_user_questions'), 'reason should mention ask_user_questions');
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Queue flow tests (NEW — enforces write-gate during /gsd queue)
+// ═══════════════════════════════════════════════════════════════════════════
 
-  // Regular code file
-  const r3 = shouldBlockContextWrite(
+test('write-gate: blocks CONTEXT.md write during queue flow without verification', () => {
+  const result = shouldBlockContextWrite(
     'write',
-    'src/index.ts',
-    'M001',
+    '.gsd/milestones/M010-3ym37m/M010-3ym37m-CONTEXT.md',
+    null,  // queue flows have no pendingAutoStart → milestoneId is null
     false,
+    true,  // but queuePhaseActive is true
   );
-  assert.strictEqual(r3.block, false, 'regular code file should pass');
+  assert.strictEqual(result.block, true, 'should block during queue flow without verification');
+  assert.ok(result.reason!.includes('multi-milestone'), 'reason should mention multi-milestone');
 });
 
-// ─── Scenario 6: Regex specificity — doesn't match S01-CONTEXT.md ──
+test('write-gate: allows CONTEXT.md write during queue flow AFTER per-milestone verification', () => {
+  // Simulate: depth_verification_M010-3ym37m was answered
+  markDepthVerified('M010-3ym37m');
 
-test('write-gate: regex does not match slice context files (S01-CONTEXT.md)', () => {
   const result = shouldBlockContextWrite(
     'write',
-    '.gsd/milestones/M001/slices/S01/S01-CONTEXT.md',
-    'M001',
+    '.gsd/milestones/M010-3ym37m/M010-3ym37m-CONTEXT.md',
+    null,
     false,
+    true,
   );
-  assert.strictEqual(result.block, false, 'S01-CONTEXT.md should not be blocked');
+  assert.strictEqual(result.block, false, 'should allow after per-milestone verification');
+});
+
+test('write-gate: blocks DIFFERENT milestone in queue flow when only one is verified', () => {
+  // M010-3ym37m was verified above, but M011-rfmd3q was NOT
+  const result = shouldBlockContextWrite(
+    'write',
+    '.gsd/milestones/M011-rfmd3q/M011-rfmd3q-CONTEXT.md',
+    null,
+    false,
+    true,
+  );
+  assert.strictEqual(result.block, true, 'should block unverified milestone even when another is verified');
 });
 
-// ─── Scenario 7: Error message contains actionable instruction ──
+test('write-gate: wildcard verification unlocks all milestones in queue flow', () => {
+  markDepthVerified('*');
+
+  const r1 = shouldBlockContextWrite(
+    'write',
+    '.gsd/milestones/M099/M099-CONTEXT.md',
+    null,
+    false,
+    true,
+  );
+  assert.strictEqual(r1.block, false, 'wildcard should pass any milestone');
+});
 
-test('write-gate: blocked reason contains depth_verification keyword', () => {
+test('write-gate: allows non-CONTEXT.md writes during queue flow regardless', () => {
   const result = shouldBlockContextWrite(
     'write',
-    '.gsd/milestones/M999/M999-CONTEXT.md',
-    'M999',
+    '.gsd/QUEUE.md',
+    null,
     false,
+    true,
   );
-  assert.strictEqual(result.block, true);
-  assert.ok(result.reason!.includes('depth_verification'), 'reason should mention depth_verification question id');
-  assert.ok(result.reason!.includes('ask_user_questions'), 'reason should mention ask_user_questions tool');
+  assert.strictEqual(result.block, false, 'QUEUE.md should pass during queue flow');
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Unique milestone ID format tests
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('write-gate: matches unique milestone ID format (M010-3ym37m)', () => {
+  const result = shouldBlockContextWrite(
+    'write',
+    '.gsd/milestones/M010-3ym37m/M010-3ym37m-CONTEXT.md',
+    'M010-3ym37m',
+    false,
+  );
+  assert.strictEqual(result.block, true, 'should match unique milestone ID format');
+});
+
+test('write-gate: matches classic milestone ID format (M001)', () => {
+  const result = shouldBlockContextWrite(
+    'write',
+    '.gsd/milestones/M001/M001-CONTEXT.md',
+    'M001',
+    false,
+  );
+  assert.strictEqual(result.block, true, 'should match classic milestone ID format');
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Per-milestone depth verification helpers
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('isDepthVerifiedFor: returns false for unknown milestone', () => {
+  assert.strictEqual(isDepthVerifiedFor('M999-xxxxxx'), true,
+    'returns true because wildcard * was set in earlier test');
+  // Note: test isolation would require clearing state, but these tests
+  // exercise the module as a singleton (matching production behavior)
+});
+
+test('isDepthVerified: returns true when any milestone verified', () => {
+  // At this point M010-3ym37m and * are verified from earlier tests
+  assert.strictEqual(isDepthVerified(), true);
 });

package/src/resources/extensions/gsd/token-counter.ts

@@ -1,3 +1,14 @@
+export type TokenProvider = "anthropic" | "openai" | "google" | "mistral" | "bedrock" | "unknown";
+
+const CHARS_PER_TOKEN_BY_PROVIDER: Record<TokenProvider, number> = {
+	anthropic: 3.5,
+	openai: 4.0,
+	google: 4.0,
+	mistral: 3.8,
+	bedrock: 3.5,
+	unknown: 4.0,
+};
+
 interface TokenEncoder {
 	encode(text: string): Uint32Array | number[];
 }
@@ -43,3 +54,12 @@ export async function initTokenCounter(): Promise<boolean> {
 export function isAccurateCountingAvailable(): boolean {
 	return encoder !== null;
 }
+
+export function getCharsPerToken(provider: TokenProvider): number {
+	return CHARS_PER_TOKEN_BY_PROVIDER[provider] ?? CHARS_PER_TOKEN_BY_PROVIDER.unknown;
+}
+
+export function estimateTokensForProvider(text: string, provider: TokenProvider): number {
+	const ratio = getCharsPerToken(provider);
+	return Math.ceil(text.length / ratio);
+}

package/src/resources/extensions/gsd/triage-ui.ts

@@ -10,7 +10,7 @@
  */
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import { showNextAction } from "../shared/next-action-ui.js";
+import { showNextAction } from "../shared/mod.js";
 import type { CaptureEntry, Classification, TriageResult } from "./captures.js";
 import { markCaptureResolved } from "./captures.js";
 

package/src/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 */
@@ -191,7 +192,7 @@ export interface ActiveRef {
 export interface MilestoneRegistryEntry {
   id: string;
   title: string;
-  status: 'complete' | 'active' | 'pending';
+  status: 'complete' | 'active' | 'pending' | 'parked';
   /** Milestone IDs that must be complete before this milestone becomes active. Populated from CONTEXT.md YAML frontmatter. */
   dependsOn?: string[];
 }
@@ -407,6 +408,9 @@ export interface Requirement {
 
 // ─── Parallel Orchestration Types ────────────────────────────────────────
 
+export type CompressionStrategy = 'truncate' | 'compress';
+export type ContextSelectionMode = 'full' | 'smart';
+
 export type MergeStrategy = "per-slice" | "per-milestone";
 export type AutoMergeMode = "auto" | "confirm" | "manual";
 

package/src/resources/extensions/gsd/unit-runtime.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import {
   gsdRoot,
@@ -8,6 +8,7 @@ import {
   resolveTaskFile,
 } from "./paths.js";
 import { loadFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
+import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
 
 export type UnitRuntimePhase =
   | "dispatched"
@@ -46,13 +47,23 @@ export interface AutoUnitRuntimeRecord {
   lastRecoveryReason?: "idle" | "hard";
 }
 
+function isAutoUnitRuntimeRecord(data: unknown): data is AutoUnitRuntimeRecord {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    (data as AutoUnitRuntimeRecord).version === 1 &&
+    typeof (data as AutoUnitRuntimeRecord).unitType === "string" &&
+    typeof (data as AutoUnitRuntimeRecord).unitId === "string"
+  );
+}
+
 function runtimeDir(basePath: string): string {
   return join(gsdRoot(basePath), "runtime", "units");
 }
 
 function runtimePath(basePath: string, unitType: string, unitId: string): string {
-  const sanitizedUnitType = unitType.replace(/[\/]/g, "-");
-  const sanitizedUnitId = unitId.replace(/[\/]/g, "-");
+  const sanitizedUnitType = unitType.replace(/[^a-zA-Z0-9._-]+/g, "-");
+  const sanitizedUnitId = unitId.replace(/[^a-zA-Z0-9._-]+/g, "-");
   return join(runtimeDir(basePath), `${sanitizedUnitType}-${sanitizedUnitId}.json`);
 }
 
@@ -63,8 +74,6 @@ export function writeUnitRuntimeRecord(
   startedAt: number,
   updates: Partial<AutoUnitRuntimeRecord> = {},
 ): AutoUnitRuntimeRecord {
-  const dir = runtimeDir(basePath);
-  mkdirSync(dir, { recursive: true });
   const path = runtimePath(basePath, unitType, unitId);
   const prev = readUnitRuntimeRecord(basePath, unitType, unitId);
   const next: AutoUnitRuntimeRecord = {
@@ -84,18 +93,12 @@ export function writeUnitRuntimeRecord(
     recoveryAttempts: updates.recoveryAttempts ?? prev?.recoveryAttempts ?? 0,
     lastRecoveryReason: updates.lastRecoveryReason ?? prev?.lastRecoveryReason,
   };
-  writeFileSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
+  saveJsonFile(path, next);
   return next;
 }
 
 export function readUnitRuntimeRecord(basePath: string, unitType: string, unitId: string): AutoUnitRuntimeRecord | null {
-  const path = runtimePath(basePath, unitType, unitId);
-  if (!existsSync(path)) return null;
-  try {
-    return JSON.parse(readFileSync(path, "utf-8")) as AutoUnitRuntimeRecord;
-  } catch {
-    return null;
-  }
+  return loadJsonFileOrNull(runtimePath(basePath, unitType, unitId), isAutoUnitRuntimeRecord);
 }
 
 export function clearUnitRuntimeRecord(basePath: string, unitType: string, unitId: string): void {

package/src/resources/extensions/gsd/validate-directory.ts

@@ -0,0 +1,164 @@
+/**
+ * GSD Directory Validation — Safeguards against running in dangerous directories.
+ *
+ * Prevents GSD from creating .gsd/ structures in system paths, home directories,
+ * or other locations where writing project scaffolding would be harmful.
+ */
+
+import { realpathSync, readdirSync } from "node:fs";
+import { homedir, platform, tmpdir } from "node:os";
+import { resolve } from "node:path";
+
+// ─── Types ──────────────────────────────────────────────────────────────────────
+
+export interface DirectoryValidationResult {
+  /** Whether the directory is safe for GSD operations */
+  safe: boolean;
+  /** Severity: "blocked" = hard stop, "warning" = user can override */
+  severity: "ok" | "blocked" | "warning";
+  /** Human-readable reason if not safe */
+  reason?: string;
+}
+
+// ─── Blocked Paths ──────────────────────────────────────────────────────────────
+
+/** Paths where GSD must never create .gsd/ — no override possible. */
+const UNIX_BLOCKED_PATHS = new Set([
+  "/",
+  "/bin",
+  "/sbin",
+  "/usr",
+  "/usr/bin",
+  "/usr/sbin",
+  "/usr/lib",
+  "/usr/local",
+  "/usr/local/bin",
+  "/etc",
+  "/var",
+  "/var/tmp",
+  "/dev",
+  "/proc",
+  "/sys",
+  "/boot",
+  "/lib",
+  "/lib64",
+  // macOS-specific
+  "/System",
+  "/Library",
+  "/Applications",
+  "/Volumes",
+  "/private",
+  "/private/var",
+  "/private/etc",
+  "/private/tmp",
+]);
+
+const WINDOWS_BLOCKED_PATHS = new Set([
+  "C:\\",
+  "C:\\Windows",
+  "C:\\Windows\\System32",
+  "C:\\Program Files",
+  "C:\\Program Files (x86)",
+]);
+
+// ─── Core Validation ────────────────────────────────────────────────────────────
+
+/**
+ * Validate whether a directory is safe for GSD to operate in.
+ *
+ * Checks in order:
+ * 1. Blocked system paths (hard stop)
+ * 2. Home directory itself (hard stop)
+ * 3. Temp directory root (hard stop)
+ * 4. High entry count heuristic (warning)
+ */
+export function validateDirectory(dirPath: string): DirectoryValidationResult {
+  // Resolve to absolute + follow symlinks so aliases can't bypass checks
+  let resolved: string;
+  try {
+    resolved = realpathSync(resolve(dirPath));
+  } catch {
+    // If we can't resolve, use the raw resolved path
+    resolved = resolve(dirPath);
+  }
+
+  // Normalize trailing slashes for consistent comparison.
+  // Special cases: "/" → "/" (not ""), "C:\" → "C:\" (not "C:")
+  let normalized = resolved.replace(/[/\\]+$/, "");
+  if (normalized === "") {
+    normalized = "/";
+  } else if (/^[A-Za-z]:$/.test(normalized)) {
+    normalized = normalized + "\\";
+  }
+
+  // ── Check 1: Blocked system paths ──────────────────────────────────────
+  const blockedPaths = platform() === "win32" ? WINDOWS_BLOCKED_PATHS : UNIX_BLOCKED_PATHS;
+  if (blockedPaths.has(normalized)) {
+    return {
+      safe: false,
+      severity: "blocked",
+      reason: `Refusing to run in system directory: ${normalized}. GSD must be run inside a project directory.`,
+    };
+  }
+
+  // ── Check 2: Home directory itself (not subdirs) ───────────────────────
+  let resolvedHome: string;
+  try {
+    resolvedHome = realpathSync(resolve(homedir())).replace(/[/\\]+$/, "");
+  } catch {
+    resolvedHome = resolve(homedir()).replace(/[/\\]+$/, "");
+  }
+
+  if (normalized === resolvedHome) {
+    return {
+      safe: false,
+      severity: "blocked",
+      reason: `Refusing to run in your home directory (${normalized}). GSD must be run inside a project directory, not $HOME.`,
+    };
+  }
+
+  // ── Check 3: Temp directory root ───────────────────────────────────────
+  let resolvedTmp: string;
+  try {
+    resolvedTmp = realpathSync(resolve(tmpdir())).replace(/[/\\]+$/, "");
+  } catch {
+    resolvedTmp = resolve(tmpdir()).replace(/[/\\]+$/, "");
+  }
+
+  if (normalized === resolvedTmp) {
+    return {
+      safe: false,
+      severity: "blocked",
+      reason: `Refusing to run in the system temp directory (${normalized}). Use a project subdirectory instead.`,
+    };
+  }
+
+  // ── Check 4: Suspiciously large directory (heuristic warning) ──────────
+  try {
+    const entries = readdirSync(normalized);
+    if (entries.length > 200) {
+      return {
+        safe: false,
+        severity: "warning",
+        reason: `This directory has ${entries.length} entries, which suggests it may not be a project directory. Are you sure you want to initialize GSD here?`,
+      };
+    }
+  } catch {
+    // Can't read directory — let downstream handle the error
+  }
+
+  return { safe: true, severity: "ok" };
+}
+
+/**
+ * Assert that a directory is safe for GSD operations.
+ * Throws with a descriptive message if the directory is blocked.
+ * Returns the validation result for warnings (caller decides how to handle).
+ */
+export function assertSafeDirectory(dirPath: string): DirectoryValidationResult {
+  const result = validateDirectory(dirPath);
+  if (result.severity === "blocked") {
+    throw new Error(result.reason);
+  }
+  return result;
+}

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

@@ -20,11 +20,12 @@ export interface EvidenceCheckJSON {
   exitCode: number;
   durationMs: number;
   verdict: "pass" | "fail";
+  blocking: boolean;
 }
 
 export interface RuntimeErrorJSON {
-  source: string;
-  severity: string;
+  source: "bg-shell" | "browser";
+  severity: "crash" | "error" | "warning";
   message: string;
   blocking: boolean;
 }
@@ -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 } : {}),
@@ -113,8 +115,11 @@ export function writeVerificationJSON(
 /**
  * Format duration in milliseconds as seconds with 1 decimal place.
  * e.g. 2340 → "2.3s", 150 → "0.2s", 0 → "0.0s"
+ *
+ * Distinct from the shared formatDuration (which uses adaptive ms/s/m/h units);
+ * evidence tables always display seconds for consistent column alignment.
  */
-function formatDuration(ms: number): string {
+function formatDurationSecs(ms: number): string {
   return `${(ms / 1000).toFixed(1)}s`;
 }
 
@@ -139,7 +144,7 @@ export function formatEvidenceTable(result: VerificationResult): string {
     const num = i + 1;
     const verdict =
       check.exitCode === 0 ? "✅ pass" : "❌ fail";
-    const duration = formatDuration(check.durationMs);
+    const duration = formatDurationSecs(check.durationMs);
 
     lines.push(
       `| ${num} | ${check.command} | ${check.exitCode} | ${verdict} | ${duration} |`,