sillyspec 3.27.2 → 3.27.5

package/src/stage-contract.js

@@ -5,13 +5,15 @@
  * CLI 不再相信 prompt 完成，completeStep 后必须过 validator。
  */
 
-import { existsSync, readdirSync, readFileSync } from 'fs'
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'fs'
 import { join, basename } from 'path'
 import { safeGit } from './git-helper.js'
+import { nowWallClock } from './datetime.js'
 import { detectChangeRisk, checkIntegrationEvidence, VERIFICATION_NEEDS, RISK_LEVEL_CAUSES } from './change-risk-profile.js'
 import { SCAN_REQUIRED_DOCS, AUXILIARY_STAGES } from './constants.js'
 import { evaluateRules } from './stage-contract-engine.js'
 import { getRule } from './stage-contract-spec.js'
+import { backfillFrontmatter } from './scan-postcheck.js'
 import { parseAllowedPaths } from './stages/plan-postcheck.js'
 
 /**
@@ -163,6 +165,31 @@ function parseDecisionRecords(content) {
   return records
 }
 
+/**
+ * decisions.md 缺 author/created_at header 时自动补齐（坑 decisions-header-late-warning，
+ * 2026-08-24 用户反馈二期：brainstorm step8 模板曾自带无 frontmatter 的 decisions 样例——
+ * agent 照抄生成必缺 header，拖到后续环节才提示。模板已修；本函数兜存量：gate 前幂等补
+ * 机械字段（author=git user / created_at=now），与 scan-fix-headers 同一 backfillFrontmatter 实现。
+ * @param {string} changeDir - changes/<name> 目录
+ * @returns {boolean} true = 本次补齐过（false = 无 decisions.md / header 已齐 / 写失败）
+ */
+export function ensureDecisionDocHeader(changeDir) {
+  try {
+    const decisionPath = join(changeDir, 'decisions.md')
+    if (!existsSync(decisionPath)) return false
+    const content = readFileSync(decisionPath, 'utf8')
+    let author = 'unknown'
+    const gitUser = safeGit(changeDir, ['config', 'user.name'])
+    if (gitUser && gitUser.value) author = String(gitUser.value).trim() || 'unknown'
+    const r = backfillFrontmatter(content, { author, createdAt: nowWallClock() })
+    if (!r.changed) return false
+    writeFileSync(decisionPath, r.content)
+    console.log(`ℹ️  已自动补齐 decisions.md 缺失的 author/created_at header: ${decisionPath}`)
+    return true
+  } catch { /* 补齐失败不阻断 gate——decisions 内容校验照常进行 */ }
+  return false
+}
+
 function extractCurrentDecisionIds(content) {
   const records = parseDecisionRecords(content)
   if (records.length === 0) return extractIds(content, 'D')
@@ -286,6 +313,27 @@ function validateBrainstormOutputs(cwd, changeName, context = {}) {
         }
       }
     }
+
+    // ── 风险判级提前提示（坑 risk-first-use-opaque，2026-08-24 用户实证）──
+    // verify --done 的 risk gate 既往只在流程末段暴露，首次使用者撞墙后才知道 frontmatter
+    // risk_level 覆盖通道。design --done 即按同款 detectChangeRisk 预判一次（此时 plan.md 尚未
+    // 产出，verify 时会连 plan 一起重判、级别可能上浮——本提示 advisory 不作为定论）：
+    // 高危关键词命中 / 存在否定抑制 → 透出判级结果 + 覆盖指引，把机制可见性提前到 design 阶段。
+    {
+      const profile = detectChangeRisk({ designContent: content })
+      if (['integration-critical', 'deployment-critical'].includes(profile.level) && !profile.explicit) {
+        warnings.push(
+          `[risk] 本次 design 判级 ${profile.level}（命中关键词：${profile.triggers.join('、')}）——verify --done 将强制真实集成证据门控。` +
+          `若属关键词误伤（实际未触碰 daemon/session/启动入口），现在就在 design.md frontmatter 加 risk_level: <真实等级>（如 unit-sufficient）显式覆盖，免得到 verify 阶段才发现而返工。`
+        )
+      }
+      if ((profile.suppressedTriggers || []).length > 0) {
+        warnings.push(
+          `[risk] 关键词命中 ${profile.suppressedTriggers.join('、')} 已被同句否定语境抑制，当前判级 ${profile.level}。` +
+          `若实际涉及对应改动，请在 design.md frontmatter 声明高危级（抑制可审计，防静默降级逃证据门控）。`
+        )
+      }
+    }
   }
 
   const decisionsFile = join(changeDir, 'decisions.md')
@@ -461,11 +509,22 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
       planContent: readIfExists(join(changeDir, 'plan.md')),
     })
     const conclusion = extractVerifyConclusion(verify)
+    // ── 否定抑制审计（坑 risk-negation-blindness）──
+    // 关键词命中被同句否定语境抑制而不参与判级时必须透出：抑制是把双刃剑（「本次不新增
+    // daemon」真豁免 vs 靠堆否定措辞静默降级逃证据门控），这里让每次抑制可见可核对；
+    // frontmatter risk_level 仍是双向权威覆盖通道。
+    if ((changeRiskProfile.suppressedTriggers || []).length > 0) {
+      warnings.push(
+        `[${changeRiskProfile.level}] 风险判级：关键词命中 ${changeRiskProfile.suppressedTriggers.join(', ')} 已被同句否定语境（不/未/无/避免…）抑制，未参与判级。` +
+        `若本变更实际涉及跨进程/状态机/启动入口改动，请在 design.md frontmatter 加 risk_level: integration-critical（或 deployment-critical）显式声明或提供真实集成证据——抑制可审计，不许用来静默降级。`
+      )
+    }
     if (['integration-critical', 'deployment-critical'].includes(changeRiskProfile.level)) {
       // 关键词误伤早期引导（坑2，FR-02）：命中高危关键词且无 frontmatter risk_level 时，
       // 无条件透出 frontmatter 覆盖指引（不依赖 conclusion / evidence），让 agent 早期即可
-      // 判断是否属误判并显式覆盖，而非撞到 evidence gate 末尾才发现出路③。遵 6417a27：不做
-      // body 否定语境扫描，只走 frontmatter 显式覆盖通道。
+      // 判断是否属误判并显式覆盖，而非撞到 evidence gate 末尾才发现出路③。含否定语境的
+      // 命中已在 detectChangeRisk 内被同句否定抑制（见 change-risk-profile.js NEGATION_CUES），
+      // 此处命中的都是无否定语境的真命中；仍误伤的走 frontmatter 显式覆盖通道。
       if (!changeRiskProfile.explicit) {
         warnings.push(
           `[${changeRiskProfile.level}] 本次变更被关键词判级（命中：${changeRiskProfile.triggers.join(', ')}）。` +
@@ -485,7 +544,12 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
         // 的结构化证据，作为附加匹配文本——有回执不依赖 agent 措辞；无回执维持原字面匹配
         let receiptText = ''
         try {
-          const receiptPath = join(cwd, '.sillyspec', '.runtime', 'verify-services.receipt.json')
+          // 回执按变更分片（坑 verify-pids-cross-session-kill：原单份被并行会话后写覆盖），
+          // 优先读本变更分片，兼容旧单份名（升级过渡期 receipt.change 过滤仍生效）
+          const runtimeDir = join(cwd, '.sillyspec', '.runtime')
+          const receiptPath = existsSync(join(runtimeDir, `verify-services-${changeName}.receipt.json`))
+            ? join(runtimeDir, `verify-services-${changeName}.receipt.json`)
+            : join(runtimeDir, 'verify-services.receipt.json')
           if (existsSync(receiptPath)) {
             const receipt = JSON.parse(readFileSync(receiptPath, 'utf8'))
             if (receipt && (receipt.reapedPidCount || 0) > 0 && (!receipt.change || receipt.change === changeName)) {

package/src/stages/archive.js

@@ -44,9 +44,17 @@ export const definition = {
     },
     {
       name: 'sync-module-docs',
-      // 坑 verify-archive-flow-pitfalls 坑4：缺 requiresWait 时 --continue --answer 会直接标 completed、
-      // agent 无机会按 module-impact.md 写入模块卡片。加 requiresWait 使 --continue 确认后回到本步执行写入
-      requiresWait: true,
+      // conditionalWait（坑 archive-subconfirm-redundant，2026-08-23 实证：requiresWait 硬门强制
+      // 三段式 --wait → --continue --answer → --done，与 verify 文档同步阻断门、归档移动前死信
+      // 校验、下一步「确认归档 --confirm」四层确认重复，交互碎。改 conditionalWait（brainstorm-auto
+      // 同款先例）：常规同步直接写入 + --done（agent 写入动作在 --done 前完成，坑 verify-archive-
+      // flow-pitfalls 坑4 的「无机会写入」不回归）；仅异常（needs_review/未映射/标记缺失）才 --wait
+      // 请用户裁决。用户确认收敛到「确认归档 --confirm」一处。
+      conditionalWait: true,
+      repeatableWait: true,
+      maxWaitRounds: 3,
+      waitReason: '等待用户裁决模块文档同步异常',
+      waitOptions: ['确认写入', '跳过同步'],
       prompt: `根据 module-impact.md 同步更新模块索引和卡片文档。
 
 ### ⚠️ 核心原则：结构化事实改 _module-map.yaml，语义解释改模块卡片
@@ -109,20 +117,52 @@ created_at: <now-datetime>
 <!-- MANUAL_NOTES_END -->
 \`\`\`
 
-4. 展示所有更新内容（diff 摘要），**必须暂停等待用户确认**
-   - 调用：\`sillyspec run archive --wait --reason "等待用户确认模块文档同步" --options "确认写入,跳过同步" --output "diff 摘要"\`
-5. **只有用户通过 --continue --answer "确认写入" 后才写入文件**
-   - 写入 _module-map.yaml 和受影响的模块卡片
-6. 用户拒绝时，不写入，但提示"module-impact.md 已保留，可稍后手动同步"
-7. 回填 module-impact.md 的"更新结果"表格，区分目标：
+4. 展示所有更新内容（diff 摘要），按同步状态分流：
+   - **常规**（无 needs_review 影响、无 unmapped 模块、人工备注标记齐全）→ **直接写入** _module-map.yaml 和受影响的模块卡片，diff 摘要写入 --output 后 --done（本步不单独弹确认——用户确认收敛到下一步「确认归档 --confirm」，该步展示同一 diff 摘要）
+   - **异常**（含 needs_review 影响项 / unmapped 模块 / 人工备注标记缺失或重复 / 覆盖会丢失手动维护字段）→ 暂停请用户裁决：
+     \`sillyspec run archive --wait --reason "等待用户裁决模块文档同步异常" --options "确认写入,跳过同步" --output "diff 摘要 + 异常说明"\`
+     用户 --continue --answer "确认写入" 后写入；"跳过同步" 则不写入，提示 "module-impact.md 已保留，可稍后手动同步"
+5. 回填 module-impact.md 的"更新结果"表格，区分目标：
    - 目标列写 "\`_module-map.yaml: <module-id>\`" 或 "\`modules/<module-id>.md\`"
-8. **同步完成后**，如需刷新 \`_module-map.yaml\` 索引：\`sillyspec modules rebuild --force\`（默认 dry-run 只预览不写；\`--force\` 才覆盖，但会清空 tags/entrypoints/main_symbols/depends_on/used_by 等手动维护字段——与 archive-impact 的「人工备注保护」约束冲突，仅当手动字段已并入骨架或可接受覆盖时用；优先手动更新 dependencies.md / 模块卡片）
+6. **同步完成后**，如需刷新 \`_module-map.yaml\` 索引：\`sillyspec modules rebuild --force\`（默认 dry-run 只预览不写；\`--force\` 才覆盖，但会清空 tags/entrypoints/main_symbols/depends_on/used_by 等手动维护字段——与 archive-impact 的「人工备注保护」约束冲突，仅当手动字段已并入骨架或可接受覆盖时用；优先手动更新 dependencies.md / 模块卡片）
 
 ### 输出
-已更新的文件路径列表 + 用户确认状态`,
+已更新的文件路径列表 + diff 摘要（异常时附裁决结果）`,
       outputHint: '模块文档更新结果',
       optional: false
     },
+    {
+      name: 'decision-distill 决策提炼',
+      // conditionalWait（同 sync-module-docs 先例）：常规提炼直接写入 + --done；仅异常（rejected
+      // 条目缺否决理由/复潮条件 → distillIntoKnowledge 返回 needsWait 非空）才 --wait 请用户裁决
+      // （补录后重跑幂等 / 跳过该条）。勿引入 requiresWait 硬门——与下一步「确认归档 --confirm」
+      // 重复确认（坑 archive-subconfirm-redundant）。
+      conditionalWait: true,
+      repeatableWait: true,
+      maxWaitRounds: 3,
+      waitReason: '等待用户裁决 rejected 决策缺字段',
+      waitOptions: ['补录后继续', '跳过该条'],
+      prompt: `读取变更 decisions.md，把有实现影响的决策提炼进决策知识库（提炼/幂等/INDEX 路由行本体在 CLI 纯函数 src/decision-distill.js，本步只接线，勿手工改写条目格式）。
+
+### 操作
+1. 定位参数：changeDir = \`.sillyspec/changes/<change-name>\`（decisions.md 所在——本步在「确认归档」移动目录之前，仍在原位）；knowledgeRoot = \`.sillyspec/knowledge\`；headHash = \`git rev-parse --short HEAD\`（落条目「最近确认」）
+2. 调用纯函数 \`distillIntoKnowledge(changeDir, knowledgeRoot, headHash)\`，按返回的 \`{ written, skipped, needsWait }\` 分流（见第 3 点）：
+   - 能解析到 sillyspec 源码/安装位置时（如 sillyspec 仓内 dogfood）直接 import 调用：\`node --input-type=module -e "import { distillIntoKnowledge } from './src/decision-distill.js'; console.log(JSON.stringify(distillIntoKnowledge(changeDir, knowledgeRoot, headHash), null, 2))"\`
+   - 解析不到（consumer 仓库无源码，node import 会 ERR_MODULE_NOT_FOUND）→ 按其语义执行：解析 D-xxx@vN 条目；入选规则 = 任意 type 的 status=rejected 留痕 + 五类 type（architecture/compatibility/boundary/definition/process）且 status∈{confirmed,accepted} 提炼 implemented，type=scope 不入选；条目幂等落 \`.sillyspec/knowledge/decisions/<模块域>.md\`（同 ID 同版本重写不重复追加、@vN+1 整段替换旧版并注 supersedes；「模块域」缺失按 impacts 路径与 _module-map.yaml paths 前缀匹配兜底，仍未中归 unmapped）；implemented 条目写「状态：implemented + 锚点：<src 路径:行号，未记录则填"未记录"> + 最近确认：<headHash> + 理由：<一句话>」，rejected 条目写「状态：rejected + 否决理由： + 复潮条件：」；\`knowledge/INDEX.md\` 的 decisions 路由行（\`- <域>|decision|决策 → [decisions/<域>.md](decisions/<域>.md)\`）幂等增删
+3. 分流规则：
+   - **常规**（needsWait 为空且 written 非空）→ 写入已由函数完成，written 摘要（decisions/<域>.md × D-xxx@vN × append/update/supersede）写入 --output 后直接 --done（本步不单独弹确认——用户确认收敛到下一步「确认归档 --confirm」）
+   - **needsWait 非空**（rejected 条目缺否决理由/复潮条件，该条目未写盘、其余条目照常提炼）→ 暂停请用户裁决：
+     \`sillyspec run archive --wait --reason "等待用户裁决 rejected 决策缺字段" --options "补录后继续,跳过该条" --output "needsWait 描述 + 已提炼摘要"\`
+     - 「补录后继续」→ 按 needsWait 描述在 changes/<change-name>/decisions.md 补齐缺失的否决理由/复潮条件，重跑第 2 步（幂等，重跑安全）
+     - 「跳过该条」→ 该条目不入库，--output 注记跳过原因后 --done
+   - **零输出**（skipped 非空 = 无 decisions.md / 无入选条目）→ 不创建任何文件、不动 INDEX，--output 注一句 skipped 原因后直接 --done（同 docs-debt 无债零输出原则）
+4. 降级：调用或解析异常（模块加载失败 / decisions.md 结构异常抛错）→ warn 记录异常摘要后跳过本步 --done（best-effort，同 agent-session-log 先例），不阻断归档——决策提炼失败不挡归档移动
+
+### 输出
+已提炼条目清单（decisions/<域>.md × D-xxx@vN × action）或零输出/跳过/降级原因`,
+      outputHint: '决策提炼结果',
+      optional: false
+    },
     {
       name: '确认归档',
       prompt: `确认归档内容，由 CLI 执行目录移动。
@@ -147,7 +187,8 @@ created_at: <now-datetime>
 1. 如果 \`.sillyspec/ROADMAP.md\` 存在，标记对应 Phase 为已完成
 2. \`git add .sillyspec/changes/archive/\` — 暂存归档结果（archive/ 下仅本次归档新增，不会裹挟 changes/ 下其他活跃变更；不要 commit，由用户通过统一提交工具处理）
 3. \`git add .sillyspec/docs/<project>/modules/\` — 暂存模块文档更新（如有；精确到本次同步的模块文档，勿 add 整个 .sillyspec/docs/）
-4. 确认 sillyspec.db 中该变更已不再 active（确认归档步骤由 CLI 调用 unregisterChange）
+4. \`git add .sillyspec/knowledge/decisions/\` — 暂存决策知识库更新（如有；decision-distill 步骤的提炼产物，精确到 decisions 子目录，勿 add 整个 .sillyspec/knowledge/；不要 commit，由用户通过统一提交工具处理）
+5. 确认 sillyspec.db 中该变更已不再 active（确认归档步骤由 CLI 调用 unregisterChange）
 
 ### 输出
 归档完成确认 + 累积规范统计`,

package/src/stages/brainstorm-auto.js

@@ -154,6 +154,13 @@ AC-011: 不涉及业务规则/产品范围/默认行为/用户可见行为变更
 #### decisions.md（必填，写入变更根目录 \`decisions.md\`）
 记录所有决策：
 \`\`\`markdown
+---
+author: <git-user>
+created_at: <now-datetime>
+---
+
+# 决策记录（Decisions）
+
 ## D-001@v1: 决策短标题
 - type: architecture | boundary | compatibility | ...
 - priority: P0 | P1 | P2

package/src/stages/brainstorm.js

@@ -46,6 +46,7 @@ export const definition = {
    - 有匹配模板 → 询问是否基于模板
    - 无相关内容 → 跳过，不输出
 8. 查询知识库：\`cat {SPEC_ROOT}/knowledge/INDEX.md 2>/dev/null\`（无索引则跳过）——按需求关键词命中条目时读取对应知识文件；known-issues/已知坑要在方案期就规避，不要等 execute 的命中报告才发现
+   - decisions 库路由：INDEX.md \`## Decisions\` 段的路由行（\`decisions/<域>.md\`，由归档时决策提炼幂等维护）命中时，读取对应决策文件——rejected 条目须看到否决理由：除非复潮条件明确满足，否则不重新提出该方案（防复潮）；确要复潮时在本变更 decisions.md 记新版本条目（D-xxx@vN+1）说明依据。CLI 预注入的否决决策提示（无命中则为空）：{DECISION_HITS}
 
 ### 模块匹配方法
 读取 _module-map.yaml 后，根据用户描述的需求关键词，匹配相关模块：
@@ -339,6 +340,11 @@ design.md 第一行标题必须用中文：# 设计文档（Design）— <变更
    - 每条记录必须有稳定版本 ID：D-001@v1、D-002@v1 ...
    - 若后续 Design Grill 修正该决策，新记录使用 D-001@v2，并写明 supersedes: D-001@v1
    - 每条记录必须包含：type、status、source、question、answer、normalized_requirement、impacts、evidence、priority
+   - 九字段之外可另加四个可选字段，按需填写、不强制全填（旧格式决策记录缺这些字段不受影响）：
+     - 锚点：决策落点的主文件，格式 <src 路径>:<行号或符号>（status=confirmed 时必填）
+     - 模块域：决策涉及的模块 ID，取自 \`{SPEC_ROOT}/docs/<project>/modules/_module-map.yaml\`，可多个、用逗号分隔
+     - 否决理由：一句话说明为何否决（status=rejected 时必填）
+     - 复潮条件：什么前提下可重新考虑该决策（status=rejected 时必填）
    - 长期术语只在 archive/scan 时再提升到 \`{SPEC_ROOT}/docs/<project>/glossary.md\`
 4. 格式自检（只查章节齐全；语义一致性/可行性/YAGNI 不在本步查，交给下一步 Design Grill 独立审查）：
    - design.md 含全部必填章节（背景/设计目标/非目标/总体方案/文件变更清单/接口定义/风险登记）
@@ -566,6 +572,11 @@ created_at: <now-datetime>
 
 ### decisions.md 格式要求（仅在有 Grill/重大决策时生成）
 \`\`\`markdown
+---
+author: <git-user>
+created_at: <now-datetime>
+---
+
 # 决策记录（Decisions）
 
 ## D-001@v1: 决策短标题

package/src/stages/doctor.js

@@ -327,9 +327,155 @@ timeout 5 which docker 2>/dev/null && echo "✅ Docker 可用" || echo "ℹ️ D
       outputHint: '模块文档健康状态',
       optional: false
     },
+    {
+      name: '决策待复核检查',
+      prompt: `检查决策知识库（knowledge/decisions/）的待复核状态（advisory，不阻断）。
+
+### 操作
+运行 docs-check 决策规则族（锚点存在性 + behind 阈值复核，task: 2026-08-23-adopt-harness-practices）：
+
+\`\`\`bash
+# 定位 sillyspec 源码根：sillyspec 本仓 dogfood 优先用仓内源码（全局安装版本可能落后于本检查项）；
+# 其余场景经 bin 符号链接解析到安装包根；均不可得时降级跳过
+SRC_ROOT=""
+if grep -q '"name": *"sillyspec"' package.json 2>/dev/null && [ -f "src/docs-check.js" ]; then
+  SRC_ROOT="$PWD"
+else
+  BIN=$(command -v sillyspec)
+  if [ -n "$BIN" ]; then
+    SRC_ROOT=$(node -e 'const fs=require("fs");const p=fs.realpathSync(process.argv[1]).replace(/\\\\/g,"/");const i=p.lastIndexOf("/bin/sillyspec.js");console.log(i===-1?"":p.slice(0,i));' "$BIN")
+  fi
+fi
+if [ -z "$SRC_ROOT" ]; then
+  echo "ℹ️ 无法定位 sillyspec 源码（非 sillyspec 仓且未安装 sillyspec 命令），跳过决策待复核检查"
+else
+  node --input-type=module -e '
+import { readFileSync, existsSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+let specBase = process.argv[2];
+if (existsSync(".sillyspec-platform.json")) {
+  try { const p = JSON.parse(readFileSync(".sillyspec-platform.json", "utf8")); if (p.specRoot) specBase = p.specRoot; } catch {}
+}
+const mod = await import(pathToFileURL(process.argv[1] + "/docs-check.js"));
+const r = await mod.runDecisionRules({ projectRoot: process.cwd(), specBase: specBase });
+if (r.empty) {
+  console.log("ℹ️ 决策库未初始化（" + specBase + "/knowledge/decisions/ 不存在）——冷启动空库，变更归档时 decision-distill 自动积累（R-02）");
+} else if (r.findings.length === 0) {
+  console.log("✅ 决策待复核：无信号（" + r.implemented + "/" + r.entries + " 条 implemented，behind 阈值 " + r.threshold + "）");
+} else {
+  console.log("⚠️ 决策待复核清单（" + r.findings.length + " 条，advisory 不阻断——D-003）:");
+  for (const f of r.findings) console.log("   - " + f.message);
+}
+if (r.exempted.length > 0) console.log("ℹ️ 另有 " + r.exempted.length + " 条经 known_failures decisions.* 键豁免: " + r.exempted.map(e => e.key).join(", "));
+' "$SRC_ROOT/src" "$PWD/.sillyspec" || echo "⚠️ 决策规则执行失败（降级跳过，不影响其他检查项）"
+fi
+\`\`\`
+
+同步骤追加 CLI 版本漂移检测（D-002 并入既有检查段不新增步骤；D-004 git/version 双轨；advisory 不阻断）——检测全局安装的 sillyspec 流程引擎与当前仓源码是否脱节：
+
+\`\`\`bash
+# 安装根独立解析：command -v sillyspec → realpath → 向上找 name=sillyspec 的 package.json
+# 勿复用上方 SRC_ROOT——sillyspec 仓场景它被 dogfood 分支强制指向当前仓，比较恒等（Grill 实证陷阱）
+node --input-type=module -e '
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const run = (cmd, args) => { try { return execFileSync(cmd, args, { encoding: "utf8", timeout: 8000, stdio: ["ignore", "pipe", "pipe"] }).trim(); } catch { return ""; } };
+const pkgOf = (dir) => { try { return JSON.parse(readFileSync(join(dir, "package.json"), "utf8")); } catch { return null; } };
+const short = (h) => h.slice(0, 7);
+
+try {
+  const cur = pkgOf(process.cwd());
+  if (!cur || cur.name !== "sillyspec") process.exit(0); // 当前仓非 sillyspec（消费项目）→ 静默跳过
+  const bin = run("sh", ["-c", "command -v sillyspec"]);
+  if (!bin) process.exit(0); // 无全局安装 → 静默跳过
+  let installRoot = "";
+  try {
+    let dir = dirname(realpathSync(bin));
+    for (;;) {
+      const p = pkgOf(dir);
+      if (p && p.name === "sillyspec") { installRoot = dir; break; }
+      const up = dirname(dir);
+      if (up === dir) break;
+      dir = up;
+    }
+  } catch {}
+  if (!installRoot) { console.log("⚠️ CLI 版本漂移检测降级：sillyspec 命令存在但未定位到安装根（" + bin + "），跳过比较，不阻断其余检查项"); process.exit(0); }
+  if (installRoot === process.cwd()) process.exit(0); // 安装根=当前仓（npm link 自身）→ 恒等不误报
+
+  // 双轨比较（D-004）：
+  // git 轨——安装根有 .git（开发态：npm link / file: 链接）→ rev-parse HEAD 双仓 + remote origin 归一化同源判定
+  // version 兜底轨——安装根无 .git（安装态：registry 安装 / npm i -g . 拷贝，npm 恒排除 .git）→ 比较双仓 package.json version
+  // 盲区声明（R-04）：同 version 不同 commit 的源码热改不检测——version 轨只在版本号变更时感知；
+  // git 轨管开发态、version 轨管安装态，两轨并集覆盖主流形态
+  const inst = pkgOf(installRoot) || {};
+  const curVer = cur.version || "?";
+  const instVer = inst.version || "?";
+  const warn = (detail) => console.log("⚠️ CLI 版本漂移：" + detail + "——全局安装的流程引擎与当前仓源码脱节，归档等流程行为可能滞后（2026-08-23 归档实证踩坑：五步版 archive 驱动六步定义，旧引擎驱动新定义），建议同步（安装根 git pull 或在 sillyspec 仓 npm i -g .）后重跑流程（advisory，不阻断）");
+
+  if (existsSync(join(installRoot, ".git"))) {
+    // remote 归一化：https/ssh 归一、.git 后缀剥离、host 小写——同源才可比较（异源 fork 无从判定 → 静默）
+    const normRemote = (u) => {
+      if (!u) return "";
+      let s = u.trim();
+      if (s.indexOf("://") === -1) {
+        const scp = s.match(/^([^@\\/]+@)([^:\\/]+):(.+)$/); // scp 形态 git@host:owner/repo.git
+        if (scp) s = "https://" + scp[2] + "/" + scp[3];
+      }
+      s = s.replace(/^ssh:\\/\\//, "https://").replace(/^git:\\/\\//, "https://");
+      const m = s.match(/^[a-zA-Z][a-zA-Z0-9+.-]*:\\/\\/(.*)$/);
+      const rest = m ? m[1] : s;
+      const slash = rest.indexOf("/");
+      let host = slash === -1 ? rest : rest.slice(0, slash);
+      const tail = slash === -1 ? "" : rest.slice(slash);
+      const at = host.indexOf("@");
+      if (at !== -1) host = host.slice(at + 1); // 剥 userinfo（ssh://git@… / https://token@…）
+      let out = "https://" + host.toLowerCase() + tail;
+      out = out.replace(/\\/+$/, "");
+      if (out.endsWith(".git")) out = out.slice(0, -4);
+      return out;
+    };
+    const curHead = run("git", ["-C", process.cwd(), "rev-parse", "HEAD"]);
+    const instHead = run("git", ["-C", installRoot, "rev-parse", "HEAD"]);
+    if (!curHead || !instHead) { console.log("⚠️ CLI 版本漂移检测降级：git 轨 rev-parse 失败（当前仓=" + (curHead ? "ok" : "fail") + " 安装根=" + (instHead ? "ok" : "fail") + "），跳过比较，不阻断其余检查项"); process.exit(0); }
+    const curRemote = normRemote(run("git", ["-C", process.cwd(), "remote", "get-url", "origin"]));
+    const instRemote = normRemote(run("git", ["-C", installRoot, "remote", "get-url", "origin"]));
+    if (curRemote && instRemote && curRemote !== instRemote) process.exit(0); // 非同源 → 静默
+    if (curHead !== instHead) warn("全局安装 " + installRoot + "（version " + instVer + " / commit " + short(instHead) + "）与当前仓（version " + curVer + " / HEAD " + short(curHead) + "）不一致");
+    // 同 commit → 一致静默
+  } else if (instVer !== curVer) {
+    warn("全局安装 " + installRoot + "（version " + instVer + "）与当前仓（version " + curVer + "）不一致（安装根无 .git，走 version 兜底轨）");
+    // 同 version → 一致静默（同 version 不同 commit 热改盲区见上方 R-04 注释）
+  }
+} catch (e) {
+  console.log("⚠️ CLI 版本漂移检测降级：" + (e && e.message ? e.message : String(e)) + "（不阻断其余检查项）");
+}
+' || echo "⚠️ CLI 版本漂移检测降级：脚本执行失败（不阻断其余检查项）"
+\`\`\`
+
+### 输出格式
+\`\`\`
+📋 决策待复核
+✅ 决策待复核：无信号（3/5 条 implemented，behind 阈值 10）
+⚠️ 决策待复核清单（1 条，advisory 不阻断——D-003）:
+   - 「D-012@v1」决策待复核：锚定模块 docs-consistency 在最近确认 a1b2c3d 后源码已前进 15 commit，超阈值 10
+ℹ️ 决策库未初始化 —— 冷启动空库（R-02）
+
+⚠️ CLI 版本漂移：全局安装 /path/to/sillyspec（version 3.26.0 / commit a1b2c3d）与当前仓（version 3.27.3 / HEAD e4f5a6b）不一致——全局安装的流程引擎与当前仓源码脱节，建议同步后重跑流程（仅漂移时输出；一致/非 sillyspec 仓/无全局安装/安装根=当前仓均静默）
+\`\`\`
+
+### 注意
+- 本检查项为 advisory（只 ⚠️ 不 ❌），不作为修复阻断项
+- 待复核的复核再确认由用户完成：确认决策仍成立后，把条目「最近确认」更新为当前 HEAD——不要自动改写
+- 全程只读，不修改 knowledge/decisions/ 下任何文件
+- CLI 版本漂移检测（同步骤追加段，D-002/D-004）同为 advisory：漂移时一行警告；一致、非 sillyspec 仓消费场景、无全局安装、安装根=当前仓（npm link 自身）均静默；探测失败降级单行，不阻断其余检查项`,
+      outputHint: '决策待复核清单',
+      optional: false
+    },
     {
       name: '汇总报告',
-      prompt: `汇总前四步的所有检查结果，生成最终的自检报告。
+      prompt: `汇总前面各步的所有检查结果，生成最终的自检报告。
 
 ### 输出格式
 \`\`\`
@@ -350,6 +496,12 @@ timeout 5 which docker 2>/dev/null && echo "✅ Docker 可用" || echo "ℹ️ D
 ## 外部依赖
 ✅ Context7 MCP — 已配置
 ⚠️  grep.app — 不可达
+
+## 决策待复核（advisory）
+⚠️ 「D-012@v1」— 锚定模块源码 behind 15 超阈值 10（复核后更新「最近确认」）
+
+## CLI 版本漂移（advisory）
+⚠️ 全局安装 sillyspec（version 3.26.0 / commit a1b2c3d）与当前仓（version 3.27.3 / HEAD e4f5a6b）不一致 — 同步后重跑流程
 \`\`\`
 
 ### 要求
@@ -370,8 +522,12 @@ timeout 5 which docker 2>/dev/null && echo "✅ Docker 可用" || echo "ℹ️ D
 - 孤儿目录 → 确认后 \`rm -rf .sillyspec/changes/<目录名>\`
 - Maven 私服不可达 → 检查 VPN、settings.xml 配置、私服状态
 - Git remote 不可达 → 检查网络、SSH key 或凭证
+- CLI 版本漂移（全局安装落后于当前仓）→ 在 sillyspec 仓执行 \`npm i -g .\` 重新全局安装（或安装根 git pull），同步后重跑流程
 - 工具未安装 → 给出安装命令（如 \`brew install maven\`）
 
+**状态错乱补 postmortem（advisory，不强制）：**
+若本次自检检出状态错乱或不一致（sillyspec.db 阶段状态与实际产出不符、孤儿目录、僵尸 quick 会话等）并已修复，建议补一条轻量 postmortem 记录进 QUICKLOG（走 quick 流程或既有条目正文核对），根因块内按列表行写四子字段：\`- 现象：\`（错乱表现）、\`- 根因：\`（深层原因）、\`- 护栏：\`（防再犯措施）、\`- 证据：\`（可追溯路径——\`sillyspec agent-log --json\` 输出的本地会话日志 jsonl 路径、相关变更 review.json、verify-result.md）。护栏结论经人工确认后归入 \`.sillyspec/knowledge/known-issues.md\`——走既有 knowledge 追加链路（先入 knowledge/uncategorized.md，经知识整理确认后归类），不新建链路不新建命令。
+
 每条建议格式：
 \`\`\`
 💡 修复：<问题描述>

package/src/stages/execute.js

@@ -11,6 +11,9 @@ import { parseRepo } from './plan-postcheck.js'
 // parseTaskRegistry（注册表同口径）——双向引用均为函数声明 + 调用时解引（无模块初始化期
 // 交叉求值），ESM live binding 下安全；两边都是纯读函数，无副作用序问题。
 import { resolveChangeModuleCards } from '../module-resolve.js'
+// 决策锚点触碰事实（2026-08-24-decision-touch-cli-drift task-01，W-A 主渲染点 D-003）：
+// changedFiles 口径与 {DOCS_DEBT} 现算同源（collectExecuteChangedFiles 唯一实现，勿双写）
+import { collectExecuteChangedFiles, computeDecisionTouches, renderDecisionTouchFacts } from '../docs-debt.js'
 
 /**
  * 任务注册表解析（2026-08-20-task-truth-unify D-001@v1：tasks.md 唯一任务真相）。
@@ -913,20 +916,43 @@ ${indexLines}
     }
   } catch { /* 热区提取 best-effort：失败不注入 */ }
 
+  // ── 决策锚点触碰事实（W-A 主渲染点，D-003）：changedFiles 口径与 run/prompt.js {DOCS_DEBT}
+  // 现算同源——collectExecuteChangedFiles（porcelain 未提交 ∪ baseline..HEAD）唯一实现，勿双写。
+  // 单过流程前缀第 4 步渲染 {DOCS_DEBT} 时 changedFiles 恒空，Wave 步（重入/续跑时已含前置
+  // Wave 已提交变更）才是触碰事实的主呈现时机。advisory：无触碰 section=''（模板字节不变，
+  // 零输出零阻断）；≤5 条截断（R-05）。best-effort：失败不注入不阻断。
+  let decisionTouchSection = ''
+  try {
+    if (changeDir) {
+      const dtSpecBase = path.dirname(path.dirname(changeDir))
+      const { changedFiles } = collectExecuteChangedFiles({
+        specBase: dtSpecBase,
+        changeName: path.basename(changeDir),
+        cwd: options.cwd || process.cwd(),
+      })
+      const dtFacts = renderDecisionTouchFacts(computeDecisionTouches(changedFiles, path.join(dtSpecBase, 'knowledge')).touches)
+      if (dtFacts) {
+        decisionTouchSection = `\n### 决策锚点触碰（CLI 算，advisory——改到锚定文件时复核对应决策）\n\n${dtFacts}\n`
+      }
+    }
+  } catch { /* 触碰事实 best-effort：失败不注入不阻断 */ }
+
   // 子代理要点 4 / Wave 开始前第 1 条：模块表 / 热区存在时换成「按注入内容执行」版文案，
   // 否则保留原文（零回归——无 map / 无 design 的项目 prompt 不变）
   const moduleDocPoint = moduleSection
     ? '4. **模块卡分级**：把上方「模块卡分级」表中该 task 命中的卡路径写进子代理 prompt（细卡整读；粗大卡只读「契约摘要/注意事项/定位」节）——勿让子代理按目录漫游或整读根层大卡'
-    : '4. 如存在模块文档（.sillyspec/docs/*/modules/），按需读取涉及模块的 <module>.md 参考接口约定和数据流'
+    : '4. 如存在模块文档（{SPEC_ROOT}/docs/*/modules/），按需读取涉及模块的 <module>.md 参考接口约定和数据流——读主仓路径（CLI 已替换为绝对路径），不要读 worktree 副本'
   const waveStartItem1 = hasDesignHotzone
     ? '1. 「非目标」「兼容策略」两节已由 CLI 提取附在上方「design.md 热区」——**不要再整读 design.md**；需要其余章节时按热区下方行号索引精准读取（Read offset/limit）。确保子代理不超范围、不破坏旧逻辑'
     : '1. 读取 design.md 的「非目标」与「兼容策略」章节（如存在），确保子代理不超范围、不破坏旧逻辑'
 
-  // 构建任务摘要（不再内联完整蓝图，减少上下文污染）
+  // 构建任务摘要（不再内联完整蓝图，减少上下文污染）。
+  // 任务卡路径用 {SPEC_ROOT} 占位符（坑 worktree-spec-artifact-misplace）：子代理 cwd=worktree 时
+  // 相对路径会解析到 worktree 的 .sillyspec 副本；占位符经 CLI 替换为主仓绝对路径。
   const taskSummary = wave.tasks.map((t, ti) => {
     const taskNum = String(t.index || (ti + 1)).padStart(2, '0')
     const taskRelPath = changeDir
-      ? `.sillyspec/changes/${path.basename(changeDir)}/tasks/task-${taskNum}.md`
+      ? `{SPEC_ROOT}/changes/${path.basename(changeDir)}/tasks/task-${taskNum}.md`
       : `task-${taskNum}.md`
     const fileInfo = t.file ? ` (${t.file})` : ''
     return `task-${taskNum}: ${t.name}${fileInfo} → ${taskRelPath}`
@@ -1025,7 +1051,7 @@ ${workdirLines}
 \`\`\`
 
 ### 注意
-蓝图文件（tasks.md / design.md / proposal.md / requirements.md / tasks/task-XX.md）在主工作区 .sillyspec/changes/<change>/ 下，它们不在跨仓仓也不在 worktree 中。读取蓝图时使用主工作区路径，不要拼接到 worktree / 跨仓仓路径下。
+蓝图文件（tasks.md / design.md / proposal.md / requirements.md / tasks/task-XX.md）在主工作区 {SPEC_ROOT}/changes/<change>/ 下（CLI 已替换为主仓绝对路径），它们不在跨仓仓也不在 worktree 中。读取蓝图时使用主工作区路径，不要拼接到 worktree / 跨仓仓路径下。
 `
   } else {
     worktreeSection = (worktreePath)
@@ -1044,7 +1070,7 @@ ${workdirLines}
 \`\`\`
 
 ### 注意
-蓝图文件（tasks.md / design.md / proposal.md / requirements.md）在主工作区 .sillyspec/changes/<change>/ 下，它们可能不在 worktree 中。读取蓝图时使用主工作区路径，不要拼接到 worktree 路径下。
+蓝图文件（tasks.md / design.md / proposal.md / requirements.md）在主工作区 {SPEC_ROOT}/changes/<change>/ 下（CLI 已替换为主仓绝对路径），它们可能不在 worktree 中。读取蓝图时使用主工作区路径，不要拼接到 worktree 路径下；同理，spec 流程产物（module-impact.md / knowledge 条目 / 模块文档）只写主仓 {SPEC_ROOT}，绝不写进 worktree 副本。
 `
       : ''
   }
@@ -1114,7 +1140,7 @@ ${taskSummary}
 
 {{include: testcase-design}}
 
-${designHotzone}
+${designHotzone}${decisionTouchSection}
 ### Wave 开始前
 ${waveStartItem1}
 2. 读取 plan.md 了解全局任务划分和依赖关系