spec-canon 0.1.15 → 0.1.17

package/README.md

@@ -101,12 +101,18 @@ spec-canon prompt show <id>
 spec-canon prompt guide
 ```
 
-`change next` 会根据当前 active change 的文档进度输出候选步骤列表，默认采用宽松模式：保留 `iface` 和 `domain-sync` 候选，让用户自己决定 next。若确认没有接口变化或无需系统级归档，可通过 `--no-contract-change`、`--no-system-change` 收窄候选。
+`change next` 会根据当前 active change 的文档进度和变更规模输出候选步骤列表。用 `--scale small|medium|complex` 指定规模：small≈`req→impl→review`、medium 增加 `iface`、complex 才铺开 `ctx/impl-spec/test-spec/domain-sync`。省略 `--scale` 时按 type 推默认（fix/chore/docs/style/ci/test→small，feat/refactor/perf→medium，complex 不自动推导）。在规模基础上还可用 `--no-contract-change`、`--no-system-change`、`-d <domain>` 进一步收窄。
+
+`ctx` 内置 Explore project context preflight：生成 `00_context` 前会先探索项目入口、SDD 文档、历史决策、近期提交和真实代码入口；只有 goal 过大或无法定位主域时才暂停澄清，普通证据缺口会写入“待补充 / 待确认”。
+
+`req`、`iface`、`impl-spec`、`test-spec` 内置 spark gate：生成正式 Spec 前会先检查是否存在关键澄清点或多方案决策。若存在，提示词会要求 AI 暂停写文件，先提出问题或方案比较，等待人工确认后再继续；若输入已经明确，则直接生成目标 Spec。
 
 `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` 命令，方便直接对照已安装包中的模板；对于 `spec-canon/templates/` 下的 6 个核心 Spec 模板，还会额外给出可直接覆盖的 `cp` 命令。
 
+仓库内额外提供了实验性 `skills/` 原型，用于把“CLI 输出 prompt 再复制粘贴给 agent”的动作收敛为 agent 内部直接调用 CLI 并执行。它们目前仅用于内部验证，不属于稳定 CLI 接口。
+
 ## 文档结构
 
 ```
@@ -124,6 +130,7 @@ docs/
 ├── prompts/                  ← 提示词文件（CLI `spec-canon prompt` 数据源）
 ├── reference/                ← 速查表（随时查阅）
 └── templates/                ← Spec 模板（7 个）
+skills/                     ← 实验性 SDD skills（内部验证）
 ```
 
 ## ROADMAP

package/dist/commands/change.js

@@ -1,8 +1,8 @@
 import { readdir, stat } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { ActiveChangeError, clearActiveChange, getActiveChangeProgress, ensureSddRoot, getActiveChangeStatus, getChangeDir, readActiveChange, writeActiveChange, } from '../utils/active-change.js';
-import { getChangeSeq, getChangeType, getNextChangeSeq, isValidChangeName, } from '../utils/change.js';
-import { buildChangeNextPlan } from '../utils/change-next.js';
+import { CHANGE_TYPE_VALUES, getChangeSeq, getChangeType, getNextChangeSeq, isValidChangeName, isValidChangeType, } from '../utils/change.js';
+import { buildChangeNextPlan, SCALE_VALUES, } from '../utils/change-next.js';
 import { ensureDir, fileExists } from '../utils/fs.js';
 import { logger } from '../utils/logger.js';
 const IGNORED_PRECREATED_CHANGE_FILES = new Set([
@@ -43,6 +43,7 @@ export function registerChangeCommand(program) {
         .command('next')
         .description('输出当前可选的下一步提示词候选')
         .option('--type <type>', '变更类型（feat / fix / refactor / perf / chore / ci / docs / style / test）')
+        .option('--scale <scale>', '变更规模（small / medium / complex）；省略则按 type 推导')
         .option('--no-contract-change', '收窄候选：本次不涉及接口 / Schema / 数据契约变化')
         .option('--no-system-change', '收窄候选：本次不会沉淀系统级知识')
         .option('-d, --domain <name>', '将 domain-sync 收窄到单域')
@@ -263,9 +264,20 @@ async function runNext(opts, rootDir) {
     try {
         await ensureSddRoot(rootDir);
         const active = await readActiveChange(rootDir);
-        const type = resolveNextType(active?.change, opts.type);
-        if (!type) {
-            logger.error('change next 需要指定 --type，或在 confirmed active change 下从 change 名自动推导');
+        if (opts.type && !isValidChangeType(opts.type)) {
+            logger.error(`--type 仅支持 ${CHANGE_TYPE_VALUES.join(' / ')}`);
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.scale && !SCALE_VALUES.includes(opts.scale)) {
+            logger.error(`--scale 仅支持 ${SCALE_VALUES.join(' / ')}`);
+            process.exitCode = 1;
+            return;
+        }
+        const type = resolveNextType(active?.change, opts.type) ?? undefined;
+        // type 只在需要推导规模时才必需；显式 --scale 时可缺省。
+        if (!type && !opts.scale) {
+            logger.error('change next 需要指定 --type 或 --scale，或在 confirmed active change 下从 change 名自动推导');
             process.exitCode = 1;
             return;
         }
@@ -276,6 +288,7 @@ async function runNext(opts, rootDir) {
             type,
             contractChange: opts.contractChange,
             systemChange: opts.systemChange,
+            scale: opts.scale,
             domain: opts.domain,
         });
         printNextPlan(plan, {
@@ -321,7 +334,8 @@ function resolveNextType(change, explicitType) {
     return getChangeType(change);
 }
 function printNextPlan(plan, opts) {
-    console.log(`type: ${opts.type}`);
+    console.log(`type: ${opts.type ?? '(未指定，按 --scale)'}`);
+    console.log(`scale: ${plan.scale}`);
     console.log(`contract-change: ${opts.contractChange ? '默认纳入候选' : '已收窄'}`);
     console.log(`system-change: ${opts.systemChange ? '默认纳入候选' : '已收窄'}`);
     console.log(`domain: ${opts.domain ?? '(自动发现受影响域)'}`);

package/dist/commands/prompt.js

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { ActiveChangeError, readActiveChange } from '../utils/active-change.js';
-import { findPrompt, getPromptsDir, listPrompts, loadPromptContent, } from '../prompts/catalog.js';
+import { findPrompt, getPromptsDir, listPrompts, loadExpandedPromptContent, loadPromptContent, } from '../prompts/catalog.js';
 import { renderPrompt } from '../prompts/renderer.js';
 import { getNextChangeSeq } from '../utils/change.js';
 import { logger } from '../utils/logger.js';
@@ -101,11 +101,12 @@ async function runShow(id, opts) {
         process.exitCode = 1;
         return;
     }
-    const template = await loadPromptContent(entry);
     if (opts.raw) {
+        const template = await loadPromptContent(entry);
         process.stdout.write(template);
         return;
     }
+    const template = await loadExpandedPromptContent(entry);
     const variables = await resolveVariables(entry.id, opts);
     if (!variables)
         return;

package/dist/prompts/catalog.d.ts

@@ -16,5 +16,6 @@ export declare function loadCatalog(): Promise<CatalogData>;
 export declare function findPrompt(id: string): Promise<PromptEntry | undefined>;
 export declare function listPrompts(stage?: string): Promise<PromptEntry[]>;
 export declare function loadPromptContent(entry: PromptEntry): Promise<string>;
+export declare function loadExpandedPromptContent(entry: PromptEntry): Promise<string>;
 export declare function getPromptsDir(): string;
 export {};

package/dist/prompts/catalog.js

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { expandPromptIncludes } from './include.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PROMPTS_DIR = resolve(__dirname, '../../templates/prompts');
 let cachedCatalog = null;
@@ -26,6 +27,10 @@ export async function loadPromptContent(entry) {
     const filePath = join(PROMPTS_DIR, entry.file);
     return readFile(filePath, 'utf-8');
 }
+export async function loadExpandedPromptContent(entry) {
+    const template = await loadPromptContent(entry);
+    return expandPromptIncludes(template, PROMPTS_DIR);
+}
 export function getPromptsDir() {
     return PROMPTS_DIR;
 }

package/dist/prompts/include.d.ts

@@ -0,0 +1 @@
+export declare function expandPromptIncludes(template: string, baseDir: string): Promise<string>;

package/dist/prompts/include.js

@@ -0,0 +1,35 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+const INCLUDE_LINE_RE = /^[ \t]*<!--\s*@include\s+(\S+)\s*-->[ \t\r]*$/;
+export async function expandPromptIncludes(template, baseDir) {
+    const resolvedBaseDir = resolve(baseDir);
+    const lines = template.split('\n');
+    const expanded = [];
+    for (const line of lines) {
+        const match = line.match(INCLUDE_LINE_RE);
+        if (!match) {
+            expanded.push(line);
+            continue;
+        }
+        const includePath = match[1];
+        if (isAbsolute(includePath)) {
+            throw new Error(`Include path must be relative: ${includePath}`);
+        }
+        const targetPath = resolve(resolvedBaseDir, includePath);
+        const relativePath = relative(resolvedBaseDir, targetPath);
+        if (relativePath === '' ||
+            relativePath.startsWith('..') ||
+            isAbsolute(relativePath)) {
+            throw new Error(`Include path escapes prompts directory: ${includePath}`);
+        }
+        const content = await readFile(targetPath, 'utf-8');
+        const hasNestedInclude = content
+            .split('\n')
+            .some((contentLine) => INCLUDE_LINE_RE.test(contentLine));
+        if (hasNestedInclude) {
+            throw new Error(`Nested include is not supported: ${includePath}`);
+        }
+        expanded.push(content);
+    }
+    return expanded.join('\n');
+}

package/dist/utils/change-next.d.ts

@@ -1,10 +1,13 @@
 import type { ActiveChange, ActiveChangeProgress } from './active-change.js';
 import type { ChangeType } from './change.js';
 export type NextCandidateId = 'ctx' | 'req' | 'iface' | 'impl-spec' | 'test-spec' | 'impl' | 'review' | 'domain-sync' | 'change clear';
+export type ChangeScale = 'small' | 'medium' | 'complex';
+export declare const SCALE_VALUES: readonly ChangeScale[];
 export interface ChangeNextOptions {
-    type: ChangeType;
+    type?: ChangeType;
     contractChange: boolean;
     systemChange: boolean;
+    scale?: ChangeScale;
     domain?: string;
 }
 export interface NextCandidate {
@@ -22,10 +25,12 @@ export interface HiddenCandidate {
 export interface ChangeNextPlan {
     active: ActiveChange | null;
     progress: ActiveChangeProgress | null;
+    scale: ChangeScale;
     blockers: string[];
     warnings: string[];
     notes: string[];
     candidates: NextCandidate[];
     hidden: HiddenCandidate[];
 }
+export declare function resolveScale(type: ChangeType | undefined, explicit?: ChangeScale): ChangeScale;
 export declare function buildChangeNextPlan(active: ActiveChange | null, progress: ActiveChangeProgress | null, options: ChangeNextOptions): ChangeNextPlan;

package/dist/utils/change-next.js

@@ -1,3 +1,4 @@
+export const SCALE_VALUES = ['small', 'medium', 'complex'];
 const CHANGE_REQUIRED = [
     'req',
     'iface',
@@ -8,6 +9,38 @@ const CHANGE_REQUIRED = [
     'domain-sync',
     'change clear',
 ];
+// 规模 → 该规模默认纳入的候选集（与文档「任务规模裁剪」表一致）。
+// small  : 小 Bugfix / 小需求    req → impl → review
+// medium : 中等需求             req → iface → impl → review → domain-sync
+// complex: 复杂 / 跨域           ctx → req → iface → impl-spec → test-spec → impl → review → domain-sync
+const SCALE_CANDIDATES = {
+    small: ['req', 'impl', 'review', 'change clear'],
+    medium: ['req', 'iface', 'impl', 'review', 'domain-sync', 'change clear'],
+    complex: [
+        'ctx',
+        'req',
+        'iface',
+        'impl-spec',
+        'test-spec',
+        'impl',
+        'review',
+        'domain-sync',
+        'change clear',
+    ],
+};
+// 省略 --scale 时由 type 推导默认规模。complex 永远不自动推导——
+// 它需要跨域 / 系统级证据，必须由人或 agent 显式 --scale complex。
+const DEFAULT_SCALE_BY_TYPE = {
+    feat: 'medium',
+    fix: 'small',
+    refactor: 'medium',
+    perf: 'medium',
+    chore: 'small',
+    ci: 'small',
+    docs: 'small',
+    style: 'small',
+    test: 'small',
+};
 const TYPE_LABELS = {
     feat: '功能变更',
     fix: '缺陷修复',
@@ -19,6 +52,11 @@ const TYPE_LABELS = {
     style: '样式调整',
     test: '测试变更',
 };
+const SCALE_LABELS = {
+    small: '小改动',
+    medium: '中等改动',
+    complex: '复杂 / 跨域',
+};
 const CANDIDATE_TITLES = {
     ctx: '生成 00_context',
     req: '生成 01_requirement',
@@ -30,23 +68,37 @@ const CANDIDATE_TITLES = {
     'domain-sync': '归档：domain_spec + 域间关系',
     'change clear': '清理 active change',
 };
+export function resolveScale(type, explicit) {
+    if (explicit)
+        return explicit;
+    // 命令层保证 type 与 scale 至少有一个存在；此处兜底以防被内部误用。
+    return type ? DEFAULT_SCALE_BY_TYPE[type] : 'medium';
+}
+function scaleIncludes(scale, id) {
+    return SCALE_CANDIDATES[scale].includes(id);
+}
+function scaleHiddenReason(scale) {
+    return `当前规模 ${scale}（${SCALE_LABELS[scale]}）不含此步；如确有需要，用 --scale 提升规模。`;
+}
 export function buildChangeNextPlan(active, progress, options) {
+    const scale = resolveScale(options.type, options.scale);
     if (!active) {
-        return buildNoActivePlan(options.type);
+        return buildNoActivePlan(options.type, scale);
     }
     if (!active.change) {
-        return buildPendingPlan(active, options);
+        return buildPendingPlan(active, options, scale);
     }
-    return buildConfirmedPlan(active, progress ?? emptyProgress(), options);
+    return buildConfirmedPlan(active, progress ?? emptyProgress(), options, scale);
 }
-function buildNoActivePlan(type) {
-    const notes = [typeNote(type)];
-    if (type !== 'feat' && type !== 'perf' && type !== 'refactor') {
+function buildNoActivePlan(type, scale) {
+    const notes = [typeNote(type), scaleNote(scale)];
+    if (scale === 'small') {
         notes.push('如果只是极小修复，也可以直接更新 AI_CHANGELOG，无需先建立 active change。');
     }
     return {
         active: null,
         progress: null,
+        scale,
         blockers: ['先运行 `spec-canon change start -g <goal>` 建立 active change。'],
         warnings: [],
         notes,
@@ -59,7 +111,7 @@ function buildNoActivePlan(type) {
         ],
     };
 }
-function buildPendingPlan(active, options) {
+function buildPendingPlan(active, options, scale) {
     const hidden = CHANGE_REQUIRED.map((id) => ({
         id,
         reason: '当前是 pending active change，需先确认 change 名。',
@@ -79,16 +131,17 @@ function buildPendingPlan(active, options) {
     return {
         active,
         progress: emptyProgress(),
+        scale,
         blockers: [
             '如需运行依赖 CHANGE 的提示词，先执行 `spec-canon change start -g <goal> -c <change>` 确认 change 名。',
         ],
         warnings: [],
-        notes: [typeNote(options.type)],
+        notes: [typeNote(options.type), scaleNote(scale)],
         candidates: [
             {
                 id: 'ctx',
                 title: CANDIDATE_TITLES['ctx'],
-                reason: 'pending active change 已具备 GOAL，可先生成 00_context。',
+                reason: 'pending active change 已具备 GOAL，可先生成 00_context 并获得 change 命名建议。',
                 command: 'spec-canon prompt show ctx',
                 priority: 0,
             },
@@ -96,59 +149,63 @@ function buildPendingPlan(active, options) {
         hidden: dedupeHidden(hidden),
     };
 }
-function buildConfirmedPlan(active, progress, options) {
+function buildConfirmedPlan(active, progress, options, scale) {
     const warnings = getWarnings(progress);
     const candidates = [];
     const hidden = [];
+    const ctxInScale = scaleIncludes(scale, 'ctx');
     pushCandidate(candidates, {
         id: 'ctx',
-        enabled: !progress.context,
+        enabled: ctxInScale && !progress.context,
         title: CANDIDATE_TITLES['ctx'],
         reason: '00_context.md 尚未生成，适合先补齐系统现状。',
         command: 'spec-canon prompt show ctx',
         priority: 0,
-        hiddenReason: '00_context.md 已存在。',
-    });
+        hiddenReason: ctxInScale ? '00_context.md 已存在。' : scaleHiddenReason(scale),
+    }, hidden);
     pushCandidate(candidates, {
         id: 'req',
-        enabled: !progress.requirement,
+        enabled: scaleIncludes(scale, 'req') && !progress.requirement,
         title: CANDIDATE_TITLES['req'],
         reason: '01_requirement.md 尚未生成，建议先明确需求与验收标准。',
         command: 'spec-canon prompt show req',
         priority: 10,
         hiddenReason: '01_requirement.md 已存在。',
     }, hidden);
-    const ifaceReason = options.contractChange
-        ? '当前保留接口/契约变化可能，且 02_interface.md 尚未生成。'
-        : '已使用 --no-contract-change 收窄候选。';
+    const ifaceInScale = scaleIncludes(scale, 'iface');
+    const ifaceHiddenReason = !ifaceInScale
+        ? scaleHiddenReason(scale)
+        : !options.contractChange
+            ? '已使用 --no-contract-change 收窄候选。'
+            : '02_interface.md 已存在。';
     pushCandidate(candidates, {
         id: 'iface',
-        enabled: options.contractChange && !progress.interface,
+        enabled: ifaceInScale && options.contractChange && !progress.interface,
         title: CANDIDATE_TITLES['iface'],
-        reason: ifaceReason,
+        reason: '当前规模纳入接口/契约设计，且 02_interface.md 尚未生成。',
         command: 'spec-canon prompt show iface',
         priority: progress.requirement ? 20 : 45,
-        hiddenReason: options.contractChange
-            ? '02_interface.md 已存在。'
-            : '已使用 --no-contract-change 收窄候选。',
+        hiddenReason: ifaceHiddenReason,
     }, hidden);
+    const implSpecInScale = scaleIncludes(scale, 'impl-spec');
     pushCandidate(candidates, {
         id: 'impl-spec',
-        enabled: !progress.implementation,
+        enabled: implSpecInScale && !progress.implementation,
         title: CANDIDATE_TITLES['impl-spec'],
         reason: implSpecReason(options.type, progress),
         command: 'spec-canon prompt show impl-spec',
         priority: implSpecPriority(options.type, progress),
-        hiddenReason: '03_implementation.md 已存在。',
+        hiddenReason: implSpecInScale ? '03_implementation.md 已存在。' : scaleHiddenReason(scale),
     }, hidden);
+    const testSpecInScale = scaleIncludes(scale, 'test-spec');
     pushCandidate(candidates, {
         id: 'test-spec',
-        enabled: !progress.testSpec,
+        enabled: testSpecInScale && !progress.testSpec,
         title: CANDIDATE_TITLES['test-spec'],
         reason: testSpecReason(options.type, progress),
         command: 'spec-canon prompt show test-spec',
         priority: progress.implementation ? 32 : 36,
-        hiddenReason: '04_test_spec.md 已存在。',
+        hiddenReason: testSpecInScale ? '04_test_spec.md 已存在。' : scaleHiddenReason(scale),
     }, hidden);
     pushCandidate(candidates, {
         id: 'impl',
@@ -170,32 +227,40 @@ function buildConfirmedPlan(active, progress, options) {
             ? 'AI_CHANGELOG 已包含当前 change。'
             : '当前还缺少足够的前置 Spec/编码结果。',
     }, hidden);
+    const domainSyncInScale = scaleIncludes(scale, 'domain-sync');
+    const domainSyncInScope = domainSyncInScale && options.systemChange;
     const domainSyncCommand = options.domain
         ? `spec-canon prompt show domain-sync -d ${options.domain}`
         : 'spec-canon prompt show domain-sync';
     const domainSyncReason = options.domain
         ? `AI_CHANGELOG 已更新，可将回填范围收窄到域 ${options.domain}。`
         : 'AI_CHANGELOG 已更新，可默认让 domain-sync 自动发现受影响域。';
+    const domainSyncHiddenReason = progress.domainSynced
+        ? 'domain-sync 已完成。'
+        : !domainSyncInScale
+            ? scaleHiddenReason(scale)
+            : !options.systemChange
+                ? '已使用 --no-system-change 收窄候选。'
+                : '完成 review 并更新 AI_CHANGELOG 后再执行。';
     pushCandidate(candidates, {
         id: 'domain-sync',
-        enabled: progress.changelogUpdated && !progress.domainSynced && options.systemChange,
+        enabled: domainSyncInScope && progress.changelogUpdated && !progress.domainSynced,
         title: CANDIDATE_TITLES['domain-sync'],
         reason: domainSyncReason,
         command: domainSyncCommand,
         priority: 80,
-        hiddenReason: progress.domainSynced
-            ? 'domain-sync 已完成。'
-            : options.systemChange
-                ? '完成 review 并更新 AI_CHANGELOG 后再执行。'
-                : '已使用 --no-system-change 收窄候选。',
+        hiddenReason: domainSyncHiddenReason,
     }, hidden);
+    const clearReason = progress.domainSynced
+        ? 'domain-sync 已完成，可清理当前 active change。'
+        : !domainSyncInScale
+            ? `当前规模 ${scale}（${SCALE_LABELS[scale]}）无需 domain-sync，可在 review 后直接清理。`
+            : '已使用 --no-system-change 收窄归档步骤，可直接清理 active change。';
     pushCandidate(candidates, {
         id: 'change clear',
-        enabled: progress.domainSynced || (progress.changelogUpdated && !options.systemChange),
+        enabled: progress.domainSynced || (progress.changelogUpdated && !domainSyncInScope),
         title: CANDIDATE_TITLES['change clear'],
-        reason: progress.domainSynced
-            ? 'domain-sync 已完成，可清理当前 active change。'
-            : '已使用 --no-system-change 收窄归档步骤，可直接清理 active change。',
+        reason: clearReason,
         command: 'spec-canon change clear',
         priority: 90,
         hiddenReason: '当前 change 仍未完成 Review/归档。',
@@ -203,10 +268,12 @@ function buildConfirmedPlan(active, progress, options) {
     return {
         active,
         progress,
+        scale,
         blockers: [],
         warnings,
         notes: [
             typeNote(options.type),
+            scaleNote(scale),
             options.domain
                 ? `domain-sync 将限定在单域 ${options.domain}。`
                 : 'domain-sync 未指定 -d，将默认自动发现受影响域。',
@@ -280,8 +347,14 @@ function getWarnings(progress) {
     return warnings;
 }
 function typeNote(type) {
+    if (!type) {
+        return '变更类型：未指定（已由 --scale 显式指定规模）。';
+    }
     return `变更类型：${type}（${TYPE_LABELS[type]}）。`;
 }
+function scaleNote(scale) {
+    return `变更规模：${scale}（${SCALE_LABELS[scale]}）；候选已按规模裁剪。`;
+}
 function emptyProgress() {
     return {
         context: false,

package/dist/utils/change.d.ts

@@ -1,5 +1,7 @@
 export declare const CHANGE_NAME_PATTERN: RegExp;
 export type ChangeType = 'feat' | 'fix' | 'refactor' | 'perf' | 'chore' | 'ci' | 'docs' | 'style' | 'test';
+export declare const CHANGE_TYPE_VALUES: readonly ChangeType[];
+export declare function isValidChangeType(value: string): value is ChangeType;
 export declare function isValidChangeName(change: string): boolean;
 export declare function getChangeSeq(change: string): string | null;
 export declare function getChangeType(change: string): ChangeType | null;

package/dist/utils/change.js

@@ -1,6 +1,20 @@
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 export const CHANGE_NAME_PATTERN = /^(feat|fix|refactor|perf|chore|ci|docs|style|test)-(\d{3})-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const CHANGE_TYPE_VALUES = [
+    'feat',
+    'fix',
+    'refactor',
+    'perf',
+    'chore',
+    'ci',
+    'docs',
+    'style',
+    'test',
+];
+export function isValidChangeType(value) {
+    return CHANGE_TYPE_VALUES.includes(value);
+}
 export function isValidChangeName(change) {
     return CHANGE_NAME_PATTERN.test(change);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-canon",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "CLI toolkit for Spec-Driven Development (SDD)",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,8 @@
     "prebuild": "node scripts/sync-templates.mjs",
     "build": "tsc",
     "dev": "tsx src/index.ts",
-    "test": "vitest run",
+    "test:skills": "node scripts/validate-skills.mjs",
+    "test": "npm run test:skills && vitest run",
     "preversion": "npm test",
     "version": "node scripts/sync-site-version.mjs",
     "prepublishOnly": "npm run build"

package/templates/00_context.md

@@ -2,47 +2,58 @@
 > 生成时间: YYYY-MM-DD | 生成者: Claude Code + @[工程师]
 > 本文档描述启动本变更时的系统现状，作为 01-04 的共享前提。
 
+<!-- 本模板是"必答清单"，不是"必填表单"：
+     - 按本次变更裁剪——删除与本次无关的小节，优于堆砌无关现状。
+     - 每节的 > 引文说明"本节要回答什么 / 谁消费它"，写内容时对齐该目的。
+     - Evidence Map 记录真实查证结果；查不到就写进"未找到或待补充"，不要凭空补全。
+     - 占位符 [xxx] 替换为真实内容，方括号本身不要保留。 -->
+
+## 0. Evidence Map（取证范围）
+> 本节要回答：本文档的结论基于哪些真实来源——区分"查证过"与"凭印象"。
+- 项目入口：[README.md / AGENTS.md / CLAUDE.md，记录已阅读项]
+- SDD 文档：[domains/README.md / 相关 domain_spec.md / RULES.md / AI_CHANGELOG.md，记录已阅读项]
+- 近期提交：[最近 5-10 条 git log 中与本次变更相关的提交]
+- 代码入口：[Controller / Router / Handler / DTO / 数据模型 / 服务模块等真实代码路径]
+- 未找到或待补充：[缺失的文档、无法定位的模块、需人工确认的信息]
+
 ## 1. 业务背景（Business Context）
-[这个变更所在的业务域是什么？用户场景是什么？
- 为什么现在要做？—— 从 PRD 中提炼，2-3 段即可]
-（→ 下游消费者：01_requirement 的 Background 段落可直接引用）
+> 本节要回答：这次变更所处的业务域、用户场景、为什么现在做。
+> 下游消费者：01_requirement 的 Background 可直接引用。
+
+[从 PRD 提炼，2-3 段即可。]
 
 ## 2. 系统现状（Current State）
+> 本节要回答：动手前，相关模块/数据/接口/依赖各是什么样。只列与本次相关的部分。
 
 ### 2.1 相关模块
-- `模块A`（path/to/module-a/）：负责 [职责]，当前状态 [正常/有已知问题]
-- `模块B`（path/to/module-b/）：负责 [职责]
-（→ 下游消费者：03_implementation 的 File Changes、04_test_spec 的 Regression Impact）
+> 下游消费者：03 的 File Changes、04 的 Regression Impact。
+- `[模块名]`（[真实路径]）：负责 [职责]，当前状态 [正常 / 有已知问题]
 
 ### 2.2 相关数据模型
-- `table_a`：[关键字段说明，当前索引情况]
-- `table_b`：[与 table_a 的关联关系]
-（→ 下游消费者：02_interface 的字段命名对齐、03_implementation 的 Data Changes）
+> 下游消费者：02 的字段命名对齐、03 的 Data Changes。
+- `[表名]`：[关键字段、当前索引、与其他表的关联关系]
 
 ### 2.3 相关接口（已有的）
-- `GET /api/v1/xxx`：[用途，当前调用方]
-- `POST /api/v1/yyy`：[用途]
-（→ 下游消费者：02_interface 的风格一致性、错误码体系对齐）
+> 下游消费者：02 的风格一致性、错误码体系对齐。
+> 取证要求：以真实代码入口（Controller/Router/Handler/路由/OpenAPI）为准，与文档冲突时以代码为准。
+- `[方法 路径]`：[用途、当前调用方]
 
 ### 2.4 依赖服务
-- [内部服务]：积分服务 v2（HTTP），SLA: P99 < 100ms
-- [外部服务]：支付网关（无直接依赖 / 有依赖）
+> 下游消费者：01 的 Constraints、03 的容错设计。
+- [内部 / 外部服务]：[服务名、协议、SLA 或容量约束（如有）]
 
 ## 3. 技术约束（Technical Constraints）
-- [性能]：当前 QPS 约 [N]，峰值 [M]
-- [数据量]：table_a 当前 [X] 万行，月增 [Y] 万
-- [兼容性]：需兼容客户端 v2.1+（不支持 [某特性]）
-- [安全]：涉及 [用户隐私/资金] 数据，需 [脱敏/审计]
-（→ 下游消费者：01_requirement 的 Constraints、02_interface 的版本策略）
+> 本节要回答：哪些既有约束会限制本次方案选择。
+> 下游消费者：01 的 Constraints、02 的版本策略。
+- [性能 / 数据量 / 兼容性 / 安全等真实约束；无相关约束的维度删除]
 
 ## 4. 历史决策（Prior Decisions）
-- [YYYY-MM-DD] 曾考虑过 [方案X]，因 [原因] 放弃
-  （来源：@spec-canon/decisions/AI_CHANGELOG.md）
-- [YYYY-MM-DD] [模块A] 重构时选择了 [方案Y]，需注意 [遗留约束]
-（→ 下游消费者：03_implementation 的 Design Decision，避免重复评估已否决方案）
+> 本节要回答：过去在相关问题上做过哪些决定，避免本次重复评估或推翻。
+> 下游消费者：03 的 Design Decision。
+- [[日期] 曾考虑 [方案] 因 [原因] 放弃 / 选择 [方案] 并留下 [约束]（来源：AI_CHANGELOG）]
+- [无相关历史决策则删除本节]
 
 ## 5. 已知风险与坑位（Known Pitfalls）
-- table_a 的 idx_xxx 索引在高并发写入时有锁竞争
-- 模块B 的 xxxMethod() 不是线程安全的，不要并发调用
-- [其他团队经验/踩坑记录]
-（→ 下游消费者：03_implementation 的坑位规避、04_test_spec 的边界用例）
+> 本节要回答：相关代码/数据里有哪些"踩过的雷"。
+> 下游消费者：03 的坑位规避、04 的边界用例。
+- [来自团队经验或代码证据的具体坑位；无则删除本节]

package/templates/01_requirement.md

@@ -3,14 +3,26 @@
 > PRD 来源: [PRD 链接或编号]
 > 系统现状: @spec-canon/changes/change-xxx/00_context.md
 
+<!-- 本模板是"必答清单"，不是"必填表单"：
+     - 按本次变更裁剪——删除不适用的小节，优于留空或写"无"。
+     - 每节的 > 引文说明"本节要回答什么 / 谁消费它"，写内容时对齐该目的。
+     - 占位符 [xxx] 替换为真实内容，方括号本身不要保留。 -->
+
 ## 1. Background（背景）
-[为什么要做这个功能？解决什么问题？—— 1-2 段即可]
+> 本节要回答：为什么做、解决什么问题。
+> 下游消费者：02/03 理解需求来由。
+
+[1-2 段即可。]
 
 ## 2. Goals（目标）
+> 本节要回答：本次要达成的结果（是什么，不是怎么做）。
+
 - Goal-1: [要达成的结果]
-- Goal-2: [要达成的结果]
 
 ## 3. Scope（范围）
+> 本节要回答：边界在哪——做什么、明确不做什么。
+> 下游消费者：03 的 File Changes 不得越出 In Scope。
+
 ### In Scope（本次做）
 - [条目化列出]
 
@@ -18,23 +30,33 @@
 - [条目化列出，明确边界]
 
 ## 4. Acceptance Criteria（验收标准）
-- AC-1: [具体的、可验证的验收条件]
-- AC-2: [具体的、可验证的验收条件]
-- AC-3: [具体的、可验证的验收条件]
-  （至少覆盖：主流程 + 幂等/重复 + 2 个失败场景）
+> 本节要回答：怎样算做对了——可验证的合约，是整个变更的锚点。
+> 下游消费者：04 的每条用例必须对齐某条 AC。
+
+- AC-1: [具体、可验证的验收条件]
+- [至少覆盖：主流程 + 幂等/重复 + 2 个失败场景]
 
 ## 5. Constraints（约束）
-- 性能：[如 P95 < 200ms]
-- 安全：[如 需鉴权、脱敏]
-- 兼容：[如 需兼容旧版客户端]
-- 依赖：[如 依赖积分服务 v2 接口]
+> 本节要回答：必须满足的非功能约束（来自 00_context §3）。
+> 下游消费者：02 的版本策略、03 的方案选择。
+
+- [性能 / 安全 / 兼容 / 依赖等；无相关维度删除]
 
 ## 6. Risks & Rollout（风险与上线策略）
+> 本节要回答：有什么风险、怎么灰度、怎么回滚。
+> 下游消费者：03 的 Rollback、04 的回归优先级。
+
 - 风险：[已识别的风险]
-- 灰度策略：[如 先开放 5% 流量]
-- 回滚预案：[如 关闭功能开关即可回滚]
+- 灰度 / 回滚：[策略；若为低风险纯新增，说明原因即可]
 
 ## 7. Consistency Check（一致性自检）
 - [ ] 各 AC 之间无矛盾
 - [ ] 约束条件在所有 AC 场景下成立
-- [ ] In/Out Scope 边界无灰色地带
+- [ ] In/Out Scope 边界无灰色地带
+
+<!-- 以下留痕仅在生成本 Spec 过程中实际触发过 spark gate（停下向人确认）时填写；
+     全程无需澄清则删除整块，不要写"无"。 -->
+## 8. Clarification Notes（澄清留痕 · 仅 gate 触发时填写）
+- 已确认：[确认过的需求解释、业务边界或验收口径]
+- 选定/放弃方案：[多种需求切法时，记录采用哪种、放弃哪种及原因]
+- 仍待确认：[不阻塞 01、但后续需确认的问题]

package/templates/02_interface.md

@@ -3,62 +3,65 @@
 > 系统现状: @spec-canon/changes/change-xxx/00_context.md
 > 对齐 01: @spec-canon/changes/change-xxx/01_requirement.md
 
+<!-- 本模板是"必答清单"，不是"必填表单"：
+     - 按本次变更裁剪——删除不适用的小节（如无数据返回则删 Data Schema）。
+     - 每节的 > 引文说明"本节要回答什么 / 谁消费它"。
+     - 表格/示例中的 field、错误码等均为占位示例，替换为真实契约，不要照抄。
+     - 占位符 [xxx] 替换为真实内容，方括号本身不要保留。 -->
+
 ## 1. Overview（总览）
-- 鉴权方式：Bearer Token
-- 幂等要求：[描述幂等键]
-- 版本策略：[如 v1 接口保持向后兼容]
+> 本节要回答：这组接口的统一规则——鉴权、幂等、版本、错误码体系。
+> 这些必须与 00_context §2.3 的既有接口风格一致。
+
+- 鉴权方式：[与既有接口一致的鉴权]
+- 幂等要求：[幂等键及语义]
+- 版本策略：[向后兼容策略]
 - 错误码体系：[遵循项目统一错误码规范]
 
 ## 2. Endpoints
+> 本节要回答：每个端点的完整契约——它是前后端/服务间的唯一真相。
+> 下游消费者：03 据此实现、04 据此做契约测试。
 
 ### API-1: [HTTP方法] [路径]
-> 对应 AC: AC-1, AC-2
+> 对应 AC: [AC-x]
 
 **Request**
 
 | 字段 | 类型 | 必填 | 说明 | 校验规则 |
 |---|---|---|---|---|
-| field1 | string | Y | 描述 | 正则/长度/枚举 |
-| field2 | int | N | 描述 | 范围 |
+| [字段] | [类型] | [Y/N] | [说明] | [正则/长度/枚举/范围] |
 
 **Response (Success)**
 
 | 字段 | 类型 | Nullable | 说明 |
 |---|---|---|---|
-| field1 | boolean | N | 描述 |
-| field2 | string | Y | 描述 |
+| [字段] | [类型] | [Y/N] | [说明] |
 
 **Error Codes**
 
 | 错误码 | HTTP Status | 说明 | 触发条件 |
 |---|---|---|---|
-| INVALID_PARAM | 400 | 参数非法 | field1 格式不符 |
-| UNAUTHORIZED | 401 | 未授权 | Token 无效或过期 |
+| [错误码] | [状态码] | [说明] | [触发条件] |
 
 **Examples**
 ```json
-// 成功 — 首次操作
-Request: { "field1": "value" }
-Response: { "field1": true, "field2": "xxx" }
-
-// 成功 — 幂等场景
-Request: { "field1": "value" }  (第二次请求)
-Response: { "field1": true, "field2": "xxx" }  (结果一致)
-
-// 失败 — 参数错误
-Request: { "field1": "" }
-Response: { "code": "INVALID_PARAM", "message": "field1 不能为空" }
+// 至少给出三种真实样例：成功首次、幂等重复、典型失败
 ```
 
 ## 3. Data Schema（可选，供 DTO 生成使用）
+> 仅当需要前端/调用方直接生成类型时填写；否则删除本节。
+
 ```typescript
-// TypeScript 类型定义（AI 可直接用于前端）
-interface XxxResponse {
-  field1: boolean;
-  field2: string | null;
-}
+[类型定义]
 ```
 
 ## 4. Notes（补充说明）
-- 兼容性注意事项
-- 与其他接口的联动关系
+> 本节要回答：契约之外、调用方仍需知道的事（兼容注意、与其他接口的联动）。
+
+- [无则删除本节]
+
+<!-- 以下留痕仅在生成本 Spec 过程中实际触发过 spark gate 时填写；无则删除整块，不要写"无"。 -->
+## 5. Contract Decisions（契约决策留痕 · 仅 gate 触发时填写）
+- 已确认：[接口形式、调用方、兼容边界、字段语义等确认判断]
+- 选定/放弃方案：[REST/RPC/事件/批处理等形式的取舍及理由]
+- 仍待确认：[不阻塞 02、但后续需确认的契约问题]

package/templates/03_implementation.md

@@ -1,81 +1,79 @@
 # Implementation Spec: [功能名称]
 > Spec Owner: @[工程师姓名] | Status: draft / approved
-> 系统现状: @spec-canon/changes/change-xxx/00_context.md
-> 对齐 01: @spec-canon/changes/change-xxx/01_requirement.md
-> 对齐 02: @spec-canon/changes/change-xxx/02_interface.md
+> 上游依赖（生成前必读）: 00_context.md + 01_requirement.md + 02_interface.md
+
+<!-- 本模板是"必答清单"，不是"必填表单"：
+     - 按本次变更裁剪——删除不适用的小节，优于留空或写"无"。
+     - 每节的 > 引文说明"本节要回答什么 / 谁消费它"，写内容时对齐该目的，不要套形式。
+     - 占位符 [xxx] 替换为真实内容，方括号本身不要保留。 -->
 
 ## 1. Goal Recap（目标复述）
-用 3-5 行复述本次要实现什么，确保 AI 理解正确。
+> 本节要回答：你对"要实现什么"的理解是否与 01/02 一致——这是后续所有决策的锚点。
+
+用 3-5 行复述本次要实现什么。若复述与 01 的 AC 有任何出入，停下回到 01 对齐，不要带着分歧往下写。
 
 ## 2. Design Decision（设计决策）
+> 本节要回答：为什么用这个方案，且它不与系统既有约束冲突。
+> 下游消费者：未来变更读这里，避免重复评估已否决方案（同 00_context §4 的作用）。
 
-### 选定方案
-[描述选定的技术方案]
+**选定方案**
+[描述方案，以及它如何满足 01 的 AC 和 02 的契约。]
 
-### 备选方案对比
+**为什么是它**
+[- 若只有一个合理方案：直接陈述"为何这是唯一合理解"，不要为凑数编造备选。
+ - 若存在多个真实可行方案：逐一列出方案、各自 trade-off、选定理由。散文或表格皆可，形式服从于把取舍讲清楚。]
 
-| 维度 | 方案 A（选定） | 方案 B | 方案 C |
-|---|---|---|---|
-| 复杂度 | ★★☆ | ★★★★ | ★★★ |
-| 性能 | ★★★ | ★★★★★ | ★★★★ |
-| 可维护性 | ★★★★★ | ★★★ | ★★ |
-| 风险 | ★★ | ★★★ | ★★★★ |
+**与既有约束的核对**
+[对照 00_context §4 历史决策、§5 已知坑位，说明本方案未踩已否决方案、未触发已知坑位；若有冲突，在此说明冲突与处理方式，而非绕过。]
 
-**选择理由**：[为什么选 A，trade-off 是什么]
+<!-- 以下留痕仅在生成本 Spec 过程中实际触发过 spark gate（停下向人确认）时填写；
+     全程无需澄清则删除整块，不要写"无"。 -->
+**决策留痕（仅 gate 触发时填写）**
+- 已确认假设：[人工确认过的实现边界 / 迁移 / 灰度 / 回滚判断]
+- 确认来源：[来自哪次澄清或哪份上游文档]
+- 仍待确认：[不阻塞 03、但执行前需再确认的问题]
 
 ## 3. File Changes（变更范围）
-- `path/to/FileA.java` — 新增 [类/方法]
-- `path/to/FileB.java` — 修改 [方法名]，调整 [逻辑]
-- `path/to/FileC.java` — 新增（新文件）
-- `path/to/TestD.java` — 新增单测
+> 本节要回答：动哪些文件、各自动什么——直接来自 00_context §2 系统现状。
+> 下游消费者：04_test_spec 据此推导回归范围；impl 阶段据此逐文件落地。
+
+- `path/to/FileA` — [新增/修改什么，对应哪个 AC 或 Endpoint]
+- [按真实代码路径列全，新文件标注"新增"]
+
+## 4. Data Changes（数据变更）
+> 仅当涉及表/索引/字段变更时填写；纯逻辑变更删除本节。
+> 下游消费者：04 的迁移测试、§7 的回退脚本。
 
-## 4. Data Changes（数据变更，如适用）
 ```sql
--- 新增表 / 索引 / 字段
-ALTER TABLE xxx ADD COLUMN yyy;
-CREATE UNIQUE INDEX idx_xxx ON table(col1, col2);
+[DDL；同时说明对存量数据的影响和迁移方式]
 ```
 
 ## 5. Core Logic（核心逻辑）
+> 本节要回答：关键流程怎么走、靠什么保证正确性。
+> 下游消费者：04 的用例设计、impl 阶段的编码。
 
-### 伪代码
-
-```
-1. 解析参数，校验格式
-2. 开启事务
-3. 尝试插入记录（唯一约束保证幂等）
-    - 冲突 → 返回已处理结果
-4. 插入成功 → 执行业务逻辑
-5. 提交事务
-6. 查询最新状态 → 组装响应
-```
-
-### 不变量断言（复杂逻辑时使用）
-- INV-1: [不变量描述]
-- INV-2: [不变量描述]
+**主流程**
+[伪代码或分步描述。重点写"非显然"的部分——幂等如何保证、事务边界、并发与失败回退；显然的 CRUD 不必展开。]
 
-### 状态图（复杂逻辑时使用）
-```mermaid
-stateDiagram-v2
-    [描述状态流转]
-```
+**不变量 / 状态流转（复杂逻辑时）**
+[列出必须始终成立的不变量，或画状态图。逻辑简单则删除本小节。]
 
 ## 6. Execution Plan（分步执行计划）
+> 本节要回答：按什么顺序施工、每步如何自证没坏。
+> 下游消费者：impl 阶段严格按此逐步执行，Gate 不过不进。
+> 硬性要求：每个 Step 必须有可运行的验证命令；无法验证的步骤要么拆细，要么说明为何无法自动验证。
 
 ### Step 1: [步骤标题]
-- 动作：[具体做什么]
+- 动作：[做什么]
 - 文件：`path/to/file`
-- ✅ 验证：`[验证命令]`（必须通过才进入下一步）
+- ✅ 验证：`[编译/测试/lint 命令]`（通过才进入下一步）
 
-### Step 2: [步骤标题]
-- 动作：[具体做什么]
-- 文件：`path/to/file`
-- ✅ 验证：`[验证命令]`
-
-### Step 3: [步骤标题]
-...
+### Step 2: ...
 
 ## 7. Rollback & Compatibility（回滚与兼容）
-- 回滚方式：[如何回退]
-- 兼容影响：[影响哪些现有功能]
-- 配置项：[需要配置什么]
+> 本节要回答：出问题怎么退、会不会伤到现有功能。
+> 下游消费者：01 的 Rollout 策略、04 的回归影响。
+
+- 回滚方式：[配置开关 / 反向迁移 / 版本回退，哪种]
+- 兼容影响：[影响哪些现有调用方或数据]
+- [若本变更无回滚风险（如纯新增、无状态），说明原因即可]

package/templates/04_test_spec.md

@@ -4,31 +4,46 @@
 > 对齐 01: AC-1 ~ AC-N
 > 对齐 02: 所有 Endpoints
 
+<!-- 本模板是"必答清单"，不是"必填表单"：
+     - 按本次变更裁剪——无接口变更则删契约测试行，无并发风险则删并发用例。
+     - 每节的 > 引文说明"本节要回答什么 / 谁消费它"。
+     - 表格内的工具名为示例，替换为本项目真实技术栈。
+     - 占位符 [xxx] 替换为真实内容，方括号本身不要保留。 -->
+
 ## 1. Test Scope（测试范围）
-- Service 层：单测
-- Controller 层：契约测试 / 集成测试
-- 接口级：契约测试（Schema 比对）
+> 本节要回答：测哪些层、不测哪些。
+
+- [按项目分层列出需覆盖的层级]
 
 ## 2. Test Strategy（测试策略）
+> 本节要回答：每层用什么测试类型、什么工具、覆盖什么重点。
+
 | 层级 | 测试类型 | 工具 | 覆盖重点 |
 |---|---|---|---|
-| Service | 单测 | JUnit 5 + Mockito | 业务逻辑、幂等、异常 |
-| Controller | 集成测试 | MockMvc / WebTestClient | 参数校验、响应格式 |
-| 契约 | Schema 比对 | 自定义断言 | Response 与 02_interface 一致 |
+| [层级] | [类型] | [本项目工具] | [重点] |
 
 ## 3. Test Cases（用例清单）
+> 本节要回答：每条 AC 如何被具体用例验证——每条用例必须对齐某条 AC。
+> 下游消费者：impl 阶段据此写测试。
 
 | 编号 | 场景 | 输入 | 期望结果 | 对齐 AC |
 |---|---|---|---|---|
-| TC-01 | [正常路径] | [输入] | [期望] | AC-1 |
-| TC-02 | [幂等场景] | [输入] | [期望] | AC-1 |
-| TC-03 | [参数异常] | [输入] | [期望错误码] | AC-2 |
-| TC-04 | [并发场景] | [输入] | [期望] | AC-1 |
+| TC-01 | [正常路径] | [输入] | [期望] | [AC-x] |
+| [覆盖：主流程 + 幂等 + 失败 + 必要时并发，对齐 01 的全部 AC] | | | | |
 
 ## 4. Test Data（数据准备）
-- 前置数据：[需要预置什么数据]
-- 时间假设：[如 "当天" 以服务端 UTC 为准]
-- Mock 依赖：[哪些外部服务需要 Mock]
+> 本节要回答：跑测试前要准备什么数据、Mock 什么依赖。
+
+- 前置数据 / 时间假设 / Mock 依赖：[按需填写]
 
 ## 5. Regression Impact（回归影响）
-- [列出可能影响的现有功能，提示需要回归]
+> 本节要回答：本次改动可能波及哪些现有功能、需回归什么。
+> 依据：00_context §2 的模块关系。
+
+- [列出需回归的现有功能]
+
+<!-- 以下留痕仅在生成本 Spec 过程中实际触发过 spark gate 时填写；无则删除整块，不要写"无"。 -->
+## 6. Test Decisions（测试决策留痕 · 仅 gate 触发时填写）
+- 已确认：[自动化/手工边界、回归范围、风险覆盖优先级]
+- 选定/放弃策略：[采用的测试组合及理由、未采用方式及原因]
+- 仍待确认：[不阻塞 04、但执行测试前需确认的问题]

package/templates/claude-md-section.md

@@ -80,9 +80,15 @@ spec-canon prompt show <id> [选项]    # 输出指定提示词（自动替换
 # 示例: spec-canon prompt show req
 ```
 
+`ctx` 内置 Explore project context preflight：生成 `00_context` 前先探索项目入口、SDD 文档、历史决策、近期提交和真实代码入口；goal 过大或无法定位主域时会先暂停澄清，普通证据缺口写入“待补充 / 待确认”。
+
+`req`、`iface`、`impl-spec`、`test-spec` 内置 spark gate：生成正式 Spec 前会先检查关键澄清点或多方案决策；若存在阻塞问题，先暂停写文件并等待人工确认，确认后再把结果沉淀到对应 Spec。gate 强度按变更规模分级——小改动只在"会导致返工或破坏现状的硬阻塞"时暂停，迁移/灰度/回滚等问题仅复杂/跨域变更才核对，避免小需求被全套清单打断。
+
+若当前环境已安装与本工作流配套的 `sdd-*` skills，可把它们视为这些 CLI 命令的对话入口：skill 负责路由和自动推进，底层真相仍是 `spec-canon` CLI 与 `spec-canon/` 文档。若未安装，则继续按上面的 CLI 流程执行。
+
 若 `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` 收窄。
+`change next` 会按变更规模裁剪候选：`--scale small|medium|complex` 直接指定规模（small≈`req→impl→review`、medium 增加 `iface`、complex 才铺开 `ctx/impl-spec/test-spec/domain-sync`）。省略 `--scale` 时按 type 推默认（fix/chore/docs/style/ci/test→small，feat/refactor/perf→medium，complex 不自动推导）。在规模基础上还可叠加 `--no-contract-change`、`--no-system-change`、`-d <domain>` 进一步收窄。
 
 `change` 支持父命令选项 `-d, --dir <path>` 指定目标项目目录；由于 `change next` 已使用 `-d` 作为 `--domain`，目录参数需写在子命令前面。
 

package/templates/prompts/daily/step0_context.md

@@ -13,6 +13,15 @@
 5. 先在输出开头单独给出一行：`建议 change 名：<type>-{{CHANGE_SEQ}}-<slug>`
 {{/if}}
 
+先执行 Explore project context preflight：
+1. 阅读项目入口文档：README.md、AGENTS.md 或 CLAUDE.md（若存在），了解项目定位、开发命令和本地规则。
+2. 阅读 SDD 入口：@spec-canon/domains/README.md、相关 `domain_spec.md`、@spec-canon/rules/RULES.md、@spec-canon/decisions/AI_CHANGELOG.md（若存在）。
+3. 查看最近 5-10 条 git log，提取与本次 goal 可能相关的近期变更、历史决策或风险信号。
+4. 判断 goal 是否适合单个 change：若明显包含多个独立子系统或多个互不依赖目标，先停止，给出拆分建议，等待我确认后再生成 00_context。
+5. 若无法定位主域或主模块，先停止，最多提出 3 个定位问题；不要凭空选择域。
+6. 若只是部分证据缺失，不要停止生成；在 00_context 中标注“待补充 / 待确认”，并说明已检查过哪些来源。
+7. 本阶段只做项目上下文探索和证据报告，不生成 01_requirement 的 AC，不设计 02_interface，不选择 03_implementation 技术方案，不制定 04_test_spec 测试策略。
+
 然后按以下顺序工作：
 1. 根据 goal 判断 change type，并解释判断依据
 2. 从 goal 中提炼 slug

package/templates/prompts/daily/step1_requirement.md

@@ -1,6 +1,22 @@
+<!-- @include shared/spark_protocol.md -->
+
 若存在 @spec-canon/changes/{{CHANGE}}/00_context.md，请先阅读；否则跳过。
 阅读以下 change goal，生成 spec-canon/changes/{{CHANGE}}/01_requirement.md。
 按 @spec-canon/templates/01_requirement.md 模板生成文档。
+
+生成前先执行 01_requirement 阶段 gate（强度随变更规模，见 Spark Gate Protocol；小改动只核对"始终核对"项的硬阻塞）：
+
+始终核对（含小改动）：
+1. 若 goal 存在多种解释，先停止并让我确认采用哪一种解释。
+2. 若 Scope / Out of Scope 不清，先提出边界问题，不要自行扩大范围。
+3. 若 AC 无法验证、互相冲突，或缺少主流程 / 幂等 / 失败场景，先指出缺口并让我确认。
+
+中等及以上变更追加核对：
+4. 若性能、安全、兼容、依赖等关键约束缺失且会影响需求判断，先提问确认。
+5. 若需求过大，可能需要拆成多个 change，先给出拆分建议并等待确认。
+
+无论规模，本阶段只做需求澄清，不提前设计接口或实现方案。
+
 要求：
 1. AC 至少覆盖主流程 + 幂等 + 2 个失败场景
 2. §3 Scope：若已有 00_context.md，基于其 §2 标注本次变更涉及的模块/文件；否则基于代码库自行分析

package/templates/prompts/daily/step2_implementation.md

@@ -1,8 +1,23 @@
+<!-- @include shared/spark_protocol.md -->
+
 请阅读 @spec-canon/changes/{{CHANGE}}/ 下的 00_context.md + 01_requirement.md + 02_interface.md，
 生成 03_implementation.md。
 按 @spec-canon/templates/03_implementation.md 模板生成文档。
-§2 Design Decision：参考 00_context.md §4 历史决策，评估技术方案。
-如果有明确最优方案，直接选定并说明理由；
-如果存在多个可行方案，使用 AskUserQuestion 向我确认后再继续。
+
+生成前先执行 03_implementation 阶段 gate（强度随变更规模，见 Spark Gate Protocol；小改动只核对"始终核对"项的硬阻塞）：
+
+始终核对（含小改动）：
+1. §2 Design Decision：参考 00_context.md §4 历史决策和 §5 已知坑位评估方案；有明确最优方案直接选定并说明理由。
+2. 若方案与历史决策或已知坑位冲突，先说明冲突，不要绕过已有约束。
+3. 若文件改动范围或某步骤的验证命令无法明确，先停止并提出问题。
+
+中等及以上变更追加核对：
+4. 若存在多个可行实现方案，先给出 2-3 个方案、trade-off、推荐方案和理由，等待我确认后再继续。
+
+复杂 / 跨域变更追加核对：
+5. 若数据迁移、灰度、回滚或跨域兼容策略无法明确，先停止并提出问题。
+
+无论规模，本阶段只做实施设计、变更范围和验证路径，不直接编码。
+
 File Changes 基于 00_context.md §2，Core Logic 规避 00_context.md §5 已知坑位。
 每个 Step 必须有验证命令。

package/templates/prompts/daily/step2_interface.md

@@ -1,8 +1,25 @@
+<!-- @include shared/spark_protocol.md -->
+
 请阅读 @spec-canon/changes/{{CHANGE}}/ 下的 00_context.md + 01_requirement.md，
 并扫描代码库中的真实接口入口（优先看 `Controller` / `Router` / `Handler` / 路由定义；若项目已有 OpenAPI 或接口 DTO，也一并参考），
 生成 02_interface.md。
 按 @spec-canon/templates/02_interface.md 模板生成文档。
 
+生成前先执行 02_interface 阶段 gate（强度随变更规模，见 Spark Gate Protocol；小接口改动聚焦"始终核对"项的硬阻塞）：
+
+始终核对：
+1. 若无法确认本次是否需要接口、事件、数据契约或外部可见行为变化，先停止并让我确认。
+2. 若 01_requirement.md 的 AC 不足以推导接口行为，先要求补充或修正 01，不要自行发明契约。
+3. 若新契约与真实代码中的既有接口风格冲突，先说明冲突和取舍方案，等待确认后再生成 02。
+
+中等及以上变更追加核对：
+4. 若字段语义、幂等策略、兼容策略或错误码边界有分歧，先提出阻塞契约设计的问题。
+
+复杂 / 跨域变更追加核对：
+5. 若 REST / RPC / 事件 / 批处理等边界形式存在多个可行方案，先给出 2-3 个方案、trade-off、推荐方案和理由。
+
+无论规模，本阶段只做系统边界和契约设计，不提前做文件级实施计划。
+
 要求：
 1. 先用 00_context.md §2.3 快速定位相关已有接口，再回看真实代码入口确认路径、HTTP 方法、参数组织、请求/响应结构、鉴权方式、错误响应风格和 DTO 命名
 2. 真实代码是接口契约的第一事实来源；00_context.md 用于汇总风格、补充背景和交叉校验

package/templates/prompts/daily/step2_test_spec.md

@@ -1,5 +1,22 @@
+<!-- @include shared/spark_protocol.md -->
+
 请阅读 @spec-canon/changes/{{CHANGE}}/ 下的全部 Spec，
 生成 04_test_spec.md。
 按 @spec-canon/templates/04_test_spec.md 模板生成文档。
+
+生成前先执行 04_test_spec 阶段 gate（强度随变更规模，见 Spark Gate Protocol；小改动只核对"始终核对"项的硬阻塞）：
+
+始终核对（含小改动）：
+1. 若回归范围不清，先基于 00_context.md §2 标出不确定点并等待确认。
+2. 若测试数据、Mock 策略或外部依赖处理不明确，先停止并提出问题。
+3. 若发现 01 / 02 / 03 之间存在影响测试设计的上游 Spec 矛盾，先停止并指出应回到哪个文档修正，不要在 04 中自行改写需求、接口或实施方案。
+
+中等及以上变更追加核对：
+4. 若自动化测试和手工验收的边界未定，先提出测试投入取舍问题。
+5. 若风险覆盖优先级需要人工取舍，先列出风险和建议覆盖顺序。
+
+复杂 / 跨域变更追加核对：
+6. 若是否需要契约测试、迁移测试、性能测试或并发测试存在分歧，先给出 2-3 个测试策略方案、trade-off、推荐方案和理由。
+
 Regression Impact 基于 00_context.md §2 的模块关系推导，
 边界用例参考 00_context.md §5 的已知坑位。

package/templates/prompts/daily/step3_execute.md

@@ -1,11 +1,22 @@
-根据现有 Spec 文档按以下分支执行：
+请基于 @spec-canon/changes/{{CHANGE}}/ 下实际存在的 Spec 文档执行编码，并遵循以下优先级与停机规则：
 
-— 若存在 @spec-canon/changes/{{CHANGE}}/03_implementation.md
-  → 按 03 中的 Step 列表逐步执行，每步运行该步骤的验证命令，通过后报告，然后我确认是否继续下一步
+1. 若存在 @spec-canon/changes/{{CHANGE}}/03_implementation.md
+   - 以 03_implementation.md 作为施工图执行：改动范围、步骤顺序、验证方式默认以 03 为准
+   - 若存在 02_interface.md，以其校验接口 / 数据契约；若存在 01_requirement.md，以其校验 AC、Scope 和非目标
+   - 若 03 与已存在的 01 / 02 或真实代码冲突，或 03 不足以确定文件范围、步骤顺序，或在结合已存在的 04_test_spec.md 后仍不足以确定验证方式，先停止并报告差异，不要自行猜测继续编码
+   - 若存在 00_context.md，可补读其相关段落（历史决策、已知坑位、依赖影响）辅助判断；若仍有歧义，建议先回补或修正 03
+   - 按 03 中的 Step 列表逐步执行；每步完成后优先运行该步骤在 03 中给出的验证命令。若 03 未写当前步骤的验证命令且存在 04_test_spec.md，优先执行 04 中与当前步骤相关的测试、回归和边界验证。只有当 03 与 04 都未给出可执行验证时，才补最小必要验证并说明理由。验证通过后报告，然后我确认是否继续下一步
 
-— 若存在 @spec-canon/changes/{{CHANGE}}/02_interface.md 但无 03
-  → 基于 01_requirement + 02_interface 自行规划实现步骤，
-    每步完成后运行编译/单测，通过后报告，然后我确认是否继续下一步
+2. 若存在 @spec-canon/changes/{{CHANGE}}/02_interface.md 但无 03
+   - 以 02_interface.md 作为契约约束，以 01_requirement.md 作为验收与范围约束，并结合真实代码定位实际修改入口
+   - 在开始编码前，先输出一个“临时执行计划”，至少包含：计划修改的文件 / 模块、步骤顺序、每步验证命令、关键假设或风险
+   - 先等待我确认临时执行计划，再开始第一步编码；不要一边规划一边直接改代码
+   - 若无法从 01 + 02 + 代码库安全推出文件范围、核心方案或验证方式，或发现涉及陌生模块、跨域依赖、历史坑位不清晰的高风险改动，则停止并建议先补 03_implementation.md；若存在 00_context.md，可先补读后再判断
+   - 开始执行后按步推进，每步完成后运行对应验证，通过后报告，然后我确认是否继续下一步
 
-— 若只有 @spec-canon/changes/{{CHANGE}}/01_requirement.md
-  → 基于 01 的 AC 直接实现，分步完成，每步运行验证命令，通过后报告，然后我确认是否继续下一步
+3. 若只有 @spec-canon/changes/{{CHANGE}}/01_requirement.md
+   - 以 01_requirement.md 的 AC、Scope、Constraints 作为唯一显式约束，并结合真实代码定位修改入口
+   - 在开始编码前，先输出一个“最小临时计划”，至少包含：计划修改的文件 / 模块、步骤顺序、每步验证命令、关键假设
+   - 先等待我确认最小临时计划，再开始第一步编码
+   - 若实现过程中发现接口 / 数据模型变更信号，应停止并建议先补 02_interface.md；若文件范围、风险或执行顺序仍不清晰，应停止并建议补 00_context.md 或 03_implementation.md
+   - 开始执行后按步推进，每步完成后运行对应验证，通过后报告，然后我确认是否继续下一步

package/templates/prompts/guide.md

@@ -2,6 +2,10 @@
 
 ## 决策树：选择正确的提示词序列
 
+`req`、`iface`、`impl-spec`、`test-spec` 内置 spark gate：生成正式 Spec 前会先检查是否存在关键澄清点或多方案决策。若存在，AI 会暂停写文件，先提出问题或方案比较，等待人工确认后再继续；这不是新增流程节点，而是 01-04 文档生成前的强制澄清协议。
+
+`ctx` 内置 Explore project context preflight：生成 00_context 前会先探索项目入口、SDD 文档、历史决策、近期提交和真实代码入口。只有 goal 过大或无法定位主域时才暂停澄清；普通证据缺口会写入“待补充 / 待确认”。
+
 ```
 你的项目处于什么阶段？
 │
@@ -86,6 +90,7 @@
 - **复杂需求**：完整流程 change start → domain-sync
 
 > `(ctx →)` 表示可选：若 AI 需要理解系统现状（如涉及陌生模块或跨域依赖），小需求 / 中等需求也应前置 `ctx`。
+> 01-04 的 spark gate 只在关键问题未确认时暂停；若输入已经明确，会直接生成目标 Spec。
 > 若确认要复用已有历史内容的 change 目录，需显式使用 `change start ... --reuse-change --yes`；默认会拒绝复用以避免上下文污染。
 
 补充：如果不想手动判断当前该跑哪一步，可在任一阶段执行 `spec-canon change next`。该命令默认输出候选步骤列表，而不是唯一推荐；如确认没有接口变化或无需系统级归档，可用 `--no-contract-change`、`--no-system-change` 收窄。

package/templates/prompts/shared/spark_protocol.md

@@ -0,0 +1,25 @@
+## Spark Gate Protocol（适用于 01-04）
+
+### 第一步：按变更规模定 gate 强度
+
+先判断本次变更规模——依据 change 名中的类型前缀（feat/fix/refactor/perf/chore/ci/docs/style/test）、`00_context`（若有），以及裁剪三问（是否需理解系统现状 / 是否动接口或数据模型 / 是否产生系统级知识）：
+
+- **小改动**（小 bugfix / 小需求 / docs / style / 单点修复）：只在出现"会导致返工或破坏现状的硬阻塞"时才停——需求有歧义、改动与现状直接冲突、上游 Spec 矛盾。不要为可选优化、未来扩展或不影响本次结果的边角问题提问。
+- **中等改动**：在硬阻塞之外，额外就接口/数据契约的关键分歧提问。
+- **复杂 / 跨域改动**：执行完整 gate，含数据迁移、灰度、回滚、跨域兼容等。
+
+宁可少问、问到点子上，也不要用一长串清单打断小改动。每个阶段 gate 的条目已标注适用强度，按本次规模只核对对应层级。
+
+### 第二步：判断该强度下是否存在关键澄清点
+
+若不存在，直接继续生成目标 Spec。
+
+若存在关键澄清点：
+1. 停止生成或修改目标 Spec 文件。
+2. 最多提出 3 个会阻塞当前 Spec 的问题。
+3. 若是方案取舍，给出 2-3 个方案、trade-off、推荐方案和理由。
+4. 等用户确认后，再将确认结果写入目标 Spec。
+
+用户确认前，不要生成目标 Spec 文件。
+不要创建独立 spark 文档作为事实源；确认结果必须沉淀到当前目标 Spec。
+若发现上游 Spec 矛盾，停止并指出应回到哪个上游文档修正。