@xulthekl/team-flow 0.61.0 → 0.63.0

package/skills/ce-brainstorm/references/prd-84-authoring-spec.md

@@ -0,0 +1,182 @@
+# PRD §8.4 撰写规范（权威）
+
+> **本文件是 PRD §8.4 生成规范的唯一权威**（v0.62.0 · F1）。
+>
+> **为何外置**：`templates/prd.md` 同时承担「客户可能强制的 D7 体例骨架」与「team-flow 维护的生成规范」。
+> 一旦模板被拷贝进项目，规范就被连带冻结、插件升级推不动。解耦后：**骨架副本可以旧，规范永远新**。
+>
+> **适用范围**：撰写（`prd-writer`）、审查（`prd-completeness-reviewer` D6）、形态核验（G7）
+> 一律以本文件为准，**不得**依据模板副本或自身预期判断。
+> 模板 `templates/prd.md` §8.4 只承载**骨架与填空槽位**，并指向本文件。
+
+---
+
+## 1. 读者与立场
+
+§8.4 面向**业务评审人**撰写。**读本节的人不需要懂技术。**
+
+- 能写进正文的：业务动作、业务规则、界面呈现、异常与边界的业务后果。
+- 不能写进正文的：类名、方法名、表名、字段名、行号、框架注解、实现方案选型。
+  （确需说明时，以括注形式附在业务名之后，例如「生效版本（字段 `last_agreement_version`）」）
+
+---
+
+## 2. 目标形态
+
+### 2.1 一功能一表
+
+每个功能模块独立成表，**两列**：
+
+| 功能形态 | 左列名 | 右列内容 |
+|---|---|---|
+| **UI 功能** | `原型/UI` | 原型文件与容器定位 |
+| **非 UI 功能** | `触发入口` | 什么事件/时机触发该功能 |
+
+右列是**业务说明**，按 §2.2 的编号骨架展开。**不得**用 checkbox 维度清单替代叙述。
+
+> **核验要点**：左列必须是**画面/入口锚点**。出现「维度 / 字段 / 类型 / 信息结构」等**技术维度名**
+> 即为形态违规——即便表格是两列、叙述也编号，语义仍是按技术维度切分。
+
+### 2.2 编号业务叙述骨架
+
+右列按**业务认知顺序**展开（不按技术维度切分）：
+
+1. **定义** —— 这个功能是什么、给谁用、解决什么问题（1–3 句，业务语汇）
+2. **条件或触发** —— UI 功能写查询条件与控件；非 UI 功能写什么情况下触发
+3. **内容或要素** —— UI 功能写展示哪些字段、什么布局；非 UI 功能写输入什么、产出什么
+4. **业务规则** —— 生效的规则逐条写清，含前提条件与例外（**本功能最重要的部分**）
+5. **异常与边界** —— 空态 / 错误态 / 无权限 / 并发 / 极值 / 状态冲突 / 数据缺失 / 外部依赖失败
+   ——**按业务风险选取**，纯展示类写关键 2–3 项即可，**不要求逐功能写全**
+
+> **密度优先**：允许在右列内嵌字段表、决策表，避免为凑骨架而把一条规则拆成五段。
+
+### 2.3 可解析性硬约束（保护下游消费方，**必守**）
+
+叙述化不得牺牲可解析性。**字段类信息**在叙述中必须以
+「**字段名在前、冒号分隔、规则在后**」的**可辨识格式**呈现：
+
+```
+协议名称：输入框，模糊匹配，最长 50 字符
+```
+
+**理由**：`prototype-reviewer`（D3 字段一致性）、`prototype-env-scout`、
+`prototype/references/builder-methodology.md` 等下游**从 §8.4 提取字段**。
+若改为自由散文（如「用户可以按协议名称搜索，是模糊匹配，最多五十个字」），
+下游解析即失败——**可读性改造不能以牺牲下游可用性为代价**。
+
+**禁止**：把字段信息写成跨句的散文；**允许**：字段表（更推荐）、编号列表中的单行「字段：规则」。
+
+---
+
+## 3. 六条生成原则
+
+| # | 原则 | 要点 |
+|---|---|---|
+| 一 | **单一真相** | 正文 = 当前生效约定的完整重述。已失效的旧结论、版本演变轨迹、被推翻的论证**不得**出现 |
+| 二 | **一功能一表** | 见 §2.1 |
+| 三 | **按业务认知顺序** | 见 §2.2；不按技术维度切分 |
+| 四 | **业务语汇为主干** | 见 §1 |
+| 五 | **呈现与完整性解耦** | 完整性走内部清单（§5），**不写入正文** |
+| 六 | **精确性优先** | 见 §4 |
+
+### 3.1 原则一的三类内容判定
+
+| 内容类型 | 定义 | 归属 |
+|---|---|---|
+| **Rationale**（为什么这样定） | 当前生效约定的理由 | **保留在正文**（压缩为一句话） |
+| **Change history**（曾经怎么定） | 已失效的旧结论与演变轨迹 | **迁出**至 `dialogue-log.md` |
+| **本期范围标记** | 本期迭代新增/变更/不变 | **保留**（受控枚举，见 §6） |
+
+**判定测试**（写作者自检 + 审查者核对）：
+
+1. 删除该句后，读者对「**当前应该怎么做**」的理解是否改变？改变 → 保留。
+2. 若不变：读者对「**为什么这么做**」的理解是否受损？受损 → 属 rationale，压缩为一句话保留。
+3. 两者皆不变 → 历史噪音，删除或迁出。
+4. 这条信息是让评审人知道「**这次变了什么**」（范围标记 → 保留），
+   还是「**以前是什么**」（演变轨迹 → 迁出）？
+
+---
+
+## 4. 精确性（弱词规则）
+
+**禁用**：比较级（较快 / 更好）、主观词（友好 / 简洁）、歧义词（支持 / 处理 / 适当）、
+开放式（等 / 尽可能 / 视情况）、漏洞词（必要时 / 一般）。
+
+**理由**：PRD 是下游（plan / spec / 代码生成）的输入。模糊表述**不会**被当作"待澄清"，
+**会被下游自行解释**，产生静默缺陷。精确不是洁癖，是正确性的前提。
+
+---
+
+## 5. 完整性：内部校验清单（**不写入正文**）
+
+UI **11 维**：页面布局 / 权限规则 / 区块说明 / 搜索模块 / 表格列定义 / 交互规则 / 弹层结构 /
+动态字段 / 导入导出规则 / 状态操作差异 / 异常边界
+
+非 UI **7 维**：触发条件 / 输入输出 / 处理步骤 / 异常处理 / 权限角色 / 幂等并发 / 性能约束
+
+**用法**：
+
+- 撰写**前**：用它核对信息是否齐备（缺什么就去澄清什么）；
+- 撰写**时**：按 §2.2 的**业务认知顺序**重组进正文叙述；
+- **不得**把清单本身写进正文（无列名清单、无 checkbox 列表）；
+- 维度不适用时：在 `detail-ledger.md` 标注 `NA + 理由`，**不在正文标注 NA**。
+
+> **核验要点**：正文出现「按 … 维覆盖，不适用标 NA」之类**清单转述**，即为违规（原则五）。
+
+---
+
+## 6. 范围标记（受控枚举）
+
+§2 业务流程一览、§7.1 功能清单的「变更类型」列**只允许取三个受控值**：
+
+`本期新增` / `本期变更` / `本期不变`
+
+**禁止**在标记位写入版本锚点（`v0.5ac` / `v0.47`）、澄清轮次锚点（`Q8 新增`）、日期、旧值、变更原因。
+这些属**演变轨迹**，归属 `dialogue-log.md`。
+
+---
+
+## 7. 反填充约束
+
+**不得为「看起来完整」而填充。** 凡无法辩护的内容一律删除。
+
+**可核对判据**（「无法辩护」本身不可核对，须落到这两条）：
+
+1. **可指回来源**：正文每条业务规则必须能指回需求来源或澄清记录
+   （`business-analysis.md` / `dialogue-log.md`）；**指不回去的即删**。
+2. **NA 必附理由且可被挑战**：`detail-ledger.md` 的 NA 须写一句理由，审查者可挑战；
+   **冲突时以「有理由的 NA」优先**（防止为消灭 NA 而反向填充）。
+
+---
+
+## 8. 可读性自查项
+
+撰写完成后逐条自检（**自查 ≠ 规格正文**，不构成对业务方的规格条款，判定权仍在业务评审）：
+
+| # | 自查项 |
+|---|---|
+| 1 | 无类名 / 方法名 / 表名 / 行号出现在正文主干 |
+| 2 | 无历史痕迹（删除线、版本锚点、「原口径作废」「已被推翻」） |
+| 3 | 术语用 §6 术语字典的**业务名** |
+| 4 | 无弱词（见 §4） |
+| 5 | 维度清单未写入正文（见 §5） |
+
+> **非脚本门禁**：本节不得接入机械门禁脚本（弱词检测先落 LLM 审查层）。
+
+---
+
+## 9. 撰写后形态核验（G7）
+
+`prd-completeness-reviewer` 在 D6 内按此 6 条核验产出形态：
+
+| # | 核验项 | 判级 |
+|---|---|---|
+| 1 | §8.4 是否「一功能一表 + 编号业务叙述」，且**左列为画面/入口锚点** | 不符 = Important |
+| 2 | §1.2 是否极简版本行：单版本行要点 **≤ 200 字**；**无**「已被 X 推翻」式反转注记；功能级历史指向 `dialogue-log.md` | 不符 = Important |
+| 3 | 范围标记是否受控枚举（§6） | 不符 = Important |
+| 4 | 有无历史痕迹残留（删除线、版本锚点、章节名带版本） | 命中 = Important |
+| 5 | 有无技术标识符越界（类名 / 方法名 / 表名 / 注解 / 字段名 / 行号） | 命中 = Important |
+| 6 | 有无把维度清单写入正文（§5） | 命中 = Important |
+
+> **判据必须同时查「形态」与「内容」**——只查形态会被"形似神不似"的产出绕过。
+> 实证：某存量 PRD 确为两列表 + 编号叙述，但左列是「维度」；§1.2 表头合规但单行要点达 7,156 字。

package/skills/ce-brainstorm/references/prd-mapping.md

@@ -74,7 +74,7 @@ ce-brainstorm 的对话流程收集的信息需要映射到 PRD 模板的 11 个
 | `iteration_version` | frontmatter | `vN`（v1/v2/…） | **产品迭代版本** | 仅新迭代/新用户故事（vN+1）|
 | 产品版本 | 正文 §1.1 版本信息 | `vN.M`（v1.0/v1.1/…） | **文档修订次版本** | vN 内每次修订递增 M（呼应反馈环路「vN 内修订不升版」）|
 
-- vN 内修订（S3→S2 回退修订）→ 只递增正文 `vN.M` 的 M，**frontmatter `iteration_version` 不变**，并在 §1.2 修订记录追加一行 + 「决策与变更履历」章节记录。
+- vN 内修订（S3→S2 回退修订）→ 只递增正文 `vN.M` 的 M，**frontmatter `iteration_version` 不变**，并在 §1.2 修订记录追加**一行一句话摘要**（**≤ 200 字**，禁「已被 X 推翻」式反转注记），**功能级历史与决策过程写入 `dialogue-log.md`**（PRD 正文不承载）。
 - 新迭代 → frontmatter `iteration_version` 升 vN+1，正文产品版本重置为 `v(N+1).0`，新建 `requirement/v(N+1)/` 目录。
 
 **文档状态枚举（§1.1）——必须与 frontmatter `frozen` 一致**：
@@ -93,7 +93,7 @@ PRD 冻结时（`frozen_downstream`），在正文标题下方插入冻结声明
 
 ```markdown
 > **本文档已于 {YYYY-MM-DD} 冻结**（`frozen_downstream`，经原型循环验证 + 人工评审通过）。
-> 下游阶段（plan/spec/build）**不可直接修改**；如 plan 或实施暴露 scope 问题，经 **S3→S2 回退在 vN 内修订**并记录「决策与变更履历」（不升版）。
+> 下游阶段（plan/spec/build）**不可直接修改**；如 plan 或实施暴露 scope 问题，经 **S3→S2 回退在 vN 内修订**——**正文更新为最新态**（就地升级、不累积历史），决策与变更过程记入 `dialogue-log.md`（不升版）。
 > 仅当**启动新迭代 vN+1** 或**用户显式绝对冻结**（`frozen_absolute`）时，才需升版。
 ```
 
@@ -107,14 +107,19 @@ PRD 冻结时（`frozen_downstream`），在正文标题下方插入冻结声明
 
 | PRD 模板 | Brainstorm Profile |
 |----------|-------------------|
-| `templates/prd.md` | `templates/prd-brainstorm-profile.md` |
+| **插件内置** `templates/prd.md`（默认） | **插件内置** `templates/prd-brainstorm-profile.md` |
 | `my-project/prd-template.md` | `my-project/prd-template-brainstorm-profile.md` |
 | `.team-flow/custom-prd.md` | `.team-flow/custom-prd-brainstorm-profile.md` |
 
+> **v0.62.0（F2）**：模板与 profile **成对**——cp / 删除 / 漂移检测一律成对处理。
+> **默认不落副本**：未配置 `prd.template` 时直接用**插件内置**，不在项目内创建
+> `.team-flow/templates/` 副本；项目内已存在的副本**非权威、不得直接读取**。
+> 内置路径一律以**插件根**为基准解析（项目根同名路径不构成回退目标）。
+
 ### 查找优先级
 
 1. 自定义模板同目录的 profile 文件（按命名规则推导）
-2. 内置默认 `templates/prd-brainstorm-profile.md`（相对 skill 基目录）
+2. 内置默认 `templates/prd-brainstorm-profile.md`（**相对插件根**解析）
 
 ### Profile 三段结构
 

package/skills/ce-brainstorm/references/prototype-loop.md

@@ -43,10 +43,10 @@ PRD 文档写入后、Handoff 之前，执行原型内循环。原型是 PRD 的
 
 派发 `prd-completeness-reviewer` 子代理（独立上下文），评审 PRD「是否完整到能支撑后续 plan/spec 实施」（区别于 Phase 2.6 claim verifier——后者管"说得对不对"，本评审管"说得全不全"）。
 
-- 派发：按名派发插件 agent `prd-completeness-reviewer`（定义见插件 `agents/prd-completeness-reviewer.md`），传入 `prd_path` + `concepts_path`（可选）+ `template_path`（默认 `templates/prd.md`）+ `detail_ledger_path`（如有）。
+- 派发：按名派发插件 agent `prd-completeness-reviewer`（定义见插件 `agents/prd-completeness-reviewer.md`），传入 `prd_path` + `concepts_path`（可选）+ `template_path`（默认**插件内置** `templates/prd.md`）+ **`spec_path`**（默认 `${CLAUDE_PLUGIN_ROOT}/skills/ce-brainstorm/references/prd-84-authoring-spec.md`，§8.4 规范唯一权威）+ `detail_ledger_path`（如有）。
 - agent 直接写审查报告到 `requirement/{ITERATION_VERSION}/prd-completeness-review.md`。
 - 判定（柔性）：PASS / PASS_WITH_WARNINGS → 进入冻结；**FAIL（Critical>0）→ 回 Phase 1.3/Phase 3 补充**后重审。
-- 6 维度：用户故事完整性(Critical)/验收标准(Critical)/边界与非功能(Important)/术语一致性(Minor)/范围闭环(Important)/§8.4 契约级细节（核心维度缺失·悬空功能=Critical，辅助维度缺失=Important）。
+- 6 维度：用户故事完整性(Critical)/验收标准(Critical)/边界与非功能(Important)/术语一致性(Minor)/范围闭环(Important)/**§8.4 信息齐备性与业务可读形态**（核心信息缺失·悬空功能=Critical，辅助信息缺失·**形态核验 G7 命中**=Important）。
 
 ## 3.5.6 冻结
 

package/skills/code-reviewer/SKILL.md

@@ -107,6 +107,8 @@ Run `tf solutions inject --phase review --limit 15` (never blocks on failure)
 3. Read `design.md` to understand architectural decisions
 4. Get the list of changed files: `git diff --name-only BASE..HEAD` or from the change directory
 
+5. **根仓 planning 制品 diff 单列（v0.63.0；S3 例外 2 判定，MUST）**：多仓场景下 `BASE..HEAD` 解析到**子仓**，而 planning 四件在**根仓** `changes/<change-name>/`——子仓 diff 里**看不到它们是否被改**。故须额外单列 `proposal.md` / `specs/` / `design.md` / `tasks.md` / `execution-contract.md` 的 diff（相对 DP-3 批准时点）。**基线获取**：优先取 G4 publish 产生的 planning commit；无则 `git log --format=%H --before='<dp_3_timestamp>' -- <paths>` 取最后提交；仍无（未跟踪文件）则以 `state.artifacts_hash` 不匹配为触发信号，diff 工作区 vs HEAD 并在报告注明「基线降级」。判定：有改动 + 已登记 `## Errata Register` 且判定依据成立 → 通过；有改动 + 未登记，或实为 gate-affecting（矩阵 `expected`/方法名、闸门基线数字、`## Test Matrix` 段）→ **Critical finding**（`frozen-artifact-modified`）。**不采信实施方对「陈述性」的自判**——判定权在本步。
+
 ### Step 1b: File Existence Check (前置, v0.43.1)
 
 在 spec-compliance 之前校验 tasks.md 声明的文件是否实际落地（设计增强方案 v0.18 §75，来源：workflow-feedback 2026-08-06——build-executor 标记 Task 完成但文件未创建，审查未发现直到 closing）：
@@ -160,6 +162,8 @@ Check for:
 
 If `test-matrix.md` exists in the change directory, audit the implementation against it:
 
+> **与 build-executor 对账表的关系（v0.63.0，S4）**：build-executor 的 `.superpowers/test-evidence/<wave>-case-test-reconciliation.md` 是**交付自检**（左移）。**本步独立复核权不减免**（审查侧不采信实施方自查）；对账表可作交叉线索，但**不得**以它「已过」替代逐 case 核验。两者是「左移 + 复核」两条路径，非重复劳动。
+
 1. **Case-by-case verification**: For each case in the matrix:
    - Check if the test implementation exists (`test_file` + `test_method_name` match)
    - Verify assertions match the matrix's `expected` output

package/skills/contract-builder/SKILL.md

@@ -36,6 +36,10 @@ Before finalizing:
 
 Must make obvious: approved behavior, out-of-scope, constraints, batches, test obligations, review gates, and conditions that force a rewind to planning. Prefer compression over repeating planning details.
 
+**`## Errata Register`（勘误登记段，v0.63.0 新增）**：DP-3 批准后 planning 四件默认**冻结**，陈述性订正改记入契约的 `## Errata Register` 段（不改 planning 原文），以减少 `artifacts_hash` 漂移 → rebuild → revise 回路。段模板、六条冻结例外、三分处方表（matrix→rebuild / 契约段→refresh-hash / wave→revise）、**勘误写入后 MUST `tf execution refresh-hash`** 的操作序、以及例外 2 的判定升格与呈报纪律——**详见 `references/freeze-and-errata.md`（MUST 按该文件执行）**。
+
+**`## Gate Registry`（闸门登记段，v0.63.0 新增，MUST）**：列 `| id | phase | command | expected |`，声明本 change 全部 G 类闸门（`id` 形如 `G-1`），`gates-probed` 门禁按此逐 id 核对 dry-run 留档。**段存在性是硬要求**——缺段/解析失败 = FAIL（缺段与「零闸门」不可区分，v0.13 RC-1 内容型豁免已删除）；确无闸门写 `N/A: <理由>` 一行。`G-<n>`（命令型闸门）与团队同步点 G1–G5 是两套编号。模板与判定规则见 `references/bridging-gate-dry-run.md`。
+
 ## UI UX Delta Prototype Reference (v0.37.0 §68.5)
 
 When the change involves UI (design.md has a `## UI Contract` section), the execution-contract's `## UX 增量` section (consumed by `tf prototype-sync`) must **state the prototype version worktree path** in its first line:
@@ -181,6 +185,8 @@ Still requires DP-3 approval.
 
 **`tasks.md` 归属（v0.22 §85）**：hotfix/tweak 默认跳过（上条），但若该 change 确实需要任务记录，`tasks.md` 由本 skill 一并产出——归属 contract-builder（本 skill 已有 `tasks.md → Execution Batches` 的 Artifact Mapping，反向生成成本最低）；任务文本不再经 spec-writer（hotfix/tweak 已跳过它）。
 
+**该路径同样强制 `- [ ]` 形态（v0.63.0；feedback 20260923-013114 E1 横展）**：本 skill 产出的 `tasks.md`，**任务行 MUST 为 `- [ ]` checkbox 形态**——与 `spec-writer` 校验清单同口径，**hotfix/tweak 路径不因轻量而豁免**（否则零 checkbox → `tasks-complete` closing 死锁原样复现，且事后补勾选同样触发 `artifacts_hash` 漂移）。
+
 ## Guardrails
 
 - **状态字段禁写（v0.30.0；v0.22 §85 澄清写入白名单）**：仅写本 skill 的 `dp_3_*` 决策字段，以及本 skill 职责内的门禁豁免键——`test_matrix_skipped` / `test_matrix_skip_reason`（v0.13 §50）、`tasks_skipped` / `tasks_skip_reason`（v0.22 §85）；**MUST NOT** 修改 `state`/`workflow` 核心字段——状态转换由主代理经 `tf state transition` 执行。`tf state init` 只创建状态文件，不改 `state` 值（来源：workflow-feedback 2026-08-01）。
@@ -192,6 +198,21 @@ Still requires DP-3 approval.
 
 ## Post-Generation
 
+### 契约 post-generation 两动作（v0.63.0，MUST，均在 `tf state init` 之前）
+
+**① Facts Recheck**：对 `facts.json` 中契约将引用的键复测一次（防 specifying→bridging 漂移），差异写 `facts.bridging_recheck`。
+**位置**：契约初稿完成后、dry-run 之前（复测可能改变闸门 `expected` 基线数字，草稿态回写成本最低）。
+**差异（含超口径项）MUST 并入 DP-3 批准 ask 呈报**，裁决权归 LT——不得由实施方自行解释掉（错判即伪绿）。
+
+**② Bridging Gate Dry-Run**：对每个 **pre-build** 闸门在主工作区当前态跑一次（预期 FAIL = RED 基线），落
+`.superpowers/test-evidence/bridging-gates-red.txt`。硬要求：首行逐字 `EXPECTED: FAIL (RED baseline)` /
+必须含 `CONTRACT_HASH: sha256:…` 行（新鲜度按**内容**判，不用 mtime）/ 每个注册 id 一个 `[G-<id>]` 分节 /
+原始输出先落文件 / 多仓逐仓分节 cwd / `post-build` 闸门只做语法可执行性 probe。
+若某闸门意外 PASS → 复核契约声明（它不是有效基线），不要改 evidence。
+**Rewind 或契约重生成后 evidence 失效，须重跑。**
+
+> 两动作的完整模板与理由见 `references/bridging-gate-dry-run.md`。
+
 Run `tf state init <change-dir>` to create `.team-flow.yaml` with hashes.
 
 For hotfix, after writing the minimal contract, run `tf state init <change-dir>` or `tf state rebuild <change-dir>` so `contract_hash` is recorded. DP-3 remains mandatory before build.

package/skills/contract-builder/references/bridging-gate-dry-run.md

@@ -0,0 +1,89 @@
+# bridging 闸门登记与 dry-run 留档（v0.63.0；feedback 20260923-013114 S2 + S1 复测）
+
+本文件承载契约 post-generation 的两个动作细则。SKILL 保留 MUST 与指针，细则在此。
+
+---
+
+## 一、`## Gate Registry`（闸门登记段，MUST）
+
+声明本 change 的全部 G 类闸门，`gates-probed` 门禁按此逐 id 核对 dry-run 留档。列固定为 `| id | phase | command | expected |`：
+
+```markdown
+## Gate Registry
+
+| id | phase | command | expected |
+|----|-------|---------|----------|
+| G-1 | pre-build | `npx eslint src/` | 0 errors |
+| G-2 | pre-build | `npm run test:unit -- --coverage` | covered 132 |
+```
+
+- `id` 形如 `G-1`/`G-2`，须与契约内各闸门小节**一一对应**（审查侧会核对）。
+- **`G-<n>` 是命令型质量闸门编号**，与团队同步点编号 **G1–G5**（§68.2 等）是**两套命名空间**，勿混用。
+- `phase: post-build` 类闸门同样登记，其 dry-run 只做**语法/路径可执行性 probe**（不预跑结果）。
+- 契约改动（含勘误段）后须**重跑 dry-run**（evidence 的 `CONTRACT_HASH` 比对会判陈旧）。
+
+### 段存在性是硬要求（fail-closed）
+
+**缺段 = `gates-probed` FAIL**——缺段与「零闸门」不可区分，v0.13 RC-1 的内容型豁免已删除。
+
+> **workflow 限定**：本维度只挂 **full** 的 `bridging→approved-for-build`。**hotfix** 走 `WORKFLOW_TRANSITION_CHECKS` 自有覆盖、**天然不挂本维度**（无需注册该段）；**tweak** 会回落继承本维度，须靠 `gates_probed_skipped` + 理由放行。
+
+**两种「无闸门」表达的判定规则**：
+
+| 情形 | 写法 | 结果 |
+|---|---|---|
+| 确无 G 类闸门 | 段存在 + `N/A: <理由>` 一行 | PASS（N/A 记录） |
+| 临时豁免（不想写段） | `tf state set <dir> gates_probed_skipped true` + `gates_probed_skip_reason '<理由>'` | PASS（可审计豁免） |
+| 忘写段 / 表解析失败 | — | **FAIL**（不得落 N/A） |
+
+> 优先用**段内 `N/A: <理由>`**（理由随契约入库、随 hash 冻结）；state 键是备用通道，仅在段写法不便时使用。
+
+---
+
+## 二、Bridging Gate Dry-Run（MUST，在 `tf state init` 之前）
+
+契约产出后，对 `## Gate Registry` 声明的每个 **pre-build** 闸门，在**主工作区当前态**跑一次
+——此时实现尚未开始，**预期结果是 FAIL**，这个 FAIL 就是 RED 基线（与 TDD 的红证据同源）。
+
+**产出**：`.superpowers/test-evidence/bridging-gates-red.txt`
+
+```text
+EXPECTED: FAIL (RED baseline)
+CONTRACT_HASH: sha256:<64 位十六进制>
+
+[G-1] npx eslint src/
+<闸门原始输出，不得摘要或改写>
+exit=1
+
+[G-2] npm run test:unit -- --coverage
+<闸门原始输出>
+exit=1
+```
+
+**六条硬要求**：
+
+1. **首行逐字** `EXPECTED: FAIL (RED baseline)`；
+2. **必须有 `CONTRACT_HASH: sha256:…` 行**，取当前 `execution-contract.md` 的 hash——新鲜度按**内容**判（不用 mtime：契约字节等价重生成、或 git 恢复会让 mtime 变新而内容未变，会误卡）；
+3. **每个注册 id 都要有 `[G-<id>]` 分节**——缺 id 会被门禁点出；
+4. **原始输出先落文件**再写本 evidence（不写管道中间结果）；
+5. **多仓**：逐仓声明执行 cwd，evidence 内逐仓分节；
+6. **`phase: post-build` 的闸门**只做语法/路径可执行性 probe，不预跑结果。
+
+> 本步把 `design.md` R-7「闸门命令已实测可跑」的文字自证物化为机械证据。
+> 若某闸门在此步**意外 PASS**，说明它不是有效基线（已实现/已满足），须复核契约声明而非改 evidence。
+> **Rewind 或契约重生成后，既存 evidence 失效**，须重跑（`CONTRACT_HASH` 比对可兜底，但纪律须遵守）。
+
+---
+
+## 三、Facts Recheck（MUST，在 dry-run 之前）
+
+对 `<change-dir>/.superpowers/facts.json` 中**契约将要引用的键**复测一次（防 specifying→bridging 期间漂移），
+差异写入 `facts.bridging_recheck` 段。
+
+**位置说明（避免与 §3.1 的「生成前」表述混淆）**：复测动作在**契约初稿完成后、dry-run 之前**执行——
+因为复测结果可能改变契约为闸门声明的基线数字（`expected` 列），此时契约尚在草稿态、回写成本最低。
+**DP-3 批准 ask 必须晚于本复测**（差异摘要要并入那次 ask）。
+
+**差异呈报（MUST）**：差异摘要（含**超出口径声明**的项）**并入 DP-3 批准 ask 一并呈报**，裁决权归 LT。
+**不得**由实施方（含主会话）自行解释掉——错判方向即伪绿（把超口径差异解释为「口径问题」→ 闸门基线数字错）。
+无法在声明口径内解释的差异 → 触发**契约侧重签判断**，不要带着已知漂移进入执行。

package/skills/contract-builder/references/freeze-and-errata.md

@@ -0,0 +1,81 @@
+# 规划制品冻结与契约勘误登记（v0.63.0；feedback 20260923-013114 S3）
+
+> **来源**：v2-C2（跨 4 仓命名统一，生产逻辑实改 ≈1 if + 1 enum + 3 文案）三轮 dispatch 实证——规划制品数字靠抄写而非实测，
+> 过期声明 6 处 + 派生描述 4 处 + tasks 测试计数 3 处 + 契约/矩阵计数 3 处，每轮订正触发 `artifacts_hash` 漂移 →
+> `contract-fresh` 失败 → rebuild → plan revise（`.team-flow.yaml:7 revision: 3` 三次重签全可定位）。
+
+## 1. 冻结规则
+
+DP-3 批准后，**planning 四件（proposal.md / specs/ / design.md / tasks.md）默认冻结**。
+
+陈述性订正**不再改 planning 原文**，改记入 `execution-contract.md` 的 **`## Errata Register`（勘误登记段）**。
+
+## 2. 勘误登记段模板
+
+追加到契约的固定段名与字段：
+
+```markdown
+## Errata Register
+
+| 日期 | 原文（planning 制品:位置） | 订正后 | 例外条款 | 授权人 | 留痕 |
+|------|--------------------------|--------|---------|--------|------|
+| 2026-09-22 | design.md §Risks 第 3 条 | 基线 115 → 132 | 例外 1（作者裁决） | LT | dp_3_result |
+```
+
+- **留痕要求**：每行必须有 `例外条款` 与 `授权人`；订正前原文须可追溯（引用制品位置，必要时附原句）。
+- 勘误段**入 `contract_hash`**（契约全文入 hash），故写入后必须按下节操作序处理。
+
+## 3. 操作序（MUST）
+
+> **勘误段写入后 MUST 执行 `tf execution refresh-hash`。**
+>
+> **理由**：写契约 = 改 `contract_hash`；不 refresh 会卡 `execution-plan-ready`（该维度挂 `executing:closing` 与 `debugging:executing`）——**恰复活了本机制要消除的 revision 回路**。
+> **先例**：`references/glaf4-delegation.md`（契约改 hash → 必须先 refresh-hash）。
+
+## 4. 三分处方表（禁止混用）
+
+| 变更对象 | 处方 | 说明 |
+|---|---|---|
+| `test-matrix.md` 段 | `tf state rebuild` | 矩阵 hash 独立（`hash.mjs computeTestMatrixHash`） |
+| 契约段（含 `## Errata Register`） | `tf execution refresh-hash` | 只动 plan 内嵌的 `contract_hash`，不碰 state |
+| wave / 执行模式变更 | plan revise | 结构性变更，走重规划 |
+
+**rebuild 与勘误段的存续顺序**：`tf state rebuild` 会重建契约 → **勘误段随旧契约丢失**，须在 rebuild 后将勘误段**回填**（回填内容以 `dp_N_result` + 审查报告为源）。
+
+## 5. 冻结例外（六条，均须留痕）
+
+| # | 例外 | 处置 |
+|---|------|------|
+| 1 | **作者级裁决落地**（LT/业务作者定稿变更，如 C2-CONFLICT-001 desc1） | 按契约裁决记录 + 订正前原文留痕；**若触及 gate-affecting → 回归例外 2** |
+| 2 | **gate-affecting 勘误必改**（矩阵 expected/方法名、闸门基线数字、契约 Test Matrix 段） | 触发 rebuild → revise |
+| 3 | **checkbox 勾选回写**（进度位） | **显式豁免**——`hash.mjs normalizeCheckboxes` 已归一化，不属冻结对象（否则与 v0.49.0 修复自相矛盾） |
+| 4 | **显式 Rewind 后的修改**（scope→re-specify、contract→re-bridge） | 冻结**不豁免** Rewind |
+| 5 | **Review Findings 分轨文本订正**（M-1/M-2 类纯文本缺陷） | 经 doc-only 授权、收口波次落地，与代码修复分轨 |
+| 6 | **LT 书面授权兜底** | 须写入 `dp_N_result` 或契约勘误段 |
+
+**例外授权升级序**：例外 6 **不可与其他例外叠加降级**——不得以「LT 曾授权例外 6」为由豁免例外 2 的判定复核；例外 1 如触及 gate-affecting，**回归例外 2** 处理。
+
+## 6. 非例外（禁止）
+
+- 无新证据的措辞美化
+- 把陈述性订正**伪装**成 gate-affecting（或其反向：把 gate-affecting 记成陈述性）
+- 绕过 Rewind 改 brief 级范围
+
+## 7. 例外 2 的判定与呈报（防伪绿关键）
+
+**判定权升格**：实施方仅**提议**，**判定由审查侧复核**（code-reviewer）+ closing 侧反查。**自判错判的方向恰是伪绿出口**。
+
+**呈报纪律（MUST）**：
+
+1. 「例外 2 提议 + 判定依据 + `## Errata Register` 摘要」**并入 wave review prompt**；
+2. **根仓 planning 制品 diff 单列进审查范围**——多仓场景下 wave `base..head` 的 git range 解析到**子仓**，而 planning 制品在**根仓**，子仓 diff 里看不到它们被改；
+3. **未在 DP-3 摘要中呈报的差异，不得执行 `tf execution refresh-hash`**（该命令是唯一能把「改过 planning」从 `validatePlan` 比对中抹掉的操作）。
+
+**closing 侧反查锚（v0.63.0 新增）**：`executing:closing` 维度已补挂 `contract-fresh`——它比对 `state.artifacts_hash` 与制品实算值，**`refresh-hash` 无法清屏**（后者只改 plan JSON）。
+
+## 8. 机械强度如实声明
+
+v0.63.0 **不加专用冻结 guard 维度**。本期 = 本文件纪律 + Staleness advisory + `contract-fresh`（含 closing 新挂）+ `executing:closing` 反查三者合成。
+**硬门禁**（DP-3 写 planning 快照 hash + closing 快照比对）归**远期上游 PR**。
+
+**收益如实拆分**：本机制消除的是**陈述性订正**的回路；**gate-affecting 订正仍走例外 2 → 仍触发 rebuild→revise**（v2-C2 的 revision 3 订正大半属此类）。不得宣称「消除了全部重签回路」。

package/skills/prototype/references/orchestration-flow.md

@@ -112,7 +112,7 @@ agent 直接写审查报告到 `requirement/vN/prototype-auto-review.md`。
 ## 步骤 ⑥ 人工评审路由（主代理）
 
 主代理用 AskUserQuestion 呈现评审结论 + 争议项，LT 选择：
-- **PRD 有问题** → 回 orchestrator S2 修订 PRD（**vN 内修订 + 变更履历，非升版**；见 feedback-loops 设计）→ PRD 更新后再回 ① 更新原型。**独立调用 fallback**（非 orchestrator 触发时）：无 S2 可回，直接提示 LT 修订 `requirement/vN/prd.md` 后重入本 skill。
+- **PRD 有问题** → 回 orchestrator S2 修订 PRD（**正文就地更新为最新态 + 变更记录写 `dialogue-log.md`，非升版**；见 feedback-loops 设计）→ PRD 更新后再回 ① 更新原型。**独立调用 fallback**（非 orchestrator 触发时）：无 S2 可回，直接提示 LT 修订 `requirement/vN/prd.md` 后重入本 skill。
 - **原型需调整**（美观/体验/品牌/信息密度等自动评审查不到的维度）→ **⛔ 必须通过 SendMessage 恢复原 prototype-builder 实施调整**（`SendMessage(to: builder_agent_id, message: "用户评审反馈：{调整意见}。请修改原型。")`），修改后 SendMessage 恢复原 prototype-reviewer 重新评审。**禁止启动新子代理**（唯一例外：SendMessage 恢复失败时的 fallback）
 - **通过** → 冻结：PRD frontmatter `frozen: true`（frozen_downstream），prototype 定版
 - **设计系统增量确认（v0.54.0，新增分支）**：若 builder handoff 的 `outstanding_questions` 含 `ds_increment` 条目（`missing_component` / `outdated_token` / `new_variant`），在本次 AskUserQuestion 中**并入**呈现：

package/skills/release-archivist/SKILL.md

@@ -254,6 +254,15 @@ tf solutions promote <change-dir>
 
 同步对象：实施代码 `changes/<change-dir>/` + arch-merge 回写（docs/architecture/）+ test-ledger（docs/test-ledger/）。**原型独立仓库场景**：若本 change 有 UX 增量回写原型，push 对应 `prd-vN` 分支（`tf prototype branch <prd-vN>` 确认/创建 worktree）。
 
+**决策点攒批与预批复单（v0.63.0；feedback 20260923-013114 S5）**：
+
+- **同根因攒批（MUST）**：同一根因的多个发现**攒成一次 ask**，不得逐个往返确认。
+- **closing 边界并入**：**DP-6 与 roadmap/push 边界并入同一次 closing 确认**（既有确认点合并三组为 DP-0+DP-A、DP-3+G4+DP-4、DP-7+落地+G5，**均不含 DP-6**，故本项为新增；三组清单以 `docs/decision-points.md` 为准）。
+- **批量预批复单模板**（closing 型变更可启用）：一次性列出全部待确认项 + 各项的建议取值 + 理由，由用户一次批复。
+
+> **⛔ 防伪绿护栏（MUST）**：**门禁类 DP（`dp_3` / `dp_4`）禁止超时代答**——这两个字段是 `dp-gate-passed` 门禁的数据源（`checks/dp-gate-passed.mjs` 仅映射 dp_3/dp_4）。**预批复只作用于非门禁确认**；DP-6 预批复为**条件式**（机器门禁全 PASS 才生效）。
+> **Rewind 作废**：Rewind 后已发出的预批复**自动作废**，须重新征询。
+
 ### Worktree Deisolation (v0.35.0) — advisory
 
 After compound promotion, check if worktree isolation exists for this change:

package/skills/spec-writer/SKILL.md

@@ -84,6 +84,8 @@ Run: `tf runtime config --get artifacts.order` — generate in configured order
 
 **Honor Architecture (v0.9 §26, v0.10 §28-§31)**: 若 `architecture/` 目录存在，design.md 的 Decisions 段必须引用其架构决策（聚合/限界上下文/CQRS/API/DB），tasks.md 的接口定义（对齐 api.md 架构路由表）和数据层任务（引用 sql/ddl/ + sql/migration/ 脚本路径）必须与 architecture/ 产出对齐——不得静默忽略或矛盾架构设计产出。
 
+**Fact Referencing (v0.63.0；feedback 20260923-013114 S1)**: 制品中凡涉及**基线数字、测试计数、目标行号、枚举现状、编号在册性**，一律从 `<change-dir>/.superpowers/facts.json` 引用键名，**不裸写数字**（抄写的事实下轮修订即漂移 → `artifacts_hash` 漂移 → 契约重签）。每个键须带采集命令 / 时间戳 / 口径声明。**强度如实声明**：这是**纪律条款**，不是硬门禁（`tf facts probe` 与 WARNING lint 归远期上游 PR）；但 facts.json 不进任何 hash，无新回路。判据四条（`command grep` / 原始输出先落文件 / 模式自证 / 数字注明命令+环境+时间戳+口径）见 `references/facts-referencing.md`（含跨仓 `repos.<name>` 结构与 bridging 复测呈报纪律）。
+
 ### proposal.md
 Must state: problem, what changes, capabilities affected, impact areas.
 
@@ -144,6 +146,7 @@ Generate one at a time. Confirm each before next. This prevents scope drift —
 
 ### tasks.md
 - `## File Structure`, `## Interfaces`, numbered tasks, exact file paths, TDD phases, ≤5 min steps, no placeholders, every requirement mapped, explicit dependencies
+- **任务行形态强制 `- [ ]`（v0.63.0；feedback 20260923-013114 E1）**：tasks.md 的**每条任务行 MUST 生成为 `- [ ]` checkbox 形态**，不得写成纯编号/纯列表。理由：`templates/tasks.md` 本就是 `- [ ]` 形态；`tasks-complete` 门禁对零已勾选**无条件 FAIL**（closing 死锁）；`hash.mjs` 的 `normalizeCheckboxes` 只归一化勾选态、**救不了行结构变化**——事后补 checkbox 会造成 `artifacts_hash` 漂移 + 契约重签（v2-C2 实证：wave1 即知风险、拖到 closing 才改，致 revision 3 重签）。生成期一行约束即同时消掉「closing 死锁」与「hash 漂移重签」双源头。
 - **接口交叉核对（v0.35.0，v0.14 §61.1）**：若 `architecture/api.md` 存在，机械比对 `tasks.md` `## Interfaces` 声明的端点集合与 `api.md` 架构路由表端点集合——tasks 引用了 api.md 未声明的端点、或 api.md 声明的关键端点 tasks 未落地 → 告警修正（traceability 从自报升级为机械比对）
 
 **If any artifact fails validation, fix before handing off to contract-builder.**

package/skills/spec-writer/references/facts-referencing.md

@@ -0,0 +1,64 @@
+# 事实引用惯例（v0.63.0；feedback 20260923-013114 S1）
+
+> **来源**：v2-C2 实证——规划制品里的数字靠**抄写**而非实测：过期声明 6 处 + 派生描述 4 处 +
+> tasks 测试计数 3 处 + 契约/矩阵计数 3 处（均带【订正】标记）。每轮订正触发 `artifacts_hash` 漂移 →
+> `contract-fresh` 失败 → rebuild → plan revise（revision 3 三次重签全可定位）。
+
+## 1. 规则
+
+**基线数字必须写成带来源的形式：`<值>（facts:<键>，ts=<时间戳>）`——脱离 facts 键的裸值即违规。**
+
+（值本身当然要写在制品里才能读懂；违规的是「值没有可追溯的 facts 键与采集时点」，不是「出现了数字」。
+阈值类 specs 正常书写不受影响。）
+
+凡涉及以下内容，一律写入 `<change-dir>/.superpowers/facts.json` 并在制品中**引用键名**：
+- G1/G2 残差基线（如「G2 违规数 119 → 132」）
+- 各仓测试计数
+- 目标文件 / 目标行号
+- 枚举现状、PRD 编号在册性
+
+**强度如实声明**：「禁止裸数字」**不是硬门禁**——自由 markdown 上硬禁会全量误报。本惯例是
+**纪律条款**（`tf facts probe` 子命令与 WARNING lint 均归远期上游 PR，v0.63.0 未实现）。
+但 facts.json 本身**不进任何 hash**（`hash.mjs` 白名单仅 proposal/specs/design/tasks/architecture），
+所以写 facts 不产生新回路。
+
+## 2. facts 三件套（每个键必带）
+
+| 项 | 要求 |
+|---|---|
+| **采集命令** | 可原样复跑的命令行 |
+| **时间戳** | ISO 8601 UTC |
+| **口径声明** | 含/不含副本、排除目录清单 |
+
+**跨仓**：facts.json **仍为单文件**，per-repo 数据以 `repos.<name>.{test_counts, target_lines, enums}`
+分节；`repos` 的键集合须与 `repo_layout` 一致（缺仓 = facts 不完整，须补采）。
+
+```json
+{
+  "repos": {
+    "ui": { "test_counts": { "value": 16, "command": "command grep -c '@Test' …", "ts": "2026-09-22T09:00:00Z", "scope": "含 dist 行" } }
+  }
+}
+```
+
+## 3. 判据四条（母本 161200；以下为转述，以母本为准）
+
+1. 扫描/计数一律 `command grep`（绕过 shell function 包装）；
+2. 原始输出**先落文件**，计数从落盘文件算出（不对管道中间结果计数）；
+3. 扫描脚本必含**模式自证段**（探针证明模式有效，防空结果假 PASS）；
+4. 每个基线数字注明**采集命令、时间戳、口径**——注意 161200 原文是「采集命令与**采集环境**」，
+   **时间戳**属本文件三件套要求（专家评审 :49），二者分开陈述、不混同转述。
+
+## 4. bridging 复测（防 specifying→bridging 漂移）
+
+契约生成前由 **contract-builder** 复测一次 facts，差异计入 `facts.bridging_recheck` 段。
+
+**差异裁决（MUST）**：差异摘要（含超口径项）**并入 DP-3 批准 ask 一并呈报**，裁决权归 LT。
+**不得**由实施方（含主会话）自行解释掉——错判方向即伪绿：把超口径差异解释为「口径问题」→
+闸门基线数字错。无法在声明口径内解释的差异 → 触发**契约侧重签判断**。
+
+## 5. 反模式
+
+- ❌ 写数字但不带 `facts:<键>` 与 `ts=`（下轮修订即漂移，且无从核对口径）
+- ❌ 同一事实在多个制品各写一遍（口径不一致的根源）
+- ❌ 引用其它 change 的计数而不声明它的采集时点

package/skills/workflow-orchestrator/SKILL.md

@@ -85,7 +85,7 @@ prd_draft → user_review → prototype_loop → prd_frozen → completed
 - **错误行为**：PRD草稿完成后直接标记S3阶段完成
 - **正确行为**：PRD草稿完成后等待用户查看，确认后继续S2阶段的后续步骤
 
-调用 `/ce-brainstorm`（mode: orchestrated）产出 PRD 草稿（Phase 3 由 prd-writer agent 契约级撰写，v0.47）；**冻结前派 `prd-completeness-reviewer` 子代理做 PRD 完整性评审**（v0.15.0，管"说得全不全"；v0.47 并入 §8.4 契约级细节 D6 维度）；原型循环由编排层直接编排（prototype skill 内部编排产出 → prototype-reviewer 自动评审 → 人工评审 → 冻结）；冻结语义为 `frozen_downstream`（迭代内变更不升版）。反馈环路检查点：scope 是否合理。详见 `references/s2-prd-prototype-loop.md`。
+调用 `/ce-brainstorm`（mode: orchestrated）产出 PRD 草稿（Phase 3 由 prd-writer agent **按 `prd-84-authoring-spec.md` 业务可读撰写**，v0.62.0）；**冻结前派 `prd-completeness-reviewer` 子代理做 PRD 完整性评审**（v0.15.0，管"说得全不全"；v0.47 并入 D6 维度，**v0.62.0 改为 §8.4 信息齐备性 + 业务可读形态核验 G7**）；原型循环由编排层直接编排（prototype skill 内部编排产出 → prototype-reviewer 自动评审 → 人工评审 → 冻结）；冻结语义为 `frozen_downstream`（迭代内变更不升版）。反馈环路检查点：scope 是否合理。详见 `references/s2-prd-prototype-loop.md`。
 
 ### ARCH: 产品级架构设计（v0.36.0 新增；2026-08-19 LT 调整上移 S3 前——S3 计划/S4 拆分是最终任务拆分，须基于架构）
 

package/skills/workflow-orchestrator/references/feedback-loops.md

@@ -36,17 +36,22 @@ S5→S4 回退时，按在途 change 状态分区处置（前置条件）：
 - 回退时受影响制品重命名为 `.revN`（保留审计轨迹）
 - 重新进入阶段**不读取上一轮制品**，只读取修订后的上游制品，避免旧内容锚定
 
-## 变更履历格式
+## 变更记录格式（v0.62.0：迁出 PRD）
 
-记录在 PRD 文档的「决策与变更履历」章节：
+**记录位置 = `requirement/vN/dialogue-log.md`**（**不再写进 PRD 正文**——PRD 只承载最新态；
+正文若保留历史，即违反「单一真相」原则，且会被 `prd-completeness-reviewer` 的形态核验判 Important）。
 
 ```markdown
 ### 决策与变更履历
-| 时间 | 触发阶段 | 变更内容 | 原因 | 影响范围 |
-|------|---------|---------|------|---------|
-| 2026-07-24 | S3→S2 | 砍掉功能X | plan 分析发现技术不可行 | §7 功能清单、§8 处理说明 |
+| 变更编号 | 时间 | 触发阶段 | 受影响需求 ID | 受影响功能 ID | 变更前 | 变更后 | 理由 | 决策人 |
+|---|---|---|---|---|---|---|---|---|
+| CHG-001 | 2026-07-24 | S3→S2 | REQ-007 | F3 | 保留功能X | 砍掉功能X | plan 分析发现技术不可行 | LT |
 ```
 
+- **受影响需求 ID / 功能 ID 为强制字段**（不可留空：「无」也须显式写，不得空着）
+- **「理由」列为强制字段**——变更履历的价值在于下游能重建「为什么这样定」
+- PRD 侧只保留 §1.2 修订记录的**一行一句话摘要**（≤ 200 字），并指向本文件
+
 ## 与双层冻结的关系
 
 - S3→S2 回退 = **临时解除 frozen_downstream**，S2 重新完成后恢复