intentdna 1.5.14 → 1.5.16

package/dist/hooks/enforce.js

@@ -13,7 +13,7 @@
  *
  * Step checkpoints are handled by the CLI, not here.
  */
-import { allowOutput, blockOutput, escalateOutput, silentOutput } from "./protocol.js";
+import { allowOutput, blockOutput, escalateOutput } from "./protocol.js";
 import { relative, normalize } from "node:path";
 // ── PreToolUse Enforcement ─────────────────────────────────
 /**
@@ -27,43 +27,42 @@ export function enforcePreToolUse(ir, input, state, roles) {
     if (state?.workflowState && ir.workflows_ir) {
         const stepRuleResult = enforceStepRules(ir, input, state);
         if (stepRuleResult !== null)
-            return stepRuleResult;
+            return { output: stepRuleResult, trace: { matched_rule: "step_rule", step_id: state.workflowState.current_step } };
     }
     // Layer 2: Role scope
     if (input.agent_type && ir.roles_scope_map && ir.roles_scope_map.length > 0) {
-        // G4: Check if scope is relaxed by iteration-based rule
         const relaxed = isStepScopeRelaxed(ir, state);
         if (!relaxed) {
             const result = enforceRoleScope(ir.roles_scope_map, input, getStepAdditionalPaths(ir, state));
             if (result)
-                return result;
+                return { output: result, trace: { matched_rule: "scope", role: input.agent_type } };
         }
     }
     // Layer 3: Tool filters
     if (ir.tool_filters.length > 0) {
         const result = enforceToolFilters(ir.tool_filters, input);
         if (result)
-            return result;
+            return { output: result, trace: { matched_rule: "filter" } };
     }
     // Layer 4: Pre-execution gates
     if (ir.pre_execution_gates.length > 0) {
         const result = enforceGates(ir.pre_execution_gates, input);
         if (result)
-            return result;
+            return { output: result, trace: { matched_rule: "gate" } };
     }
     // Layer 5: Output schema
     if (roles && input.tool_name === "Write") {
         const result = enforceOutputSchema(roles, input);
         if (result)
-            return result;
+            return { output: result, trace: { matched_rule: "output_schema" } };
     }
     // Layer 6: Handoff — check consumed artifacts are available
     if (state?.workflowState && ir.workflows_ir) {
         const result = enforceHandoffConsumes(ir, state.workflowState, state.existingArtifactPaths);
         if (result)
-            return result;
+            return { output: result, trace: { matched_rule: "handoff", step_id: state.workflowState.current_step } };
     }
-    return silentOutput();
+    return null;
 }
 // ── PostToolUse Enforcement ────────────────────────────────
 /**
@@ -92,8 +91,13 @@ export function enforcePostToolUse(ir, input) {
         }
     }
     if (lines.length === 0)
-        return silentOutput();
-    return allowOutput(lines.join("\n"));
+        return null;
+    // Audit-only path: validator entries emit audit lines, plus bash scope WARN lines.
+    // If any bash scope violation was found use "scope" (real path match); otherwise
+    // this is validator-only output — use "validator" for accurate trace semantics.
+    const hasScopeViolation = lines.some(l => l.startsWith("WARN"));
+    const matchedRule = hasScopeViolation ? "scope" : "validator";
+    return { output: allowOutput(lines.join("\n")), trace: { matched_rule: matchedRule } };
 }
 // ── UserPromptSubmit Enforcement ───────────────────────────
 /**
@@ -103,7 +107,7 @@ export function enforcePostToolUse(ir, input) {
 export function enforceUserPromptSubmit(ir, _input) {
     const highPriority = ir.prompt_directives.filter(d => d.priority === "high");
     if (highPriority.length === 0)
-        return silentOutput();
+        return null;
     const lines = [
         "<system-reminder>[Intent DNA] Active high-priority policies:",
     ];
@@ -111,7 +115,7 @@ export function enforceUserPromptSubmit(ir, _input) {
         lines.push(`  - [${d.source_gene}] ${d.text}`);
     }
     lines.push("</system-reminder>");
-    return allowOutput(lines.join("\n"));
+    return { output: allowOutput(lines.join("\n")) };
 }
 // ── SubagentStop Enforcement ───────────────────────────────
 /**
@@ -120,9 +124,9 @@ export function enforceUserPromptSubmit(ir, _input) {
 export function enforceSubagentStop(ir, input) {
     const rolesScopeMap = ir.roles_scope_map;
     if (!rolesScopeMap || rolesScopeMap.length === 0)
-        return silentOutput();
+        return null;
     if (!input.agent_type)
-        return silentOutput();
+        return null;
     for (const entry of rolesScopeMap) {
         const agentTypeName = `dna-${toKebabCase(entry.role_name)}`;
         if (input.agent_type === agentTypeName) {
@@ -130,10 +134,15 @@ export function enforceSubagentStop(ir, input) {
             const scopeDesc = writeGlobs.length > 0
                 ? `write:[${writeGlobs.join(",")}]`
                 : "write:[]";
-            return allowOutput(`[Intent DNA] SubagentStop audit: role=${entry.role_name} agent=${input.agent_name ?? "unknown"} scope=${scopeDesc}`);
+            return {
+                output: allowOutput(`[Intent DNA] SubagentStop audit: role=${entry.role_name} agent=${input.agent_name ?? "unknown"} scope=${scopeDesc}`),
+                trace: { matched_rule: "scope", role: entry.role_name },
+            };
         }
     }
-    return allowOutput(`[Intent DNA] SubagentStop: unknown role for agent_type=${input.agent_type}`);
+    return {
+        output: allowOutput(`[Intent DNA] SubagentStop: unknown role for agent_type=${input.agent_type}`),
+    };
 }
 // ── PreCompact Enforcement ─────────────────────────────────
 /**
@@ -145,7 +154,7 @@ export function enforcePreCompact(ir, workflowContext) {
     const hasRoles = ir.roles_scope_map && ir.roles_scope_map.length > 0;
     const hasWorkflow = !!workflowContext;
     if (!hasDirectives && !hasRoles && !hasWorkflow)
-        return silentOutput();
+        return null;
     const critical = ir.prompt_directives.filter(d => d.priority === "high");
     const standard = ir.prompt_directives.filter(d => d.priority === "medium");
     const lines = [
@@ -176,7 +185,7 @@ export function enforcePreCompact(ir, workflowContext) {
     if (hasWorkflow) {
         lines.push(`  Active workflow: ${workflowContext.workflow} (step: ${workflowContext.current_step}, role: ${workflowContext.current_role})`);
     }
-    return allowOutput(lines.join("\n"));
+    return { output: allowOutput(lines.join("\n")) };
 }
 // ── Notification Enforcement ───────────────────────────────
 /**
@@ -187,12 +196,14 @@ export function enforceNotification(ir, input) {
     const blockGates = ir.pre_execution_gates.filter(g => g.action === "block" || g.action === "escalate");
     const blockFilters = ir.tool_filters.filter(f => f.action === "remove");
     if (blockGates.length === 0 && blockFilters.length === 0)
-        return silentOutput();
+        return null;
     const message = input.message ?? "";
     if (message.includes("Intent DNA")) {
-        return allowOutput(`[Intent DNA] Notification: violation detected — ${input.title ?? "untitled"}: ${message}`);
+        return {
+            output: allowOutput(`[Intent DNA] Notification: violation detected — ${input.title ?? "untitled"}: ${message}`),
+        };
     }
-    return silentOutput();
+    return null;
 }
 // ── SessionStart Enforcement ───────────────────────────────
 /**
@@ -200,16 +211,14 @@ export function enforceNotification(ir, input) {
  * Returns silent if no DNA policies are active.
  */
 export function enforceSessionStart(ir, input) {
-    // Check if there's anything meaningful to report
     const directiveCount = ir.prompt_directives.length;
     const gateCount = ir.pre_execution_gates.length;
     const filterCount = ir.tool_filters.length;
     const roleCount = ir.roles_scope_map?.length ?? 0;
     const workflowCount = ir.workflows_ir?.length ?? 0;
     if (directiveCount === 0 && gateCount === 0 && filterCount === 0 && roleCount === 0) {
-        return silentOutput();
+        return null;
     }
-    // Build policy summary
     const lines = [
         "[Intent DNA] Session initialized — active governance:",
     ];
@@ -230,7 +239,7 @@ export function enforceSessionStart(ir, input) {
     if (stats.length > 0) {
         lines.push(`  Enforcement: ${stats.join(", ")}`);
     }
-    return allowOutput(lines.join("\n"), "SessionStart");
+    return { output: allowOutput(lines.join("\n"), "SessionStart") };
 }
 /**
  * Enforce Stop hook — verify workflow checkpoint completion.
@@ -245,31 +254,25 @@ export function enforceSessionStart(ir, input) {
  *   - Workflow active + unmet checkpoints for current step
  */
 export function enforceStop(ir, input, workflowState) {
-    // Safety valve 1: no workflow state → silent
     if (!workflowState || !workflowState.active) {
-        return silentOutput();
+        return null;
     }
-    // Safety valve 2: context_limit stops → NEVER block
     const reason = input.stop_reason ?? "";
     if (reason.includes("context_limit") || reason.includes("context_window")) {
-        return silentOutput();
+        return null;
     }
-    // Safety valve 3: user abort → don't block
     if (reason === "user_abort" || reason === "sigint") {
-        return silentOutput();
+        return null;
     }
-    // Safety valve 4: stale state (>2h)
     const STALE_MS = 2 * 60 * 60 * 1000;
     if (workflowState.started_at) {
         const age = Date.now() - new Date(workflowState.started_at).getTime();
         if (age > STALE_MS) {
-            return silentOutput();
+            return null;
         }
     }
-    // Check for unmet checkpoints in current step
     const checkpoints = ir.step_checkpoints ?? [];
     const currentStepCheckpoints = checkpoints.filter(cp => cp.step_id === workflowState.current_step);
-    // Also check workflows_ir for the active workflow's checkpoints
     let workflowCheckpoints = currentStepCheckpoints;
     if (ir.workflows_ir && ir.workflows_ir.length > 0) {
         const activeWf = ir.workflows_ir.find(w => w.workflow_name === workflowState.workflow);
@@ -281,27 +284,27 @@ export function enforceStop(ir, input, workflowState) {
         }
     }
     if (workflowCheckpoints.length === 0) {
-        return silentOutput(); // No checkpoints for current step
+        return null;
     }
-    // Build list of blocking checkpoints
     const blocking = workflowCheckpoints.flatMap(cp => cp.checkpoints.filter(c => (c.action ?? "block") === "block"));
     if (blocking.length === 0) {
-        // No checkpoint blocking — check handoff produces
         if (workflowState.workflow) {
             const handoffResult = enforceHandoffProduces(ir, {
                 current_step: workflowState.current_step,
                 workflow: workflowState.workflow,
                 completed_artifacts: workflowState.completed_artifacts,
             });
-            if (handoffResult && !handoffResult.continue)
+            if (handoffResult)
                 return handoffResult;
         }
-        return silentOutput();
+        return null;
     }
-    // Block: workflow active with unmet checkpoints
     const messages = blocking.map(c => c.message);
-    return blockOutput(`[Intent DNA] Workflow '${workflowState.workflow}' has unmet checkpoints at step '${workflowState.current_step}':\n` +
-        messages.map(m => `  - ${m}`).join("\n"));
+    return {
+        output: blockOutput(`[Intent DNA] Workflow '${workflowState.workflow}' has unmet checkpoints at step '${workflowState.current_step}':\n` +
+            messages.map(m => `  - ${m}`).join("\n")),
+        trace: { matched_rule: "handoff", step_id: workflowState.current_step },
+    };
 }
 // ── G4: State-driven Step Enforcement ─────────────────────
 /** Write tools that step read_only rule should block */
@@ -393,10 +396,12 @@ export function enforceHandoffProduces(ir, wfState) {
     if (!currentEntry?.produces || currentEntry.produces.length === 0)
         return null;
     const currentArtifacts = (wfState.completed_artifacts ?? []).find(a => a.step_id === wfState.current_step);
-    // Check that each produced artifact with a path has been recorded
     for (const produced of currentEntry.produces) {
         if (produced.path && (!currentArtifacts || !currentArtifacts.artifacts.some(a => a.path === produced.path))) {
-            return blockOutput(`[Intent DNA] Step '${wfState.current_step}' must produce artifact '${produced.description}' (path: ${produced.path}) before proceeding.`);
+            return {
+                output: blockOutput(`[Intent DNA] Step '${wfState.current_step}' must produce artifact '${produced.description}' (path: ${produced.path}) before proceeding.`),
+                trace: { matched_rule: "handoff", step_id: wfState.current_step },
+            };
         }
     }
     return null;
@@ -712,3 +717,13 @@ export function checkContextReadiness(sessionReads, required) {
     const missing = required.filter(f => !readSet.has(f));
     return { ready: missing.length === 0, missing };
 }
+// ── Workflow Boundary Gate ────────────────────────────────────
+export function checkWorkflowBoundary(workflowCompleted, targetSkill) {
+    if (workflowCompleted) {
+        return {
+            output: blockOutput(`[Intent DNA] Workflow completed. Cannot start skill '${targetSkill}'.`),
+            trace: { matched_rule: "workflow_boundary" },
+        };
+    }
+    return { output: allowOutput() };
+}

package/dist/hooks/protocol.d.ts

@@ -54,6 +54,17 @@ export interface HookOutput {
         permissionDecision?: "ask" | "allow" | "deny";
     };
 }
+export type MatchedRule = "scope" | "filter" | "gate" | "schema" | "validator" | "handoff" | "step_rule" | "output_schema" | "context_gate" | "reflection_gate" | "workflow_boundary";
+export interface TraceMetadata {
+    matched_rule: MatchedRule;
+    gene_id?: string;
+    step_id?: string;
+    role?: string;
+}
+export interface EnforceResult {
+    output: HookOutput;
+    trace?: TraceMetadata;
+}
 /** Create an allow output, optionally injecting text into the conversation. */
 export declare function allowOutput(additionalContext?: string, hookEventName?: string): HookOutput;
 /** Create a block output with reason. */

package/dist/hooks/schema.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Hook input validation — CC protocol boundary.
+ * Zero external dependencies. Hand-written validators.
+ * Fail-open: invalid input → log warning + return { valid: false, ... }
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    normalized?: Record<string, unknown>;
+}
+/**
+ * Validate hook input against expected schema for each event type.
+ * Returns normalized input (camelCase) on success.
+ */
+export declare function validateHookInput(event: string, raw: unknown): ValidationResult;
+/**
+ * Normalize session_id field from various formats:
+ * - session_id (snake_case from CC)
+ * - sessionId (camelCase internal)
+ * - CLAUDE_SESSION_ID (env var fallback)
+ */
+export declare function normalizeSessionId(input: Record<string, unknown>): string | undefined;

package/dist/hooks/schema.js

@@ -0,0 +1,86 @@
+/**
+ * Hook input validation — CC protocol boundary.
+ * Zero external dependencies. Hand-written validators.
+ * Fail-open: invalid input → log warning + return { valid: false, ... }
+ */
+/**
+ * Validate hook input against expected schema for each event type.
+ * Returns normalized input (camelCase) on success.
+ */
+export function validateHookInput(event, raw) {
+    if (typeof raw !== "object" || raw === null) {
+        return { valid: false, errors: ["Input must be an object"] };
+    }
+    const input = raw;
+    const errors = [];
+    const normalized = { ...input };
+    // Normalize session_id to sessionId
+    const sessionId = normalizeSessionId(input);
+    if (sessionId !== undefined) {
+        normalized.sessionId = sessionId;
+        delete normalized.session_id;
+    }
+    switch (event) {
+        case "PreToolUse":
+            if (typeof input.tool_name !== "string") {
+                errors.push("PreToolUse: tool_name must be a string");
+            }
+            if (typeof input.tool_input !== "object" || input.tool_input === null) {
+                errors.push("PreToolUse: tool_input must be an object");
+            }
+            break;
+        case "PostToolUse":
+            if (typeof input.tool_name !== "string") {
+                errors.push("PostToolUse: tool_name must be a string");
+            }
+            if (typeof input.tool_input !== "object" || input.tool_input === null) {
+                errors.push("PostToolUse: tool_input must be an object");
+            }
+            // tool_output is optional
+            break;
+        case "SessionStart":
+            // session_id is optional but should be normalized if present
+            break;
+        case "SubagentStop":
+            // agent_type or agent_name should be present but not strictly required
+            break;
+        case "Notification":
+            if (typeof input.title !== "string" && input.title !== undefined) {
+                errors.push("Notification: title must be a string if present");
+            }
+            if (typeof input.message !== "string" && input.message !== undefined) {
+                errors.push("Notification: message must be a string if present");
+            }
+            break;
+        case "UserPromptSubmit":
+        case "PreCompact":
+        case "Stop":
+            // Minimal validation — these events have no required fields beyond base
+            break;
+        default:
+            errors.push(`Unknown event type: ${event}`);
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        normalized: errors.length === 0 ? normalized : undefined,
+    };
+}
+/**
+ * Normalize session_id field from various formats:
+ * - session_id (snake_case from CC)
+ * - sessionId (camelCase internal)
+ * - CLAUDE_SESSION_ID (env var fallback)
+ */
+export function normalizeSessionId(input) {
+    if (typeof input.sessionId === "string") {
+        return input.sessionId;
+    }
+    if (typeof input.session_id === "string") {
+        return input.session_id;
+    }
+    if (typeof input.CLAUDE_SESSION_ID === "string") {
+        return input.CLAUDE_SESSION_ID;
+    }
+    return undefined;
+}

package/dist/hooks/state-manager.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Intent DNA — DNAStateManager
+ *
+ * Class-based facade over state.ts module functions. Bundles projectDir +
+ * sessionId into a single object so call sites don't repeat those args.
+ * Adds experience chain persistence (markdown + structured JSON) and
+ * lifecycle operations (init / cleanup / isStale) that state.ts lacks.
+ *
+ * Existing state.ts functions remain the canonical I/O primitives — this
+ * class delegates to them. Prefer this class in new code; state.ts exports
+ * are @deprecated for direct use.
+ */
+import type { DNAWorkflowState, AuditEntry, SurgeonAttemptState, SessionReadsState } from "./state.js";
+/** Single entry in the experience chain — one per failed surgeon round. */
+export interface ExperienceEntry {
+    round: number;
+    analysis: string;
+    attempt: string;
+    result: string;
+    lesson: string;
+    timestamp: string;
+}
+export declare class DNAStateManager {
+    private readonly projectDir;
+    private readonly sessionId?;
+    constructor(projectDir: string, sessionId?: string | undefined);
+    readWorkflowState(stalenessMs?: number): Promise<DNAWorkflowState | null>;
+    writeWorkflowState(state: DNAWorkflowState): Promise<void>;
+    clearWorkflowState(): Promise<void>;
+    appendAudit(entry: AuditEntry): Promise<void>;
+    readSurgeonAttempts(): Promise<SurgeonAttemptState>;
+    writeSurgeonAttempts(state: SurgeonAttemptState): Promise<void>;
+    readSessionReads(): Promise<SessionReadsState>;
+    appendSessionRead(filePath: string): Promise<void>;
+    readExperienceChain(): Promise<ExperienceEntry[]>;
+    writeExperienceChain(chain: ExperienceEntry[]): Promise<void>;
+    appendExperience(entry: ExperienceEntry): Promise<void>;
+    /** Ensure session directory structure exists. */
+    init(): Promise<void>;
+    /**
+     * Remove this manager's state files.
+     * Callers that need trace rotation should invoke rotateTraces() from state.ts separately.
+     */
+    cleanup(): Promise<void>;
+    /** True when workflow.json started_at exceeds the staleness threshold. */
+    isStale(stalenessMs?: number): Promise<boolean>;
+    private path;
+}

package/dist/hooks/state-manager.js

@@ -0,0 +1,135 @@
+/**
+ * Intent DNA — DNAStateManager
+ *
+ * Class-based facade over state.ts module functions. Bundles projectDir +
+ * sessionId into a single object so call sites don't repeat those args.
+ * Adds experience chain persistence (markdown + structured JSON) and
+ * lifecycle operations (init / cleanup / isStale) that state.ts lacks.
+ *
+ * Existing state.ts functions remain the canonical I/O primitives — this
+ * class delegates to them. Prefer this class in new code; state.ts exports
+ * are @deprecated for direct use.
+ */
+import { readFile, mkdir, unlink, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveStateDir, readWorkflowState as rwState, writeWorkflowState as wwState, clearWorkflowState as cwState, appendAudit as aAudit, readSurgeonAttempts as rSurg, writeSurgeonAttempts as wSurg, readSessionReads as rReads, appendSessionRead as aRead, atomicWrite, } from "./state.js";
+const EXPERIENCE_JSON = "workflow/experience.json";
+const EXPERIENCE_MD = "workflow/experience.md";
+const DEFAULT_STALENESS_MS = 2 * 60 * 60 * 1000; // 2h — matches state.ts
+// ── Manager ────────────────────────────────────────────────
+export class DNAStateManager {
+    projectDir;
+    sessionId;
+    constructor(projectDir, sessionId) {
+        this.projectDir = projectDir;
+        this.sessionId = sessionId;
+    }
+    // ── Workflow state ──
+    readWorkflowState(stalenessMs = DEFAULT_STALENESS_MS) {
+        return rwState(this.projectDir, this.sessionId, stalenessMs);
+    }
+    writeWorkflowState(state) {
+        return wwState(this.projectDir, state, this.sessionId);
+    }
+    clearWorkflowState() {
+        return cwState(this.projectDir, this.sessionId);
+    }
+    // ── Audit log ──
+    appendAudit(entry) {
+        return aAudit(this.projectDir, entry);
+    }
+    // ── Surgeon attempts ──
+    readSurgeonAttempts() {
+        return rSurg(this.projectDir, this.sessionId);
+    }
+    writeSurgeonAttempts(state) {
+        return wSurg(this.projectDir, state, this.sessionId);
+    }
+    // ── Session reads ──
+    readSessionReads() {
+        return rReads(this.projectDir, this.sessionId);
+    }
+    appendSessionRead(filePath) {
+        return aRead(this.projectDir, filePath, this.sessionId);
+    }
+    // ── Experience chain (new) ──
+    async readExperienceChain() {
+        const path = this.path(EXPERIENCE_JSON);
+        try {
+            const raw = await readFile(path, "utf-8");
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    async writeExperienceChain(chain) {
+        await atomicWrite(this.path(EXPERIENCE_JSON), JSON.stringify(chain, null, 2));
+        await atomicWrite(this.path(EXPERIENCE_MD), renderExperienceMarkdown(chain));
+    }
+    async appendExperience(entry) {
+        const chain = await this.readExperienceChain();
+        chain.push(entry);
+        await this.writeExperienceChain(chain);
+    }
+    // ── Lifecycle ──
+    /** Ensure session directory structure exists. */
+    async init() {
+        await mkdir(resolveStateDir(this.projectDir, this.sessionId), { recursive: true });
+    }
+    /**
+     * Remove this manager's state files.
+     * Callers that need trace rotation should invoke rotateTraces() from state.ts separately.
+     */
+    async cleanup() {
+        const dir = resolveStateDir(this.projectDir, this.sessionId);
+        for (const rel of ["workflow.json", EXPERIENCE_JSON, EXPERIENCE_MD, "workflow/surgeon-attempts.json", "workflow/session-reads.json"]) {
+            await unlink(join(dir, rel)).catch(() => { });
+        }
+    }
+    /** True when workflow.json started_at exceeds the staleness threshold. */
+    async isStale(stalenessMs = DEFAULT_STALENESS_MS) {
+        const wfPath = join(resolveStateDir(this.projectDir, this.sessionId), "workflow.json");
+        try {
+            const raw = await readFile(wfPath, "utf-8");
+            const state = JSON.parse(raw);
+            if (!state.started_at)
+                return false;
+            return Date.now() - new Date(state.started_at).getTime() > stalenessMs;
+        }
+        catch {
+            // No workflow.json — fall back to directory mtime for unparseable state
+            try {
+                const s = await stat(wfPath);
+                return Date.now() - s.mtimeMs > stalenessMs;
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    path(rel) {
+        return join(resolveStateDir(this.projectDir, this.sessionId), rel);
+    }
+}
+// ── Markdown rendering ────────────────────────────────────
+function renderExperienceMarkdown(chain) {
+    if (chain.length === 0) {
+        return "# Experience chain\n\n_Empty — no attempts yet._\n";
+    }
+    const lines = ["# Experience chain", ""];
+    for (const e of chain) {
+        lines.push(`## Round ${e.round} — ${e.timestamp}`);
+        lines.push("");
+        lines.push(`**Analysis:** ${e.analysis}`);
+        lines.push("");
+        lines.push(`**Attempt:** ${e.attempt}`);
+        lines.push("");
+        lines.push(`**Result:** ${e.result}`);
+        lines.push("");
+        lines.push(`**Lesson:** ${e.lesson}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/dist/hooks/state.d.ts

@@ -56,20 +56,24 @@ export interface SurgeonAttemptState {
 export declare function resolveStateDir(projectDir: string, sessionId?: string): string;
 /**
  * Read current workflow state. Returns null if not found or stale.
+ * @deprecated Prefer `new DNAStateManager(projectDir, sessionId).readWorkflowState()`.
  */
 export declare function readWorkflowState(projectDir: string, sessionId?: string, stalenessMs?: number): Promise<DNAWorkflowState | null>;
 /**
  * Write workflow state atomically.
+ * @deprecated Prefer `DNAStateManager.writeWorkflowState()`.
  */
 export declare function writeWorkflowState(projectDir: string, state: DNAWorkflowState, sessionId?: string): Promise<void>;
 /**
  * Clear workflow state (workflow complete).
+ * @deprecated Prefer `DNAStateManager.clearWorkflowState()`.
  */
 export declare function clearWorkflowState(projectDir: string, sessionId?: string): Promise<void>;
 /**
  * Append an entry to the audit log with dedup protection.
  * Dedup key: event + tool_name + timestamp (second-level).
  * Log file: `.dna/audit/violations-YYYY-MM-DD.log` (JSON Lines format)
+ * @deprecated Prefer `DNAStateManager.appendAudit()`.
  */
 export declare function appendAudit(projectDir: string, entry: AuditEntry): Promise<void>;
 /**
@@ -84,10 +88,12 @@ export declare function appendCompletedArtifact(projectDir: string, stepId: stri
 export declare function atomicWrite(filePath: string, data: string): Promise<void>;
 /**
  * Read surgeon attempt state. Returns default state if not found.
+ * @deprecated Prefer `DNAStateManager.readSurgeonAttempts()`.
  */
 export declare function readSurgeonAttempts(projectDir: string, sessionId?: string): Promise<SurgeonAttemptState>;
 /**
  * Write surgeon attempt state atomically.
+ * @deprecated Prefer `DNAStateManager.writeSurgeonAttempts()`.
  */
 export declare function writeSurgeonAttempts(projectDir: string, state: SurgeonAttemptState, sessionId?: string): Promise<void>;
 /** Tracks which files a session has Read — for context gate enforcement */
@@ -97,6 +103,7 @@ export interface SessionReadsState {
 }
 /**
  * Read session reads state. Returns empty reads if not found.
+ * @deprecated Prefer `DNAStateManager.readSessionReads()`.
  */
 export declare function readSessionReads(projectDir: string, sessionId?: string): Promise<SessionReadsState>;
 /**
@@ -105,6 +112,7 @@ export declare function readSessionReads(projectDir: string, sessionId?: string)
 export declare function writeSessionReads(projectDir: string, state: SessionReadsState, sessionId?: string): Promise<void>;
 /**
  * Append a file path to session reads (dedup).
+ * @deprecated Prefer `DNAStateManager.appendSessionRead()`.
  */
 export declare function appendSessionRead(projectDir: string, filePath: string, sessionId?: string): Promise<void>;
 /** Trace entry for hook call observability */