intentdna 1.4.7 → 1.4.9

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

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

@@ -1,7 +1,8 @@
 /**
- * dna feedback [--days <N>] [--json]
+ * 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)
@@ -9,6 +10,7 @@
 export interface FeedbackOptions {
     days: number;
     json: boolean;
+    evolve: boolean;
 }
 export interface FeedbackReport {
     period_days: number;

package/dist/cli/commands/feedback.js

@@ -1,12 +1,16 @@
 /**
- * dna feedback [--days <N>] [--json]
+ * 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)
  */
 import { readTraces } from "../../hooks/state.js";
+import { traceToOutcomes, 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();
@@ -130,11 +134,41 @@ export async function runFeedback(opts) {
     const stats = aggregate(traces);
     const suggestions = generateSuggestions(stats);
     const report = { ...stats, period_days: opts.days, suggestions };
-    if (opts.json) {
+    if (opts.json && !opts.evolve) {
         process.stdout.write(JSON.stringify(report, null, 2) + "\n");
     }
-    else {
+    else if (!opts.evolve) {
         process.stderr.write(formatReport(report));
     }
+    // --evolve: convert traces → epigenetic markers
+    if (opts.evolve) {
+        const outcomes = traceToOutcomes(traces);
+        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");
+    }
     return 0;
 }

package/dist/cli/index.js

@@ -29,7 +29,7 @@ Commands:
   show          Show gene expression state
   evolve        Generate epigenetic markers from outcomes
   epigenetic    Record outcomes, view markers and summaries
-  feedback      Analyze trace data, suggest template optimizations (--days <N>, --json)
+  feedback      Analyze trace data, suggest template optimizations (--days <N>, --json, --evolve)
 
 Options:
   --help, -h    Show help for a command
@@ -412,6 +412,7 @@ async function main() {
                 options: {
                     days: { type: "string", short: "d", default: "7" },
                     json: { type: "boolean", default: false },
+                    evolve: { type: "boolean", default: false },
                 },
                 strict: false,
             });
@@ -419,6 +420,7 @@ async function main() {
             const code = await runFeedback({
                 days: parseInt(fbValues.days, 10) || 7,
                 json: fbValues.json,
+                evolve: fbValues.evolve,
             });
             process.exit(code);
             break;

package/dist/evolution/trace-bridge.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Intent DNA — Trace-to-Evolution Bridge
+ *
+ * Converts hook trace data into ExecutionOutcomes that the epigenetic
+ * marker generator can process. This closes the feedback loop:
+ *   traces (observed behavior) → outcomes → markers → gene modulation
+ *
+ * Gene extraction from trace reasons:
+ *   - Tool filters: "(gene: <name>)" in reason
+ *   - Role scope: "Role '<name>'" → gene "scope:<role>"
+ *   - Gates: "(gene: <name>)" pattern or fallback to "gate"
+ */
+import type { TraceEntry } from "../hooks/state.js";
+import type { ExecutionOutcome } from "./types.js";
+/**
+ * Extract the gene name from a trace entry's reason string.
+ * Returns null if no gene can be determined.
+ */
+export declare function extractGeneFromReason(reason: string | undefined): string | null;
+/**
+ * Convert trace entries into ExecutionOutcomes for the evolution engine.
+ *
+ * Groups block/warn traces by gene, creates one outcome per unique
+ * (gene, decision) pair. Allow decisions are not converted since
+ * they don't carry gene information.
+ */
+export declare function traceToOutcomes(traces: TraceEntry[], dnaId?: string): ExecutionOutcome[];
+/**
+ * Summarize trace-to-outcome conversion for human review.
+ */
+export declare function summarizeConversion(outcomes: ExecutionOutcome[]): string;

package/dist/evolution/trace-bridge.js

@@ -0,0 +1,99 @@
+/**
+ * Intent DNA — Trace-to-Evolution Bridge
+ *
+ * Converts hook trace data into ExecutionOutcomes that the epigenetic
+ * marker generator can process. This closes the feedback loop:
+ *   traces (observed behavior) → outcomes → markers → gene modulation
+ *
+ * Gene extraction from trace reasons:
+ *   - Tool filters: "(gene: <name>)" in reason
+ *   - Role scope: "Role '<name>'" → gene "scope:<role>"
+ *   - Gates: "(gene: <name>)" pattern or fallback to "gate"
+ */
+import { randomUUID } from "node:crypto";
+/**
+ * Extract the gene name from a trace entry's reason string.
+ * Returns null if no gene can be determined.
+ */
+export function extractGeneFromReason(reason) {
+    if (!reason)
+        return null;
+    // Pattern: (gene: <name>) — from tool filters and gates
+    const geneMatch = reason.match(/\(gene:\s*(\w+)\)/);
+    if (geneMatch)
+        return geneMatch[1];
+    // Pattern: Role '<name>' — from scope enforcement
+    const roleMatch = reason.match(/Role '(\w+)'/);
+    if (roleMatch)
+        return `scope:${roleMatch[1]}`;
+    // Pattern: source_gene in gate messages
+    const sourceMatch = reason.match(/source_gene:\s*(\w+)/);
+    if (sourceMatch)
+        return sourceMatch[1];
+    return null;
+}
+/**
+ * Convert trace entries into ExecutionOutcomes for the evolution engine.
+ *
+ * Groups block/warn traces by gene, creates one outcome per unique
+ * (gene, decision) pair. Allow decisions are not converted since
+ * they don't carry gene information.
+ */
+export function traceToOutcomes(traces, dnaId = "default") {
+    // Collect feedback per gene from block/warn traces
+    const geneFeedback = new Map();
+    for (const trace of traces) {
+        if (trace.decision === "allow")
+            continue;
+        const gene = extractGeneFromReason(trace.reason);
+        if (!gene)
+            continue;
+        const existing = geneFeedback.get(gene) ?? { hindered: 0, details: [] };
+        existing.hindered++;
+        if (trace.reason && existing.details.length < 3) {
+            const short = trace.reason.split("\n")[0].slice(0, 80);
+            existing.details.push(short);
+        }
+        geneFeedback.set(gene, existing);
+    }
+    // Convert to ExecutionOutcomes
+    const outcomes = [];
+    const totalEvents = traces.length;
+    const timestamp = new Date().toISOString();
+    for (const [gene, stats] of geneFeedback) {
+        const feedback = [];
+        // Each block counts as a "hindered" feedback
+        for (let i = 0; i < stats.hindered; i++) {
+            feedback.push({
+                gene,
+                effect: "hindered",
+                detail: stats.details[i] ?? `blocked ${stats.hindered} times`,
+            });
+        }
+        outcomes.push({
+            id: `trace_${randomUUID().slice(0, 8)}`,
+            timestamp,
+            dna_id: dnaId,
+            action: `enforcement: ${gene} blocked ${stats.hindered}/${totalEvents} events`,
+            active_genes: [gene],
+            constraints_applied: [gene],
+            success: false, // Blocks indicate friction
+            constraint_feedback: feedback,
+        });
+    }
+    return outcomes;
+}
+/**
+ * Summarize trace-to-outcome conversion for human review.
+ */
+export function summarizeConversion(outcomes) {
+    if (outcomes.length === 0)
+        return "No actionable gene feedback found in traces.";
+    const lines = ["Trace → Epigenetic conversion:"];
+    for (const o of outcomes) {
+        const gene = o.active_genes[0];
+        const count = o.constraint_feedback.length;
+        lines.push(`  ${gene}: ${count} block${count > 1 ? "s" : ""} → will suppress`);
+    }
+    return lines.join("\n");
+}

package/dist/hooks/cli.js

@@ -18,7 +18,7 @@ import { readFile, stat } from "node:fs/promises";
 import { resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { readStdin, writeOutput, silentOutput, allowOutput } from "./protocol.js";
-import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, } from "./enforce.js";
+import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, extractBashWritePaths, } from "./enforce.js";
 import { appendAudit, readWorkflowState, appendTrace, rotateTraces, readTraces } from "./state.js";
 // ── Constants ──────────────────────────────────────────────
 const DEFAULT_IR_PATH = ".dna/compiled/ir.json";
@@ -92,18 +92,21 @@ async function main() {
         return;
     }
     const state = {};
-    // Load workflow state for events that need handoff context
-    if (event === "PreToolUse") {
+    // Load workflow state for events that need it (handoff context + PreCompact preservation)
+    if (event === "PreToolUse" || event === "PreCompact") {
         const wfState = await readWorkflowState(projectDir, sessionId);
         if (wfState && wfState.active) {
             state.workflowState = {
                 current_step: wfState.current_step,
                 workflow: wfState.workflow,
+                current_role: wfState.current_role,
                 completed_artifacts: wfState.completed_artifacts,
             };
             // Re-run fallback: scan consumed artifact paths on disk so
             // enforceHandoffConsumes can skip blocks for files that already exist.
-            state.existingArtifactPaths = await scanConsumedArtifactPaths(projectDir, ir, wfState.workflow, wfState.current_step);
+            if (event === "PreToolUse") {
+                state.existingArtifactPaths = await scanConsumedArtifactPaths(projectDir, ir, wfState.workflow, wfState.current_step);
+            }
         }
     }
     // Special handling for Stop — needs async workflow state read + session summary
@@ -154,17 +157,37 @@ async function main() {
     }
     // Dispatch to enforcement engine with timing
     const start = Date.now();
-    const output = dispatch(event, ir, rawInput, state);
+    let output = dispatch(event, ir, rawInput, state);
     const durationMs = Date.now() - start;
+    // Extract target file path for trace + pattern detection
+    const toolInput = typeof rawInput.tool_input === "object" && rawInput.tool_input !== null
+        ? rawInput.tool_input : undefined;
+    let targetPath = typeof toolInput?.file_path === "string" ? toolInput.file_path : undefined;
+    if (!targetPath && typeof toolInput?.command === "string") {
+        const bashPaths = extractBashWritePaths(toolInput.command);
+        if (bashPaths.length > 0)
+            targetPath = bashPaths[0];
+    }
+    // O4: Block pattern recognition — suggest scope expansion on repeated blocks
+    if (event === "PreToolUse" && output.continue === false && targetPath) {
+        try {
+            const traces = await readTraces(projectDir, 1);
+            const blockCount = traces.filter(t => t.decision === "block" && t.target_path === targetPath).length;
+            if (blockCount >= 2) {
+                output = {
+                    ...output,
+                    reason: (output.reason ?? "") +
+                        `\n\n[Intent DNA] Pattern detected: '${targetPath}' blocked ${blockCount + 1} times this session. Consider expanding the role's write scope.`,
+                };
+            }
+        }
+        catch { /* fail-open: pattern detection never blocks */ }
+    }
     writeOutput(output);
     // Trace logging (async, fail-open)
     const decision = output.continue === false ? "block"
         : output.hookSpecificOutput?.additionalContext?.startsWith("WARN") ? "warn"
             : "allow";
-    // Extract target file path from tool_input (Write/Edit/Read)
-    const toolInput = typeof rawInput.tool_input === "object" && rawInput.tool_input !== null
-        ? rawInput.tool_input : undefined;
-    const targetPath = typeof toolInput?.file_path === "string" ? toolInput.file_path : undefined;
     appendTrace(projectDir, {
         trace_id: randomUUID(),
         event,
@@ -221,7 +244,11 @@ function dispatch(event, ir, input, state) {
                 agent_type: typeof input.agent_type === "string" ? input.agent_type : undefined,
             });
         case "PreCompact":
-            return enforcePreCompact(ir);
+            return enforcePreCompact(ir, state.workflowState ? {
+                workflow: state.workflowState.workflow,
+                current_step: state.workflowState.current_step,
+                current_role: state.workflowState.current_role ?? "",
+            } : null);
         case "Notification":
             return enforceNotification(ir, {
                 title: typeof input.title === "string" ? input.title : undefined,

package/dist/hooks/enforce.d.ts

@@ -26,6 +26,7 @@ export interface EnforceState {
     workflowState?: {
         current_step: string;
         workflow: string;
+        current_role?: string;
         completed_artifacts?: CompletedArtifactEntry[];
     };
     /** Artifact paths that exist on disk — fallback for re-run idempotency.
@@ -41,7 +42,8 @@ export interface EnforceState {
 export declare function enforcePreToolUse(ir: ConstraintIR, input: PreToolUseInput, state?: EnforceState, roles?: Record<string, RoleDef>): HookOutput;
 /**
  * Enforce PostToolUse validators.
- * Currently logs validators for audit. Returns allow with context.
+ * 1. Runs post-execution validators (audit)
+ * 2. Verifies Bash write paths were within scope (defense-in-depth)
  */
 export declare function enforcePostToolUse(ir: ConstraintIR, input: PostToolUseInput): HookOutput;
 /**
@@ -55,8 +57,13 @@ export declare function enforceUserPromptSubmit(ir: ConstraintIR, _input: UserPr
 export declare function enforceSubagentStop(ir: ConstraintIR, input: SubagentStopInput): HookOutput;
 /**
  * Preserve DNA directive summary before context compaction.
+ * Includes: high-priority directives, role scope map, active workflow state.
  */
-export declare function enforcePreCompact(ir: ConstraintIR): HookOutput;
+export declare function enforcePreCompact(ir: ConstraintIR, workflowContext?: {
+    workflow: string;
+    current_step: string;
+    current_role: string;
+} | null): HookOutput;
 /**
  * Check if a notification is a DNA violation and return audit info.
  * The CLI handles actual audit file writes.
@@ -124,3 +131,9 @@ export declare function evaluateGateCondition(condition: string, input: PreToolU
  * Resolve a tool filter target to concrete Claude Code tool names.
  */
 export declare function resolveToolTarget(target?: string): string[] | null;
+/**
+ * Extract file paths that a Bash command writes to.
+ * Detects: output redirection (> / >>), tee, cp, mv.
+ * Returns deduplicated list of target paths.
+ */
+export declare function extractBashWritePaths(command: string): string[];

package/dist/hooks/enforce.js

@@ -14,7 +14,7 @@
  * Step checkpoints are handled by the CLI, not here.
  */
 import { allowOutput, blockOutput, escalateOutput, silentOutput } from "./protocol.js";
-import { relative } from "node:path";
+import { relative, normalize } from "node:path";
 // ── PreToolUse Enforcement ─────────────────────────────────
 /**
  * Enforce PreToolUse constraints.
@@ -58,16 +58,31 @@ export function enforcePreToolUse(ir, input, state, roles) {
 // ── PostToolUse Enforcement ────────────────────────────────
 /**
  * Enforce PostToolUse validators.
- * Currently logs validators for audit. Returns allow with context.
+ * 1. Runs post-execution validators (audit)
+ * 2. Verifies Bash write paths were within scope (defense-in-depth)
  */
 export function enforcePostToolUse(ir, input) {
-    const validators = ir.post_execution_validators;
-    if (validators.length === 0)
-        return silentOutput();
     const lines = [];
+    // Layer 1: Post-execution validators
+    const validators = ir.post_execution_validators;
     for (const v of validators) {
         lines.push(`[Intent DNA] PostToolUse validator: ${v.check} (gene: ${v.source_gene})`);
     }
+    // Layer 2: Bash write scope verification (defense-in-depth)
+    if (input.tool_name === "Bash" && input.agent_type && ir.roles_scope_map && ir.roles_scope_map.length > 0) {
+        const cmd = input.tool_input.command;
+        if (typeof cmd === "string") {
+            const writePaths = extractBashWritePaths(cmd);
+            if (writePaths.length > 0) {
+                const violations = verifyPathsAgainstScope(ir.roles_scope_map, input.agent_type, writePaths, input.cwd);
+                for (const v of violations) {
+                    lines.push(`WARN [Intent DNA] PostToolUse: Bash wrote outside scope — ${v}`);
+                }
+            }
+        }
+    }
+    if (lines.length === 0)
+        return silentOutput();
     return allowOutput(lines.join("\n"));
 }
 // ── UserPromptSubmit Enforcement ───────────────────────────
@@ -113,14 +128,18 @@ export function enforceSubagentStop(ir, input) {
 // ── PreCompact Enforcement ─────────────────────────────────
 /**
  * Preserve DNA directive summary before context compaction.
+ * Includes: high-priority directives, role scope map, active workflow state.
  */
-export function enforcePreCompact(ir) {
-    if (ir.prompt_directives.length === 0)
+export function enforcePreCompact(ir, workflowContext) {
+    const hasDirectives = ir.prompt_directives.length > 0;
+    const hasRoles = ir.roles_scope_map && ir.roles_scope_map.length > 0;
+    const hasWorkflow = !!workflowContext;
+    if (!hasDirectives && !hasRoles && !hasWorkflow)
         return silentOutput();
     const critical = ir.prompt_directives.filter(d => d.priority === "high");
     const standard = ir.prompt_directives.filter(d => d.priority === "medium");
     const lines = [
-        "[Intent DNA] PreCompact: Preserving directive summary for compact",
+        "[Intent DNA] PreCompact: Preserving governance context for compact",
     ];
     if (critical.length > 0) {
         lines.push("  Critical directives:");
@@ -134,6 +153,19 @@ export function enforcePreCompact(ir) {
             lines.push(`    - [${d.source_gene}] ${d.text}`);
         }
     }
+    // Preserve role scope map so agent knows its boundaries post-compact
+    if (hasRoles) {
+        lines.push("  Active role scopes:");
+        for (const entry of ir.roles_scope_map) {
+            const writeGlobs = entry.scope.write ?? [];
+            const readGlobs = entry.scope.read ?? [];
+            lines.push(`    - ${entry.role_name}: write=[${writeGlobs.join(",")}] read=[${readGlobs.join(",")}]`);
+        }
+    }
+    // Preserve workflow state so agent retains step context
+    if (hasWorkflow) {
+        lines.push(`  Active workflow: ${workflowContext.workflow} (step: ${workflowContext.current_step}, role: ${workflowContext.current_role})`);
+    }
     return allowOutput(lines.join("\n"));
 }
 // ── Notification Enforcement ───────────────────────────────
@@ -315,29 +347,72 @@ export function enforceHandoffProduces(ir, wfState) {
 function enforceRoleScope(rolesScopeMap, input) {
     if (!input.agent_type)
         return null;
-    if (!isWriteTool(input.tool_name))
-        return null;
-    const filePath = extractFilePath(input);
-    if (!filePath)
+    // Standard write tools: check single file path
+    if (isWriteTool(input.tool_name)) {
+        const filePath = extractFilePath(input);
+        if (!filePath)
+            return null;
+        return checkPathAgainstScope(rolesScopeMap, input, filePath);
+    }
+    // Bash: extract potential write targets from command
+    if (input.tool_name === "Bash") {
+        const cmd = input.tool_input.command;
+        if (typeof cmd !== "string")
+            return null;
+        const writePaths = extractBashWritePaths(cmd);
+        if (writePaths.length === 0)
+            return null;
+        for (const p of writePaths) {
+            const result = checkPathAgainstScope(rolesScopeMap, input, p);
+            if (result)
+                return result;
+        }
         return null;
-    // Convert absolute path to relative for glob matching
+    }
+    return null;
+}
+/** Check a single file path against role scope. Shared by Write tools and Bash. */
+function checkPathAgainstScope(rolesScopeMap, input, filePath) {
     const cwd = input.cwd;
-    const relativePath = cwd && filePath.startsWith("/") ? relative(cwd, filePath) : filePath;
+    let relativePath = cwd && filePath.startsWith("/") ? relative(cwd, filePath) : filePath;
+    // Normalize to resolve traversal (e.g., "src/../../test/x.ts" → "../test/x.ts")
+    relativePath = normalize(relativePath);
     for (const entry of rolesScopeMap) {
         const agentTypeName = `dna-${toKebabCase(entry.role_name)}`;
         if (input.agent_type !== agentTypeName)
             continue;
         const writeGlobs = entry.scope.write ?? [];
         if (writeGlobs.length === 0) {
-            return blockOutput(`[Intent DNA]: Role '${entry.role_name}' has no write permission (path: ${filePath})`);
+            return allowOutput(`WARN [Intent DNA]: Role '${entry.role_name}' has no write permission (path: ${filePath}). Merge-time scope gate will filter.`);
         }
         if (!checkWriteAllowed(relativePath, writeGlobs)) {
-            return blockOutput(`[Intent DNA]: Role '${entry.role_name}' cannot write to '${filePath}' (allowed: ${writeGlobs.join(", ")})`);
+            return allowOutput(`WARN [Intent DNA]: Role '${entry.role_name}' cannot write to '${filePath}' (allowed: ${writeGlobs.join(", ")}). Merge-time scope gate will filter.`);
         }
         return null; // Role matched, write allowed
     }
     return null; // No matching role — allow
 }
+/**
+ * Verify a list of paths against role scope. Returns violation messages.
+ * Used by PostToolUse for defense-in-depth auditing (warn, not block).
+ */
+function verifyPathsAgainstScope(rolesScopeMap, agentType, paths, cwd) {
+    const violations = [];
+    for (const entry of rolesScopeMap) {
+        const agentTypeName = `dna-${toKebabCase(entry.role_name)}`;
+        if (agentType !== agentTypeName)
+            continue;
+        const writeGlobs = entry.scope.write ?? [];
+        for (const p of paths) {
+            const relativePath = cwd && p.startsWith("/") ? relative(cwd, p) : p;
+            if (writeGlobs.length === 0 || !checkWriteAllowed(relativePath, writeGlobs)) {
+                violations.push(`role '${entry.role_name}' wrote to '${p}' (allowed: ${writeGlobs.join(", ") || "none"})`);
+            }
+        }
+        break; // Found the role, done
+    }
+    return violations;
+}
 function enforceToolFilters(filters, input) {
     for (const filter of filters) {
         const matchedTools = resolveToolTarget(filter.target);
@@ -486,12 +561,67 @@ function extractFilePath(input) {
     const fp = input.tool_input.file_path;
     if (typeof fp === "string" && fp)
         return fp;
-    // Bash tool — try to extract from command
-    const cmd = input.tool_input.command;
-    if (typeof cmd === "string")
-        return null; // Can't reliably extract
     return null;
 }
+/**
+ * Extract file paths that a Bash command writes to.
+ * Detects: output redirection (> / >>), tee, cp, mv.
+ * Returns deduplicated list of target paths.
+ */
+export function extractBashWritePaths(command) {
+    const paths = [];
+    // 1. Output redirection: > or >>
+    //    Skip fd duplication (>&N, >&-), /dev/ paths, and variable expansions
+    const redirectRegex = />{1,2}\s*(?!&)(?:"([^"]+)"|'([^']+)'|([^\s;|&><()`$]+))/g;
+    let match;
+    while ((match = redirectRegex.exec(command)) !== null) {
+        const p = match[1] ?? match[2] ?? match[3];
+        if (p && !p.startsWith("/dev/"))
+            paths.push(p);
+    }
+    // 2. tee command: writes stdin to file(s)
+    //    tee [-ai] file1 [file2 ...]
+    const teeMatch = command.match(/\btee\s+(.*?)(?:[;|&]|$)/);
+    if (teeMatch) {
+        const teeArgs = teeMatch[1].trim().split(/\s+/);
+        for (const arg of teeArgs) {
+            if (arg.startsWith("-"))
+                continue;
+            if (arg.startsWith("/dev/"))
+                continue;
+            if (arg.startsWith("$"))
+                continue;
+            // Handle quoted paths
+            const cleaned = arg.replace(/^["']|["']$/g, "");
+            if (cleaned)
+                paths.push(cleaned);
+        }
+    }
+    // 3. cp/mv destination: last non-flag argument
+    const cpMvMatch = command.match(/\b(cp|mv)\s+(.*?)(?:[;|&]|$)/);
+    if (cpMvMatch) {
+        const args = cpMvMatch[2].trim().split(/\s+/).filter(a => !a.startsWith("-"));
+        if (args.length >= 2) {
+            const dest = args[args.length - 1].replace(/^["']|["']$/g, "");
+            if (dest && !dest.startsWith("/dev/") && !dest.startsWith("$")) {
+                paths.push(dest);
+            }
+        }
+    }
+    // 4. sed -i: in-place file editing — the target file is the last argument
+    const sedInPlace = command.match(/\bsed\s+[^;|&]*?-i/);
+    if (sedInPlace) {
+        const sedFull = command.match(/\bsed\s+(.*?)(?:\s*[;|&]|$)/);
+        if (sedFull) {
+            const tokens = sedFull[1].trim().split(/\s+/);
+            const lastToken = tokens[tokens.length - 1]?.replace(/^["']|["']$/g, "");
+            if (lastToken && !lastToken.startsWith("/dev/") && !lastToken.startsWith("$") && !lastToken.startsWith("-")) {
+                paths.push(lastToken);
+            }
+        }
+    }
+    return [...new Set(paths)];
+}
 /** Convert string to kebab-case (matches agent-md.ts toKebabCase). */
 function toKebabCase(s) {
     return s

package/dist/runtime/workflow-runner.js

@@ -258,11 +258,13 @@ function generateGroupExecution(group, stepMap, options, plan) {
         }
         // Merge worktrees back (escalate on conflict)
         lines.push("");
-        lines.push("  # Merge worktrees back to main branch");
+        lines.push("  # Scope gate + merge worktrees back to main branch");
         for (const id of group.step_ids) {
+            const step = stepMap.get(id);
             const varId = sanitizeForBash(id);
             const safeId = sanitizeForShell(id);
             lines.push(`  if [ "$STEP_${varId}_STATUS" -eq 0 ]; then`);
+            lines.push(`    scope_gate "${safeId}" "dna-wt-${safeId}" "${step.role}" "${safeId}"`);
             lines.push(`    merge_worktree "dna-wt-${safeId}" "${safeId}"`);
             lines.push("  fi");
         }
@@ -336,6 +338,77 @@ function generateMergeWorktreeFn() {
         "",
     ];
 }
+/**
+ * Generate the scope_gate bash helper function.
+ * Filters out-of-scope file changes from a worktree branch before merging.
+ * Reads role write scope from .dna/compiled/ir.json, reverts unauthorized files,
+ * and writes trace entries for each violation.
+ * Fail-open: never prevents merge from proceeding.
+ */
+function generateScopeGateFn() {
+    return [
+        "# Scope gate: filter out-of-scope changes before merge (three-layer defense L3)",
+        "scope_gate() {",
+        '  local name="$1" branch="$2" role="$3" step_id="$4"',
+        '  local ir_path="${PROJECT_ROOT}/.dna/compiled/ir.json"',
+        "",
+        '  [ ! -f "$ir_path" ] && return 0',
+        "",
+        "  # Read write scope globs for this role from IR",
+        "  local allowed_globs",
+        "  allowed_globs=$(jq -r --arg role \"$role\" \\",
+        "    '.roles_scope_map[]? | select(.role_name == $role) | .scope.write[]?' \\",
+        '    "$ir_path" 2>/dev/null)',
+        "",
+        "  # No scope defined — allow all changes",
+        '  [ -z "$allowed_globs" ] && return 0',
+        "",
+        "  # Get files changed by this branch vs main",
+        "  local changed",
+        '  changed=$(git diff --name-only "$MAIN_BRANCH...$branch" 2>/dev/null)',
+        '  [ -z "$changed" ] && return 0',
+        "",
+        "  local rejected=()",
+        '  while IFS= read -r file; do',
+        '    [ -z "$file" ] && continue',
+        "    local allowed=false",
+        '    while IFS= read -r glob; do',
+        '      [ -z "$glob" ] && continue',
+        "      # Prefix matching (consistent with enforce.ts globToPrefix)",
+        '      local prefix="${glob%%\\**}"',
+        '      if [ -z "$prefix" ] || [[ "$file" == "${prefix}"* ]]; then',
+        "        allowed=true",
+        "        break",
+        "      fi",
+        '    done <<< "$allowed_globs"',
+        '    if [ "$allowed" = false ]; then',
+        '      rejected+=("$file")',
+        "    fi",
+        '  done <<< "$changed"',
+        "",
+        '  [ ${#rejected[@]} -eq 0 ] && return 0',
+        "",
+        "  echo \"[Intent DNA] Scope gate: ${#rejected[@]} file(s) outside role '${role}' scope, reverted:\"",
+        '  printf "  - %s\\n" "${rejected[@]}"',
+        "",
+        "  # Revert out-of-scope files in worktree branch",
+        '  for file in "${rejected[@]}"; do',
+        '    (cd ".dna/worktrees/${name}" && git checkout "$MAIN_BRANCH" -- "$file") 2>/dev/null || true',
+        "  done",
+        '  (cd ".dna/worktrees/${name}" && git add -A && git commit --amend --no-edit) 2>/dev/null || true',
+        "",
+        "  # Write trace entries for scope violations",
+        '  local trace_dir="${PROJECT_ROOT}/.dna/state/trace"',
+        '  mkdir -p "$trace_dir" 2>/dev/null || true',
+        '  local trace_file="${trace_dir}/trace-$(date +%Y-%m-%d).jsonl"',
+        '  for file in "${rejected[@]}"; do',
+        "    printf '{\"trace_id\":\"%s\",\"event\":\"ScopeGate\",\"agent_type\":\"dna-%s\",\"step\":\"%s\",\"decision\":\"warn\",\"reason\":\"Merge-time scope gate reverted out-of-scope file\",\"target_path\":\"%s\",\"duration_ms\":0,\"timestamp\":\"%s\"}\\n' \\",
+        "      \"$(uuidgen | tr '[:upper:]' '[:lower:]')\" \"$role\" \"$step_id\" \"$file\" \"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)\" >> \"$trace_file\"",
+        "  done",
+        "}",
+        "",
+    ];
+}
 /**
  * Generate transition check code after all groups execute.
  */
@@ -404,9 +477,10 @@ export function compileWorkflowToShell(plan, options) {
     // run_agent function
     lines.push(...generateRunAgentFn(opts));
     lines.push("");
-    // merge_worktree function (only if needed)
+    // merge_worktree + scope_gate functions (only if needed)
     if (needsWorktreeSupport(plan)) {
         lines.push(...generateMergeWorktreeFn());
+        lines.push(...generateScopeGateFn());
     }
     // Main execution
     if (plan.retry.max_retries > 0) {

package/package.json

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

package/spec/parallel-isolation.md

@@ -19,8 +19,31 @@ DNA 模板可声明并行执行策略和文件隔离策略，编译到 workflow-
 | Schema 声明 | step 属性 + parallel block 双支持 | 灵活性 + 简洁性兼顾 |
 | auto 模式 | 编译时 scope overlap 检测 | DNA 独有能力——Role scope 编译时已知 |
 | merge 策略 | escalate only (MVP) | 冲突报告给用户，不自动解决 |
+| scope.write 语义 | merge-time accept filter | 不是运行时 block rule，是合并时的产出过滤器 |
 | 模型差异 | 暂不考虑 | 后续扩展 |
 
+## 设计哲学：默会知识与三层防御
+
+参考波兰尼（Michael Polanyi）默会知识理论：意图不能被规则穷尽，但可以通过适当的"身体"来实现。
+
+**核心洞察**：`scope.write: ["test/**"]` 表达的是模板作者的**意图**（"这个角色只该写测试文件"），不应该被实现为运行时工具拦截（显性规则，不完备），而应该被实现为物理隔离 + 出口把关（身体 + 审查）。
+
+### 为什么工具拦截不可靠
+
+路径级 scope enforce 通过拦截工具检查文件路径（Write/Edit/Bash/MCP...）。但写文件的工具不可枚举——每出现一个新工具就是一个绕过点。这是认识论问题，不是实现问题：显性规则永远追不上默会知识的丰富度。
+
+### 三层对应
+
+| 层 | 时机 | 机制 | 波兰尼对应 | 可靠度 |
+|---|---|---|---|---|
+| **工具控制** | PreToolUse | `tool_permissions.deny` — 禁止工具本身 | 显性知识（可完全条文化） | 高——工具名有限可枚举 |
+| **过程提示** | PreToolUse | 当前 scope enforce（保留为软防线） | 辅助线索（from） | 低——最佳努力，不可依赖 |
+| **出口把关** | Merge time | **scope gate 过滤 git diff** — 只接受 scope 内改动 | 焦点判断（to） | **确定性——基于实际产出** |
+
+scope.write 的真正语义：**merge 时的 accept filter**，不是运行时的 block rule。
+
+agent 在 worktree 内有完整读权限（理解上下文）和写自由（不被微管理），但只有符合角色意图的产出才能合并回主分支。如同管理者不盯每次敲键盘，而在 review 时评估产出。
+
 ## Schema 设计
 
 ### isolation 取值
@@ -152,6 +175,39 @@ git worktree remove .dna/worktrees/fix-auth 2>/dev/null
 git worktree remove .dna/worktrees/fix-api 2>/dev/null
 ```
 
+### Merge-time scope gate
+
+合并前过滤越权改动（scope.write 的真正执行点）：
+
+```bash
+# scope gate: 只接受 scope 内的改动
+scope_gate() {
+  local branch=$1 role=$2
+  # 获取该 role 的 write scope globs (从 IR 读取)
+  local allowed_globs=$(read_scope_globs "$role")
+  
+  # 检查所有改动文件
+  local changed=$(git diff --name-only HEAD...$branch)
+  local rejected=()
+  for file in $changed; do
+    if ! matches_any_glob "$file" $allowed_globs; then
+      rejected+=("$file")
+      # 在 worktree 中 revert 越权改动
+      (cd .dna/worktrees/$branch && git checkout HEAD -- "$file")
+    fi
+  done
+  
+  if [ ${#rejected[@]} -gt 0 ]; then
+    echo "[Intent DNA] Scope gate: ${#rejected[@]} file(s) outside scope, reverted:"
+    printf "  - %s\n" "${rejected[@]}"
+    # trace 记录越权尝试 → 表观遗传反馈
+  fi
+}
+
+scope_gate "fix-auth" "surgeon"
+scope_gate "fix-api" "surgeon"
+```
+
 ## Constraint IR 扩展
 
 ```typescript
@@ -175,11 +231,14 @@ interface WorkflowIR {
 
 | DNA 概念 | 在并行隔离中的角色 |
 |---|---|
+| **Role scope.write** | **merge-time scope gate 的输入**——决定哪些改动可以合并回主分支 |
 | **Role scope** | auto 模式的编译时 overlap 分析输入 |
+| **tool_permissions.deny** | 工具级控制（可靠层）——reviewer 不能用 Edit |
 | **Handoff** | 并行 step 的 artifact 传递（已实现） |
 | **Threshold codon** | 可声明 `parallel_without_isolation == false` 硬约束 |
 | **Attract codon** | `attract: worktree_per_task` 软提示（保留兼容） |
-| **Hooks enforce** | worktree 内 scope enforce 仍生效 |
+| **Hooks enforce (PreToolUse)** | 保留为过程提示（辅助软防线），不作为安全保障依赖 |
+| **表观遗传** | scope gate 越权记录 → trace → epigenetic marker 反馈 |
 
 ## 不做
 
@@ -187,6 +246,7 @@ interface WorkflowIR {
 - LLM 模型差异适配（暂不考虑）
 - context budget 管理（已由独立进程 + Handoff 解决）
 - container 级隔离（过度设计）
+- sparse-checkout（限制读权限会破坏 agent 理解上下文的能力）
 
 ## Acceptance Criteria
 
@@ -197,9 +257,12 @@ interface WorkflowIR {
 - [ ] Compiler: parallel block 展开为 step + depends_on
 - [ ] workflow-runner: isolation=none 行为不变（向后兼容）
 - [ ] workflow-runner: isolation=worktree 生成 git worktree 生命周期脚本
+- [ ] workflow-runner: merge 前执行 scope gate（过滤越权改动）
 - [ ] workflow-runner: merge 冲突时 escalate（报告 + 保留分支）
+- [ ] scope gate: 越权改动被 revert + trace 记录
 - [ ] E2E: 两个并行 step 写不同目录，auto → none，正确执行
 - [ ] E2E: 两个并行 step 写相同目录，auto → worktree，隔离执行 + merge
+- [ ] E2E: agent 写越权文件，scope gate 过滤 + trace 记录
 - [ ] Dogfood: flutter-rewrite rescue workflow 可配置 isolation
 - [ ] IR: ParallelGroup 包含 isolation + scope_overlap 信息
 - [ ] 测试覆盖所有新增代码