gsd-pi 2.10.12 → 2.12.0

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

@@ -0,0 +1,122 @@
+/**
+ * Unit tests for the CONTEXT.md write-gate (D031 guard chain).
+ *
+ * Exercises shouldBlockContextWrite() — a pure function that implements:
+ *   (a) toolName !== "write" → pass
+ *   (b) milestoneId null → pass (not in discussion)
+ *   (c) path doesn't match /M\d+-CONTEXT\.md$/ → pass
+ *   (d) depthVerified → pass
+ *   (e) else → block with actionable reason
+ */
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { shouldBlockContextWrite } from '../index.ts';
+
+// ─── Scenario 1: Blocks CONTEXT.md write during discussion without depth verification (absolute path) ──
+
+test('write-gate: blocks CONTEXT.md write during discussion without depth verification (absolute path)', () => {
+  const result = shouldBlockContextWrite(
+    'write',
+    '/Users/dev/project/.gsd/milestones/M001/M001-CONTEXT.md',
+    'M001',
+    false,
+  );
+  assert.strictEqual(result.block, true, 'should block the write');
+  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',
+    '.gsd/milestones/M005/M005-CONTEXT.md',
+    'M005',
+    false,
+  );
+  assert.strictEqual(result.block, true, 'should block the write');
+  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', () => {
+  const result = shouldBlockContextWrite(
+    'write',
+    '/Users/dev/project/.gsd/milestones/M001/M001-CONTEXT.md',
+    'M001',
+    true,
+  );
+  assert.strictEqual(result.block, false, 'should not block 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', () => {
+  const result = shouldBlockContextWrite(
+    'write',
+    '.gsd/milestones/M001/M001-CONTEXT.md',
+    null,
+    false,
+  );
+  assert.strictEqual(result.block, false, 'should not block outside discussion phase');
+});
+
+// ─── Scenario 5: Allows non-CONTEXT.md writes during discussion ──
+
+test('write-gate: allows non-CONTEXT.md writes during discussion', () => {
+  // DISCUSSION.md
+  const r1 = shouldBlockContextWrite(
+    'write',
+    '.gsd/milestones/M001/M001-DISCUSSION.md',
+    'M001',
+    false,
+  );
+  assert.strictEqual(r1.block, false, 'DISCUSSION.md should pass');
+
+  // Slice file
+  const r2 = shouldBlockContextWrite(
+    'write',
+    '.gsd/milestones/M001/slices/S01/S01-PLAN.md',
+    'M001',
+    false,
+  );
+  assert.strictEqual(r2.block, false, 'slice plan should pass');
+
+  // Regular code file
+  const r3 = shouldBlockContextWrite(
+    'write',
+    'src/index.ts',
+    'M001',
+    false,
+  );
+  assert.strictEqual(r3.block, false, 'regular code file should pass');
+});
+
+// ─── Scenario 6: Regex specificity — doesn't match S01-CONTEXT.md ──
+
+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',
+    false,
+  );
+  assert.strictEqual(result.block, false, 'S01-CONTEXT.md should not be blocked');
+});
+
+// ─── Scenario 7: Error message contains actionable instruction ──
+
+test('write-gate: blocked reason contains depth_verification keyword', () => {
+  const result = shouldBlockContextWrite(
+    'write',
+    '.gsd/milestones/M999/M999-CONTEXT.md',
+    'M999',
+    false,
+  );
+  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');
+});

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

@@ -0,0 +1,296 @@
+// GSD Extension — Core Type Definitions
+// Types consumed by state derivation, file parsing, and status display.
+// Pure interfaces — no logic, no runtime dependencies.
+
+// ─── Enums & Literal Unions ────────────────────────────────────────────────
+
+export type RiskLevel = 'low' | 'medium' | 'high';
+export type Phase = 'pre-planning' | 'needs-discussion' | 'discussing' | 'researching' | 'planning' | 'executing' | 'verifying' | 'summarizing' | 'advancing' | 'completing-milestone' | 'replanning-slice' | 'complete' | 'paused' | 'blocked';
+export type ContinueStatus = 'in_progress' | 'interrupted' | 'compacted';
+
+// ─── Roadmap (Milestone-level) ─────────────────────────────────────────────
+
+export interface RoadmapSliceEntry {
+  id: string;          // e.g. "S01"
+  title: string;       // e.g. "Types + File I/O + Git Operations"
+  risk: RiskLevel;
+  depends: string[];   // e.g. ["S01", "S02"]
+  done: boolean;
+  demo: string;        // the "After this:" sentence
+}
+
+export interface BoundaryMapEntry {
+  fromSlice: string;   // e.g. "S01"
+  toSlice: string;     // e.g. "S02" or "terminal"
+  produces: string;    // raw text block of what this slice produces
+  consumes: string;    // raw text block of what it consumes (or "nothing")
+}
+
+export interface Roadmap {
+  title: string;       // e.g. "M001: GSD Extension — Hierarchical Planning with Auto Mode"
+  vision: string;
+  successCriteria: string[];
+  slices: RoadmapSliceEntry[];
+  boundaryMap: BoundaryMapEntry[];
+}
+
+// ─── Slice Plan ────────────────────────────────────────────────────────────
+
+export interface TaskPlanEntry {
+  id: string;          // e.g. "T01"
+  title: string;       // e.g. "Core Type Definitions"
+  description: string;
+  done: boolean;
+  estimate: string;    // e.g. "30m", "2h" — informational only
+  files?: string[];    // e.g. ["types.ts", "files.ts"] — extracted from "- Files:" subline
+  verify?: string;     // e.g. "run tests" — extracted from "- Verify:" subline
+}
+
+export interface SlicePlan {
+  id: string;          // e.g. "S01"
+  title: string;       // from the H1
+  goal: string;
+  demo: string;
+  mustHaves: string[]; // top-level must-have bullet points
+  tasks: TaskPlanEntry[];
+  filesLikelyTouched: string[];
+}
+
+// ─── Summary (Task & Slice level) ──────────────────────────────────────────
+
+export interface SummaryRequires {
+  slice: string;
+  provides: string;
+}
+
+export interface SummaryFrontmatter {
+  id: string;
+  parent: string;
+  milestone: string;
+  provides: string[];
+  requires: SummaryRequires[];
+  affects: string[];
+  key_files: string[];
+  key_decisions: string[];
+  patterns_established: string[];
+  drill_down_paths: string[];
+  observability_surfaces: string[];
+  duration: string;
+  verification_result: string;
+  completed_at: string;
+  blocker_discovered: boolean;
+}
+
+export interface FileModified {
+  path: string;
+  description: string;
+}
+
+export interface Summary {
+  frontmatter: SummaryFrontmatter;
+  title: string;
+  oneLiner: string;
+  whatHappened: string;
+  deviations: string;
+  filesModified: FileModified[];
+}
+
+// ─── Continue-Here ─────────────────────────────────────────────────────────
+
+export interface ContinueFrontmatter {
+  milestone: string;
+  slice: string;
+  task: string;
+  step: number;
+  totalSteps: number;
+  status: ContinueStatus;
+  savedAt: string;
+}
+
+export interface Continue {
+  frontmatter: ContinueFrontmatter;
+  completedWork: string;
+  remainingWork: string;
+  decisions: string;
+  context: string;
+  nextAction: string;
+}
+
+// ─── Secrets Manifest ──────────────────────────────────────────────────────
+
+export type SecretsManifestEntryStatus = 'pending' | 'collected' | 'skipped';
+
+export interface SecretsManifestEntry {
+  key: string;              // e.g. "OPENAI_API_KEY"
+  service: string;          // e.g. "OpenAI"
+  dashboardUrl: string;     // e.g. "https://platform.openai.com/api-keys" — empty if unknown
+  guidance: string[];       // numbered setup steps
+  formatHint: string;       // e.g. "starts with sk-" — empty if unknown
+  status: SecretsManifestEntryStatus;
+  destination: string;      // e.g. "dotenv", "vercel", "convex"
+}
+
+export interface SecretsManifest {
+  milestone: string;        // e.g. "M001"
+  generatedAt: string;      // ISO 8601 timestamp
+  entries: SecretsManifestEntry[];
+}
+
+export interface ManifestStatus {
+  pending: string[];    // manifest status = pending AND not in env
+  collected: string[];  // manifest status = collected AND not in env
+  skipped: string[];    // manifest status = skipped
+  existing: string[];   // key present in .env or process.env (regardless of manifest status)
+}
+
+// ─── GSD State (Derived Dashboard) ────────────────────────────────────────
+
+export interface ActiveRef {
+  id: string;
+  title: string;
+}
+
+export interface MilestoneRegistryEntry {
+  id: string;
+  title: string;
+  status: 'complete' | 'active' | 'pending';
+  /** Milestone IDs that must be complete before this milestone becomes active. Populated from CONTEXT.md YAML frontmatter. */
+  dependsOn?: string[];
+}
+
+export interface RequirementCounts {
+  active: number;
+  validated: number;
+  deferred: number;
+  outOfScope: number;
+  blocked: number;
+  total: number;
+}
+
+export interface GSDState {
+  activeMilestone: ActiveRef | null;
+  activeSlice: ActiveRef | null;
+  activeTask: ActiveRef | null;
+  phase: Phase;
+  recentDecisions: string[];
+  blockers: string[];
+  nextAction: string;
+  activeBranch?: string;
+  activeWorkspace?: string;
+  registry: MilestoneRegistryEntry[];
+  requirements?: RequirementCounts;
+  progress?: {
+    milestones: { done: number; total: number };
+    slices?: { done: number; total: number };
+    tasks?: { done: number; total: number };
+  };
+}
+
+// ─── Post-Unit Hook Types ─────────────────────────────────────────────────
+
+export interface PostUnitHookConfig {
+  /** Unique hook identifier — used in idempotency keys and logging. */
+  name: string;
+  /** Unit types that trigger this hook (e.g., ["execute-task"]). */
+  after: string[];
+  /** Prompt sent to the LLM session. Supports {milestoneId}, {sliceId}, {taskId} substitutions. */
+  prompt: string;
+  /** Max times this hook can fire for the same trigger unit. Default 1, max 10. */
+  max_cycles?: number;
+  /** Model override for hook sessions. */
+  model?: string;
+  /** Expected output file name (relative to task/slice dir). Used for idempotency — skip if exists. */
+  artifact?: string;
+  /** If this file is produced instead of artifact, re-run the trigger unit then re-run hooks. */
+  retry_on?: string;
+  /** Agent definition file to use. */
+  agent?: string;
+  /** Set false to disable without removing config. Default true. */
+  enabled?: boolean;
+}
+
+export interface HookExecutionState {
+  /** Hook name. */
+  hookName: string;
+  /** The unit type that triggered this hook. */
+  triggerUnitType: string;
+  /** The unit ID that triggered this hook. */
+  triggerUnitId: string;
+  /** Current cycle (1-based). */
+  cycle: number;
+  /** Whether the hook completed with a retry signal (retry_on artifact found). */
+  pendingRetry: boolean;
+}
+
+export interface HookDispatchResult {
+  /** Hook name for display. */
+  hookName: string;
+  /** The prompt to send. */
+  prompt: string;
+  /** Model override, if configured. */
+  model?: string;
+  /** Synthetic unit type, e.g. "hook/code-review". */
+  unitType: string;
+  /** The trigger unit's ID, reused for the hook. */
+  unitId: string;
+}
+
+// ─── Pre-Dispatch Hook Types ──────────────────────────────────────────────
+
+export interface PreDispatchHookConfig {
+  /** Unique hook identifier. */
+  name: string;
+  /** Unit types this hook intercepts before dispatch (e.g., ["execute-task"]). */
+  before: string[];
+  /** Action to take: "modify" mutates the prompt, "skip" skips the unit, "replace" swaps it. */
+  action: 'modify' | 'skip' | 'replace';
+  /** For "modify": text prepended to the unit prompt. Supports {milestoneId}, {sliceId}, {taskId}. */
+  prepend?: string;
+  /** For "modify": text appended to the unit prompt. Supports {milestoneId}, {sliceId}, {taskId}. */
+  append?: string;
+  /** For "replace": the replacement prompt. Supports {milestoneId}, {sliceId}, {taskId}. */
+  prompt?: string;
+  /** For "replace": override the unit type label. */
+  unit_type?: string;
+  /** For "skip": optional condition file — only skip if this file exists (relative to unit dir). */
+  skip_if?: string;
+  /** Model override when this hook fires. */
+  model?: string;
+  /** Set false to disable without removing config. Default true. */
+  enabled?: boolean;
+}
+
+export interface PreDispatchResult {
+  /** What happened: the unit proceeds with modifications, was skipped, or was replaced. */
+  action: 'proceed' | 'skip' | 'replace';
+  /** Modified/replacement prompt (for "proceed" and "replace"). */
+  prompt?: string;
+  /** Override unit type (for "replace"). */
+  unitType?: string;
+  /** Model override. */
+  model?: string;
+  /** Names of hooks that fired, for logging. */
+  firedHooks: string[];
+}
+
+// ─── Hook State Persistence Types ─────────────────────────────────────────
+
+export interface PersistedHookState {
+  /** Cycle counts keyed as "hookName/triggerUnitType/triggerUnitId". */
+  cycleCounts: Record<string, number>;
+  /** Timestamp of last state save. */
+  savedAt: string;
+}
+
+export interface HookStatusEntry {
+  /** Hook name. */
+  name: string;
+  /** Hook type: "post" or "pre". */
+  type: 'post' | 'pre';
+  /** Whether hook is enabled. */
+  enabled: boolean;
+  /** What unit types it targets. */
+  targets: string[];
+  /** Current cycle counts for active triggers. */
+  activeCycles: Record<string, number>;
+}

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

@@ -0,0 +1,184 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import {
+  gsdRoot,
+  relSliceFile,
+  relTaskFile,
+  resolveSliceFile,
+  resolveTaskFile,
+} from "./paths.js";
+import { loadFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
+
+export type UnitRuntimePhase =
+  | "dispatched"
+  | "wrapup-warning-sent"
+  | "timeout"
+  | "recovered"
+  | "finalized"
+  | "paused"
+  | "skipped";
+
+export interface ExecuteTaskRecoveryStatus {
+  planPath: string;
+  summaryPath: string;
+  summaryExists: boolean;
+  taskChecked: boolean;
+  nextActionAdvanced: boolean;
+  mustHaveCount: number;
+  mustHavesMentionedInSummary: number;
+}
+
+export interface AutoUnitRuntimeRecord {
+  version: 1;
+  unitType: string;
+  unitId: string;
+  startedAt: number;
+  updatedAt: number;
+  phase: UnitRuntimePhase;
+  wrapupWarningSent: boolean;
+  timeoutAt: number | null;
+  lastProgressAt: number;
+  progressCount: number;
+  lastProgressKind: string;
+  recovery?: ExecuteTaskRecoveryStatus;
+  recoveryAttempts?: number;
+  lastRecoveryReason?: "idle" | "hard";
+}
+
+function runtimeDir(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "units");
+}
+
+function runtimePath(basePath: string, unitType: string, unitId: string): string {
+  return join(runtimeDir(basePath), `${unitType}-${unitId.replace(/[\/]/g, "-")}.json`);
+}
+
+export function writeUnitRuntimeRecord(
+  basePath: string,
+  unitType: string,
+  unitId: string,
+  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 = {
+    version: 1,
+    unitType,
+    unitId,
+    startedAt,
+    updatedAt: Date.now(),
+    phase: updates.phase ?? prev?.phase ?? "dispatched",
+    wrapupWarningSent: updates.wrapupWarningSent ?? prev?.wrapupWarningSent ?? false,
+    timeoutAt: updates.timeoutAt ?? prev?.timeoutAt ?? null,
+    lastProgressAt: updates.lastProgressAt ?? prev?.lastProgressAt ?? Date.now(),
+    progressCount: updates.progressCount ?? prev?.progressCount ?? 0,
+    lastProgressKind: updates.lastProgressKind ?? prev?.lastProgressKind ?? "dispatch",
+    recovery: updates.recovery ?? prev?.recovery,
+    recoveryAttempts: updates.recoveryAttempts ?? prev?.recoveryAttempts ?? 0,
+    lastRecoveryReason: updates.lastRecoveryReason ?? prev?.lastRecoveryReason,
+  };
+  writeFileSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
+  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;
+  }
+}
+
+export function clearUnitRuntimeRecord(basePath: string, unitType: string, unitId: string): void {
+  const path = runtimePath(basePath, unitType, unitId);
+  if (existsSync(path)) unlinkSync(path);
+}
+
+/**
+ * Return all runtime records currently on disk for `basePath`.
+ * Returns an empty array if the runtime directory does not exist.
+ */
+export function listUnitRuntimeRecords(basePath: string): AutoUnitRuntimeRecord[] {
+  const dir = runtimeDir(basePath);
+  if (!existsSync(dir)) return [];
+  const results: AutoUnitRuntimeRecord[] = [];
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith(".json")) continue;
+    try {
+      const raw = readFileSync(join(dir, file), "utf-8");
+      const record = JSON.parse(raw) as AutoUnitRuntimeRecord;
+      results.push(record);
+    } catch {
+      // Skip malformed files
+    }
+  }
+  return results;
+}
+
+export async function inspectExecuteTaskDurability(
+  basePath: string,
+  unitId: string,
+): Promise<ExecuteTaskRecoveryStatus | null> {
+  const [mid, sid, tid] = unitId.split("/");
+  if (!mid || !sid || !tid) return null;
+
+  const planAbs = resolveSliceFile(basePath, mid, sid, "PLAN");
+  const summaryAbs = resolveTaskFile(basePath, mid, sid, tid, "SUMMARY");
+  const stateAbs = join(gsdRoot(basePath), "STATE.md");
+
+  const planPath = relSliceFile(basePath, mid, sid, "PLAN");
+  const summaryPath = relTaskFile(basePath, mid, sid, tid, "SUMMARY");
+
+  const planContent = planAbs ? await loadFile(planAbs) : null;
+  const stateContent = existsSync(stateAbs) ? readFileSync(stateAbs, "utf-8") : "";
+  const summaryExists = !!(summaryAbs && existsSync(summaryAbs));
+
+  const escapedTid = tid.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const taskChecked = !!planContent && new RegExp(`^- \\[[xX]\\] \\*\\*${escapedTid}:`, "m").test(planContent);
+  const nextActionAdvanced = !new RegExp(`Execute ${tid}\\b`).test(stateContent);
+
+  // Must-have coverage: load task plan and count mentions in summary
+  let mustHaveCount = 0;
+  let mustHavesMentionedInSummary = 0;
+
+  const taskPlanAbs = resolveTaskFile(basePath, mid, sid, tid, "PLAN");
+  if (taskPlanAbs) {
+    const taskPlanContent = await loadFile(taskPlanAbs);
+    if (taskPlanContent) {
+      const mustHaves = parseTaskPlanMustHaves(taskPlanContent);
+      mustHaveCount = mustHaves.length;
+      if (mustHaveCount > 0 && summaryExists && summaryAbs) {
+        const summaryContent = await loadFile(summaryAbs);
+        if (summaryContent) {
+          mustHavesMentionedInSummary = countMustHavesMentionedInSummary(mustHaves, summaryContent);
+        }
+      }
+    }
+  }
+
+  return {
+    planPath,
+    summaryPath,
+    summaryExists,
+    taskChecked,
+    nextActionAdvanced,
+    mustHaveCount,
+    mustHavesMentionedInSummary,
+  };
+}
+
+export function formatExecuteTaskRecoveryStatus(status: ExecuteTaskRecoveryStatus): string {
+  const missing = [] as string[];
+  if (!status.summaryExists) missing.push(`summary missing (${status.summaryPath})`);
+  if (!status.taskChecked) missing.push(`task checkbox unchecked in ${status.planPath}`);
+  if (!status.nextActionAdvanced) missing.push("state next action still points at the timed-out task");
+  if (status.mustHaveCount > 0 && status.mustHavesMentionedInSummary < status.mustHaveCount) {
+    missing.push(`must-have gap: ${status.mustHavesMentionedInSummary} of ${status.mustHaveCount} must-haves addressed in summary`);
+  }
+  return missing.length > 0 ? missing.join("; ") : "all durable task artifacts present";
+}