intentdna 1.5.13 → 1.5.15

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 发布

package/.claude-plugin/hooks/hooks.json

@@ -1,12 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "dna-hook PreToolUse", "timeout": 5 }] }],
-    "PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "dna-hook PostToolUse", "timeout": 3 }] }],
-    "UserPromptSubmit": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "dna-hook UserPromptSubmit", "timeout": 5 }] }],
-    "SubagentStop": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "dna-hook SubagentStop", "timeout": 3 }] }],
-    "PreCompact": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "dna-hook PreCompact", "timeout": 3 }] }],
-    "Notification": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "dna-hook Notification", "timeout": 3 }] }],
-    "Stop": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "dna-hook Stop", "timeout": 3 }] }],
-    "SessionStart": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "dna-hook SessionStart", "timeout": 5 }] }]
-  }
-}

package/.claude-plugin/marketplace.json

@@ -1,16 +0,0 @@
-{
-  "name": "intentdna",
-  "description": "Declarative policy layer for AI agent governance",
-  "owner": {
-    "name": "Samuel",
-    "email": "wanglushan3344@gmail.com"
-  },
-  "plugins": [
-    {
-      "name": "intentdna",
-      "description": "DNA template compilation + runtime enforcement",
-      "version": "1.5.13",
-      "source": "./"
-    }
-  ]
-}

package/.claude-plugin/plugin.json

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