gsd-pi 2.11.0 → 2.13.0

package/dist/resources/extensions/gsd/guided-flow.ts

@@ -9,10 +9,12 @@
 import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { showNextAction } from "../shared/next-action-ui.js";
 import { loadFile, parseRoadmap } from "./files.js";
-import { loadPrompt } from "./prompt-loader.js";
+import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
 import { deriveState } from "./state.js";
 import { startAuto } from "./auto.js";
 import { readCrashLock, clearLock, formatCrashInfo } from "./crash-recovery.js";
+import { listUnitRuntimeRecords, clearUnitRuntimeRecord } from "./unit-runtime.js";
+import { resolveExpectedArtifactPath } from "./auto.js";
 import {
   gsdRoot, milestonesDir, resolveMilestoneFile, resolveMilestonePath,
   resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile,
@@ -97,11 +99,19 @@ function dispatchWorkflow(pi: ExtensionAPI, note: string, customType = "gsd-run"
  */
 function buildDiscussPrompt(nextId: string, preamble: string, _basePath: string): string {
   const milestoneRel = `.gsd/milestones/${nextId}`;
+  const inlinedTemplates = [
+    inlineTemplate("project", "Project"),
+    inlineTemplate("requirements", "Requirements"),
+    inlineTemplate("context", "Context"),
+    inlineTemplate("roadmap", "Roadmap"),
+    inlineTemplate("decisions", "Decisions"),
+  ].join("\n\n---\n\n");
   return loadPrompt("discuss", {
     milestoneId: nextId,
     preamble,
     contextPath: `${milestoneRel}/${nextId}-CONTEXT.md`,
     roadmapPath: `${milestoneRel}/${nextId}-ROADMAP.md`,
+    inlinedTemplates,
   });
 }
 
@@ -234,11 +244,13 @@ export async function showQueue(
   ].join(" ");
 
   // ── Dispatch the queue prompt ───────────────────────────────────────
+  const queueInlinedTemplates = inlineTemplate("context", "Context");
   const prompt = loadPrompt("queue", {
     preamble,
     nextId,
     nextIdPlus1,
     existingMilestonesContext: existingContext,
+    inlinedTemplates: queueInlinedTemplates,
   });
 
   pi.sendMessage(
@@ -415,6 +427,7 @@ async function buildDiscussSlicePrompt(
   const sliceDirPath = `.gsd/milestones/${mid}/slices/${sid}`;
   const sliceContextPath = `${sliceDirPath}/${sid}-CONTEXT.md`;
 
+  const inlinedTemplates = inlineTemplate("slice-context", "Slice Context");
   return loadPrompt("guided-discuss-slice", {
     milestoneId: mid,
     sliceId: sid,
@@ -423,6 +436,7 @@ async function buildDiscussSlicePrompt(
     sliceDirPath,
     contextPath: sliceContextPath,
     projectRoot: base,
+    inlinedTemplates,
   });
 }
 
@@ -506,6 +520,42 @@ export async function showDiscuss(
 /**
  * The one wizard. Reads state, shows contextual options, dispatches into the workflow doc.
  */
+/**
+ * Self-heal: scan runtime records and clear stale ones left behind when
+ * auto-mode crashed mid-unit. auto.ts has its own selfHealRuntimeRecords()
+ * but guided-flow (manual /gsd mode) never called it — meaning stale records
+ * persisted until the next /gsd auto run.  This ensures the wizard always
+ * starts from a clean state regardless of how the previous session ended.
+ */
+function selfHealRuntimeRecords(basePath: string, ctx: ExtensionContext): { cleared: number } {
+  try {
+    const records = listUnitRuntimeRecords(basePath);
+    let cleared = 0;
+    for (const record of records) {
+      const { unitType, unitId, phase } = record;
+      // Clear records whose expected artifact already exists (completed but not cleaned up)
+      const artifactPath = resolveExpectedArtifactPath(unitType, unitId, basePath);
+      if (artifactPath && existsSync(artifactPath)) {
+        clearUnitRuntimeRecord(basePath, unitType, unitId);
+        cleared++;
+        continue;
+      }
+      // Clear records stuck in dispatched or timeout phase (process died mid-unit)
+      if (phase === "dispatched" || phase === "timeout") {
+        clearUnitRuntimeRecord(basePath, unitType, unitId);
+        cleared++;
+      }
+    }
+    if (cleared > 0) {
+      ctx.ui.notify(`Self-heal: cleared ${cleared} stale runtime record(s) from a previous session.`, "info");
+    }
+    return { cleared };
+  } catch {
+    // Non-fatal — self-heal should never block the wizard
+    return { cleared: 0 };
+  }
+}
+
 export async function showSmartEntry(
   ctx: ExtensionCommandContext,
   pi: ExtensionAPI,
@@ -544,6 +594,9 @@ export async function showSmartEntry(
     }
   }
 
+  // ── Self-heal stale runtime records from crashed auto-mode sessions ──
+  selfHealRuntimeRecords(basePath, ctx);
+
   // Check for crash from previous auto-mode session
   const crashLock = readCrashLock(basePath);
   if (crashLock) {
@@ -683,8 +736,9 @@ export async function showSmartEntry(
     });
 
     if (choice === "discuss_draft") {
+      const discussMilestoneTemplates = inlineTemplate("context", "Context");
       const basePrompt = loadPrompt("guided-discuss-milestone", {
-        milestoneId, milestoneTitle,
+        milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates,
       });
       const seed = draftContent
         ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}`
@@ -692,9 +746,10 @@ export async function showSmartEntry(
       pendingAutoStart = { ctx, pi, basePath, milestoneId, step: stepMode };
       dispatchWorkflow(pi, seed, "gsd-discuss");
     } else if (choice === "discuss_fresh") {
+      const discussMilestoneTemplates = inlineTemplate("context", "Context");
       pendingAutoStart = { ctx, pi, basePath, milestoneId, step: stepMode };
       dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", {
-        milestoneId, milestoneTitle,
+        milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates,
       }), "gsd-discuss");
     } else if (choice === "skip_milestone") {
       const milestoneIds = findMilestoneIds(basePath);
@@ -753,13 +808,20 @@ export async function showSmartEntry(
       });
 
       if (choice === "plan") {
+        const planMilestoneTemplates = [
+          inlineTemplate("roadmap", "Roadmap"),
+          inlineTemplate("plan", "Slice Plan"),
+          inlineTemplate("task-plan", "Task Plan"),
+          inlineTemplate("secrets-manifest", "Secrets Manifest"),
+        ].join("\n\n---\n\n");
         const secretsOutputPath = relMilestoneFile(basePath, milestoneId, "SECRETS");
         dispatchWorkflow(pi, loadPrompt("guided-plan-milestone", {
-          milestoneId, milestoneTitle, secretsOutputPath,
+          milestoneId, milestoneTitle, secretsOutputPath, inlinedTemplates: planMilestoneTemplates,
         }));
       } else if (choice === "discuss") {
+        const discussMilestoneTemplates = inlineTemplate("context", "Context");
         dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", {
-          milestoneId, milestoneTitle,
+          milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates,
         }));
       } else if (choice === "skip_milestone") {
         const milestoneIds = findMilestoneIds(basePath);
@@ -866,14 +928,19 @@ export async function showSmartEntry(
     });
 
     if (choice === "plan") {
+      const planSliceTemplates = [
+        inlineTemplate("plan", "Slice Plan"),
+        inlineTemplate("task-plan", "Task Plan"),
+      ].join("\n\n---\n\n");
       dispatchWorkflow(pi, loadPrompt("guided-plan-slice", {
-        milestoneId, sliceId, sliceTitle,
+        milestoneId, sliceId, sliceTitle, inlinedTemplates: planSliceTemplates,
       }));
     } else if (choice === "discuss") {
       dispatchWorkflow(pi, await buildDiscussSlicePrompt(milestoneId, sliceId, sliceTitle, basePath));
     } else if (choice === "research") {
+      const researchTemplates = inlineTemplate("research", "Research");
       dispatchWorkflow(pi, loadPrompt("guided-research-slice", {
-        milestoneId, sliceId, sliceTitle,
+        milestoneId, sliceId, sliceTitle, inlinedTemplates: researchTemplates,
       }));
     } else if (choice === "status") {
       const { fireStatusViaCommand } = await import("./commands.js");
@@ -904,8 +971,12 @@ export async function showSmartEntry(
     });
 
     if (choice === "complete") {
+      const completeSliceTemplates = [
+        inlineTemplate("slice-summary", "Slice Summary"),
+        inlineTemplate("uat", "UAT"),
+      ].join("\n\n---\n\n");
       dispatchWorkflow(pi, loadPrompt("guided-complete-slice", {
-        milestoneId, sliceId, sliceTitle,
+        milestoneId, sliceId, sliceTitle, inlinedTemplates: completeSliceTemplates,
       }));
     } else if (choice === "status") {
       const { fireStatusViaCommand } = await import("./commands.js");
@@ -965,8 +1036,9 @@ export async function showSmartEntry(
           milestoneId, sliceId,
         }));
       } else {
+        const executeTaskTemplates = inlineTemplate("task-summary", "Task Summary");
         dispatchWorkflow(pi, loadPrompt("guided-execute-task", {
-          milestoneId, sliceId, taskId, taskTitle,
+          milestoneId, sliceId, taskId, taskTitle, inlinedTemplates: executeTaskTemplates,
         }));
       }
     } else if (choice === "status") {

package/dist/resources/extensions/gsd/post-unit-hooks.ts

@@ -0,0 +1,449 @@
+// GSD Extension — Hook Engine (Post-Unit, Pre-Dispatch, State Persistence)
+// Manages hook queue, cycle tracking, artifact verification, pre-dispatch
+// interception, and durable hook state for user-configured extensibility.
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import type {
+  PostUnitHookConfig,
+  PreDispatchHookConfig,
+  HookExecutionState,
+  HookDispatchResult,
+  PreDispatchResult,
+  PersistedHookState,
+  HookStatusEntry,
+} from "./types.js";
+import { resolvePostUnitHooks, resolvePreDispatchHooks } from "./preferences.js";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+// ─── Hook Queue State ──────────────────────────────────────────────────────
+
+/** Currently executing hook, or null if in normal dispatch flow. */
+let activeHook: HookExecutionState | null = null;
+
+/** Queue of hooks remaining for the current trigger unit. */
+let hookQueue: Array<{
+  config: PostUnitHookConfig;
+  triggerUnitType: string;
+  triggerUnitId: string;
+}> = [];
+
+/** Cycle counts per hook+trigger, keyed as "hookName/triggerUnitType/triggerUnitId". */
+const cycleCounts = new Map<string, number>();
+
+/** Set when a hook completes with retry_on artifact present — signals caller to re-run trigger. */
+let retryPending = false;
+
+/** Stores the trigger unit info for pending retries so caller knows what to re-run. */
+let retryTrigger: { unitType: string; unitId: string } | null = null;
+
+// ─── Public API ────────────────────────────────────────────────────────────
+
+/**
+ * Called after a unit completes. Returns the next hook unit to dispatch,
+ * or null if no hooks apply (normal dispatch should proceed).
+ *
+ * Call flow:
+ * 1. A core unit (e.g. execute-task) completes → handleAgentEnd calls this
+ * 2. If hooks match, returns first hook to dispatch. Caller sends the prompt.
+ * 3. Hook unit completes → handleAgentEnd calls this again (activeHook is set)
+ * 4. Checks retry_on / next hook / done → returns next action or null
+ */
+export function checkPostUnitHooks(
+  completedUnitType: string,
+  completedUnitId: string,
+  basePath: string,
+): HookDispatchResult | null {
+  // If we just completed a hook unit, handle its result
+  if (activeHook) {
+    return handleHookCompletion(basePath);
+  }
+
+  // Don't trigger hooks for other hook units (prevent hook-on-hook chains)
+  if (completedUnitType.startsWith("hook/")) return null;
+
+  // Check if any hooks are configured for this unit type
+  const hooks = resolvePostUnitHooks().filter(h =>
+    h.after.includes(completedUnitType),
+  );
+  if (hooks.length === 0) return null;
+
+  // Build hook queue for this trigger
+  hookQueue = hooks.map(config => ({
+    config,
+    triggerUnitType: completedUnitType,
+    triggerUnitId: completedUnitId,
+  }));
+
+  return dequeueNextHook(basePath);
+}
+
+/**
+ * Returns whether a hook is currently active (for progress display).
+ */
+export function getActiveHook(): HookExecutionState | null {
+  return activeHook;
+}
+
+/**
+ * Returns true if a retry of the trigger unit was requested by a hook.
+ * Caller should re-dispatch the original trigger unit, then hooks will
+ * fire again on its next completion.
+ */
+export function isRetryPending(): boolean {
+  return retryPending;
+}
+
+/**
+ * Returns the trigger unit info for a pending retry, or null.
+ * Clears the retry state after reading.
+ */
+export function consumeRetryTrigger(): { unitType: string; unitId: string } | null {
+  if (!retryPending || !retryTrigger) return null;
+  const trigger = { ...retryTrigger };
+  retryPending = false;
+  retryTrigger = null;
+  return trigger;
+}
+
+/**
+ * Reset all hook state. Called on auto-mode start/stop.
+ */
+export function resetHookState(): void {
+  activeHook = null;
+  hookQueue = [];
+  cycleCounts.clear();
+  retryPending = false;
+  retryTrigger = null;
+}
+
+// ─── Internal ──────────────────────────────────────────────────────────────
+
+function dequeueNextHook(basePath: string): HookDispatchResult | null {
+  while (hookQueue.length > 0) {
+    const entry = hookQueue.shift()!;
+    const { config, triggerUnitType, triggerUnitId } = entry;
+
+    // Check idempotency — if artifact already exists, skip this hook
+    if (config.artifact) {
+      const artifactPath = resolveHookArtifactPath(basePath, triggerUnitId, config.artifact);
+      if (existsSync(artifactPath)) continue;
+    }
+
+    // Check cycle limit
+    const cycleKey = `${config.name}/${triggerUnitType}/${triggerUnitId}`;
+    const currentCycle = (cycleCounts.get(cycleKey) ?? 0) + 1;
+    const maxCycles = config.max_cycles ?? 1;
+    if (currentCycle > maxCycles) continue;
+
+    cycleCounts.set(cycleKey, currentCycle);
+
+    activeHook = {
+      hookName: config.name,
+      triggerUnitType,
+      triggerUnitId,
+      cycle: currentCycle,
+      pendingRetry: false,
+    };
+
+    // Build the prompt with variable substitution
+    const [mid, sid, tid] = triggerUnitId.split("/");
+    const prompt = config.prompt
+      .replace(/\{milestoneId\}/g, mid ?? "")
+      .replace(/\{sliceId\}/g, sid ?? "")
+      .replace(/\{taskId\}/g, tid ?? "");
+
+    return {
+      hookName: config.name,
+      prompt,
+      model: config.model,
+      unitType: `hook/${config.name}`,
+      unitId: triggerUnitId,
+    };
+  }
+
+  // No more hooks — clear active state and return null for normal dispatch
+  activeHook = null;
+  return null;
+}
+
+function handleHookCompletion(basePath: string): HookDispatchResult | null {
+  const hook = activeHook!;
+  const hooks = resolvePostUnitHooks();
+  const config = hooks.find(h => h.name === hook.hookName);
+
+  // Check if retry was requested via retry_on artifact
+  if (config?.retry_on) {
+    const retryArtifactPath = resolveHookArtifactPath(basePath, hook.triggerUnitId, config.retry_on);
+    if (existsSync(retryArtifactPath)) {
+      // Check cycle limit before allowing retry
+      const cycleKey = `${config.name}/${hook.triggerUnitType}/${hook.triggerUnitId}`;
+      const currentCycle = cycleCounts.get(cycleKey) ?? 1;
+      const maxCycles = config.max_cycles ?? 1;
+
+      if (currentCycle < maxCycles) {
+        // Signal retry — caller will re-dispatch the trigger unit
+        activeHook = null;
+        hookQueue = [];
+        retryPending = true;
+        retryTrigger = { unitType: hook.triggerUnitType, unitId: hook.triggerUnitId };
+        return null;
+      }
+      // Max cycles reached — fall through to normal completion
+    }
+  }
+
+  // Hook completed normally — try next hook in queue
+  activeHook = null;
+  return dequeueNextHook(basePath);
+}
+
+/**
+ * Resolve the path where a hook artifact is expected to be written.
+ * Uses the trigger unit's directory context:
+ *   - Task-level (M001/S01/T01): .gsd/M001/slices/S01/tasks/T01-{artifact}
+ *   - Slice-level (M001/S01):    .gsd/M001/slices/S01/{artifact}
+ *   - Milestone-level (M001):    .gsd/M001/{artifact}
+ */
+export function resolveHookArtifactPath(basePath: string, unitId: string, artifactName: string): string {
+  const parts = unitId.split("/");
+  if (parts.length === 3) {
+    const [mid, sid, tid] = parts;
+    return join(basePath, ".gsd", mid, "slices", sid, "tasks", `${tid}-${artifactName}`);
+  }
+  if (parts.length === 2) {
+    const [mid, sid] = parts;
+    return join(basePath, ".gsd", mid, "slices", sid, artifactName);
+  }
+  return join(basePath, ".gsd", parts[0], artifactName);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 2: Pre-Dispatch Hooks
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Run pre-dispatch hooks for a unit about to be dispatched.
+ * Returns a result indicating whether the unit should proceed (with optional
+ * prompt modifications), be skipped, or be replaced entirely.
+ *
+ * Multiple hooks can fire for the same unit type. They compose:
+ * - "modify" hooks stack (all prepend/append applied in order)
+ * - "skip" short-circuits (first matching skip wins)
+ * - "replace" short-circuits (first matching replace wins)
+ * - Skip/replace hooks take precedence over modify hooks
+ */
+export function runPreDispatchHooks(
+  unitType: string,
+  unitId: string,
+  prompt: string,
+  basePath: string,
+): PreDispatchResult {
+  // Don't intercept hook units
+  if (unitType.startsWith("hook/")) {
+    return { action: "proceed", prompt, firedHooks: [] };
+  }
+
+  const hooks = resolvePreDispatchHooks().filter(h =>
+    h.before.includes(unitType),
+  );
+  if (hooks.length === 0) {
+    return { action: "proceed", prompt, firedHooks: [] };
+  }
+
+  const [mid, sid, tid] = unitId.split("/");
+  const substitute = (text: string): string =>
+    text
+      .replace(/\{milestoneId\}/g, mid ?? "")
+      .replace(/\{sliceId\}/g, sid ?? "")
+      .replace(/\{taskId\}/g, tid ?? "");
+
+  const firedHooks: string[] = [];
+  let currentPrompt = prompt;
+
+  for (const hook of hooks) {
+    if (hook.action === "skip") {
+      // Check optional skip condition
+      if (hook.skip_if) {
+        const conditionPath = resolveHookArtifactPath(basePath, unitId, hook.skip_if);
+        if (!existsSync(conditionPath)) continue; // Condition not met, don't skip
+      }
+      firedHooks.push(hook.name);
+      return { action: "skip", firedHooks };
+    }
+
+    if (hook.action === "replace") {
+      firedHooks.push(hook.name);
+      return {
+        action: "replace",
+        prompt: substitute(hook.prompt ?? ""),
+        unitType: hook.unit_type,
+        model: hook.model,
+        firedHooks,
+      };
+    }
+
+    if (hook.action === "modify") {
+      firedHooks.push(hook.name);
+      if (hook.prepend) {
+        currentPrompt = `${substitute(hook.prepend)}\n\n${currentPrompt}`;
+      }
+      if (hook.append) {
+        currentPrompt = `${currentPrompt}\n\n${substitute(hook.append)}`;
+      }
+    }
+  }
+
+  return {
+    action: "proceed",
+    prompt: currentPrompt,
+    model: hooks.find(h => h.action === "modify" && h.model)?.model,
+    firedHooks,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 3: Hook State Persistence
+// ═══════════════════════════════════════════════════════════════════════════
+
+const HOOK_STATE_FILE = "hook-state.json";
+
+function hookStatePath(basePath: string): string {
+  return join(basePath, ".gsd", HOOK_STATE_FILE);
+}
+
+/**
+ * Persist current hook cycle counts to disk so they survive crashes/restarts.
+ * Called after each hook dispatch and on auto-mode pause.
+ */
+export function persistHookState(basePath: string): void {
+  const state: PersistedHookState = {
+    cycleCounts: Object.fromEntries(cycleCounts),
+    savedAt: new Date().toISOString(),
+  };
+  try {
+    const dir = join(basePath, ".gsd");
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(hookStatePath(basePath), JSON.stringify(state, null, 2), "utf-8");
+  } catch {
+    // Non-fatal — state is recreatable from artifacts
+  }
+}
+
+/**
+ * Restore hook cycle counts from disk after a crash/restart.
+ * Called during auto-mode resume.
+ */
+export function restoreHookState(basePath: string): void {
+  try {
+    const filePath = hookStatePath(basePath);
+    if (!existsSync(filePath)) return;
+    const raw = readFileSync(filePath, "utf-8");
+    const state: PersistedHookState = JSON.parse(raw);
+    if (state.cycleCounts && typeof state.cycleCounts === "object") {
+      cycleCounts.clear();
+      for (const [key, value] of Object.entries(state.cycleCounts)) {
+        if (typeof value === "number") {
+          cycleCounts.set(key, value);
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — fresh state is fine
+  }
+}
+
+/**
+ * Clear persisted hook state file from disk.
+ * Called on clean auto-mode stop.
+ */
+export function clearPersistedHookState(basePath: string): void {
+  try {
+    const filePath = hookStatePath(basePath);
+    if (existsSync(filePath)) {
+      writeFileSync(filePath, JSON.stringify({ cycleCounts: {}, savedAt: new Date().toISOString() }, null, 2), "utf-8");
+    }
+  } catch {
+    // Non-fatal
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 3: Hook Status Reporting
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get status of all configured hooks for display by /gsd hooks.
+ */
+export function getHookStatus(): HookStatusEntry[] {
+  const entries: HookStatusEntry[] = [];
+
+  // Post-unit hooks
+  const postHooks = resolvePostUnitHooks();
+  for (const hook of postHooks) {
+    const activeCycles: Record<string, number> = {};
+    for (const [key, count] of cycleCounts) {
+      if (key.startsWith(`${hook.name}/`)) {
+        activeCycles[key] = count;
+      }
+    }
+    entries.push({
+      name: hook.name,
+      type: "post",
+      enabled: hook.enabled !== false,
+      targets: hook.after,
+      activeCycles,
+    });
+  }
+
+  // Pre-dispatch hooks
+  const preHooks = resolvePreDispatchHooks();
+  for (const hook of preHooks) {
+    entries.push({
+      name: hook.name,
+      type: "pre",
+      enabled: hook.enabled !== false,
+      targets: hook.before,
+      activeCycles: {},
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * Format hook status for terminal display.
+ */
+export function formatHookStatus(): string {
+  const entries = getHookStatus();
+  if (entries.length === 0) {
+    return "No hooks configured. Add post_unit_hooks or pre_dispatch_hooks to .gsd/preferences.md";
+  }
+
+  const lines: string[] = ["Configured Hooks:", ""];
+
+  const postHooks = entries.filter(e => e.type === "post");
+  const preHooks = entries.filter(e => e.type === "pre");
+
+  if (postHooks.length > 0) {
+    lines.push("Post-Unit Hooks (run after unit completes):");
+    for (const hook of postHooks) {
+      const status = hook.enabled ? "enabled" : "disabled";
+      const cycles = Object.keys(hook.activeCycles).length;
+      const cycleInfo = cycles > 0 ? ` (${cycles} active cycle${cycles === 1 ? "" : "s"})` : "";
+      lines.push(`  ${hook.name} [${status}] → after: ${hook.targets.join(", ")}${cycleInfo}`);
+    }
+    lines.push("");
+  }
+
+  if (preHooks.length > 0) {
+    lines.push("Pre-Dispatch Hooks (run before unit dispatches):");
+    for (const hook of preHooks) {
+      const status = hook.enabled ? "enabled" : "disabled";
+      lines.push(`  ${hook.name} [${status}] → before: ${hook.targets.join(", ")}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}