spec-canon 0.1.11 → 0.1.12

package/README.md

@@ -23,7 +23,7 @@ SpecCanon 的本质是一个**文档状态机**：每份 Spec 文档是一个状
 | **系统级** | `domains/README.md` | 持续更新 | 域间关系全景 |
 | **系统级** | `domains/<domain>/domain_spec.md` | 持续累积 | 系统当前行为（Canon） |
 | **Change 级** | `change-xxx/00_context~04_test_spec` | 单次生命周期 | 本次变更做了什么 |
-| **项目级** | `SKILL.md` / `AI_CHANGELOG.md` | 持续累积 | 团队学到了什么 |
+| **项目级** | `RULES.md` / `AI_CHANGELOG.md` | 持续累积 | 团队学到了什么 |
 
 ### 闭环演化
 
@@ -94,7 +94,7 @@ spec-canon prompt guide
 
 `change` 还支持父命令选项 `-d, --dir <path>` 指定目标项目目录，默认当前目录。由于 `change next` 已用 `-d` 表示 `--domain`，指定目录时请写在子命令前：`spec-canon change -d /path/to/project next`。
 
-`sync` 会在项目内写入 `spec-canon/.template-manifest.json`，用于记录当前骨架状态，为后续更智能的升级能力预留基础。若有文件需要人工比对，CLI 会同时输出参考模板路径和建议的 `code --diff` / `diff -u` 命令，方便直接对照已安装包中的模板。
+`sync` 会在项目内写入 `spec-canon/.template-manifest.json`，用于记录当前骨架状态，为后续更智能的升级能力预留基础。若有文件需要人工比对，CLI 会同时输出参考模板路径和建议的 `code --diff` / `diff -u` 命令，方便直接对照已安装包中的模板；对于 `spec-canon/templates/` 下的 6 个核心 Spec 模板，还会额外给出可直接覆盖的 `cp` 命令。
 
 ## 文档结构
 

package/dist/commands/sync.js

@@ -1,6 +1,14 @@
 import { join, resolve } from 'node:path';
 import { ScaffoldSyncError, syncScaffold, } from '../utils/scaffold.js';
 import { logger } from '../utils/logger.js';
+const COPYABLE_TEMPLATE_PATHS = new Set([
+    'spec-canon/templates/00_context.md',
+    'spec-canon/templates/01_requirement.md',
+    'spec-canon/templates/02_interface.md',
+    'spec-canon/templates/03_implementation.md',
+    'spec-canon/templates/04_test_spec.md',
+    'spec-canon/templates/domain_spec.md',
+]);
 export function registerSyncCommand(program) {
     program
         .command('sync')
@@ -19,6 +27,7 @@ async function runSync(opts) {
         logger.success('SDD 同步完成');
         logger.blank();
         console.log(`created: ${report.created.length}`);
+        console.log(`migrated: ${report.migrated.length}`);
         console.log(`up_to_date: ${report.upToDate.length}`);
         console.log(`preserved: ${report.preserved.length}`);
         console.log(`manual_review: ${report.manualReview.length}`);
@@ -30,6 +39,14 @@ async function runSync(opts) {
             }
             logger.blank();
         }
+        if (report.migrated.length > 0) {
+            logger.success('已迁移文件：');
+            for (const item of report.migrated) {
+                logger.dim(`  ${item.fromPath} -> ${item.path}`);
+                logger.dim(`    ${item.reason}`);
+            }
+            logger.blank();
+        }
         if (report.manualReview.length > 0) {
             logger.warn('需要人工比对：');
             for (const line of formatManualReviewSection(report.manualReview, targetDir)) {
@@ -54,16 +71,33 @@ export function formatManualReviewItem(item, targetDir) {
         `    ${item.reason}`,
     ];
     if (!item.templatePath) {
+        if (!item.referencePath) {
+            return lines;
+        }
+        const targetPath = join(targetDir, item.path);
+        const quotedReferencePath = quoteShellArg(item.referencePath);
+        const quotedTargetPath = quoteShellArg(targetPath);
+        lines.push(`    参考文件: ${item.referencePath}`);
+        lines.push(`    建议命令: code --diff ${quotedReferencePath} ${quotedTargetPath}`);
+        lines.push(`    建议命令: diff -u ${quotedReferencePath} ${quotedTargetPath}`);
         return lines;
     }
     const targetPath = join(targetDir, item.path);
     const quotedTemplatePath = quoteShellArg(item.templatePath);
     const quotedTargetPath = quoteShellArg(targetPath);
-    lines.push(`    参考模板: ${item.templatePath}`);
+    const sourceLabel = item.compareMode === 'merge-section'
+        ? '当前 CLI SDD 协议段基线'
+        : item.sourceKind === 'baseline'
+            ? '当前 CLI 基线'
+            : '参考模板';
+    lines.push(`    ${sourceLabel}: ${item.templatePath}`);
     lines.push(`    建议命令: code --diff ${quotedTemplatePath} ${quotedTargetPath}`);
     lines.push(`    建议命令: diff -u ${quotedTemplatePath} ${quotedTargetPath}`);
+    if (shouldSuggestTemplateCopy(item)) {
+        lines.push(`    建议命令: cp ${quotedTemplatePath} ${quotedTargetPath}`);
+    }
     if (item.compareMode === 'merge-section') {
-        lines.push('    CLAUDE.md 只需合并 SDD 协议段，无需整文件覆盖');
+        lines.push('    CLAUDE.md 只需按需合并 SDD 协议段，无需整文件覆盖');
     }
     return lines;
 }
@@ -80,3 +114,9 @@ export function formatManualReviewSection(items, targetDir) {
 function quoteShellArg(value) {
     return JSON.stringify(value);
 }
+function shouldSuggestTemplateCopy(item) {
+    return item.sourceKind === 'template' &&
+        item.compareMode === 'full-file' &&
+        item.templatePath !== undefined &&
+        COPYABLE_TEMPLATE_PATHS.has(item.path);
+}

package/dist/templates/index.d.ts

@@ -3,5 +3,5 @@ export declare function loadTemplate(name: string): Promise<string>;
 /** 7 个 Change Spec 模板 */
 export declare const SPEC_TEMPLATES: readonly ["00_context.md", "01_requirement.md", "02_interface.md", "03_implementation.md", "04_test_spec.md", "domain_spec.md", "AI_CHANGELOG.md"];
 /** CLI 独有模板 */
-export declare const CLI_TEMPLATES: readonly ["claude-md-section.md", "domains-readme.md", "skill.md"];
+export declare const CLI_TEMPLATES: readonly ["claude-md-section.md", "domains-readme.md", "rules.md"];
 export declare function loadAllSpecTemplates(): Promise<Map<string, string>>;

package/dist/templates/index.js

@@ -24,7 +24,7 @@ export const SPEC_TEMPLATES = [
 export const CLI_TEMPLATES = [
     'claude-md-section.md',
     'domains-readme.md',
-    'skill.md',
+    'rules.md',
 ];
 export async function loadAllSpecTemplates() {
     const map = new Map();

package/dist/utils/scaffold.d.ts

@@ -28,12 +28,19 @@ export interface TemplateManifest {
 }
 export interface SyncReport {
     created: string[];
+    migrated: Array<{
+        path: string;
+        fromPath: string;
+        reason: string;
+    }>;
     upToDate: string[];
     preserved: string[];
     manualReview: Array<{
         path: string;
         reason: string;
+        sourceKind?: 'template' | 'baseline';
         templatePath?: string;
+        referencePath?: string;
         compareMode?: 'full-file' | 'merge-section';
     }>;
     manifestPath: string;

package/dist/utils/scaffold.js

@@ -16,9 +16,11 @@ const BASE_DIRS = [
     join(SDD_ROOT, 'domains'),
     join(SDD_ROOT, 'changes'),
     join(SDD_ROOT, 'decisions'),
-    join(SDD_ROOT, 'skills'),
+    join(SDD_ROOT, 'rules'),
     join(SDD_ROOT, 'templates'),
 ];
+const RULES_FILE = join(SDD_ROOT, 'rules', 'RULES.md');
+const LEGACY_RULES_FILE = join(SDD_ROOT, 'skills', 'SKILL.md');
 export class ScaffoldSyncError extends Error {
 }
 export async function ensureBaseScaffoldDirs(rootDir) {
@@ -56,22 +58,22 @@ export async function buildManagedFiles(rootDir, opts = {}) {
         desiredContent: await loadTemplate('AI_CHANGELOG.md'),
     });
     addManagedFile(files, {
-        relativePath: join(SDD_ROOT, 'skills', 'SKILL.md'),
-        sourceId: 'template:skill.md',
-        desiredContent: await loadTemplate('skill.md'),
+        relativePath: RULES_FILE,
+        sourceId: 'template:rules.md',
+        desiredContent: await loadTemplate('rules.md'),
     });
     addManagedFile(files, {
         relativePath: join(SDD_ROOT, 'domains', 'README.md'),
         sourceId: 'template:domains-readme.md',
         desiredContent: await loadTemplate('domains-readme.md'),
-        manualReviewReason: 'spec-canon/domains/README.md 与当前模板不同，已保留，请手动比对',
+        manualReviewReason: 'spec-canon/domains/README.md 是持续演化的活文档，当前内容与 CLI 初始基线存在差异，已保留，可按需参考基线结构手动比对',
     });
     if (opts.includeClaude) {
         addManagedFile(files, {
             relativePath: 'CLAUDE.md',
             sourceId: 'generated:claude-md',
             desiredContent: await buildClaudeMdContent(),
-            manualReviewReason: 'CLAUDE.md 已存在，未自动同步 SDD 协议段，请手动比对',
+            manualReviewReason: 'CLAUDE.md 是用户自定义项目说明文件，CLI 未自动改写；如需吸收新版 SDD 协议，请手动合并当前 CLI 提供的协议段基线',
         });
     }
     const domains = new Set(opts.extraDomains ?? []);
@@ -151,6 +153,7 @@ export async function syncScaffold(rootDir) {
         throw new ScaffoldSyncError('未找到 spec-canon/ 目录，请先运行 spec-canon init');
     }
     await ensureBaseScaffoldDirs(rootDir);
+    const legacyCompatibility = await applyLegacyRulesCompatibility(rootDir);
     const files = await buildManagedFiles(rootDir, {
         includeClaude: true,
         includeExistingDomains: true,
@@ -166,16 +169,20 @@ export async function syncScaffold(rootDir) {
         created: statuses
             .filter((status) => status.state === 'created')
             .map((status) => status.relativePath),
+        migrated: legacyCompatibility.migrated,
         upToDate: statuses
             .filter((status) => status.state === 'unchanged')
             .map((status) => status.relativePath),
         preserved: statuses
             .filter((status) => status.state === 'preserved')
             .map((status) => status.relativePath),
-        manualReview: statuses
-            .filter((status) => status.state === 'preserved' &&
-            status.manualReviewReason !== undefined)
-            .map((status) => buildManualReviewItem(status)),
+        manualReview: [
+            ...statuses
+                .filter((status) => status.state === 'preserved' &&
+                status.manualReviewReason !== undefined)
+                .map((status) => buildManualReviewItem(status)),
+            ...legacyCompatibility.manualReview,
+        ],
         manifestPath,
     };
 }
@@ -203,16 +210,71 @@ function buildManualReviewItem(status) {
         reason: status.manualReviewReason,
     };
     if (status.sourceId.startsWith('template:')) {
-        item.templatePath = getTemplatePath(status.sourceId.slice('template:'.length));
+        const templateName = status.sourceId.slice('template:'.length);
+        item.sourceKind = templateName === 'domains-readme.md'
+            ? 'baseline'
+            : 'template';
+        item.templatePath = getTemplatePath(templateName);
         item.compareMode = 'full-file';
         return item;
     }
     if (status.sourceId === 'generated:claude-md') {
+        item.sourceKind = 'baseline';
         item.templatePath = getTemplatePath('claude-md-section.md');
         item.compareMode = 'merge-section';
     }
     return item;
 }
+async function applyLegacyRulesCompatibility(rootDir) {
+    const migrated = [];
+    const manualReview = [];
+    const legacyRulesPath = join(rootDir, LEGACY_RULES_FILE);
+    const rulesPath = join(rootDir, RULES_FILE);
+    const legacyRulesExists = await fileExists(legacyRulesPath);
+    if (!legacyRulesExists) {
+        return { migrated, manualReview };
+    }
+    const rulesExists = await fileExists(rulesPath);
+    if (!rulesExists) {
+        await writeFileSafe(rulesPath, await readFileSafe(legacyRulesPath));
+        migrated.push({
+            path: RULES_FILE,
+            fromPath: LEGACY_RULES_FILE,
+            reason: '已从 spec-canon/skills/SKILL.md 复制内容到 spec-canon/rules/RULES.md，请确认后手动删除旧文件',
+        });
+    }
+    else {
+        manualReview.push({
+            path: RULES_FILE,
+            reason: '检测到 spec-canon/skills/SKILL.md 与 spec-canon/rules/RULES.md 同时存在，CLI 未自动合并，请手动比对并在确认后删除旧文件',
+            referencePath: legacyRulesPath,
+            compareMode: 'full-file',
+        });
+    }
+    const claudePath = join(rootDir, 'CLAUDE.md');
+    if (!(await fileExists(claudePath))) {
+        return { migrated, manualReview };
+    }
+    const claudeContent = await readFileSafe(claudePath);
+    if (!containsLegacyRulesReference(claudeContent)) {
+        return { migrated, manualReview };
+    }
+    manualReview.push({
+        path: 'CLAUDE.md',
+        reason: 'CLAUDE.md 中仍引用旧规则路径，请将 spec-canon/skills/SKILL.md 更新为 spec-canon/rules/RULES.md',
+        sourceKind: 'baseline',
+        templatePath: getTemplatePath('claude-md-section.md'),
+        compareMode: 'merge-section',
+    });
+    return { migrated, manualReview };
+}
+function containsLegacyRulesReference(content) {
+    return [
+        'SKILL.md',
+        'spec-canon/skills/',
+        'spec-canon/skills/SKILL.md',
+    ].some((pattern) => content.includes(pattern));
+}
 function hashContent(content) {
     return createHash('sha256').update(content).digest('hex');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-canon",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "CLI toolkit for Spec-Driven Development (SDD)",
   "type": "module",
   "license": "MIT",

package/templates/claude-md-section.md

@@ -19,7 +19,7 @@
 | 系统级 | `spec-canon/domains/<domain>/domain_spec.md` | 持续累积 | 系统当前行为（Canon） |
 | Change 级 | `spec-canon/changes/<change>/00~04` | 单次生命周期 | 本次变更做了什么 |
 | 项目级 | `spec-canon/decisions/AI_CHANGELOG.md` | 持续累积 | 技术决策留痕 |
-| 项目级 | `spec-canon/skills/SKILL.md` | 持续累积 | 团队规则库（开始任务前先阅读） |
+| 项目级 | `spec-canon/rules/RULES.md` | 持续累积 | 团队规则库（开始任务前先阅读） |
 
 Change Spec 生成顺序（后者依赖前者作为上下文）：
 `00_context → 01_requirement → 02_interface → 03_implementation → 04_test_spec`
@@ -78,7 +78,7 @@ spec-canon prompt show <id> [选项]    # 输出指定提示词（自动替换
 # 示例: spec-canon prompt show req
 ```
 
-若 `spec-canon` 版本升级后新增了骨架文件，优先运行 `spec-canon sync` 补齐缺失内容；该命令默认不会覆盖你已编辑过的文件。
+若 `spec-canon` 版本升级后新增了骨架文件，优先运行 `spec-canon sync` 补齐缺失内容；该命令默认不会覆盖你已编辑过的文件。若 `spec-canon/templates/` 下的 6 个核心 Spec 模板与当前版本不一致，CLI 会同时给出 `code --diff` / `diff -u` / `cp` 建议命令，便于确认后直接同步。
 
 `change next` 默认会保留 `iface`、`domain-sync` 等候选，让你自己选择 next；如确认不需要，可用 `--no-contract-change`、`--no-system-change` 收窄。
 

package/templates/domain_spec.md

@@ -35,4 +35,4 @@ stateDiagram-v2
 
 ## 6. 已知约束与坑位（Known Constraints）
 - [约束/坑位描述]
-  （来源: feat-001 开发过程 / SKILL.md）
+  （来源: feat-001 开发过程 / RULES.md）

package/templates/prompts/daily/domain_sync.md

@@ -13,7 +13,7 @@
 3. 数据流变化 → §3
 4. 新增接口 → §4
 5. 数据模型变更 → §5
-6. 新坑位 → §6 + 同步到 SKILL.md
+6. 新坑位 → §6 + 同步到 RULES.md
 7. 00_context.md 中有而 domain_spec 中没有的信息 → 补充
 请先输出回填草稿，等我审阅。
 
@@ -80,7 +80,7 @@
 3. 数据流变化 → §3
 4. 新增接口 → §4
 5. 数据模型变更 → §5
-6. 新坑位 → §6 + 同步到 SKILL.md
+6. 新坑位 → §6 + 同步到 RULES.md
 7. 00_context.md 中有而 domain_spec 中没有的信息 → 补充
 请先输出每个域的回填草稿，等我审阅。
 

package/templates/prompts/iterative/cold_batch_baseline.md

@@ -8,7 +8,7 @@
    须标注 README.md 中记录的跨域调用关系（上游谁调用本域、本域调用哪些下游）
 4. §4 接口清单：从路由/Controller 文件中提取完整列表
 5. §5 数据模型：从 Entity/Migration 文件中提取
-6. §6 已知约束：从代码注释、TODO、FIXME、SKILL.md 中提取
+6. §6 已知约束：从代码注释、TODO、FIXME、RULES.md 中提取
 7. 对每条信息标注置信度：
    ✅ 确定（代码中有明确逻辑）
    ⚠️ 推测（从代码模式推断）

package/templates/rules.md

@@ -0,0 +1,12 @@
+# RULES.md — 团队规则库
+
+> 项目积累的规则和经验。每次发现 AI 重复犯错的 pattern，追加为新规则。
+
+## 规则清单
+
+<!-- 格式示例：
+### R-001: [规则标题]
+- **场景**：[什么情况下触发]
+- **规则**：[具体要求]
+- **来源**：[哪个变更开发中发现]
+-->