sillyspec 3.20.5 → 3.20.6

package/docs/sillyspec/file-lifecycle/platform-workflows-sync.md

@@ -1,6 +1,7 @@
 ---
 author: qinyi
 created_at: 2026-06-04 16:25:42
+updated_at: 2026-07-02 11:00:00
 ---
 
 # 平台模式、Workflow 与 Sync
@@ -24,6 +25,10 @@ created_at: 2026-06-04 16:25:42
 
 后续 `--done` / `--skip` 会从该文件恢复参数。
 
+## 平台残留清理（一次性）
+
+`run.js` 在平台模式（`specRoot` 指向外部）首次启动时，会检查源码目录 `cwd/.sillyspec/` 是否为旧版本残留并清理（复用 `init.js` 的 `cleanupRuntimeResidue`）。该清理**仅在首次执行一次**：完成后在 cwd 根写入 `.sillyspec-platform-cleaned` 标记文件，后续每次 `run` 直接跳过，避免重复检查与噪声。清理白名单与边界见总览的「平台模式残留清理边界」。
+
 ## 路径替换
 
 `run.js outputStep()` 在 scan 阶段替换：

package/docs/sillyspec/file-lifecycle/stage-artifacts.md

@@ -31,7 +31,7 @@ created_at: 2026-06-04 16:25:42
 | execute | 12+ | 生成/使用 worktree，按 Wave 执行；最终 apply/cleanup |
 | verify | 7 | 写 `verify-result.md` |
 | archive | 5 | 写 `module-impact.md`，同步模块文档，归档目录 |
-| quick | 3 | 写 quicklog 或追加 change tasks；直接改主工作区 |
+| quick | 3 | 始终写 quicklog；关联变更时另在各 change tasks.md 追加并勾选 task；直接改主工作区 |
 
 ## 变更四件套
 
@@ -42,7 +42,7 @@ created_at: 2026-06-04 16:25:42
 | `proposal.md` | brainstorm 第 11 步；propose 第 5 步 | propose/plan/verify/archive prompt |
 | `design.md` | brainstorm 第 10/11 步；propose 第 5 步 | plan、execute、verify、worktree apply 的文件清单 |
 | `requirements.md` | brainstorm 第 11 步；propose 第 5 步 | plan、verify |
-| `tasks.md` | brainstorm 第 11 步；propose 第 5 步；quick `--change` 可追加 task | plan、execute、verify、archive |
+| `tasks.md` | brainstorm 第 11 步；propose 第 5 步；quick 关联变更时可追加 task | plan、execute、verify、archive |
 
 `run.js validateFileLocations()` 在阶段完成时会检查：
 
@@ -140,7 +140,7 @@ created_at: 2026-06-04 16:25:42
 
 路径：`.sillyspec/quicklog/QUICKLOG-<git-user>.md`
 
-创建方式：quick 阶段“理解任务”prompt，且没有 `--change` 时创建/追加。
+创建方式：quick 阶段“理解任务”prompt，**每次 quick 都创建/追加**（无论是否关联变更）。关联变更时，同一 ql-ID 会同步写入各关联变更的 tasks.md 作为未勾选 task，step 3 完成时勾选。
 
 格式规则来自 prompt：
 

package/docs/sillyspec/file-lifecycle.md

@@ -1,7 +1,7 @@
 ---
 author: qinyi
 created_at: 2026-05-31 11:00:00
-updated_at: 2026-07-01 15:00:00
+updated_at: 2026-07-02 11:00:00
 ---
 
 # SillySpec 文件生命周期
@@ -66,15 +66,16 @@ updated_at: 2026-07-01 15:00:00
 | `.sillyspec/changes/archive/` | 是 | archive `确认归档 --confirm` 分支 | 已归档变更目录 |
 | `.sillyspec/knowledge/` | 是 | `init.js` 建目录；scan「Extract Project Knowledge」步骤产出 | `INDEX.md`、`uncategorized.md`，以及 scan 提取的 `conventions.md`/`patterns.md`/`known-issues.md` |
 | `.sillyspec/workflows/` | 是 | `init.js` 从模板复制 | workflow check 定义 |
-| `.sillyspec/quicklog/` | 是 | quick prompt | 无 `--change` quick 任务记录 |
+| `.sillyspec/quicklog/` | 是 | quick prompt | 每次 quick 任务记录（始终写入；关联变更另在各 change tasks.md 勾选） |
 | `.sillyspec/shared/` | 是 | `init.js` | 共享目录，当前无核心生命周期逻辑 |
 | `.sillyspec/workspace/` | 是 | `init.js` | 工作区目录，当前无核心生命周期逻辑 |
 | `.sillyspec/.runtime/` | 否 | `init.js`、`ProgressManager`、运行时命令 | DB、gate、artifacts、history、workflow-runs、worktrees、knowledge-hit-report.json、postcheck-result.json |
 
 `init.js` 会把 `.sillyspec/.runtime/`、`.sillyspec/local.yaml`、`.sillyspec/codebase/SCAN-RAW.md` 追加到 `.gitignore`。
 
-> **平台模式残留清理边界**（`init.js` `cleanupRuntimeResidue`，由 `run.js` 启动时复用）：
+> **平台模式残留清理边界**（`init.js` `cleanupRuntimeResidue`，由 `run.js` 启动时首次执行一次）：
 > 当 `specRoot` 指向外部、源码目录的 `.sillyspec/` 含真实资产（`changes/`/`projects/`/`sillyspec.db`）时，只清理运行时残留，**不整删 `.runtime/`**。清理白名单保留权威状态：`worktrees/`、`sillyspec.db`、`global.json`、`gate-status.json`、`contract-artifacts/`、`execute-runs/`；其余子项（`artifacts/`、`scan-runs/`、`scan-projects.json`、`user-inputs.md`、`postcheck-result.json` 等可重建缓存）逐项删除，`local.yaml`、`codebase/` 整删。未知子项默认保留（安全侧倾斜）。
+> 该清理在 `run.js` 启动时**仅执行一次**：首次处理后写 cwd 根的 `.sillyspec-platform-cleaned` 标记文件，后续每次 `run` 直接跳过。旧版每次启动都打印 `❌ 拒绝删除` 红叉属误导性噪声（清理既不阻塞流程也不动真实资产），已降为 `ℹ️` 一次性提示。
 
 ## 主要文件流
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.20.5",
+  "version": "3.20.6",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/index.js

@@ -9,7 +9,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join, resolve } from 'path';
 import { cmdInit, getVersion } from './init.js';
-import { ProgressManager } from './progress.js';
+import { ProgressManager, resolvePlatformSpecDir } from './progress.js';
 
 // ── CLI 入口 ──
 
@@ -188,7 +188,7 @@ async function main() {
       await (await import('./setup.js')).cmdSetup(dir, { json, list: setupList });
       break;
     case 'progress': {
-      const pm = new ProgressManager();
+      const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(dir, specDir) });
       const progDir = specDir ? dir : resolveEffectiveDir(dir);
       const subCommand = filteredArgs[1];
       const stageIdx = filteredArgs.indexOf('--stage');
@@ -347,7 +347,7 @@ async function main() {
       const wtSubCmd = filteredArgs[1];
       const wtName = filteredArgs.slice(2).find(a => !a.startsWith('-'));
       const wm = new WorktreeManager({ cwd: dir });
-      const pm = new ProgressManager({ specDir });
+      const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(dir, specDir) });
 
       // isolation 写入 DB 的辅助函数
       async function _writeIsolationToDB(cwd, changeName, info) {
@@ -749,7 +749,7 @@ SillySpec platform — SillyHub 平台同步
         console.error('❌ 用法: sillyspec change-rename <旧变更名> <新变更名>');
         process.exit(1);
       }
-      const pm = new ProgressManager({ specDir });
+      const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(dir, specDir) });
       await pm.renameChange(dir, oldName, newName);
       break;
     }

package/src/progress.js

@@ -34,6 +34,24 @@ export function resolveSpecDir(startDir) {
   }
   return join(resolve(startDir), SPEC_DIR_NAME);
 }
+
+/**
+ * 平台感知的 specDir 解析（所有 CLI 子命令统一入口）。
+ * 优先级：显式 --spec-dir > 平台 pointer(.sillyspec-platform.json 的 specRoot) > resolveSpecDir(cwd)
+ * 修复 run 读 pointer、其它子命令读 legacy .sillyspec 的割裂。
+ */
+export function resolvePlatformSpecDir(cwd, explicitSpecDir = null) {
+  if (explicitSpecDir) return resolve(explicitSpecDir);
+  const pointerPath = join(resolve(cwd), '.sillyspec-platform.json');
+  if (existsSync(pointerPath)) {
+    try {
+      const ptr = JSON.parse(readFileSync(pointerPath, 'utf8'));
+      if (ptr.specRoot) return ptr.specRoot;
+    } catch { /* 损坏的 pointer 落到 fallback */ }
+  }
+  return resolveSpecDir(cwd);
+}
+
 const CHANGES_SUBDIR = 'changes';
 const GLOBAL_FILE = 'global.json';
 const CURRENT_VERSION = 3;

package/src/quick-recommend.js

@@ -0,0 +1,115 @@
+/**
+ * quick-recommend.js — quick 阶段多变更关联推荐打分
+ *
+ * 多变更场景下，quick 启动前用「脏文件 + 任务描述」双信号，
+ * 推测当前 quick 改动最可能归属哪些活跃变更，供交互式多选默认勾选。
+ *
+ * 纯函数 + 只读文件系统，无副作用，便于单测。
+ */
+import { join } from 'path'
+import { existsSync, readFileSync } from 'fs'
+import { parseFileChangeList } from './change-list.js'
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * 单个 token 是否命中上下文（参考 knowledge-match.js 的 keywordMatchesContext 思路）。
+ * - 过短（<2 字符）视为噪音
+ * - 非 ASCII（中文等）用子串匹配
+ * - ASCII 用词边界匹配，避免 "DB" 误命中 "dashboard"
+ */
+function tokenInContext(token, contextLower) {
+  const t = token.toLowerCase().trim()
+  if (t.length < 2) return false
+  if (/[^\x00-\x7f]/.test(t)) {
+    // 中文（等非 ASCII）：用 2-gram 重叠匹配。
+    // 避免整串子串匹配漏召回（如 token「修解析器」与 context「修复解析器」整串不等，
+    // 但共享 2-gram「解析」）。2-gram 足以抑制单字噪音，又能覆盖词形变化。
+    for (let i = 0; i <= t.length - 2; i++) {
+      if (contextLower.includes(t.slice(i, i + 2))) return true
+    }
+    return false
+  }
+  return new RegExp(`(^|[^a-z0-9])${escapeRegex(t)}([^a-z0-9]|$)`).test(contextLower)
+}
+
+/**
+ * 把任务描述切成用于匹配的 token（按空白/标点切分，过滤空串）。
+ * 保留中英文混排，不做分词——推荐只求召回，精确度靠用户最终勾选把关。
+ */
+function tokenizeDescription(desc) {
+  if (!desc) return []
+  return desc
+    .split(/[\s,，。、;；:：()（）\[\]{}"'`/\\|]+/)
+    .map(t => t.trim())
+    .filter(Boolean)
+}
+
+/** 读取变更 proposal.md 的全文（小写），用于任务描述信号匹配；缺失返回空串。 */
+function readProposalContext(specDir, changeName) {
+  const p = join(specDir, 'changes', changeName, 'proposal.md')
+  if (!existsSync(p)) return ''
+  try {
+    return readFileSync(p, 'utf8').toLowerCase()
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * 判断单个脏文件是否命中 design.md 声明的文件清单。
+ * 支持精确匹配 + 目录前缀匹配（design 可能写目录、脏文件是目录下文件，或反之）。
+ */
+function fileHitsList(dirtyFile, fileList) {
+  if (fileList.has(dirtyFile)) return true
+  for (const declared of fileList) {
+    if (declared === dirtyFile) continue
+    if (dirtyFile.startsWith(declared + '/') || declared.startsWith(dirtyFile + '/')) return true
+  }
+  return false
+}
+
+/**
+ * 推荐关联变更。
+ * @param {{ activeChanges: string[], specDir: string, baselineFiles?: string[], quickFiles?: string[], taskDescription?: string }} opts
+ * @returns {{ name: string, score: number, reasons: string[] }[]} 按 score 降序、同名升序
+ */
+export function recommendChanges({
+  activeChanges,
+  specDir,
+  baselineFiles = [],
+  quickFiles = [],
+  taskDescription = '',
+}) {
+  if (!activeChanges || activeChanges.length === 0) return []
+
+  const dirtyFiles = [...new Set([...baselineFiles, ...quickFiles])]
+    .filter(f => f && !f.startsWith('.sillyspec/'))
+  const descTokens = [...new Set(tokenizeDescription(taskDescription))]
+
+  const results = activeChanges.map(name => {
+    const reasons = []
+
+    // 信号 1：脏文件命中 design.md 文件变更清单
+    const fileList = parseFileChangeList(join(specDir, 'changes', name, 'design.md'))
+    if (fileList.size > 0 && dirtyFiles.length > 0) {
+      for (const f of dirtyFiles) {
+        if (fileHitsList(f, fileList)) reasons.push(`脏文件命中: ${f}`)
+      }
+    }
+
+    // 信号 2：任务描述 token 命中 proposal.md
+    const proposalCtx = readProposalContext(specDir, name)
+    if (proposalCtx && descTokens.length > 0) {
+      for (const t of descTokens) {
+        if (tokenInContext(t, proposalCtx)) reasons.push(`任务描述命中: ${t}`)
+      }
+    }
+
+    return { name, score: reasons.length, reasons }
+  })
+
+  return results.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+}

package/src/run.js

@@ -10,6 +10,7 @@ import { createRequire } from 'module'
 const require = createRequire(import.meta.url)
 import { ProgressManager } from './progress.js'
 import { SCAN_STATUS, POINTER_STATUS, isPointerCorrupted } from './constants.js'
+import { checkbox } from '@inquirer/prompts'
 
 /**
  * 清洗项目名：只保留 ASCII 字母/数字/横线/下划线/点，过滤中文和特殊字符。
@@ -703,6 +704,20 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
   if (changeName && promptText.includes('<change-name>')) {
     promptText = promptText.replace(/<change-name>/g, changeName)
   }
+  // 替换 <linked-changes> 占位符（quick 阶段：从 .runtime/quick-guard.json 读关联变更）
+  if (promptText.includes('<linked-changes>')) {
+    const specBaseLc = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    let linkedChanges = []
+    try {
+      const guardFile = join(specBaseLc, '.runtime', 'quick-guard.json')
+      if (existsSync(guardFile)) {
+        const guard = JSON.parse(readFileSync(guardFile, 'utf8'))
+        linkedChanges = Array.isArray(guard.linkedChanges) ? guard.linkedChanges : []
+      }
+    } catch {}
+    const display = linkedChanges.length > 0 ? linkedChanges.join(', ') : '（无）'
+    promptText = promptText.replace(/<linked-changes>/g, display)
+  }
   // 平台模式：注入路径覆盖指令
   if (platformOpts?.specRoot || platformOpts?.runtimeRoot) {
     const projectName = dbProjectName || basename(cwd)
@@ -1276,30 +1291,39 @@ export async function runCommand(args, cwd, specDir = null) {
   // runCommand 后续所有 .sillyspec/ 操作必须用 specBase
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
 
-  // 平台模式：清理旧版本残留的 cwd/.sillyspec/（防止源码污染）。
+  // 平台模式：首次接入时清理旧版本残留的 cwd/.sillyspec/（防止源码污染）。
   // ⚠️ 同 init.js：必须保护真实资产（changes/、projects/、sillyspec.db）。
+  // 只在「首次」执行一次——用 cwd 下的 .sillyspec-platform-cleaned 标记文件记录已处理，
+  // 后续每次 run 直接跳过，避免重复检查 + 红叉噪声（此清理不阻塞流程、不动真实资产）。
   if (platformOpts.specRoot) {
     const legacyDir = join(cwd, '.sillyspec')
-    if (existsSync(legacyDir)) {
-      let hasChanges = false;
-      try {
-        const cd = join(legacyDir, 'changes');
-        if (existsSync(cd)) hasChanges = readdirSync(cd).length > 0;
-      } catch {}
-      let hasProjects = false;
-      try {
-        const pd = join(legacyDir, 'projects');
-        if (existsSync(pd)) hasProjects = readdirSync(pd).length > 0;
-      } catch {}
-      const hasDb = existsSync(join(legacyDir, 'sillyspec.db'));
-
-      if (hasChanges || hasProjects || hasDb) {
-        console.error('❌ [sillyspec] 拒绝删除源码目录的 .sillyspec/：检测到真实资产。仅清理运行时残留，保留 worktrees 与进度状态。');
-        const { cleanupRuntimeResidue } = await import('./init.js')
-        cleanupRuntimeResidue(legacyDir);
-      } else {
-        try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
+    const cleanedMarker = join(cwd, '.sillyspec-platform-cleaned')
+    if (!existsSync(cleanedMarker)) {
+      if (existsSync(legacyDir)) {
+        let hasChanges = false;
+        try {
+          const cd = join(legacyDir, 'changes');
+          if (existsSync(cd)) hasChanges = readdirSync(cd).length > 0;
+        } catch {}
+        let hasProjects = false;
+        try {
+          const pd = join(legacyDir, 'projects');
+          if (existsSync(pd)) hasProjects = readdirSync(pd).length > 0;
+        } catch {}
+        const hasDb = existsSync(join(legacyDir, 'sillyspec.db'));
+
+        if (hasChanges || hasProjects || hasDb) {
+          // 真实资产存在：只清运行时残留（白名单保留 worktrees/进度），不整删
+          const { cleanupRuntimeResidue } = await import('./init.js')
+          cleanupRuntimeResidue(legacyDir);
+          console.log('ℹ️  [sillyspec] 源码目录 .sillyspec/ 含真实资产，已跳过整删，仅清理运行时残留（仅本次首次，后续不再提示）。');
+        } else {
+          try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
+          if (!existsSync(legacyDir)) console.log('🧹 已清理旧版本残留的源码 .sillyspec/ 目录');
+        }
       }
+      // 标记本 cwd 已做平台残留清理决策，后续 run 跳过（即使之后 .sillyspec/ 被重建也不误清）
+      try { writeFileSync(cleanedMarker, new Date().toISOString() + '\n') } catch {}
     }
   }
 
@@ -1317,11 +1341,23 @@ export async function runCommand(args, cwd, specDir = null) {
     inputText = flags[inputIdx + 1]
   }
 
-  // 解析 --change <name>
+  // 解析 --change <name>（quick 阶段支持逗号分隔多值，作为「关联变更」）
   let changeName = null
+  let linkedChanges = []
   const changeIdx = flags.indexOf('--change')
   if (changeIdx !== -1 && flags[changeIdx + 1]) {
     changeName = flags[changeIdx + 1]
+    if (stageName === 'quick') {
+      linkedChanges = changeName.split(',').map(s => s.trim()).filter(Boolean)
+      changeName = null
+    }
+  }
+  // quick 的 progress 键固定走 'default'：归属语义已由 linkedChanges 承担（→ quick-guard.json
+  // → <linked-changes> 占位符注入 prompt）。progress 不能走 pm.read(cwd, null) 的自动检测——
+  // 多活跃 change 项目里 quick 步骤进度会随活跃 change 增减在各 change/default 间漂移，
+  // 表现为 --done 时「回退」到更早步骤。固定 default 后无论是否带 --change 都稳定。
+  if (stageName === 'quick') {
+    changeName = 'default'
   }
 
   // 解析 --files a.js,b.js（quick 专用：显式声明 allowedFiles）
@@ -1363,6 +1399,16 @@ export async function runCommand(args, cwd, specDir = null) {
   // scan 元数据追踪（存储在 stageData.scanMeta 中，completeStep 通过 progress 访问）
 
   const pm = new ProgressManager({ specDir: specRoot })
+
+  // quick 阶段：多变更交互式选择关联变更（--change 未指定时）
+  if (stageName === 'quick' && linkedChanges.length === 0) {
+    linkedChanges = await resolveQuickLinkedChanges({
+      pm, cwd, specDir: specRoot, quickFiles,
+      taskDescription: inputText || '',
+      nonInteractive: isNonInteractive,
+    })
+  }
+
   let progress = await pm.read(cwd, changeName)
 
   if (!progress) {
@@ -1382,6 +1428,12 @@ export async function runCommand(args, cwd, specDir = null) {
     } else {
       // brainstorm 作为流程入口，自动生成变更名并初始化
       if (stageName === 'brainstorm') {
+        if (isDone) {
+          console.error('❌ --done 找不到变更进度数据。')
+          console.error('   请用 --change <变更名> 指定要完成的变更，')
+          console.error('   或先运行 sillyspec run brainstorm --change <变更名> 初始化。')
+          process.exit(1)
+        }
         const date = new Date().toISOString().slice(0, 10)
         const autoName = `${date}-new-change`
         console.log(`🔄 自动创建变更：${autoName}`)
@@ -1523,7 +1575,7 @@ export async function runCommand(args, cwd, specDir = null) {
   }
 
   // 默认：输出当前步骤
-  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts, { quickFiles, isAllowNew, isForceBaseline, isForceRescan })
+  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts, { quickFiles, isAllowNew, isForceBaseline, isForceRescan, linkedChanges })
 }
 
 /**
@@ -1538,6 +1590,73 @@ function resolveChangeNameAuto(cwd, specDir = null) {
   return null
 }
 
+/**
+ * quick 阶段多变更交互式选择关联变更。
+ * - 0 活跃变更 → []（仅记 QUICKLOG，不关联）
+ * - 1 活跃变更 → 默认关联它（保持现状友好，不弹交互）
+ * - ≥2 活跃变更 + 交互 → checkbox 多选（推荐项默认勾，空选 = 不关联）
+ * - ≥2 活跃变更 + 非交互 → []（不关联）+ 提示用 --change a,b
+ */
+async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles, taskDescription, nonInteractive }) {
+  let activeChanges = []
+  try {
+    activeChanges = await pm.listChanges(cwd)
+  } catch {
+    activeChanges = []
+  }
+  if (activeChanges.length === 0) return []
+  if (activeChanges.length === 1) return [activeChanges[0]]
+
+  if (nonInteractive || process.stdin.isTTY === false) {
+    console.log('💡 非交互环境，已默认不关联变更；如需关联请用 --change a,b')
+    return []
+  }
+
+  // 脏文件（推荐信号之一）
+  let baselineFiles = []
+  try {
+    const { execSync } = await import('child_process')
+    const gs = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
+    baselineFiles = gs.trim().split('\n').filter(Boolean)
+      .map(l => l.slice(3).trim())
+      .filter(f => !f.startsWith('.sillyspec/'))
+  } catch {}
+
+  // 推荐打分（脏文件 + 任务描述双信号）
+  let recommendations = []
+  try {
+    const { recommendChanges } = await import('./quick-recommend.js')
+    recommendations = recommendChanges({ activeChanges, specDir, baselineFiles, quickFiles, taskDescription })
+  } catch {
+    recommendations = activeChanges.map(name => ({ name, score: 0, reasons: [] }))
+  }
+  const scoreMap = new Map(recommendations.map(r => [r.name, r.score]))
+  const reasonMap = new Map(recommendations.map(r => [r.name, r.reasons]))
+  const recommendedSet = new Set(recommendations.filter(r => r.score > 0).map(r => r.name))
+
+  // 按推荐分降序展示
+  const ordered = [...activeChanges].sort((a, b) =>
+    (scoreMap.get(b) || 0) - (scoreMap.get(a) || 0) || a.localeCompare(b))
+
+  const choices = ordered.map(name => {
+    const reasons = reasonMap.get(name) || []
+    const isRec = recommendedSet.has(name)
+    return {
+      name: `${isRec ? '⭐ ' : '   '}${name}`,
+      value: name,
+      description: reasons.length > 0 ? reasons.join('；') : '无推荐信号',
+      checked: isRec,
+    }
+  })
+
+  console.log('🔗 检测到多个活跃变更，选择本次 quick 关联哪些（可多选；不勾选任何项 = 仅记 QUICKLOG，不关联变更）')
+  if (recommendedSet.size > 0) {
+    console.log('   ⭐ = 基于脏文件/任务描述推荐，已默认勾选')
+  }
+  const selected = await checkbox({ message: '关联变更（空格切换，回车确认）', choices })
+  return selected
+}
+
 async function runStage(pm, progress, stageName, cwd, changeName, skipApproval = false, platformOpts = {}, quickOpts = {}) {
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
   // 状态转换校验
@@ -1730,6 +1849,7 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
         allowedFiles,
         allowNew,
         forceBaseline,
+        linkedChanges: Array.isArray(quickOpts?.linkedChanges) ? quickOpts.linkedChanges : [],
         startedAt: new Date().toISOString(),
       }
       // 写入 quick-guard.json 供 worktree-guard hook 读取

package/src/stage-contract.js

@@ -144,8 +144,14 @@ function readIfExists(file) {
 }
 
 function warnMissingIds(warnings, ids, targetContent, targetName, sourceName) {
+  // 剥版本后缀（@vN）按基号词边界匹配：target 里写裸号 D-001 即视为引用了 D-001@V1
+  // 的当前版本（prompt 常裸号引用，旧版字面 includes("D-001@V1") 会批量误报）。
+  // 大小写不敏感：target 整体大写后比对。
+  const targetUpper = targetContent.toUpperCase()
   for (const id of ids) {
-    if (!targetContent.toUpperCase().includes(id)) {
+    const base = id.replace(/@V\d+$/, '')
+    const re = new RegExp(`\\b${base}\\b`)
+    if (!re.test(targetUpper)) {
       warnings.push(`${targetName} 未引用 ${sourceName} 中的 ${id}`)
     }
   }
@@ -281,9 +287,9 @@ function validateBrainstormOutputs(cwd, changeName, context = {}) {
       const design = readIfExists(join(changeDir, 'design.md'))
       const requirements = readIfExists(join(changeDir, 'requirements.md'))
       const tasks = readIfExists(join(changeDir, 'tasks.md'))
+      // decision 的天然引用落点是 design.md；requirements（需求按 FR 组织）与
+      // tasks（骨架，待 plan 展开）不强求逐条引用每个架构决策，否则批量误报。
       warnMissingIds(warnings, decisionIds, design, 'design.md', 'decisions.md')
-      warnMissingIds(warnings, decisionIds, requirements, 'requirements.md', 'decisions.md')
-      warnMissingIds(warnings, decisionIds, tasks, 'tasks.md', 'decisions.md')
     }
   }
 

package/src/stages/quick.js

@@ -9,12 +9,12 @@ export const definition = {
       prompt: `解析任务参数，加载项目上下文。
 
 ### 操作
-1. 检查是否携带 \`--change <变更名>\`，确定记录方式
+1. 检查关联变更（\`<linked-changes>\`，逗号分隔的变更名列表；显示「（无）」= 不关联变更），确定记录方式
 2. 理解任务：模糊则问一个问题确认
 3. 加载项目信息：\`cat .sillyspec/projects/*.yaml 2>/dev/null\`（了解项目结构和技术栈）
 4. 加载上下文：\`cat .sillyspec/docs/<project>/scan/CONVENTIONS.md 2>/dev/null\`
 5. 加载本地配置：\`cat .sillyspec/local.yaml 2>/dev/null\`（构建命令、测试命令、环境变量等）
-6. 如有 \`--change\`，加载设计文档：\`cat .sillyspec/changes/<change-name>/design.md 2>/dev/null\`（理解设计意图）
+6. 若有关联变更，加载每个变更的设计文档：\`cat .sillyspec/changes/<c>/design.md 2>/dev/null\`（理解设计意图）
 7. 如有需要，查询知识库：\`cat .sillyspec/knowledge/INDEX.md 2>/dev/null\`
 
 ### 模块文档加载
@@ -24,11 +24,14 @@ export const definition = {
 
 ### 创建任务记录（⛔ 此步骤不能跳过，没有 quicklog 记录 = 未完成）
 理解完任务后，**必须**立即创建记录文件，再输出任何其他内容：
+
+**A. 始终创建 QUICKLOG（无论是否关联变更）**
 1. 使用预注入的 git 用户名：\`<git-user>\`
-2. 无 \`--change\`：创建 .sillyspec/quicklog/QUICKLOG-\`<git-user>\`.md\`（已存在则追加），写入：
+2. 创建/追加 \`.sillyspec/quicklog/QUICKLOG-\`<git-user>\`.md\`，写入：
    \`\`\`
    ## ql-<YYYYMMDD>-<NNN>-<XXXX> | <now-datetime> | <一句话任务描述>
    状态：进行中
+   关联变更：<linked-changes>
    文件：<预估要改的文件>
    \`\`\`
    - ID 格式：\`ql-YYYYMMDD-NNN-XXXX\`
@@ -36,9 +39,16 @@ export const definition = {
    - 追加前扫描文件中已有的 \`ql-<当天日期>-\` 前缀的最大序号，+1 作为新序号
    - 每天从 001 开始，跨日重新计数
    - 此 ID 可被 design.md / plan.md / archive / module 变更索引引用
-3. 有 \`--change\`：在 \`.sillyspec/changes/<change-name>/tasks.md\` 追加未勾选的 task
 
-这样 Gate 检测到 .sillyspec/\` 下有变更，就不会拦截后续的代码修改。
+**B. 若关联变更（\`<linked-changes>\` 不为「（无）」）**
+3. 解析 \`<linked-changes>\`（逗号分隔的变更名列表，可能有多个 = 一次 quick 同时归属多个变更）
+4. 对**每个**变更 \`<c>\`：在 \`.sillyspec/changes/<c>/tasks.md\` 追加一条未勾选 task：
+   \`- [ ] <ql-ID> <一句话任务描述>\`（复用步骤 A 生成的同一个 ql-ID）
+   - 若 \`changes/<c>/\` 目录或 tasks.md 不存在，先 \`mkdir -p .sillyspec/changes/<c>\` 再创建 tasks.md
+   - 同一个 ql-ID 出现在 QUICKLOG 和所有关联变更的 tasks.md 中，便于交叉引用
+   - \`<linked-changes>\` 为「（无）」时跳过本步，仅保留 QUICKLOG
+
+这样 Gate 检测到 \`.sillyspec/\` 下有变更，就不会拦截后续的代码修改。
 
 ### 输出
 quicklog 已创建（必须放在输出的第一行确认）+ 任务理解 + 上下文摘要
@@ -72,27 +82,27 @@ quicklog 已创建（必须放在输出的第一行确认）+ 任务理解 + 上
       prompt: `Git 暂存并更新任务记录。
 
 ### 操作
-1. 查看 \`git status --porcelain\`，确认只包含本次 quick 相关文件
-2. 使用 \`git add -- <file...>\` 暂存本次 quick 实际修改的文件（不要 commit，由用户通过统一提交工具处理）
-   - 禁止使用 \`git add -A\`
-   - 不要暂存 quick 开始前就已存在的无关改动
-3. 更新 Step 1 创建的记录：
-   - 无 \`--change\`：找到对应 ql-ID 的条目，将「状态：进行中」改为「状态：已完成」，补充实际改动文件和结果摘要
-   - 有 \`--change\`：勾选 tasks.md 中对应的 task checkbox
-4. QUICKLOG 轮转：超过 500 行则重命名为 \`QUICKLOG-<USER>-YYYY-MM-DD.md\`（日期取最后一条记录的日期）。新文件从空开始，ql-ID 需扫描同目录所有 QUICKLOG 文件中当天最大序号 +1
-5. 如果发现项目特有的坑，追加到 \`.sillyspec/knowledge/uncategorized.md\`
-6. 任务比预期复杂 → 建议用完整流程
-
-### 模块文档同步
-7. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
-8. 对比本次修改的文件（\`git diff --name-only HEAD\`）与模块映射
-9. 如果命中模块 → 直接同步模块文档：
-   - 读取对应的 \`.sillyspec/docs/<project>/modules/<module>.md\`（如不存在则新建）
-   - 根据本次改动内容更新模块文档（正文描述当前状态，底部变更索引追加本次 ql-ID）
-   - 变更索引格式：\`- ql-YYYYMMDD-NNN-XXXX | <一句话描述>\`
-   - 写入模块文档
-   - 使用 \`git add -- <module-doc>\` 暂存更新的模块文件
-10. 未命中任何模块 → 跳过，不做额外操作
+1. 查看 \`git status --porcelain\`，确认只包含本次 quick 相关文件
+2. 使用 \`git add -- <file...>\` 暂存本次 quick 实际修改的文件（不要 commit，由用户通过统一提交工具处理）
+   - 禁止使用 \`git add -A\`
+   - 不要暂存 quick 开始前就已存在的无关改动
+3. 更新 Step 1 创建的记录：
+   - QUICKLOG：找到对应 ql-ID 的条目，将「状态：进行中」改为「状态：已完成」，补充实际改动文件和结果摘要（**始终做**，无论是否关联变更）
+   - 关联变更：对 Step 1 在每个 \`changes/<c>/tasks.md\` 写入的 ql-ID task，将其 checkbox 由 \`- [ ]\` 勾选为 \`- [x]\`；若 Step 1 未写入（用户事后才决定关联），则按 Step 1 的格式补写并直接勾选
+4. QUICKLOG 轮转：超过 500 行则重命名为 \`QUICKLOG-<USER>-YYYY-MM-DD.md\`（日期取最后一条记录的日期）。新文件从空开始，ql-ID 需扫描同目录所有 QUICKLOG 文件中当天最大序号 +1
+5. 如果发现项目特有的坑，追加到 \`.sillyspec/knowledge/uncategorized.md\`
+6. 任务比预期复杂 → 建议用完整流程
+
+### 模块文档同步
+7. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
+8. 对比本次修改的文件（\`git diff --name-only HEAD\`）与模块映射
+9. 如果命中模块 → 直接同步模块文档：
+   - 读取对应的 \`.sillyspec/docs/<project>/modules/<module>.md\`（如不存在则新建）
+   - 根据本次改动内容更新模块文档（正文描述当前状态，底部变更索引追加本次 ql-ID）
+   - 变更索引格式：\`- ql-YYYYMMDD-NNN-XXXX | <一句话描述>\`
+   - 写入模块文档
+   - 使用 \`git add -- <module-doc>\` 暂存更新的模块文件
+10. 未命中任何模块 → 跳过，不做额外操作
 
 ### 输出
 暂存确认 + 记录路径 + 模块文档同步结果（如有）`,

package/src/sync.js

@@ -10,6 +10,7 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
 import { join } from 'path';
+import { resolvePlatformSpecDir } from './progress.js';
 
 const LOCAL_YAML = '.sillyspec/local.yaml';
 const CHANGES_DIR = '.sillyspec/changes';
@@ -200,7 +201,7 @@ export class SyncManager {
     let progressData;
     try {
       const { ProgressManager } = await import('./progress.js');
-      const pm = new ProgressManager();
+      const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(this.cwd) });
       progressData = await pm.read(this.cwd, changeName);
     } catch (err) {
       console.warn(`[sync] 读取 progress 失败 (${changeName}): ${err.message}`);
@@ -225,7 +226,7 @@ export class SyncManager {
     // 更新 platform_last_sync
     try {
       const { ProgressManager } = await import('./progress.js');
-      const pm = new ProgressManager();
+      const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(this.cwd) });
       await pm._updatePlatformLastSync(this.cwd, changeName);
     } catch (err) {
       console.warn(`[sync] 更新 platform_last_sync 失败: ${err.message}`);
@@ -326,7 +327,7 @@ export class SyncManager {
     // 更新本地 approvals 表
     try {
       const { ProgressManager } = await import('./progress.js');
-      const pm = new ProgressManager();
+      const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(this.cwd) });
       await pm._updateApprovalStatus(this.cwd, changeName, result.status, result.reason);
     } catch (err) {
       console.warn(`[sync] 更新本地审批状态失败: ${err.message}`);

package/test/decision-ref-version.mjs

@@ -0,0 +1,85 @@
+/**
+ * 回归：decision 引用校验不应因「版本号有无 / 大小写」误报
+ *
+ * 现象：prompt 让用 D-xxx@v1，但 design/requirements 里常裸号引用 D-xxx。
+ *       旧校验器用 targetContent.includes("D-xxx@V1") 字面匹配 → 批量误报。
+ *       另：强制 decision 在 design+requirements+tasks 三处都引用，tasks 骨架不自然。
+ *
+ * 修 A：warnMissingIds 剥 @vN 后缀，按基号词边界匹配（裸号 D-001 视为引用 D-001@V1）。
+ * 修 B：brainstorm 阶段不再强制 requirements.md / tasks.md 引用每个 decision（decision 天然落点在 design）。
+ */
+import { runValidators } from '../src/stage-contract.js'
+import { mkdirSync, writeFileSync, rmSync } from 'fs'
+import { join } from 'path'
+import os from 'os'
+
+let failed = 0
+const fail = m => { failed++; console.log(`  ❌ FAIL: ${m}`) }
+const pass = m => console.log(`  ✅ PASS: ${m}`)
+
+function setup() {
+  const tmp = join(os.tmpdir(), `ss-ref-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`)
+  const cd = join(tmp, '.sillyspec', 'changes', 'tc')
+  mkdirSync(cd, { recursive: true })
+  return { tmp, cd }
+}
+
+console.log('=== decision 引用校验：版本号 / 裸号 / 三文件放宽 ===\n')
+
+{
+  const { tmp, cd } = setup()
+  // decisions：小写 @v1（测大小写不敏感）+ 一条 supersede 链
+  writeFileSync(join(cd, 'decisions.md'), [
+    '# Decisions', '',
+    '## D-001@v1: 决策一', 'status: accepted', 'priority: P2', '',
+    '## D-002@v1: 决策二', 'status: accepted', 'priority: P2', '',
+    '## D-003@v1: 旧', 'status: superseded', 'supersedes: ', '',
+    '## D-003@v2: 新', 'status: accepted', 'supersedes: D-003@v1', '',
+  ].join('\n'))
+  // design：裸号引用 D-001（小写原文）；不引用 D-002（真实缺口）；D-003@v2 裸号 D-003
+  writeFileSync(join(cd, 'design.md'), [
+    '# Design', '',
+    '## 文件变更清单', '- src/a.js 覆盖 D-001', '- src/b.py 涉及 D-003', '',
+    '## 风险登记', '- 风险', '',
+    '## 自审', '- 已审', '',
+  ].join('\n'))
+  writeFileSync(join(cd, 'proposal.md'), '# P\n\n## 不在范围内\n- x\n')
+  writeFileSync(join(cd, 'requirements.md'), '# Req\n\n- FR-01: 功能\n')
+  // tasks：骨架，不引用任何 decision
+  writeFileSync(join(cd, 'tasks.md'), '# Tasks\n\n## W1\n- [ ] （待 plan 展开）\n')
+
+  const r = runValidators('brainstorm', tmp, 'tc', {})
+  const ref = r.warnings.filter(w => w.includes('未引用'))
+  console.log('  产出未引用警告：')
+  for (const w of ref) console.log(`     - ${w}`)
+
+  // 修 A：裸号 D-001（小写）应被识别，design 不报 D-001
+  if (ref.some(w => w.includes('design.md') && w.includes('D-001'))) {
+    fail('design 裸号 D-001（小写）仍被报 —— 修A 未生效（版本号/大小写）')
+  } else pass('design 裸号 D-001 被识别（修A：剥版本号 + 大小写不敏感）')
+
+  // 修 A：D-003 裸号应匹配 active 的 D-003@V2（V1 被 supersede 排除）
+  if (ref.some(w => w.includes('design.md') && w.includes('D-003'))) {
+    fail('design 裸号 D-003 未匹配到 active D-003@V2')
+  } else pass('design 裸号 D-003 匹配 active D-003@V2（supersede 链正确）')
+
+  // 真实缺口保留：design 确实没引用 D-002
+  if (ref.some(w => w.includes('design.md') && w.includes('D-002'))) {
+    pass('design 未引用 D-002 正确报警（真实缺口保留）')
+  } else fail('design D-002 缺口未报警 —— 校验器被改得过松')
+
+  // 修 B：requirements / tasks 不再被强制引用每个 decision
+  if (ref.some(w => w.includes('requirements.md'))) {
+    fail('requirements 仍被强制引用 decision —— 修B 未生效')
+  } else pass('requirements 不再强制引用 decision（修B）')
+  if (ref.some(w => w.includes('tasks.md'))) {
+    fail('tasks 骨架仍被强制引用 decision —— 修B 未生效')
+  } else pass('tasks 骨架不再强制引用 decision（修B）')
+
+  rmSync(tmp, { recursive: true, force: true })
+}
+
+console.log('\n' + '='.repeat(50))
+console.log(failed === 0 ? '✅ 全部通过' : `❌ 失败 ${failed}`)
+console.log('='.repeat(50))
+if (failed > 0) process.exit(1)

package/test/platform-scan-p0.test.mjs

@@ -140,21 +140,32 @@ function assert(label, condition, detail) {
 
 // ── 测试 6：quick step 1 prompt 强制要求 quicklog ──
 {
-  const { definition } = await import('../src/stages/quick.js')
-  const step1Prompt = definition.steps[0].prompt
-  const step3Prompt = definition.steps[2].prompt
+  const { definition } = await import('../src/stages/quick.js')
+  const step1Prompt = definition.steps[0].prompt
+  const step3Prompt = definition.steps[2].prompt
 
   assert('quick step 1 包含 ⛔ 标记', step1Prompt.includes('⛔'))
   assert('quick step 1 包含「不能跳过」', step1Prompt.includes('不能跳过'))
-  assert('quick step 1 包含 quicklog 未创建 warning', step1Prompt.includes('quicklog 未创建'))
-  assert('quick step 1 输出要求 quicklog 第一行', step1Prompt.includes('第一行确认'))
-  assert('quick step 3 禁止 git add -A', step3Prompt.includes('禁止使用 `git add -A`'))
-  assert('quick step 3 使用 scoped git add', step3Prompt.includes('git add -- <file...>'))
+  assert('quick step 1 包含 quicklog 未创建 warning', step1Prompt.includes('quicklog 未创建'))
+  assert('quick step 1 输出要求 quicklog 第一行', step1Prompt.includes('第一行确认'))
+  assert('quick step 3 禁止 git add -A', step3Prompt.includes('禁止使用 `git add -A`'))
+  assert('quick step 3 使用 scoped git add', step3Prompt.includes('git add -- <file...>'))
+
+  // 新语义：QUICKLOG 始终记录 + 多变更关联
+  assert('quick step 1 含 <linked-changes> 占位符', step1Prompt.includes('<linked-changes>'))
+  assert('quick step 1 含「关联变更」措辞', step1Prompt.includes('关联变更'))
+  assert('quick step 1 QUICKLOG 始终创建', step1Prompt.includes('始终创建 QUICKLOG'))
+  assert('quick step 3 QUICKLOG 始终更新', step3Prompt.includes('始终做'))
 
   // run.js 审计包含 quicklog 检查
   const runSrc = await readFile(join(__dirname, '..', 'src', 'run.js'), 'utf8')
   assert('quick 审计检查 quicklog 目录存在', runSrc.includes('quicklog 目录不存在'))
   assert('quick 审计检查 quicklog 为空', runSrc.includes('quicklog 目录为空'))
+
+  // run.js 多变更交互入口 + 推荐打分
+  assert('run.js 含 resolveQuickLinkedChanges 交互入口', runSrc.includes('resolveQuickLinkedChanges'))
+  assert('run.js 含 recommendChanges 推荐打分', runSrc.includes('recommendChanges'))
+  assert('run.js 含 <linked-changes> 占位符注入', runSrc.includes('<linked-changes>'))
 }
 
 // ── 结果 ──

package/test/quick-recommend.test.mjs

@@ -0,0 +1,146 @@
+/**
+ * quick-recommend.test.mjs — 推荐打分单测
+ * 覆盖：脏文件命中 / 任务描述命中 / 双信号叠加 / 都不命中 / 空活跃变更 / 排序
+ */
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { recommendChanges } from '../src/quick-recommend.js'
+
+const passed = []
+const failed = []
+function assert(label, cond) {
+  ;(cond ? passed : failed).push(label)
+  if (!cond) console.error(`  ❌ ${label}`)
+}
+
+function setupTmp() {
+  const root = mkdtempSync(join(tmpdir(), 'qrec-'))
+  const specDir = join(root, '.sillyspec')
+  return { root, specDir, cleanup: () => rmSync(root, { recursive: true, force: true }) }
+}
+
+function writeChange(specDir, name, { designFiles = [], proposalText = '' } = {}) {
+  const dir = join(specDir, 'changes', name)
+  mkdirSync(dir, { recursive: true })
+  if (designFiles.length) {
+    const rows = designFiles.map((f) => `| 修改 | \`${f}\` | x |`).join('\n')
+    writeFileSync(
+      join(dir, 'design.md'),
+      `# ${name}\n\n## 文件变更清单\n\n| 操作 | 文件路径 | 说明 |\n|------|----------|------|\n${rows}\n`,
+    )
+  } else {
+    writeFileSync(join(dir, 'design.md'), `# ${name}\n\n无文件清单\n`)
+  }
+  writeFileSync(join(dir, 'proposal.md'), proposalText || `# ${name} proposal\n`)
+}
+
+// 测试 1：脏文件命中
+{
+  const { specDir, cleanup } = setupTmp()
+  try {
+    writeChange(specDir, 'change-a', { designFiles: ['src/foo.js', 'src/bar.js'] })
+    writeChange(specDir, 'change-b', { designFiles: ['docs/x.md'] })
+    const r = recommendChanges({
+      activeChanges: ['change-a', 'change-b'],
+      specDir,
+      baselineFiles: ['src/foo.js'],
+      taskDescription: '',
+    })
+    const a = r.find((x) => x.name === 'change-a')
+    const b = r.find((x) => x.name === 'change-b')
+    assert('脏文件命中：change-a score>0', a.score > 0)
+    assert('脏文件命中：change-a reasons 含「脏文件命中」', a.reasons.some((rr) => rr.startsWith('脏文件命中')))
+    assert('脏文件未命中：change-b score=0', b.score === 0)
+    assert('排序：高分在前', r[0].name === 'change-a')
+  } finally {
+    cleanup()
+  }
+}
+
+// 测试 2：任务描述命中
+{
+  const { specDir, cleanup } = setupTmp()
+  try {
+    writeChange(specDir, 'parser-fix', { proposalText: '# 解析器重构\n本变更修复解析器逻辑\n' })
+    writeChange(specDir, 'unrelated', { proposalText: '# 文档更新\n' })
+    const r = recommendChanges({
+      activeChanges: ['parser-fix', 'unrelated'],
+      specDir,
+      taskDescription: '修复解析器 bug',
+    })
+    const p = r.find((x) => x.name === 'parser-fix')
+    const u = r.find((x) => x.name === 'unrelated')
+    assert('描述命中：parser-fix score>0', p.score > 0)
+    assert('描述命中：reasons 含「任务描述命中」', p.reasons.some((rr) => rr.startsWith('任务描述命中')))
+    assert('描述未命中：unrelated score=0', u.score === 0)
+  } finally {
+    cleanup()
+  }
+}
+
+// 测试 3：双信号叠加
+{
+  const { specDir, cleanup } = setupTmp()
+  try {
+    writeChange(specDir, 'both', { designFiles: ['src/foo.js'], proposalText: '# 解析器\n修复解析器\n' })
+    const r = recommendChanges({
+      activeChanges: ['both'],
+      specDir,
+      baselineFiles: ['src/foo.js'],
+      taskDescription: '修解析器',
+    })
+    assert('双信号叠加 score=2', r[0].score === 2)
+    assert('双信号 reasons 数=2', r[0].reasons.length === 2)
+  } finally {
+    cleanup()
+  }
+}
+
+// 测试 4：都不命中
+{
+  const { specDir, cleanup } = setupTmp()
+  try {
+    writeChange(specDir, 'c', { designFiles: ['src/x.js'], proposalText: '# 其他\n' })
+    const r = recommendChanges({
+      activeChanges: ['c'],
+      specDir,
+      baselineFiles: ['src/unrelated.js'],
+      taskDescription: '别的任务',
+    })
+    assert('都不命中 score=0', r[0].score === 0)
+    assert('都不命中 reasons 为空', r[0].reasons.length === 0)
+  } finally {
+    cleanup()
+  }
+}
+
+// 测试 5：空活跃变更
+{
+  const r = recommendChanges({ activeChanges: [], specDir: '/tmp/x', baselineFiles: ['a.js'] })
+  assert('空活跃变更返回 []', Array.isArray(r) && r.length === 0)
+}
+
+// 测试 6：无 design/proposal 文件不报错（robustness）
+{
+  const { specDir, cleanup } = setupTmp()
+  try {
+    mkdirSync(join(specDir, 'changes', 'empty'), { recursive: true }) // 无任何文件
+    const r = recommendChanges({ activeChanges: ['empty'], specDir, baselineFiles: ['a.js'], taskDescription: 'x' })
+    assert('缺文件不报错 score=0', r[0].score === 0)
+  } finally {
+    cleanup()
+  }
+}
+
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${passed.length}`)
+console.log(`❌ 失败: ${failed.length}`)
+console.log(`${'='.repeat(50)}`)
+
+if (failed.length > 0) {
+  console.log('\n失败详情:')
+  for (const f of failed) console.log(`  ❌ ${f}`)
+}
+
+process.exit(failed.length > 0 ? 1 : 0)

package/test/stage-contract.test.mjs

@@ -167,10 +167,12 @@ writeFileSync(join(traceDir, 'requirements.md'), '# Requirements\n\n### FR-01: A
 writeFileSync(join(traceDir, 'tasks.md'), '- [ ] task-01: implement naming (D-001@v1)\n')
 
 const brainstormTrace = runValidators('brainstorm', traceRoot, 'trace')
-if (brainstormTrace.ok === true && brainstormTrace.warnings.some(w => w.includes('requirements.md 未引用') && w.includes('D-001@V1'))) {
-  console.log('✅ brainstorm validator 检测到 requirements.md 缺少 D-001@v1 引用')
+// 修 B：requirements.md / tasks.md 不再强制引用每个 decision（decision 天然落点 design.md）。
+// 此处 requirements.md 没有 D-001，但 design.md 有，故不应报 requirements 未引用。
+if (brainstormTrace.ok === true && !brainstormTrace.warnings.some(w => w.includes('requirements.md 未引用'))) {
+  console.log('✅ brainstorm validator 不再强制 requirements.md 引用 decision（修B：落点 design）')
 } else {
-  console.log('❌ brainstorm validator 未检测到 requirements.md 缺少 D-001@v1 引用', brainstormTrace)
+  console.log('❌ brainstorm validator 仍强制 requirements.md 引用 decision', brainstormTrace.warnings)
   failed++
 }