@xulthekl/team-flow 0.61.0 → 0.63.0

package/scripts/lib/config-loader.mjs

@@ -21,7 +21,25 @@ const DEFAULTS = {
     language: 'auto',
   },
   prd: {
+    // 模板路径。默认值为 **插件内置** 相对路径 —— 一律以**插件根**为基准解析，
+    // 项目根下的同名路径不构成回退目标（v0.62.0 F2，消除默认值基准歧义）。
     template: 'templates/prd.md',
+    // §8.4 撰写规范文件（v0.62.0 F1）。规范与体例解耦后，权威物是它而非模板骨架。
+    // 路径相对于插件根解析。
+    spec: 'skills/ce-brainstorm/references/prd-84-authoring-spec.md',
+    // 模板一致性确认记忆（v0.62.0 G2）。
+    // 由 `tf prd ack set` 原子写入（G6），落点 = resolveConfigWritePath() 命中的文件。
+    // 判据：三个 hash 全等 → 静默按 mode 执行；任一变化 → 重新提问（上一选择作默认项）。
+    template_ack: {
+      in_use_hash: null,   // 实际使用的模板骨架 hash
+      plugin_hash: null,   // 插件内置模板骨架 hash
+      spec_hash: null,     // 规范文件 hash —— v0.62.0 新增：规范升级须触发重问
+      plugin_version: null,
+      mode: null,          // 'adopt_latest' | 'keep_legacy'
+      diff_digest: null,   // 批准时所见差异摘要的摘要值 —— 否则事后无法复现"批了什么"
+      acknowledged_at: null,
+      acknowledged_by: null,
+    },
   },
   conventions: {
     // 项目级规范文件路径映射（v0.11 §33）
@@ -129,6 +147,27 @@ function findConfigFile(startDir) {
   return null;
 }
 
+/**
+ * v0.62.0（G5）：**写入路径与读取路径对齐**。
+ *
+ * 缺陷：`tf config --set` 原固定写 `<cwd>/team-flow.config.json`（legacy 第 2 顺位），
+ * 而读取走 `findConfigFile`，其**首选** `<cwd>/.team-flow/team-flow.config.json`
+ * 且**首个命中即返回、不合并** → 在已有 `.team-flow/` 配置的项目里 `--set`
+ * **静默无效**（写进一个没人读的文件），并在项目根留下误导性配置。
+ *
+ * 改法：写入一律落到 `findConfigFile()` 命中的那个文件；未命中则新建
+ * `.team-flow/team-flow.config.json`（与读取首选一致）。G6 的 ack 写入复用同一函数。
+ *
+ * @param {string} startDir
+ * @returns {string} 应写入的配置文件绝对路径
+ */
+export function resolveConfigWritePath(startDir) {
+  const hit = findConfigFile(startDir);
+  if (hit) return hit;
+  // 未命中 → 用读取的首选位置新建，避免"写了但读不到"
+  return join(startDir, '.team-flow', 'team-flow.config.json');
+}
+
 export function loadConfig(projectRoot) {
   const configPath = findConfigFile(projectRoot || process.cwd());
   if (!configPath) return { ...DEFAULTS };

package/scripts/lib/state-loader.mjs

@@ -83,6 +83,13 @@ const BUILTIN_DEFAULTS = {
   // `change:<name>`，若不给跳过键则 guard 永久 FAIL 无出路）。
   arch_merge_skipped: null,
   arch_merge_skip_reason: null,
+  // Bridging gates dry-run gate (v0.63.0；feedback 20260923-013114 S2)
+  // gates-probed 挂 full 的 bridging→approved-for-build；hotfix 走 WORKFLOW_TRANSITION_CHECKS
+  // 自有覆盖自动豁免；**tweak 无该键的覆盖条目 → 回落继承本维度**，故 tweak 必须靠
+  // gates_probed_skipped 放行——缺此键则 tweak 硬卡死（三处管道缺一不可）。
+  gates_probed_skipped: null,
+  gates_probed_skip_reason: null,
+  gates_probed_na: null,
   // 注意：schema_version 故意不在 BUILTIN_DEFAULTS 中（v0.13 §48.1）——
   // 它只由 `tf state init` 在 change 创建时打戳，字段缺失本身就是"存量 change"信号。
 };
@@ -213,6 +220,11 @@ export function writeState(changeDir, state) {
   lines.push('# === Arch merge gate (v0.53.0 §110.2) ===');
   lines.push(`arch_merge_skipped: ${state.arch_merge_skipped ?? 'null'}`);
   lines.push(`arch_merge_skip_reason: ${state.arch_merge_skip_reason ?? 'null'}`);
+  lines.push('');
+  lines.push('# === Bridging gates dry-run gate (v0.63.0) ===');
+  lines.push(`gates_probed_skipped: ${state.gates_probed_skipped ?? 'null'}`);
+  lines.push(`gates_probed_skip_reason: ${state.gates_probed_skip_reason ?? 'null'}`);
+  lines.push(`gates_probed_na: ${state.gates_probed_na ?? 'null'}`);
 
   fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
 }

package/scripts/lib/template-hash.mjs

@@ -0,0 +1,95 @@
+// scripts/lib/template-hash.mjs — 模板 / 规范文件的稳定 hash（v0.62.0，F5）
+//
+// 存在理由：改造前 **F3（Node 侧机械脚本）与 G1（skill 散文侧人工比对）各有一套
+// hash 判据**。同一文件在两处算出不同结果（换行、尾空白、编码差异）会导致
+// 「门失效」（该拦的没拦）或「误报落后」（不该问的乱问）。本模块把判据收敛为
+// **唯一实现**，两侧一律调用，不另立第二套。
+//
+// 判据定义（v1.7 §5.7 F5）：
+//   ① 算法 sha256，前缀 `sha256:`（与 `hash.mjs` 既有惯例一致）
+//   ② 颗粒度 = 整文件字节；**先做换行归一化（CRLF→LF）与首尾空白裁剪**
+//   ③ 输出：全长用于比对，`shortHash()`（前 8 位）仅用于展示
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+
+/**
+ * 归一化：CRLF → LF，并裁剪首尾空白。
+ *
+ * 只做这两件事，不做更激进的归一化（不折叠空行、不统一缩进）——
+ * 内容级差异应当反映到 hash 上，否则"改了却没变 hash"，门就形同虚设。
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function normalizeForHash(content) {
+  return (content ?? '').replace(/\r\n/g, '\n').trim();
+}
+
+/**
+ * 对内容取稳定 hash。空内容返回 null（不是空串 hash）——
+ * 「文件为空/不存在」是独立状态，不应与「内容为空串」混淆。
+ *
+ * @param {string} content
+ * @returns {string|null} `sha256:<hex>` 或 null
+ */
+export function hashContent(content) {
+  const normalized = normalizeForHash(content);
+  if (normalized.length === 0) return null;
+  return `sha256:${crypto.createHash('sha256').update(normalized, 'utf-8').digest('hex')}`;
+}
+
+/**
+ * 对文件取稳定 hash（文件不存在返回 null）。
+ *
+ * @param {string} filePath
+ * @returns {string|null}
+ */
+export function hashTemplateFile(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return null;
+  return hashContent(fs.readFileSync(filePath, 'utf-8'));
+}
+
+/**
+ * 展示用短标识（默认前 8 位，去掉 `sha256:` 前缀）。
+ *
+ * @param {string|null} hash
+ * @param {number} [len=8]
+ * @returns {string}
+ */
+export function shortHash(hash, len = 8) {
+  if (!hash) return '—';
+  const hex = hash.startsWith('sha256:') ? hash.slice(7) : hash;
+  return hex.slice(0, len);
+}
+
+/**
+ * 一次算出「模板骨架 + 规范文件」两个 hash（G1 判据对象，v1.7 DEC-16）。
+ *
+ * F 类-F1 之后，**权威物是规范文件而非模板骨架**，故判据必须含 spec_hash；
+ * 只比骨架会导致「规范升级不触发重问」——正是红队批评的「门管错了对象」。
+ *
+ * @param {{ templatePath?: string, specPath?: string }} paths
+ * @returns {{ template_hash: string|null, spec_hash: string|null }}
+ */
+export function hashTemplatePair(paths = {}) {
+  return {
+    template_hash: hashTemplateFile(paths.templatePath),
+    spec_hash: hashTemplateFile(paths.specPath),
+  };
+}
+
+/**
+ * 比对两组 hash（G2 ack 失效判定）。
+ *
+ * @param {{ template_hash?: string|null, spec_hash?: string|null }} current
+ * @param {{ in_use_hash?: string, spec_hash?: string, plugin_hash?: string }} ack
+ * @returns {{ matched: boolean, changed: string[] }}
+ */
+export function compareAgainstAck(current, ack = {}) {
+  const changed = [];
+  // ack 字段名沿用 config schema：in_use_hash 记录的是"项目侧实际使用"的骨架 hash
+  if ((current.template_hash ?? null) !== (ack.in_use_hash ?? null)) changed.push('in_use_hash');
+  if ((current.spec_hash ?? null) !== (ack.spec_hash ?? null)) changed.push('spec_hash');
+  return { matched: changed.length === 0, changed };
+}

package/scripts/team-flow.mjs

@@ -11,6 +11,7 @@ const COMMANDS = {
   version:        () => import('./lib/cmd-version.mjs'),
   sync:           () => import('./lib/cmd-sync.mjs'),
   config:         () => import('./lib/cmd-config.mjs'),
+  prd:            () => import('./lib/cmd-prd.mjs'),
   state:          () => import('./lib/cmd-state.mjs'),
   inject:         () => import('./lib/cmd-inject.mjs'),
   audit:          () => import('./lib/cmd-audit.mjs'),

package/skills/build-executor/SKILL.md

@@ -131,18 +131,9 @@ For full/hotfix by default. Execute waves as dispatched by workflow-start.
 1. Read the current plan with `tf execution show <change-dir> --json`; only waves shown with `current: true` and `eligible: true` may start. A `retryable: true` wave may only be repaired and re-reviewed; do not dispatch its dependents until its replacement receipt is `pass`. The CLI encodes dependencies in `--wave <id>:<strategy>:<tasks>[:<depends-on,...>]` and rejects a review receipt for a wave whose prerequisites lack current `pass` receipts.
 2. A `parallel` wave may dispatch independent tasks simultaneously only when the platform supports concurrent dispatch. If it does not, disclose the unavailable capability and execute the same wave one task at a time without changing its stored strategy.
 3. A `serial` wave dispatches one task at a time in listed order.
-4. After every wave, write back the tasks.md checkboxes for that wave, then notify workflow-start via SendMessage that the wave is complete and needs review.
+4. **case↔test 对账（v0.63.0；feedback 20260923-013114 S4，MUST，不过不许报完成）**：产出 `.superpowers/test-evidence/<wave>-case-test-reconciliation.md`——口径见下方 `### Wave Case↔Test Reconciliation (v0.63.0)
 
-   **tasks.md 勾选回写（v0.49.0 §83.3.4）**：按 `wave.tasks` 匹配 tasks.md 对应行，把 `- [ ]` 改为 `- [x]`（只改勾选标记，不动任务文本）。这是执行进度的权威登记——`tasks-complete` guard 在 closing 时要求零未勾选项，留到收尾轮必然遗忘。若该 change 的 tasks.md 不使用 checkbox 形态（如以 `### Task N.M` 标题组织），零 `- [x]` 会使该 guard 无条件 FAIL：此时与 workflow-start 确认改用 checkbox 形态或走显式豁免，不要静默跳过。A1 修复后勾选不再使 plan 过期（§83.3.1），因此不会阻塞本 wave 的 receipt 登记（receipt 由 workflow-start 写入）。
-
-   Notify with:
-   - Wave ID
-   - Worktree path
-   - Branch
-   - Repositories and commit SHAs (base + head)
-   - Summary of changes
-5. **Do not** attempt to dispatch code-reviewer or write review receipts — that is workflow-start's responsibility.
-6. Critical/Important findings require a `fail` receipt, a focused repair, re-review, then a replacement `pass` receipt. Never advance or close with a missing or failed receipt.
+**交付自检（MUST，不过不许报完成）**：每个 wave 完成时产出 `.superpowers/test-evidence/<wave>-case-test-reconciliation.md`（case id → 测试文件 → 方法名 → 断言点）。**完成门 = 机械层（case_id↔文件）+ 半机械层（方法名）通过即放行**；**断言点层归 code-reviewer Step 5b，不构成本步条件**（防卡死、防自填假证据）。不进 receipt JSON / 不进 test-matrix hash / 不新增 guard 维度。三层判据表、无脚本降级模板、N/A 落盘、升级路径与复用评估见 `references/wave-delivery-selfcheck.md`。
 
 ### Wave Verify: Actual Test Count (v0.43.1)
 
@@ -152,6 +143,10 @@ For full/hotfix by default. Execute waves as dispatched by workflow-start.
 2. 对照 test-matrix 当前 wave 覆盖的用例数（**分母排除 `test_tier=e2e`**——E2E case 由 Playwright 执行，不进入 `mvn test`/`npm test` 的 `Tests run: N`，口径与 code-reviewer Step 5b / release-archivist Step 2b 一致）：实际执行数明显低于预期（< 70%）→ **警告 + 调查**（@Nested 静默跳过、测试未被发现、编译期跳过等），未查明前不得报告 "N tests pass"。
 3. 报告引用实际执行数（按 runner 的计数口径），而非 BUILD SUCCESS 或编译通过数量。
 
+### Gate-Only Wave Receipt Protocol (v0.63.0)
+
+**零代码/纯闸门波次**的 receipt 范围：以根仓 planning commit（`tf publish --changes` 产物）作 base..head（`base` = 其父提交、`head` = 该 commit 本身）。**⚠️ 执行者 = workflow-start**（本 agent 不得自行写 receipt）。**若 G4 尚未执行：先按 G4 纪律完成 AskUserQuestion → 再 publish → 再建 receipt**，不得静默代替用户选择。**⛔ 有代码的波次不得借用。** 细则见 `references/wave-delivery-selfcheck.md`。
+
 ### Per-Task Loop
 1. **Dispatch implementer**: Load the template with `tf runtime asset read skills/build-executor/implementer-prompt.md`. Extract task brief with `scripts/task-brief PLAN_FILE N`. Include: where task fits, brief path, interfaces from prior tasks, report file path.
 2. **Handle response**: DONE → generate review package + dispatch reviewer. DONE_WITH_CONCERNS → assess. NEEDS_CONTEXT → provide context. BLOCKED → re-dispatch with better model or escalate.

package/skills/build-executor/references/wave-delivery-selfcheck.md

@@ -0,0 +1,92 @@
+# 波次交付自检（v0.63.0；feedback 20260923-013114 S4 + E2）
+
+本文件承载 build-executor SKILL 中两个「每次波次都要执行」的流程细节。SKILL 保留 MUST 与指针，细则在此。
+
+---
+
+## 一、case↔test 对账（S4）
+
+**来源**：v2-C2 实测——矩阵↔测试两份手写文本漂移（I-1 测试缺矩阵 expected 子断言 / M-1 方法名漂移 /
+M-2 expected 与实测矛盾）**全部在 code-reviewer 才抓出**，引发修复 + 复审一整轮。本步把「事后抓漂移」前移为「交付自检」。
+
+**产出**：`.superpowers/test-evidence/<wave>-case-test-reconciliation.md`，本 wave 覆盖的每个矩阵 case 一行：
+
+```markdown
+| case_id | 测试文件 | 方法名 | 断言点 | 备注 |
+|---|---|---|---|---|
+| Svc-create-001 | src/test/java/.../XxxServiceTest.java | shouldCreate_whenValid() | assertThat(status).isEqualTo(...) | — |
+```
+
+### 三层判据（按可判定性分层，不搞一刀切）
+
+| 层 | 判据 | 谁判 | 是否构成本步完成条件 |
+|---|---|---|---|
+| `case_id` ↔ 测试文件 | **机械**——矩阵 12 列格式本就含 `test_file` / `test_method_name` 列 | 脚本比对 | **是** |
+| 方法名 | **半机械**——可 grep 校验；矩阵一行对多测试时须在备注注明拆分；`@ParameterizedTest` 一方法对多 case 时 grep 仍命中文件，case↔参数行语义归审查侧 | 脚本提示 + 人工确认 | **是** |
+| 断言点 | **审查侧**——语义对应，机器不可判 | code-reviewer Step 5b | **否**——归审查侧，**不构成本步的完成条件**，本步不得因它卡住或自证 |
+
+> **完成门（防卡死/防造假）**：**机械层 + 半机械层两层通过 → 本步放行**（可进入下一步通知 wave 完成）。
+> 断言点层由 code-reviewer 独立复核，实施方**不需要也不得**为其自证——否则会逼出「自填断言点」的假自证。
+
+### 硬边界（MUST NOT 越界）
+
+- **不进 receipt JSON**（`execution-plan.mjs` 的 `savedReceipt` 字段白名单会静默丢弃）；
+- **不进 test-matrix hash**（`hash.mjs computeTestMatrixHash` 防自循环设计）；
+- **不新增 guard 维度**——走「evidence 文件 + 报告引用」的既有哲学。
+
+**反向回填限缩**：允许**仅方法名**从测试回同步矩阵；**expected 禁止由测试反生成**（防 oracle 循环）。
+
+### N/A 与无脚本降级
+
+- **N/A 落盘位置**：无矩阵的 change（hotfix/tweak，legacy 豁免）→ 在**同一 evidence 文件**内写
+  `N/A: <理由>`（文件仍须存在，保持「有产物可查」的一致性），**不得**静默跳过。
+- **机械层脚本不存在时**（team-flow 不内置，脚本由项目侧提供）：降级为人工执行同口径比对——
+  ```bash
+  # 矩阵 test_file 列 → 文件存在性
+  command grep -nE '^\|' test-matrix.md | …      # 逐行取 case_id / test_file
+  test -s <test_file>                            # 存在且非空
+  # test_method_name 列 → 源文件内 grep
+  command grep -rn "<method_name>" <test_file>
+  ```
+  **原始输出先落文件**再计数（判据四条），并在对账表末尾注明「机械层为人工降级执行」。
+- **升级**：对账反复不过（≥2 轮）→ 根因属纯文本订正走 doc-only 收口波次；**根因属矩阵 expected/方法名本身错**
+  → 走契约勘误的 gate-affecting 通道（rebuild→revise），**不得**以 doc-only 绕过。
+
+**复用评估（已做，勿重复）**：glaf4-dev 的 case 级对账实现
+（`glaf4-dev/0.6.2/scripts/gates/spring_contract_check.py`——case_id ↔ 测试方法「恰一个」匹配 + fail-closed 报告结构）
+**算法与报告形态可借鉴，实现不可直接复用**：其硬绑 Java/Spring（`.java` 后缀、surefire 报告），
+而 team-flow 的 change 跨 JS/Java/Kotlin 多栈，须泛化重写。
+
+---
+
+## 二、Gate-Only 波次 receipt 协议（E2）
+
+> **执行者 = workflow-start，不是本 agent。** receipt 由 workflow-start 组装并写入
+> （见 SKILL `### Planned-Wave Loop` 第 6 条：build-executor **不得**自行 dispatch reviewer 或写 receipt）。
+> 本文件记录该协议，**供 workflow-start 在组装 `--base/--head` 时遵循**；build-executor 只需在报告中提供
+> 「本波次无代码提交」这一事实，**不自行构造范围**。
+
+**现状**：`tf execution review` 的 `validateResolvedRange` 拒绝 `base == head`（**防伪设计，非缺陷**）——
+但纯闸门/制品型波次**没有代码提交**，每次都要人肉发明一个范围（v2-C1 wave4 与 v2-C2 w3 已重复 ≥2 次）。
+
+**固化协议**：纯闸门 / 零代码波次，以**根仓 planning commit**（`tf publish --changes` 的产物）作 receipt 范围：
+
+| 项 | 取值 |
+|---|---|
+| `base` | planning commit 的**父提交** |
+| `head` | planning commit **本身** |
+
+**若该波次的 G4（阶段产物同步门禁点，§68.2）尚未执行**：G4 本身是一个**阻塞 AskUserQuestion**
+（A 提交并推送 / B 仅提交不推送 / C 暂不同步），**不得静默代替用户选择**。故此处不是「选 C 直接补 publish」，
+而是：
+
+1. **按 G4 纪律完成询问**（本场景通常倾向 B「仅提交不推送」——planning commit 只需落地为 receipt 基线，未必需要推送）；
+2. 用户批复后，按其选择执行 `tf publish --changes`；
+3. **再**以该 commit 组装 receipt 的 base..head。
+
+> 若跳过询问静默执行，等于替用户决定了 G4 的结果——**收据先于闸门 = 伪绿方向**。
+> 反过来把 G4 延到下一波次同样脱节。所以唯一正确顺序是「先问 → 再 publish → 再建 receipt」。
+
+- **⛔ 有代码的波次不得借用本协议**——它不是放宽范围校验的口子，只为消掉「每次重新发明」的浪费。
+- **命名空间提示**：本协议的 `G4` 属**团队同步点编号 G1–G5**；契约 `## Gate Registry` 里的 `G-1`/`G-2`
+  是**命令型质量闸门**编号——**两套编号互不相干**，不要混用。

package/skills/ce-brainstorm/SKILL.md

@@ -8,7 +8,7 @@ argument-hint: "[feature idea or problem to explore] [output:html]"
 
 **Note: The current year is 2026.** Use this when dating PRD documents.
 
-Brainstorming answers **WHAT** to build through collaborative dialogue, producing a **PRD document** (产品需求文档). It precedes `/ce-plan` (**HOW** to build). In compound engineering, write under `requirement/vN/prd.md`. The PRD template is configurable via `prd.template` config (default: `templates/prd.md`). This skill explores, clarifies, and documents — it does not implement code.
+Brainstorming answers **WHAT** to build through collaborative dialogue, producing a **PRD document** (产品需求文档). It precedes `/ce-plan` (**HOW** to build). In compound engineering, write under `requirement/vN/prd.md`. The PRD template is configurable via `prd.template` config (default: **plugin built-in** `templates/prd.md`, resolved against the **plugin root**, never the project root). The **§8.4 authoring spec** (`references/prd-84-authoring-spec.md`) is the sole authority for §8.4 form and rules. PRDs are written to be **business-readable** — a business reviewer must be able to read them without technical knowledge. This skill explores, clarifies, and documents — it does not implement code.
 
 ## 调用模式（v0.7 新增）
 
@@ -40,12 +40,13 @@ Brainstorming answers **WHAT** to build through collaborative dialogue, producin
 | 职责 | 执行方 | 说明 |
 |------|--------|------|
 | 需求澄清、场景确认、流程确认、方案决策 | **主会话** | 需要用户交互和判断的工作 |
-| PRD 文档撰写（Phase 3） | **prd-writer agent**（v0.47） | 执行性文档生成（契约级 §8.4），主会话做 QA 和冻结 |
+| PRD 文档撰写（Phase 3） | **prd-writer agent**（v0.62.0） | 执行性文档生成（业务可读 §8.4），主会话做 QA 和冻结 |
 | 流程图绘制（mermaid） | **子代理**（推荐） | 基于已确认的流程数据生成图表 |
 | 活动表批量生成 | **子代理**（推荐） | 基于已确认的 L4 子流程生成表格 |
 | 综合报告（synthesis summary） | **子代理**（可选） | 大量数据的汇总整理 |
 
 **子代理委托方式**：使用 `Agent` 工具（`context: fork` 或自定义 agent），将已确认的结构化数据作为输入，要求子代理按模板产出。主会话审查产出后决定接受或修正。PRD 撰写（Phase 3）固定委托命名 agent **prd-writer**（预加载 ce-brainstorm，只执行 Phase 3、不提问）；其余执行性产出（流程图/活动表/综合报告）可委托通用子代理。
+**prd-writer「不提问」的边界（v0.62.0 · G3）**：它不向用户提问，但**会断言并回传**——若模板/规范 hash 与插件内置不一致且无有效 `template_ack`，返回 `TEMPLATE_MISMATCH` + 差异摘要并**停止撰写**，由**主会话**向用户确认后再恢复。传入参数须含 `plugin_root` 与 `template_ack`。
 
 ### Stage Breakpoints
 
@@ -100,40 +101,91 @@ If no feature description was provided, ask the user. If `docs/ideation/*.md` ex
 
 > **⛔ GUARDRAIL：禁止写入 skill 源码目录**
 >
-> 项目级制品（PRD 模板、配置文件等）只在**项目工作区**创建/修改：
-> - 模板文件：`.team-flow/templates/`
+> 项目级制品只在**项目工作区**创建/修改：
 > - 配置文件：`.team-flow/team-flow.config.json`
 >
 > **绝不写入 skill 源码目录**（`skills/ce-brainstorm/` 等）。
+>
+> **⚠️ 模板例外（v0.62.0 · F2）——默认不落副本**：
+> - **默认使用插件内置模板**，**不得**在项目内创建模板副本；
+> - 仅当用户**明确选择**「项目内留副本以便定制」时，才在 `.team-flow/templates/` 创建，
+>   且**必须同时写入 `prd.template` 配置指向该副本**（否则成为无人消费的影子副本）；
+> - 项目内已存在的 `.team-flow/templates/prd.md` **非权威、不得直接读取**——
+>   生成规范一律以插件内置 `templates/prd.md` 与 `prd-84-authoring-spec.md` 为准。
 
 Determine `OUTPUT_FORMAT` (md or html). For the full 5-level precedence, read `references/output-format.md`.
 
 **Resolve PRD template — MANDATORY STEP, DO NOT SKIP.**
 
+> **v0.62.0（F2）默认不落副本**：「默认模板」= **直接使用插件内置模板**，**不 cp 到项目**。
+> 只有用户**明确选择**「项目内留副本以便定制」时才 cp，且**必须同时写入 `prd.template` 配置**。
+
 1. **检查 tf CLI 是否可用**：运行 `which tf`
-   - ✅ 可用：继续执行 `tf runtime config --get prd.template`
+   - ✅ 可用：执行 `tf runtime config --get prd.template`
+     - 有值（用户配置的自定义路径/副本路径）→ 解析该路径（相对路径按项目根解析）
+     - 无值 / 返回默认 `templates/prd.md` → **按插件内置解析**（见下方「基准」），**不查项目根**
    - ❌ 不可用：走降级逻辑（见下方）
 
-2. **降级逻辑（tf 不可用时）**：
-   - 通知用户：`tf` 命令不可用，将使用默认配置
-   - **询问用户**：默认模板 or 自定义路径？
-     - 默认模板：**直接 cp skill 内置模板到项目目录**（见下方步骤）
-     - 自定义路径：验证文件存在，在项目工作区记录配置
-   - **维护配置文件**：在 `.team-flow/team-flow.config.json` 中记录配置（如文件不存在则创建）
-
-3. **默认模板处理步骤（重要）**：
-   - **源文件**：skill 内置 `templates/prd.md`（相对于 skill 基础目录）
+2. **基准（v0.62.0 显式化，消除歧义）**：
+   - **内置路径一律以插件根为基准**：`${CLAUDE_PLUGIN_ROOT}/templates/prd.md`
+   - 项目根下若恰好存在同名 `templates/prd.md`，**不构成回退目标、不得使用**
+     （旧行为靠「项目根恰好没有同名文件」才不歧义，属隐性依赖）
+   - 用户配置值若为相对路径 → 按**项目根**解析
+
+3. **降级逻辑（tf 不可用时）**：
+   - 通知用户：`tf` 命令不可用，将按插件内置模板解析
+   - **询问用户**：使用插件内置模板，**还是在项目内留一份副本以便定制**？
+     - **插件内置**（默认）：直接解析 `${CLAUDE_PLUGIN_ROOT}/templates/prd.md`，**不 cp、不写配置**
+     - **项目内留副本**：cp 到 `.team-flow/templates/prd.md`
+       → **必须同时写入 `prd.template` 配置指向该副本**
+       （`tf config --set prd.template=.team-flow/templates/prd.md`）
+       → 否则该副本无人消费，成为误导性影子副本
+
+4. **副本创建步骤（仅当用户明确选择「项目内留副本」时）**：
+   - **源文件**：插件内置 `templates/prd.md`
    - **目标目录**：`.team-flow/templates/`（项目工作区）
-   - **操作**：直接 `cp` 源文件到目标目录，**不要自行创建简化版本**
-   - **验证**：检查目标文件是否存在且包含完整的11个章节
-
-Built-in `templates/prd.md` is relative to the skill's base directory. Custom paths are relative to project root.
+   - **操作**：直接 `cp`，**不要自行创建简化版本**
+   - **验证**：目标文件存在且含完整的 11 个章节
+   - **成对**：模板与 brainstorm profile 必须成对处理（见下）
 
 **⛔ 关键约束**：
-- **错误行为**：自行创建简化版本的PRD模板
-- **正确行为**：直接 cp 原始 PRD 模板到项目目录，保持模板完整性
+- **错误行为**：自行创建简化版本的 PRD 模板／默认往项目里 cp 副本／**直接读取项目内既有的 `.team-flow/templates/prd.md`**
+- **正确行为**：默认用插件内置；仅在用户明确定制时 cp，并同步写配置
+
+**Resolve brainstorm profile.** After template resolution, look for `<template-name>-brainstorm-profile.md`
+**in the same directory as the resolved template**——模板与 profile **成对**，cp / 删除 / 漂移检测一律成对处理。
+Store as `BRAINSTORM_PROFILE_PATH`. Fall back to built-in `templates/prd-brainstorm-profile.md`.
+
+5. **模板一致性确认门（DP-8，v0.62.0 · G1）—— 阻塞，不可跳过**：
+
+   模板解析完成后、**Phase 3 派发 prd-writer 之前**，运行 `tf prd check --plugin-root "${CLAUDE_PLUGIN_ROOT}"`
+   取判据（判据实现见 `scripts/lib/template-hash.mjs`，**不得在本 skill 另写一套**）：
 
-**Resolve brainstorm profile.** After template resolution, look for `<template-name>-brainstorm-profile.md` in the same directory. Store as `BRAINSTORM_PROFILE_PATH`. Fall back to built-in `templates/prd-brainstorm-profile.md`.
+   | STATUS | 行为 |
+   |---|---|
+   | `MATCH` | **静默继续**——三 hash 与 `template_ack` 全等，用户此前已确认过 |
+   | `NO_ACK` | **阻塞提问**（首次） |
+   | `MISMATCH` | **阻塞提问**（模板/规范已变化，上次确认失效） |
+   | `UNRESOLVED` | 无法定位模板或插件根 → 记 `missing_info` 并**降级为警告**，不阻断 |
+
+   **提问三选项**（一律在**主会话**执行；prd-writer 是"不提问"子代理）：
+
+   | 选项 | 含义 | 后续 |
+   |---|---|---|
+   | **A. 按最新模板与规则** | 采用插件内置模板 + 最新规范 | **先执行历史文档就地升级**（见下），再撰写；`tf prd ack set --mode adopt_latest …` |
+   | **B. 保留当前模板继续** | 沿用项目现有模板（已确认落后） | 直接撰写；`tf prd ack set --mode keep_legacy …`，**并落 `dialogue-log.md` 受控记录**（属偏离接受 waiver） |
+   | **C. 先看差异再定** | 输出差异摘要后回到 A/B | **不写 ack**（下次仍会问） |
+
+   **ack 写入**：`tf prd ack set`（原子命令，**不要**用多次 `tf config --set` 拼装——
+   现行 `--set` 的值解析不支持对象，且 6 字段分 6 次写无原子性）。
+   须写入 `in_use_hash` / `plugin_hash` / `spec_hash` / `plugin_version` / `mode` / `diff_digest`。
+
+   **选 A 时的历史文档前置处置（全部完成才放行撰写）**：
+   ① 同迭代旧形态 `prd.md` **就地升级为新形态**（**不归档、不改名**——改文件名会打断 S3/spec 路径引用与证据链）；
+   ② 成对处置项目内模板 / profile 副本；③ `dialogue-log.md` 登记「形态迁移」变更记录（**含升级前内容摘要值**，作为"不归档"的留痕替代）；
+   ④ 补齐 `detail-ledger.md` 结构；⑤ **信息保全核对**：先完整读取旧形态 → 升级时逐项核对旧文信息无一遗漏 → 通过才放行。
+
+   **自动化路径（jarvis 等夜间值守）**：遇本门**一律挂起**，**不得代答或跳过**。
 
 #### 0.1–0.5 Routing Sub-phases
 
@@ -155,7 +207,8 @@ For detailed routing logic, read `references/phase0-routing.md`. Summary:
 
 **1.3 Dialogue** — Follow Interaction Rules. Fire blindspot gate (if tripwire armed) and visual-probe gate (before first shape decision). Rigor probes fire as open-ended questions before Phase 2. Before exit: integration check for non-obvious consequences. **Exit when**: primary actor, outcome, scope, success criteria all known or recorded as assumptions.
 
-**1.3b 功能细节澄清（v0.47）** — Follow the brainstorm profile's「功能细节（契约级）」core dimension. Standard/Deep scope **强制契约级澄清**（UI 布局/字段/交互/异常/权限；非 UI 触发/输入输出/处理/异常/幂等并发/性能），Lightweight 简化。产出 **detail_ledger**（`requirement/vN/detail-ledger.md`，逐功能维度 → 已澄清/待澄清/NA），供 Phase 3 §8.4 撰写 + 冻结前 D6 核对。
+**1.3b 功能细节澄清（v0.62.0）** — Follow the brainstorm profile's「功能细节」core dimension. Standard/Deep scope **逐条澄清业务信息**（UI：谁用 / 展示什么 / 能做什么 / 失败怎么办；非 UI：何时触发 / 输入输出 / 出错怎么办），Lightweight 简化。产出 **detail_ledger**（`requirement/vN/detail-ledger.md`，逐功能 → 已澄清/待澄清/NA），供 Phase 3 §8.4 撰写 + 冻结前 D6 核对。
+**边界**：澄清的是**业务信息本身**，不是「正文该写成什么样」——形态由 `prd-84-authoring-spec.md` 规定。
 
 **1.4 Dialogue Log Persistence** — Automated step, no user interaction. Trigger: Phase 1.3 dialogue exits. Traverse each Q&A round extracting original text + decisions, generate dialogue summary and decision summary table. Write to `requirement/vN/dialogue-log.md` (create or append). No ledger update.
 
@@ -193,15 +246,26 @@ Propose **2-3 approaches** (or recommend directly if one is clearly best). Use n
 - `requirement/ledger.md` — all requirement/scenario/process items and their associations
 - `requirement/vN/dialogue-log.md` — §1.2 revision record reference path
 - `requirement/vN/business-analysis.md` — data source for §2/§3/§7/§8
-- `requirement/vN/detail-ledger.md` — 功能细节澄清产出（v0.47），§8.4 逐功能详述数据源 + D6 核对基准
+- `requirement/vN/detail-ledger.md` — **维度清单载体 + 完整性台账 + D6 核对基准**（v0.62.0）：承载 11 维 / 7 维的内部校验清单与逐功能状态（已澄清 / 待澄清 / `NA + 理由`），是 §8.4 撰写的**信息数据源**（不是正文形态模板）
 
 **⛔ MANDATORY：生成PRD文档前，必须先读取 `references/brainstorm-sections.md`**
 
-**§8.4 功能模块提取规则（v0.47）**：规范唯一权威 = 模板 `templates/prd.md` §8.4「必含维度检查清单」（UI 11 维 / 非 UI 7 维双形态 + NA 机制），**本处不再重复维护维度清单**。生成 PRD 前必须读取模板检查清单，逐功能模块按适用维度详述；维度不适用标注 `NA + 理由`；**未标注 NA 且未覆盖 = 缺失**。
+**§8.4 功能模块提取规则（v0.62.0）**：**规范唯一权威 = `references/prd-84-authoring-spec.md`**
+（**不是**模板 §8.4、也**不是**项目内的模板副本）——本处不再重复维护规范。生成 PRD 前必须读取该规范文件：
+
+- 每个功能模块 = **一张两列表格 + 编号业务叙述**（定义 → 条件或触发 → 内容或要素 → 业务规则 → 异常与边界）
+- **左列必须是画面/入口锚点**（UI 用 `原型/UI`，非 UI 用 `触发入口`），**不得**写成「维度 / 字段 / 类型」
+- 完整性走**内部校验清单**（11 维 / 7 维）：撰写前核对信息齐备，**清单本身不写入正文**
+- 维度不适用 → 在 `detail-ledger.md` 标 `NA + 理由`，**不在正文标注 NA**
+- 面向**业务评审人**撰写：业务语汇为主干，技术标识符不进正文主干，禁弱词
 
 Read `references/brainstorm-sections.md` for doc-warranted criteria. If warranted: read template from `PRD_TEMPLATE_PATH`, fill via `references/prd-mapping.md`, write to `requirement/{ITERATION_VERSION}/prd.md`. Vocabulary capture: update `CONCEPTS.md` with resolved domain terms (only if it exists).
 
-> **子代理委托（v0.47）**：Phase 3 PRD 撰写委托 **prd-writer** agent。主会话将已确认结构化数据（business-analysis.md + dialogue-log.md + **detail_ledger** + synthesis summary + template_path）作为参数传入；prd-writer 按模板 §8.4 契约级检查清单逐功能详述，不提问、不虚构，`missing_info` 返回主会话决定是否回 Phase 1.3 补澄清。主会话负责 QA-4 审查和冻结确认。
+> **子代理委托（v0.62.0）**：Phase 3 PRD 撰写委托 **prd-writer** agent。主会话将已确认结构化数据
+> （business-analysis.md + dialogue-log.md + **detail_ledger** + synthesis summary + `template_path`
+> + **`plugin_root`** + **`template_ack`**）作为参数传入；prd-writer 按 **`prd-84-authoring-spec.md`**
+> 逐功能按业务认知顺序撰写，不提问、不虚构，`missing_info` 返回主会话决定是否回 Phase 1.3 补澄清。
+> 主会话负责 QA-4 审查和冻结确认。
 
 ### Phase 3.5: Prototype Inner Loop
 
@@ -209,7 +273,7 @@ Read `references/brainstorm-sections.md` for doc-warranted criteria. If warrante
 
 ### QA-4: PRD Quality Check
 
-Fires after Phase 3 (or Phase 3.5 if prototype loop ran). Read `references/evidence-chain-validation.md` for QA-4 criteria. Evaluates PRD completeness and traceability against business analysis artifacts. **冻结前完整性评审（6 维，含 §8.4 契约级细节 D6）的派发点已归并**：standalone 路径由 Phase 3.5（`references/prototype-loop.md` §3.5.5）派发 prd-completeness-reviewer；orchestrated 路径由 orchestrator S2 派发（见 `workflow-orchestrator/references/s2-prd-prototype-loop.md`）；**QA-4 自身不重复派发**，仅按评审结果判定是否回 Phase 1.3/Phase 3 修订。
+Fires after Phase 3 (or Phase 3.5 if prototype loop ran). Read `references/evidence-chain-validation.md` for QA-4 criteria. Evaluates PRD completeness and traceability against business analysis artifacts. **冻结前完整性评审（6 维，含 §8.4 信息齐备性与业务可读形态 D6）的派发点已归并**：standalone 路径由 Phase 3.5（`references/prototype-loop.md` §3.5.5）派发 prd-completeness-reviewer；orchestrated 路径由 orchestrator S2 派发（见 `workflow-orchestrator/references/s2-prd-prototype-loop.md`）；**QA-4 自身不重复派发**，仅按评审结果判定是否回 Phase 1.3/Phase 3 修订。
 
 ### Phase 3.6: PRD ↔ Scenario/Process Bidirectional Validation
 
@@ -241,7 +305,7 @@ requirement/
 ├── vN/                                # Iteration version
 │   ├── prd.md                         # PRD document
 │   ├── dialogue-log.md                # Dialogue log (Phase 1.4 output)
-│   ├── detail-ledger.md               # 功能细节澄清产出（v0.47，§8.4 数据源 + D6 核对基准）
+│   ├── detail-ledger.md               # 维度清单载体 + 完整性台账 + D6 核对基准（v0.62.0）
 │   └── business-analysis.md           # Business analysis (requirements + scenarios + processes)
 doc/
 └── active-registry/

package/skills/ce-brainstorm/references/brainstorm-sections.md

@@ -30,7 +30,9 @@ New `ce-brainstorm` outputs follow the PRD artifact contract:
 - **Path:** `requirement/vN/prd.md` (N is the iteration version number, e.g., v1, v2). Legacy fallback: `prd/vN/prd.md`.
 - **Metadata:** `project_name`, `iteration_version`, `prd_template` (template path).
 - **Template source:** read `prd.template` from project configuration, or use
-  the default `templates/prd.md`.
+  the **plugin built-in** `templates/prd.md` (resolved against the **plugin root**;
+  a project-local `templates/prd.md` is **not** a fallback and must not be read directly).
+- **§8.4 authoring spec:** `prd-84-authoring-spec.md` — sole authority for §8.4 form and rules.
 - **Structure:** the PRD contains 11 chapters as defined by the PRD template:
   1. 版本修订记录
   2. 业务流程一览
@@ -255,6 +257,9 @@ as template placeholder.
 - **§6 D7.4_业务术语字典** — fill with domain terms actively defined during
   dialogue. Only include terms where the conversation pinned down a precise
   meaning. Skip terms merely mentioned in passing.
+  **v0.62.0**：该表是**业务与代码共享词汇表**——「术语名称」用**业务语汇**（PRD 正文主干一律用它），
+  并填「**代码标识**」列（该术语在代码中的对应标识：类名/字段名/枚举值等），供**实现侧对齐**；
+  **不得**用代码标识回写正文主干。业务上无对应代码概念的填「—」。
 
 - **§7 D7.5_系统功能清单** — fill from brainstorm Requirements. Each R-ID
   maps to a system function entry with the requirement's intent as the function
@@ -267,11 +272,13 @@ as template placeholder.
   所属流程 (BP-xxx). Skip §8.3 (hardware/network) and §8.5 (non-functional)
   unless the brainstorm explicitly covered these.
 
-  **§8.4 功能模块提取规则（v0.47）**：
-  - **规范权威**：模板 `templates/prd.md` §8.4「必含维度检查清单」是唯一权威（UI 11 维/非 UI 7 维双形态 + NA 机制），本文件不再重复维护维度清单。撰写（prd-writer）与审查（prd-completeness-reviewer D6）均以模板为基准。
-  - **详细程度**：保留原始需求文档中的关键细节，不要过度概括（页面布局/搜索字段/表格列/交互规则/动态字段/级联逻辑等——逐项见模板检查清单）
-  - **错误行为**：只提取输入/输出/业务规则，丢失原始需求文档中的大量关键细节
-  - **正确行为**：充分利用原始需求文档的详细内容，保持信息完整性
+  **§8.4 功能模块提取规则（v0.62.0）**：
+  - **规范权威**：**`prd-84-authoring-spec.md` 是唯一权威**（**不是**模板 §8.4、也**不是**项目内模板副本），本文件不再重复维护规范。撰写（prd-writer）与审查（prd-completeness-reviewer D6 + 形态核验 G7）均以该规范文件为基准。
+  - **呈现形态**：每个功能模块 = 一张两列表格 + 编号业务叙述（定义 → 条件或触发 → 内容或要素 → 业务规则 → 异常与边界）；**左列必须是画面/入口锚点**（`原型/UI` 或 `触发入口`）
+  - **完整性**：11 维 / 7 维降为**内部校验清单**，撰写前核对信息齐备，**清单本身不写入正文**；维度不适用在 `detail-ledger.md` 标 `NA + 理由`
+  - **详细程度**：保留原始需求文档中的关键**业务**细节，不要过度概括
+  - **错误行为**：只提取输入/输出/业务规则，丢失原始需求文档中的大量关键细节；或把维度清单写进正文
+  - **正确行为**：充分利用原始需求文档的详细内容，按业务认知顺序重组进正文，保持信息完整性
 
 ## Agent agency
 
@@ -297,8 +304,10 @@ Every PRD produced by `ce-brainstorm` carries metadata in YAML frontmatter.
 - **`iteration_version`** — the iteration version (e.g., "v1", "v2"),
   corresponding to the `requirement/vN/` directory.
 - **`date`** — creation date in ISO 8601 (`YYYY-MM-DD`).
-- **`prd_template`** — relative path to the PRD template used (e.g.,
-  `templates/prd.md`).
+- **`prd_template`** — relative path to the PRD template used. When the plugin built-in
+  is in effect (the default), record `templates/prd.md` and note it resolves against the
+  **plugin root**; `prd_84_spec` — relative path to the §8.4 authoring spec
+  (`skills/ce-brainstorm/references/prd-84-authoring-spec.md`).
 - **`prd_readiness`** — always `requirements-only` for new `ce-brainstorm`
   outputs. `ce-plan` produces a separate `plan.md` document (not modifying the PRD).
 
@@ -331,6 +340,15 @@ existing fields breaks downstream consumers.
   file layouts, code structure stay out unless the brainstorm itself is
   inherently about a technical or architectural change and those details are
   the subject of the decision.
+  **Vocabulary boundary (v0.62.0):** 正文主干用**业务语汇**（§6 术语字典的业务名）；
+  类名 / 方法名 / 表名 / 注解 / 字段名 / 行号**不得**出现在正文主干，确需时以**括注**附于业务名之后
+  （例：「生效版本（字段 `last_agreement_version`）」）。
+- **No history traces (v0.62.0).** 删除线、版本锚点（`v0.5ac`）、澄清轮次锚点（`Q8 新增`）、
+  「原口径作废」「已被推翻」「沿革留痕」一律**不进正文**——它们属演变轨迹，迁 `dialogue-log.md`。
+- **No internal checklist transcript (v0.62.0).** 11 维 / 7 维检查清单是**撰写者的内部校验清单**，
+  不得把清单本身（或「按 … 维覆盖，不适用标 NA」式转述）写进正文；不适用维度在 `detail-ledger.md` 标 `NA + 理由`。
+- **No weak words (v0.62.0).** 禁用比较级 / 主观词 / 歧义词 / 开放式 / 漏洞词
+  （较快 / 友好 / 支持 / 适当 / 等 / 尽可能 / 必要时）——模糊表述会被下游自行解释，产生静默缺陷。
 
 ## Rendering
 

package/skills/ce-brainstorm/references/evidence-chain-validation.md

@@ -16,7 +16,7 @@ This reference covers three connected operations after PRD generation: QA-4 qual
 | C5 | Consistency | PRD §2 process overview table matches business-analysis.md process list? | Error |
 | C6 | Consistency | PRD §3 process descriptions match business-analysis.md process details? | Error |
 | C7 | Metadata | PRD frontmatter complete (title / project_name / iteration_version / date / prd_template)? | Warning |
-| C8 | Detail | §8.4 契约级细节：逐功能模块按模板检查清单覆盖适用维度（UI 11 维/非 UI 7 维，单一权威 = 模板 §8.4）+ §7↔§8.4 交叉核对无悬空功能（v0.47 并入 D6 模型：核心维度缺失/悬空 = Critical，辅助维度缺失 = Important） | Critical |
+| C8 | Detail | §8.4 信息齐备性与业务可读形态：逐功能模块按**业务认知顺序**核对信息是否可定位（**单一权威 = `prd-84-authoring-spec.md`**，**不是**模板 §8.4、也**不是**项目内模板副本）+ §7↔§8.4 交叉核对无悬空功能 + **形态核验 G7 六条**（左列为画面/入口锚点、§1.2 极简版本行、范围标记受控枚举、无历史痕迹、无技术标识符越界、维度清单未入正文）。判级：核心信息缺失/悬空 = Critical，辅助信息缺失/**形态核验命中** = Important | Critical |
 
 **Verdict rule:** All Error-level checks pass → PASS. Any Error fails → FAIL. Warnings are reported but do not block.