sillyspec 3.27.1 → 3.27.5

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 了解全局任务划分和依赖关系
@@ -1143,6 +1169,7 @@ ${taskList}
    - 最后一个 Wave 完成后做一次全量编译验证
    - 用户明确要求编译时
 4. 每个任务完成后：
+   - **在 worktree 内 git add -A && git commit -m "<task-NN 摘要>"**（坑 subagent-uncommitted-newfile-apply3way，2026-08-22 实证：纯新增文件不 commit 时 apply 的 git apply --3way 报 "does not exist in index" 直接炸——未 commit 的新文件不在 base commit 也不在 index，patch 生成取不到。commit 后 base..HEAD diff 完整、apply 顺畅，review.json 的 head 也有真实锚点）
    - **先写 review.json 再勾选 checkbox**（见下方 Task Review Gate）
    - **既跑 lint check 也跑 formatter**：凡变更涉及的源码跑项目的 lint 检查 **和** 格式化（如 \`ruff format\` / \`prettier --write\`），不要只跑 check——只 check 不 format 会把格式问题留到 commit 时被 pre-commit hook 拦截（worktree 内二进制可能缺失，先 \`which <bin>\` 确认，缺则 \`uv tool install\` / \`uv sync\`）
    - 记录改动文件和测试结果

package/src/stages/plan-postcheck.js

@@ -19,6 +19,7 @@ import { tmpdir } from 'os'
 import jsYaml from 'js-yaml'
 import { parseFileChangeList, pathMatches } from '../change-list.js'
 import { getRule } from '../stage-contract-spec.js'
+import { TASKCARD_PLACEHOLDERS } from '../taskcard-placeholders.js'
 import { validateScriptCommands } from './cmd-existence.js'
 
 // ═══════════════════════════════════════════════════════════════
@@ -173,7 +174,12 @@ export function parseHeadCommit(content) {
 export function parseRepoRegistry(yamlText) {
   const reg = new Map()
   if (!yamlText) return reg
-  const lines = yamlText.split('\n')
+  // CRLF 归一（坑 register-repo-crlf-idempotent-loop，2026-08-23 实证：Windows 下 agent Write
+  // 工具/编辑器写出的 local.yaml 带 \r——条目正则 `(.*)$` 的 `.` 不匹配 \r、`$` 又要求真串尾，
+  // 行尾残留 \r 时整条失配 → 空 Map → MultiRepoContext fail-closed 报「未注册」→ register-repo
+  // 幂等跳过不落盘 → 死循环。同文件 parseAllowedPaths/parseDependsOn/parseBaseCommit 均有此
+  // 归一，本函数是唯一缺口）
+  const lines = String(yamlText).replace(/\r\n?/g, '\n').split('\n')
   let startIdx = -1
   for (let i = 0; i < lines.length; i++) {
     if (/^repos:\s*(?:#.*)?$/.test(lines[i])) { startIdx = i; break }
@@ -356,6 +362,28 @@ function parseTaskWavesFromPlan(planPath) {
   return map
 }
 
+/**
+ * 收集任务卡 depends_on → Map<taskId, deps>（Wave 重排 / plan-adopt-waves 共用）。
+ * taskId 优先取卡内 frontmatter id:（与文件名解耦——文件名 task-01 但 id 改写过时以 id 为准）。
+ * @param {string} tasksDir - changes/<name>/tasks 目录
+ * @returns {Map<string, string[]>}
+ */
+export function collectTaskDepMap(tasksDir) {
+  const depMap = new Map()
+  if (!existsSync(tasksDir)) return depMap
+  for (const file of readdirSync(tasksDir).filter(f => /^task-\d+\.md$/.test(f))) {
+    const content = readFileSync(pJoin(tasksDir, file), 'utf8')
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/)
+    let taskId = file.replace('.md', '')
+    if (fmMatch) {
+      const idMatch = fmMatch[1].match(/^id:\s*(.+)/m)
+      if (idMatch) taskId = idMatch[1].trim()
+    }
+    depMap.set(taskId, parseDependsOn(content))
+  }
+  return depMap
+}
+
 /**
  * 本地一致性校验器
  * @param {string} changeDir - 变更目录
@@ -448,7 +476,9 @@ export function validateBlueprintConsistency(changeDir) {
       if (ts.length > 1) {
         errors.push(
           `路径 ${p} 被 Wave ${w} 内 ${ts.length} 个 task 修改: ${ts.join(', ')} — 同 Wave 任务 execute 强制并行（execute.js:603），` +
-          `子代理会互相覆盖该文件。解法：把它们拆到不同 Wave（串行）。`
+          `子代理会互相覆盖该文件。解法：把它们拆到不同 Wave（串行）。` +
+          `（注：quick 阶段对同文件并发只提示不阻断——那是轻量流程无并行子代理、最坏后果 git 可分离；` +
+          `此处硬拦是因并行覆盖不可自动恢复，两阶段宽严不同是设计使然）`
         )
       }
     }
@@ -1000,6 +1030,22 @@ export function validatePlanFeasibility(changeDir, projectRoot = null) {
     if (!hasVerify) errors.push(fsRule.data.messageVerify.replaceAll('${id}', taskId || file))
     if (!hasConstraints) errors.push(fsRule.data.messageConstraints.replaceAll('${id}', taskId || file))
 
+    // 5b. 骨架占位符拦截（坑 taskcard-placeholder-slip，2026-08-24 用户实证：task 卡留成
+    // 空骨架、九字段「存在性」全过，直到人工审计才发现）。占位标记是 taskcard.js 生成的
+    // 封闭集合（TASKCARD_PLACEHOLDERS 同源导出），精确匹配；verify 字段的占位命令刻意
+    // 不拦（可能是真实 tsc 命令）。占位符视同缺字段，与 9 字段缺失同级 error。
+    // 先剥 HTML 注释再匹配——骨架尾部注释自身罗列了占位标记清单（填充指引），不剥会把
+    // 已填充卡的注释误判成占位残留。
+    const contentNoComments = content.replace(/<!--[\s\S]*?-->/g, '')
+    const placeholderHits = TASKCARD_PLACEHOLDERS.filter(p => contentNoComments.includes(p.marker))
+    if (placeholderHits.length > 0) {
+      errors.push(
+        (fsRule.data.messagePlaceholder || '${id}: task 卡仍是未填充的生成骨架')
+          .replaceAll('${id}', taskId || file)
+          .replaceAll('${fields}', placeholderHits.map(p => p.field).join('、'))
+      )
+    }
+
     // 6. acceptance best-effort 字段 grep（D-05 软约束，warning 不阻断）
     // 从 acceptance 文本提取 snake_case/camelCase 标识符，grep allowed_paths 指向的源文件；
     // 找不到 → warning（给 LLM 审查提线索，不阻断 execute）。宁漏不噪：只取 snake/camel，
@@ -1246,18 +1292,7 @@ export async function executePlanPostcheck(context) {
   const tasksDir = pJoin(changeDir, 'tasks')
   if (existsSync(tasksDir)) {
     const taskFiles = readdirSync(tasksDir).filter(f => /^task-\d+\.md$/.test(f))
-    const depMap = new Map()
-
-    for (const file of taskFiles) {
-      const content = readFileSync(pJoin(tasksDir, file), 'utf8')
-      const fmMatch = content.match(/^---\n([\s\S]*?)\n---/)
-      let taskId = file.replace('.md', '')
-      if (fmMatch) {
-        const idMatch = fmMatch[1].match(/^id:\s*(.+)/m)
-        if (idMatch) taskId = idMatch[1].trim()
-      }
-      depMap.set(taskId, parseDependsOn(content))
-    }
+    const depMap = collectTaskDepMap(tasksDir)
 
     const { waves, error: topoError } = topoSortWaves(depMap)
     if (topoError) {
@@ -1270,8 +1305,10 @@ export async function executePlanPostcheck(context) {
       console.log(`     Wave ${i + 1}: ${wave.join(', ')}`)
     })
 
-    // 比较 plan.md 现有 Wave 分组
-    if (waves.length > 1 && taskFiles.length > 1) {
+    // 比较 plan.md 现有 Wave 分组 + 依赖方向硬校验（坑 wave-dep-direction-unchecked，
+    // 2026-08-24 用户反馈二期：主控手排 Wave 与拓扑比对只警告不阻断，而真正的正确性违规
+    // ——depends_on 落同 Wave / 后置 Wave——此前完全没有校验）
+    if (taskFiles.length > 0) {
       const planPath = pJoin(changeDir, 'plan.md')
       if (existsSync(planPath)) {
         const planContent = readFileSync(planPath, 'utf8')
@@ -1303,6 +1340,30 @@ export async function executePlanPostcheck(context) {
           }
           if (currentWaveTasks) existingWaves.push(currentWaveTasks)
 
+          // ── 依赖方向硬校验 ──
+          // Wave 契约（execute.js Wave 要点 1）：同一 Wave 的子代理强制并行；有依赖的 task
+          // 必须落在其依赖的后置 Wave。同 Wave / 后置 Wave 引用都是正确性违规（并行破坏依赖
+          // / 顺序颠倒），硬拦；仅分组数差异（手工过度串行化）合法，保留下方 warning。
+          const waveOf = new Map()
+          existingWaves.forEach((ws, i) => { for (const t of ws) waveOf.set(t, i) })
+          const directionViolations = []
+          for (const [taskId, deps] of depMap) {
+            const w = waveOf.get(taskId)
+            if (w === undefined) continue // 卡片未列入任何 Wave → 由 validatePlanForExecute 覆盖校验兜底
+            for (const dep of deps) {
+              const dw = waveOf.get(dep)
+              if (dw === undefined) continue // 依赖不存在的 task → feasibility depends_on 引用校验兜底
+              if (dw === w) directionViolations.push(`${taskId} depends_on ${dep}，但两者同在 Wave ${w + 1}（同 Wave 强制并行，依赖被破坏）`)
+              else if (dw > w) directionViolations.push(`${taskId} depends_on ${dep}，但 ${dep} 在后置 Wave ${dw + 1}（顺序颠倒）`)
+            }
+          }
+          if (directionViolations.length > 0) {
+            console.error(`\n❌ Wave 依赖方向违规（${directionViolations.length} 处）：`)
+            for (const v of directionViolations) console.error(`   ${v}`)
+            console.error('   解法：sillyspec plan-adopt-waves --change <变更名> 一键按 depends_on 拓扑重排 plan.md Wave 段，或手动调整分组')
+            throw new Error('planPostcheck: Wave 依赖方向违规（depends_on 同 Wave / 后置 Wave）——' + directionViolations.join('；'))
+          }
+
           const sameStructure = waves.length === existingWaves.length &&
             waves.every((w, i) => {
               const a = [...w].sort().join(',')
@@ -1313,8 +1374,8 @@ export async function executePlanPostcheck(context) {
           if (sameStructure) {
             console.log('  ✅ Wave 分组与拓扑排序一致，无需更新 plan.md')
           } else {
-            console.log('  ⚠️  Wave 分组与拓扑排序不一致，建议手动调整 plan.md')
-            console.log('     拓扑排序建议的 Wave 分组见上方')
+            console.log('  ⚠️  Wave 分组与拓扑排序不一致（依赖方向已校验合法——手工比拓扑更细的串行化是安全做法，可保持现状）')
+            console.log('     标准分组见上方 📊；如需对齐：sillyspec plan-adopt-waves --change <变更名>（重排 plan.md Wave 段并同步任务总表 W 列）')
           }
         }
       }

package/src/stages/plan.js

@@ -473,6 +473,9 @@ ${taskList}
 \`\`\`
 你是一个专注的 TaskCard 生成器。你的任务是为指定 batch 生成全部 TaskCard。
 
+## ⚠️ 格式形态（第一眼必读，坑 taskcard-body-section-rework）
+TaskCard 的契约字段全部在 **frontmatter**（首对 --- 包裹的 YAML 键值对：id/title/title_zh/allowed_paths/goal/...）——**不是 body 章节**（## 标题下的段落）。goal 是 frontmatter 的 \`goal: >\` 多行标量、implementation/acceptance/verify/constraints 是 frontmatter 的列表项；写成 body 章节（\`## goal\` / \`## Goal\` 等）会三组校验全挂返工。先跑骨架命令再 Edit 填充，骨架即正确形态。
+
 ## 输入
 - 变更目录：${changeDir}
 - 当前时间：<now-datetime>（frontmatter 的 created_at 使用此值）
@@ -507,6 +510,7 @@ ${taskcardTemplate}
 - 所有 task 都被某个 batch 覆盖、无遗漏、无重复
 - frontmatter 字段分两组对照（与 plan-postcheck / taskcard-rules.md 同源，三处清单以此为准）：
   - **硬校验 9 字段**（缺失 plan-postcheck 直接报错阻断）：id、title、title_zh、allowed_paths、goal、implementation、acceptance、verify、constraints
+  - **占位符硬拦**（骨架占位值未替换视同缺字段，plan --done 报错阻断）：FR-XX、D-XXX、src/example/file.ts、一句话说明这个 task、具体步骤 1、可验证的验收条件 1、边界约束 1
   - **规范约定 5 字段**（应填但缺失只影响规范性，不阻断）：author、created_at、priority、depends_on、blocks
 - 每个 task 总长度 20~40 行
 - **一致性自查**：

package/src/stages/quick.js

@@ -66,6 +66,9 @@ step 3 --done 审计会把 src 核心文件（CLI / 状态机 / 注入框架等
 ### 输出
 实现摘要 + 修改文件列表
 
+### 📌 末步预告：结果摘要四字段（step3 --done 硬校验，缺一被拒）
+下一步（step3）--done 必须给四字段结果摘要（推荐 \`--req/--cause/--solution/--result\` 四参数，CLI 自动合成；兼容 \`--output "需求：… 根因：… 方案：… 结果：…"\`）。其中「结果：验证情况（测试数 / lint / typecheck / 部署状态）」的素材在**本步**产生——实现摘要里请顺手记下具体验证数据（如「3 个单测通过、lint 0 告警」），step3 直接引用，避免到收尾时回忆不起来或被硬校验打回重跑。
+
 ### 铁律
 - 不要修改无关文件
 - 不要编造不存在的 CLI 子命令
@@ -97,7 +100,9 @@ sillyspec run quick --done --change <id> --req "一句话语义化短标题（
 结果：验证情况（测试数 / lint / typecheck / 部署状态）
 \`\`\`
 
-⚠️ **「需求：」（= --req）就是 QUICKLOG 条目标题**——CLI 提取该字段、截到首个标点（，。；,;）、超 80 字再截断。写成完整需求长句会被截成语义不完整的状语前半段（如「在 X 时，…」标题只剩「在 X 时」），事后还得手改。一句话说清改了什么（如「登录限流修复——INCR 计数误清」），需求背景放「根因：/方案：」字段。旧形式正文内避免嵌套全角冒号（标签后紧接嵌套冒号会被拆分判定缺字段）——这正是四参数形式消灭的事故面。
+⚠️ **「需求：」（= --req）就是 QUICKLOG 条目标题**——CLI 提取该字段、截到首个标点（，。；,;）、超 80 字再截断。写成完整需求长句会被截成语义不完整的状语前半段（如「在 X 时，…」标题只剩「在 X 时」），事后还得手改。一句话说清改了什么（如「登录限流修复——INCR 计数误清」），需求背景放「根因：/方案：」字段。单行旧形式的风险仅在「正文里再次出现顶层标签字样」——需求：/根因：/方案：/结果： 字样前导恰是空白或句末标点（。；！？）时，会被边界扫描误当真实字段边界（错位/缺字段被拒）——这正是四参数形式消灭的事故面。注意区分：根因块内以列表行形态出现的嵌套子字段（\`- 现象：\` \`- 根因：\` \`- 护栏：\` \`- 证据：\`）是**合法形态**——「- 」前缀不构成顶层标签、不参与拆分判定，顶层四字段边界不受影响（postmortem 用法见下方可选提示）。
+
+> 💡 **可选（非必填）**——根因字段属 postmortem 场景（踩坑修复、值得留档复盘）时，可改用多行 \`--output\` 形式，在根因块内按列表行补四子字段：\`根因：\` 行后换行接 \`- 现象：…\`（出了什么问题）、\`- 根因：…\`（深层原因）、\`- 护栏：…\`（防再犯措施）、\`- 证据：…\`（可追溯路径，如 sillyspec agent-log --json 输出的会话日志 jsonl 路径、review.json、verify-result.md）。该列表行形态为合法格式（顶层标签边界不受影响，详见上方说明）；常规场景仍推荐四参数形式。
 
 ### 📎 文件括注 --file-notes（可选，省事后手改文件行）
 若希望 QUICKLOG「文件：」行直接落盘为多行带括注（而非单行逗号路径），\`--done\` 时加 \`--file-notes\`，CLI 落盘为多行 \`- path（括注）\`，免去事后手改：