intentdna 1.6.2 → 1.6.3

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.6.2",
+      "version": "1.6.3",
       "author": {
         "name": "Samuel"
       },
@@ -25,5 +25,5 @@
       ]
     }
   ],
-  "version": "1.6.2"
+  "version": "1.6.3"
 }

package/.claude-plugin/plugin.json

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

package/README.md

@@ -185,7 +185,9 @@ dna init --template <name>   # Start from template
 dna sync <file>              # Compile DNA → harness config
 dna import .                 # Import existing config → DNA
 dna verify                   # Check config integrity
-dna evolve <dna-id>          # Generate epigenetic markers from outcomes
+dna feedback --evolve        # Preview marker changes from local classified signals
+dna evolve <dna-id>          # Preview marker changes from persisted outcomes
+dna sync <file> --evolve     # Mutating path: apply evolved markers before sync
 ```
 
 ---
@@ -207,8 +209,12 @@ Read more: [DESIGN.md](DESIGN.md)
 
 - [DESIGN.md](DESIGN.md) — long-term architecture and design
 - [ROADMAP.md](ROADMAP.md) — current stage, next plan, deferred work
+- [docs/README.md](docs/README.md) — Repo-Wiki root and reading paths
+- [spec/README.md](spec/README.md) — engineering spec index and status map
 - [spec/schema-spec.md](spec/schema-spec.md) — schema contract
 - [docs/references/](docs/references/) — distilled research and implementation references
+- [docs/workflows/](docs/workflows/) — operational runbooks
+- [docs/troubleshooting/](docs/troubleshooting/) — troubleshooting entry points
 - [docs/insights/](docs/insights/) — strategic and product-thinking documents
 
 ---

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

@@ -1,11 +1,14 @@
 /**
- * dna evolve <dna-id> [--preview] [--store-dir <path>]
+ * dna evolve <dna-id> [--preview] [--apply] [--store-dir <path>]
  *
- * Generate/update epigenetic markers from accumulated outcomes.
+ * Preview epigenetic marker changes from accumulated persisted outcomes.
+ * Applying markers from this command is intentionally not implemented in the
+ * local kernel; `dna sync --evolve` remains the explicit mutating sync path.
  */
 export interface EvolveOptions {
     dnaId: string;
-    preview: boolean;
+    preview?: boolean;
+    apply?: boolean;
     storeDir?: string;
 }
 export declare function runEvolve(opts: EvolveOptions): Promise<number>;

package/dist/cli/commands/evolve.js

@@ -1,47 +1,93 @@
 /**
- * dna evolve <dna-id> [--preview] [--store-dir <path>]
+ * dna evolve <dna-id> [--preview] [--apply] [--store-dir <path>]
  *
- * Generate/update epigenetic markers from accumulated outcomes.
+ * Preview epigenetic marker changes from accumulated persisted outcomes.
+ * Applying markers from this command is intentionally not implemented in the
+ * local kernel; `dna sync --evolve` remains the explicit mutating sync path.
  */
-import { EvolutionEngine } from "../../evolution/index.js";
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { safePathComponent } from "../../hooks/state.js";
+import { describeMarkerChanges } from "../../evolution/marker-gen.js";
+import { DEFAULT_EVOLUTION_CONFIG } from "../../evolution/types.js";
 import { bold, green, yellow, dim, cyan } from "../util/format.js";
+async function readOutcomesReadOnly(storeDir, dnaId) {
+    const safeDnaId = safePathComponent(dnaId, "dna_id");
+    const dir = join(storeDir, "outcomes", safeDnaId);
+    let files;
+    try {
+        files = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const outcomes = [];
+    for (const file of files) {
+        if (!file.endsWith(".json"))
+            continue;
+        try {
+            const raw = await readFile(join(dir, file), "utf-8");
+            outcomes.push(JSON.parse(raw));
+        }
+        catch {
+            // Skip corrupt outcome files in preview.
+        }
+    }
+    return outcomes.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+}
+async function readMarkersReadOnly(storeDir, dnaId) {
+    const safeDnaId = safePathComponent(dnaId, "dna_id");
+    try {
+        const raw = await readFile(join(storeDir, "markers", `${safeDnaId}.json`), "utf-8");
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+function printChanges(changes) {
+    process.stderr.write(bold("Marker changes preview:") + "\n\n");
+    for (const change of changes) {
+        switch (change.type) {
+            case "create":
+                process.stderr.write(`  ${green("+ CREATE")} ${cyan(change.gene)} → ${change.action} ×${change.factor.toFixed(2)} (${change.feedback_count} feedbacks)\n`);
+                break;
+            case "update":
+                process.stderr.write(`  ${yellow("~ UPDATE")} ${cyan(change.gene)} → ${change.action} ×${change.factor.toFixed(2)} (${change.feedback_count} feedbacks)\n`);
+                break;
+            case "neutral":
+                process.stderr.write(`  ${dim("= NEUTRAL")} ${cyan(change.gene)} ×${change.factor.toFixed(2)} (${change.feedback_count} feedbacks)\n`);
+                break;
+            case "insufficient_data":
+                process.stderr.write(`  ${dim("? INSUFFICIENT")} ${cyan(change.gene)} (${change.feedback_count}/${change.needed} feedbacks needed)\n`);
+                break;
+        }
+    }
+}
 export async function runEvolve(opts) {
     if (!opts.dnaId) {
         process.stderr.write("Error: dna-id is required\n");
         return 2;
     }
+    if (opts.apply) {
+        process.stderr.write("Error: `dna evolve --apply` is not implemented in this kernel slice. " +
+            "`dna evolve` is preview-only; `dna sync --evolve` is the explicit mutating sync path.\n");
+        return 2;
+    }
     try {
-        const engine = new EvolutionEngine(opts.storeDir ? { store_dir: opts.storeDir } : undefined);
-        if (opts.preview) {
-            const changes = await engine.preview(opts.dnaId);
-            if (changes.length === 0) {
-                process.stderr.write("No marker changes to generate (no outcomes recorded)\n");
-                return 0;
-            }
-            process.stderr.write(bold("Marker changes preview:") + "\n\n");
-            for (const change of changes) {
-                switch (change.type) {
-                    case "create":
-                        process.stderr.write(`  ${green("+ CREATE")} ${cyan(change.gene)} → ${change.action} ×${change.factor.toFixed(2)} (${change.feedback_count} feedbacks)\n`);
-                        break;
-                    case "update":
-                        process.stderr.write(`  ${yellow("~ UPDATE")} ${cyan(change.gene)} → ${change.action} ×${change.factor.toFixed(2)} (${change.feedback_count} feedbacks)\n`);
-                        break;
-                    case "neutral":
-                        process.stderr.write(`  ${dim("= NEUTRAL")} ${cyan(change.gene)} ×${change.factor.toFixed(2)} (${change.feedback_count} feedbacks)\n`);
-                        break;
-                    case "insufficient_data":
-                        process.stderr.write(`  ${dim("? INSUFFICIENT")} ${cyan(change.gene)} (${change.feedback_count}/${change.needed} feedbacks needed)\n`);
-                        break;
-                }
-            }
+        const safeDnaId = safePathComponent(opts.dnaId, "dna_id");
+        const storeDir = opts.storeDir ?? DEFAULT_EVOLUTION_CONFIG.store_dir;
+        const outcomes = await readOutcomesReadOnly(storeDir, safeDnaId);
+        const existingMarkers = await readMarkersReadOnly(storeDir, safeDnaId);
+        const changes = describeMarkerChanges(outcomes, existingMarkers);
+        if (changes.length === 0) {
+            process.stderr.write("No marker changes to generate (no outcomes recorded)\n");
+            process.stderr.write("Preview only: no outcomes or markers were persisted.\n");
             return 0;
         }
-        // Actually evolve
-        const markers = await engine.evolve(opts.dnaId);
-        process.stderr.write(`Evolved ${opts.dnaId}: ${markers.length} active markers\n`);
-        // Output markers as JSON
-        process.stdout.write(JSON.stringify(markers, null, 2) + "\n");
+        printChanges(changes);
+        process.stderr.write("\nPreview only: no outcomes or markers were persisted.\n");
         return 0;
     }
     catch (err) {

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

@@ -1,38 +1,13 @@
 /**
  * dna feedback [--days <N>] [--json] [--evolve]
  *
- * Analyze trace/audit data and produce actionable feedback for template optimization.
- * With --evolve: convert trace data into epigenetic markers (preview by default).
- *
- * Reads: .dna/state/trace/trace-*.jsonl
- * Outputs: human-readable report (or JSON with --json)
+ * Build a local kernel observability report from traces and verifier results.
+ * With --evolve: include a preview-only marker diff derived from local signals.
  */
 export interface FeedbackOptions {
     days: number;
     json: boolean;
     evolve: boolean;
-}
-export interface FeedbackReport {
-    period_days: number;
-    total_events: number;
-    blocks: number;
-    warns: number;
-    allows: number;
-    verifier_results: number;
-    verifier_passes: number;
-    verifier_failures: number;
-    top_blocked_tools: Array<{
-        tool: string;
-        count: number;
-    }>;
-    top_blocked_paths: Array<{
-        path: string;
-        count: number;
-    }>;
-    top_block_reasons: Array<{
-        reason: string;
-        count: number;
-    }>;
-    suggestions: string[];
+    dnaId?: string;
 }
 export declare function runFeedback(opts: FeedbackOptions): Promise<number>;

package/dist/cli/commands/feedback.js

@@ -1,196 +1,27 @@
 /**
  * dna feedback [--days <N>] [--json] [--evolve]
  *
- * Analyze trace/audit data and produce actionable feedback for template optimization.
- * With --evolve: convert trace data into epigenetic markers (preview by default).
- *
- * Reads: .dna/state/trace/trace-*.jsonl
- * Outputs: human-readable report (or JSON with --json)
+ * Build a local kernel observability report from traces and verifier results.
+ * With --evolve: include a preview-only marker diff derived from local signals.
  */
-import { readTraces, readVerifierResults } from "../../hooks/state.js";
-import { mergeOutcomes, summarizeConversion } from "../../evolution/trace-bridge.js";
-import { describeMarkerChanges } from "../../evolution/marker-gen.js";
-import { EvolutionStore } from "../../evolution/store.js";
-function aggregate(traces) {
-    let blocks = 0, warns = 0, allows = 0;
-    const toolCounts = new Map();
-    const pathCounts = new Map();
-    const reasonCounts = new Map();
-    for (const t of traces) {
-        if (t.decision === "block") {
-            blocks++;
-            if (t.tool_name)
-                toolCounts.set(t.tool_name, (toolCounts.get(t.tool_name) ?? 0) + 1);
-            if (t.target_path)
-                pathCounts.set(t.target_path, (pathCounts.get(t.target_path) ?? 0) + 1);
-            if (t.reason) {
-                // Normalize reason to first line
-                const shortReason = t.reason.split("\n")[0].replace(/^\[Intent DNA\]\s*/, "").slice(0, 100);
-                reasonCounts.set(shortReason, (reasonCounts.get(shortReason) ?? 0) + 1);
-            }
-        }
-        else if (t.decision === "warn") {
-            warns++;
-        }
-        else {
-            allows++;
-        }
-    }
-    const sorted = (map, limit, key) => [...map.entries()]
-        .sort((a, b) => b[1] - a[1])
-        .slice(0, limit)
-        .map(([k, count]) => ({ [key]: k, count }));
-    return {
-        total_events: traces.length,
-        blocks,
-        warns,
-        allows,
-        top_blocked_tools: sorted(toolCounts, 5, "tool"),
-        top_blocked_paths: sorted(pathCounts, 5, "path"),
-        top_block_reasons: sorted(reasonCounts, 5, "reason"),
-    };
-}
-function generateSuggestions(report, verifierResults = 0) {
-    const suggestions = [];
-    if (report.blocks === 0 && report.warns === 0) {
-        if (verifierResults > 0) {
-            suggestions.push("No trace blocks or warnings in this window. Verifier activity is present, so review verifier pass/fail results alongside trace data.");
-        }
-        else {
-            suggestions.push("No blocks or warnings — DNA constraints are not firing. Consider tightening rules or verifying hooks are active.");
-        }
-        return suggestions;
-    }
-    const blockRate = report.total_events > 0 ? report.blocks / report.total_events : 0;
-    if (blockRate > 0.3) {
-        suggestions.push(`High block rate (${(blockRate * 100).toFixed(0)}%). Review if DNA rules are too restrictive — this may slow development.`);
-    }
-    // Tool-specific suggestions
-    for (const t of report.top_blocked_tools) {
-        if (t.count >= 5) {
-            suggestions.push(`Tool '${t.tool}' blocked ${t.count} times. Consider expanding permissions if this is expected usage.`);
-        }
-    }
-    // Path-specific suggestions
-    for (const p of report.top_blocked_paths) {
-        if (p.count >= 3) {
-            suggestions.push(`Path '${p.path}' blocked ${p.count} times. Consider adding to write scope if agents need access.`);
-        }
-    }
-    // Repeated reason patterns
-    for (const r of report.top_block_reasons) {
-        if (r.count >= 3) {
-            suggestions.push(`Repeated block: "${r.reason}" (${r.count}x). May indicate a rule-scope mismatch.`);
-        }
-    }
-    if (suggestions.length === 0) {
-        suggestions.push("Constraints are working within normal parameters. No action needed.");
-    }
-    return suggestions;
-}
-function formatReport(report) {
-    const lines = [];
-    lines.push(`DNA Feedback Report (last ${report.period_days} day${report.period_days > 1 ? "s" : ""})`);
-    lines.push("=".repeat(50));
-    lines.push("");
-    lines.push(`Total events: ${report.total_events}`);
-    lines.push(`  Allowed: ${report.allows}`);
-    lines.push(`  Blocked: ${report.blocks}`);
-    lines.push(`  Warned:  ${report.warns}`);
-    lines.push("");
-    if (report.verifier_results > 0) {
-        lines.push(`Verifier results: ${report.verifier_results}`);
-        lines.push(`  Passed: ${report.verifier_passes}`);
-        lines.push(`  Failed: ${report.verifier_failures}`);
-        lines.push("");
-    }
-    if (report.top_blocked_tools.length > 0) {
-        lines.push("Top blocked tools:");
-        for (const t of report.top_blocked_tools) {
-            lines.push(`  ${t.tool}: ${t.count}`);
-        }
-        lines.push("");
-    }
-    if (report.top_blocked_paths.length > 0) {
-        lines.push("Top blocked paths:");
-        for (const p of report.top_blocked_paths) {
-            lines.push(`  ${p.path}: ${p.count}`);
-        }
-        lines.push("");
-    }
-    if (report.top_block_reasons.length > 0) {
-        lines.push("Top block reasons:");
-        for (const r of report.top_block_reasons) {
-            lines.push(`  "${r.reason}": ${r.count}`);
-        }
-        lines.push("");
-    }
-    if (report.suggestions.length > 0) {
-        lines.push("Suggestions:");
-        for (const s of report.suggestions) {
-            lines.push(`  - ${s}`);
-        }
-        lines.push("");
-    }
-    return lines.join("\n");
-}
+import { buildKernelReport, formatKernelReport } from "../../report/kernel-report.js";
 export async function runFeedback(opts) {
-    const projectDir = process.cwd();
-    const traces = await readTraces(projectDir, opts.days);
-    const cutoff = new Date();
-    cutoff.setDate(cutoff.getDate() - opts.days);
-    const verifierResults = (await readVerifierResults(projectDir)).filter((result) => {
-        const timestamp = Date.parse(result.timestamp);
-        return Number.isNaN(timestamp) || timestamp >= cutoff.getTime();
+    const report = await buildKernelReport({
+        projectDir: process.cwd(),
+        days: opts.days,
+        includeMarkerPreview: opts.evolve,
+        dnaId: opts.dnaId,
     });
-    if (traces.length === 0 && verifierResults.length === 0) {
+    if (report.summary.traces === 0 && report.summary.verifier_results === 0) {
         process.stderr.write(`No trace or verifier data found for the last ${opts.days} day(s).\n`);
         process.stderr.write("Signals are generated by dna-hook during Claude Code sessions.\n");
         return 0;
     }
-    const stats = aggregate(traces);
-    const verifierStats = {
-        verifier_results: verifierResults.length,
-        verifier_passes: verifierResults.filter((result) => result.status === "pass").length,
-        verifier_failures: verifierResults.filter((result) => result.status === "fail").length,
-    };
-    const suggestions = generateSuggestions(stats, verifierStats.verifier_results);
-    const report = { ...stats, ...verifierStats, period_days: opts.days, suggestions };
-    if (opts.json && !opts.evolve) {
+    if (opts.json) {
         process.stdout.write(JSON.stringify(report, null, 2) + "\n");
     }
-    else if (!opts.evolve) {
-        process.stderr.write(formatReport(report));
-    }
-    // --evolve: convert normalized local signals → epigenetic markers
-    if (opts.evolve) {
-        const outcomes = mergeOutcomes(traces, verifierResults);
-        if (outcomes.length === 0) {
-            process.stderr.write(formatReport(report));
-            process.stderr.write("\nNo actionable gene feedback found in traces — nothing to evolve.\n");
-            return 0;
-        }
-        const store = new EvolutionStore();
-        const existingMarkers = await store.loadMarkers("default");
-        const changes = describeMarkerChanges(outcomes, existingMarkers);
-        process.stderr.write(formatReport(report));
-        process.stderr.write("\n" + summarizeConversion(outcomes) + "\n\n");
-        process.stderr.write("Marker changes (preview):\n");
-        for (const c of changes) {
-            if (c.type === "create") {
-                process.stderr.write(`  + CREATE ${c.gene} → ${c.action} x${c.factor.toFixed(2)} (${c.feedback_count} feedbacks)\n`);
-            }
-            else if (c.type === "update") {
-                process.stderr.write(`  ~ UPDATE ${c.gene} → ${c.action} x${c.factor.toFixed(2)} (${c.feedback_count} feedbacks)\n`);
-            }
-            else if (c.type === "neutral") {
-                process.stderr.write(`  = NEUTRAL ${c.gene} x${c.factor.toFixed(2)} (${c.feedback_count} feedbacks)\n`);
-            }
-            else {
-                process.stderr.write(`  ? INSUFFICIENT ${c.gene} (${c.feedback_count}/${c.needed} needed)\n`);
-            }
-        }
-        process.stderr.write("\nRun `dna evolve --apply` to persist markers.\n");
+    else {
+        process.stderr.write(formatKernelReport(report));
     }
     return 0;
 }

package/dist/cli/index.js

@@ -27,9 +27,9 @@ Commands:
   compile       Compile DNA files to framework configuration
   validate      Validate DNA files for correctness
   show          Show gene expression state
-  evolve        Generate epigenetic markers from outcomes
+  evolve        Preview epigenetic marker changes from persisted outcomes
   epigenetic    Record outcomes, view markers and summaries
-  feedback      Analyze trace data, suggest template optimizations (--days <N>, --json, --evolve)
+  feedback      Build local kernel report (--days <N>, --json, --evolve preview, --dna-id <id>)
   templates     Template management (deploy to global install)
 
 Options:
@@ -54,7 +54,7 @@ Examples:
   dna sync my.dna.json --agents .claude/agents
   dna sync my.dna.json --workflow ./scripts
   dna sync my.dna.json --target claude-md --inject CLAUDE.md --hooks .claude/hooks --agents .claude/agents --workflow ./scripts
-  dna sync my.dna.json --target soul-md --inject SOUL.md --evolve
+  dna sync my.dna.json --target soul-md --inject SOUL.md --evolve  # mutates markers before sync
   dna sync --remove --inject CLAUDE.md --hooks .claude/hooks --agents .claude/agents
   dna verify                          Verify synced files against .dna/lock
   dna verify --lock /path/to/.dna/lock
@@ -65,7 +65,8 @@ Examples:
   dna run --dna my.dna.json --workflow dev-pipeline --task P5.8 --dry-run
   dna compile my.dna.json --context work
   dna show my.dna.json --context work
-  dna evolve my_dna_id --preview
+  dna evolve my_dna_id                  Preview marker changes without persisting
+  dna evolve my_dna_id --apply           Unsupported in this kernel; use sync --evolve for explicit mutation
 `;
 async function main() {
     const args = process.argv.slice(2);
@@ -317,6 +318,7 @@ async function main() {
                 args: rest,
                 options: {
                     preview: { type: "boolean", default: false },
+                    apply: { type: "boolean", default: false },
                     "store-dir": { type: "string" },
                 },
                 allowPositionals: true,
@@ -326,6 +328,7 @@ async function main() {
             const code = await runEvolve({
                 dnaId: positionals[0] ?? "",
                 preview: values.preview,
+                apply: values.apply,
                 storeDir: values["store-dir"],
             });
             process.exit(code);
@@ -417,6 +420,7 @@ async function main() {
                     days: { type: "string", short: "d", default: "7" },
                     json: { type: "boolean", default: false },
                     evolve: { type: "boolean", default: false },
+                    "dna-id": { type: "string" },
                 },
                 strict: false,
             });
@@ -425,6 +429,7 @@ async function main() {
                 days: parseInt(fbValues.days, 10) || 7,
                 json: fbValues.json,
                 evolve: fbValues.evolve,
+                dnaId: fbValues["dna-id"],
             });
             process.exit(code);
             break;

package/dist/hooks/cli.d.ts

@@ -15,7 +15,7 @@
  * Fail-open: all errors → { continue: true, suppressOutput: true }
  */
 import type { ArtifactFact, ConstraintIR, VerifierSpec } from "../schema/types.js";
-import type { HookOutput } from "./protocol.js";
+import type { HookEvent, HookOutput } from "./protocol.js";
 import { blockOutput } from "./protocol.js";
 import { readWorkflowState } from "./state.js";
 import type { VerifierResultEntry } from "./state.js";
@@ -51,8 +51,34 @@ declare function resolveWorkflowArtifactFacts(projectDir: string, ir: Constraint
     inputs?: Record<string, string>;
     resolved_variables?: Record<string, string>;
 }, sessionId?: string): Promise<ArtifactFact[]>;
+type HookArtifactResult = {
+    facts: ArtifactFact[];
+} | {
+    output: HookOutput;
+};
+type HookWorkflowStateResult = {
+    state: Awaited<ReturnType<typeof readWorkflowState>>;
+} | {
+    output: HookOutput;
+};
+declare function readWorkflowStateForHook(projectDir: string, event: HookEvent, sessionId?: string): Promise<HookWorkflowStateResult>;
+declare function resolveWorkflowArtifactFactsForHook(projectDir: string, ir: ConstraintIR, wfState: {
+    workflow: string;
+    current_step: string;
+    inputs?: Record<string, string>;
+    resolved_variables?: Record<string, string>;
+}, event: HookEvent, sessionId?: string): Promise<HookArtifactResult>;
+declare function finalizeAndResolveArtifactsForHook(projectDir: string, ir: ConstraintIR, wfState: {
+    workflow: string;
+    current_step: string;
+    inputs?: Record<string, string>;
+    resolved_variables?: Record<string, string>;
+}, event: HookEvent, sessionId?: string): Promise<HookArtifactResult>;
 export declare const recordProducedArtifactsForTest: typeof recordProducedArtifacts;
 export declare const resolveWorkflowArtifactFactsForTest: typeof resolveWorkflowArtifactFacts;
+export declare const readWorkflowStateForHookTest: typeof readWorkflowStateForHook;
+export declare const resolveWorkflowArtifactFactsForHookTest: typeof resolveWorkflowArtifactFactsForHook;
+export declare const finalizeAndResolveArtifactsForHookTest: typeof finalizeAndResolveArtifactsForHook;
 export declare function appendStopVerifierWarnings(output: HookOutput, verifierResults: VerifierResultEntry[], currentStep?: string): HookOutput;
 export declare function runVerifiersForTest(projectDir: string, ir: ConstraintIR, workflowState: {
     workflow: string;

package/dist/hooks/cli.js

@@ -107,7 +107,12 @@ async function main() {
     let wfStateRaw = null;
     // Load workflow state for events that need it (handoff context + PreCompact preservation)
     if (event === "PreToolUse" || event === "PostToolUse" || event === "PreCompact") {
-        wfStateRaw = await readWorkflowState(projectDir, sessionId);
+        const workflowState = await readWorkflowStateForHook(projectDir, event, sessionId);
+        if ("output" in workflowState) {
+            writeOutput(workflowState.output);
+            return;
+        }
+        wfStateRaw = workflowState.state;
         if (wfStateRaw && wfStateRaw.active) {
             state.workflowState = {
                 current_step: wfStateRaw.current_step,
@@ -116,7 +121,13 @@ async function main() {
                 completed_artifacts: wfStateRaw.completed_artifacts,
                 iteration: wfStateRaw.iteration, // G4: pass iteration for state-driven rules
             };
-            state.artifactFacts = await resolveWorkflowArtifactFacts(projectDir, ir, wfStateRaw, sessionId);
+            const artifactFacts = await resolveWorkflowArtifactFactsForHook(projectDir, ir, wfStateRaw, event, sessionId);
+            if ("output" in artifactFacts) {
+                writeOutput(artifactFacts.output);
+                appendArtifactResolverTrace(projectDir, event, wfStateRaw, artifactFacts.output, sessionId);
+                return;
+            }
+            state.artifactFacts = artifactFacts.facts;
         }
     }
     if (event === "PreToolUse" && wfStateRaw?.active) {
@@ -148,7 +159,22 @@ async function main() {
     }
     // Special handling for Stop — needs async workflow state read + session summary
     if (event === "Stop") {
-        const wfState = await readWorkflowState(projectDir, sessionId);
+        const workflowState = await readWorkflowStateForHook(projectDir, event, sessionId);
+        if ("output" in workflowState) {
+            writeOutput(workflowState.output);
+            return;
+        }
+        const wfState = workflowState.state;
+        let stopArtifactFacts = [];
+        if (wfState?.active) {
+            const artifactFacts = await finalizeAndResolveArtifactsForHook(projectDir, ir, wfState, event, sessionId);
+            if ("output" in artifactFacts) {
+                writeOutput(artifactFacts.output);
+                appendArtifactResolverTrace(projectDir, event, wfState, artifactFacts.output, sessionId);
+                return;
+            }
+            stopArtifactFacts = artifactFacts.facts;
+        }
         const stopContext = wfState ? {
             active: wfState.active,
             workflow: wfState.workflow,
@@ -156,7 +182,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) : [],
+            artifact_facts: stopArtifactFacts,
         } : null;
         const verifierResults = stopContext?.active
             ? await runStopVerifiersForTest(projectDir, ir, stopContext, sessionId)
@@ -548,8 +574,51 @@ async function finalizeAndResolveArtifacts(projectDir, ir, wfState, sessionId) {
     await recordProducedArtifacts(projectDir, ir, wfState, sessionId);
     return resolveWorkflowArtifactFacts(projectDir, ir, wfState, sessionId);
 }
+function artifactResolverErrorOutput(event, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return blockOutput(`[Intent DNA] ${event} artifact resolver failed: ${detail}`);
+}
+async function readWorkflowStateForHook(projectDir, event, sessionId) {
+    try {
+        return { state: await readWorkflowState(projectDir, sessionId) };
+    }
+    catch (error) {
+        return { output: artifactResolverErrorOutput(event, error) };
+    }
+}
+async function resolveWorkflowArtifactFactsForHook(projectDir, ir, wfState, event, sessionId) {
+    try {
+        return { facts: await resolveWorkflowArtifactFacts(projectDir, ir, wfState, sessionId) };
+    }
+    catch (error) {
+        return { output: artifactResolverErrorOutput(event, error) };
+    }
+}
+async function finalizeAndResolveArtifactsForHook(projectDir, ir, wfState, event, sessionId) {
+    try {
+        return { facts: await finalizeAndResolveArtifacts(projectDir, ir, wfState, sessionId) };
+    }
+    catch (error) {
+        return { output: artifactResolverErrorOutput(event, error) };
+    }
+}
+function appendArtifactResolverTrace(projectDir, event, wfState, output, sessionId) {
+    appendTrace(projectDir, {
+        trace_id: randomUUID(),
+        event,
+        workflow: wfState.workflow,
+        step: wfState.current_step,
+        decision: "block",
+        reason: output.reason,
+        duration_ms: 0,
+        timestamp: new Date().toISOString(),
+    }, sessionId).catch(() => { });
+}
 export const recordProducedArtifactsForTest = recordProducedArtifacts;
 export const resolveWorkflowArtifactFactsForTest = resolveWorkflowArtifactFacts;
+export const readWorkflowStateForHookTest = readWorkflowStateForHook;
+export const resolveWorkflowArtifactFactsForHookTest = resolveWorkflowArtifactFactsForHook;
+export const finalizeAndResolveArtifactsForHookTest = finalizeAndResolveArtifactsForHook;
 function clearBlockingVerifierCheckpoints(ir, workflowState) {
     if (!workflowState || !ir.verifier_specs || ir.verifier_specs.length === 0)
         return ir;