intentdna 1.5.2 → 1.5.4

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "intentdna",
       "description": "DNA template compilation + runtime enforcement",
-      "version": "1.5.2",
+      "version": "1.5.4",
       "source": "./"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "intentdna",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "description": "Declarative policy layer for AI agent governance"
 }

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

@@ -54,4 +54,27 @@ export { getPackageVersion } from "../util/version.js";
  * Throws if two configs declare the same namespace.
  */
 export declare function checkNamespaceCollisions(configPaths: string[]): Promise<void>;
+/**
+ * Compare two semver strings. Returns:
+ *   1  if a > b
+ *   0  if a == b
+ *  -1  if a < b
+ * Handles major.minor.patch format. Non-numeric parts are ignored.
+ */
+export declare function compareSemver(a: string, b: string): -1 | 0 | 1;
+/** Info about a single template that has an available upgrade. */
+export interface TemplateUpgradeInfo {
+    configPath: string;
+    templateName: string;
+    currentVersion: string;
+    availableVersion: string;
+}
+/**
+ * Check template versions against current package version.
+ * Returns upgrade info for outdated configs and prints human-readable suggestions.
+ *
+ * U1: Semver-aware comparison — only suggests upgrades when package is strictly newer.
+ * Handles missing _template_version (old configs created before versioning).
+ */
+export declare function checkTemplateVersions(configPaths: string[]): Promise<TemplateUpgradeInfo[]>;
 export declare function runSync(opts: SyncOptions): Promise<number>;

package/dist/cli/commands/sync.js

@@ -253,28 +253,72 @@ export async function checkNamespaceCollisions(configPaths) {
         }
     }
 }
+/**
+ * Compare two semver strings. Returns:
+ *   1  if a > b
+ *   0  if a == b
+ *  -1  if a < b
+ * Handles major.minor.patch format. Non-numeric parts are ignored.
+ */
+export function compareSemver(a, b) {
+    const parse = (v) => v.split(".").map(s => parseInt(s, 10) || 0);
+    const pa = parse(a);
+    const pb = parse(b);
+    const len = Math.max(pa.length, pb.length);
+    for (let i = 0; i < len; i++) {
+        const va = pa[i] ?? 0;
+        const vb = pb[i] ?? 0;
+        if (va > vb)
+            return 1;
+        if (va < vb)
+            return -1;
+    }
+    return 0;
+}
 /**
  * Check template versions against current package version.
- * Prints upgrade suggestions for outdated configs.
+ * Returns upgrade info for outdated configs and prints human-readable suggestions.
+ *
+ * U1: Semver-aware comparison — only suggests upgrades when package is strictly newer.
+ * Handles missing _template_version (old configs created before versioning).
  */
-async function checkTemplateVersions(configPaths) {
+export async function checkTemplateVersions(configPaths) {
     const pkgVersion = await getPackageVersion();
     if (!pkgVersion)
-        return;
+        return [];
+    const upgrades = [];
     for (const configPath of configPaths) {
         try {
             const content = await readFile(configPath, "utf-8");
             const data = parseYAML(content);
             const tmplVersion = typeof data._template_version === "string" ? data._template_version : undefined;
             const tmplName = typeof data._source_template === "string" ? data._source_template : undefined;
-            if (tmplVersion && tmplName && tmplVersion !== pkgVersion) {
-                process.stderr.write(`Template "${tmplName}" has update: ${tmplVersion} → ${pkgVersion}. Run: dna init --upgrade ${tmplName}\n`);
+            if (tmplName && !tmplVersion) {
+                // Old config without version tracking — suggest upgrade
+                upgrades.push({
+                    configPath,
+                    templateName: tmplName,
+                    currentVersion: "unknown",
+                    availableVersion: pkgVersion,
+                });
+                process.stderr.write(`Upgrade available: "${tmplName}" has no version tag. Run: dna init --upgrade ${tmplName}\n`);
+            }
+            else if (tmplVersion && tmplName && compareSemver(pkgVersion, tmplVersion) > 0) {
+                // Package is strictly newer than template — suggest upgrade
+                upgrades.push({
+                    configPath,
+                    templateName: tmplName,
+                    currentVersion: tmplVersion,
+                    availableVersion: pkgVersion,
+                });
+                process.stderr.write(`Upgrade available: "${tmplName}" ${tmplVersion} → ${pkgVersion}. Run: dna init --upgrade ${tmplName}\n`);
             }
         }
         catch {
             // Non-critical — skip version check for unparseable files
         }
     }
+    return upgrades;
 }
 function resolveSpeciesPath(ref) {
     if (!ref.startsWith("species:"))
@@ -483,6 +527,8 @@ export async function runSync(opts) {
             if (removed > 0) {
                 process.stderr.write(`Cleaned ${removed} legacy bash hook(s) from ${oldHooksDir}\n`);
             }
+            // G2/G3: Register built-in DNA MCP server in .claude/.mcp.json
+            await registerDNAMCPServer(cwd);
         }
         // Step 3.6: Register hooks in settings.json (bin mode only)
         // Plugin mode: hooks managed by plugin framework — skip settings.json
@@ -680,3 +726,28 @@ async function writeMCPConfig(mcpDeps, mcpJsonPath, variables) {
 function substituteVariables(template, vars) {
     return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? `{{${key}}}`);
 }
+/**
+ * G2/G3: Register the built-in DNA MCP server (dna-mcp) in .claude/.mcp.json.
+ * Idempotent: only adds if not already present.
+ */
+async function registerDNAMCPServer(cwd) {
+    const mcpJsonPath = resolve(cwd, ".claude", ".mcp.json");
+    let existing = {};
+    try {
+        const raw = await readFile(mcpJsonPath, "utf-8");
+        existing = JSON.parse(raw);
+    }
+    catch { /* doesn't exist yet */ }
+    const mcpServers = (existing.mcpServers ?? {});
+    // Don't overwrite if user already configured it
+    if (mcpServers["intentdna"])
+        return;
+    mcpServers["intentdna"] = {
+        command: "dna-mcp",
+        args: ["--project-dir", cwd],
+    };
+    existing.mcpServers = mcpServers;
+    await mkdir(dirname(mcpJsonPath), { recursive: true });
+    await writeFileAsync(mcpJsonPath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
+    process.stderr.write(`MCP: registered dna-mcp server in ${mcpJsonPath}\n`);
+}

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

@@ -12,6 +12,7 @@
 export interface VerifyOptions {
     lockFile: string;
     stats?: boolean;
+    health?: boolean;
 }
 export interface LockFileEntry {
     sha256: string;
@@ -31,3 +32,13 @@ export declare function sha256(content: string): string;
 export declare function parseLockFile(raw: string): LockFile;
 export declare function verifyLock(lock: LockFile): Promise<VerifyResult[]>;
 export declare function runVerify(opts: VerifyOptions): Promise<number>;
+export interface HealthCheckResult {
+    name: string;
+    status: "pass" | "warn" | "fail";
+    detail: string;
+}
+/**
+ * U3: Comprehensive health report for DNA installation.
+ * Checks IR, configs, templates, hooks, and trace system.
+ */
+export declare function runHealth(): Promise<number>;

package/dist/cli/commands/verify.js

@@ -54,6 +54,10 @@ export async function verifyLock(lock) {
 }
 // ── CLI entry ──────────────────────────────────────────────
 export async function runVerify(opts) {
+    // Handle --health mode
+    if (opts.health) {
+        return runHealth();
+    }
     // Handle --stats mode
     if (opts.stats) {
         return runStats();
@@ -214,3 +218,189 @@ function truncate(s, max) {
         return s;
     return s.slice(0, max - 3) + "...";
 }
+/**
+ * U3: Comprehensive health report for DNA installation.
+ * Checks IR, configs, templates, hooks, and trace system.
+ */
+export async function runHealth() {
+    const cwd = process.cwd();
+    const checks = [];
+    const { resolve } = await import("node:path");
+    const { stat, readFile: rf, readdir } = await import("node:fs/promises");
+    // 1. Check compiled IR
+    const irPath = resolve(cwd, ".dna", "compiled", "ir.json");
+    try {
+        const raw = await rf(irPath, "utf-8");
+        const data = JSON.parse(raw);
+        if (data.ir_version && data.ir) {
+            const age = Date.now() - new Date(data.compiled_at ?? data.ir.compiled_at).getTime();
+            const ageHours = Math.round(age / 3600000);
+            checks.push({
+                name: "Compiled IR",
+                status: "pass",
+                detail: `v${data.ir_version}, compiled ${ageHours}h ago, ${data.ir.source_dna_ids?.length ?? 0} template(s)`,
+            });
+        }
+        else if (data.compiled_at) {
+            checks.push({ name: "Compiled IR", status: "warn", detail: "Legacy format — run `dna sync` to upgrade" });
+        }
+        else {
+            checks.push({ name: "Compiled IR", status: "fail", detail: "Unrecognized format" });
+        }
+    }
+    catch {
+        checks.push({ name: "Compiled IR", status: "fail", detail: "Not found — run `dna sync`" });
+    }
+    // 2. Check DNA config files
+    const { autoDetectConfigs } = await import("./sync.js");
+    const configs = await autoDetectConfigs();
+    if (configs.length > 0) {
+        checks.push({ name: "DNA configs", status: "pass", detail: `${configs.length} config(s) found` });
+    }
+    else {
+        checks.push({ name: "DNA configs", status: "fail", detail: "No config files found — run `dna init --template <name>`" });
+    }
+    // 3. Check config validity
+    if (configs.length > 0) {
+        const { loadDNA } = await import("../../compiler/index.js");
+        let valid = 0;
+        let invalid = 0;
+        const errors = [];
+        for (const configPath of configs) {
+            try {
+                await loadDNA(configPath);
+                valid++;
+            }
+            catch (err) {
+                invalid++;
+                const { basename } = await import("node:path");
+                errors.push(`${basename(configPath)}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        if (invalid === 0) {
+            checks.push({ name: "Config validity", status: "pass", detail: `${valid} config(s) valid` });
+        }
+        else {
+            checks.push({ name: "Config validity", status: "fail", detail: errors.join("; ") });
+        }
+    }
+    // 4. Check template versions
+    if (configs.length > 0) {
+        const { checkTemplateVersions: checkVersions } = await import("./sync.js");
+        // Suppress stderr output from checkTemplateVersions — we'll report ourselves
+        const origWrite = process.stderr.write;
+        process.stderr.write = (() => true);
+        try {
+            const upgrades = await checkVersions(configs);
+            if (upgrades.length === 0) {
+                checks.push({ name: "Template versions", status: "pass", detail: "All up to date" });
+            }
+            else {
+                const names = upgrades.map(u => `${u.templateName} (${u.currentVersion} → ${u.availableVersion})`);
+                checks.push({ name: "Template versions", status: "warn", detail: `Upgrade available: ${names.join(", ")}` });
+            }
+        }
+        catch {
+            checks.push({ name: "Template versions", status: "warn", detail: "Could not check versions" });
+        }
+        finally {
+            process.stderr.write = origWrite;
+        }
+    }
+    // 5. Check .claude settings or plugin registration
+    const settingsPath = resolve(cwd, ".claude", "settings.json");
+    try {
+        const raw = await rf(settingsPath, "utf-8");
+        const settings = JSON.parse(raw);
+        const hooks = settings.hooks;
+        const hasHooks = hooks && typeof hooks === "object" && Object.keys(hooks).length > 0;
+        if (hasHooks) {
+            const eventCount = Object.keys(hooks).length;
+            checks.push({ name: "Hook registration", status: "pass", detail: `${eventCount} event(s) in settings.json` });
+        }
+        else {
+            checks.push({ name: "Hook registration", status: "warn", detail: "No hooks in settings.json — using plugin mode?" });
+        }
+    }
+    catch {
+        // Check for plugin registration instead
+        const mcpPath = resolve(cwd, ".claude", ".mcp.json");
+        try {
+            const raw = await rf(mcpPath, "utf-8");
+            const mcp = JSON.parse(raw);
+            if (mcp.mcpServers?.intentdna) {
+                checks.push({ name: "MCP server", status: "pass", detail: "dna-mcp registered in .mcp.json" });
+            }
+            else {
+                checks.push({ name: "Hook registration", status: "warn", detail: "No hooks or MCP server found" });
+            }
+        }
+        catch {
+            checks.push({ name: "Hook registration", status: "warn", detail: "No settings.json or .mcp.json — run `dna setup` or `dna sync`" });
+        }
+    }
+    // 6. Check trace system
+    const traceDir = resolve(cwd, ".dna", "state", "trace");
+    try {
+        const files = await readdir(traceDir);
+        const traceFiles = files.filter(f => f.startsWith("trace-") && f.endsWith(".jsonl"));
+        if (traceFiles.length > 0) {
+            // Read latest trace file size
+            const latest = traceFiles.sort().pop();
+            const latestStat = await stat(resolve(traceDir, latest));
+            const sizeKB = Math.round(latestStat.size / 1024);
+            checks.push({ name: "Trace system", status: "pass", detail: `${traceFiles.length} file(s), latest ${sizeKB}KB` });
+        }
+        else {
+            checks.push({ name: "Trace system", status: "warn", detail: "No trace files — hooks not fired yet" });
+        }
+    }
+    catch {
+        checks.push({ name: "Trace system", status: "warn", detail: "No trace directory — will be created on first hook call" });
+    }
+    // 7. Check lock file drift
+    const lockPath = resolve(cwd, ".dna", "lock");
+    try {
+        const raw = await rf(lockPath, "utf-8");
+        const lock = parseLockFile(raw);
+        const results = await verifyLock(lock);
+        const drifted = results.filter(r => r.status !== "match");
+        if (drifted.length === 0) {
+            checks.push({ name: "Output drift", status: "pass", detail: `${results.length} file(s) match lock` });
+        }
+        else {
+            checks.push({ name: "Output drift", status: "warn", detail: `${drifted.length}/${results.length} file(s) drifted — run \`dna sync\`` });
+        }
+    }
+    catch {
+        checks.push({ name: "Output drift", status: "warn", detail: "No lock file — run `dna sync` to generate" });
+    }
+    // ── Format output ──────────────────────────────────────
+    const ICONS = { pass: "ok", warn: "!!", fail: "XX" };
+    process.stderr.write("\nIntent DNA Health Report\n");
+    process.stderr.write("========================\n\n");
+    let hasFailure = false;
+    let hasWarning = false;
+    for (const check of checks) {
+        const icon = ICONS[check.status];
+        const label = check.name.padEnd(20);
+        process.stderr.write(`  [${icon}] ${label} ${check.detail}\n`);
+        if (check.status === "fail")
+            hasFailure = true;
+        if (check.status === "warn")
+            hasWarning = true;
+    }
+    process.stderr.write("\n");
+    if (hasFailure) {
+        process.stderr.write("Status: issues found — see [XX] items above\n");
+        return 1;
+    }
+    else if (hasWarning) {
+        process.stderr.write("Status: healthy with warnings — see [!!] items above\n");
+        return 0;
+    }
+    else {
+        process.stderr.write("Status: all checks passed\n");
+        return 0;
+    }
+}

package/dist/cli/index.js

@@ -58,6 +58,7 @@ Examples:
   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 verify --health                 Comprehensive health check of DNA installation
   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
@@ -126,6 +127,7 @@ async function main() {
                 options: {
                     lock: { type: "string", default: ".dna/lock" },
                     stats: { type: "boolean", default: false },
+                    health: { type: "boolean", default: false },
                 },
                 allowPositionals: true,
                 strict: false,
@@ -134,6 +136,7 @@ async function main() {
             const code = await runVerify({
                 lockFile: verifyValues.lock,
                 stats: verifyValues.stats,
+                health: verifyValues.health,
             });
             process.exit(code);
             break;

package/dist/compiler/compile.js

@@ -219,6 +219,7 @@ export function compileDNA(activated, cascaded) {
             const wfStepCheckpoints = [];
             const activeRoles = [];
             const handoffChain = [];
+            const stepEnforceRules = [];
             for (const step of wf.steps ?? []) {
                 if (!activeRoles.includes(step.role)) {
                     activeRoles.push(step.role);
@@ -238,6 +239,15 @@ export function compileDNA(activated, cascaded) {
                         consumes: step.handoff.consumes,
                     });
                 }
+                // G4: Collect step enforce rules
+                if (step.enforce) {
+                    stepEnforceRules.push({
+                        step_id: step.id,
+                        read_only: step.enforce.read_only,
+                        relax_after_iteration: step.enforce.relax_after_iteration,
+                        additional_write_paths: step.enforce.additional_write_paths,
+                    });
+                }
             }
             // Derive namespace from workflow key: "ns_wfname" → "ns", "wfname" → ""
             const underscoreIdx = wfKey.indexOf("_");
@@ -248,6 +258,7 @@ export function compileDNA(activated, cascaded) {
                 step_checkpoints: wfStepCheckpoints,
                 active_roles: activeRoles,
                 handoff_chain: handoffChain,
+                step_enforce_rules: stepEnforceRules.length > 0 ? stepEnforceRules : undefined,
             });
         }
     }

package/dist/governance/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Intent DNA — Remote Governance Module
+ *
+ * Architecture reservation for Phase 7 enterprise governance.
+ * Currently exports type definitions only — no runtime implementation.
+ */
+export type { AuditReport, RemoteDNAPolicy, PolicyContent, PolicyScope, PolicyUpdate, GovernanceConfig, GovernanceClient, GovernanceResponse, GovernanceSubscription, } from "./types.js";

package/dist/governance/index.js

@@ -0,0 +1,7 @@
+/**
+ * Intent DNA — Remote Governance Module
+ *
+ * Architecture reservation for Phase 7 enterprise governance.
+ * Currently exports type definitions only — no runtime implementation.
+ */
+export {};

package/dist/governance/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Intent DNA — Remote Governance Types
+ *
+ * Architecture reservation for enterprise governance communication.
+ * Phase 7 implementation — current phase only defines interfaces.
+ *
+ * Capabilities:
+ *   - Audit data reporting to central server
+ *   - Enterprise DNA policy pull
+ *   - Policy update push notifications
+ */
+/** Audit report sent from local DNA to governance server */
+export interface AuditReport {
+    /** Report ID (UUID) */
+    report_id: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Session that generated the report */
+    session_id: string;
+    /** Project identifier */
+    project_id: string;
+    /** Summary statistics */
+    stats: {
+        total_events: number;
+        blocks: number;
+        warns: number;
+        allows: number;
+    };
+    /** Top blocked tools */
+    top_blocked_tools: Array<{
+        tool: string;
+        count: number;
+    }>;
+    /** Top blocked paths */
+    top_blocked_paths: Array<{
+        path: string;
+        count: number;
+    }>;
+    /** Active DNA template IDs */
+    active_templates: string[];
+    /** IR version in use */
+    ir_version: number;
+}
+/** Enterprise DNA policy pulled from governance server */
+export interface RemoteDNAPolicy {
+    /** Policy ID */
+    policy_id: string;
+    /** Policy version (semver) */
+    version: string;
+    /** When the policy was last updated */
+    updated_at: string;
+    /** Priority level (higher overrides lower) */
+    priority: number;
+    /** The DNA content (can be inlined or a URL reference) */
+    dna: PolicyContent;
+    /** Which projects/teams this policy applies to */
+    scope: PolicyScope;
+    /** Whether this policy is mandatory (cannot be overridden locally) */
+    mandatory: boolean;
+}
+/** Policy content — either inline DNA JSON or a reference */
+export interface PolicyContent {
+    /** Inline DNA JSON */
+    inline?: Record<string, unknown>;
+    /** URL to fetch DNA from */
+    url?: string;
+    /** SHA-256 hash for integrity verification */
+    sha256?: string;
+}
+/** Scope of a policy — which projects/teams it applies to */
+export interface PolicyScope {
+    /** Apply to all projects */
+    all?: boolean;
+    /** Apply to specific project IDs */
+    projects?: string[];
+    /** Apply to specific team names */
+    teams?: string[];
+    /** Apply to projects matching glob patterns */
+    project_patterns?: string[];
+}
+/** Policy update push notification */
+export interface PolicyUpdate {
+    /** Update type */
+    type: "created" | "updated" | "revoked";
+    /** The policy that changed */
+    policy: RemoteDNAPolicy;
+    /** Change description */
+    change_description?: string;
+    /** Whether immediate re-sync is required */
+    requires_resync: boolean;
+}
+/** Configuration for connecting to a governance server */
+export interface GovernanceConfig {
+    /** Server URL */
+    server_url: string;
+    /** Authentication token or API key */
+    auth_token?: string;
+    /** Organization ID */
+    org_id: string;
+    /** Polling interval in seconds (for pull mode) */
+    poll_interval_s?: number;
+    /** Enable push notifications via WebSocket */
+    push_enabled?: boolean;
+    /** TLS certificate path (for mTLS) */
+    tls_cert?: string;
+}
+/** Governance client interface — to be implemented in Phase 7 */
+export interface GovernanceClient {
+    /** Report audit data to the governance server */
+    reportAudit(report: AuditReport): Promise<GovernanceResponse>;
+    /** Pull latest policies from the governance server */
+    pullPolicies(): Promise<RemoteDNAPolicy[]>;
+    /** Subscribe to policy updates (push mode) */
+    subscribePolicyUpdates(callback: (update: PolicyUpdate) => void): Promise<GovernanceSubscription>;
+    /** Check connectivity to the governance server */
+    healthCheck(): Promise<boolean>;
+}
+/** Response from governance server operations */
+export interface GovernanceResponse {
+    /** Whether the operation succeeded */
+    ok: boolean;
+    /** Error message if failed */
+    error?: string;
+    /** Server-side request ID for debugging */
+    request_id?: string;
+}
+/** Subscription handle for push updates */
+export interface GovernanceSubscription {
+    /** Unique subscription ID */
+    id: string;
+    /** Unsubscribe from updates */
+    unsubscribe(): Promise<void>;
+    /** Whether the subscription is active */
+    active: boolean;
+}

package/dist/governance/types.js

@@ -0,0 +1,12 @@
+/**
+ * Intent DNA — Remote Governance Types
+ *
+ * Architecture reservation for enterprise governance communication.
+ * Phase 7 implementation — current phase only defines interfaces.
+ *
+ * Capabilities:
+ *   - Audit data reporting to central server
+ *   - Enterprise DNA policy pull
+ *   - Policy update push notifications
+ */
+export {};

package/dist/hooks/cli.js

@@ -101,6 +101,7 @@ async function main() {
                 workflow: wfState.workflow,
                 current_role: wfState.current_role,
                 completed_artifacts: wfState.completed_artifacts,
+                iteration: wfState.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.
@@ -277,7 +278,8 @@ async function loadIR(irPath) {
         // Support both raw IR and wrapped CompiledIRFile format
         if (data.ir_version && data.ir) {
             if (data.ir_version !== EXPECTED_IR_VERSION) {
-                process.stderr.write(`[Intent DNA] IR version mismatch: file has v${data.ir_version}, expected v${EXPECTED_IR_VERSION}. Run \`dna sync\` to recompile.\n`);
+                process.stderr.write(`\n  Intent DNA: IR version mismatch (v${data.ir_version} on disk, v${EXPECTED_IR_VERSION} expected)\n` +
+                    `  Fix: run \`dna sync\` to recompile\n\n`);
             }
             return data.ir;
         }
@@ -285,9 +287,21 @@ async function loadIR(irPath) {
         if (data.compiled_at && data.source_dna_ids) {
             return data;
         }
+        process.stderr.write(`\n  Intent DNA: unrecognized IR format at ${irPath}\n` +
+            `  Fix: run \`dna sync\` to regenerate\n\n`);
         return null;
     }
-    catch {
+    catch (err) {
+        // U3: Human-readable error instead of silent failure
+        const isNotFound = err instanceof Error && "code" in err && err.code === "ENOENT";
+        if (isNotFound) {
+            process.stderr.write(`\n  Intent DNA: no compiled IR found at ${irPath}\n` +
+                `  Fix: run \`dna sync\` to compile your DNA config\n\n`);
+        }
+        else {
+            process.stderr.write(`\n  Intent DNA: failed to load IR — ${err instanceof Error ? err.message : String(err)}\n` +
+                `  Fix: run \`dna sync\` to recompile\n\n`);
+        }
         return null;
     }
 }

package/dist/hooks/enforce.d.ts

@@ -28,6 +28,8 @@ export interface EnforceState {
         workflow: string;
         current_role?: string;
         completed_artifacts?: CompletedArtifactEntry[];
+        /** 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). */