intentdna 1.3.0 → 1.4.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "intentdna",
+  "description": "Declarative policy layer for AI agent governance — compile DNA templates to hooks, agents, and constraints",
+  "plugins": [
+    {
+      "name": "intentdna",
+      "description": "DNA template compilation + runtime enforcement",
+      "version": "1.2.3",
+      "source": "./"
+    }
+  ]
+}

package/dist/cli/commands/setup.d.ts

@@ -1,9 +1,21 @@
 /**
- * dna setup
+ * dna setup [--scope user|project] [--yes]
  *
- * Registers intentdna as a Claude Code plugin.
- * Auto-detects whether claude CLI is available and prints guidance accordingly.
+ * Registers intentdna as a Claude Code plugin:
+ *   1. Detect claude CLI availability
+ *   2. Resolve package path (npm global root)
+ *   3. Confirm with user (unless --yes)
+ *   4. Run: claude plugin marketplace add <path>
+ *   5. Run: claude plugin install intentdna@intentdna --scope <scope>
+ *   6. Verify registration
+ *
+ * Falls back to bin mode guidance when claude CLI is unavailable.
+ *
+ * Reference: OMC plugin registration flow (marketplace add → plugin install)
  */
+export type SetupScope = "user" | "project";
 export interface SetupOptions {
+    scope: SetupScope;
+    yes: boolean;
 }
-export declare function runSetup(_opts: SetupOptions): Promise<number>;
+export declare function runSetup(opts: SetupOptions): Promise<number>;

package/dist/cli/commands/setup.js

@@ -1,42 +1,192 @@
 /**
- * dna setup
+ * dna setup [--scope user|project] [--yes]
  *
- * Registers intentdna as a Claude Code plugin.
- * Auto-detects whether claude CLI is available and prints guidance accordingly.
+ * Registers intentdna as a Claude Code plugin:
+ *   1. Detect claude CLI availability
+ *   2. Resolve package path (npm global root)
+ *   3. Confirm with user (unless --yes)
+ *   4. Run: claude plugin marketplace add <path>
+ *   5. Run: claude plugin install intentdna@intentdna --scope <scope>
+ *   6. Verify registration
+ *
+ * Falls back to bin mode guidance when claude CLI is unavailable.
+ *
+ * Reference: OMC plugin registration flow (marketplace add → plugin install)
  */
 import { execSync } from "node:child_process";
-export async function runSetup(_opts) {
-    let claudeAvailable = false;
+import { createInterface } from "node:readline";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { stat } from "node:fs/promises";
+// ── Helpers ───────────────────────────────────────────────
+function log(msg) {
+    process.stderr.write(msg + "\n");
+}
+async function fileExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function confirm(question) {
+    return new Promise((res) => {
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        rl.question(question + " [Y/n] ", (answer) => {
+            rl.close();
+            const a = answer.trim().toLowerCase();
+            res(a === "" || a === "y" || a === "yes");
+        });
+    });
+}
+/**
+ * Check if claude CLI is available and return its version string.
+ */
+function detectClaudeCLI() {
     try {
-        execSync("claude --version", { stdio: "ignore" });
-        claudeAvailable = true;
+        return execSync("claude --version 2>/dev/null", { encoding: "utf-8", timeout: 5000 }).trim();
     }
     catch {
-        // claude CLI not found — fall through to bin mode
-    }
-    if (claudeAvailable) {
-        process.stderr.write("Claude Code CLI detected.\n");
-        process.stderr.write("\n");
-        process.stderr.write("Intent DNA plugin mode:\n");
-        process.stderr.write("  The .claude-plugin/ directory contains plugin.json and hook scripts.\n");
-        process.stderr.write("  To register as a plugin, run:\n");
-        process.stderr.write("\n");
-        let npmRoot = "";
-        try {
-            npmRoot = execSync("npm root -g", { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+        return null;
+    }
+}
+/**
+ * Resolve the intentdna package root directory.
+ * Priority: npm global install → local package directory (development).
+ */
+async function resolvePackagePath() {
+    // 1. Try npm global root
+    try {
+        const npmRoot = execSync("npm root -g", {
+            encoding: "utf-8",
+            timeout: 5000,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        const globalPath = resolve(npmRoot, "intentdna");
+        if (await fileExists(resolve(globalPath, ".claude-plugin", "plugin.json"))) {
+            return globalPath;
         }
-        catch {
-            // ignore
+    }
+    catch { /* not installed globally */ }
+    // 2. Try local package (development mode — this file is inside the package)
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    // In dist: dist/cli/commands/setup.js → ../../.. = package root
+    const localRoot = resolve(thisDir, "..", "..", "..");
+    if (await fileExists(resolve(localRoot, ".claude-plugin", "plugin.json"))) {
+        return localRoot;
+    }
+    return null;
+}
+/**
+ * Check if intentdna is already registered as a plugin.
+ */
+function isPluginRegistered() {
+    try {
+        const result = execSync("claude plugin list 2>/dev/null", {
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        return result.includes("intentdna");
+    }
+    catch {
+        return false;
+    }
+}
+// ── Main ──────────────────────────────────────────────────
+export async function runSetup(opts) {
+    const scope = opts.scope;
+    // Step 1: Detect claude CLI
+    const claudeVersion = detectClaudeCLI();
+    if (!claudeVersion) {
+        log("Claude Code CLI not detected.");
+        log("");
+        log("Intent DNA can run in bin mode (standalone dna-hook binary):");
+        log("  dna sync              Register dna-hook events in settings.json");
+        log("  dna sync --plugin     Force plugin-style IR generation");
+        log("");
+        log("To use plugin mode, install Claude Code first, then re-run 'dna setup'.");
+        return 0;
+    }
+    log(`Claude Code detected: ${claudeVersion}`);
+    // Step 2: Check if already registered
+    if (isPluginRegistered()) {
+        log("Intent DNA plugin is already registered.");
+        log("Run 'dna sync' to compile and activate your DNA templates.");
+        return 0;
+    }
+    // Step 3: Resolve package path
+    const pkgPath = await resolvePackagePath();
+    if (!pkgPath) {
+        log("Error: Could not find intentdna package with .claude-plugin/ directory.");
+        log("Ensure intentdna is installed: npm install -g intentdna");
+        return 1;
+    }
+    log(`Package found: ${pkgPath}`);
+    log(`Scope: ${scope}`);
+    // Step 4: Confirmation prompt
+    if (!opts.yes) {
+        log("");
+        log("This will:");
+        log(`  1. Register '${pkgPath}' as a plugin marketplace`);
+        log(`  2. Install intentdna plugin (scope: ${scope})`);
+        log("");
+        if (process.stdin.isTTY) {
+            const ok = await confirm("Proceed?");
+            if (!ok) {
+                log("Aborted.");
+                return 0;
+            }
         }
-        const pluginPath = npmRoot ? `${npmRoot}/intentdna` : "<npm-root>/intentdna";
-        process.stderr.write(`    claude plugin add ${pluginPath}\n`);
-        process.stderr.write("\n");
-        process.stderr.write("  Or run 'dna sync --plugin' to activate hooks via settings.json.\n");
-        process.stderr.write("Intent DNA plugin registered. Run 'dna sync' to activate.\n");
+    }
+    // Step 5: Register marketplace
+    try {
+        log("");
+        log(`Running: claude plugin marketplace add ${pkgPath}`);
+        execSync(`claude plugin marketplace add "${pkgPath}"`, {
+            encoding: "utf-8",
+            timeout: 30000,
+            stdio: ["inherit", "pipe", "pipe"],
+        });
+        log("Marketplace registered.");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log(`Warning: marketplace add failed: ${msg}`);
+        log("You may need to run manually:");
+        log(`  claude plugin marketplace add "${pkgPath}"`);
+        // Continue — install may still work if marketplace was already added
+    }
+    // Step 6: Install plugin
+    try {
+        const installCmd = `claude plugin install intentdna@intentdna --scope ${scope}`;
+        log(`Running: ${installCmd}`);
+        execSync(installCmd, {
+            encoding: "utf-8",
+            timeout: 30000,
+            stdio: ["inherit", "pipe", "pipe"],
+        });
+        log("Plugin installed.");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log(`Warning: plugin install failed: ${msg}`);
+        log("You may need to run manually:");
+        log(`  claude plugin install intentdna@intentdna --scope ${scope}`);
+        return 1;
+    }
+    // Step 7: Verify
+    if (isPluginRegistered()) {
+        log("");
+        log("Intent DNA plugin registered successfully.");
+        log("Run 'dna sync' to compile and activate your DNA templates.");
+        return 0;
     }
     else {
-        process.stderr.write("Claude Code CLI not detected. Using bin mode.\n");
-        process.stderr.write("Run 'dna sync' to register dna-hook in settings.json\n");
+        log("");
+        log("Plugin install completed but verification failed.");
+        log("Try: claude plugin list");
+        return 1;
     }
-    return 0;
 }

package/dist/cli/commands/verify.d.ts

@@ -11,6 +11,7 @@
  */
 export interface VerifyOptions {
     lockFile: string;
+    stats?: boolean;
 }
 export interface LockFileEntry {
     sha256: string;

package/dist/cli/commands/verify.js

@@ -11,6 +11,7 @@
  */
 import { readFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
+import { readTraces } from "../../hooks/state.js";
 // ── Helpers ────────────────────────────────────────────────
 export function sha256(content) {
     return createHash("sha256").update(content, "utf-8").digest("hex");
@@ -53,6 +54,10 @@ export async function verifyLock(lock) {
 }
 // ── CLI entry ──────────────────────────────────────────────
 export async function runVerify(opts) {
+    // Handle --stats mode
+    if (opts.stats) {
+        return runStats();
+    }
     // Read lock file
     let raw;
     try {
@@ -99,3 +104,67 @@ export async function runVerify(opts) {
         return 0;
     }
 }
+// ── Stats Mode ────────────────────────────────────────────
+async function runStats() {
+    const cwd = process.cwd();
+    const entries = await readTraces(cwd, 1); // last 24h
+    if (entries.length === 0) {
+        process.stderr.write("No trace data found (last 24h).\n");
+        process.stderr.write("Traces are written to .dna/state/trace/ during hook execution.\n");
+        return 0;
+    }
+    // Group by event
+    const byEvent = new Map();
+    for (const e of entries) {
+        const list = byEvent.get(e.event) ?? [];
+        list.push(e);
+        byEvent.set(e.event, list);
+    }
+    process.stderr.write("Hook call statistics (last 24h):\n");
+    for (const [event, list] of byEvent) {
+        const blocks = list.filter(e => e.decision === "block").length;
+        const warns = list.filter(e => e.decision === "warn").length;
+        const avgMs = list.reduce((sum, e) => sum + e.duration_ms, 0) / list.length;
+        const parts = [`${list.length} calls`];
+        if (blocks > 0)
+            parts.push(`${blocks} blocks`);
+        if (warns > 0)
+            parts.push(`${warns} warns`);
+        parts.push(`avg ${avgMs.toFixed(1)}ms`);
+        process.stderr.write(`  ${event.padEnd(18)} ${parts.join(", ")}\n`);
+    }
+    // Workflow stats
+    const withWorkflow = entries.filter(e => e.workflow);
+    if (withWorkflow.length > 0) {
+        const byWorkflow = new Map();
+        for (const e of withWorkflow) {
+            const key = e.workflow;
+            const list = byWorkflow.get(key) ?? [];
+            list.push(e);
+            byWorkflow.set(key, list);
+        }
+        process.stderr.write("\nWorkflow statistics:\n");
+        for (const [wf, list] of byWorkflow) {
+            const steps = new Set(list.map(e => e.step).filter(Boolean));
+            const blocks = list.filter(e => e.decision === "block").length;
+            process.stderr.write(`  ${wf}: ${list.length} tool calls, ${steps.size} steps, ${blocks} blocks\n`);
+        }
+    }
+    // Block reasons TOP 3
+    const blockEntries = entries.filter(e => e.decision === "block");
+    if (blockEntries.length > 0) {
+        const reasons = new Map();
+        for (const e of blockEntries) {
+            const key = `${e.event}:${e.tool_name ?? "unknown"}`;
+            reasons.set(key, (reasons.get(key) ?? 0) + 1);
+        }
+        const sorted = [...reasons.entries()].sort((a, b) => b[1] - a[1]).slice(0, 3);
+        process.stderr.write("\nBlock reasons TOP 3:\n");
+        let rank = 0;
+        for (const [reason, count] of sorted) {
+            rank++;
+            process.stderr.write(`  ${rank}. ${reason} x ${count}\n`);
+        }
+    }
+    return 0;
+}

package/dist/cli/index.js

@@ -17,7 +17,7 @@ const HELP = `Intent DNA CLI v0.3.0
 Usage: dna <command> [options]
 
 Commands:
-  setup         Register intentdna as a Claude Code plugin (auto-detect mode)
+  setup         Register intentdna as a Claude Code plugin (--scope user|project, --yes)
   guard         Zero-config guardrails — detect environment, apply safety rules
   sync          Compile + inject DNA into target file (CLAUDE.md, SOUL.md, etc.)
   verify        Verify synced files match .dna/lock checksums (drift detection)
@@ -53,6 +53,7 @@ Examples:
   dna sync --remove --inject CLAUDE.md --hooks .claude/hooks --agents .claude/agents
   dna verify                          Verify synced files against .dna/lock
   dna verify --lock /path/to/.dna/lock
+  dna verify --stats                  Show hook call statistics (last 24h)
   dna import .                  Import existing harness configs into DNA format
   dna run --dna my.dna.json --workflow dev-pipeline --task P5.8
   dna run --dna my.dna.json --workflow dev-pipeline --task P5.8 --dry-run
@@ -120,6 +121,7 @@ async function main() {
                 args: rest,
                 options: {
                     lock: { type: "string", default: ".dna/lock" },
+                    stats: { type: "boolean", default: false },
                 },
                 allowPositionals: true,
                 strict: false,
@@ -127,6 +129,7 @@ async function main() {
             const { runVerify } = await import("./commands/verify.js");
             const code = await runVerify({
                 lockFile: verifyValues.lock,
+                stats: verifyValues.stats,
             });
             process.exit(code);
             break;
@@ -357,8 +360,24 @@ async function main() {
             break;
         }
         case "setup": {
+            const { values: setupValues } = parseArgs({
+                args: rest,
+                options: {
+                    scope: { type: "string", short: "s", default: "user" },
+                    yes: { type: "boolean", short: "y", default: false },
+                },
+                strict: false,
+            });
+            const setupScope = setupValues.scope;
+            if (setupScope !== "user" && setupScope !== "project") {
+                process.stderr.write(`Error: --scope must be 'user' or 'project', got '${setupScope}'\n`);
+                process.exit(2);
+            }
             const { runSetup } = await import("./commands/setup.js");
-            const code = await runSetup({});
+            const code = await runSetup({
+                scope: setupScope,
+                yes: setupValues.yes,
+            });
             process.exit(code);
             break;
         }

package/dist/compiler/compile.js

@@ -218,6 +218,7 @@ export function compileDNA(activated, cascaded) {
         for (const [wfKey, wf] of Object.entries(cascaded.workflows)) {
             const wfStepCheckpoints = [];
             const activeRoles = [];
+            const handoffChain = [];
             for (const step of wf.steps ?? []) {
                 if (!activeRoles.includes(step.role)) {
                     activeRoles.push(step.role);
@@ -229,6 +230,14 @@ export function compileDNA(activated, cascaded) {
                         checkpoints: [...step.checkpoints],
                     });
                 }
+                // Collect handoff chain entries
+                if (step.handoff) {
+                    handoffChain.push({
+                        step_id: step.id,
+                        produces: step.handoff.produces,
+                        consumes: step.handoff.consumes,
+                    });
+                }
             }
             // Derive namespace from workflow key: "ns_wfname" → "ns", "wfname" → ""
             const underscoreIdx = wfKey.indexOf("_");
@@ -238,6 +247,7 @@ export function compileDNA(activated, cascaded) {
                 namespace,
                 step_checkpoints: wfStepCheckpoints,
                 active_roles: activeRoles,
+                handoff_chain: handoffChain,
             });
         }
     }

package/dist/compiler/workflow.js

@@ -173,6 +173,7 @@ function toWorkflowStep(def) {
         prompt: def.prompt ?? null,
         completion: def.completion && def.completion.length > 0 ? [...def.completion] : null,
         checkpoints: def.checkpoints && def.checkpoints.length > 0 ? [...def.checkpoints] : null,
+        handoff: def.handoff ?? null,
     };
 }
 /**

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, enforceSessionStart, enforceStop, } from "./enforce.js";
-import { appendAudit, readWorkflowState } from "./state.js";
+import { appendAudit, readWorkflowState, appendTrace, rotateTraces } from "./state.js";
 // ── Constants ──────────────────────────────────────────────
 const DEFAULT_IR_PATH = ".dna/compiled/ir.json";
 const VALID_EVENTS = new Set([
@@ -52,6 +53,17 @@ async function main() {
         return;
     }
     const state = {};
+    // 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);
@@ -61,6 +73,7 @@ async function main() {
             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,
@@ -68,11 +81,42 @@ async function main() {
             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
+    // 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 : "";

package/dist/hooks/enforce.d.ts

@@ -13,7 +13,7 @@
  *
  * 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 {
@@ -22,6 +22,12 @@ export interface SessionStartInput {
     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.
@@ -71,6 +77,7 @@ export interface StopWorkflowContext {
     current_step: string;
     current_role: string;
     started_at: string;
+    completed_artifacts?: CompletedArtifactEntry[];
 }
 /**
  * Enforce Stop hook — verify workflow checkpoint completion.
@@ -85,6 +92,16 @@ export interface StopWorkflowContext {
  *   - 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 ────────────────────────────────
@@ -237,6 +243,16 @@ export function enforceStop(ir, input, workflowState) {
     // 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
@@ -245,6 +261,51 @@ export function enforceStop(ir, input, workflowState) {
         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/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) {

package/dist/schema/types.d.ts

@@ -82,6 +82,20 @@ export interface RoleDef {
     success_criteria?: string[];
     failure_modes?: string[];
 }
+/** Handoff artifact type — what kind of artifact is passed between steps */
+export type HandoffType = "file" | "directory" | "test_result" | "git_commit" | "summary" | "state";
+/** A single artifact consumed or produced by a workflow step */
+export interface HandoffArtifact {
+    type: HandoffType;
+    path?: string;
+    from?: string;
+    description: string;
+}
+/** Handoff declaration for a workflow step */
+export interface StepHandoff {
+    consumes?: HandoffArtifact[];
+    produces?: HandoffArtifact[];
+}
 /** Transition condition between workflow steps */
 export interface TransitionDef {
     from: string;
@@ -124,6 +138,7 @@ export interface WorkflowStepDef {
     prompt?: string;
     completion?: CompletionCheck[];
     checkpoints?: StepCheckpoint[];
+    handoff?: StepHandoff;
 }
 /** Top-level workflow definition */
 export interface WorkflowDef {
@@ -133,6 +148,8 @@ export interface WorkflowDef {
     transitions?: TransitionDef[];
     retry_policy?: RetryPolicy;
     max_rounds?: number;
+    produces?: HandoffArtifact[];
+    consumes?: HandoffArtifact[];
 }
 export interface EpigeneticEffect {
     gene?: string;
@@ -236,12 +253,28 @@ export interface StepCheckpointIR {
     step_id: string;
     checkpoints: StepCheckpoint[];
 }
+/** Handoff chain entry — tracks what each step consumes/produces */
+export interface HandoffChainEntry {
+    step_id: string;
+    produces?: HandoffArtifact[];
+    consumes?: HandoffArtifact[];
+}
 /** Workflow-partitioned IR — isolates constraints per workflow */
 export interface WorkflowIR {
     workflow_name: string;
     namespace: string;
     step_checkpoints: StepCheckpointIR[];
     active_roles: string[];
+    handoff_chain: HandoffChainEntry[];
+}
+/** Record of artifacts completed by a step — used for cross-session resume */
+export interface CompletedArtifactEntry {
+    step_id: string;
+    artifacts: {
+        type: string;
+        path: string;
+        verified_at: string;
+    }[];
 }
 /** Runtime workflow state written to .dna/state/workflow.json */
 export interface WorkflowState {
@@ -252,6 +285,7 @@ export interface WorkflowState {
     iteration: number;
     session_id: string;
     started_at: string;
+    completed_artifacts?: CompletedArtifactEntry[];
 }
 export interface ConstraintIR {
     prompt_directives: PromptDirective[];
@@ -280,6 +314,7 @@ export interface WorkflowStep {
     prompt: string | null;
     completion: CompletionCheck[] | null;
     checkpoints: StepCheckpoint[] | null;
+    handoff: StepHandoff | null;
 }
 /** A group of steps that can execute in parallel */
 export interface ParallelGroup {

package/dist/templates/code-review-pipeline.dna.yaml

@@ -80,10 +80,22 @@ workflow:
       role: implementer
       description: Implement the feature
       prompt: "Implement task {{task_id}} according to the design document."
+      handoff:
+        produces:
+          - type: git_commit
+            description: "Implementation commit"
     - id: review
       role: reviewer
       description: Review the implementation
       prompt: "Review all changes for task {{task_id}}. Output PASS or FAIL."
+      handoff:
+        consumes:
+          - type: git_commit
+            from: implement
+            description: "Implementation to review"
+        produces:
+          - type: summary
+            description: "Review verdict (PASS/FAIL)"
   transitions:
     - from: review
       to: implement

package/dist/templates/flutter-refactoring-rescue.dna.yaml

@@ -130,13 +130,33 @@ workflows:
         role: investigator
         description: Trace the broken chain in v1 and v2, identify first breakpoint
         prompt: "Trace the call chain for '{{feature}}' in v1 ({{v1_path}}) and v2 ({{v2_path}}). Find where v2 breaks."
+        handoff:
+          produces:
+            - type: summary
+              description: "Breakpoint analysis with file paths and line numbers"
       - id: fix
         role: surgeon
         depends_on: [trace]
         description: Fix the identified breakpoint
         prompt: "Fix the breakpoint identified by investigator. Copy logic from v1, change one file only."
+        handoff:
+          consumes:
+            - type: summary
+              from: trace
+              description: "Breakpoint analysis from investigator"
+          produces:
+            - type: git_commit
+              description: "Single-file fix commit"
       - id: verify
         role: investigator
         depends_on: [fix]
         description: Verify the fix with adb
         prompt: "Run the feature on device. adb screencap + logcat. Compare with v1 behavior."
+        handoff:
+          consumes:
+            - type: git_commit
+              from: fix
+              description: "Fix commit to verify"
+          produces:
+            - type: summary
+              description: "Verification result with screenshots"

package/dist/templates/flutter-rewrite.dna.yaml

@@ -190,11 +190,27 @@ workflows:
         role: scanner
         description: "Scan v1 module in {{v1_path}}/. Output behavior doc to {{behavior_docs}}/$ARGUMENTS.md. List all user actions with call chains."
         prompt: "Scan module '$ARGUMENTS' in {{v1_path}}/. For each page, list: action → function() → return value. Output to {{behavior_docs}}/$ARGUMENTS.md. Then immediately proceed to write_tests."
+        handoff:
+          produces:
+            - type: file
+              path: "{{behavior_docs}}/$ARGUMENTS.md"
+              description: "Behavior document for module"
       - id: write_tests
         role: test_writer
         depends_on: [scan]
         description: "Read {{behavior_docs}}/$ARGUMENTS.md, write tests in {{test_path}}/$ARGUMENTS/, run baseline, commit."
         prompt: "Read {{behavior_docs}}/$ARGUMENTS.md. Write tests in {{test_path}}/$ARGUMENTS/. Test ALL layers: logic, widget, navigation. Run tests, record red/green baseline. Append baseline to behavior doc. Git commit: behavior-lock($ARGUMENTS): X tests (Y red, Z skipped)"
+        handoff:
+          consumes:
+            - type: file
+              path: "{{behavior_docs}}/$ARGUMENTS.md"
+              description: "Behavior document from scan step"
+          produces:
+            - type: directory
+              path: "{{test_path}}/$ARGUMENTS/"
+              description: "Test files for module"
+            - type: git_commit
+              description: "Behavior lock commit"
 
   rescue:
     name: Rescue
@@ -204,6 +220,13 @@ workflows:
         role: investigator
         description: "Run tests, assess current state, pick next targets."
         prompt: "Run tests in {{test_path}}/$ARGUMENTS/. Categorize all non-passing tests: 1) RED (failing) — highest priority, fix first. 2) SKIPPED-logic — state/notifier/service tests, fix second. 3) SKIPPED-widget — widget/UI/navigation tests, fix after logic is done. For the highest priority category, pick a batch of related tests. Trace: what does v1 do vs what does v2 do? Find the breakpoints. Report findings and the plan for this round."
+        handoff:
+          produces:
+            - type: summary
+              description: "Investigation findings and breakpoint analysis"
+            - type: test_result
+              path: "{{test_path}}/$ARGUMENTS/"
+              description: "Current test state assessment"
       - id: fix
         role: surgeon
         depends_on: [investigate]
@@ -212,11 +235,27 @@ workflows:
           - assert: clean_working_tree
             message: "Commit all changes before proceeding to report step"
         prompt: "Fix the identified breakpoints. Read v1 in {{v1_path}}/. Rewrite in v2 style in {{v2_path}}/. Logic tests: implement notifier/state/service code. Widget tests: copy widget from v1, change bindings (Obx→Consumer, Get.to→context.go), set up widget test infra (ProviderScope, mock providers, GoRouter) if needed. Run tests after each fix. Red→green or Skipped→green = done. Still failing = revert and re-analyze. Maximize test coverage per round. When done, commit all changes: rescue($ARGUMENTS): round N — X passed (+Y)"
+        handoff:
+          consumes:
+            - type: summary
+              from: investigate
+              description: "Investigation findings from investigate step"
+          produces:
+            - type: git_commit
+              description: "Rescue round commit"
       - id: report
         role: investigator
         depends_on: [fix]
         description: "Summarize round, guide next steps."
         prompt: "Run full test suite in {{test_path}}/$ARGUMENTS/. Report: 1) passed/skipped/failed delta vs last round. 2) List remaining skipped tests by category (logic vs widget vs platform). 3) If skipped tests remain, end with: Run /rescue $ARGUMENTS to continue. 4) If all tests pass, end with: Module $ARGUMENTS rescue complete."
+        handoff:
+          consumes:
+            - type: git_commit
+              from: fix
+              description: "Committed fix from surgeon"
+          produces:
+            - type: summary
+              description: "Round summary with test delta"
 
   core-align:
     name: Core Align

package/dist/templates/full-pipeline.dna.yaml

@@ -110,18 +110,47 @@ workflow:
       description: Read task and produce design document
       run_if: "round == 1"
       prompt: "Read task {{task_id}} from BOARD.md. Produce a design document."
+      handoff:
+        produces:
+          - type: file
+            path: "docs/tasks/{{task_id}}.md"
+            description: "Design document for task"
     - id: implement
       role: implementer
       description: Implement according to design
       prompt: "Implement task {{task_id}} following the design document."
+      handoff:
+        consumes:
+          - type: file
+            path: "docs/tasks/{{task_id}}.md"
+            description: "Design document from planner"
+        produces:
+          - type: git_commit
+            description: "Implementation commit"
     - id: test
       role: tester
       description: Run tests and fix failures
       prompt: "Run tests. Fix failures. Add missing tests for {{task_id}}."
+      handoff:
+        consumes:
+          - type: git_commit
+            from: implement
+            description: "Implementation to test"
+        produces:
+          - type: test_result
+            description: "Test results after fixes"
     - id: review
       role: reviewer
       description: Review and output verdict
       prompt: "Review changes for {{task_id}}. Output PASS or FAIL."
+      handoff:
+        consumes:
+          - type: test_result
+            from: test
+            description: "Test results to review"
+        produces:
+          - type: summary
+            description: "Review verdict (PASS/FAIL)"
   transitions:
     - from: review
       to: implement

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intentdna",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Intent DNA — Declarative policy layer for AI agent behavior",
   "type": "module",
   "main": "dist/index.js",