spec-canon 0.1.14 → 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,9 +1,17 @@
+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([
+    '.DS_Store',
+    'Thumbs.db',
+]);
+const ADOPTABLE_PRECREATED_CHANGE_FILES = new Set([
+    '00_context.md',
+]);
 export function registerChangeCommand(program) {
     const change = program
         .command('change')
@@ -14,6 +22,8 @@ export function registerChangeCommand(program) {
         .description('启动或确认当前 change')
         .option('-c, --change <name>', '已确认的变更目录名')
         .option('-g, --goal <content>', '变更目标 / 问题描述 / PRD 引用')
+        .option('--reuse-change', '允许复用已存在且包含历史内容的 change 目录（高风险）', false)
+        .option('--yes', '确认复用旧 change 的风险并继续', false)
         .action(async (opts, command) => {
         await runStart(opts, getRootDir(command));
     });
@@ -33,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 收窄到单域')
@@ -74,12 +85,27 @@ async function runStart(opts, rootDir) {
                 process.exitCode = 1;
                 return;
             }
-            if (await fileExists(getChangeDir(opts.change, rootDir))) {
-                logger.error(`change 目录已存在：spec-canon/changes/${opts.change}。为避免复用旧 change，请改用新的 change 名，或先运行 spec-canon prompt show ctx`);
+            const targetDir = getChangeDir(opts.change, rootDir);
+            const inspection = await inspectChangeDir(targetDir);
+            if (inspection.pathKind === 'non-directory') {
+                logger.error(`change 路径不是目录：spec-canon/changes/${opts.change}。请先清理该文件后重试`);
                 process.exitCode = 1;
                 return;
             }
-            await ensureDir(getChangeDir(opts.change, rootDir));
+            if (inspection.state === 'conflict') {
+                if (!opts.reuseChange) {
+                    logger.error(`change 目录已存在：spec-canon/changes/${opts.change}。如需显式复用旧 change，请使用 --reuse-change --yes`);
+                    process.exitCode = 1;
+                    return;
+                }
+                if (!opts.yes) {
+                    logger.error(`检测到旧 change 内容：spec-canon/changes/${opts.change}（${inspection.effectiveEntries.join(', ')}）。复用可能混入历史上下文；如确认复用，请执行 spec-canon change start -g <goal> -c <change> --reuse-change --yes`);
+                    process.exitCode = 1;
+                    return;
+                }
+                logger.warn(`正在复用旧 change：spec-canon/changes/${opts.change}；已有内容：${inspection.effectiveEntries.join(', ')}。请确认本次 goal 与历史上下文一致。`);
+            }
+            await ensureDir(targetDir);
             await writeActiveChange({
                 ...existing,
                 change: opts.change,
@@ -102,17 +128,39 @@ async function runStart(opts, rootDir) {
     const changesDir = join(rootDir, 'spec-canon', 'changes');
     await ensureDir(changesDir);
     if (opts.change) {
+        const targetDir = getChangeDir(opts.change, rootDir);
+        const inspection = await inspectChangeDir(targetDir);
+        const targetState = inspection.state;
+        const targetExists = targetState !== 'missing';
+        const targetConflict = targetState === 'conflict';
+        const canInspectExistingLatestTarget = targetExists &&
+            getPrevChangeSeq(nextChangeSeq) === changeSeq;
         if (changeSeq !== nextChangeSeq) {
-            logger.error(`change 名中的序号 ${changeSeq} 不是当前可用序号 ${nextChangeSeq}。为避免复用旧 change，请先运行 spec-canon change start -g <goal>，再执行 spec-canon prompt show ctx`);
-            process.exitCode = 1;
-            return;
+            if (!canInspectExistingLatestTarget) {
+                logger.error(`change 名中的序号 ${changeSeq} 不是当前可用序号 ${nextChangeSeq}。为避免复用旧 change，请先运行 spec-canon change start -g <goal>，再执行 spec-canon prompt show ctx`);
+                process.exitCode = 1;
+                return;
+            }
         }
-        if (await fileExists(getChangeDir(opts.change, rootDir))) {
-            logger.error(`change 目录已存在：spec-canon/changes/${opts.change}。为避免复用旧 change，请改用新的 change 名，或先运行 spec-canon change start -g <goal> 再执行 spec-canon prompt show ctx`);
+        if (inspection.pathKind === 'non-directory') {
+            logger.error(`change 路径不是目录：spec-canon/changes/${opts.change}。请先清理该文件后重试`);
             process.exitCode = 1;
             return;
         }
-        await ensureDir(getChangeDir(opts.change, rootDir));
+        if (targetConflict) {
+            if (!opts.reuseChange) {
+                logger.error(`change 目录已存在：spec-canon/changes/${opts.change}。如需显式复用旧 change，请使用 --reuse-change --yes`);
+                process.exitCode = 1;
+                return;
+            }
+            if (!opts.yes) {
+                logger.error(`检测到旧 change 内容：spec-canon/changes/${opts.change}（${inspection.effectiveEntries.join(', ')}）。复用可能混入历史上下文；如确认复用，请执行 spec-canon change start -g <goal> -c <change> --reuse-change --yes`);
+                process.exitCode = 1;
+                return;
+            }
+            logger.warn(`正在复用旧 change：spec-canon/changes/${opts.change}；已有内容：${inspection.effectiveEntries.join(', ')}。请确认本次 goal 与历史上下文一致。`);
+        }
+        await ensureDir(targetDir);
     }
     await writeActiveChange({
         goal: opts.goal,
@@ -129,6 +177,46 @@ async function runStart(opts, rootDir) {
         logger.info('下一步：运行 spec-canon prompt show ctx，确认建议的 change 名后，可再次执行 change start -g <goal> -c <change>');
     }
 }
+function getPrevChangeSeq(seq) {
+    const seqNum = Number.parseInt(seq, 10);
+    if (!Number.isFinite(seqNum) || seqNum <= 1) {
+        return null;
+    }
+    return String(seqNum - 1).padStart(3, '0');
+}
+async function inspectChangeDir(dirPath) {
+    if (!(await fileExists(dirPath))) {
+        return {
+            state: 'missing',
+            pathKind: 'missing',
+            effectiveEntries: [],
+        };
+    }
+    const targetStat = await stat(dirPath);
+    if (!targetStat.isDirectory()) {
+        return {
+            state: 'conflict',
+            pathKind: 'non-directory',
+            effectiveEntries: ['<non-directory-path>'],
+        };
+    }
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    const effectiveEntries = entries.filter((entry) => !IGNORED_PRECREATED_CHANGE_FILES.has(entry.name));
+    if (effectiveEntries.length === 0) {
+        return {
+            state: 'adoptable',
+            pathKind: 'directory',
+            effectiveEntries: [],
+        };
+    }
+    const onlyPrecreatedContext = effectiveEntries.every((entry) => entry.isFile() &&
+        ADOPTABLE_PRECREATED_CHANGE_FILES.has(entry.name));
+    return {
+        state: onlyPrecreatedContext ? 'adoptable' : 'conflict',
+        pathKind: 'directory',
+        effectiveEntries: effectiveEntries.map((entry) => entry.name),
+    };
+}
 async function runStatus(rootDir) {
     try {
         await ensureSddRoot(rootDir);
@@ -176,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;
         }
@@ -189,6 +288,7 @@ async function runNext(opts, rootDir) {
             type,
             contractChange: opts.contractChange,
             systemChange: opts.systemChange,
+            scale: opts.scale,
             domain: opts.domain,
         });
         printNextPlan(plan, {
@@ -234,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;