intentdna 1.5.20 → 1.5.21

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "intentdna",
       "description": "Declarative policy layer for AI agent behavior with plugin-managed hook runtime for Claude Code.",
-      "version": "1.5.20",
+      "version": "1.5.21",
       "author": {
         "name": "Samuel"
       },
@@ -25,5 +25,5 @@
       ]
     }
   ],
-  "version": "1.5.20"
+  "version": "1.5.21"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "intentdna",
-  "version": "1.5.20",
+  "version": "1.5.21",
   "description": "Declarative policy layer for AI agent behavior",
   "author": {
     "name": "Samuel"

package/README.md

@@ -8,10 +8,11 @@ Intent DNA turns intent, policy, and accumulated experience into enforceable age
 
 ## What It Is
 
-Intent DNA is a compiler and runtime toolkit for managing agent behavior across three layers:
+Intent DNA is a compiler and runtime toolkit for managing agent behavior across four layers:
 
 - **Behavioral guidance** via generated prompt/context files
 - **Deterministic enforcement** via hooks and runtime checks
+- **Artifact handoff** via session-scoped manifests and resolver facts
 - **Feedback loops** via trace, audit, and epigenetic evolution
 
 It governs the agents operating on your systems rather than re-implementing the systems themselves.
@@ -81,11 +82,12 @@ Typical outputs include:
 |--------|---------|
 | `CLAUDE.md` | Behavioral guidance |
 | `.dna/compiled/ir.json` | Runtime-readable compiled constraints |
+| `.dna/state/sessions/*/handoffs/*.json` | Local artifact manifests for workflow handoff facts |
 | `.claude/agents/*.md` | Role definitions |
 | `.claude/skills/*/SKILL.md` | Workflow entrypoints |
 | `.claude/settings.json` or plugin runtime | Hook wiring |
 
-**Key idea:** prompts can drift, but runtime constraints and feedback loops make behavior governable.
+**Key idea:** prompts can drift, but runtime constraints, resolver-backed handoffs, and feedback loops make behavior governable.
 
 ---
 
@@ -97,6 +99,7 @@ Intent DNA currently focuses on:
 - Role-based agent workflows
 - Template-driven project bootstrap and upgrades
 - Deterministic guardrails and stateful enforcement
+- Resolver-backed artifact handoff between workflow steps
 - Dogfood-driven template iteration
 
 Adapter and ecosystem direction are tracked in [ROADMAP.md](ROADMAP.md), not duplicated here.

package/dist/hooks/cli.d.ts

@@ -14,7 +14,7 @@
  *
  * Fail-open: all errors → { continue: true, suppressOutput: true }
  */
-import type { ConstraintIR, VerifierSpec } from "../schema/types.js";
+import type { ArtifactFact, ConstraintIR, VerifierSpec } from "../schema/types.js";
 import type { HookOutput } from "./protocol.js";
 import { blockOutput } from "./protocol.js";
 import { readWorkflowState } from "./state.js";
@@ -39,6 +39,20 @@ export declare function computeSummary(traces: Array<{
     reason?: string;
 }>): SessionSummary;
 export declare function formatSummary(s: SessionSummary): string | null;
+declare function recordProducedArtifacts(projectDir: string, ir: ConstraintIR, wfState: {
+    workflow: string;
+    current_step: string;
+    inputs?: Record<string, string>;
+    resolved_variables?: Record<string, string>;
+}, sessionId?: string): Promise<ArtifactFact[]>;
+declare function resolveWorkflowArtifactFacts(projectDir: string, ir: ConstraintIR, wfState: {
+    workflow: string;
+    current_step: string;
+    inputs?: Record<string, string>;
+    resolved_variables?: Record<string, string>;
+}, sessionId?: string): Promise<ArtifactFact[]>;
+export declare const recordProducedArtifactsForTest: typeof recordProducedArtifacts;
+export declare const resolveWorkflowArtifactFactsForTest: typeof resolveWorkflowArtifactFacts;
 export declare function appendStopVerifierWarnings(output: HookOutput, verifierResults: VerifierResultEntry[], currentStep?: string): HookOutput;
 export declare function runVerifiersForTest(projectDir: string, ir: ConstraintIR, workflowState: {
     workflow: string;
@@ -81,3 +95,4 @@ export declare function handlePreToolGates(ir: ConstraintIR, rawInput: Record<st
  * Fail-open: any exception returns null.
  */
 export declare function buildWorkflowGuidance(projectDir: string, wfState: Awaited<ReturnType<typeof readWorkflowState>>, sessionId?: string): Promise<string | null>;
+export {};

package/dist/hooks/cli.js

@@ -14,14 +14,14 @@
  *
  * Fail-open: all errors → { continue: true, suppressOutput: true }
  */
-import { readFile, realpath, stat } from "node:fs/promises";
+import { mkdir, readFile, realpath, stat, unlink, writeFile } from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { readStdin, writeOutput, silentOutput, allowOutput, blockOutput, stopOutput } from "./protocol.js";
 import { validateHookInput } from "./schema.js";
 import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, extractBashWritePaths, checkReflectionLimit, checkContextReadiness, checkWorkflowBoundary, } from "./enforce.js";
-import { appendAudit, readWorkflowState, appendTrace, rotateTraces, readTraces, cleanStaleState, readSurgeonAttempts, writeSurgeonAttempts, appendSessionRead, readSessionReads, appendVerifierResult } from "./state.js";
+import { appendAudit, readWorkflowState, appendTrace, rotateTraces, readTraces, cleanStaleState, readSurgeonAttempts, writeSurgeonAttempts, appendSessionRead, readSessionReads, appendVerifierResult, appendCompletedArtifact, artifactIdentity, buildArtifactKey, readArtifactManifest, resolveArtifactTemplate, safePathComponent, writeArtifactManifest } from "./state.js";
 import { writeAuditEvent } from "../audit/index.js";
 // ── Constants ──────────────────────────────────────────────
 const DEFAULT_IR_PATH = ".dna/compiled/ir.json";
@@ -116,13 +116,15 @@ async function main() {
                 completed_artifacts: wfStateRaw.completed_artifacts,
                 iteration: wfStateRaw.iteration, // G4: pass iteration for state-driven rules
             };
-            // Re-run fallback: scan consumed artifact paths on disk so
-            // enforceHandoffConsumes can skip blocks for files that already exist.
-            if (event === "PreToolUse") {
-                state.existingArtifactPaths = await scanConsumedArtifactPaths(projectDir, ir, wfStateRaw.workflow, wfStateRaw.current_step);
-            }
+            state.artifactFacts = await resolveWorkflowArtifactFacts(projectDir, ir, wfStateRaw, sessionId);
         }
     }
+    if (event === "PreToolUse" && wfStateRaw?.active) {
+        try {
+            await captureGitCommitBefore(projectDir, ir, wfStateRaw, rawInput, sessionId);
+        }
+        catch { /* fail-open */ }
+    }
     // Phase 2B: PreToolUse gates (workflow boundary + context gate).
     // Run before dispatch so the block shortcircuits the rest of the pipeline.
     if (event === "PreToolUse") {
@@ -154,6 +156,7 @@ async function main() {
             current_role: wfState.current_role,
             started_at: wfState.started_at,
             completed_artifacts: wfState.completed_artifacts,
+            artifact_facts: wfState.active ? await finalizeAndResolveArtifacts(projectDir, ir, wfState, sessionId) : [],
         } : null;
         const verifierResults = stopContext?.active
             ? await runStopVerifiersForTest(projectDir, ir, stopContext, sessionId)
@@ -245,6 +248,13 @@ async function main() {
             }
         }
         catch { /* fail-open */ }
+        try {
+            if (wfStateRaw?.active) {
+                await recordGitCommitHandoff(projectDir, ir, wfStateRaw, rawInput, sessionId);
+                await recordProducedArtifacts(projectDir, ir, wfStateRaw, sessionId);
+            }
+        }
+        catch { /* fail-open */ }
     }
     // Extract target file path for trace + pattern detection
     const toolInput = typeof rawInput.tool_input === "object" && rawInput.tool_input !== null
@@ -395,36 +405,151 @@ async function loadIR(irPath) {
         return null;
     }
 }
-// ── Artifact Scanning ─────────────────────────────────────
-/**
- * Check consumed artifact paths on disk for the current workflow step.
- * Returns a Set of artifact paths that exist, enabling re-run idempotency
- * (prior run's output files satisfy the current step's consumes).
- */
-async function scanConsumedArtifactPaths(projectDir, ir, workflowName, currentStep) {
-    const paths = new Set();
-    if (!ir.workflows_ir)
-        return paths;
-    const activeWf = ir.workflows_ir.find(w => w.workflow_name === workflowName);
-    if (!activeWf)
-        return paths;
-    const entry = activeWf.handoff_chain.find(h => h.step_id === currentStep);
-    if (!entry?.consumes)
-        return paths;
-    for (const consumed of entry.consumes) {
-        if (!consumed.path)
+// ── Artifact Manifest Resolution ─────────────────────────
+function workflowEntry(ir, workflowName, stepId) {
+    return ir.workflows_ir
+        ?.find(w => w.workflow_name === workflowName)
+        ?.handoff_chain.find(h => h.step_id === stepId) ?? null;
+}
+function findProducerStep(ir, workflowName, consumed) {
+    if (consumed.from)
+        return consumed.from;
+    const workflow = ir.workflows_ir?.find(w => w.workflow_name === workflowName);
+    const producer = workflow?.handoff_chain.find(h => h.produces?.some(p => p.type === consumed.type && ((p.path && consumed.path && p.path === consumed.path) ||
+        (p.name && consumed.name && p.name === consumed.name) ||
+        (p.artifact_id && consumed.artifact_id && p.artifact_id === consumed.artifact_id))));
+    return producer?.step_id ?? "external";
+}
+async function projectRelativeExistingPath(projectDir, path) {
+    const fullPath = resolve(projectDir, path);
+    let realProject;
+    let realTarget;
+    try {
+        realProject = await realpath(projectDir);
+        realTarget = await realpath(fullPath);
+    }
+    catch {
+        return null;
+    }
+    const rel = relative(realProject, realTarget);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
+        return null;
+    await stat(realTarget);
+    return rel;
+}
+function resolvedArtifactIdentity(artifact, wfState) {
+    const resolvedPath = artifact.path ? resolveArtifactTemplate(artifact.path, wfState) : undefined;
+    if (artifact.path && !resolvedPath)
+        return null;
+    const identity = artifactIdentity(artifact, resolvedPath ?? undefined);
+    return identity ? { identity, resolvedPath: resolvedPath ?? undefined } : null;
+}
+async function writeManifestForArtifact(projectDir, workflowName, sessionId, producerStep, artifact, wfState, metadata) {
+    const resolved = resolvedArtifactIdentity(artifact, wfState);
+    if (!resolved)
+        return null;
+    const key = buildArtifactKey({ workflow: workflowName, sessionId, producerStep, type: artifact.type, identity: resolved.identity });
+    const fact = await writeArtifactManifest(projectDir, {
+        key,
+        type: artifact.type,
+        workflow: workflowName,
+        session_id: sessionId,
+        producer_step: producerStep,
+        identity: resolved.identity,
+        path: resolved.resolvedPath,
+        contract_path: artifact.path,
+        name: artifact.name,
+        artifact_id: artifact.artifact_id,
+        metadata,
+    });
+    await appendCompletedArtifact(projectDir, producerStep, {
+        type: artifact.type,
+        path: fact.manifest_path,
+        artifact_id: fact.id,
+        metadata,
+    }, sessionId);
+    return fact;
+}
+async function recordProducedArtifacts(projectDir, ir, wfState, sessionId) {
+    const sid = sessionId ?? "";
+    if (!sid)
+        return [];
+    const entry = workflowEntry(ir, wfState.workflow, wfState.current_step);
+    const facts = [];
+    for (const produced of entry?.produces ?? []) {
+        if (produced.type === "git_commit")
             continue;
-        const fullPath = resolve(projectDir, consumed.path);
-        try {
-            await stat(fullPath);
-            paths.add(consumed.path);
+        const resolved = resolvedArtifactIdentity(produced, wfState);
+        if (!resolved)
+            continue;
+        let metadata;
+        if (resolved.resolvedPath) {
+            const rel = await projectRelativeExistingPath(projectDir, resolved.resolvedPath);
+            if (!rel)
+                continue;
+            metadata = { source_path: rel };
         }
-        catch {
-            // File doesn't exist — not an error, just means artifact not available
+        else if (produced.type !== "summary" && produced.type !== "state" && produced.type !== "test_result") {
+            continue;
+        }
+        const fact = await writeManifestForArtifact(projectDir, wfState.workflow, sid, wfState.current_step, produced, wfState, metadata);
+        if (fact && await verifyArtifactFact(projectDir, fact))
+            facts.push(fact);
+    }
+    return facts;
+}
+async function verifyArtifactFact(projectDir, fact) {
+    if (fact.type === "file" || fact.type === "directory") {
+        if (!fact.path)
+            return false;
+        return (await projectRelativeExistingPath(projectDir, fact.path)) !== null;
+    }
+    if (fact.type === "test_result") {
+        if (!fact.path)
+            return true;
+        return (await projectRelativeExistingPath(projectDir, fact.path)) !== null;
+    }
+    if (fact.type === "git_commit") {
+        const commit = typeof fact.metadata?.commit === "string" ? fact.metadata.commit : undefined;
+        if (!commit)
+            return false;
+        return (await runGit(projectDir, ["cat-file", "-e", `${commit}^{commit}`])) !== null;
+    }
+    return true;
+}
+async function resolveWorkflowArtifactFacts(projectDir, ir, wfState, sessionId) {
+    const sid = sessionId ?? "";
+    if (!sid)
+        return [];
+    const facts = [];
+    const entry = workflowEntry(ir, wfState.workflow, wfState.current_step);
+    const contracts = [...(entry?.consumes ?? []), ...(entry?.produces ?? [])];
+    for (const artifact of contracts) {
+        if (artifact.required === false)
+            continue;
+        const producerStep = entry?.produces?.includes(artifact) ? wfState.current_step : findProducerStep(ir, wfState.workflow, artifact);
+        const resolved = resolvedArtifactIdentity(artifact, wfState);
+        if (!resolved)
+            continue;
+        const key = buildArtifactKey({ workflow: wfState.workflow, sessionId: sid, producerStep, type: artifact.type, identity: resolved.identity });
+        let fact = await readArtifactManifest(projectDir, key);
+        if (!fact && producerStep === "external" && artifact.path && resolved.resolvedPath) {
+            const rel = await projectRelativeExistingPath(projectDir, resolved.resolvedPath);
+            if (rel) {
+                fact = await writeManifestForArtifact(projectDir, wfState.workflow, sid, "external", artifact, wfState, { source_path: rel, external_input: true });
+            }
         }
+        if (fact && await verifyArtifactFact(projectDir, fact))
+            facts.push(fact);
     }
-    return paths;
+    return facts;
+}
+async function finalizeAndResolveArtifacts(projectDir, ir, wfState, sessionId) {
+    await recordProducedArtifacts(projectDir, ir, wfState, sessionId);
+    return resolveWorkflowArtifactFacts(projectDir, ir, wfState, sessionId);
 }
+export const recordProducedArtifactsForTest = recordProducedArtifacts;
+export const resolveWorkflowArtifactFactsForTest = resolveWorkflowArtifactFacts;
 function clearBlockingVerifierCheckpoints(ir, workflowState) {
     if (!workflowState || !ir.verifier_specs || ir.verifier_specs.length === 0)
         return ir;
@@ -1002,6 +1127,89 @@ export async function runStopVerifiersForTest(projectDir, ir, workflowState, ses
     results.push(...await runVerifiersForTest(projectDir, ir, workflowState, "stop", sessionId, options));
     return results;
 }
+// ── Handoff Artifact Recording ───────────────────────────
+function stepProducesGitCommit(ir, workflow, stepId) {
+    const activeWf = ir.workflows_ir?.find(w => w.workflow_name === workflow);
+    const currentEntry = activeWf?.handoff_chain.find(h => h.step_id === stepId);
+    return Boolean(currentEntry?.produces?.some(p => p.type === "git_commit"));
+}
+async function runGit(projectDir, args) {
+    return new Promise((resolveResult) => {
+        const child = spawn("git", args, { cwd: projectDir, stdio: ["ignore", "pipe", "ignore"] });
+        const chunks = [];
+        child.stdout.on("data", (chunk) => chunks.push(chunk));
+        child.on("close", (code) => {
+            if (code !== 0) {
+                resolveResult(null);
+                return;
+            }
+            resolveResult(Buffer.concat(chunks).toString("utf-8").trim());
+        });
+        child.on("error", () => resolveResult(null));
+    });
+}
+function gitCommitCapturePath(projectDir, workflow, stepId, sessionId) {
+    const safeWorkflow = safePathComponent(workflow, "workflow");
+    const safeStepId = safePathComponent(stepId, "step_id");
+    if (!sessionId)
+        return join(projectDir, ".dna", "state", "git-commit-before", safeWorkflow, `${safeStepId}.json`);
+    return join(projectDir, ".dna", "state", "sessions", safePathComponent(sessionId, "session_id"), "handoffs", safeWorkflow, safeStepId, "git-commit-before.json");
+}
+async function captureGitCommitBefore(projectDir, ir, workflowState, input, sessionId) {
+    if (!sessionId)
+        return;
+    if (!stepProducesGitCommit(ir, workflowState.workflow, workflowState.current_step))
+        return;
+    if (input.tool_name !== "Bash")
+        return;
+    const command = typeof input.tool_input?.command === "string"
+        ? input.tool_input.command
+        : "";
+    if (!/\bgit\s+commit\b/.test(command))
+        return;
+    const before = await runGit(projectDir, ["rev-parse", "HEAD"]);
+    if (!before)
+        return;
+    const capturePath = gitCommitCapturePath(projectDir, workflowState.workflow, workflowState.current_step, sessionId);
+    await mkdir(dirname(capturePath), { recursive: true });
+    await writeFile(capturePath, JSON.stringify({ before, captured_at: new Date().toISOString() }, null, 2), "utf-8");
+}
+async function recordGitCommitHandoff(projectDir, ir, workflowState, input, sessionId) {
+    if (!sessionId)
+        return;
+    if (!stepProducesGitCommit(ir, workflowState.workflow, workflowState.current_step))
+        return;
+    if (input.tool_name !== "Bash")
+        return;
+    const command = typeof input.tool_input?.command === "string"
+        ? input.tool_input.command
+        : "";
+    if (!/\bgit\s+commit\b/.test(command))
+        return;
+    const capturePath = gitCommitCapturePath(projectDir, workflowState.workflow, workflowState.current_step, sessionId);
+    let base;
+    try {
+        const capture = JSON.parse(await readFile(capturePath, "utf-8"));
+        base = capture.before;
+        await unlink(capturePath).catch(() => { });
+    }
+    catch {
+        return;
+    }
+    if (!base)
+        return;
+    const commit = await runGit(projectDir, ["rev-parse", "HEAD"]);
+    if (!commit || commit === base)
+        return;
+    const subject = await runGit(projectDir, ["log", "-1", "--format=%s", commit]);
+    const changedPaths = base
+        ? (await runGit(projectDir, ["diff", "--name-only", base, commit]))?.split("\n").filter(Boolean) ?? []
+        : [];
+    const dirtyAfter = (await runGit(projectDir, ["status", "--porcelain"]))?.split("\n").filter(Boolean) ?? [];
+    const entry = workflowEntry(ir, workflowState.workflow, workflowState.current_step);
+    const contract = entry?.produces?.find(p => p.type === "git_commit") ?? { type: "git_commit", description: "Git commit" };
+    await writeManifestForArtifact(projectDir, workflowState.workflow, sessionId ?? "", workflowState.current_step, contract, workflowState, { commit, base, subject, changed_paths: changedPaths, dirty_after: dirtyAfter });
+}
 // ── Surgeon Reflection Gate ──────────────────────────────
 /** Regex to parse test green count from vitest/flutter test output */
 const TEST_PASSED_RE = /(\d+)\s+(?:tests?\s+)?passed/i;
@@ -1176,7 +1384,8 @@ export async function handlePreToolGates(ir, rawInput, wfState, projectDir, sess
             }
             if (required.length > 0) {
                 const sessionReadsState = await readSessionReads(projectDir, sessionId);
-                const ready = checkContextReadiness(sessionReadsState.read_files, required);
+                const resolvedRequired = required.map(path => resolveArtifactTemplate(path, wfState) ?? path);
+                const ready = checkContextReadiness(sessionReadsState.read_files, resolvedRequired);
                 if (!ready.ready) {
                     return {
                         output: blockOutput(`[Intent DNA] Context Gate: required context files not yet read — ${ready.missing.join(", ")}. Read them before attempting ${toolName}.`),

package/dist/hooks/enforce.d.ts

@@ -13,7 +13,7 @@
  *
  * Step checkpoints are handled by the CLI, not here.
  */
-import type { ConstraintIR, RoleDef, CompletedArtifactEntry } from "../schema/types.js";
+import type { ConstraintIR, RoleDef, ArtifactFact, CompletedArtifactEntry } from "../schema/types.js";
 import type { PreToolUseInput, PostToolUseInput, UserPromptSubmitInput, SubagentStopInput, NotificationInput, EnforceResult } from "./protocol.js";
 /** SessionStart input fields */
 export interface SessionStartInput {
@@ -31,9 +31,8 @@ export interface EnforceState {
         /** G4: current workflow iteration (for relax_after_iteration rules) */
         iteration?: number;
     };
-    /** Artifact paths that exist on disk — fallback for re-run idempotency.
-     *  CLI checks disk, passes paths here so enforce stays pure (no I/O). */
-    existingArtifactPaths?: Set<string>;
+    /** Resolved artifact facts loaded by CLI/state before pure enforcement. */
+    artifactFacts?: ArtifactFact[];
 }
 /**
  * Enforce PreToolUse constraints.
@@ -90,6 +89,7 @@ export interface StopWorkflowContext {
     current_role: string;
     started_at: string;
     completed_artifacts?: CompletedArtifactEntry[];
+    artifact_facts?: ArtifactFact[];
 }
 /**
  * Enforce Stop hook — verify workflow checkpoint completion.
@@ -112,7 +112,7 @@ export declare function enforceStop(ir: ConstraintIR, input: StopEnforceInput, w
 export declare function enforceHandoffProduces(ir: ConstraintIR, wfState: {
     current_step: string;
     workflow: string;
-    completed_artifacts?: CompletedArtifactEntry[];
+    artifact_facts?: ArtifactFact[];
 }): 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;

package/dist/hooks/enforce.js

@@ -58,7 +58,7 @@ export function enforcePreToolUse(ir, input, state, roles) {
     }
     // Layer 6: Handoff — check consumed artifacts are available
     if (state?.workflowState && ir.workflows_ir) {
-        const result = enforceHandoffConsumes(ir, state.workflowState, state.existingArtifactPaths);
+        const result = enforceHandoffConsumes(ir, state.workflowState, state.artifactFacts ?? []);
         if (result)
             return { output: result, trace: { matched_rule: "handoff", step_id: state.workflowState.current_step } };
     }
@@ -283,20 +283,18 @@ export function enforceStop(ir, input, workflowState) {
             }
         }
     }
+    const handoffResult = enforceHandoffProduces(ir, {
+        current_step: workflowState.current_step,
+        workflow: workflowState.workflow,
+        artifact_facts: workflowState.artifact_facts ?? [],
+    });
+    if (handoffResult)
+        return handoffResult;
     if (workflowCheckpoints.length === 0) {
         return null;
     }
     const blocking = workflowCheckpoints.flatMap(cp => cp.checkpoints.filter(c => (c.action ?? "block") === "block"));
     if (blocking.length === 0) {
-        if (workflowState.workflow) {
-            const handoffResult = enforceHandoffProduces(ir, {
-                current_step: workflowState.current_step,
-                workflow: workflowState.workflow,
-                completed_artifacts: workflowState.completed_artifacts,
-            });
-            if (handoffResult)
-                return handoffResult;
-        }
         return null;
     }
     const messages = blocking.map(c => c.message);
@@ -359,26 +357,23 @@ function getStepAdditionalPaths(ir, state) {
  * 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, existingPaths) {
+function enforceHandoffConsumes(ir, wfState, artifactFacts) {
     const activeWf = ir.workflows_ir?.find(w => w.workflow_name === wfState.workflow);
-    if (!activeWf || activeWf.handoff_chain.length === 0)
+    if (!activeWf || (activeWf.handoff_chain?.length ?? 0) === 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)) {
-            // Re-run fallback: if the consumed artifact file exists on disk
-            // (from a prior run), treat the dependency as satisfied.
-            if (consumed.path && existingPaths?.has(consumed.path)) {
-                continue;
-            }
-            return blockOutput(`[Intent DNA] Step '${wfState.current_step}' requires artifact from step '${producer.step_id}' (${consumed.description}). Run step '${producer.step_id}' first.`);
+        if (consumed.required === false)
+            continue;
+        const producerStep = consumed.from ?? findProducerStep(activeWf.handoff_chain, consumed) ?? "external";
+        const fact = artifactFacts.find(a => artifactMatches(a, consumed, producerStep, wfState.workflow));
+        if (!fact) {
+            return blockOutput(`[Intent DNA] Step '${wfState.current_step}' requires artifact '${consumed.description}' from '${producerStep}', but no verified manifest was resolved.`);
+        }
+        if (consumed.type === "git_commit" && typeof fact.metadata?.commit !== "string") {
+            return blockOutput(`[Intent DNA] Step '${wfState.current_step}' requires git_commit artifact from '${producerStep}', but no commit identity was recorded.`);
         }
     }
     return null;
@@ -390,22 +385,52 @@ function enforceHandoffConsumes(ir, wfState, existingPaths) {
  */
 export function enforceHandoffProduces(ir, wfState) {
     const activeWf = ir.workflows_ir?.find(w => w.workflow_name === wfState.workflow);
-    if (!activeWf || activeWf.handoff_chain.length === 0)
+    if (!activeWf || (activeWf.handoff_chain?.length ?? 0) === 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);
+    const facts = wfState.artifact_facts ?? [];
     for (const produced of currentEntry.produces) {
-        if (produced.path && (!currentArtifacts || !currentArtifacts.artifacts.some(a => a.path === produced.path))) {
+        if (produced.required === false)
+            continue;
+        const fact = facts.find(a => artifactMatches(a, produced, wfState.current_step, wfState.workflow));
+        if (!fact) {
+            return {
+                output: blockOutput(`[Intent DNA] Step '${wfState.current_step}' must produce artifact '${produced.description}' before proceeding; no verified manifest was resolved.`),
+                trace: { matched_rule: "handoff", step_id: wfState.current_step },
+            };
+        }
+        if (produced.type === "git_commit" && typeof fact.metadata?.commit !== "string") {
             return {
-                output: blockOutput(`[Intent DNA] Step '${wfState.current_step}' must produce artifact '${produced.description}' (path: ${produced.path}) before proceeding.`),
+                output: blockOutput(`[Intent DNA] Step '${wfState.current_step}' must produce git_commit artifact '${produced.description}' with recorded commit identity before proceeding.`),
                 trace: { matched_rule: "handoff", step_id: wfState.current_step },
             };
         }
     }
     return null;
 }
+function findProducerStep(handoffChain, consumed) {
+    const producer = handoffChain.find(h => h.produces?.some(p => p.type === consumed.type && ((p.path && consumed.path && p.path === consumed.path) ||
+        (p.name && consumed.name && p.name === consumed.name) ||
+        (p.artifact_id && consumed.artifact_id && p.artifact_id === consumed.artifact_id))));
+    return producer?.step_id ?? null;
+}
+function artifactMatches(fact, artifact, producerStep, workflow) {
+    if (fact.workflow !== workflow)
+        return false;
+    if (fact.producer_step !== producerStep)
+        return false;
+    if (fact.type !== artifact.type)
+        return false;
+    if (artifact.path && fact.contract_path !== artifact.path && fact.path !== artifact.path)
+        return false;
+    if (artifact.name && fact.name !== artifact.name && fact.identity !== artifact.name)
+        return false;
+    if (artifact.artifact_id && fact.artifact_id !== artifact.artifact_id && fact.identity !== artifact.artifact_id)
+        return false;
+    return true;
+}
 function enforceRoleScope(rolesScopeMap, input, additionalWritePaths = []) {
     if (!input.agent_type)
         return null;

package/dist/hooks/state.d.ts

@@ -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 type { CompletedArtifactEntry, VerifierKind, VerifierSeverity, VerifierWhen } from "../schema/types.js";
+import type { ArtifactFact, ArtifactKey, ArtifactManifest, CompletedArtifactEntry, HandoffArtifact, HandoffType, VerifierKind, VerifierSeverity, VerifierWhen } from "../schema/types.js";
 /** Workflow state written by runtime and read by hooks */
 export interface DNAWorkflowState {
     active: boolean;
@@ -19,6 +19,8 @@ export interface DNAWorkflowState {
     iteration: number;
     session_id: string;
     started_at: string;
+    inputs?: Record<string, string>;
+    resolved_variables?: Record<string, string>;
     completed_artifacts?: CompletedArtifactEntry[];
 }
 /** Audit log entry (one per line in JSON Lines format) */
@@ -48,12 +50,28 @@ export interface SurgeonAttemptState {
         lesson: string;
     }>;
 }
+export declare function safePathComponent(value: string, label: string): string;
 /**
  * Resolve state directory path.
  * With session isolation: `.dna/state/sessions/<sessionId>/`
  * Without: `.dna/state/`
  */
 export declare function resolveStateDir(projectDir: string, sessionId?: string): string;
+export declare const ARTIFACT_RESOLVER_VERSION = 1;
+export declare function isRequiredArtifact(artifact: HandoffArtifact): boolean;
+export declare function artifactIdentity(artifact: HandoffArtifact, resolvedPath?: string): string | null;
+export declare function artifactHash(key: ArtifactKey): string;
+export declare function buildArtifactKey(params: {
+    workflow: string;
+    sessionId: string;
+    producerStep: string;
+    type: HandoffType;
+    identity: string;
+}): ArtifactKey;
+export declare function artifactManifestPath(projectDir: string, key: ArtifactKey): string;
+export declare function resolveArtifactTemplate(template: string, state?: Pick<DNAWorkflowState, "inputs" | "resolved_variables">): string | null;
+export declare function writeArtifactManifest(projectDir: string, manifest: Omit<ArtifactManifest, "id" | "recorded_at" | "resolver_version">): Promise<ArtifactFact>;
+export declare function readArtifactManifest(projectDir: string, key: ArtifactKey): Promise<ArtifactFact | null>;
 /**
  * Read current workflow state. Returns null if not found or stale.
  * @deprecated Prefer `new DNAStateManager(projectDir, sessionId).readWorkflowState()`.
@@ -83,6 +101,8 @@ export declare function appendAudit(projectDir: string, entry: AuditEntry): Prom
 export declare function appendCompletedArtifact(projectDir: string, stepId: string, artifact: {
     type: string;
     path: string;
+    artifact_id?: string;
+    metadata?: Record<string, unknown>;
 }, sessionId?: string): Promise<void>;
 /** Atomic write: write to temp file then rename. */
 export declare function atomicWrite(filePath: string, data: string): Promise<void>;

package/dist/hooks/state.js

@@ -10,10 +10,27 @@
  * All write operations use atomic temp+rename pattern.
  */
 import { readFile, writeFile, rename, mkdir, appendFile, unlink, readdir, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import { join, dirname } from "node:path";
 // ── Constants ──────────────────────────────────────────────
 const WORKFLOW_FILE = "workflow.json";
 const DEFAULT_STALENESS_MS = 2 * 60 * 60 * 1000; // 2 hours
+const SAFE_PATH_COMPONENT = /^[A-Za-z0-9._-]{1,128}$/;
+const USER_ARTIFACT_PATH_ARGUMENTS = new Set(["ARGUMENTS", "arguments", "task_id"]);
+export function safePathComponent(value, label) {
+    if (value === "." || value === ".." || !SAFE_PATH_COMPONENT.test(value)) {
+        throw new Error(`Invalid ${label}`);
+    }
+    return value;
+}
+function safeUserArtifactPathArgument(value, label) {
+    try {
+        return safePathComponent(value, label);
+    }
+    catch {
+        return null;
+    }
+}
 // ── Path Resolution ────────────────────────────────────────
 /**
  * Resolve state directory path.
@@ -23,10 +40,97 @@ const DEFAULT_STALENESS_MS = 2 * 60 * 60 * 1000; // 2 hours
 export function resolveStateDir(projectDir, sessionId) {
     const base = join(projectDir, ".dna", "state");
     if (sessionId) {
-        return join(base, "sessions", sessionId);
+        return join(base, "sessions", safePathComponent(sessionId, "session_id"));
     }
     return base;
 }
+export const ARTIFACT_RESOLVER_VERSION = 1;
+export function isRequiredArtifact(artifact) {
+    return artifact.required !== false;
+}
+export function artifactIdentity(artifact, resolvedPath) {
+    return artifact.artifact_id ?? artifact.name ?? resolvedPath ?? (artifact.type === "git_commit" ? "git_commit" : null);
+}
+export function artifactHash(key) {
+    return createHash("sha256")
+        .update(JSON.stringify(key))
+        .digest("hex")
+        .slice(0, 16);
+}
+export function buildArtifactKey(params) {
+    return {
+        workflow: params.workflow,
+        session_id: params.sessionId,
+        producer_step: params.producerStep,
+        type: params.type,
+        identity: params.identity,
+    };
+}
+export function artifactManifestPath(projectDir, key) {
+    return join(resolveStateDir(projectDir, key.session_id), "handoffs", safePathComponent(key.workflow, "workflow"), safePathComponent(key.producer_step, "producer_step"), `${artifactHash(key)}.json`);
+}
+export function resolveArtifactTemplate(template, state) {
+    let resolved = template;
+    const inputs = state?.inputs ?? {};
+    const resolvedVariables = state?.resolved_variables ?? {};
+    resolved = resolved.replace(/\{\{(\w+)\}\}/g, (_match, name) => {
+        const inputValue = inputs[name];
+        if (inputValue !== undefined) {
+            return safeUserArtifactPathArgument(inputValue, name) ?? `{{${name}}}`;
+        }
+        const resolvedValue = resolvedVariables[name];
+        if (resolvedValue === undefined)
+            return `{{${name}}}`;
+        if (USER_ARTIFACT_PATH_ARGUMENTS.has(name)) {
+            return safeUserArtifactPathArgument(resolvedValue, name) ?? `{{${name}}}`;
+        }
+        return resolvedValue;
+    });
+    const args = inputs.ARGUMENTS ?? inputs.arguments ?? inputs.task_id ?? resolvedVariables.ARGUMENTS ?? resolvedVariables.arguments ?? resolvedVariables.task_id;
+    if (resolved.includes("$ARGUMENTS")) {
+        if (args === undefined)
+            return null;
+        const safeArgs = safeUserArtifactPathArgument(args, "ARGUMENTS");
+        if (!safeArgs)
+            return null;
+        resolved = resolved.replaceAll("$ARGUMENTS", safeArgs);
+    }
+    if (/\{\{\w+\}\}/.test(resolved))
+        return null;
+    return resolved;
+}
+export async function writeArtifactManifest(projectDir, manifest) {
+    const id = artifactHash(manifest.key);
+    const full = {
+        ...manifest,
+        id,
+        recorded_at: new Date().toISOString(),
+        resolver_version: ARTIFACT_RESOLVER_VERSION,
+    };
+    const manifestPath = artifactManifestPath(projectDir, manifest.key);
+    await atomicWrite(manifestPath, JSON.stringify(full, null, 2));
+    return { ...full, manifest_path: manifestPath };
+}
+export async function readArtifactManifest(projectDir, key) {
+    const manifestPath = artifactManifestPath(projectDir, key);
+    try {
+        const manifest = JSON.parse(await readFile(manifestPath, "utf-8"));
+        if (manifest.resolver_version !== ARTIFACT_RESOLVER_VERSION)
+            return null;
+        if (manifest.key.workflow !== key.workflow || manifest.key.session_id !== key.session_id ||
+            manifest.key.producer_step !== key.producer_step || manifest.key.type !== key.type ||
+            manifest.key.identity !== key.identity)
+            return null;
+        if (manifest.workflow !== key.workflow || manifest.session_id !== key.session_id ||
+            manifest.producer_step !== key.producer_step || manifest.type !== key.type ||
+            manifest.identity !== key.identity)
+            return null;
+        return { ...manifest, manifest_path: manifestPath };
+    }
+    catch {
+        return null;
+    }
+}
 // ── Workflow State ─────────────────────────────────────────
 /**
  * Read current workflow state. Returns null if not found or stale.
@@ -121,13 +225,24 @@ export async function appendCompletedArtifact(projectDir, stepId, artifact, sess
         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))
+    const verifiedAt = new Date().toISOString();
+    const existing = stepEntry.artifacts.find(a => a.type === artifact.type && a.path === artifact.path);
+    if (existing) {
+        existing.verified_at = verifiedAt;
+        if (artifact.artifact_id)
+            existing.artifact_id = artifact.artifact_id;
+        if (artifact.metadata)
+            existing.metadata = artifact.metadata;
+        state.completed_artifacts = artifacts;
+        await writeWorkflowState(projectDir, state, sessionId);
         return;
+    }
     stepEntry.artifacts.push({
         type: artifact.type,
         path: artifact.path,
-        verified_at: new Date().toISOString(),
+        verified_at: verifiedAt,
+        ...(artifact.artifact_id ? { artifact_id: artifact.artifact_id } : {}),
+        ...(artifact.metadata ? { metadata: artifact.metadata } : {}),
     });
     state.completed_artifacts = artifacts;
     await writeWorkflowState(projectDir, state, sessionId);

package/dist/mcp/tools-state.js

@@ -11,6 +11,10 @@ import { resolve } from "node:path";
 import { readWorkflowState, writeWorkflowState, readTraces, listSessions } from "../hooks/state.js";
 import { loadCompiledIR } from "../runtime/plugin-adapter.js";
 import { textResult } from "./server.js";
+function isStringRecord(value) {
+    return typeof value === "object" && value !== null &&
+        Object.values(value).every(v => typeof v === "string");
+}
 export function createStateTools(projectDir) {
     return [
         // ── dna_status ────────────────────────────────────────
@@ -95,6 +99,8 @@ export function createStateTools(projectDir) {
                     iteration: { type: "number", description: "Current iteration number" },
                     active: { type: "boolean", description: "Whether workflow is active (false to deactivate)" },
                     session_id: { type: "string", description: "Session ID for isolation" },
+                    inputs: { type: "object", description: "Workflow runtime inputs such as ARGUMENTS" },
+                    resolved_variables: { type: "object", description: "Resolved template variables for artifact paths" },
                 },
                 required: ["workflow", "current_step", "current_role"],
             },
@@ -109,6 +115,8 @@ export function createStateTools(projectDir) {
                     iteration: typeof args.iteration === "number" ? args.iteration : (existing?.iteration ?? 1),
                     session_id: sessionId ?? existing?.session_id ?? "",
                     started_at: existing?.started_at ?? new Date().toISOString(),
+                    inputs: isStringRecord(args.inputs) ? args.inputs : existing?.inputs,
+                    resolved_variables: isStringRecord(args.resolved_variables) ? args.resolved_variables : existing?.resolved_variables,
                     completed_artifacts: existing?.completed_artifacts,
                 };
                 await writeWorkflowState(projectDir, state, sessionId);

package/dist/runtime/settings-adapter.js

@@ -70,10 +70,10 @@ export function detectEnabledEvents(ir) {
     const hasStopVerifiers = ir.verifier_specs?.some((spec) => spec.when === "stop" || spec.when === "pre_handoff" || spec.when === "post_step") ?? false;
     const hasPostToolVerifiers = ir.verifier_specs?.some((spec) => spec.when === "post_tool_use") ?? false;
     const hasHandoffs = ir.workflows_ir?.some((wf) => wf.handoff_chain.length > 0) ?? false;
-    if (hasGates || hasFilters || hasRoleScope || hasCheckpoints) {
+    if (hasGates || hasFilters || hasRoleScope || hasCheckpoints || hasHandoffs) {
         events.push("preToolUse");
     }
-    if (ir.post_execution_validators.length > 0 || hasPostToolVerifiers) {
+    if (ir.post_execution_validators.length > 0 || hasPostToolVerifiers || hasHandoffs) {
         events.push("postToolUse");
     }
     if (ir.prompt_directives.some(d => d.priority === "high")) {

package/dist/runtime/skill-adapter.js

@@ -42,6 +42,12 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
         lines.push("</Purpose>");
         lines.push("");
     }
+    lines.push("<Workflow_State>");
+    lines.push("At workflow start, persist runtime inputs in DNA workflow state before executing steps.");
+    lines.push("Record the invocation argument as inputs.ARGUMENTS so handoff artifact paths like $ARGUMENTS can be resolved deterministically.");
+    lines.push("If template variables are shown below, persist their resolved values as resolved_variables.");
+    lines.push("</Workflow_State>");
+    lines.push("");
     // Required Context — context files that must be read before any work
     const workflowKeys = [plan.workflow_key, plan.source_workflow, plan.name].filter((key, index, keys) => Boolean(key) && keys.indexOf(key) === index);
     const requiredReadAssets = [];

package/dist/schema/types.d.ts

@@ -94,9 +94,38 @@ export type HandoffType = "file" | "directory" | "test_result" | "git_commit" |
 export interface HandoffArtifact {
     type: HandoffType;
     path?: string;
+    name?: string;
+    artifact_id?: string;
     from?: string;
+    required?: boolean;
     description: string;
 }
+export interface ArtifactKey {
+    workflow: string;
+    session_id: string;
+    producer_step: string;
+    type: HandoffType;
+    identity: string;
+}
+export interface ArtifactManifest {
+    id: string;
+    key: ArtifactKey;
+    type: HandoffType;
+    workflow: string;
+    session_id: string;
+    producer_step: string;
+    identity: string;
+    path?: string;
+    contract_path?: string;
+    name?: string;
+    artifact_id?: string;
+    metadata?: Record<string, unknown>;
+    recorded_at: string;
+    resolver_version: number;
+}
+export interface ArtifactFact extends ArtifactManifest {
+    manifest_path: string;
+}
 /** Handoff declaration for a workflow step */
 export interface StepHandoff {
     consumes?: HandoffArtifact[];
@@ -344,13 +373,19 @@ export interface WorkflowIR {
     step_enforce_rules?: StepEnforceRule[];
 }
 /** Record of artifacts completed by a step — used for cross-session resume */
+export interface CompletedArtifactMetadata {
+    [key: string]: unknown;
+}
+export interface CompletedArtifactRecord {
+    type: string;
+    path: string;
+    verified_at: string;
+    artifact_id?: string;
+    metadata?: CompletedArtifactMetadata;
+}
 export interface CompletedArtifactEntry {
     step_id: string;
-    artifacts: {
-        type: string;
-        path: string;
-        verified_at: string;
-    }[];
+    artifacts: CompletedArtifactRecord[];
 }
 /** Runtime workflow state written to .dna/state/workflow.json */
 export interface WorkflowState {
@@ -361,6 +396,8 @@ export interface WorkflowState {
     iteration: number;
     session_id: string;
     started_at: string;
+    inputs?: Record<string, string>;
+    resolved_variables?: Record<string, string>;
     completed_artifacts?: CompletedArtifactEntry[];
 }
 export interface ConstraintIR {

package/dist/schema/validate.js

@@ -382,6 +382,16 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
                 }
             }
         }
+        for (const direction of ["consumes", "produces"]) {
+            const artifacts = step.handoff?.[direction] ?? [];
+            for (let j = 0; j < artifacts.length; j++) {
+                const artifact = artifacts[j];
+                const artifactPath = `${stepPath}.handoff.${direction}[${j}]`;
+                if (artifact.required !== false && artifact.type !== "git_commit" && !artifact.path && !artifact.name && !artifact.artifact_id) {
+                    errors.push({ path: artifactPath, message: "required handoff artifacts must define path, name, or artifact_id" });
+                }
+            }
+        }
         // checkpoints validation
         if (step.checkpoints) {
             if (!Array.isArray(step.checkpoints)) {

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

@@ -99,6 +99,7 @@ workflow:
             description: "Implementation to review"
         produces:
           - type: summary
+            required: false
             description: "Review verdict (PASS/FAIL)"
   transitions:
     - from: review

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

@@ -133,6 +133,7 @@ workflows:
         handoff:
           produces:
             - type: summary
+              name: breakpoint_analysis
               description: "Breakpoint analysis with file paths and line numbers"
       - id: fix
         role: surgeon
@@ -143,6 +144,7 @@ workflows:
           consumes:
             - type: summary
               from: trace
+              name: breakpoint_analysis
               description: "Breakpoint analysis from investigator"
           produces:
             - type: git_commit
@@ -159,4 +161,5 @@ workflows:
               description: "Fix commit to verify"
           produces:
             - type: summary
+              required: false
               description: "Verification result with screenshots"

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

@@ -254,13 +254,13 @@ roles:
       - "Output a structured verdict block with verdict, artifact_reviewed, sections_to_fix, evidence_paths, confidence, and summary"
 
   fix_reviewer:
-    description: "Reviews surgeon changes against approved diagnosis, v1 evidence, and v2 architecture. Read-only."
+    description: "Reviews surgeon changes against approved diagnosis, v1 evidence, and v2 architecture. Writes only the structured review verdict artifact."
     tool_permissions:
-      allow: [Read, Grep, Glob, Bash]
-      deny: [Edit, Write, NotebookEdit]
+      allow: [Read, Grep, Glob, Bash, Write]
+      deny: [Edit, NotebookEdit]
     scope:
       read: ["**/*"]
-      write: []
+      write: [".dna/reviews/**"]
     instructions:
       - "Read diagnosis spec, behavior doc, and git diff before judging"
       - "Verify changes are minimal and limited to the approved diagnosis classifications"
@@ -424,6 +424,7 @@ workflows:
               description: "Diagnosis spec from analyzer"
           produces:
             - type: summary
+              required: false
               description: "Review verdict (APPROVE or REQUEST_REANALYSIS)"
 
   fix:
@@ -474,9 +475,9 @@ workflows:
         depends_on: [fix_bugs]
         description: "Review surgeon changes before verification"
         prompt: |
-          Read diagnosis spec, behavior doc, and git diff.
+          Read diagnosis spec and behavior doc before reviewing the surgeon's handoff changes.
 
-          Review only the surgeon's changes:
+          Review only the surgeon's handoff changes:
           1. Are changes limited to BUG / UNIMPLEMENTED / INFRA / TEST_BUG items in the approved diagnosis?
           2. Is REMOVED handling absent unless explicitly approved by user?
           3. Does implementation preserve v1 behavior and follow v2 architecture?
@@ -495,6 +496,8 @@ workflows:
           }
           ```
 
+          Write the same verdict JSON to .dna/reviews/$ARGUMENTS-review.json before finishing.
+
           REQUEST_CHANGES → include failure_reason and concrete next_round_focus for the next fix invocation. The next_round_focus must name the priority/classification and specific test file or evidence path to address first.
         handoff:
           consumes:
@@ -508,7 +511,8 @@ workflows:
               path: "docs/behavior/$ARGUMENTS.md"
               description: "Behavior document"
           produces:
-            - type: summary
+            - type: file
+              path: ".dna/reviews/$ARGUMENTS-review.json"
               description: "Review verdict (APPROVE or REQUEST_CHANGES)"
 
       - id: verify_report
@@ -551,8 +555,9 @@ workflows:
           - BLOCKED: user confirmation is needed or repeated no-progress prevents safe continuation
         handoff:
           consumes:
-            - type: summary
+            - type: file
               from: review_changes
+              path: ".dna/reviews/$ARGUMENTS-review.json"
               description: "Review verdict from fix_reviewer"
             - type: git_commit
               from: fix_bugs
@@ -565,4 +570,5 @@ workflows:
               path: ".dna/fix-progress/$ARGUMENTS.md"
               description: "Durable cumulative fix-progress artifact for the next fix invocation"
             - type: summary
+              required: false
               description: "Verification report with test delta"

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

@@ -142,6 +142,7 @@ workflow:
             description: "Implementation to test"
         produces:
           - type: test_result
+            name: test_results
             description: "Test results after fixes"
     - id: review
       role: reviewer
@@ -151,9 +152,11 @@ workflow:
         consumes:
           - type: test_result
             from: test
+            name: test_results
             description: "Test results to review"
         produces:
           - type: summary
+            required: false
             description: "Review verdict (PASS/FAIL)"
   transitions:
     - from: review

package/package.json

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

package/spec/schema-spec.md

@@ -239,6 +239,8 @@ output_schema:
 
 Workflows define multi-step agent pipelines with dependency ordering, parallel execution, retry, and artifact handoff.
 
+Handoff artifacts compile into local session-scoped manifests. A required artifact must have a stable identity from `path`, `name`, or `artifact_id`; required `summary`/`state` artifacts without one are invalid. Runtime enforcement treats the manifest as the local fact source and uses workflow inputs such as `$ARGUMENTS` before resolving artifact keys. User-provided workflow `inputs` used in artifact path templates are constrained to safe single path components; trusted `resolved_variables` may still provide configured path prefixes. This blocks prompt/path/metadata-only satisfaction; cryptographic protection against direct manifest forgery is deferred to signing/registry work.
+
 ### Single Workflow
 ```yaml
 workflow:
@@ -266,6 +268,7 @@ workflow:
             description: "Implementation to review"
         produces:
           - type: summary
+            required: false
             description: "Review verdict"
 
   transitions: