intentdna 1.4.9 → 1.5.2

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/dist/cli/commands/init.js

@@ -7,10 +7,12 @@ import { writeFile, readFile, readdir, mkdir, copyFile, access } from "node:fs/p
 import { resolve, dirname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseYAML } from "../../schema/yaml-parser.js";
+import { getPackageVersion, sanitizeTemplateName } from "../util/version.js";
 import { validateDNA } from "../../schema/validate.js";
 import { askString, askChoice, askNumber, askYesNo, closePrompt } from "../util/prompt.js";
 const TEMPLATES_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "templates");
 const PROJECT_TEMPLATES_DIR = ".dna/templates";
+const MULTI_CONFIG_DIR = ".dna/configs";
 async function dirExists(path) {
     try {
         await access(path);
@@ -63,18 +65,40 @@ async function listTemplates() {
     return results;
 }
 /**
- * Inject _source_template field after the `type:` line in YAML content.
+ * Inject _source_template and _template_version fields after the namespace/type line in YAML content.
  */
-function injectSourceTemplate(content, templateName) {
-    // Insert after the last top-level field before genes/contexts/roles/etc
+function injectSourceTemplate(content, templateName, version) {
     const marker = /^(namespace:\s*.+)$/m;
     const typeMarker = /^(type:\s*.+)$/m;
     const match = content.match(marker) || content.match(typeMarker);
+    const versionLine = version ? `\n_template_version: "${version}"` : "";
     if (match) {
-        return content.replace(match[0], `${match[0]}\n_source_template: ${templateName}`);
+        return content.replace(match[0], `${match[0]}\n_source_template: ${templateName}${versionLine}`);
+    }
+    return `_source_template: ${templateName}${versionLine}\n${content}`;
+}
+/**
+ * Check namespace collision against existing configs in .dna/configs/.
+ */
+async function checkNamespaceAgainstExisting(namespace, templateName) {
+    if (!namespace)
+        return;
+    try {
+        const files = await readdir(MULTI_CONFIG_DIR);
+        for (const f of files.filter(f => f.endsWith(".yaml") || f.endsWith(".yml"))) {
+            const content = await readFile(resolve(MULTI_CONFIG_DIR, f), "utf-8");
+            const data = parseYAML(content);
+            const existingNs = typeof data.namespace === "string" ? data.namespace : undefined;
+            if (existingNs === namespace && f !== `${templateName}.yaml`) {
+                throw new Error(`Namespace "${namespace}" conflict: already used by ${f}. Each template must have a unique namespace.`);
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.includes("conflict"))
+            throw err;
+        // Dir doesn't exist yet — no collision possible
     }
-    // Fallback: prepend
-    return `_source_template: ${templateName}\n${content}`;
 }
 /**
  * Infer template name from a DNA config's id field.
@@ -86,18 +110,31 @@ function inferTemplateName(id) {
     return id.slice("template_".length).replace(/_/g, "-");
 }
 /**
- * Auto-detect the DNA config file path.
+ * Auto-detect DNA config file(s) for upgrade.
+ * Priority: .dna/configs/*.yaml (multi-config) > legacy single-config
  */
-async function autoDetectConfig() {
+async function autoDetectConfigsForUpgrade() {
+    // Priority 1: .dna/configs/*.yaml (multi-config)
+    try {
+        const files = await readdir(MULTI_CONFIG_DIR);
+        const yamls = files
+            .filter(f => f.endsWith(".yaml") || f.endsWith(".yml"))
+            .sort()
+            .map(f => resolve(MULTI_CONFIG_DIR, f));
+        if (yamls.length > 0)
+            return yamls;
+    }
+    catch { /* dir doesn't exist */ }
+    // Fallback: legacy single-config paths
     const candidates = [
         ".dna/config.yaml", ".dna/config.yml", ".dna/config.json",
         ".dna.yaml", ".dna.yml", ".dna.json",
     ];
     for (const name of candidates) {
         if (await dirExists(name))
-            return name;
+            return [name];
     }
-    return null;
+    return [];
 }
 /**
  * Upgrade config from a newer template version while preserving user-filled variables.
@@ -127,8 +164,9 @@ async function upgradeConfig(configPath, templateName) {
     const srcDir = found.source === "project" ? PROJECT_TEMPLATES_DIR : TEMPLATES_DIR;
     const srcPath = resolve(srcDir, `${found.name}.dna.yaml`);
     let newContent = await readFile(srcPath, "utf-8");
-    // 4. Inject _source_template
-    newContent = injectSourceTemplate(newContent, found.name);
+    // 4. Inject _source_template and _template_version
+    const pkgVersion = await getPackageVersion();
+    newContent = injectSourceTemplate(newContent, found.name, pkgVersion ?? undefined);
     // 5. Replace VariableDef entries with user values where they exist
     for (const [key, value] of Object.entries(userVars)) {
         // Match multi-line VariableDef: "key:\n    description: ...\n    default: ..."
@@ -148,27 +186,52 @@ async function upgradeConfig(configPath, templateName) {
     return 0;
 }
 export async function runInit(opts) {
-    // Upgrade mode: update template while preserving user variables
+    // Upgrade mode: update template(s) while preserving user variables
     if (opts.upgrade !== undefined) {
-        const configPath = await autoDetectConfig();
-        if (!configPath) {
+        const configPaths = await autoDetectConfigsForUpgrade();
+        if (configPaths.length === 0) {
             process.stderr.write("No DNA config found. Run `dna init --template <name>` first.\n");
             return 2;
         }
-        let templateName = typeof opts.upgrade === "string" ? opts.upgrade : undefined;
-        // Auto-infer template name if not specified
-        if (!templateName) {
+        // If --upgrade <name> (non-empty string), find the specific config
+        if (typeof opts.upgrade === "string" && opts.upgrade.length > 0) {
+            // Sequential scan to find config by _source_template
+            let targetPath;
+            for (const p of configPaths) {
+                const content = await readFile(p, "utf-8");
+                const data = parseYAML(content);
+                if (data._source_template === opts.upgrade) {
+                    targetPath = p;
+                    break;
+                }
+            }
+            if (!targetPath) {
+                // Try direct template name match on filename
+                targetPath = configPaths.find(p => basename(p).replace(/\.(yaml|yml)$/, "") === opts.upgrade);
+            }
+            if (!targetPath) {
+                process.stderr.write(`Config for template "${opts.upgrade}" not found in: ${configPaths.map(p => basename(p)).join(", ")}\n`);
+                return 2;
+            }
+            return upgradeConfig(targetPath, opts.upgrade);
+        }
+        // --upgrade (no arg): upgrade all configs
+        let exitCode = 0;
+        for (const configPath of configPaths) {
             const content = await readFile(configPath, "utf-8");
             const data = parseYAML(content);
-            templateName = typeof data._source_template === "string"
+            let templateName = typeof data._source_template === "string"
                 ? data._source_template
                 : inferTemplateName(typeof data.id === "string" ? data.id : "") ?? undefined;
+            if (!templateName) {
+                process.stderr.write(`Cannot infer template for ${basename(configPath)}. Skipping.\n`);
+                continue;
+            }
+            const code = await upgradeConfig(configPath, templateName);
+            if (code !== 0)
+                exitCode = code;
         }
-        if (!templateName) {
-            process.stderr.write("Cannot infer template name. Specify it: dna init --upgrade <template-name>\n");
-            return 2;
-        }
-        return upgradeConfig(configPath, templateName);
+        return exitCode;
     }
     // Register mode: copy a template into .dna/templates/ with namespace uniqueness check
     if (opts.register) {
@@ -226,10 +289,17 @@ export async function runInit(opts) {
         const srcDir = found.source === "project" ? PROJECT_TEMPLATES_DIR : TEMPLATES_DIR;
         const srcPath = resolve(srcDir, `${found.name}.dna.yaml`);
         const content = await readFile(srcPath, "utf-8");
-        // Inject _source_template metadata for upgrade tracking
-        const contentWithSource = injectSourceTemplate(content, found.name);
-        const outPath = opts.output || ".dna/config.yaml";
-        // Ensure .dna/ directory exists
+        // Inject _source_template and _template_version metadata for upgrade tracking
+        const pkgVersion = await getPackageVersion();
+        const contentWithSource = injectSourceTemplate(content, found.name, pkgVersion ?? undefined);
+        // Check namespace collision against existing configs
+        const srcData = parseYAML(content);
+        const srcNs = typeof srcData.namespace === "string" ? srcData.namespace : undefined;
+        await checkNamespaceAgainstExisting(srcNs, found.name);
+        // Default output: .dna/configs/<template-name>.yaml (multi-config)
+        const safeName = sanitizeTemplateName(found.name);
+        const outPath = opts.output || resolve(MULTI_CONFIG_DIR, `${safeName}.yaml`);
+        // Ensure output directory exists
         const outDir = resolve(outPath, "..");
         await mkdir(outDir, { recursive: true });
         await writeFile(outPath, contentWithSource, "utf-8");

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

@@ -40,4 +40,18 @@ export interface SyncOptions {
  *   → ALSO write settings.json to register dna-hook events
  */
 export declare function detectMode(): Promise<"plugin" | "bin">;
+/**
+ * Auto-detect DNA configs: multi-config (.dna/configs/*.yaml) or legacy single-config.
+ * Returns array of absolute paths.
+ */
+export declare function autoDetectConfigs(): Promise<string[]>;
+/**
+ * Read the current package version from package.json.
+ */
+export { getPackageVersion } from "../util/version.js";
+/**
+ * Check for namespace collisions across multiple config files.
+ * Throws if two configs declare the same namespace.
+ */
+export declare function checkNamespaceCollisions(configPaths: string[]): Promise<void>;
 export declare function runSync(opts: SyncOptions): Promise<number>;

package/dist/cli/commands/sync.js

@@ -10,12 +10,14 @@
  *
  * Targets: claude-md, soul-md, cursorrules, system-prompt
  */
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, basename } from "node:path";
 import { readFile, writeFile as writeFileAsync, stat, mkdir, readdir, unlink, rm } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline";
 import { loadDNA, compileFromFiles } from "../../compiler/index.js";
+import { parseYAML } from "../../schema/yaml-parser.js";
+import { getPackageVersion } from "../util/version.js";
 import { compileToMarkdown, injectIntoFile, removeFromFile } from "../../runtime/markdown.js";
 import { compileAllRolesToAgentMD, writeAgentMDFiles, removeAgentMDFiles } from "../../runtime/agent-md.js";
 import { removeWorkflowScripts } from "../../runtime/workflow-runner.js";
@@ -181,7 +183,7 @@ async function resolveVariables(rawVars, configPath) {
     return resolved;
 }
 /**
- * Auto-detect DNA config file in current directory.
+ * Auto-detect DNA config file in current directory (legacy single-config).
  * Priority: .dna/config.yaml > .dna/config.yml > .dna/config.json > .dna.yaml > .dna.yml > .dna.json
  */
 async function autoDetectDNA() {
@@ -197,6 +199,83 @@ async function autoDetectDNA() {
     }
     return null;
 }
+/**
+ * Auto-detect DNA configs: multi-config (.dna/configs/*.yaml) or legacy single-config.
+ * Returns array of absolute paths.
+ */
+export async function autoDetectConfigs() {
+    const cwd = process.cwd();
+    // Priority 1: .dna/configs/*.yaml (multi-config)
+    const configsDir = resolve(cwd, ".dna", "configs");
+    try {
+        const files = await readdir(configsDir);
+        const yamls = files
+            .filter(f => f.endsWith(".yaml") || f.endsWith(".yml"))
+            .sort()
+            .map(f => resolve(configsDir, f));
+        if (yamls.length > 0)
+            return yamls;
+    }
+    catch { /* dir doesn't exist */ }
+    // Fallback: legacy single-config paths
+    const legacy = await autoDetectDNA();
+    if (legacy)
+        return [legacy];
+    return [];
+}
+/**
+ * Read the current package version from package.json.
+ */
+export { getPackageVersion } from "../util/version.js";
+/**
+ * Check for namespace collisions across multiple config files.
+ * Throws if two configs declare the same namespace.
+ */
+export async function checkNamespaceCollisions(configPaths) {
+    const namespaces = new Map();
+    for (const configPath of configPaths) {
+        try {
+            const content = await readFile(configPath, "utf-8");
+            const data = parseYAML(content);
+            const ns = typeof data.namespace === "string" ? data.namespace : undefined;
+            if (ns) {
+                const file = basename(configPath);
+                if (namespaces.has(ns)) {
+                    throw new Error(`Namespace "${ns}" conflict: ${namespaces.get(ns)} and ${file}. Each template must have a unique namespace.`);
+                }
+                namespaces.set(ns, file);
+            }
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.includes("conflict"))
+                throw err;
+            // Parse error — will be caught later during compilation
+        }
+    }
+}
+/**
+ * Check template versions against current package version.
+ * Prints upgrade suggestions for outdated configs.
+ */
+async function checkTemplateVersions(configPaths) {
+    const pkgVersion = await getPackageVersion();
+    if (!pkgVersion)
+        return;
+    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`);
+            }
+        }
+        catch {
+            // Non-critical — skip version check for unparseable files
+        }
+    }
+}
 function resolveSpeciesPath(ref) {
     if (!ref.startsWith("species:"))
         return null;
@@ -253,10 +332,21 @@ async function generateLockFile(lockPath, dnaSources, outputFiles) {
 export async function runSync(opts) {
     // ── Auto-detect mode: zero-config when no files/outputs specified ──
     if (!opts.remove && opts.files.length === 0) {
-        const autoFile = await autoDetectDNA();
-        if (autoFile) {
-            opts.files = [autoFile];
-            process.stderr.write(`Auto-detected: ${autoFile}\n`);
+        const autoFiles = await autoDetectConfigs();
+        if (autoFiles.length > 0) {
+            opts.files = autoFiles;
+            if (autoFiles.length === 1) {
+                process.stderr.write(`Auto-detected: ${autoFiles[0]}\n`);
+            }
+            else {
+                process.stderr.write(`Auto-detected: ${autoFiles.length} config(s) in .dna/configs/\n`);
+            }
+            // Namespace collision check (multi-config)
+            if (autoFiles.length > 1) {
+                await checkNamespaceCollisions(autoFiles);
+            }
+            // Template version check
+            await checkTemplateVersions(autoFiles);
         }
     }
     if (!opts.remove && !opts.inject && !opts.hooksDir && !opts.agentsDir && !opts.workflowDir && !opts.skillsDir && !opts.settingsPath) {
@@ -340,12 +430,15 @@ export async function runSync(opts) {
     try {
         // Track all output file paths for lock file generation
         const trackedOutputs = [];
+        // Step 0: Expand and pre-validate all DNA files before any work
+        // loadDNA() calls validateDNA() internally — validation failures throw here,
+        // before evolve/compile/inject waste any work.
+        const expandedFiles = await expandFiles(opts.files);
+        const loadedDNAs = await Promise.all(expandedFiles.map(loadDNA));
         // Step 1: Evolve if requested
         let epigeneticMarkers = undefined;
         if (opts.evolve) {
-            // Need to know the DNA ID for evolution
-            const expandedFiles = await expandFiles(opts.files);
-            const dnas = await Promise.all(expandedFiles.map(loadDNA));
+            const dnas = loadedDNAs;
             // Use the highest-priority DNA's ID
             const primaryDna = dnas.reduce((a, b) => a.cascade.priority >= b.cascade.priority ? a : b);
             const engine = new EvolutionEngine(opts.storeDir ? { store_dir: opts.storeDir } : undefined);
@@ -356,7 +449,6 @@ export async function runSync(opts) {
             }
         }
         // Step 2: Compile
-        const expandedFiles = await expandFiles(opts.files);
         const ir = await compileFromFiles(expandedFiles, {
             context: opts.context,
             role: opts.role,
@@ -378,7 +470,7 @@ export async function runSync(opts) {
         // Step 3.5: Write compiled IR (needed for both plugin and bin mode)
         {
             const cwd = process.cwd();
-            const dnas = await Promise.all(expandedFiles.map(loadDNA));
+            const dnas = loadedDNAs;
             const cascadedForIR = cascadeDNA(dnas);
             const roles = cascadedForIR.roles;
             const compiled = createCompiledIR(ir, roles);
@@ -413,7 +505,7 @@ export async function runSync(opts) {
             if (staleAgents.length > 0) {
                 process.stderr.write(`Cleaned ${staleAgents.length} stale agent file(s)\n`);
             }
-            const dnas = await Promise.all(expandedFiles.map(loadDNA));
+            const dnas = loadedDNAs;
             const cascaded = cascadeDNA(dnas);
             const roles = cascaded.roles;
             if (Object.keys(roles).length === 0) {
@@ -433,7 +525,7 @@ export async function runSync(opts) {
         }
         // Step 6: Generate workflow script(s)
         if (opts.workflowDir) {
-            const dnas = await Promise.all(expandedFiles.map(loadDNA));
+            const dnas = loadedDNAs;
             const cascadedForWf = cascadeDNA(dnas);
             const workflows = cascadedForWf.workflows;
             if (Object.keys(workflows).length === 0) {
@@ -474,7 +566,7 @@ export async function runSync(opts) {
             if (staleSkills.length > 0) {
                 process.stderr.write(`Cleaned ${staleSkills.length} stale skill dir(s)\n`);
             }
-            const dnas = await Promise.all(expandedFiles.map(loadDNA));
+            const dnas = loadedDNAs;
             const cascadedForSkills = cascadeDNA(dnas);
             const workflows = cascadedForSkills.workflows;
             const roles = cascadedForSkills.roles;
@@ -484,7 +576,7 @@ export async function runSync(opts) {
                 if (d.variables)
                     Object.assign(rawVars, d.variables);
             }
-            const configPath = await autoDetectDNA();
+            const configPath = opts.files.length === 1 ? opts.files[0] : null;
             const variables = await resolveVariables(rawVars, configPath);
             // Step 8: Generate .claude/.mcp.json from MCP dependencies (inside skillsDir block, shares variables)
             {

package/dist/cli/util/version.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared CLI utilities for package metadata.
+ */
+/**
+ * Read the current package version from package.json.
+ */
+export declare function getPackageVersion(): Promise<string | null>;
+/**
+ * Sanitize a template name to prevent path traversal.
+ * Strips path separators and parent directory references.
+ */
+export declare function sanitizeTemplateName(name: string): string;

package/dist/cli/util/version.js

@@ -0,0 +1,28 @@
+/**
+ * Shared CLI utilities for package metadata.
+ */
+import { readFile } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Read the current package version from package.json.
+ */
+export async function getPackageVersion() {
+    try {
+        const thisDir = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = resolve(thisDir, "..", "..", "..", "package.json");
+        const raw = await readFile(pkgPath, "utf-8");
+        const pkg = JSON.parse(raw);
+        return typeof pkg.version === "string" ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Sanitize a template name to prevent path traversal.
+ * Strips path separators and parent directory references.
+ */
+export function sanitizeTemplateName(name) {
+    return name.replace(/[/\\]/g, "").replace(/\.\./g, "");
+}

package/dist/compiler/cascade.d.ts

@@ -18,6 +18,8 @@ export interface CascadedDNA {
     workflows: Record<string, WorkflowDef>;
     epigenetic_markers: EpigeneticMarker[];
     source_ids: string[];
+    /** Warnings from cascade process (e.g., cross-namespace gene collisions) */
+    warnings?: string[];
 }
 /**
  * Cascade multiple DNA layers into a single merged DNA.

package/dist/compiler/cascade.js

@@ -98,21 +98,37 @@ export function cascadeDNA(layers) {
     // Sort by priority ascending (species first, task last)
     const sorted = [...layers].sort((a, b) => a.cascade.priority - b.cascade.priority);
     const mergedGenes = {};
+    const geneSourceNs = {}; // track which namespace defined each gene
     const mergedContexts = {};
     const mergedRoles = {};
     const mergedWorkflows = {};
     const allMarkers = [];
     const sourceIds = [];
+    const warnings = [];
     for (const dna of sorted) {
         sourceIds.push(dna.id);
         const ns = dna.namespace;
-        // Merge genes
+        // Merge genes (cross-namespace: additive merge + warning)
         for (const [name, gene] of Object.entries(dna.genes)) {
             if (mergedGenes[name]) {
-                mergedGenes[name] = mergeGenes(mergedGenes[name], gene);
+                const existingNs = geneSourceNs[name];
+                if (ns !== existingNs) {
+                    // Different namespaces define same gene — additive codon merge + warning
+                    mergedGenes[name] = {
+                        description: gene.description || mergedGenes[name].description,
+                        codons: [...mergedGenes[name].codons, ...gene.codons],
+                        tags: [...new Set([...(mergedGenes[name].tags ?? []), ...(gene.tags ?? [])])],
+                    };
+                    warnings.push(`Gene "${name}" defined in both ${existingNs ?? "(no namespace)"} and ${ns ?? "(no namespace)"}. Codons merged.`);
+                }
+                else {
+                    // Same namespace — normal cascade (higher priority wins)
+                    mergedGenes[name] = mergeGenes(mergedGenes[name], gene);
+                }
             }
             else {
                 mergedGenes[name] = { ...gene, codons: [...gene.codons] };
+                geneSourceNs[name] = ns;
             }
         }
         // Merge contexts (higher priority replaces entirely)
@@ -147,5 +163,6 @@ export function cascadeDNA(layers) {
         workflows: mergedWorkflows,
         epigenetic_markers: allMarkers,
         source_ids: sourceIds,
+        warnings: warnings.length > 0 ? warnings : undefined,
     };
 }

package/dist/hooks/cli.js

@@ -19,7 +19,7 @@ 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, extractBashWritePaths, } from "./enforce.js";
-import { appendAudit, readWorkflowState, appendTrace, rotateTraces, readTraces } from "./state.js";
+import { appendAudit, readWorkflowState, appendTrace, rotateTraces, readTraces, cleanStaleState } from "./state.js";
 // ── Constants ──────────────────────────────────────────────
 const DEFAULT_IR_PATH = ".dna/compiled/ir.json";
 const VALID_EVENTS = new Set([
@@ -127,7 +127,7 @@ async function main() {
         }, stopContext);
         // Session summary: aggregate block/warn stats from trace
         try {
-            const traces = await readTraces(projectDir, 1);
+            const traces = await readTraces(projectDir, 1, sessionId);
             const summary = computeSummary(traces);
             const summaryText = formatSummary(summary);
             if (summaryText) {
@@ -152,7 +152,7 @@ async function main() {
             decision: stopOutput.continue === false ? "block" : "allow",
             duration_ms: 0,
             timestamp: new Date().toISOString(),
-        }).catch(() => { });
+        }, sessionId).catch(() => { });
         return;
     }
     // Dispatch to enforcement engine with timing
@@ -171,7 +171,7 @@ async function main() {
     // 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 traces = await readTraces(projectDir, 1, sessionId);
             const blockCount = traces.filter(t => t.decision === "block" && t.target_path === targetPath).length;
             if (blockCount >= 2) {
                 output = {
@@ -200,10 +200,11 @@ async function main() {
         target_path: decision !== "allow" ? targetPath : undefined,
         duration_ms: durationMs,
         timestamp: new Date().toISOString(),
-    }).catch(() => { }); // Fail-open
-    // Side effect: rotate traces on SessionStart
+    }, sessionId).catch(() => { }); // Fail-open
+    // Side effect: rotate traces + clean stale state on SessionStart
     if (event === "SessionStart") {
         rotateTraces(projectDir).catch(() => { });
+        cleanStaleState(projectDir).catch(() => { });
     }
     // Side effect: audit log for notifications
     if (event === "Notification" && output.hookSpecificOutput?.additionalContext?.includes("violation")) {
@@ -267,12 +268,17 @@ function dispatch(event, ir, input, state) {
     }
 }
 // ── IR Loading ─────────────────────────────────────────────
+/** Expected IR schema version — must match plugin-adapter.ts */
+const EXPECTED_IR_VERSION = 1;
 async function loadIR(irPath) {
     try {
         const raw = await readFile(irPath, "utf-8");
         const data = JSON.parse(raw);
         // 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`);
+            }
             return data.ir;
         }
         // Direct ConstraintIR

package/dist/hooks/state.d.ts

@@ -62,6 +62,8 @@ export declare function appendCompletedArtifact(projectDir: string, stepId: stri
     type: string;
     path: string;
 }, sessionId?: string): Promise<void>;
+/** Atomic write: write to temp file then rename. */
+export declare function atomicWrite(filePath: string, data: string): Promise<void>;
 /** Trace entry for hook call observability */
 export interface TraceEntry {
     trace_id: string;
@@ -78,17 +80,27 @@ export interface TraceEntry {
 }
 /**
  * Append a trace entry to the daily trace file.
- * File: `.dna/state/trace/trace-YYYY-MM-DD.jsonl`
+ * With sessionId: `.dna/state/trace/trace-YYYY-MM-DD-{sessionId}.jsonl`
+ * Without: `.dna/state/trace/trace-YYYY-MM-DD.jsonl` (backward compat)
  * Fail-open: never throws.
  */
-export declare function appendTrace(projectDir: string, entry: TraceEntry): Promise<void>;
+export declare function appendTrace(projectDir: string, entry: TraceEntry, sessionId?: string): Promise<void>;
 /**
  * Read trace entries from the last N days.
+ * With sessionId: reads only that session's trace files.
+ * Without: reads all trace files (merged view).
  * Returns parsed entries sorted by timestamp.
  */
-export declare function readTraces(projectDir: string, days?: number): Promise<TraceEntry[]>;
+export declare function readTraces(projectDir: string, days?: number, sessionId?: string): Promise<TraceEntry[]>;
 /**
  * Clean up trace files older than retention period.
  * Removes `.dna/state/trace/trace-*.jsonl` files older than TRACE_RETENTION_DAYS.
  */
 export declare function rotateTraces(projectDir: string): Promise<number>;
+/**
+ * Clean up stale state from `.dna/state/sessions/` and root state.
+ * Removes workflow.json files older than DEFAULT_STALENESS_MS (2h).
+ * Called on SessionStart to prevent state accumulation.
+ * Fail-open: never throws.
+ */
+export declare function cleanStaleState(projectDir: string): Promise<number>;

package/dist/hooks/state.js

@@ -130,7 +130,7 @@ export async function appendCompletedArtifact(projectDir, stepId, artifact, sess
 }
 // ── Internal ───────────────────────────────────────────────
 /** Atomic write: write to temp file then rename. */
-async function atomicWrite(filePath, data) {
+export async function atomicWrite(filePath, data) {
     const tmpPath = filePath + ".tmp." + process.pid;
     await mkdir(dirname(filePath), { recursive: true });
     await writeFile(tmpPath, data, "utf-8");
@@ -139,17 +139,29 @@ async function atomicWrite(filePath, data) {
 const TRACE_DIR = "trace";
 const MAX_TRACE_SIZE = 10 * 1024 * 1024; // 10MB
 const TRACE_RETENTION_DAYS = 7;
+/**
+ * Build trace file name.
+ * With session isolation: `trace-{date}-{sessionId}.jsonl`
+ * Without: `trace-{date}.jsonl` (backward compat / merged view)
+ */
+function traceFileName(date, sessionId) {
+    if (sessionId) {
+        return `trace-${date}-${sessionId}.jsonl`;
+    }
+    return `trace-${date}.jsonl`;
+}
 /**
  * Append a trace entry to the daily trace file.
- * File: `.dna/state/trace/trace-YYYY-MM-DD.jsonl`
+ * With sessionId: `.dna/state/trace/trace-YYYY-MM-DD-{sessionId}.jsonl`
+ * Without: `.dna/state/trace/trace-YYYY-MM-DD.jsonl` (backward compat)
  * Fail-open: never throws.
  */
-export async function appendTrace(projectDir, entry) {
+export async function appendTrace(projectDir, entry, sessionId) {
     try {
         const traceDir = join(projectDir, ".dna", "state", TRACE_DIR);
         await mkdir(traceDir, { recursive: true });
         const date = entry.timestamp.slice(0, 10);
-        const tracePath = join(traceDir, `trace-${date}.jsonl`);
+        const tracePath = join(traceDir, traceFileName(date, sessionId));
         // Check file size — rotate if over limit
         try {
             const stats = await stat(tracePath);
@@ -165,9 +177,11 @@ export async function appendTrace(projectDir, entry) {
 }
 /**
  * Read trace entries from the last N days.
+ * With sessionId: reads only that session's trace files.
+ * Without: reads all trace files (merged view).
  * Returns parsed entries sorted by timestamp.
  */
-export async function readTraces(projectDir, days = 1) {
+export async function readTraces(projectDir, days = 1, sessionId) {
     const traceDir = join(projectDir, ".dna", "state", TRACE_DIR);
     const entries = [];
     const cutoff = new Date();
@@ -178,8 +192,16 @@ export async function readTraces(projectDir, days = 1) {
         const traceFiles = files
             .filter(f => f.startsWith("trace-") && f.endsWith(".jsonl"))
             .filter(f => {
-            const fileDate = f.slice(6, 16); // "trace-YYYY-MM-DD.jsonl" → "YYYY-MM-DD"
-            return fileDate >= cutoffDate;
+            // Extract date from filename: trace-YYYY-MM-DD.jsonl or trace-YYYY-MM-DD-{sessionId}.jsonl
+            const fileDate = f.slice(6, 16); // "trace-YYYY-MM-DD..."
+            if (fileDate < cutoffDate)
+                return false;
+            // Session filter: only include files for this session (or shared files)
+            if (sessionId) {
+                const suffix = f.slice(16); // "-{sessionId}.jsonl" or ".jsonl"
+                return suffix === `-${sessionId}.jsonl` || suffix === ".jsonl";
+            }
+            return true;
         })
             .sort();
         for (const file of traceFiles) {
@@ -226,3 +248,68 @@ export async function rotateTraces(projectDir) {
     }
     return removed;
 }
+// ── Stale State Cleanup ──────────────────────────────────
+/**
+ * Clean up stale state from `.dna/state/sessions/` and root state.
+ * Removes workflow.json files older than DEFAULT_STALENESS_MS (2h).
+ * Called on SessionStart to prevent state accumulation.
+ * Fail-open: never throws.
+ */
+export async function cleanStaleState(projectDir) {
+    let removed = 0;
+    const sessionsDir = join(projectDir, ".dna", "state", "sessions");
+    try {
+        const sessions = await readdir(sessionsDir);
+        for (const sessionDir of sessions) {
+            const wfPath = join(sessionsDir, sessionDir, WORKFLOW_FILE);
+            try {
+                const raw = await readFile(wfPath, "utf-8");
+                const state = JSON.parse(raw);
+                if (state.started_at) {
+                    const age = Date.now() - new Date(state.started_at).getTime();
+                    if (age > DEFAULT_STALENESS_MS) {
+                        // Remove stale session directory
+                        const { rm } = await import("node:fs/promises");
+                        await rm(join(sessionsDir, sessionDir), { recursive: true, force: true });
+                        removed++;
+                    }
+                }
+            }
+            catch {
+                // Malformed or missing workflow.json — clean up the directory
+                try {
+                    const dirStat = await stat(join(sessionsDir, sessionDir));
+                    if (dirStat.isDirectory()) {
+                        const dirAge = Date.now() - dirStat.mtimeMs;
+                        if (dirAge > DEFAULT_STALENESS_MS) {
+                            const { rm } = await import("node:fs/promises");
+                            await rm(join(sessionsDir, sessionDir), { recursive: true, force: true });
+                            removed++;
+                        }
+                    }
+                }
+                catch { /* skip */ }
+            }
+        }
+    }
+    catch {
+        // No sessions dir — nothing to clean
+    }
+    // Also clean root-level stale workflow state
+    const rootWfPath = join(projectDir, ".dna", "state", WORKFLOW_FILE);
+    try {
+        const raw = await readFile(rootWfPath, "utf-8");
+        const state = JSON.parse(raw);
+        if (state.started_at) {
+            const age = Date.now() - new Date(state.started_at).getTime();
+            if (age > DEFAULT_STALENESS_MS) {
+                await unlink(rootWfPath).catch(() => { });
+                removed++;
+            }
+        }
+    }
+    catch {
+        // No root workflow state
+    }
+    return removed;
+}

package/dist/runtime/plugin-adapter.js

@@ -6,8 +6,9 @@
  *
  * This is the bridge between compile-time (dna sync) and runtime (hook execution).
  */
-import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { readFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
+import { atomicWrite } from "../hooks/state.js";
 // ── Serialize ──────────────────────────────────────────────
 /**
  * Create a CompiledIRFile wrapper around a ConstraintIR.
@@ -30,7 +31,7 @@ export async function writeCompiledIR(projectDir, compiled) {
     const outputDir = join(projectDir, ".dna", "compiled");
     await mkdir(outputDir, { recursive: true });
     const outputPath = join(outputDir, "ir.json");
-    await writeFile(outputPath, JSON.stringify(compiled, null, 2) + "\n", "utf-8");
+    await atomicWrite(outputPath, JSON.stringify(compiled, null, 2) + "\n");
     return outputPath;
 }
 /**

package/dist/schema/validate.js

@@ -235,6 +235,16 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
         if (step.prompt !== undefined && (typeof step.prompt !== "string" || !step.prompt)) {
             errors.push({ path: `${stepPath}.prompt`, message: "prompt must be a non-empty string" });
         }
+        // isolation: must be a valid enum value
+        if (step.isolation !== undefined) {
+            const validIsolation = ["none", "worktree", "auto"];
+            if (!validIsolation.includes(step.isolation)) {
+                errors.push({
+                    path: `${stepPath}.isolation`,
+                    message: `must be one of: ${validIsolation.join(", ")}`,
+                });
+            }
+        }
         // checkpoints validation
         if (step.checkpoints) {
             if (!Array.isArray(step.checkpoints)) {
@@ -283,6 +293,26 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
             }
         }
     }
+    // Validate default_isolation
+    if (workflow.default_isolation !== undefined) {
+        const validIsolation = ["none", "worktree", "auto"];
+        if (!validIsolation.includes(workflow.default_isolation)) {
+            errors.push({
+                path: `${path}.default_isolation`,
+                message: `must be one of: ${validIsolation.join(", ")}`,
+            });
+        }
+    }
+    // Validate merge_strategy
+    if (workflow.merge_strategy !== undefined) {
+        const validStrategies = ["escalate"];
+        if (!validStrategies.includes(workflow.merge_strategy)) {
+            errors.push({
+                path: `${path}.merge_strategy`,
+                message: `must be one of: ${validStrategies.join(", ")}`,
+            });
+        }
+    }
     // Validate transitions
     const validConditions = ["pass", "fail", "always", "error"];
     for (let i = 0; i < (workflow.transitions?.length ?? 0); i++) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intentdna",
-  "version": "1.4.9",
+  "version": "1.5.2",
   "description": "Intent DNA — Declarative policy layer for AI agent behavior",
   "type": "module",
   "main": "dist/index.js",
@@ -10,7 +10,7 @@
     "dna-hook": "dist/hooks/cli.js"
   },
   "scripts": {
-    "build": "tsc && mkdir -p dist/species dist/templates && cp src/species/*.json dist/species/ && cp src/templates/*.yaml dist/templates/",
+    "build": "tsc && mkdir -p dist/species dist/templates && cp src/species/*.json dist/species/ && cp src/templates/*.yaml dist/templates/ && node scripts/sync-plugin-version.cjs",
     "dev": "tsc --watch",
     "test": "node --experimental-vm-modules node_modules/.bin/vitest run",
     "test:watch": "node --experimental-vm-modules node_modules/.bin/vitest"

package/spec/foundation-hardening.md

@@ -0,0 +1,177 @@
+# Spec: DNA 基础设施加固
+
+## Metadata
+- Interview: 5 rounds, final ambiguity 20%
+- Date: 2026-04-15
+- Status: 设计完成
+
+## Goal
+
+全面审视 DNA 基础设施的薄弱点，从可靠性 → 治理能力 → 工具体验三个维度加固，对标 OMC 补齐差距，为组织级治理奠基。
+
+## 成功标准
+
+- 零已知缺陷
+- 关键路径测试覆盖 >90%
+- 可交付给他人使用（不需要作者盯着）
+- 架构可扩展（后续治理功能不需要重构基础）
+
+## 优先级: 可靠性 → 治理能力 → 工具体验
+
+---
+
+## 第一阶段: 可靠性加固
+
+### R1: Config 编译前验证
+
+**问题**: `dna compile` 绕过 `validateDNA()`，无效 DNA 静默编译。
+
+**修复**: sync/compile 入口统一调用 `validateDNA()`，验证失败 → 报错退出。
+
+### R2: Trace 并发安全
+
+**问题**: 多 session 同时 `appendFile` 写 trace.jsonl，可能 corrupt。
+
+**修复**:
+- 方案 A: trace 文件按 session 隔离 → `trace-{date}-{sessionId}.jsonl`
+- 方案 B: 使用 `O_APPEND` 原子追加（POSIX 保证 ≤ PIPE_BUF 的 write 原子性）
+- 推荐 A（简单、和 OMC 一致）
+
+### R3: IR 版本迁移
+
+**问题**: `ir_version` 字段存在但无迁移逻辑。破坏性 IR 变更让旧 hook 静默失败。
+
+**修复**:
+- dna-hook 检测 `ir_version` 不匹配 → 输出明确错误 "IR version mismatch, run dna sync"
+- 保留 fail-open（不 block，但警告）
+
+### R4: 原子写入
+
+**问题**: state 写入使用普通 `writeFile`，进程中断可能 corrupt。
+
+**修复**: 参考 OMC 的 temp+rename 模式（state.ts 已有，确认所有写入路径都用）
+
+### R5: Stale 状态清理
+
+**问题**: 无超时机制，残留 state 文件永久存在。
+
+**修复**: 参考 OMC 的 2h stale 超时。SessionStart 时检查并清理过期 state。
+
+---
+
+## 第二阶段: 治理能力
+
+### G1: Session 隔离
+
+**问题**: `.dna/state/` 无 session 目录，多 session 状态冲突。
+
+**修复**: 
+```
+.dna/state/
+  sessions/
+    {sessionId}/
+      workflow.json
+      trace.jsonl        ← session 级 trace
+  trace/
+    trace-{date}.jsonl   ← 全局 trace（合并视图）
+```
+
+### G2: MCP Server — 状态管理工具
+
+DNA 的第一个 MCP server，提供：
+- `dna_state_read(mode)` — 读 workflow/enforce 状态
+- `dna_state_write(mode, data)` — 写状态
+- `dna_trace_query(filters)` — 查询 trace 数据
+- `dna_workflow_status()` — 当前 workflow 进度
+
+实现方式: 参考 OMC 的 `createSdkMcpServer()`，注册为 Claude Code plugin 的 MCP server。
+
+### G3: MCP Server — 编译工具链
+
+- `dna_compile(config_path)` — 编译 DNA 到 IR
+- `dna_sync()` — 一键同步（等同 CLI dna sync）
+- `dna_generate(description)` — 从描述生成 DNA
+
+让 LLM 直接操作 DNA，不需要 Bash 中转。
+
+### G4: 状态驱动 Enforce
+
+**问题**: enforce 只读静态 IR，不能根据 workflow 运行时状态调整。
+
+**修复**: enforce 接受 state 参数，支持条件规则：
+- "rescue 第 3 轮后放宽 scope"
+- "scan 步骤只读，fix 步骤可写"
+- 当前 WorkflowState 已传入 enforce，但只用于 checkpoint。扩展为通用条件。
+
+### G5: MCP Server — 远程治理通信（后续）
+
+- 上报审计数据到中央服务器
+- 拉取企业级 DNA 策略
+- 接收策略更新推送
+
+这是 Phase 7 的企业治理基础，当前只做架构预留。
+
+---
+
+## 第三阶段: 工具体验
+
+### U1: dna sync 自动检测升级
+
+sync 时对比 `_template_version`，有更新 → 提示升级。
+
+### U2: 冷启动优化
+
+**问题**: 每次 hook 调用 spawn Node.js ~50ms。
+
+**方案**:
+- 短期: IR 缓存到内存（MCP server 常驻进程时自然解决）
+- 长期: MCP server 内置 enforce，hook 调用走 MCP 而非 spawn
+
+### U3: 错误信息优化
+
+hook 报错时输出人类可读的提示而非 JSON。`dna verify` 输出友好的健康报告。
+
+---
+
+## 与 OMC 差距对标
+
+| 差距 | 对应任务 | 阶段 |
+|------|---------|------|
+| 无 session 隔离 | G1 | 二 |
+| 无 MCP 工具 | G2 + G3 | 二 |
+| 每次冷启动 | U2 | 三 |
+| 纯静态 enforce | G4 | 二 |
+| trace 并发 | R2 | 一 |
+| 无原子写入 | R4 | 一 |
+| 无 stale 清理 | R5 | 一 |
+
+## DNA 已有优势（保持）
+
+| 优势 | 不要丢 |
+|------|--------|
+| 纯函数 enforce | 不引入 I/O 到 enforce.ts |
+| 编译时 IR | 保持预编译模式，MCP 是补充不是替代 |
+| Fail-open | 所有错误 → allow |
+| 确定性 | 同 IR + 同 input = 同 output |
+
+## Acceptance Criteria
+
+### 第一阶段
+- [ ] dna compile/sync 编译前调用 validateDNA()
+- [ ] trace 写入 session 隔离或原子追加
+- [ ] IR 版本不匹配 → 明确警告
+- [ ] 所有 state 写入使用 temp+rename
+- [ ] SessionStart 清理 >2h stale state
+- [ ] 测试覆盖所有修复
+
+### 第二阶段
+- [ ] .dna/state/sessions/{id}/ 目录结构
+- [ ] MCP server 提供 state_read/write/trace_query
+- [ ] MCP server 提供 compile/sync/generate
+- [ ] enforce 支持 WorkflowState 条件规则
+- [ ] 远程通信架构预留（接口定义，不实现）
+
+### 第三阶段
+- [ ] dna sync 自动检测模板版本 + 提示升级
+- [ ] MCP server 常驻进程解决冷启动
+- [ ] 错误信息人类可读

package/spec/multi-config.md

@@ -0,0 +1,172 @@
+# Spec: Multi-Config 模板管理
+
+## Metadata
+- Date: 2026-04-15
+- Phase: 6 (持续改进 C2/C3)
+- Status: 设计完成，待实现
+
+## Goal
+
+支持一个项目同时使用多个 DNA 模板，每个模板有独立的 namespace、roles、workflows。统一编译到一个 IR，运行时透明。
+
+## 目录结构
+
+```
+.dna/
+  configs/                     # 多模板配置目录
+    flutter-rewrite.yaml       # namespace: frw
+    secure-dev.yaml            # namespace: sec
+    code-review.yaml           # namespace: cr
+  compiled/
+    ir.json                    # 合并后的单一 IR
+  state/
+    trace/
+  lock                         # 追踪所有 configs 的 hash
+```
+
+## 核心设计决策
+
+| 决策 | 结论 | 理由 |
+|------|------|------|
+| 目录结构 | `.dna/configs/*.yaml` | 独立目录，清晰分离 |
+| IR 输出 | 合并为单一 ir.json | hooks 只读一个 IR，运行时透明 |
+| Namespace 冲突 | 编译时报错 | 一个 namespace 只属于一个模板，静默覆盖 = 数据丢失 |
+| Gene 冲突 | 合并 codons + 警告 | gene 是项目级共享概念，additive 合并最合理 |
+| 向后兼容 | 暂不考虑 | 新项目直接用 configs/，老项目手动迁移 |
+| 性能 | 无影响 | YAML parse 5 个文件 ~25ms，ir.json KB 级，hook 运行时无差异 |
+
+## Namespace 冲突处理
+
+编译时扫描 `configs/*.yaml`，检测 namespace 重复：
+
+```typescript
+// sync.ts
+const namespaces = new Map<string, string>(); // namespace → filename
+for (const config of configs) {
+  if (namespaces.has(config.namespace)) {
+    throw new Error(
+      `Namespace "${config.namespace}" conflict: ` +
+      `${namespaces.get(config.namespace)} and ${config.filename}. ` +
+      `Each template must have a unique namespace.`
+    );
+  }
+  namespaces.set(config.namespace, config.filename);
+}
+```
+
+## Gene 冲突处理
+
+同名 gene 来自不同模板时，合并 codons 并输出警告：
+
+```typescript
+// cascade.ts
+if (mergedGenes[geneName] && sourceNamespace !== existingNamespace) {
+  // Different templates define same gene — merge codons
+  mergedGenes[geneName].codons.push(...gene.codons);
+  warnings.push(
+    `Gene "${geneName}" defined in both ${existingNamespace} and ${sourceNamespace}. ` +
+    `Codons merged. Verify this is intentional.`
+  );
+} else {
+  // Same namespace or new gene — normal cascade (higher priority wins)
+  mergedGenes[geneName] = gene;
+}
+```
+
+## 模板版本追踪
+
+每个 config 文件增加 `_template_version` 字段：
+
+```yaml
+_source_template: flutter-rewrite
+_template_version: "1.4.9"      # npm 包版本时写入
+```
+
+`dna sync` 时对比：
+1. 读每个 config 的 `_source_template` + `_template_version`
+2. 查 npm 包里对应模板的当前版本
+3. 版本不一致 → 提示 "flutter-rewrite 有新版本 (1.4.9 → 1.5.0)，是否升级？(Y/n)"
+4. 确认 → `upgradeConfig()` 全量替换 + 回写 variables
+
+## dna sync 流程变化
+
+```
+当前:
+  autoDetectDNA() → 找 .dna/config.yaml → 读一个文件 → 编译
+
+新:
+  autoDetectConfigs() → 扫描 .dna/configs/*.yaml
+    → 读所有文件
+    → 检测 namespace 冲突（报错）
+    → 检测 gene 冲突（合并 + 警告）
+    → 检测模板版本（提示升级）
+    → cascadeDNA(all) → 合并为一个 IR
+    → 生成全部产物
+```
+
+## dna init 流程变化
+
+```
+当前:
+  dna init --template flutter-rewrite
+    → 写 .dna/config.yaml
+
+新:
+  dna init --template flutter-rewrite
+    → mkdir -p .dna/configs/
+    → 写 .dna/configs/flutter-rewrite.yaml
+
+  dna init --template secure-dev    (追加第二个模板)
+    → 检测 namespace 冲突
+    → 写 .dna/configs/secure-dev.yaml
+```
+
+## dna init --upgrade 流程变化
+
+```
+当前:
+  读 .dna/config.yaml → 升级一个
+
+新:
+  dna init --upgrade                  (升级所有)
+    → 扫描 configs/*.yaml
+    → 逐个检测版本，逐个升级
+
+  dna init --upgrade flutter-rewrite  (升级指定)
+    → 只升级 configs/flutter-rewrite.yaml
+```
+
+## 对现有功能的影响
+
+| 功能 | 改动 |
+|------|------|
+| **autoDetectDNA()** | 改为 `autoDetectConfigs()`，扫描 `configs/*.yaml` |
+| **cascadeDNA()** | 无改动（已支持多 DNA 输入） |
+| **ir.json** | 内容更大（更多 roles/workflows），格式不变 |
+| **hooks (dna-hook)** | 无改动（只读 ir.json） |
+| **agents/*.md** | 无改动（namespace 前缀天然隔离） |
+| **skills/*.md** | 无改动（namespace 前缀天然隔离） |
+| **settings.json** | 无改动（hook 注册逻辑不变） |
+| **CLAUDE.md** | 所有模板的 directives 合并注入 |
+| **lock 文件** | 追踪所有 configs/*.yaml 的 hash |
+| **dna init** | 写到 `configs/` 目录 |
+| **dna init --upgrade** | 支持全量升级和指定升级 |
+
+## 不做
+
+- 向后兼容自动迁移（老项目手动 `mv config.yaml configs/`）
+- config 间的 gene 优先级控制（MVP 用合并 + 警告）
+- 运行时动态加载 config（全部编译时处理）
+
+## Acceptance Criteria
+
+- [ ] `dna init --template X` 写到 `.dna/configs/X.yaml`
+- [ ] `dna sync` 自动扫描 `configs/*.yaml`
+- [ ] namespace 重复 → 编译报错
+- [ ] 同名 gene 不同模板 → codons 合并 + 警告
+- [ ] `_template_version` 写入 config，sync 时对比提示升级
+- [ ] `dna init --upgrade` 支持全量和指定模板
+- [ ] 多模板编译为单一 ir.json
+- [ ] agents/skills 文件 namespace 隔离正确
+- [ ] lock 文件追踪所有 configs
+- [ ] 测试覆盖：namespace 冲突、gene 合并、多模板编译、升级流程