@tea-agent/loop-agent 0.33.0 → 0.33.2

package/skills/analyze-product-requirements/references/forward-test-cases.md

@@ -5,34 +5,34 @@
 ## Case 1：无需澄清
 
 ```text
-Use $analyze-product-requirements --target frontend.
+显式调用 `analyze-product-requirements` skill，参数：`target=frontend`。
 需求：登录用户在个人资料页修改自己的昵称；昵称 2–20 个字符；保存失败时保留输入并允许重试；不修改头像。
 ```
 
-核对：三个产物都在 `<project-root>/docs/product-analysis/<requirement-id>/`；三者 `analysis_scope` 均为 `frontend`；Product Analysis 为 `no-clarification-required` 且不含正式 AC；Clarification 使用三章精简结构且没有 BR/Q/DEC；Product Requirement 为 complete；故事与同 ID 输出规范一一对应。
+核对：生成产物前直接询问用户是否还有内容需要补充；未收到明确的“无需补充/确认继续”前不冻结 Product Analysis、不生成 complete 产物；用户确认后，三个产物都在 `<project-root>/docs/product-analysis/<requirement-id>/`，三者 `analysis_scope` 均为 `frontend`；Product Analysis 为 `no-clarification-required` 且不含正式 AC，其“原始需求”包含有效 `inline:sha256:*` 身份，每个前端初步输出规范包含有效页面路由；Clarification 使用三章精简结构、记录相同的原始需求身份和 `内容补充：用户已确认无需补充`，且没有 BR/Q/DEC；Product Requirement 为 complete，不含“默认假设”或“未决事项”；故事与同 ID 输出规范一一对应，每个前端规范均包含有效页面路由。
 
 ## Case 2：需要逐题澄清
 
 ```text
-Use $analyze-product-requirements target=both.
+显式调用 `analyze-product-requirements` skill，参数：`target=both`。
 需求：管理员可以导出用户数据。
 ```
 
-核对：先列 3–6 个分支；从管理员角色和敏感字段范围开始；每轮先推荐再只问一个主要问题；收到回答后重新识别模糊点；`clarification_rounds` 和问题轮次一致且最多为 3。第 3 轮后仍有 P0/P1 时保持 pending，不再提问、不自行补全；不得回写 Product Analysis。
+核对：角色定义、导出范围、敏感字段、文件格式、有效期和失败行为中任何推断、含糊、缺失或多种合理解释都进入待确认问题；按实际决策树列出分支；每轮先推荐再只问一个决策问题；收到回答后重新扫描全部未确认产品内容；`clarification_rounds` 和问题轮次一致且不受人为上限约束；全部分支收敛后必须汇总范围、规则、状态/边界、已确认默认行为和非目标，并询问用户确认或补充；用户补充后重新收敛并再次汇总确认；明确确认前保持 pending；不得回写 Product Analysis。
 
 ## Case 3：后端 API 业务需求
 
 ```text
-Use $analyze-product-requirements target=backend.
+显式调用 `analyze-product-requirements` skill，参数：`target=backend`。
 需求：登录用户查询自己订单的退款状态，失败时看到可理解原因，内部错误不得泄露。
 ```
 
-核对：BE 故事只保留能力、使用方、价值、触发方式和 AC 引用；同 ID 输出规范明确输入输出语义、权限和规则；不虚构最终 URL、HTTP 方法、DTO 或代码落点。
+核对：必须先询问该接口实现为 Web、Remote 还是 Web + Remote；确认前保持 pending。确认后 BE 故事只保留能力、使用方、价值、明确的 `API（Web）|API（Remote）|API（Web + Remote）` 触发方式和 AC 引用；同 ID 输出规范明确输入输出语义、权限和规则；不虚构最终 URL、HTTP 方法、DTO 或代码落点。
 
 ## Case 4：非 API 后端任务
 
 ```text
-Use $analyze-product-requirements target=backend.
+显式调用 `analyze-product-requirements` skill，参数：`target=backend`。
 需求：每天归档 90 天前已完成通知，重复执行不得重复归档。
 ```
 
@@ -41,7 +41,7 @@ Use $analyze-product-requirements target=backend.
 ## Case 5：回答仍然模糊
 
 ```text
-Use $analyze-product-requirements target=both.
+显式调用 `analyze-product-requirements` skill，参数：`target=both`。
 需求：管理员可以导出用户数据。
 第一轮询问导出字段范围时，用户回答：敏感字段按实际情况处理。
 ```
@@ -59,8 +59,86 @@ Use $analyze-product-requirements target=both.
 ## Case 7：代码事实不得泄漏到最终需求
 
 ```text
-Use $analyze-product-requirements target=backend，并提供一个仓库。
+显式调用 `analyze-product-requirements` skill，参数：`target=backend`，并提供一个仓库。
 需求：仅管理员可以导出用户数据。仓库中现有权限判断位于 src/auth/permission.ts，使用 role=admin。
 ```
 
 核对：Product Analysis 可记录 `CODE-FACT-*`、证据路径和现状；Clarification 可引用该证据辅助判断，但不得把现状自动视为目标决策；Product Requirement 只写“仅管理员可以导出用户数据”等产品规则，不包含 `CODE-FACT-*`、`src/auth/permission.ts`、`role=admin`、代码符号、模块结构或当前实现过程。
+
+## Case 8：分页允许值来源
+
+```text
+显式调用 `analyze-product-requirements` skill，参数：`target=backend`。
+A：需求明确 pageSize 为必填，但未给出允许值集合。
+B：需求明确 pageSize 允许值为 5、10、20。
+```
+
+知识库分页规范允许值为 `20/50/100`。核对：A 使用有效知识库规范的 `20/50/100`；B 原样沿用 `5/10/20`，不得被知识库或默认集合覆盖。知识库不可用或未命中时，A 才使用默认集合 `10/20/50/100`。不得从知识库/API 文档自动带入路径、方法、参数名、必填性、默认值、响应、错误码或 DTO。
+
+## Case 9：项目状态与空数据规范
+
+使用包含统一空状态组件、loading/error 枚举和同类列表页的仓库。核对：当前宿主支持隔离的只读代码侦察 agent 时优先委派探索；不支持时由当前 agent 执行同等范围的受限、定向搜索；Product Analysis 与 Product Requirement 使用项目真实状态名、共享空状态组件及恢复交互；不得用 generic `empty` 或自造文案替代项目规范。
+
+## Case 10：unknown 分流
+
+仓库中未定位到空数据规范，但需求要求定义空数据展示。核对：把目标空数据行为作为产品决策逐题澄清，不询问代码位置。若仅未定位到组件文件或状态枚举声明位置，则保留 `CODE-FACT-*` unknown 并交给依赖 skill，不进入澄清或 Product Requirement。
+
+## Case 11：所有实际问题都由用户确认
+
+使用包含推断需求和 P2 产品行为决策的需求。核对：每项推断需求都进入待确认问题并由用户逐题确认；用户确认前 Clarification 和 Product Requirement 保持 pending；不得生成 `default-confirmed` 或 `confirmed-default`；complete 时每个实际 `Q-*` 都为 `confirmed/user`。
+
+## Case 12：原始明确行为不伪造问题
+
+原始需求明确指定页面路由、权限和错误恢复方式。核对：这些内容以 `source-requirement` 事实直接合并，不生成 `Q-*`、`DEC-Q-*` 或二次确认。
+
+## Case 13：页面路由
+
+分别使用独立页面、嵌入式抽屉以及两个共享同一页面的前端故事。核对：Product Analysis 和 Product Requirement 的每个前端故事输出规范都包含页面路由；独立页面写以 `/` 开头的目标 URL；抽屉写“`不适用；嵌入 /所属页面 页面`”；共享页面的两个故事分别填写同一路由，不得合并或省略；不得写路由配置文件、框架组件或 middleware。
+
+## Case 14：pending 与 complete 结构
+
+存在产品行为 unknown 时，pending Product Requirement 必须包含“未决事项”；全部确认后重新生成 complete 文档并删除该章节。两种状态都不得生成“默认假设”。
+
+## Case 15：普通执行验证范围
+
+核对普通需求分析只运行 Product Analysis、Requirement Clarification 和 Product Requirement 三个当前产物 validator，不运行 `test-validators.mjs`。
+
+## Case 16：知识库命中与证据边界
+
+使用需要空状态、错误语义和分页约定的需求，并让 `kb-design-assist` 返回可定位、当前有效的设计系统及分页规范。核对：先检索知识库再定向核验仓库；Product Analysis 记录 `executed-hit` 和结构完整的 `KB-FACT-*`；Product Requirement 使用规范化后的产品行为，但不包含 `KB-FACT-*`、知识库路径、搜索过程、Controller/Service/Entity/Response 等实现规范名称。
+
+## Case 17：知识库强制前置、未命中或不可用
+
+分别使用“看似不涉及项目规范”的简单需求、让 `kb-design-assist` 返回无结果，以及让调用失败。核对：简单需求仍先从需求提取检索词并真实调用知识库，不允许 `not-executed`；无结果记录 `executed-no-match`，在有仓库时降级为受限、定向的代码库规范搜索，无仓库时按 unknown 分流；调用失败记录 `unavailable`，必须先说明失败原因并询问用户选择“修复后重试”或“跳过知识库”，未选择前不得预扫描项目资料、探索代码库或生成 complete 产物；选择修复后按重试结果继续，明确选择跳过后才允许降级。不得把“未执行”误写成“未命中”，也不得绕过确认门禁。
+
+## Case 18：知识库与需求冲突
+
+原始需求明确分页允许值为 `5/10/20`，知识库规范为 `20/50/100`；另提供一份与原始错误恢复行为冲突的设计规范。核对：分页沿用原始需求；用户可见行为冲突进入逐题澄清，用户裁决前保持 pending；不得静默采用知识库结果。
+
+## Case 19：Web + Remote 接口范围
+
+需求只写“实现订单列表接口”。核对：必须询问 Web、Remote 或两者；用户确认两者后写 `触发方式：API（Web + Remote）`，不新增接口形态字段，也不在 Product Requirement 中虚构 `/order/list` 或 `/remote/order/list`。
+
+## Case 20：项目资料预扫描
+
+知识库检索结束后提供包含 `ai_workspace/project-how-to`、`code-specification`、`project-business` 的仓库。核对：常规代码搜索前按固定顺序枚举并定向读取三个目录；目录缺失时记录 `not-found` 并继续；资料事实不能替代真实代码证据。
+
+## Case 20A：知识库、代码库与澄清顺序
+
+使用同时包含权限歧义、状态约定和已有相似实现的需求。核对执行轨迹严格为：从原始需求提取检索计划 → 调用 `kb-design-assist` → 项目资料预扫描 → 按知识结论定向探索代码库 → 汇总冲突与 unknown → 逐题向用户澄清。不得在知识库门禁通过前搜索代码，也不得在代码事实尚可查证时提前询问用户。
+
+## Case 21：提示词冻结与来源身份
+
+分别使用 inline 与文件输入生成 Product Analysis。核对：inline 身份只绑定准确正文；file 身份同时绑定规范化真实路径与正文；Clarification 记录相同原始需求身份。完整内容先写入正式 `product-analysis.md`，随即以归一化 target 校验正式文件；首次失败时把同源正式文件保留为未冻结草稿，当前或后续轮次均可继续修正，首次返回 exit 0 后立即冻结并进入澄清。冻结后当前及后续轮次不得再次对正式路径调用写入、格式化、移动或删除工具；Step 5 只读复验。使用相同正文但不同文件路径继续任务时，同源判定必须停止。
+
+## Case 21A：正式文件校验通过后才冻结
+
+构造缺少必填章节或 target 不匹配的 Product Analysis。核对：完整内容先写入正式路径但保持未冻结；validator 非 0 时允许修正正式文件，且不得开始逐题澄清；执行中断后重新进入时，同源文件校验失败仍视为未冻结草稿并继续修正。首次返回 exit 0 后立即冻结并进入澄清，冻结后再次修改必须被流程拒绝。
+
+## Case 22：pending 状态一致性
+
+构造 `pending Clarification + pending Product Requirement`、`pending + complete`、`complete + pending` 三组。核对：第一组仅在显式 `--allow-pending` 时通过；后两组始终失败；最终交付与依赖 skill 不使用 `--allow-pending`。
+
+## Case 23：严格结构与全局唯一性
+
+分别向三个产物 frontmatter 注入 `source_path`，让两个故事复用同一个 AC ID，并把 complete Clarification 的“最终决策”改为“未形成”。核对：额外 frontmatter 字段、重复 AC ID 和未形成最终决策都被 validator 拒绝。

package/skills/analyze-product-requirements/references/kb-integration.md

@@ -0,0 +1,56 @@
+# kb-design-assist 接入契约
+
+每个新 requirement 完成输入识别后，必须先根据需求内容使用当前宿主原生的 skill 加载机制调用第三方 `kb-design-assist`，再预扫描项目资料和探索代码库。即使需求简单、未显式提到项目规范，或模型预判知识库可能没有结果，也不得跳过真实检索。
+
+## 调用输入
+
+先从原始需求提取业务目标、角色、领域对象、关键动作、状态/边界、权限、接口与分页线索，再向 `kb-design-assist` 提供：
+
+- 可识别的项目、产品或知识库范围；无法确定时使用当前项目上下文，不得臆造范围。
+- 已归一化的 `target`、相关故事、业务关键词、领域对象和待查问题。
+- 需要检索的规范类别；只查询与当前需求直接相关的内容，不做无边界扫描。
+- 返回要求：规范结论、文档标题与章节/定位、版本或生效状态、适用范围、置信度、冲突与未定位项。
+
+需求分析优先查询设计系统、交互/文案规范、用户可见状态枚举、共享状态组件、权限可见性、错误语义和分页允许值。Controller、Service、Entity、Response、Remote、Web API 或 `interfaces.md` 等纯实现规范仅用于判断当前问题是否属于下游技术设计，不得据此扩写产品需求。
+
+知识库状态已确定或用户确认跳过后，再按固定顺序预扫描 `<project-root>/ai_workspace/project-how-to`、`code-specification`、`project-business`，然后才进入常规代码搜索。目录缺失不阻断；命中内容作为项目资料事实记录，并按知识库、项目资料、代码现状之间的冲突规则处理。
+
+## 结果状态
+
+当前宿主可发现 `kb-design-assist` 时，使用宿主原生的 skill 加载机制调用。知识检索必须记录一种真实状态：
+
+- `executed-hit`：已执行并命中可定位、适用且有效的规范。
+- `executed-no-match`：已执行，但没有与当前问题相关的结果。
+- `unavailable`：`kb-design-assist` 未安装、不可发现、调用失败或无法访问目标知识库。
+
+未执行知识库检索属于流程违规，不得生成 Product Analysis。未执行时不得声称“未命中”；调用失败时不得模拟结果。`executed-no-match` 和 `unavailable` 均不得伪装为 `executed-hit`。
+
+状态为 `executed-no-match` 时直接触发降级：有仓库时执行受限、定向的代码库搜索，只查找与当前问题直接相关的规范或共享定义；没有仓库时按 unknown 分流。`executed-hit` 不触发规范降级，但仍必须探索代码库以核验现状。
+
+状态为 `unavailable` 时不得直接降级。立即停止后续知识查证与 complete 产物生成，向用户说明可观察到的失败原因，并单独询问选择：
+
+1. **修复后重试**：等待用户修复安装、发现、调用或访问问题，再重新调用 `kb-design-assist`；以重试后的真实结果状态继续流程。
+2. **跳过知识库**：仅在用户明确同意后，记录 `- 用户处置：已确认跳过知识库`，再执行与 `executed-no-match` 相同的受限、定向代码库降级；没有仓库时按 unknown 分流。
+
+用户未明确选择前保持阻断，不得自动重试、自动跳过、自动降级或把 `unavailable` 改写为其他状态。正常任务为定位当前实现而进行的代码核验不属于降级，但不得借此绕过该确认门禁或把代码现状冒充项目规范。
+
+## 事实与优先级
+
+每条有效结果使用 `KB-FACT-*`，记录规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响和置信度。过期、适用范围不明、相互冲突或无法定位来源的结果不得作为已确认规范，只能记录为冲突或 unknown。
+
+产品行为来源优先级：
+
+1. 用户已确认决策。
+2. 原始需求明确内容。
+3. 当前有效且适用于本项目的知识库规范。
+4. 模型推断或通用兜底。
+
+知识库与用户决策、原始需求或另一份有效规范冲突时，保留证据并生成产品澄清问题，用户裁决前不得选边。知识库事实只能填补项目规范，不得发明业务范围、业务规则或用户意图。
+
+分页允许值遵循：原始需求/用户确认 > 有效知识库分页规范 > 固定兜底 `10/20/50/100`。即使知识库命中 API 文档，也不得自动带入路径、方法、参数名、必填性、默认值、响应结构、错误码或 DTO。
+
+## 产物边界
+
+- Product Analysis 的“知识库事实”记录检索状态及 `KB-FACT-*`；代码证据继续使用 `CODE-FACT-*`。
+- Requirement Clarification 可引用 `KB-FACT-*` 解释冲突或推荐理由。
+- Product Requirement 只能保留不含来源标识和技术证据的目标产品行为；不得出现 `KB-FACT-*`、知识库搜索过程、文档路径或实现规范名称。

package/skills/analyze-product-requirements/references/product-analysis-schema.md

@@ -1,32 +1,41 @@
-# Product Analysis V3 输出契约
+# Product Analysis V4 输出契约
 
-Product Analysis 是澄清前快照，只允许一次创建。首次写入后，正文、frontmatter 和路径全部冻结；需要更正时使用新的 `requirement_id`。
+Product Analysis 是澄清前快照，只允许一次创建。首次写入后，正文、frontmatter 和路径全部冻结，后续轮次不得再对该路径调用写入、格式化、移动或删除工具。冻结只由 skill 提示词约束，不创建完整性 sidecar，也不由 validator 检测外部修改；需要更正时使用新的 `requirement_id`。
 
 ```yaml
 ---
-artifact_version: "3.0"
+artifact_version: "4.0"
 artifact_type: product-analysis
 requirement_id: <lowercase-slug>
-project_root: ../../..
 analysis_scope: frontend | backend | both
 analysis_status: ready-for-clarification | no-clarification-required
-source_requirement: <路径或 inline>
-repository_root: <路径或 none>
 ---
 ```
 
+Frontmatter 只允许以上五个字段，不得增加来源路径、项目根或其他运行时字段。
+
 文件固定为 `<project-root>/docs/product-analysis/<requirement-id>/product-analysis.md`。
 
-固定章节：原始需求、需求概述、业务目标、需求分析、外部事实。需求分析包含明确需求、推断需求、待确认问题、初步非目标；外部事实包含知识库事实、代码库事实。
+固定章节：原始需求、需求概述、业务目标、需求分析、外部事实。原始需求必须包含 `- 原始需求身份：inline:sha256:<64位小写十六进制>` 或 `- 原始需求身份：file:sha256:<64位小写十六进制>`，并保留准确原文；inline 摘要只绑定正文，file 摘要同时绑定规范化真实路径与正文，均使用 `scripts/compute-source-identity.mjs` 生成。不得把原始路径另写入 frontmatter。
+
+需求分析包含明确需求、推断需求、待确认问题、初步非目标；外部事实包含知识库事实、代码库事实。“知识库事实”必须先记录 `executed-hit | executed-no-match | unavailable` 状态；每个新 requirement 都必须真实执行知识检索，不允许未执行状态。若 complete 流程最终仍记录 `unavailable`，必须同时记录 `- 用户处置：已确认跳过知识库`，否则不得生成本产物。有效事实使用 `KB-FACT-*`，包含规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响和置信度。“代码库事实”继续使用 `CODE-FACT-*`。
 
 按 scope 追加“初步前端用户故事/初步前端输出规范”或“初步后端用户故事/初步后端输出规范”。不得生成独立用户角色或验收标准汇总。
 
 前端故事字段：角色、目标、价值、入口、验收关注点。
 
-后端故事字段：系统能力、使用方、业务价值、触发方式、验收关注点。触发方式使用 API、定时任务、事件、消息、内部调用或数据迁移。
+后端故事字段：系统能力、使用方、业务价值、触发方式、验收关注点。触发方式使用 `API（Web）`、`API（Remote）`、`API（Web + Remote）`、定时任务、事件、消息、内部调用或数据迁移。需求只说明“接口/API”但没有确认 Web、Remote 或两者时，必须进入待确认问题，不得自行选择。
+
+每个故事必须恰好存在一个同 ID 输出规范。前端输出规范字段：页面/组件、页面路由、展示内容、交互动作、UI 状态、表单校验、权限可见性、边界处理。后端输出规范字段：输入语义、输出语义、数据读写、权限规则、业务规则、安全要求、幂等与并发、错误与边界。
 
-每个故事必须恰好存在一个同 ID 输出规范。前端输出规范字段：页面/组件、展示内容、交互动作、UI 状态、表单校验、权限可见性、边界处理。后端输出规范字段：输入语义、输出语义、数据读写、权限规则、业务规则、安全要求、幂等与并发、错误与边界。
+每个前端故事的同 ID 输出规范都必须独立填写页面路由，不得因多个故事共享页面而省略。独立页面写以 `/` 开头的目标 URL；没有独立路由的组件、弹窗或抽屉写“`不适用；嵌入 /account/profile 页面`”这类模板，必须包含真实 `/…` 路径并以“页面”结尾。不得填写路由注册文件、框架路由组件、route config 或 middleware。
+
+状态变量、UI 状态、空数据、loading、error、disabled、错误文案和兜底行为必须优先采用 `kb-design-assist` 查明的当前有效项目规范，再核验设计系统、共享组件和同类实现；未查明时标为 unknown，不得把通用模式写成项目事实。影响产品行为或验收的 unknown 进入待确认问题；纯实现/代码落点 unknown 只保留在外部事实中。
+
+后端分页：以原始需求/用户确认为准。输入已给出每页条数允许值时原样记录；未说明时优先使用 `kb-design-assist` 返回的当前有效分页规范，仍未查明才按默认集合 `10`、`20`、`50`、`100` 生成。不得因此把知识库/API 文档的路径、方法、参数名、必填性、默认值、响应、错误码或 DTO 自动带入。Validator 不解析或推断分页允许值集合；该规则由生成流程和 forward-test 核对。
 
 Product Analysis 只记录验收关注点，不得出现正式 `AC-FE-*`、`AC-BE-*` 或 Given/When/Then 块。
 
-`no-clarification-required` 的待确认问题明确写“无”和理由，不得出现问题标记、优先级或问句；`ready-for-clarification` 至少包含一个带优先级或问号的问题。
+推断需求一律属于未确认产品内容。任何推断需求，以及原始需求、知识库、代码核验或分析过程中发现的含糊、缺失、冲突、多种合理解释或目标行为 unknown，都必须进入待确认问题并在后续逐题向用户澄清。纯代码位置、符号、复用点和实现方式不属于产品需求，继续留在代码库事实中。
+
+`no-clarification-required` 只允许在“推断需求”包含独立一行 `- 无未确认的推断需求。` 且“待确认问题”包含独立一行 `- 无待确认问题。` 时使用；待确认问题可另写理由，但不得出现问题标记、优先级、问句或其他未确认产品内容。`ready-for-clarification` 至少包含一个带优先级或问号的问题。

package/skills/analyze-product-requirements/references/product-requirement-schema.md

@@ -1,33 +1,42 @@
-# Product Requirement V3 输出契约
+# Product Requirement V4 输出契约
 
 Product Requirement 是澄清后的完整需求文档和下游唯一需求事实源。
 
 ```yaml
 ---
-artifact_version: "3.0"
+artifact_version: "4.0"
 artifact_type: product-requirement
 requirement_id: <lowercase-slug>
-project_root: ../../..
 requirement_status: pending | complete
 analysis_scope: frontend | backend | both
-source_requirement: <路径或 inline>
-source_product_analysis: ./product-analysis.md
-source_clarification: ./requirement-clarification.md
 ---
 ```
 
-固定章节：需求概述、业务目标、需求范围、业务规则、决策追溯。需求范围包含已确认需求、非目标、默认假设、未决事项。不得生成独立用户角色或验收标准汇总。
+Frontmatter 只允许以上五个字段，不得增加来源路径、项目根、仓库路径或其他运行时字段。
 
-Product Requirement 只描述目标产品行为，不承载代码侦察记录。不得包含 `CODE-FACT-*`、仓库文件路径、代码级类/函数/组件符号、模块调用关系、数据表名、证据位置、当前实现过程或实现算法。产品层的页面或组件名称仍可用于描述用户可见输出。代码库事实只可在经用户确认或被原始需求明确要求后，转换为不含实现细节的产品规则；原始证据保留在 Product Analysis 或 Clarification。
+固定章节：需求概述、业务目标、需求范围、业务规则、决策追溯。需求范围包含“已确认范围”和“非目标”。`pending` 与 `complete` 均禁止“默认假设”章节。`pending` 文档另含“未决事项”；`complete` 文档禁止“未决事项”。不得生成独立用户角色、验收标准汇总、前后端契约、Open Questions、测试建议或独立边界 case 章节。
+
+Product Requirement 只描述目标产品行为，不承载知识检索或代码侦察记录。不得包含 `KB-FACT-*`、`CODE-FACT-*`、知识库/仓库文件路径、代码级类/函数/组件符号、模块调用关系、数据表名、证据位置、当前实现过程或实现算法。产品层的页面或组件名称仍可用于描述用户可见输出。当前有效知识库规范只能在不与用户决策或原始需求冲突时转换为项目既定的产品规则；代码库事实只可在经用户确认或被原始需求明确要求后转换为不含实现细节的产品规则。原始证据保留在 Product Analysis 或 Clarification。
+
+机器校验至少拦截：`KB-FACT-*`、`CODE-FACT-*`、常见仓库路径（如 `src/`）、`*Controller/*Service/*Repository/*Handler/*Middleware` 符号，以及“证据位置”。其余实现泄漏仍按本契约人工遵守。知识库/仓库 API 技术惯例仅可在分析与澄清中查证；写入本产物的参数名、必填性、默认值必须来自原始需求或用户确认。
 
 按 scope 追加前端/后端用户故事和同域输出规范。
 
-前端故事字段：角色、目标、价值、入口、验收标准。后端故事字段：系统能力、使用方、业务价值、触发方式、验收标准。
+前端故事字段：角色、目标、价值、入口、验收标准。后端故事字段：系统能力、使用方、业务价值、触发方式、验收标准。入口描述用户如何到达能力，不替代目标 URL。
+
+每个故事必须恰好存在一个同 ID 输出规范。前端规范字段：页面/组件、页面路由、展示内容、交互动作、UI 状态、表单校验、权限可见性、边界处理。后端规范字段：输入语义、输出语义、数据读写、权限规则、业务规则、安全要求、幂等与并发、错误与边界。
 
-每个故事必须恰好存在一个同 ID 输出规范。前端规范字段：页面/组件、展示内容、交互动作、UI 状态、表单校验、权限可见性、边界处理。后端规范字段：输入语义、输出语义、数据读写、权限规则、业务规则、安全要求、幂等与并发、错误与边界。
+页面路由写以 `/` 开头的目标 URL。没有独立路由的组件、弹窗或抽屉写“`不适用；嵌入 /account/profile 页面`”这类模板：必须含真实 `/…` 路径并以“页面”结尾。可以描述 Path 参数的产品语义、用户可见 Query、进入条件和必要跳转；不得包含路由注册文件、框架路由组件、route config 或 middleware。
+
+状态变量、UI 状态、空数据、loading、error、disabled、错误文案和兜底行为必须遵循 `kb-design-assist` 或项目资料查明的当前有效规范，保留项目真实枚举、共享组件、文案和交互方式；影响产品行为的 unknown 未澄清前不得 complete，纯实现/代码落点 unknown 不进入本产物。
+
+后端分页允许值按“原始需求/用户确认 > 当前有效知识库分页规范 > 默认集合 `10`、`20`、`50`、`100`”确定。参数名、必填性、默认值和其他 API 契约必须来自原始需求或用户确认，不得从知识库/API 文档自动带入。Validator 不解析或推断分页允许值集合；该规则由生成流程和 forward-test 核对。
 
 正式 `AC-FE-*` 或 `AC-BE-*` 作为四级标题嵌入对应输出规范。故事的验收标准引用必须与该规范中的 AC 完全一致；AC 遵循 `acceptance-criteria.md`。
+每个 AC ID 在整个 Product Requirement 中必须全局唯一，不得在不同故事或不同输出规范中复用。
+
+后端触发方式明确写 `API（Web）`、`API（Remote）`、`API（Web + Remote）`、定时任务、事件、消息、内部调用或数据迁移。Web 与 Remote 都按 HTTP 接口处理；两者都需要时，下游必须生成两个独立 Method+Path。只写笼统的 `API` 不得 complete。
 
-后端触发方式明确写 API、定时任务、事件、消息、内部调用或数据迁移，供下游判断 API 适用性。
+`complete` 不得包含任何尚未确认的产品行为，也不得生成“默认假设”或“未决事项”。`pending` 必须生成“未决事项”且不得生成“默认假设”，真实未决项以 `P0：`、`P1：` 或 `P2：` 开头。用户接受推荐值后，将其写成已确认规则、输出规范或 AC，并在决策追溯登记；可使用“默认”描述已确认产品行为，但不得把模型假设作为需求来源。澄清决策使用 `DEC-Q-*` 在决策追溯中登记并定位到正式章节。
 
-`complete` 不得包含未解决 P0/P1。真实未决项以 `P0：`、`P1：` 或 `P2：` 开头。澄清决策使用 `DEC-Q-*` 在决策追溯中登记并定位到正式章节。
+`pending` Product Requirement 必须与 `pending` Requirement Clarification 成对生成和校验；`complete` 同理。`--allow-pending` 仅用于内部中间产物，不得用于最终交付或下游消费。

package/skills/analyze-product-requirements/references/requirement-clarification-schema.md

@@ -1,35 +1,66 @@
-# Requirement Clarification V3 输出契约
+# Requirement Clarification V4 输出契约
 
 ```yaml
 ---
-artifact_version: "3.0"
+artifact_version: "4.0"
 artifact_type: requirement-clarification
 requirement_id: <lowercase-slug>
-project_root: ../../..
 analysis_scope: frontend | backend | both
 clarification_status: pending | complete
-clarification_rounds: 0 | 1 | 2 | 3
-source_product_analysis: ./product-analysis.md
-target_product_requirement: ./product-requirement.md
+clarification_rounds: <大于等于 0 的整数>
 ---
 ```
 
-文件与 Product Analysis、Product Requirement 位于同一需求目录。
+Frontmatter 只允许以上六个字段，不得增加来源路径、项目根或其他运行时字段。
+
+文件与 Product Analysis、Product Requirement 位于同一需求目录；`analysis_scope` 必须与二者一致。
+
+“来源”或“澄清来源”固定包含：
+
+- `- Product Analysis：./product-analysis.md`
+- `- 原始需求身份：<与 Product Analysis 完全一致的 inline:sha256:* 或 file:sha256:*>`
+
+校验时核对 Product Analysis 与 Clarification 的原始需求身份。Product Analysis 的首次写入冻结由 skill 提示词约束，validator 不检测其外部修改。
 
 ## 无需澄清
 
-只生成三个章节：澄清结论、来源、合并结果。`clarification_rounds` 必须为 `0`。澄清结论写明 `no-clarification-required` 和理由；不得生成 `BR-*`、`Q-*`、`DEC-Q-*`。
+只生成三个章节：澄清结论、来源、合并结果。仅当 Product Analysis 的“推断需求”为 `- 无未确认的推断需求。` 且“待确认问题”为 `- 无待确认问题。` 时允许使用本结构。`clarification_rounds` 必须为 `0`。澄清结论写明 `no-clarification-required`、理由，以及一行 `- 内容补充：用户已确认无需补充`；不得生成 `BR-*`、`Q-*`、`DEC-Q-*`。
+
+在生成这些产物前，必须直接询问用户是否还有内容需要补充。用户补充时先并入输入并重新判断是否需要澄清；只有用户明确表示无需补充或确认继续时，才能把 Clarification 和 Product Requirement 标为 `complete`。这次确认不计入澄清轮次，也不生成额外章节或决策标记。
 
 ## 需要澄清
 
-固定章节：澄清来源、决策分支、问题记录、决策索引。定义 3–6 个 `BR-*` 分支，表格包含分支 ID、名称、优先级、依赖和状态。
+固定章节：澄清来源、决策分支、问题记录、决策索引。按实际决策树定义一个或多个 `BR-*` 分支，表格包含分支 ID、名称、优先级、依赖和状态。
+
+问题核心字段：
+
+| 字段 | 约束 |
+|------|------|
+| 澄清轮次 | 1…`clarification_rounds` 的整数 |
+| 分支 | 已定义的 `BR-*` |
+| 优先级 | `P0` \| `P1` \| `P2` |
+| 影响范围 | `common` \| `frontend` \| `backend` \| `both` |
+| 推荐答案 / 推荐理由 | 必填 |
+| 用户回答 / 最终决策 | 必填 |
+| 决策来源 | 仅 `user`（实际 `Q-*`） |
+| 状态 | `confirmed` \| `pending-blocking` \| `pending-non-blocking` |
+| 决策标记 | 必须为 `DEC-<Q-ID>`，如 `DEC-Q-001` |
+| 目标位置 | 指向范围、规则、故事、输出规范或 AC |
+
+条件字段：有前置依赖时写依赖问题；存在真实备选时写备选方案；状态为 `pending-non-blocking` 时必须写 `未确认影响`。
+
+`clarification_rounds` 必须为正整数，每个问题的澄清轮次不得超过该值。
 
-问题核心字段：澄清轮次、分支、优先级、影响范围、推荐答案、推荐理由、用户回答、最终决策、决策来源、状态、决策标记、目标位置。`clarification_rounds` 必须为 `1`–`3`，每个问题的澄清轮次不得超过该值。
+Clarification 与 Product Requirement 的状态必须一致：`pending` 只能配对 `pending`，`complete` 只能配对 `complete`。`--allow-pending` 只允许校验前一种内部中间状态；不带参数的交付校验只接受后一种。无需澄清的精简结构只能直接生成 complete，不存在 pending 精简结构。
 
-条件字段：有前置依赖时写依赖问题；存在真实备选时写备选方案；决策来源为 `code-evidence` 时写代码证据；状态为 `pending-non-blocking` 时写未确认影响。
+原始需求已经明确的产品行为作为 `source-requirement` 事实直接合并，不生成 `Q-*`、`DEC-Q-*` 或 `confirmed/user` 伪记录。代码事实用于查证现状，不作为产品决策来源；实现事实 unknown 不生成澄清问题。
 
-状态使用 confirmed、default-confirmed、pending-blocking、pending-non-blocking；决策来源使用 user、source-requirement、code-evidence、confirmed-default。决策标记必须为 `DEC-Q-*`。
+`complete` 要求：
 
-`complete` 要求全部分支 resolved；P0/P1 必须由用户明确回答并使用 confirmed/user；P2 可确认、使用已确认默认值，或在写明影响后延后。complete 时每个决策标记必须出现在 Product Requirement 的决策追溯中。
+1. 全部分支 `resolved`。
+2. 所有实际 `Q-*` 均为 `confirmed` + `user`，且用户回答不是“未回答/待确认/无”。
+   `最终决策` 必须已经形成，不能是“未形成/未回答/待确认/尚未确认/无”。
+3. 决策索引包含全部 `DEC-Q-*`，且含一行 `- 共同理解：已确认`（表示分支收敛后已向用户汇总范围、规则、状态/边界、默认产品行为和非目标，用户明确确认该汇总）。
+4. 每个决策标记出现在 Product Requirement 的决策追溯中。
 
-每轮在用户回答后重新识别模糊点，有必要才再澄清。最多 3 轮；第 3 轮后仍有 P0/P1 时产物必须保持 `pending`，不得继续追问或自行填补决策。
+不得通过推荐答案或默认假设完成需求。每轮只问一个决策问题，不设置轮数上限；仍有未解决决策或尚未确认最终共同理解时必须保持 `pending`。用户对共同理解汇总提出补充或修正后，必须重新收敛分支、重新汇总并再次请求确认。

package/skills/analyze-product-requirements/scripts/compute-source-identity.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+
+const [command, fileArg] = process.argv.slice(2);
+if (!["inline-source", "file-source"].includes(command) || !fileArg) {
+  console.error("Usage: node compute-source-identity.mjs <inline-source|file-source> <file>");
+  process.exit(2);
+}
+
+const path = resolve(fileArg);
+let body;
+try {
+  body = readFileSync(path);
+} catch (error) {
+  console.error(`Cannot read ${path}: ${error.message}`);
+  process.exit(2);
+}
+
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+
+if (command === "inline-source") {
+  console.log(`inline:sha256:${sha256(body)}`);
+} else {
+  let normalizedPath;
+  try {
+    normalizedPath = realpathSync(path);
+  } catch (error) {
+    console.error(`Cannot resolve source path ${path}: ${error.message}`);
+    process.exit(2);
+  }
+  console.log(`file:sha256:${sha256(Buffer.concat([Buffer.from(normalizedPath), Buffer.from([0]), body]))}`);
+}