intentdna 1.5.13 → 1.5.14

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

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

@@ -11,4 +11,8 @@ export interface InitOptions {
     register?: string;
     upgrade?: string | boolean;
 }
+/**
+ * Calculate SHA256 hash of template content (truncated to 16 hex chars).
+ */
+export declare function calculateTemplateHash(content: string): string;
 export declare function runInit(opts: InitOptions): Promise<number>;

package/dist/cli/commands/init.js

@@ -6,8 +6,9 @@
 import { writeFile, readFile, readdir, mkdir, copyFile, access } from "node:fs/promises";
 import { resolve, dirname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
 import { parseYAML } from "../../schema/yaml-parser.js";
-import { getPackageVersion, sanitizeTemplateName } from "../util/version.js";
+import { 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");
@@ -65,17 +66,24 @@ async function listTemplates() {
     return results;
 }
 /**
- * Inject _source_template and _template_version fields after the namespace/type line in YAML content.
+ * Calculate SHA256 hash of template content (truncated to 16 hex chars).
  */
-function injectSourceTemplate(content, templateName, version) {
+export function calculateTemplateHash(content) {
+    return createHash("sha256").update(content, "utf-8").digest("hex").slice(0, 16);
+}
+/**
+ * Inject _source_template, _template_version, and _template_content_hash fields after the namespace/type line in YAML content.
+ */
+function injectSourceTemplate(content, templateName, templateVersion, templateHash) {
     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}"` : "";
+    const versionLine = templateVersion ? `\n_template_version: "${templateVersion}"` : "";
+    const hashLine = templateHash ? `\n_template_content_hash: "${templateHash}"` : "";
     if (match) {
-        return content.replace(match[0], `${match[0]}\n_source_template: ${templateName}${versionLine}`);
+        return content.replace(match[0], `${match[0]}\n_source_template: ${templateName}${versionLine}${hashLine}`);
     }
-    return `_source_template: ${templateName}${versionLine}\n${content}`;
+    return `_source_template: ${templateName}${versionLine}${hashLine}\n${content}`;
 }
 /**
  * Check namespace collision against existing configs in .dna/configs/.
@@ -164,9 +172,11 @@ 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 and _template_version
-    const pkgVersion = await getPackageVersion();
-    newContent = injectSourceTemplate(newContent, found.name, pkgVersion ?? undefined);
+    // 4. Inject _source_template, _template_version, and _template_content_hash
+    const templateData = parseYAML(newContent);
+    const templateVersion = typeof templateData.version === "string" ? templateData.version : undefined;
+    const templateHash = calculateTemplateHash(newContent);
+    newContent = injectSourceTemplate(newContent, found.name, templateVersion, templateHash);
     // 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: ..."
@@ -290,8 +300,11 @@ export async function runInit(opts) {
         const srcPath = resolve(srcDir, `${found.name}.dna.yaml`);
         const content = await readFile(srcPath, "utf-8");
         // Inject _source_template and _template_version metadata for upgrade tracking
-        const pkgVersion = await getPackageVersion();
-        const contentWithSource = injectSourceTemplate(content, found.name, pkgVersion ?? undefined);
+        // Inject _source_template, _template_version, and _template_content_hash for upgrade tracking
+        const templateData = parseYAML(content);
+        const templateVersion = typeof templateData.version === "string" ? templateData.version : undefined;
+        const templateHash = calculateTemplateHash(content);
+        const contentWithSource = injectSourceTemplate(content, found.name, templateVersion, templateHash);
         // Check namespace collision against existing configs
         const srcData = parseYAML(content);
         const srcNs = typeof srcData.namespace === "string" ? srcData.namespace : undefined;

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

@@ -40,6 +40,12 @@ export interface SyncOptions {
  *   → ALSO write settings.json to register dna-hook events
  */
 export declare function detectMode(): Promise<"plugin" | "bin">;
+/**
+ * Remove stale DNA-managed files from a directory.
+ * Only removes files matching activeNamespaces (dna-{ns}-*).
+ * Returns list of removed paths.
+ */
+export declare function cleanStaleDNAFiles(dir: string, type: "agents" | "skills", activeNamespaces: string[]): Promise<string[]>;
 /**
  * Auto-detect DNA configs: multi-config (.dna/configs/*.yaml) or legacy single-config.
  * Returns array of absolute paths.
@@ -70,11 +76,10 @@ export interface TemplateUpgradeInfo {
     availableVersion: string;
 }
 /**
- * Check template versions against current package version.
- * Returns upgrade info for outdated configs and prints human-readable suggestions.
+ * Check template versions against current template content hashes.
+ * Returns upgrade info for changed 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).
+ * Uses content hash comparison instead of semver — detects any template content change.
  */
 export declare function checkTemplateVersions(configPaths: string[]): Promise<TemplateUpgradeInfo[]>;
 export declare function runSync(opts: SyncOptions): Promise<number>;

package/dist/cli/commands/sync.js

@@ -17,7 +17,6 @@ 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";
@@ -72,6 +71,32 @@ const LEGACY_BASH_HOOKS = [
     "dna-pre-compact.sh",
     "dna-notification.sh",
 ];
+const TEMPLATES_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "templates");
+function calculateTemplateHash(content) {
+    return createHash("sha256").update(content, "utf-8").digest("hex").slice(0, 16);
+}
+async function findTemplateFile(templateName) {
+    // Try direct filename match first
+    const directPath = resolve(TEMPLATES_DIR, `${templateName}.dna.yaml`);
+    if (await fileExists(directPath))
+        return directPath;
+    // Fallback: search by id or name field
+    try {
+        const files = await readdir(TEMPLATES_DIR);
+        for (const file of files) {
+            if (!file.endsWith(".dna.yaml") && !file.endsWith(".dna.yml"))
+                continue;
+            const fullPath = resolve(TEMPLATES_DIR, file);
+            const content = await readFile(fullPath, "utf-8");
+            const data = parseYAML(content);
+            if (data.id === templateName || data.name === templateName) {
+                return fullPath;
+            }
+        }
+    }
+    catch { /* fail-open */ }
+    return null;
+}
 /**
  * Remove legacy bash hook scripts written by previous Intent DNA versions.
  * Only removes files that contain the sentinel comment.
@@ -93,15 +118,22 @@ async function removeLegacyBashHooks(hooksDir) {
 }
 /**
  * Remove stale DNA-managed files from a directory.
- * Scans for files/dirs containing the sentinel marker and deletes them.
+ * Only removes files matching activeNamespaces (dna-{ns}-*).
  * Returns list of removed paths.
  */
-async function cleanStaleDNAFiles(dir, type) {
+export async function cleanStaleDNAFiles(dir, type, activeNamespaces) {
     const removed = [];
     try {
         const entries = await readdir(dir, { withFileTypes: true });
         for (const entry of entries) {
             const fullPath = resolve(dir, entry.name);
+            // Extract namespace from filename: dna-{namespace}-*
+            const nsMatch = entry.name.match(/^dna-([a-z0-9_-]+)-/);
+            const fileNamespace = nsMatch ? nsMatch[1] : null;
+            // Skip if namespace doesn't match active namespaces
+            if (!fileNamespace || !activeNamespaces.includes(fileNamespace)) {
+                continue;
+            }
             if (type === "agents" && entry.isFile() && entry.name.endsWith(".md")) {
                 const content = await readFile(fullPath, "utf-8").catch(() => "");
                 if (content.includes(DNA_SENTINEL)) {
@@ -276,42 +308,44 @@ export function compareSemver(a, b) {
     return 0;
 }
 /**
- * Check template versions against current package version.
- * Returns upgrade info for outdated configs and prints human-readable suggestions.
+ * Check template versions against current template content hashes.
+ * Returns upgrade info for changed 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).
+ * Uses content hash comparison instead of semver — detects any template content change.
  */
 export async function checkTemplateVersions(configPaths) {
-    const pkgVersion = await getPackageVersion();
-    if (!pkgVersion)
-        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 (tmplName && !tmplVersion) {
-                // Old config without version tracking — suggest upgrade
+            const tmplHash = typeof data._template_content_hash === "string" ? data._template_content_hash : undefined;
+            const tmplVersion = typeof data._template_version === "string" ? data._template_version : undefined;
+            if (!tmplName)
+                continue;
+            const templatePath = await findTemplateFile(tmplName);
+            if (!templatePath)
+                continue;
+            const currentTemplateContent = await readFile(templatePath, "utf-8");
+            const currentHash = calculateTemplateHash(currentTemplateContent);
+            if (!tmplHash) {
                 upgrades.push({
                     configPath,
                     templateName: tmplName,
-                    currentVersion: "unknown",
-                    availableVersion: pkgVersion,
+                    currentVersion: tmplVersion ?? "unknown",
+                    availableVersion: "content-changed",
                 });
-                process.stderr.write(`Upgrade available: "${tmplName}" has no version tag. Run: dna init --upgrade ${tmplName}\n`);
+                process.stderr.write(`Upgrade available: "${tmplName}" has no content hash. Run: dna init --upgrade ${tmplName}\n`);
             }
-            else if (tmplVersion && tmplName && compareSemver(pkgVersion, tmplVersion) > 0) {
-                // Package is strictly newer than template — suggest upgrade
+            else if (currentHash !== tmplHash) {
                 upgrades.push({
                     configPath,
                     templateName: tmplName,
-                    currentVersion: tmplVersion,
-                    availableVersion: pkgVersion,
+                    currentVersion: tmplVersion ?? "unknown",
+                    availableVersion: "content-changed",
                 });
-                process.stderr.write(`Upgrade available: "${tmplName}" ${tmplVersion} → ${pkgVersion}. Run: dna init --upgrade ${tmplName}\n`);
+                process.stderr.write(`Template content changed: "${tmplName}". Run: dna init --upgrade ${tmplName}\n`);
             }
         }
         catch {
@@ -544,10 +578,14 @@ export async function runSync(opts) {
         else if (opts.plugin && opts.settingsPath) {
             process.stderr.write(`Plugin mode: hooks managed by plugin framework (skipping settings.json)\n`);
         }
+        // Extract active namespaces from loaded DNAs for namespace-scoped cleanup
+        const activeNamespaces = loadedDNAs
+            .map(d => d.namespace)
+            .filter((ns) => typeof ns === "string");
         // Step 5: Generate agent MD files
         if (opts.agentsDir) {
             // Clean stale DNA-managed agents before regenerating
-            const staleAgents = await cleanStaleDNAFiles(opts.agentsDir, "agents");
+            const staleAgents = await cleanStaleDNAFiles(opts.agentsDir, "agents", activeNamespaces);
             if (staleAgents.length > 0) {
                 process.stderr.write(`Cleaned ${staleAgents.length} stale agent file(s)\n`);
             }
@@ -608,7 +646,7 @@ export async function runSync(opts) {
         // Step 7: Generate skill files from workflows
         if (opts.skillsDir) {
             // Clean stale DNA-managed skills before regenerating
-            const staleSkills = await cleanStaleDNAFiles(opts.skillsDir, "skills");
+            const staleSkills = await cleanStaleDNAFiles(opts.skillsDir, "skills", activeNamespaces);
             if (staleSkills.length > 0) {
                 process.stderr.write(`Cleaned ${staleSkills.length} stale skill dir(s)\n`);
             }

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

@@ -324,6 +324,10 @@ workflows:
           - 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
+
+          Report results and STOP.
+
+          Next step for user: Run /dna-frw-diagnosis $ARGUMENTS to analyze failing tests.
         handoff:
           consumes:
             - type: file

package/package.json

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

package/spec/template-version-namespace-fix.md

@@ -0,0 +1,653 @@
+# Template Version + Namespace Cleanup Fix
+
+## Metadata
+- Generated: 2026-04-19
+- Status: APPROVED
+- 预计工期: 2-3 小时
+- 发版类型: patch
+
+## 背景
+
+两个独立 bug 需要一起修：
+
+### Bug 1: _template_version 跟 package 版本走
+**问题**: 改了 flutter-rewrite 模板 → 发版 1.5.13 → 所有模板的 _template_version 都变成 1.5.13，但只有 flutter-rewrite 真正改了内容。
+
+**根因**: `injectSourceTemplate()` 用 `getPackageVersion()` 而不是模板自身的 `version` 字段。
+
+### Bug 2: cleanStaleDNAFiles 不区分 namespace
+**问题**: 项目用 frw + be 两个模板，`dna sync frw` 会把 be 的 agent/skill 也删掉。
+
+**根因**: `cleanStaleDNAFiles()` 只看 `intentdna:managed` 标记，不看 namespace。
+
+---
+
+## 方案
+
+### 方案 A: Template Content Hash Tracking
+
+每个模板用 content hash 追踪版本，不依赖手动 bump version 字段。
+
+**流程**：
+1. `dna init <template>` 时：
+   - 计算模板文件内容的 SHA256 hash
+   - 写入项目 config: `_template_content_hash: "abc123..."`
+   - 保留 `_template_version` 字段（从模板的 `version` 读取，不是 pkg 版本）
+
+2. `dna sync` 时：
+   - 读当前模板文件，计算 hash
+   - 对比项目 config 的 `_template_content_hash`
+   - 不同 → 提示 "Template content changed. Run: dna init --upgrade <template>"
+
+3. `dna init --upgrade <template>` 时：
+   - 更新 `_template_content_hash` 为新 hash
+   - 更新 `_template_version` 为模板的 `version` 字段
+
+**优点**：
+- 不依赖手动 bump version
+- 任何模板内容变化都能检测到
+- 不同模板独立追踪
+
+**缺点**：
+- 用户手动改了项目 config（加自定义 gene）也会触发"模板变化"提示
+- 需要明确告知用户：项目 config 是"模板实例"，改动后不再追踪上游模板更新
+
+### 方案 B: Namespace-aware Cleanup
+
+`cleanStaleDNAFiles()` 只删当前 sync 的 namespace 对应的文件。
+
+**实现**：
+```typescript
+// 当前
+async function cleanStaleDNAFiles(dir: string, type: "agent" | "skill"): Promise<number>
+
+// 修改后
+async function cleanStaleDNAFiles(
+  dir: string,
+  type: "agent" | "skill",
+  activeNamespaces: string[]  // 当前 sync 的模板的 namespace 列表
+): Promise<number>
+```
+
+**逻辑**：
+1. 扫描 `.claude/agents/` 或 `.claude/skills/`
+2. 对每个文件/目录：
+   - 读内容检查 `intentdna:managed` 标记
+   - 如果有标记 → 提取文件名前缀（`dna-frw-*` → `frw`）
+   - 如果前缀在 `activeNamespaces` 中 → 删除
+   - 否则保留
+
+**文件名规则**：
+- Agent MD: `dna-{namespace}-{role}.md`
+- Skill dir: `dna-{namespace}-{workflow}/`
+
+**边界情况**：
+- 文件名不符合 `dna-{ns}-*` 格式 → 保留（可能是用户手写的）
+- 没有 `intentdna:managed` 标记 → 保留
+- namespace 不在 activeNamespaces → 保留
+
+---
+
+## 实施步骤
+
+### Step 1: Template Content Hash (Bug 1)
+
+#### 1.1 新增 hash 计算函数
+
+文件：`src/cli/commands/init.ts`
+
+```typescript
+import { createHash } from "crypto";
+
+/**
+ * Calculate SHA256 hash of template content.
+ * Used for tracking template changes independent of version field.
+ */
+function calculateTemplateHash(content: string): string {
+  return createHash("sha256").update(content, "utf-8").digest("hex").slice(0, 16);
+}
+```
+
+#### 1.2 修改 injectSourceTemplate
+
+文件：`src/cli/commands/init.ts:91-100`
+
+```typescript
+// 之前
+function injectSourceTemplate(content: string, templateName: string, version?: string): string {
+  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}${versionLine}`);
+  }
+  return `_source_template: ${templateName}${versionLine}\n${content}`;
+}
+
+// 之后
+function injectSourceTemplate(
+  content: string,
+  templateName: string,
+  templateVersion?: string,
+  templateHash?: string
+): string {
+  const marker = /^(namespace:\s*.+)$/m;
+  const typeMarker = /^(type:\s*.+)$/m;
+  const match = content.match(marker) || content.match(typeMarker);
+  
+  const versionLine = templateVersion ? `\n_template_version: "${templateVersion}"` : "";
+  const hashLine = templateHash ? `\n_template_content_hash: "${templateHash}"` : "";
+  const metadata = `\n_source_template: ${templateName}${versionLine}${hashLine}`;
+  
+  if (match) {
+    return content.replace(match[0], `${match[0]}${metadata}`);
+  }
+  return `_source_template: ${templateName}${versionLine}${hashLine}\n${content}`;
+}
+```
+
+#### 1.3 修改 init 命令调用点
+
+文件：`src/cli/commands/init.ts`
+
+找到两处 `injectSourceTemplate()` 调用：
+
+**调用点 1（约 194 行，--upgrade 路径）**：
+```typescript
+// 之前
+const pkgVersion = await getPackageVersion();
+newContent = injectSourceTemplate(newContent, found.name, pkgVersion ?? undefined);
+
+// 之后
+const templateData = parseYAML(newContent) as Record<string, unknown>;
+const templateVersion = typeof templateData.version === "string" ? templateData.version : undefined;
+const templateHash = calculateTemplateHash(newContent);
+newContent = injectSourceTemplate(newContent, found.name, templateVersion, templateHash);
+```
+
+**调用点 2（约 340 行，新建路径）**：
+```typescript
+// 之前
+const pkgVersion = await getPackageVersion();
+const contentWithSource = injectSourceTemplate(content, found.name, pkgVersion ?? undefined);
+
+// 之后
+const templateData = parseYAML(content) as Record<string, unknown>;
+const templateVersion = typeof templateData.version === "string" ? templateData.version : undefined;
+const templateHash = calculateTemplateHash(content);
+const contentWithSource = injectSourceTemplate(content, found.name, templateVersion, templateHash);
+```
+
+#### 1.4 修改 checkTemplateVersions
+
+文件：`src/cli/commands/sync.ts:334-370`
+
+```typescript
+// 之前
+export async function checkTemplateVersions(configPaths: string[]): Promise<TemplateUpgradeInfo[]> {
+  const pkgVersion = await getPackageVersion();
+  if (!pkgVersion) return [];
+
+  const upgrades: TemplateUpgradeInfo[] = [];
+
+  for (const configPath of configPaths) {
+    try {
+      const content = await readFile(configPath, "utf-8");
+      const data = parseYAML(content) as Record<string, unknown>;
+      const tmplVersion = typeof data._template_version === "string" ? data._template_version : undefined;
+      const tmplName = typeof data._source_template === "string" ? data._source_template : undefined;
+
+      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 {
+      // Fail-open
+    }
+  }
+
+  return upgrades;
+}
+
+// 之后
+export async function checkTemplateVersions(configPaths: string[]): Promise<TemplateUpgradeInfo[]> {
+  const upgrades: TemplateUpgradeInfo[] = [];
+
+  for (const configPath of configPaths) {
+    try {
+      const content = await readFile(configPath, "utf-8");
+      const data = parseYAML(content) as Record<string, unknown>;
+      const tmplName = typeof data._source_template === "string" ? data._source_template : undefined;
+      const tmplHash = typeof data._template_content_hash === "string" ? data._template_content_hash : undefined;
+      const tmplVersion = typeof data._template_version === "string" ? data._template_version : undefined;
+
+      if (!tmplName) continue;
+
+      // Find current template file
+      const templatePath = await findTemplateFile(tmplName);
+      if (!templatePath) continue;
+
+      const currentTemplateContent = await readFile(templatePath, "utf-8");
+      const currentHash = calculateTemplateHash(currentTemplateContent);
+
+      if (!tmplHash) {
+        // Old config without hash tracking — suggest upgrade
+        upgrades.push({
+          configPath,
+          templateName: tmplName,
+          currentVersion: tmplVersion ?? "unknown",
+          availableVersion: "content-changed",
+        });
+        process.stderr.write(
+          `Upgrade available: "${tmplName}" has no content hash. Run: dna init --upgrade ${tmplName}\n`,
+        );
+      } else if (currentHash !== tmplHash) {
+        // Template content changed
+        upgrades.push({
+          configPath,
+          templateName: tmplName,
+          currentVersion: tmplVersion ?? "unknown",
+          availableVersion: "content-changed",
+        });
+        process.stderr.write(
+          `Template content changed: "${tmplName}". Run: dna init --upgrade ${tmplName}\n`,
+        );
+      }
+    } catch {
+      // Fail-open
+    }
+  }
+
+  return upgrades;
+}
+
+/**
+ * Find template file path by template name.
+ * Searches in src/templates/ directory.
+ */
+async function findTemplateFile(templateName: string): Promise<string | null> {
+  const templatesDir = resolve(__dirname, "..", "..", "templates");
+  try {
+    const files = await readdir(templatesDir);
+    for (const file of files) {
+      if (file.endsWith(".dna.yaml") || file.endsWith(".dna.yml")) {
+        const fullPath = resolve(templatesDir, file);
+        const content = await readFile(fullPath, "utf-8");
+        const data = parseYAML(content) as Record<string, unknown>;
+        const id = typeof data.id === "string" ? data.id : undefined;
+        const name = typeof data.name === "string" ? data.name : undefined;
+        if (id === templateName || name === templateName) {
+          return fullPath;
+        }
+      }
+    }
+  } catch {
+    // Fail-open
+  }
+  return null;
+}
+```
+
+需要在文件顶部 import：
+```typescript
+import { createHash } from "crypto";
+```
+
+并把 `calculateTemplateHash` 函数从 init.ts 移到共享位置或复制一份。
+
+---
+
+### Step 2: Namespace-aware Cleanup (Bug 2)
+
+#### 2.1 修改 cleanStaleDNAFiles 签名
+
+文件：`src/cli/commands/sync.ts:126-141`
+
+```typescript
+// 之前
+async function cleanStaleDNAFiles(dir: string, type: "agent" | "skill"): Promise<number>
+
+// 之后
+async function cleanStaleDNAFiles(
+  dir: string,
+  type: "agent" | "skill",
+  activeNamespaces: string[]
+): Promise<number>
+```
+
+#### 2.2 修改 cleanStaleDNAFiles 实现
+
+```typescript
+async function cleanStaleDNAFiles(
+  dir: string,
+  type: "agent" | "skill",
+  activeNamespaces: string[]
+): Promise<number> {
+  let removed = 0;
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = resolve(dir, entry.name);
+      
+      // Extract namespace from filename
+      // Agent: dna-{ns}-{role}.md
+      // Skill: dna-{ns}-{workflow}/
+      const match = entry.name.match(/^dna-([a-z0-9_-]+)-/);
+      if (!match) continue; // Not DNA-managed naming pattern
+      
+      const namespace = match[1];
+      if (!activeNamespaces.includes(namespace)) {
+        // Not in current sync scope, skip
+        continue;
+      }
+
+      // Check for intentdna:managed sentinel
+      let hasManaged = false;
+      if (entry.isFile()) {
+        const content = await readFile(fullPath, "utf-8");
+        hasManaged = content.includes("intentdna:managed");
+      } else if (entry.isDirectory()) {
+        // Check SKILL.md inside skill directory
+        const skillMd = resolve(fullPath, "SKILL.md");
+        try {
+          const content = await readFile(skillMd, "utf-8");
+          hasManaged = content.includes("intentdna:managed");
+        } catch {
+          // No SKILL.md or unreadable
+        }
+      }
+
+      if (hasManaged) {
+        if (entry.isDirectory()) {
+          await rm(fullPath, { recursive: true, force: true });
+        } else {
+          await unlink(fullPath);
+        }
+        removed++;
+      }
+    }
+  } catch {
+    // Fail-open
+  }
+  return removed;
+}
+```
+
+#### 2.3 修改调用点
+
+文件：`src/cli/commands/sync.ts`
+
+找到 `cleanStaleDNAFiles` 的调用点（约 600-650 行），传入 activeNamespaces：
+
+```typescript
+// 之前
+if (opts.agentsDir) {
+  const removed = await cleanStaleDNAFiles(opts.agentsDir, "agent");
+  if (removed > 0) process.stderr.write(`Cleaned ${removed} stale agent file(s)\n`);
+}
+if (opts.skillsDir) {
+  const removed = await cleanStaleDNAFiles(opts.skillsDir, "skill");
+  if (removed > 0) process.stderr.write(`Cleaned ${removed} stale skill dir(s)\n`);
+}
+
+// 之后
+// Extract namespaces from all loaded DNAs
+const activeNamespaces = dnas
+  .map(d => typeof d.namespace === "string" ? d.namespace : null)
+  .filter((ns): ns is string => ns !== null);
+
+if (opts.agentsDir) {
+  const removed = await cleanStaleDNAFiles(opts.agentsDir, "agent", activeNamespaces);
+  if (removed > 0) process.stderr.write(`Cleaned ${removed} stale agent file(s)\n`);
+}
+if (opts.skillsDir) {
+  const removed = await cleanStaleDNAFiles(opts.skillsDir, "skill", activeNamespaces);
+  if (removed > 0) process.stderr.write(`Cleaned ${removed} stale skill dir(s)\n`);
+}
+```
+
+---
+
+### Step 3: 测试
+
+#### 3.1 单元测试
+
+新建 `test/template-version-hash.test.ts`：
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { calculateTemplateHash } from "../src/cli/commands/init.js";
+
+describe("calculateTemplateHash", () => {
+  it("returns consistent hash for same content", () => {
+    const content = "namespace: test\nversion: 0.1.0";
+    const hash1 = calculateTemplateHash(content);
+    const hash2 = calculateTemplateHash(content);
+    expect(hash1).toBe(hash2);
+  });
+
+  it("returns different hash for different content", () => {
+    const content1 = "namespace: test\nversion: 0.1.0";
+    const content2 = "namespace: test\nversion: 0.2.0";
+    const hash1 = calculateTemplateHash(content1);
+    const hash2 = calculateTemplateHash(content2);
+    expect(hash1).not.toBe(hash2);
+  });
+
+  it("returns 16-char hex string", () => {
+    const hash = calculateTemplateHash("test");
+    expect(hash).toMatch(/^[a-f0-9]{16}$/);
+  });
+});
+```
+
+新建 `test/namespace-cleanup.test.ts`：
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, writeFile, readdir, rm } from "fs/promises";
+import { resolve } from "path";
+import { cleanStaleDNAFiles } from "../src/cli/commands/sync.js";
+
+describe("cleanStaleDNAFiles namespace filtering", () => {
+  const testDir = resolve(__dirname, ".test-cleanup");
+  const agentsDir = resolve(testDir, "agents");
+
+  beforeEach(async () => {
+    await mkdir(agentsDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  it("only removes files matching active namespaces", async () => {
+    // Create files for two namespaces
+    await writeFile(
+      resolve(agentsDir, "dna-frw-surgeon.md"),
+      "<!-- intentdna:managed -->\nFRW surgeon"
+    );
+    await writeFile(
+      resolve(agentsDir, "dna-be-handler.md"),
+      "<!-- intentdna:managed -->\nBE handler"
+    );
+
+    // Clean only frw namespace
+    const removed = await cleanStaleDNAFiles(agentsDir, "agent", ["frw"]);
+
+    expect(removed).toBe(1);
+    const remaining = await readdir(agentsDir);
+    expect(remaining).toEqual(["dna-be-handler.md"]);
+  });
+
+  it("preserves files without intentdna:managed", async () => {
+    await writeFile(
+      resolve(agentsDir, "dna-frw-custom.md"),
+      "User-written agent"
+    );
+
+    const removed = await cleanStaleDNAFiles(agentsDir, "agent", ["frw"]);
+
+    expect(removed).toBe(0);
+    const remaining = await readdir(agentsDir);
+    expect(remaining).toEqual(["dna-frw-custom.md"]);
+  });
+
+  it("preserves files not matching dna-{ns}- pattern", async () => {
+    await writeFile(
+      resolve(agentsDir, "custom-agent.md"),
+      "<!-- intentdna:managed -->\nCustom"
+    );
+
+    const removed = await cleanStaleDNAFiles(agentsDir, "agent", ["frw"]);
+
+    expect(removed).toBe(0);
+    const remaining = await readdir(agentsDir);
+    expect(remaining).toEqual(["custom-agent.md"]);
+  });
+});
+```
+
+#### 3.2 集成测试
+
+在 intentdna 项目：
+```bash
+npm test  # 全绿
+```
+
+在 lwk_flutter_v2-rewrite 项目（单模板场景）：
+```bash
+dna sync
+# 验证：不报错，agent/skill 正常生成
+```
+
+创建测试项目（多模板场景）：
+```bash
+mkdir /tmp/multi-template-test && cd /tmp/multi-template-test
+dna init flutter-rewrite
+dna init backend-api  # 假设有这个模板，或用另一个
+dna sync
+# 验证：两个模板的 agent/skill 都保留
+```
+
+---
+
+### Step 4: 文档更新
+
+#### 4.1 CHANGELOG.md
+
+```markdown
+## [1.5.14] - 2026-04-19
+
+### Fixed
+- Template version tracking now uses template's own `version` field instead of package version
+- Added `_template_content_hash` to detect template changes independent of version bumps
+- `dna sync` now only cleans stale files from active namespaces, fixing multi-template projects
+- Namespace-aware cleanup prevents accidental deletion of other templates' generated files
+
+### Changed
+- `dna init` now injects `_template_content_hash` alongside `_template_version`
+- `dna sync` detects template content changes via hash comparison
+```
+
+#### 4.2 docs/multi-template.md（新建）
+
+```markdown
+# Multi-Template Projects
+
+Intent DNA supports using multiple templates in a single project.
+
+## Setup
+
+```bash
+dna init flutter-rewrite
+dna init backend-api
+```
+
+Each template must have a unique `namespace` field. Namespace collisions are detected and blocked.
+
+## Sync Behavior
+
+`dna sync` processes all templates in `.dna/configs/*.yaml` and only cleans files belonging to active namespaces.
+
+Example:
+- `dna-frw-*` files belong to `frw` namespace
+- `dna-be-*` files belong to `be` namespace
+- Syncing `frw` template will not delete `be` files
+
+## Template Updates
+
+Each template tracks its content independently via `_template_content_hash`. When template content changes:
+
+```bash
+dna sync
+# Output: Template content changed: "flutter-rewrite". Run: dna init --upgrade flutter-rewrite
+```
+
+Run upgrade to update:
+```bash
+dna init --upgrade flutter-rewrite
+```
+```
+
+---
+
+### Step 5: 发版
+
+```bash
+cd /Users/samuel/lawark/intentdna
+npm test  # 全绿
+/dna-release patch "fix: template version tracking + namespace-aware cleanup for multi-template projects"
+```
+
+---
+
+## 验收清单
+
+### Bug 1: Template Version
+- [ ] `calculateTemplateHash()` 实现
+- [ ] `injectSourceTemplate()` 接受 templateVersion + templateHash 参数
+- [ ] init 命令两处调用点更新（读模板 version 字段，不读 pkg 版本）
+- [ ] `checkTemplateVersions()` 改为 hash 对比
+- [ ] `findTemplateFile()` 辅助函数实现
+- [ ] 单元测试通过
+
+### Bug 2: Namespace Cleanup
+- [ ] `cleanStaleDNAFiles()` 接受 activeNamespaces 参数
+- [ ] 文件名 namespace 提取逻辑（`dna-{ns}-*` 正则）
+- [ ] 只删匹配 namespace 的文件
+- [ ] sync 调用点传入 activeNamespaces
+- [ ] 单元测试通过
+
+### 集成验证
+- [ ] intentdna 项目 npm test 全绿
+- [ ] lwk_flutter_v2-rewrite dna sync 正常
+- [ ] 多模板测试项目验证（如果有第二个模板）
+
+### 文档
+- [ ] CHANGELOG.md 更新
+- [ ] docs/multi-template.md 新建（可选）
+
+### 发版
+- [ ] /dna-release patch 执行
+- [ ] v1.5.14 发布