intentdna 1.4.8 → 1.5.1

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/runtime/workflow-runner.js

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

package/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.8",
+  "version": "1.5.1",
   "description": "Intent DNA — Declarative policy layer for AI agent behavior",
   "type": "module",
   "main": "dist/index.js",

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 合并、多模板编译、升级流程