intentdna 1.5.13 → 1.5.15

package/dist/hooks/enforce.d.ts

@@ -14,11 +14,11 @@
  * Step checkpoints are handled by the CLI, not here.
  */
 import type { ConstraintIR, RoleDef, CompletedArtifactEntry } from "../schema/types.js";
-import type { PreToolUseInput, PostToolUseInput, UserPromptSubmitInput, SubagentStopInput, NotificationInput, HookOutput } from "./protocol.js";
+import type { PreToolUseInput, PostToolUseInput, UserPromptSubmitInput, SubagentStopInput, NotificationInput, EnforceResult } from "./protocol.js";
 /** SessionStart input fields */
 export interface SessionStartInput {
     cwd?: string;
-    session_id?: string;
+    sessionId?: string;
     trigger?: string;
 }
 export interface EnforceState {
@@ -41,22 +41,22 @@ export interface EnforceState {
  *
  * Optional `roles` parameter provides output_schema enforcement.
  */
-export declare function enforcePreToolUse(ir: ConstraintIR, input: PreToolUseInput, state?: EnforceState, roles?: Record<string, RoleDef>): HookOutput;
+export declare function enforcePreToolUse(ir: ConstraintIR, input: PreToolUseInput, state?: EnforceState, roles?: Record<string, RoleDef>): EnforceResult | null;
 /**
  * Enforce PostToolUse validators.
  * 1. Runs post-execution validators (audit)
  * 2. Verifies Bash write paths were within scope (defense-in-depth)
  */
-export declare function enforcePostToolUse(ir: ConstraintIR, input: PostToolUseInput): HookOutput;
+export declare function enforcePostToolUse(ir: ConstraintIR, input: PostToolUseInput): EnforceResult | null;
 /**
  * Inject DNA policy reminders on each user prompt.
  * Only injects when there are high-priority directives.
  */
-export declare function enforceUserPromptSubmit(ir: ConstraintIR, _input: UserPromptSubmitInput): HookOutput;
+export declare function enforceUserPromptSubmit(ir: ConstraintIR, _input: UserPromptSubmitInput): EnforceResult | null;
 /**
  * Audit role scope compliance when a subagent finishes.
  */
-export declare function enforceSubagentStop(ir: ConstraintIR, input: SubagentStopInput): HookOutput;
+export declare function enforceSubagentStop(ir: ConstraintIR, input: SubagentStopInput): EnforceResult | null;
 /**
  * Preserve DNA directive summary before context compaction.
  * Includes: high-priority directives, role scope map, active workflow state.
@@ -65,21 +65,21 @@ export declare function enforcePreCompact(ir: ConstraintIR, workflowContext?: {
     workflow: string;
     current_step: string;
     current_role: string;
-} | null): HookOutput;
+} | null): EnforceResult | null;
 /**
  * Check if a notification is a DNA violation and return audit info.
  * The CLI handles actual audit file writes.
  */
-export declare function enforceNotification(ir: ConstraintIR, input: NotificationInput): HookOutput;
+export declare function enforceNotification(ir: ConstraintIR, input: NotificationInput): EnforceResult | null;
 /**
  * Initialize DNA state and inject policy summary on session start.
  * Returns silent if no DNA policies are active.
  */
-export declare function enforceSessionStart(ir: ConstraintIR, input: SessionStartInput): HookOutput;
+export declare function enforceSessionStart(ir: ConstraintIR, input: SessionStartInput): EnforceResult | null;
 /** Stop enforcement input — includes workflow awareness */
 export interface StopEnforceInput {
     cwd?: string;
-    session_id?: string;
+    sessionId?: string;
     stop_reason?: string;
 }
 /** Workflow state context for stop enforcement */
@@ -103,7 +103,7 @@ export interface StopWorkflowContext {
  * Block when:
  *   - Workflow active + unmet checkpoints for current step
  */
-export declare function enforceStop(ir: ConstraintIR, input: StopEnforceInput, workflowState: StopWorkflowContext | null): HookOutput;
+export declare function enforceStop(ir: ConstraintIR, input: StopEnforceInput, workflowState: StopWorkflowContext | null): EnforceResult | null;
 /**
  * Enforce handoff produces — verify that the current step has produced
  * its declared artifacts. Called at stop/checkpoint time.
@@ -113,7 +113,7 @@ export declare function enforceHandoffProduces(ir: ConstraintIR, wfState: {
     current_step: string;
     workflow: string;
     completed_artifacts?: CompletedArtifactEntry[];
-}): HookOutput | null;
+}): EnforceResult | null;
 /** Check if a file path is allowed by a list of write globs (prefix matching). */
 export declare function checkWriteAllowed(filePath: string, allowedGlobs: string[]): boolean;
 /**
@@ -157,3 +157,4 @@ export interface ContextReadinessResult {
  * Pure function — no I/O.
  */
 export declare function checkContextReadiness(sessionReads: string[], required: string[]): ContextReadinessResult;
+export declare function checkWorkflowBoundary(workflowCompleted: boolean, targetSkill: string): EnforceResult;

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;
+}