intentdna 1.5.3 → 1.5.5

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "intentdna",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "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:"))

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/hooks/cli.js

@@ -278,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;
         }
@@ -286,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/mcp/index.js

@@ -13,6 +13,7 @@
 import { createMCPServer } from "./server.js";
 import { createStateTools } from "./tools-state.js";
 import { createCompileTools } from "./tools-compile.js";
+import { createEnforceTools } from "./tools-enforce.js";
 // Parse args
 const args = process.argv.slice(2);
 let projectDir = process.cwd();
@@ -34,5 +35,6 @@ catch { /* use default */ }
 const tools = [
     ...createStateTools(projectDir),
     ...createCompileTools(projectDir),
+    ...createEnforceTools(projectDir),
 ];
 createMCPServer({ name: "intentdna", version }, tools);

package/dist/mcp/tools-enforce.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Intent DNA — MCP Enforce Tools (U2)
+ *
+ * Provides enforcement via MCP server with in-memory IR cache.
+ * Zero cold-start: IR is loaded once and cached with mtime-based invalidation.
+ *
+ * Tools:
+ *   - dna_enforce: Run enforcement for a hook event (PreToolUse, PostToolUse, etc.)
+ */
+import type { ConstraintIR, RoleDef } from "../schema/types.js";
+import type { ToolDef } from "./server.js";
+/** In-memory IR cache with mtime-based invalidation. */
+export declare class IRCache {
+    private ir;
+    private roles;
+    private lastMtime;
+    private irPath;
+    constructor(projectDir: string);
+    /** Get cached IR, reloading from disk only if file changed. */
+    get(): Promise<{
+        ir: ConstraintIR;
+        roles?: Record<string, RoleDef>;
+    } | null>;
+    /** Invalidate the cache (e.g., after dna sync). */
+    invalidate(): void;
+}
+export declare function createEnforceTools(projectDir: string): ToolDef[];

package/dist/mcp/tools-enforce.js

@@ -0,0 +1,178 @@
+/**
+ * Intent DNA — MCP Enforce Tools (U2)
+ *
+ * Provides enforcement via MCP server with in-memory IR cache.
+ * Zero cold-start: IR is loaded once and cached with mtime-based invalidation.
+ *
+ * Tools:
+ *   - dna_enforce: Run enforcement for a hook event (PreToolUse, PostToolUse, etc.)
+ */
+import { resolve } from "node:path";
+import { stat, readFile } from "node:fs/promises";
+import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, } from "../hooks/enforce.js";
+import { textResult, errorResult } from "./server.js";
+// ── IR Cache ────────────────────────────────────────────────
+/** In-memory IR cache with mtime-based invalidation. */
+export class IRCache {
+    ir = null;
+    roles = undefined;
+    lastMtime = 0;
+    irPath;
+    constructor(projectDir) {
+        this.irPath = resolve(projectDir, ".dna", "compiled", "ir.json");
+    }
+    /** Get cached IR, reloading from disk only if file changed. */
+    async get() {
+        try {
+            const fileStat = await stat(this.irPath);
+            const mtime = fileStat.mtimeMs;
+            const cachedIR = this.ir;
+            if (cachedIR && mtime === this.lastMtime) {
+                return { ir: cachedIR, roles: this.roles };
+            }
+            // File changed or first load — read from disk
+            const raw = await readFile(this.irPath, "utf-8");
+            const data = JSON.parse(raw);
+            if (data.ir_version && data.ir) {
+                const ir = data.ir;
+                this.ir = ir;
+                this.roles = data.roles;
+                this.lastMtime = mtime;
+                return { ir, roles: this.roles };
+            }
+            // Direct ConstraintIR format (backward compat)
+            if (data.compiled_at && data.source_dna_ids) {
+                const ir = data;
+                this.ir = ir;
+                this.roles = undefined;
+                this.lastMtime = mtime;
+                return { ir };
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Invalidate the cache (e.g., after dna sync). */
+    invalidate() {
+        this.ir = null;
+        this.roles = undefined;
+        this.lastMtime = 0;
+    }
+}
+const VALID_EVENTS = new Set([
+    "PreToolUse", "PostToolUse", "UserPromptSubmit",
+    "SubagentStop", "PreCompact", "Notification", "SessionStart",
+]);
+function dispatchEnforce(event, ir, input, roles) {
+    switch (event) {
+        case "PreToolUse":
+            return enforcePreToolUse(ir, {
+                tool_name: String(input.tool_name ?? ""),
+                tool_input: (input.tool_input ?? {}),
+                agent_type: typeof input.agent_type === "string" ? input.agent_type : undefined,
+                cwd: typeof input.cwd === "string" ? input.cwd : undefined,
+            }, undefined, roles);
+        case "PostToolUse":
+            return enforcePostToolUse(ir, {
+                tool_name: String(input.tool_name ?? ""),
+                tool_input: (input.tool_input ?? {}),
+                tool_output: typeof input.tool_output === "string" ? input.tool_output : undefined,
+                agent_type: typeof input.agent_type === "string" ? input.agent_type : undefined,
+            });
+        case "UserPromptSubmit":
+            return enforceUserPromptSubmit(ir, {
+                prompt: typeof input.prompt === "string" ? input.prompt : undefined,
+            });
+        case "SubagentStop":
+            return enforceSubagentStop(ir, {
+                agent_name: typeof input.agent_name === "string" ? input.agent_name : undefined,
+                agent_type: typeof input.agent_type === "string" ? input.agent_type : undefined,
+            });
+        case "PreCompact":
+            return enforcePreCompact(ir);
+        case "Notification":
+            return enforceNotification(ir, {
+                title: typeof input.title === "string" ? input.title : undefined,
+                message: typeof input.message === "string" ? input.message : undefined,
+            });
+        case "SessionStart":
+            return enforceSessionStart(ir, {
+                cwd: typeof input.cwd === "string" ? input.cwd : undefined,
+                session_id: typeof input.session_id === "string" ? input.session_id : undefined,
+            });
+        default:
+            return { continue: true, suppressOutput: true };
+    }
+}
+// ── Tool Registration ───────────────────────────────────────
+export function createEnforceTools(projectDir) {
+    const cache = new IRCache(projectDir);
+    return [
+        {
+            name: "dna_enforce",
+            description: "Run DNA enforcement for a hook event. Uses in-memory cached IR for zero cold-start. " +
+                "Returns the same result as the dna-hook binary but without spawning a new process.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    event: {
+                        type: "string",
+                        description: "Hook event type",
+                        enum: [...VALID_EVENTS],
+                    },
+                    input: {
+                        type: "object",
+                        description: "Hook input (same fields as Claude Code passes to hooks via stdin)",
+                    },
+                },
+                required: ["event", "input"],
+            },
+            handler: async (args) => {
+                const event = String(args.event);
+                if (!VALID_EVENTS.has(event)) {
+                    return errorResult(`Invalid event: ${event}. Valid: ${[...VALID_EVENTS].join(", ")}`);
+                }
+                const cached = await cache.get();
+                if (!cached) {
+                    return errorResult("No compiled IR found. Run `dna sync` to compile your DNA config.");
+                }
+                const input = (args.input ?? {});
+                const result = dispatchEnforce(event, cached.ir, input, cached.roles);
+                // Format as human-readable text
+                const lines = [];
+                lines.push(`Decision: ${result.continue ? "allow" : "BLOCK"}`);
+                if (result.reason)
+                    lines.push(`Reason: ${result.reason}`);
+                if (result.hookSpecificOutput?.additionalContext) {
+                    lines.push(`Context: ${result.hookSpecificOutput.additionalContext}`);
+                }
+                return textResult(lines.join("\n"));
+            },
+        },
+        {
+            name: "dna_enforce_cache_status",
+            description: "Check IR cache status — whether IR is loaded, file path, and last load time",
+            inputSchema: { type: "object", properties: {} },
+            handler: async () => {
+                const cached = await cache.get();
+                if (!cached) {
+                    return textResult("IR cache: empty (no compiled IR found at .dna/compiled/ir.json)");
+                }
+                const lines = [
+                    "IR cache: loaded",
+                    `  Templates: ${cached.ir.source_dna_ids.join(", ")}`,
+                    `  Compiled: ${cached.ir.compiled_at}`,
+                    `  Directives: ${cached.ir.prompt_directives.length}`,
+                    `  Gates: ${cached.ir.pre_execution_gates.length}`,
+                    `  Filters: ${cached.ir.tool_filters.length}`,
+                ];
+                if (cached.roles) {
+                    lines.push(`  Roles: ${Object.keys(cached.roles).join(", ")}`);
+                }
+                return textResult(lines.join("\n"));
+            },
+        },
+    ];
+}

package/dist/schema/yaml-parser.d.ts

@@ -3,8 +3,8 @@
  *
  * Parses the YAML subset used by DNA templates and dna import output.
  * Supports: scalars, arrays (inline and block), objects (indentation),
- * comments, quoted strings. Does NOT support: anchors, aliases, tags,
- * multi-line scalars (|, >), complex keys, merge keys.
+ * comments, quoted strings, block scalars (|, >).
+ * Does NOT support: anchors, aliases, tags, complex keys, merge keys.
  *
  * Zero external dependencies.
  */

package/dist/schema/yaml-parser.js

@@ -3,8 +3,8 @@
  *
  * Parses the YAML subset used by DNA templates and dna import output.
  * Supports: scalars, arrays (inline and block), objects (indentation),
- * comments, quoted strings. Does NOT support: anchors, aliases, tags,
- * multi-line scalars (|, >), complex keys, merge keys.
+ * comments, quoted strings, block scalars (|, >).
+ * Does NOT support: anchors, aliases, tags, complex keys, merge keys.
  *
  * Zero external dependencies.
  */
@@ -49,6 +49,34 @@ function parseBlock(lines, startLine, baseIndent) {
             const key = content.slice(0, colonIdx).trim();
             const valueStr = content.slice(colonIdx + 1).trim();
             if (valueStr === "" || valueStr === "|" || valueStr === ">") {
+                // Block scalar: collect indented lines as a single string
+                if (valueStr === "|" || valueStr === ">") {
+                    const blockLines = [];
+                    let j = i + 1;
+                    const blockIndent = j < lines.length ? getIndent(lines[j]) : indent + 2;
+                    while (j < lines.length) {
+                        const bLine = lines[j];
+                        const bStripped = bLine.trimEnd();
+                        if (bStripped === "") {
+                            blockLines.push("");
+                            j++;
+                            continue;
+                        }
+                        const bIndent = getIndent(bLine);
+                        if (bIndent < blockIndent)
+                            break;
+                        blockLines.push(bLine.slice(blockIndent));
+                        j++;
+                    }
+                    // Trim trailing empty lines
+                    while (blockLines.length > 0 && blockLines[blockLines.length - 1] === "") {
+                        blockLines.pop();
+                    }
+                    const sep = valueStr === "|" ? "\n" : " ";
+                    obj[key] = blockLines.join(sep) + "\n";
+                    i = j;
+                    continue;
+                }
                 // Value is a nested block — check next line's indent
                 const nextNonEmpty = findNextNonEmptyLine(lines, i + 1);
                 if (nextNonEmpty < lines.length) {

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

@@ -98,6 +98,25 @@ genes:
         signal: uncertain_information
         response: escalate_to_human
 
+  minimal_change:
+    description: Each fix should be the smallest possible change
+    codons:
+      - type: attract
+        target: single_file_change
+      - type: repel
+        target: unnecessary_refactoring
+      - type: threshold
+        condition: "files_changed_per_round <= 5"
+        action: escalate
+
+  evidence_based:
+    description: All completion claims require fresh test evidence
+    codons:
+      - type: attract
+        target: run_tests_before_claiming_done
+      - type: repel
+        target: trust_without_evidence
+
 contexts: {}
 
 
@@ -147,6 +166,9 @@ roles:
       - Find where v2 diverges
       - Report with exact file paths and line numbers
       - Never suggest code changes
+      - "If round > 1: review previous round's git diff first, judge if direction is correct"
+      - "If previous fix produced 0 red→green transitions: warn 'no progress'"
+      - "Categorize by severity: CRITICAL (compile errors) > HIGH (logic failures) > LOW (widget/style)"
 
   surgeon:
     description: Fixes breakpoints and builds missing layers by understanding v1 intent and rewriting in v2 style.
@@ -165,6 +187,12 @@ roles:
       - After each change, run tests
       - If fix doesn't work, revert and re-analyze
       - Never "improve" code — preserve exact behavior
+      - "Before each fix: run `git diff` to confirm previous round's change scope"
+      - "After each file change: run `flutter analyze` to verify compilation"
+      - "Maximum 5 files per round — if more needed, the scope is too large, split it"
+      - "Same issue failed 3 times → STOP and report as blocked, do not retry"
+      - "Commit message must include: what changed, why, which test it targets"
+      - Do not introduce new abstractions or refactor unrelated code
 
   # ── Core align 角色 ──
   core_aligner:
@@ -188,18 +216,46 @@ workflows:
     steps:
       - id: scan
         role: scanner
-        description: "Scan v1 module in {{v1_path}}/. Output behavior doc to {{behavior_docs}}/$ARGUMENTS.md. List all user actions with call chains."
-        prompt: "Scan module '$ARGUMENTS' in {{v1_path}}/. For each page, list: action → function() → return value. Output to {{behavior_docs}}/$ARGUMENTS.md. Then immediately proceed to write_tests."
+        description: "Detect scenario (first-time vs re-run), scan v1 module accordingly."
+        prompt: |
+          Scenario detection:
+          - Check if {{test_path}}/$ARGUMENTS/ has test files AND {{behavior_docs}}/$ARGUMENTS.md exists
+          - Both missing → Scenario 1 (first-time): full scan, output complete behavior doc
+          - At least one exists → Scenario 2 (re-run/incremental): read existing behavior doc, compare against v1 source changes, output incremental diff only (do NOT rewrite the entire doc)
+
+          Scenario 1: Scan module '$ARGUMENTS' in {{v1_path}}/. For each page, list: action → function() → return value. Output to {{behavior_docs}}/$ARGUMENTS.md.
+          Scenario 2: Read {{behavior_docs}}/$ARGUMENTS.md. Compare against current v1 source in {{v1_path}}/. Output only the DIFF (added/removed/changed behaviors). Append changes to existing doc, do not rewrite.
         handoff:
           produces:
             - type: file
               path: "{{behavior_docs}}/$ARGUMENTS.md"
-              description: "Behavior document for module"
+              description: "Behavior document for module (full or incremental)"
       - id: write_tests
         role: test_writer
         depends_on: [scan]
-        description: "Read {{behavior_docs}}/$ARGUMENTS.md, write tests in {{test_path}}/$ARGUMENTS/, run baseline, commit."
-        prompt: "Read {{behavior_docs}}/$ARGUMENTS.md. Write tests in {{test_path}}/$ARGUMENTS/. Test ALL layers: logic, widget, navigation. Run tests, record red/green baseline. Append baseline to behavior doc. Git commit: behavior-lock($ARGUMENTS): X tests (Y red, Z skipped)"
+        description: "Write or update tests based on scenario, verify compilation."
+        prompt: |
+          Scenario detection (same as scan step):
+          - {{test_path}}/$ARGUMENTS/ has NO test files → Scenario 1 (first-time)
+          - {{test_path}}/$ARGUMENTS/ has existing tests → Scenario 2 (re-run)
+
+          Scenario 1 (first-time):
+          - Read {{behavior_docs}}/$ARGUMENTS.md
+          - Write tests in {{test_path}}/$ARGUMENTS/. Test ALL layers: logic, widget, navigation
+          - Run `flutter analyze` to verify compilation — do NOT run `flutter test` (no implementation yet)
+          - Git commit: "behavior-lock($ARGUMENTS): N tests (fresh, not yet runnable)"
+
+          Scenario 2 (re-run/incremental):
+          - Read the incremental diff from behavior doc
+          - Update existing tests incrementally — do NOT rewrite all tests (preserves rescue progress)
+          - Run `flutter test {{test_path}}/$ARGUMENTS/` with NO timeout — record baseline
+          - Append baseline to behavior doc
+          - Git commit: "behavior-lock($ARGUMENTS): N tests (X green, Y red from behavior change)"
+
+          BANNED patterns:
+          - Do NOT use `sleep N && check` polling — run commands in foreground
+          - Do NOT use `timeout Nm flutter test` — let tests run to completion
+          - Do NOT rewrite existing test files from scratch — update incrementally
         handoff:
           consumes:
             - type: file
@@ -214,12 +270,25 @@ workflows:
 
   rescue:
     name: Rescue
-    description: "Fix v2 module $ARGUMENTS — logic layer first, then widget layer, commit when done"
+    description: "Fix v2 module $ARGUMENTS — investigate, fix, review, verify, report. Max 10 rounds with convergence protection."
+    max_rounds: 10
+    convergence_rule: "2 consecutive rounds with 0 test progress (green count not increasing) → STOP. Output blocked items + analysis."
     steps:
       - id: investigate
         role: investigator
-        description: "Run tests, assess current state, pick next targets."
-        prompt: "Run tests in {{test_path}}/$ARGUMENTS/. Categorize all non-passing tests: 1) RED (failing) — highest priority, fix first. 2) SKIPPED-logic — state/notifier/service tests, fix second. 3) SKIPPED-widget — widget/UI/navigation tests, fix after logic is done. For the highest priority category, pick a batch of related tests. Trace: what does v1 do vs what does v2 do? Find the breakpoints. Report findings and the plan for this round."
+        description: "Run tests, assess current state, pick next targets by severity."
+        prompt: |
+          Round context:
+          - If round > 1: review previous round's git diff first
+          - If previous round had 0 test progress (no red→green or skip→green): warn "no progress" and consider changing approach
+
+          Run tests in {{test_path}}/$ARGUMENTS/. Categorize all non-passing tests by severity:
+          CRITICAL: compile errors, import failures — fix first
+          HIGH: logic test failures (state/notifier/service) — fix second
+          LOW: widget test failures (rendering/navigation) — fix after logic is done
+
+          Pick highest severity batch. Trace: what does v1 do vs what does v2 do? Find the breakpoints.
+          Report findings and the plan for this round.
         handoff:
           produces:
             - type: summary
@@ -230,11 +299,20 @@ workflows:
       - id: fix
         role: surgeon
         depends_on: [investigate]
-        description: "Fix the identified issues. Handle both logic and widget layers."
+        description: "Fix identified issues. Max 5 files per round."
         checkpoints:
           - assert: clean_working_tree
-            message: "Commit all changes before proceeding to report step"
-        prompt: "Fix the identified breakpoints. Read v1 in {{v1_path}}/. Rewrite in v2 style in {{v2_path}}/. Logic tests: implement notifier/state/service code. Widget tests: copy widget from v1, change bindings (Obx→Consumer, Get.to→context.go), set up widget test infra (ProviderScope, mock providers, GoRouter) if needed. Run tests after each fix. Red→green or Skipped→green = done. Still failing = revert and re-analyze. Maximize test coverage per round. When done, commit all changes: rescue($ARGUMENTS): round N — X passed (+Y)"
+            message: "Commit all changes before proceeding"
+        prompt: |
+          Fix the identified breakpoints. Rules:
+          - Read v1 intent in {{v1_path}}/, rewrite in v2 style in {{v2_path}}/ (not copy v1 verbatim)
+          - Maximum 5 files per round — if more needed, split the scope
+          - Run `flutter analyze` after each file change
+          - Same issue failed 3 times → STOP, report as blocked, do not retry
+          - Logic tests: implement notifier/state/service code
+          - Widget tests: copy widget from v1, change bindings (Obx→Consumer, Get.to→context.go), set up infra (ProviderScope, mock providers, GoRouter) if needed
+          - Run tests after each fix. Red→green or Skip→green = progress. Still failing = revert and re-analyze
+          - Commit: "rescue($ARGUMENTS): round N — what changed, why, which tests targeted"
         handoff:
           consumes:
             - type: summary
@@ -243,11 +321,19 @@ workflows:
           produces:
             - type: git_commit
               description: "Rescue round commit"
-      - id: report
+      - id: review
         role: investigator
         depends_on: [fix]
-        description: "Summarize round, guide next steps."
-        prompt: "Run full test suite in {{test_path}}/$ARGUMENTS/. Report: 1) passed/skipped/failed delta vs last round. 2) List remaining skipped tests by category (logic vs widget vs platform). 3) If skipped tests remain, end with: Run /rescue $ARGUMENTS to continue. 4) If all tests pass, end with: Module $ARGUMENTS rescue complete."
+        description: "Read-only review of surgeon's changes."
+        prompt: |
+          Review surgeon's git diff (read-only, do NOT modify any files):
+          1. Are changes minimal? No unnecessary files touched?
+          2. Does the code match v2 patterns (Riverpod, GoRouter)?
+          3. Are mocks correct (not faked just to make tests pass)?
+          4. Any new issues introduced?
+
+          Verdict: APPROVE → proceed to verify
+          Verdict: REQUEST_CHANGES → describe specific problems. Next round's investigate step will include this feedback.
         handoff:
           consumes:
             - type: git_commit
@@ -255,7 +341,50 @@ workflows:
               description: "Committed fix from surgeon"
           produces:
             - type: summary
-              description: "Round summary with test delta"
+              description: "Review verdict (APPROVE or REQUEST_CHANGES)"
+      - id: verify
+        role: investigator
+        depends_on: [review]
+        description: "Independent test verification + regression check."
+        prompt: |
+          Run tests independently (do not trust surgeon's reported results):
+          1. `flutter test {{test_path}}/$ARGUMENTS/` (no timeout)
+          2. `flutter analyze` (compilation check)
+          3. Check for regressions in core module tests if applicable
+
+          Record test delta vs previous round.
+          Each acceptance criterion: VERIFIED / PARTIAL / MISSING
+          Verdict: PASS or FAIL
+        handoff:
+          consumes:
+            - type: summary
+              from: review
+              description: "Review verdict"
+          produces:
+            - type: test_result
+              path: "{{test_path}}/$ARGUMENTS/"
+              description: "Verified test results"
+      - id: report
+        role: investigator
+        depends_on: [verify]
+        description: "Round summary with convergence judgment."
+        prompt: |
+          Summary:
+          1. Test delta: +N green, -M red, ±K skipped vs last round
+          2. Remaining tests by category (logic vs widget vs platform)
+          3. Convergence check:
+             - If 2 consecutive rounds with no test progress → STOP, output blocked items + analysis
+             - If all green → "Module $ARGUMENTS rescue complete"
+             - Otherwise → "Run /rescue $ARGUMENTS to continue (round N+1 of max 10)"
+          4. If review verdict was REQUEST_CHANGES: include the specific feedback for next round
+        handoff:
+          consumes:
+            - type: test_result
+              from: verify
+              description: "Verified test results from verify step"
+          produces:
+            - type: summary
+              description: "Round summary with test delta and convergence status"
 
   core-align:
     name: Core Align

package/package.json

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

package/spec/flutter-rewrite-template-optimization.md

@@ -0,0 +1,270 @@
+# Spec: flutter-rewrite 模板优化
+
+## 问题
+
+flutter-rewrite 模板的 behavior-lock 和 rescue 工作流都有设计缺陷，导致：
+1. behavior-lock 不区分首次和重跑，首次跑测试浪费时间
+2. rescue 没有 code review 和 verify 步骤，surgeon 自己写自己审
+3. 没有回归检查、收敛保护、diff 审查
+
+参考 OMC agent 设计（code-reviewer/verifier/executor/test-engineer）改进。
+
+---
+
+## 一、behavior-lock 优化
+
+### 场景检测
+
+```
+检查 {{test_path}}/$ARGUMENTS/ 是否已有测试文件
+检查 {{behavior_docs}}/$ARGUMENTS.md 是否已存在
+
+两者都不存在 → 场景 1（首次）
+至少一个存在 → 场景 2（重跑/增量）
+```
+
+### 场景 1: 首次
+
+```
+scan  → 全量扫描 v1，输出完整行为文档
+write → 写测试文件 → `flutter analyze` 验证编译 → 不跑 flutter test
+commit: "behavior-lock($MODULE): N tests (fresh, not yet runnable)"
+```
+
+### 场景 2: 重跑/增量
+
+```
+scan  → 读已有行为文档，对比 v1 变化，输出增量 diff
+write → 增量更新测试（不全量重写）→ `flutter test` 无超时 → 记录 baseline
+commit: "behavior-lock($MODULE): N tests (X green, Y red from behavior change)"
+```
+
+### scanner 增量
+
+场景 2 时 scanner 不重写行为文档，而是：
+1. 读已有 behavior doc
+2. 对比 v1 源码变化
+3. 增量更新
+4. 输出 diff 摘要
+
+### 禁止的模式
+
+| 禁止 | 原因 | 替代 |
+|------|------|------|
+| `sleep N && check` 轮询 | 浪费时间 | 前台跑 |
+| `timeout Nm flutter test` | 测试可能需要很久 | 不设超时 |
+| 全量重写已有测试 | 丢失 rescue 成果 | 增量更新 |
+| 首次跑 `flutter test` | 没实现，编译不过 | `flutter analyze` |
+
+---
+
+## 二、rescue 优化
+
+### 当前流程（缺陷）
+
+```
+investigate → fix → report → 重复
+              ↑ 无人审查
+              ↑ 无回归检查
+              ↑ 无收敛保护
+```
+
+### 优化后流程
+
+```
+investigate → fix → review → verify → report
+                     ↑ 只读审查 diff    ↑ 自己跑测试+回归
+```
+
+### 新增: review 步骤（参考 OMC code-reviewer）
+
+```yaml
+- id: review
+  role: investigator    # read-only，不能改代码
+  depends_on: [fix]
+  prompt: |
+    Review surgeon's changes (git diff):
+    1. 改动是否最小化？有没有改不该改的文件？
+    2. 是否匹配 v2 代码风格（Riverpod, GoRouter）？
+    3. mock 是否正确（不是为了让测试过而写假 mock）？
+    4. 有没有引入新问题？
+    
+    Verdict: APPROVE / REQUEST_CHANGES
+    如果 REQUEST_CHANGES → 说明具体问题，下轮 investigate 带上 review 意见
+```
+
+### 新增: verify 步骤（参考 OMC verifier）
+
+```yaml
+- id: verify
+  role: investigator    # read-only
+  depends_on: [review]  # review APPROVE 后才 verify
+  prompt: |
+    自己跑测试验证（不信任 surgeon 的报告）:
+    1. flutter test {{test_path}}/$ARGUMENTS/ （当前模块，无超时）
+    2. flutter test 核心模块（回归检查）
+    3. flutter analyze（编译检查）
+    
+    每个 acceptance criterion: VERIFIED / PARTIAL / MISSING
+    Verdict: PASS / FAIL
+```
+
+### surgeon 加约束（参考 OMC executor）
+
+```yaml
+surgeon:
+  instructions:
+    # 现有的保留，新增：
+    - 每次 fix 前先 `git diff` 确认上轮改动范围
+    - 每个文件改动后跑 `flutter analyze`
+    - 单轮最多改 5 个文件，超过说明范围太大需要拆分
+    - 同一问题失败 3 次 → 停止，报告卡点，不要无限重试
+    - commit message 必须包含：改了什么、为什么、对应哪个测试
+    - 不引入新抽象，不重构不相关代码
+```
+
+### investigator 加约束
+
+```yaml
+investigator:
+  instructions:
+    # 现有的保留，新增：
+    - 非首轮：先 review 上轮 git diff，判断方向是否正确
+    - 如果上轮 fix 没有让任何测试从 red→green，警告"无进展"
+    - 分类时标注严重度：CRITICAL（编译不过）> HIGH（逻辑错误）> LOW（widget 样式）
+```
+
+### 收敛保护
+
+```yaml
+rescue:
+  max_rounds: 10
+  convergence_rule: |
+    连续 2 轮无测试进展（green 数没增加）→ 停止
+    输出卡点分析 + 剩余问题清单
+  round_budget: |
+    每轮最多改 5 个文件
+    每轮必须让至少 1 个测试从 red/skip → green，否则视为无进展
+```
+
+### 完整 rescue workflow
+
+```yaml
+rescue:
+  name: Rescue
+  max_rounds: 10
+  steps:
+    - id: investigate
+      role: investigator
+      prompt: |
+        Round context:
+        - If round > 1: review previous round's git diff first
+        - If previous round had 0 progress: warn and consider changing approach
+        
+        Run tests, categorize by severity:
+        CRITICAL: compile errors, import failures
+        HIGH: logic test failures (state/notifier)
+        LOW: widget test failures (rendering/navigation)
+        
+        Pick highest severity batch. Trace v1 vs v2. Report breakpoints.
+
+    - id: fix
+      role: surgeon
+      depends_on: [investigate]
+      checkpoints:
+        - assert: clean_working_tree
+      prompt: |
+        Fix identified breakpoints. Rules:
+        - Read v1 intent, rewrite in v2 style (not copy v1 verbatim)
+        - Maximum 5 files per round
+        - flutter analyze after each file change
+        - Same issue failed 3 times → STOP, report as blocked
+        - Commit: rescue($ARGUMENTS): round N — what changed and why
+
+    - id: review
+      role: investigator
+      depends_on: [fix]
+      prompt: |
+        Review surgeon's git diff (read-only):
+        1. Changes minimal? No unnecessary files touched?
+        2. Matches v2 patterns (Riverpod, GoRouter)?
+        3. Mocks correct (not faked to pass)?
+        4. No new issues introduced?
+        Verdict: APPROVE → proceed to verify
+        Verdict: REQUEST_CHANGES → next round investigate includes review feedback
+
+    - id: verify
+      role: investigator
+      depends_on: [review]
+      prompt: |
+        Run independently (don't trust surgeon's results):
+        1. flutter test {{test_path}}/$ARGUMENTS/ (no timeout)
+        2. flutter analyze
+        3. Check: any regression in core tests?
+        Record delta vs last round. PASS or FAIL.
+
+    - id: report
+      role: investigator
+      depends_on: [verify]
+      prompt: |
+        Summary:
+        1. Test delta: +N green, -M red, ±K skipped
+        2. Remaining by category (logic vs widget vs platform)
+        3. Convergence: are we making progress?
+        4. If 2 rounds no progress → STOP, output blocked items
+        5. If all green → "Module $ARGUMENTS rescue complete"
+        6. Otherwise → "Run /rescue $ARGUMENTS to continue"
+```
+
+---
+
+## 三、全局规则（两个工作流共享）
+
+### DNA gene 层面
+
+```yaml
+genes:
+  # 现有 preserve_behavior 等保留，新增：
+  minimal_change:
+    description: Each fix should be the smallest possible change
+    codons:
+      - type: attract
+        target: single_file_change
+      - type: repel
+        target: unnecessary_refactoring
+      - type: threshold
+        condition: "files_changed_per_round <= 5"
+        action: escalate
+
+  evidence_based:
+    description: All completion claims require fresh test evidence
+    codons:
+      - type: attract
+        target: run_tests_before_claiming_done
+      - type: repel
+        target: trust_without_evidence
+```
+
+---
+
+## Acceptance Criteria
+
+### behavior-lock
+- [ ] 场景检测正确（首次 vs 重跑）
+- [ ] 首次: 只 analyze，不 test
+- [ ] 重跑: 增量更新测试，不全量重写
+- [ ] 重跑: 跑测试无超时
+- [ ] scanner 增量: 输出 diff 而非全量重写
+- [ ] 禁止 sleep 轮询模式
+
+### rescue
+- [ ] review 步骤: investigator 审查 surgeon 的 git diff
+- [ ] verify 步骤: 独立跑测试 + 回归检查
+- [ ] surgeon 约束: 最多 5 文件/轮，3 次失败停止
+- [ ] 收敛保护: 2 轮无进展 → 停止
+- [ ] 轮次上限: 最多 10 轮
+- [ ] report 包含收敛判断
+
+### 全局
+- [ ] minimal_change gene 编译到 IR
+- [ ] evidence_based gene 编译到 IR

package/spec/foundation-hardening.md

@@ -172,6 +172,6 @@ hook 报错时输出人类可读的提示而非 JSON。`dna verify` 输出友好
 - [x] 远程通信架构预留（接口定义，不实现）
 
 ### 第三阶段
-- [ ] dna sync 自动检测模板版本 + 提示升级
-- [ ] MCP server 常驻进程解决冷启动
-- [ ] 错误信息人类可读
+- [x] dna sync 自动检测模板版本 + 提示升级
+- [x] MCP server 常驻进程解决冷启动
+- [x] 错误信息人类可读