intentdna 1.2.3 → 1.4.0

package/dist/hooks/cli.js

@@ -16,9 +16,10 @@
  */
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { randomUUID } from "node:crypto";
 import { readStdin, writeOutput, silentOutput } from "./protocol.js";
-import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, } from "./enforce.js";
-import { appendAudit } from "./state.js";
+import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, } from "./enforce.js";
+import { appendAudit, readWorkflowState, appendTrace, rotateTraces } from "./state.js";
 // ── Constants ──────────────────────────────────────────────
 const DEFAULT_IR_PATH = ".dna/compiled/ir.json";
 const VALID_EVENTS = new Set([
@@ -52,9 +53,70 @@ async function main() {
         return;
     }
     const state = {};
-    // Dispatch to enforcement engine
+    // Load workflow state for events that need handoff context
+    if (event === "PreToolUse") {
+        const wfState = await readWorkflowState(projectDir, sessionId);
+        if (wfState && wfState.active) {
+            state.workflowState = {
+                current_step: wfState.current_step,
+                workflow: wfState.workflow,
+                completed_artifacts: wfState.completed_artifacts,
+            };
+        }
+    }
+    // Special handling for Stop — needs async workflow state read
+    if (event === "Stop") {
+        const wfState = await readWorkflowState(projectDir, sessionId);
+        const stopContext = wfState ? {
+            active: wfState.active,
+            workflow: wfState.workflow,
+            current_step: wfState.current_step,
+            current_role: wfState.current_role,
+            started_at: wfState.started_at,
+            completed_artifacts: wfState.completed_artifacts,
+        } : null;
+        const stopOutput = enforceStop(ir, {
+            cwd: typeof rawInput.cwd === "string" ? rawInput.cwd : undefined,
+            session_id: sessionId,
+            stop_reason: typeof rawInput.stop_reason === "string" ? rawInput.stop_reason : undefined,
+        }, stopContext);
+        writeOutput(stopOutput);
+        // Trace for Stop
+        appendTrace(projectDir, {
+            trace_id: randomUUID(),
+            event: "Stop",
+            workflow: wfState?.workflow,
+            step: wfState?.current_step,
+            decision: stopOutput.continue === false ? "block" : "allow",
+            duration_ms: Date.now() - Date.now(), // minimal
+            timestamp: new Date().toISOString(),
+        }).catch(() => { });
+        return;
+    }
+    // Dispatch to enforcement engine with timing
+    const start = Date.now();
     const output = dispatch(event, ir, rawInput, state);
+    const durationMs = Date.now() - start;
     writeOutput(output);
+    // Trace logging (async, fail-open)
+    const decision = output.continue === false ? "block"
+        : output.hookSpecificOutput?.additionalContext?.startsWith("WARN") ? "warn"
+            : "allow";
+    appendTrace(projectDir, {
+        trace_id: randomUUID(),
+        event,
+        tool_name: typeof rawInput.tool_name === "string" ? rawInput.tool_name : undefined,
+        agent_type: typeof rawInput.agent_type === "string" ? rawInput.agent_type : undefined,
+        workflow: state.workflowState?.workflow,
+        step: state.workflowState?.current_step,
+        decision: decision,
+        duration_ms: durationMs,
+        timestamp: new Date().toISOString(),
+    }).catch(() => { }); // Fail-open
+    // Side effect: rotate traces on SessionStart
+    if (event === "SessionStart") {
+        rotateTraces(projectDir).catch(() => { });
+    }
     // Side effect: audit log for notifications
     if (event === "Notification" && output.hookSpecificOutput?.additionalContext?.includes("violation")) {
         const message = typeof rawInput.message === "string" ? rawInput.message : "";
@@ -103,7 +165,11 @@ function dispatch(event, ir, input, state) {
         case "Stop":
             return silentOutput(); // DNA doesn't block stops
         case "SessionStart":
-            return silentOutput(); // Placeholder — will initialize DNA state in future
+            return enforceSessionStart(ir, {
+                cwd: typeof input.cwd === "string" ? input.cwd : undefined,
+                session_id: typeof input.sessionId === "string" ? input.sessionId : undefined,
+                trigger: typeof input.trigger === "string" ? input.trigger : undefined,
+            });
         default:
             return silentOutput();
     }

package/dist/hooks/enforce.d.ts

@@ -13,9 +13,21 @@
  *
  * Step checkpoints are handled by the CLI, not here.
  */
-import type { ConstraintIR, RoleDef } from "../schema/types.js";
+import type { ConstraintIR, RoleDef, CompletedArtifactEntry } from "../schema/types.js";
 import type { PreToolUseInput, PostToolUseInput, UserPromptSubmitInput, SubagentStopInput, NotificationInput, HookOutput } from "./protocol.js";
+/** SessionStart input fields */
+export interface SessionStartInput {
+    cwd?: string;
+    session_id?: string;
+    trigger?: string;
+}
 export interface EnforceState {
+    /** Workflow handoff context — passed from CLI after reading workflow state */
+    workflowState?: {
+        current_step: string;
+        workflow: string;
+        completed_artifacts?: CompletedArtifactEntry[];
+    };
 }
 /**
  * Enforce PreToolUse constraints.
@@ -47,6 +59,49 @@ export declare function enforcePreCompact(ir: ConstraintIR): HookOutput;
  * The CLI handles actual audit file writes.
  */
 export declare function enforceNotification(ir: ConstraintIR, input: NotificationInput): HookOutput;
+/**
+ * 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;
+/** Stop enforcement input — includes workflow awareness */
+export interface StopEnforceInput {
+    cwd?: string;
+    session_id?: string;
+    stop_reason?: string;
+}
+/** Workflow state context for stop enforcement */
+export interface StopWorkflowContext {
+    active: boolean;
+    workflow: string;
+    current_step: string;
+    current_role: string;
+    started_at: string;
+    completed_artifacts?: CompletedArtifactEntry[];
+}
+/**
+ * Enforce Stop hook — verify workflow checkpoint completion.
+ *
+ * Safety valves (NEVER block):
+ *   - context_limit / context_window stops
+ *   - Stale workflow state (>2h)
+ *   - No active workflow
+ *   - No checkpoints defined
+ *
+ * Block when:
+ *   - Workflow active + unmet checkpoints for current step
+ */
+export declare function enforceStop(ir: ConstraintIR, input: StopEnforceInput, workflowState: StopWorkflowContext | null): HookOutput;
+/**
+ * Enforce handoff produces — verify that the current step has produced
+ * its declared artifacts. Called at stop/checkpoint time.
+ * Returns block output if a required artifact is missing, null if all produced.
+ */
+export declare function enforceHandoffProduces(ir: ConstraintIR, wfState: {
+    current_step: string;
+    workflow: string;
+    completed_artifacts?: CompletedArtifactEntry[];
+}): HookOutput | 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;
 /**

package/dist/hooks/enforce.js

@@ -46,6 +46,12 @@ export function enforcePreToolUse(ir, input, state, roles) {
         if (result)
             return result;
     }
+    // Layer 6: Handoff — check consumed artifacts are available
+    if (state?.workflowState && ir.workflows_ir) {
+        const result = enforceHandoffConsumes(ir, state.workflowState);
+        if (result)
+            return result;
+    }
     return silentOutput();
 }
 // ── PostToolUse Enforcement ────────────────────────────────
@@ -145,7 +151,161 @@ export function enforceNotification(ir, input) {
     }
     return silentOutput();
 }
+// ── SessionStart Enforcement ───────────────────────────────
+/**
+ * Initialize DNA state and inject policy summary on session start.
+ * 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();
+    }
+    // Build policy summary
+    const lines = [
+        "[Intent DNA] Session initialized — active governance:",
+    ];
+    if (ir.source_dna_ids.length > 0) {
+        lines.push(`  Templates: ${ir.source_dna_ids.join(", ")}`);
+    }
+    const stats = [];
+    if (directiveCount > 0)
+        stats.push(`${directiveCount} directives`);
+    if (gateCount > 0)
+        stats.push(`${gateCount} gates`);
+    if (filterCount > 0)
+        stats.push(`${filterCount} filters`);
+    if (roleCount > 0)
+        stats.push(`${roleCount} roles`);
+    if (workflowCount > 0)
+        stats.push(`${workflowCount} workflows`);
+    if (stats.length > 0) {
+        lines.push(`  Enforcement: ${stats.join(", ")}`);
+    }
+    return allowOutput(lines.join("\n"));
+}
+/**
+ * Enforce Stop hook — verify workflow checkpoint completion.
+ *
+ * Safety valves (NEVER block):
+ *   - context_limit / context_window stops
+ *   - Stale workflow state (>2h)
+ *   - No active workflow
+ *   - No checkpoints defined
+ *
+ * Block when:
+ *   - 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();
+    }
+    // Safety valve 2: context_limit stops → NEVER block
+    const reason = input.stop_reason ?? "";
+    if (reason.includes("context_limit") || reason.includes("context_window")) {
+        return silentOutput();
+    }
+    // Safety valve 3: user abort → don't block
+    if (reason === "user_abort" || reason === "sigint") {
+        return silentOutput();
+    }
+    // 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();
+        }
+    }
+    // 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);
+        if (activeWf) {
+            const wfStepCps = activeWf.step_checkpoints.filter(cp => cp.step_id === workflowState.current_step);
+            if (wfStepCps.length > 0) {
+                workflowCheckpoints = wfStepCps;
+            }
+        }
+    }
+    if (workflowCheckpoints.length === 0) {
+        return silentOutput(); // No checkpoints for current step
+    }
+    // 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)
+                return handoffResult;
+        }
+        return silentOutput();
+    }
+    // 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"));
+}
 // ── Internal: Layer Enforcement ────────────────────────────
+/**
+ * Enforce handoff consumes — verify that the current step's consumed
+ * artifacts have been produced by a preceding step.
+ * Returns block output if a required artifact is missing, null if all satisfied.
+ */
+function enforceHandoffConsumes(ir, wfState) {
+    const activeWf = ir.workflows_ir?.find(w => w.workflow_name === wfState.workflow);
+    if (!activeWf || activeWf.handoff_chain.length === 0)
+        return null;
+    const currentEntry = activeWf.handoff_chain.find(h => h.step_id === wfState.current_step);
+    if (!currentEntry?.consumes || currentEntry.consumes.length === 0)
+        return null;
+    const completedStepIds = new Set((wfState.completed_artifacts ?? []).map(a => a.step_id));
+    // For each consumed artifact, find the producing step and check it completed
+    for (const consumed of currentEntry.consumes) {
+        // Find which step produces this artifact
+        const producer = activeWf.handoff_chain.find(h => h.produces?.some(p => p.type === consumed.type && ((p.path && consumed.path && p.path === consumed.path) ||
+            (consumed.from && h.step_id === consumed.from))));
+        if (producer && !completedStepIds.has(producer.step_id)) {
+            return blockOutput(`[Intent DNA] Step '${wfState.current_step}' requires artifact from step '${producer.step_id}' (${consumed.description}). Run step '${producer.step_id}' first.`);
+        }
+    }
+    return null;
+}
+/**
+ * Enforce handoff produces — verify that the current step has produced
+ * its declared artifacts. Called at stop/checkpoint time.
+ * Returns block output if a required artifact is missing, null if all produced.
+ */
+export function enforceHandoffProduces(ir, wfState) {
+    const activeWf = ir.workflows_ir?.find(w => w.workflow_name === wfState.workflow);
+    if (!activeWf || activeWf.handoff_chain.length === 0)
+        return null;
+    const currentEntry = activeWf.handoff_chain.find(h => h.step_id === wfState.current_step);
+    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 null;
+}
 function enforceRoleScope(rolesScopeMap, input) {
     if (!input.agent_type)
         return null;

package/dist/hooks/index.d.ts

@@ -4,6 +4,6 @@
  * Public exports for the hook enforcement engine.
  * Used by the `dna-hook` CLI and importable for programmatic use.
  */
-export { type HookEvent, type HookInput, type HookOutput, type HookInputBase, type PreToolUseInput, type PostToolUseInput, type UserPromptSubmitInput, type SubagentStopInput, type PreCompactInput, type NotificationInput, type StopInput, readStdin, writeOutput, allowOutput, blockOutput, escalateOutput, silentOutput, } from "./protocol.js";
-export { type EnforceState, enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, checkWriteAllowed, globToPrefix, evaluateGateCondition, resolveToolTarget, } from "./enforce.js";
+export { type HookEvent, type HookInput, type HookOutput, type HookInputBase, type PreToolUseInput, type PostToolUseInput, type UserPromptSubmitInput, type SubagentStopInput, type PreCompactInput, type NotificationInput, type StopInput, type SessionStartInput as SessionStartHookInput, readStdin, writeOutput, allowOutput, blockOutput, escalateOutput, silentOutput, } from "./protocol.js";
+export { type EnforceState, type SessionStartInput, type StopEnforceInput, type StopWorkflowContext, enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, checkWriteAllowed, globToPrefix, evaluateGateCondition, resolveToolTarget, } from "./enforce.js";
 export { type DNAWorkflowState, type AuditEntry, resolveStateDir, readWorkflowState, writeWorkflowState, clearWorkflowState, appendAudit, } from "./state.js";

package/dist/hooks/index.js

@@ -7,6 +7,6 @@
 // Protocol types and I/O
 export { readStdin, writeOutput, allowOutput, blockOutput, escalateOutput, silentOutput, } from "./protocol.js";
 // Enforcement engine
-export { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, checkWriteAllowed, globToPrefix, evaluateGateCondition, resolveToolTarget, } from "./enforce.js";
+export { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, checkWriteAllowed, globToPrefix, evaluateGateCondition, resolveToolTarget, } from "./enforce.js";
 // State management
 export { resolveStateDir, readWorkflowState, writeWorkflowState, clearWorkflowState, appendAudit, } from "./state.js";

package/dist/hooks/protocol.d.ts

@@ -39,7 +39,10 @@ export interface NotificationInput extends HookInputBase {
 export interface StopInput extends HookInputBase {
     stop_reason?: string;
 }
-export type HookInput = PreToolUseInput | PostToolUseInput | UserPromptSubmitInput | SubagentStopInput | PreCompactInput | NotificationInput | StopInput;
+export interface SessionStartInput extends HookInputBase {
+    trigger?: string;
+}
+export type HookInput = PreToolUseInput | PostToolUseInput | UserPromptSubmitInput | SubagentStopInput | PreCompactInput | NotificationInput | StopInput | SessionStartInput;
 export interface HookOutput {
     continue: boolean;
     decision?: "block" | "allow";

package/dist/hooks/state.d.ts

@@ -9,6 +9,7 @@
  * All read operations are fail-safe (return null on error, never throw).
  * All write operations use atomic temp+rename pattern.
  */
+import type { CompletedArtifactEntry } from "../schema/types.js";
 /** Workflow state written by runtime and read by hooks */
 export interface DNAWorkflowState {
     active: boolean;
@@ -18,6 +19,7 @@ export interface DNAWorkflowState {
     iteration: number;
     session_id: string;
     started_at: string;
+    completed_artifacts?: CompletedArtifactEntry[];
 }
 /** Audit log entry (one per line in JSON Lines format) */
 export interface AuditEntry {
@@ -47,7 +49,44 @@ export declare function writeWorkflowState(projectDir: string, state: DNAWorkflo
  */
 export declare function clearWorkflowState(projectDir: string, sessionId?: string): Promise<void>;
 /**
- * Append an entry to the audit log.
+ * 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)
  */
 export declare function appendAudit(projectDir: string, entry: AuditEntry): Promise<void>;
+/**
+ * Record a completed artifact for a workflow step.
+ * Reads current workflow state, appends the artifact, writes back atomically.
+ */
+export declare function appendCompletedArtifact(projectDir: string, stepId: string, artifact: {
+    type: string;
+    path: string;
+}, sessionId?: string): Promise<void>;
+/** Trace entry for hook call observability */
+export interface TraceEntry {
+    trace_id: string;
+    event: string;
+    tool_name?: string;
+    agent_type?: string;
+    workflow?: string;
+    step?: string;
+    decision: "allow" | "block" | "warn";
+    duration_ms: number;
+    timestamp: string;
+}
+/**
+ * Append a trace entry to the daily trace file.
+ * File: `.dna/state/trace/trace-YYYY-MM-DD.jsonl`
+ * Fail-open: never throws.
+ */
+export declare function appendTrace(projectDir: string, entry: TraceEntry): Promise<void>;
+/**
+ * Read trace entries from the last N days.
+ * Returns parsed entries sorted by timestamp.
+ */
+export declare function readTraces(projectDir: string, days?: number): Promise<TraceEntry[]>;
+/**
+ * Clean up trace files older than retention period.
+ * Removes `.dna/state/trace/trace-*.jsonl` files older than TRACE_RETENTION_DAYS.
+ */
+export declare function rotateTraces(projectDir: string): Promise<number>;

package/dist/hooks/state.js

@@ -9,7 +9,7 @@
  * All read operations are fail-safe (return null on error, never throw).
  * All write operations use atomic temp+rename pattern.
  */
-import { readFile, writeFile, rename, mkdir, appendFile, unlink } from "node:fs/promises";
+import { readFile, writeFile, rename, mkdir, appendFile, unlink, readdir, stat } from "node:fs/promises";
 import { join, dirname } from "node:path";
 // ── Constants ──────────────────────────────────────────────
 const WORKFLOW_FILE = "workflow.json";
@@ -73,7 +73,8 @@ export async function clearWorkflowState(projectDir, sessionId) {
 }
 // ── Audit Log ──────────────────────────────────────────────
 /**
- * Append an entry to the audit log.
+ * 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)
  */
 export async function appendAudit(projectDir, entry) {
@@ -81,8 +82,52 @@ export async function appendAudit(projectDir, entry) {
     await mkdir(auditDir, { recursive: true });
     const date = entry.timestamp.slice(0, 10); // YYYY-MM-DD
     const logPath = join(auditDir, `violations-${date}.log`);
+    // Dedup: check if identical entry (same event+tool+second) already exists
+    const dedupKey = `${entry.event}|${entry.tool_name ?? ""}|${entry.timestamp.slice(0, 19)}`;
+    try {
+        const existing = await readFile(logPath, "utf-8");
+        const lines = existing.trimEnd().split("\n");
+        // Check last 10 lines for dedup (avoid scanning entire file)
+        const recentLines = lines.slice(-10);
+        for (const line of recentLines) {
+            try {
+                const prev = JSON.parse(line);
+                const prevKey = `${prev.event}|${prev.tool_name ?? ""}|${prev.timestamp.slice(0, 19)}`;
+                if (prevKey === dedupKey)
+                    return; // Already logged
+            }
+            catch { /* skip malformed lines */ }
+        }
+    }
+    catch { /* file doesn't exist yet */ }
     await appendFile(logPath, JSON.stringify(entry) + "\n", "utf-8");
 }
+// ── Completed Artifacts ───────────────────────────────────
+/**
+ * Record a completed artifact for a workflow step.
+ * Reads current workflow state, appends the artifact, writes back atomically.
+ */
+export async function appendCompletedArtifact(projectDir, stepId, artifact, sessionId) {
+    const state = await readWorkflowState(projectDir, sessionId, 0);
+    if (!state)
+        return;
+    const artifacts = state.completed_artifacts ?? [];
+    let stepEntry = artifacts.find(a => a.step_id === stepId);
+    if (!stepEntry) {
+        stepEntry = { step_id: stepId, artifacts: [] };
+        artifacts.push(stepEntry);
+    }
+    // Dedup: don't add if same path already recorded
+    if (stepEntry.artifacts.some(a => a.path === artifact.path))
+        return;
+    stepEntry.artifacts.push({
+        type: artifact.type,
+        path: artifact.path,
+        verified_at: new Date().toISOString(),
+    });
+    state.completed_artifacts = artifacts;
+    await writeWorkflowState(projectDir, state, sessionId);
+}
 // ── Internal ───────────────────────────────────────────────
 /** Atomic write: write to temp file then rename. */
 async function atomicWrite(filePath, data) {
@@ -91,3 +136,93 @@ async function atomicWrite(filePath, data) {
     await writeFile(tmpPath, data, "utf-8");
     await rename(tmpPath, filePath);
 }
+const TRACE_DIR = "trace";
+const MAX_TRACE_SIZE = 10 * 1024 * 1024; // 10MB
+const TRACE_RETENTION_DAYS = 7;
+/**
+ * Append a trace entry to the daily trace file.
+ * File: `.dna/state/trace/trace-YYYY-MM-DD.jsonl`
+ * Fail-open: never throws.
+ */
+export async function appendTrace(projectDir, entry) {
+    try {
+        const traceDir = join(projectDir, ".dna", "state", TRACE_DIR);
+        await mkdir(traceDir, { recursive: true });
+        const date = entry.timestamp.slice(0, 10);
+        const tracePath = join(traceDir, `trace-${date}.jsonl`);
+        // Check file size — rotate if over limit
+        try {
+            const stats = await stat(tracePath);
+            if (stats.size >= MAX_TRACE_SIZE)
+                return; // silently skip if file too large
+        }
+        catch { /* file doesn't exist yet */ }
+        await appendFile(tracePath, JSON.stringify(entry) + "\n", "utf-8");
+    }
+    catch {
+        // Fail-open: trace write failure never affects hook execution
+    }
+}
+/**
+ * Read trace entries from the last N days.
+ * Returns parsed entries sorted by timestamp.
+ */
+export async function readTraces(projectDir, days = 1) {
+    const traceDir = join(projectDir, ".dna", "state", TRACE_DIR);
+    const entries = [];
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - days);
+    const cutoffDate = cutoff.toISOString().slice(0, 10);
+    try {
+        const files = await readdir(traceDir);
+        const traceFiles = files
+            .filter(f => f.startsWith("trace-") && f.endsWith(".jsonl"))
+            .filter(f => {
+            const fileDate = f.slice(6, 16); // "trace-YYYY-MM-DD.jsonl" → "YYYY-MM-DD"
+            return fileDate >= cutoffDate;
+        })
+            .sort();
+        for (const file of traceFiles) {
+            const content = await readFile(join(traceDir, file), "utf-8");
+            for (const line of content.trim().split("\n")) {
+                if (!line)
+                    continue;
+                try {
+                    entries.push(JSON.parse(line));
+                }
+                catch { /* skip malformed */ }
+            }
+        }
+    }
+    catch {
+        // No trace dir yet
+    }
+    return entries;
+}
+/**
+ * Clean up trace files older than retention period.
+ * Removes `.dna/state/trace/trace-*.jsonl` files older than TRACE_RETENTION_DAYS.
+ */
+export async function rotateTraces(projectDir) {
+    const traceDir = join(projectDir, ".dna", "state", TRACE_DIR);
+    let removed = 0;
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - TRACE_RETENTION_DAYS);
+    const cutoffDate = cutoff.toISOString().slice(0, 10);
+    try {
+        const files = await readdir(traceDir);
+        for (const file of files) {
+            if (!file.startsWith("trace-") || !file.endsWith(".jsonl"))
+                continue;
+            const fileDate = file.slice(6, 16);
+            if (fileDate < cutoffDate) {
+                await unlink(join(traceDir, file)).catch(() => { });
+                removed++;
+            }
+        }
+    }
+    catch {
+        // No trace dir
+    }
+    return removed;
+}

package/dist/runtime/skill-adapter.js

@@ -124,6 +124,27 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
         lines.push("</Checkpoints>");
         lines.push("");
     }
+    // Handoff — artifact flow between steps
+    const stepsWithHandoff = plan.steps.filter((s) => s.handoff && (s.handoff.consumes?.length || s.handoff.produces?.length));
+    if (stepsWithHandoff.length > 0) {
+        lines.push("<Handoff>");
+        for (const step of stepsWithHandoff) {
+            const h = step.handoff;
+            if (h.produces && h.produces.length > 0) {
+                for (const p of h.produces) {
+                    lines.push(`  Step ${step.id} produces: ${p.description} (${p.type}${p.path ? `, ${p.path}` : ""})`);
+                }
+            }
+            if (h.consumes && h.consumes.length > 0) {
+                for (const c of h.consumes) {
+                    const fromNote = c.from ? ` from ${c.from}` : "";
+                    lines.push(`  Step ${step.id} consumes: ${c.description}${fromNote} (${c.type}${c.path ? `, ${c.path}` : ""})`);
+                }
+            }
+        }
+        lines.push("</Handoff>");
+        lines.push("");
+    }
     // Variables — collect {{var_name}} references from the whole plan
     const varRefs = collectVariableRefs(plan);
     if (varRefs.size > 0) {