intentdna 1.5.20 → 1.6.0

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.6.0",
       "author": {
         "name": "Samuel"
       },
@@ -25,5 +25,5 @@
       ]
     }
   ],
-  "version": "1.5.20"
+  "version": "1.6.0"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "intentdna",
-  "version": "1.5.20",
+  "version": "1.6.0",
   "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/cli/commands/sync.js

@@ -20,7 +20,7 @@ import { parseYAML } from "../../schema/yaml-parser.js";
 import { compileToMarkdown, injectIntoFile, removeFromFile } from "../../runtime/markdown.js";
 import { compileAllRolesToAgentMD, writeAgentMDFiles, removeAgentMDFiles } from "../../runtime/agent-md.js";
 import { removeWorkflowScripts } from "../../runtime/workflow-runner.js";
-import { compileWorkflowToSkill, writeSkillFiles } from "../../runtime/skill-adapter.js";
+import { compileWorkflowToSkill, compileControllerToSkill, writeSkillFiles } from "../../runtime/skill-adapter.js";
 import { compilePluginSettings, detectEnabledEvents, mergeSettingsFile, recommendHookTimeouts } from "../../runtime/settings-adapter.js";
 import { createCompiledIR, writeCompiledIR } from "../../runtime/plugin-adapter.js";
 import { cascadeDNA } from "../../compiler/cascade.js";
@@ -127,11 +127,9 @@ export async function cleanStaleDNAFiles(dir, type, activeNamespaces) {
         const entries = await readdir(dir, { withFileTypes: true });
         for (const entry of entries) {
             const fullPath = resolve(dir, entry.name);
-            // Extract namespace from filename: dna-{namespace}-*
-            const nsMatch = entry.name.match(/^dna-([a-z0-9_-]+)-/);
-            const fileNamespace = nsMatch ? nsMatch[1] : null;
-            // Skip if namespace doesn't match active namespaces
-            if (!fileNamespace || !activeNamespaces.includes(fileNamespace)) {
+            // Match active namespace prefixes directly so multi-hyphen names like
+            // dna-frw-fix-loop still resolve to namespace frw.
+            if (!activeNamespaces.some(ns => entry.name.startsWith(`dna-${ns}-`))) {
                 continue;
             }
             if (type === "agents" && entry.isFile() && entry.name.endsWith(".md")) {
@@ -653,6 +651,7 @@ export async function runSync(opts) {
             const dnas = loadedDNAs;
             const cascadedForSkills = cascadeDNA(dnas);
             const workflows = cascadedForSkills.workflows;
+            const controllers = cascadedForSkills.controllers;
             const roles = cascadedForSkills.roles;
             // Collect and resolve variables from all DNA files
             const rawVars = {};
@@ -676,8 +675,8 @@ export async function runSync(opts) {
                     process.stderr.write(`MCP: wrote ${Object.keys(mcpDeps).length} server(s) to ${mcpJsonPath}\n`);
                 }
             }
-            if (Object.keys(workflows).length === 0) {
-                process.stderr.write("No workflow defined — no skills to generate\n");
+            if (Object.keys(workflows).length === 0 && Object.keys(controllers).length === 0) {
+                process.stderr.write("No workflow or controller defined — no skills to generate\n");
             }
             else {
                 const { compileWorkflow } = await import("../../compiler/workflow.js");
@@ -688,6 +687,9 @@ export async function runSync(opts) {
                         skillResults.push(compileWorkflowToSkill(result.plan, roles, ir, variables));
                     }
                 }
+                for (const [name, controllerDef] of Object.entries(controllers)) {
+                    skillResults.push(compileControllerToSkill(name, controllerDef, variables, workflows));
+                }
                 if (skillResults.length > 0) {
                     const written = await writeSkillFiles(skillResults, opts.skillsDir);
                     process.stderr.write(`Generated ${written.length} skill file(s) in ${opts.skillsDir}\n`);

package/dist/compiler/cascade.d.ts

@@ -10,12 +10,13 @@
  *   - attract/repel: same target accumulates, different targets independent
  *   - amplify/suppress: factors multiply (1.5x × 2.0x = 3.0x)
  */
-import type { IntentDNA, Gene, ContextRegion, EpigeneticMarker, RoleDef, WorkflowDef, LegibilityAssetMap, VerifierCommandPolicy } from "../schema/types.js";
+import type { IntentDNA, Gene, ContextRegion, EpigeneticMarker, RoleDef, WorkflowDef, LegibilityAssetMap, VerifierCommandPolicy, ControllerDef } from "../schema/types.js";
 export interface CascadedDNA {
     genes: Record<string, Gene>;
     contexts: Record<string, ContextRegion>;
     roles: Record<string, RoleDef>;
     workflows: Record<string, WorkflowDef>;
+    controllers: Record<string, ControllerDef>;
     epigenetic_markers: EpigeneticMarker[];
     source_ids: string[];
     /** Warnings from cascade process (e.g., cross-namespace gene collisions) */

package/dist/compiler/cascade.js

@@ -91,6 +91,20 @@ function prefixRecordKeys(record, ns) {
         return record;
     return Object.fromEntries(Object.entries(record).map(([key, value]) => [`${ns}_${key}`, value]));
 }
+function prefixController(controller, ns) {
+    return {
+        ...controller,
+        diagnosis_workflow: `${ns}_${controller.diagnosis_workflow}`,
+        fix_workflow: `${ns}_${controller.fix_workflow}`,
+        roles: {
+            analyzer: `${ns}_${controller.roles.analyzer}`,
+            analysis_reviewer: `${ns}_${controller.roles.analysis_reviewer}`,
+            surgeon: `${ns}_${controller.roles.surgeon}`,
+            fix_reviewer: `${ns}_${controller.roles.fix_reviewer}`,
+            test_runner: `${ns}_${controller.roles.test_runner}`,
+        },
+    };
+}
 function prefixLegibilityAssets(map, ns) {
     if (!map)
         return undefined;
@@ -176,6 +190,7 @@ export function cascadeDNA(layers) {
     const mergedContexts = {};
     const mergedRoles = {};
     const mergedWorkflows = {};
+    const mergedControllers = {};
     const allMarkers = [];
     const sourceIds = [];
     const warnings = [];
@@ -225,6 +240,15 @@ export function cascadeDNA(layers) {
                 mergedWorkflows[name] = wf;
             }
         }
+        // Merge controllers: namespace-prefixed keys + workflow/role references
+        for (const [name, controller] of Object.entries(dna.controllers ?? {})) {
+            if (ns) {
+                mergedControllers[`${ns}_${name}`] = prefixController(controller, ns);
+            }
+            else {
+                mergedControllers[name] = controller;
+            }
+        }
         // Collect epigenetic markers
         if (dna.epigenetic?.markers) {
             allMarkers.push(...dna.epigenetic.markers);
@@ -250,6 +274,7 @@ export function cascadeDNA(layers) {
         contexts: mergedContexts,
         roles: mergedRoles,
         workflows: mergedWorkflows,
+        controllers: mergedControllers,
         epigenetic_markers: allMarkers,
         source_ids: sourceIds,
         warnings: warnings.length > 0 ? warnings : undefined,

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,9 +112,9 @@ 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). */
+/** Check if a file path is allowed by a list of write globs. */
 export declare function checkWriteAllowed(filePath: string, allowedGlobs: string[]): boolean;
 /**
  * Extract directory prefix from a glob pattern.