gsd-pi 2.11.0 → 2.12.0

package/src/resources/extensions/gsd/tests/post-unit-hooks.test.ts

@@ -0,0 +1,297 @@
+// GSD Extension — Hook Engine Tests (Post-Unit, Pre-Dispatch, State Persistence)
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createTestContext } from "./test-helpers.ts";
+import {
+  checkPostUnitHooks,
+  getActiveHook,
+  resetHookState,
+  isRetryPending,
+  consumeRetryTrigger,
+  resolveHookArtifactPath,
+  runPreDispatchHooks,
+  persistHookState,
+  restoreHookState,
+  clearPersistedHookState,
+  getHookStatus,
+  formatHookStatus,
+} from "../post-unit-hooks.ts";
+
+const { assertEq, assertTrue, assertMatch, report } = createTestContext();
+
+// ─── Fixture Helpers ───────────────────────────────────────────────────────
+
+function createFixtureBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-hook-test-"));
+  mkdirSync(join(base, ".gsd", "M001", "slices", "S01", "tasks"), { recursive: true });
+  return base;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 1: Post-Unit Hook Tests
+// ═══════════════════════════════════════════════════════════════════════════
+
+// ─── resolveHookArtifactPath ───────────────────────────────────────────────
+
+console.log("\n=== resolveHookArtifactPath ===");
+
+{
+  const base = "/project";
+
+  // Task-level
+  const taskPath = resolveHookArtifactPath(base, "M001/S01/T01", "REVIEW-PASS.md");
+  assertEq(
+    taskPath,
+    join(base, ".gsd", "M001", "slices", "S01", "tasks", "T01-REVIEW-PASS.md"),
+    "task-level artifact path",
+  );
+
+  // Slice-level
+  const slicePath = resolveHookArtifactPath(base, "M001/S01", "REVIEW-PASS.md");
+  assertEq(
+    slicePath,
+    join(base, ".gsd", "M001", "slices", "S01", "REVIEW-PASS.md"),
+    "slice-level artifact path",
+  );
+
+  // Milestone-level
+  const milestonePath = resolveHookArtifactPath(base, "M001", "REVIEW-PASS.md");
+  assertEq(
+    milestonePath,
+    join(base, ".gsd", "M001", "REVIEW-PASS.md"),
+    "milestone-level artifact path",
+  );
+}
+
+// ─── resetHookState ────────────────────────────────────────────────────────
+
+console.log("\n=== resetHookState ===");
+
+{
+  resetHookState();
+  assertEq(getActiveHook(), null, "no active hook after reset");
+  assertTrue(!isRetryPending(), "no retry pending after reset");
+  assertEq(consumeRetryTrigger(), null, "no retry trigger after reset");
+}
+
+// ─── checkPostUnitHooks with no hooks configured ───────────────────────────
+
+console.log("\n=== No hooks configured ===");
+
+{
+  resetHookState();
+  const base = createFixtureBase();
+  try {
+    const result = checkPostUnitHooks("execute-task", "M001/S01/T01", base);
+    assertEq(result, null, "returns null when no hooks configured");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+// ─── Hook units don't trigger hooks (no hook-on-hook) ──────────────────────
+
+console.log("\n=== Hook-on-hook prevention ===");
+
+{
+  resetHookState();
+  const base = createFixtureBase();
+  try {
+    const result = checkPostUnitHooks("hook/code-review", "M001/S01/T01", base);
+    assertEq(result, null, "hook units don't trigger other hooks");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+// ─── consumeRetryTrigger clears state ──────────────────────────────────────
+
+console.log("\n=== consumeRetryTrigger clears state ===");
+
+{
+  resetHookState();
+  assertEq(consumeRetryTrigger(), null, "no trigger initially");
+  assertTrue(!isRetryPending(), "no retry initially");
+}
+
+// ─── Variable substitution in prompts ──────────────────────────────────────
+
+console.log("\n=== Variable substitution ===");
+
+{
+  const base = "/project";
+
+  // 3-part ID
+  const path3 = resolveHookArtifactPath(base, "M002/S03/T05", "result.md");
+  assertTrue(path3.includes("M002"), "3-part ID extracts milestoneId");
+  assertTrue(path3.includes("S03"), "3-part ID extracts sliceId");
+  assertTrue(path3.includes("T05"), "3-part ID extracts taskId");
+
+  // 2-part ID
+  const path2 = resolveHookArtifactPath(base, "M002/S03", "result.md");
+  assertTrue(path2.includes("M002"), "2-part ID extracts milestoneId");
+  assertTrue(path2.includes("S03"), "2-part ID extracts sliceId");
+
+  // 1-part ID
+  const path1 = resolveHookArtifactPath(base, "M002", "result.md");
+  assertTrue(path1.includes("M002"), "1-part ID extracts milestoneId");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 2: Pre-Dispatch Hook Tests
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log("\n=== Pre-dispatch: no hooks configured ===");
+
+{
+  const base = createFixtureBase();
+  try {
+    const result = runPreDispatchHooks("execute-task", "M001/S01/T01", "original prompt", base);
+    assertEq(result.action, "proceed", "proceeds when no hooks");
+    assertEq(result.prompt, "original prompt", "prompt unchanged");
+    assertEq(result.firedHooks.length, 0, "no hooks fired");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+console.log("\n=== Pre-dispatch: hook units bypass ===");
+
+{
+  const base = createFixtureBase();
+  try {
+    const result = runPreDispatchHooks("hook/review", "M001/S01/T01", "hook prompt", base);
+    assertEq(result.action, "proceed", "hook units always proceed");
+    assertEq(result.prompt, "hook prompt", "hook prompt unchanged");
+    assertEq(result.firedHooks.length, 0, "no hooks fired for hook units");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 3: State Persistence Tests
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log("\n=== State persistence: persist and restore ===");
+
+{
+  const base = createFixtureBase();
+  try {
+    resetHookState();
+
+    // Persist empty state
+    persistHookState(base);
+    const filePath = join(base, ".gsd", "hook-state.json");
+    assertTrue(existsSync(filePath), "hook-state.json created");
+
+    const content = JSON.parse(readFileSync(filePath, "utf-8"));
+    assertEq(typeof content.savedAt, "string", "savedAt is a string");
+    assertEq(Object.keys(content.cycleCounts).length, 0, "empty cycle counts");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+console.log("\n=== State persistence: restore from disk ===");
+
+{
+  const base = createFixtureBase();
+  try {
+    resetHookState();
+
+    // Write a state file with some cycle counts
+    const stateFile = join(base, ".gsd", "hook-state.json");
+    writeFileSync(stateFile, JSON.stringify({
+      cycleCounts: {
+        "review/execute-task/M001/S01/T01": 2,
+        "simplify/execute-task/M001/S01/T02": 1,
+      },
+      savedAt: new Date().toISOString(),
+    }), "utf-8");
+
+    // Restore
+    restoreHookState(base);
+
+    // Verify by persisting and reading back
+    persistHookState(base);
+    const restored = JSON.parse(readFileSync(stateFile, "utf-8"));
+    assertEq(restored.cycleCounts["review/execute-task/M001/S01/T01"], 2, "cycle count restored for review");
+    assertEq(restored.cycleCounts["simplify/execute-task/M001/S01/T02"], 1, "cycle count restored for simplify");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+console.log("\n=== State persistence: clear ===");
+
+{
+  const base = createFixtureBase();
+  try {
+    resetHookState();
+
+    // Write then clear
+    const stateFile = join(base, ".gsd", "hook-state.json");
+    writeFileSync(stateFile, JSON.stringify({
+      cycleCounts: { "review/execute-task/M001/S01/T01": 3 },
+      savedAt: new Date().toISOString(),
+    }), "utf-8");
+
+    clearPersistedHookState(base);
+
+    const cleared = JSON.parse(readFileSync(stateFile, "utf-8"));
+    assertEq(Object.keys(cleared.cycleCounts).length, 0, "cycle counts cleared");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+console.log("\n=== State persistence: restore handles missing file ===");
+
+{
+  const base = createFixtureBase();
+  try {
+    resetHookState();
+    // Should not throw
+    restoreHookState(base);
+    assertEq(getActiveHook(), null, "no active hook after restore from missing file");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+console.log("\n=== State persistence: restore handles corrupt file ===");
+
+{
+  const base = createFixtureBase();
+  try {
+    resetHookState();
+    writeFileSync(join(base, ".gsd", "hook-state.json"), "not json", "utf-8");
+    // Should not throw
+    restoreHookState(base);
+    assertEq(getActiveHook(), null, "no active hook after corrupt restore");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 3: Hook Status Reporting Tests
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log("\n=== Hook status: no hooks ===");
+
+{
+  resetHookState();
+  const entries = getHookStatus();
+  // No preferences file = no hooks
+  assertEq(entries.length, 0, "no entries when no hooks configured");
+
+  const formatted = formatHookStatus();
+  assertMatch(formatted, /No hooks configured/, "status message says no hooks");
+}
+
+report();

package/src/resources/extensions/gsd/tests/preferences-hooks.test.ts

@@ -0,0 +1,226 @@
+// GSD Extension — Hook Preferences Parsing Tests (Post-Unit + Pre-Dispatch)
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertEq, assertTrue, report } = createTestContext();
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 1: Post-Unit Hook Config Tests
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log("\n=== Post-unit hook config validation ===");
+
+{
+  const validHook = {
+    name: "test-hook",
+    after: ["execute-task"],
+    prompt: "Test prompt",
+    max_cycles: 2,
+    model: "claude-sonnet-4-6",
+    artifact: "TEST-RESULT.md",
+    retry_on: "TEST-ISSUES.md",
+    enabled: true,
+  };
+
+  assertEq(validHook.name, "test-hook", "valid hook has name");
+  assertEq(validHook.after.length, 1, "valid hook has one after entry");
+  assertEq(validHook.after[0], "execute-task", "valid hook triggers after execute-task");
+  assertTrue(validHook.max_cycles! <= 10, "max_cycles within limit");
+  assertTrue(validHook.max_cycles! >= 1, "max_cycles above minimum");
+}
+
+console.log("\n=== max_cycles clamping ===");
+
+{
+  const clampedHigh = Math.max(1, Math.min(10, Math.round(15)));
+  assertEq(clampedHigh, 10, "max_cycles above 10 clamped to 10");
+
+  const clampedLow = Math.max(1, Math.min(10, Math.round(0)));
+  assertEq(clampedLow, 1, "max_cycles below 1 clamped to 1");
+
+  const clampedNeg = Math.max(1, Math.min(10, Math.round(-5)));
+  assertEq(clampedNeg, 1, "negative max_cycles clamped to 1");
+
+  const normal = Math.max(1, Math.min(10, Math.round(3)));
+  assertEq(normal, 3, "normal max_cycles passes through");
+}
+
+console.log("\n=== Post-unit hook merging ===");
+
+{
+  const baseHooks = [
+    { name: "review", after: ["execute-task"], prompt: "base prompt" },
+    { name: "lint", after: ["plan-slice"], prompt: "lint code" },
+  ];
+
+  const overrideHooks = [
+    { name: "review", after: ["execute-task", "complete-slice"], prompt: "override prompt" },
+    { name: "security", after: ["execute-task"], prompt: "security check" },
+  ];
+
+  const merged = [...baseHooks];
+  for (const hook of overrideHooks) {
+    const idx = merged.findIndex(h => h.name === hook.name);
+    if (idx >= 0) {
+      merged[idx] = hook;
+    } else {
+      merged.push(hook);
+    }
+  }
+
+  assertEq(merged.length, 3, "merged has 3 hooks");
+  assertEq(merged[0].prompt, "override prompt", "review hook was overridden");
+  assertEq(merged[0].after.length, 2, "overridden review has 2 after entries");
+  assertEq(merged[1].name, "lint", "lint kept from base");
+  assertEq(merged[2].name, "security", "security added from override");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 2: Pre-Dispatch Hook Config Tests
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log("\n=== Pre-dispatch hook config shape ===");
+
+{
+  const modifyHook = {
+    name: "inject-context",
+    before: ["execute-task"],
+    action: "modify" as const,
+    prepend: "Remember to follow coding conventions.",
+    append: "Run tests after making changes.",
+    enabled: true,
+  };
+
+  assertEq(modifyHook.name, "inject-context", "modify hook has name");
+  assertEq(modifyHook.action, "modify", "action is modify");
+  assertTrue(!!modifyHook.prepend, "has prepend text");
+  assertTrue(!!modifyHook.append, "has append text");
+}
+
+{
+  const skipHook = {
+    name: "skip-research",
+    before: ["research-slice"],
+    action: "skip" as const,
+    skip_if: "RESEARCH-DONE.md",
+    enabled: true,
+  };
+
+  assertEq(skipHook.action, "skip", "action is skip");
+  assertEq(skipHook.skip_if, "RESEARCH-DONE.md", "has skip condition");
+}
+
+{
+  const replaceHook = {
+    name: "custom-planning",
+    before: ["plan-slice"],
+    action: "replace" as const,
+    prompt: "Use custom planning approach for {sliceId}",
+    unit_type: "custom-plan",
+    model: "claude-opus-4-6",
+    enabled: true,
+  };
+
+  assertEq(replaceHook.action, "replace", "action is replace");
+  assertTrue(!!replaceHook.prompt, "replace hook has prompt");
+  assertEq(replaceHook.unit_type, "custom-plan", "has unit_type override");
+}
+
+console.log("\n=== Pre-dispatch action validation ===");
+
+{
+  const validActions = new Set(["modify", "skip", "replace"]);
+  assertTrue(validActions.has("modify"), "modify is valid");
+  assertTrue(validActions.has("skip"), "skip is valid");
+  assertTrue(validActions.has("replace"), "replace is valid");
+  assertTrue(!validActions.has("delete"), "delete is not valid");
+  assertTrue(!validActions.has(""), "empty string is not valid");
+}
+
+console.log("\n=== Pre-dispatch hook merging ===");
+
+{
+  const baseHooks = [
+    { name: "inject", before: ["execute-task"], action: "modify" as const, prepend: "base" },
+  ];
+
+  const overrideHooks = [
+    { name: "inject", before: ["execute-task"], action: "modify" as const, prepend: "override" },
+    { name: "gate", before: ["plan-slice"], action: "skip" as const },
+  ];
+
+  const merged = [...baseHooks];
+  for (const hook of overrideHooks) {
+    const idx = merged.findIndex(h => h.name === hook.name);
+    if (idx >= 0) {
+      merged[idx] = hook;
+    } else {
+      merged.push(hook);
+    }
+  }
+
+  assertEq(merged.length, 2, "merged has 2 pre-dispatch hooks");
+  assertEq(merged[0].prepend, "override", "inject hook overridden");
+  assertEq(merged[1].name, "gate", "gate hook added");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Known unit types validation
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log("\n=== Known unit types ===");
+
+{
+  const knownUnitTypes = new Set([
+    "research-milestone", "plan-milestone", "research-slice", "plan-slice",
+    "execute-task", "complete-slice", "replan-slice", "reassess-roadmap",
+    "run-uat", "fix-merge", "complete-milestone",
+  ]);
+
+  assertTrue(knownUnitTypes.has("execute-task"), "execute-task is known");
+  assertTrue(knownUnitTypes.has("complete-slice"), "complete-slice is known");
+  assertTrue(knownUnitTypes.has("plan-slice"), "plan-slice is known");
+  assertTrue(!knownUnitTypes.has("hook/review"), "hook types are not in known set");
+  assertTrue(!knownUnitTypes.has("invalid-type"), "invalid types are not in known set");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Preferences YAML format verification
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log("\n=== Preferences YAML format ===");
+
+{
+  const prefsContent = [
+    "---",
+    "version: 1",
+    "post_unit_hooks:",
+    "  - name: code-review",
+    "    after:",
+    "      - execute-task",
+    "    prompt: Review the changes",
+    "    max_cycles: 3",
+    "    artifact: REVIEW-PASS.md",
+    "    retry_on: REVIEW-ISSUES.md",
+    "pre_dispatch_hooks:",
+    "  - name: inject-conventions",
+    "    before:",
+    "      - execute-task",
+    "    action: modify",
+    "    append: Follow project coding conventions",
+    "  - name: custom-research",
+    "    before:",
+    "      - research-slice",
+    "    action: replace",
+    "    prompt: Custom research prompt",
+    "---",
+  ].join("\n");
+
+  assertTrue(prefsContent.includes("post_unit_hooks:"), "has post_unit_hooks key");
+  assertTrue(prefsContent.includes("pre_dispatch_hooks:"), "has pre_dispatch_hooks key");
+  assertTrue(prefsContent.includes("action: modify"), "has modify action");
+  assertTrue(prefsContent.includes("action: replace"), "has replace action");
+}
+
+report();

package/src/resources/extensions/gsd/tests/regex-hardening.test.ts

@@ -67,6 +67,18 @@ async function main(): Promise<void> {
     assertEq('M001-abc123: Title'.replace(TITLE_STRIP_RE, ''), 'Title', 'strips M001-abc123: Title → Title');
     assertEq('M042-z9a8b7: Dashboard'.replace(TITLE_STRIP_RE, ''), 'Dashboard', 'strips M042-z9a8b7: Dashboard');
 
+    // Em dash in title — current format (M001: Title) correctly preserves em dash in title body
+    assertEq(
+      'M001: Foundation — Build Core'.replace(TITLE_STRIP_RE, ''),
+      'Foundation — Build Core',
+      'strips M001: prefix and preserves em dash in title body',
+    );
+    assertEq(
+      'M001-abc123: Foundation — Build Core'.replace(TITLE_STRIP_RE, ''),
+      'Foundation — Build Core',
+      'strips M001-abc123: prefix and preserves em dash in title body (unique format)',
+    );
+
     // Edge case: dash-style separator (M001 — Title: Subtitle preserves colon in body)
     assertEq(
       'M001 — Unique Milestone IDs: Foo'.replace(TITLE_STRIP_RE, ''),

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

@@ -185,3 +185,112 @@ export interface GSDState {
     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>;
+}