@tea-agent/loop-agent 0.25.5 → 0.26.0

package/skills/ai-engineering-context/SKILL.md

@@ -1,48 +1,48 @@
----
-name: ai-engineering-context
-description: 当 AI coding agent 启动 loop-agent 工作、准备 DAG 或 Loop context、委派 role-specific 节点，或决定 requirements、facts、evidence、handoff notes 应落何处时使用。
----
-
-# AI Engineering Context
-
-Context 是工程 artifact，不是 chat 残留。须显式保留 requirements、role 边界、write authority、evidence 与 handoff facts。
-
-## When to Use
-
-在启动 task、DAG、workflow 或 Loop round；准备 role prompt；委派给 Cursor/Pi/shell/static executor；或处理 stale plan、冲突 requirements、缺失 evidence 时使用。
-
-不要用于 private platform paths、personal memory、Google Drive 规则，或替代 task skills。
-
-## Context Priority
-
-按以下顺序优先采信 facts：最新 user instruction；task source/contract；DAG/Loop artifacts；ai_workspace/loop-agent/plans/ADRs；code/tests；chat history 仅作 hint。
-
-若 sources 冲突，停止并点明冲突。
-
-## Role Boundaries
-
-- Planner：contract、DAG shape、write boundary、verification plan；不做 implementation edits。
-- Scout：code/test/doc/artifact facts；不写 repo。
-- Implementer：在 writeSet 内做 bounded changes；不扩大 scope 或宣称完成。
-- Reviewer：bugs、regressions、missing tests、risk；除非被指派，否则不重写。
-- Verifier：command evidence、reproduction、failure category；model judgment 不是 proof。
-- Supervisor：gates、escalation、repair scope；不绕过 write-guard 或 human-gate。
-- Closeout：evidence、risks、next steps；不隐藏 failures。
-
-## Prompt Contract
-
-每个 delegated node prompt 应包含：objective、task id、role、executor、allowed paths、forbidden paths、writeSet、upstream artifact refs、concise excerpts、output contract、expected evidence、non-goals、stop conditions。
-
-read-only node 只能在 node output 返回 findings。不得在 repo 中创建 scratch files。
-
-## Persistence Rules
-
-Requirements 与 constraints 写入 task `source/`。Execution state 与 node artifacts 写入 `.harness/`。Durable plans、reports、decisions 写入 `ai_workspace/loop-agent/`。可复用 process guidance 写入 `.agents/skills/`。Chat 仅 transient。
-
-## Failure Handling
-
-- Missing context：运行 scout 或读取 durable source。
-- Ambiguous requirement：implementation 前更新 contract。
-- Verification failure：改 code 前先 diagnose cause。
-- Missing skill instructions：视为 context defect；不要假设 hidden behavior。
-- Missing fresh verification：不要 close out。
+---
+name: ai-engineering-context
+description: 当 AI coding agent 启动 loop-agent 工作、准备 DAG 或 Loop context、委派 role-specific 节点，或决定 requirements、facts、evidence、handoff notes 应落何处时使用。
+---
+
+# AI Engineering Context
+
+Context 是工程 artifact，不是 chat 残留。须显式保留 requirements、role 边界、write authority、evidence 与 handoff facts。
+
+## When to Use
+
+在启动 task、DAG、workflow 或 Loop round；准备 role prompt；委派给 Cursor/Pi/shell/static executor；或处理 stale plan、冲突 requirements、缺失 evidence 时使用。
+
+不要用于 private platform paths、personal memory、Google Drive 规则，或替代 task skills。
+
+## Context Priority
+
+按以下顺序优先采信 facts：最新 user instruction；task source/contract；DAG/Loop artifacts；ai_workspace/loop-agent/plans/ADRs；code/tests；chat history 仅作 hint。
+
+若 sources 冲突，停止并点明冲突。
+
+## Role Boundaries
+
+- Planner：contract、DAG shape、write boundary、verification plan；不做 implementation edits。
+- Scout：code/test/doc/artifact facts；不写 repo。
+- Implementer：在 writeSet 内做 bounded changes；不扩大 scope 或宣称完成。
+- Reviewer：bugs、regressions、missing tests、risk；除非被指派，否则不重写。
+- Verifier：command evidence、reproduction、failure category；model judgment 不是 proof。
+- Supervisor：gates、escalation、repair scope；不绕过 write-guard 或 human-gate。
+- Closeout：evidence、risks、next steps；不隐藏 failures。
+
+## Prompt Contract
+
+每个 delegated node prompt 应包含：objective、task id、role、executor、allowed paths、forbidden paths、writeSet、upstream artifact refs、concise excerpts、output contract、expected evidence、non-goals、stop conditions。
+
+read-only node 只能在 node output 返回 findings。不得在 repo 中创建 scratch files。
+
+## Persistence Rules
+
+Requirements 与 constraints 写入 task `source/`。Execution state 与 node artifacts 写入 `.harness/`。Durable plans、reports、decisions 写入 `ai_workspace/loop-agent/`。可复用 process guidance 写入 `.agents/skills/`。Chat 仅 transient。
+
+## Failure Handling
+
+- Missing context：运行 scout 或读取 durable source。
+- Ambiguous requirement：implementation 前更新 contract。
+- Verification failure：改 code 前先 diagnose cause。
+- Missing skill instructions：视为 context defect；不要假设 hidden behavior。
+- Missing fresh verification：不要 close out。

package/skills/analyze-product-dependencies/SKILL.md

@@ -1,67 +1,67 @@
----
-name: analyze-product-dependencies
-description: 基于 complete Product Requirement 探索代码库，按 frontend、backend 或 both 范围将故事、输出规范和验收标准映射到真实文件、组件、服务、数据、权限与证据，并仅为 API 型后端故事生成精简 Swagger 风格 Markdown API 文档。用于代码影响分析、依赖分析、API 文档或需求到代码映射。
----
-
-# Analyze Product Dependencies
-
-IRON LAW：`product-requirement.md` 是唯一需求事实源。不得从原始需求、Product Analysis、Clarification 或聊天重新解释需求，不得修改代码或上游产物。
-
-## 输入与产物
-
-- 必填：complete `product-requirement.md` 的实际路径和可读取代码仓库路径；Product Requirement 必须位于项目根的需求目录。
-- 可选：`target=frontend|backend|both` 或 `--target frontend|backend|both`；两种写法等价，默认继承上游 scope。
-- 输出写回 Product Requirement 所在目录；始终生成 `dependency-analysis.md`，选中 API 型后端故事时额外生成 `api-documentation.md`。
-
-## Workflow
-
-- [ ] Step 0：输入门禁 ⛔ BLOCKING
-  - [ ] 读取 `references/input-contract.md` 并运行 Product Requirement 输入校验器。
-  - [ ] 将 `target=<value>` 和 `--target <value>` 归一化为唯一 target；缺省时继承上游 scope，非法值或冲突的多个值必须停止。
-  - [ ] 从 Product Requirement 继承 `requirement_id`、`project_root` 和输出目录；显式 target 必须是上游 scope 的子集，只校验和分析选中故事。
-  - [ ] 在代码侦察前明确回显“分析范围：frontend | backend | both”；新增产物的 `analysis_scope` 必须等于该归一化 target，后续不得自动扩大范围。
-  - [ ] 门禁失败时只生成 blocked Dependency Analysis，不伪造 API 或代码落点。
-- [ ] Step 1：完整代码侦察 ⚠️ REQUIRED
-  - [ ] 读取 `references/scouting-rules.md`。
-  - [ ] 逐个读取选中故事及其同 ID 输出规范和 AC，再定位入口、调用链、状态、类型、数据、权限、错误、日志和测试；`frontend` 不分析 `BE-US-*`，`backend` 不分析 `FE-US-*`。
-  - [ ] 区分 confirmed、inferred、unknown，并为每项结论提供证据。
-- [ ] Step 2：判断 API 适用性 ⚠️ REQUIRED
-  - [ ] 只要一个选中的 `BE-US-*` 触发方式为 API，就必须生成 API 文档。
-  - [ ] target 为 `frontend` 时不读取或分析后端故事，不生成 API 文档或 API 实现映射。
-  - [ ] 定时任务、事件、消息、数据迁移或纯内部调用且不形成 HTTP 契约时，不生成空 API 文档。
-  - [ ] 无 API 时 Dependency Analysis 使用 `source_api_documentation: none`，API 实现映射明确写不适用。
-- [ ] Step 3：建立 Canonical API Model ⚠️ REQUIRED
-  - [ ] API 场景读取 `references/api-documentation-schema.md`。
-  - [ ] 结合 Product Requirement 的业务契约与仓库现有 API 规范，确定方法、路径、参数、响应、错误、Schema、分页、示例和代码落点。API 文档不输出认证方式或权限要求。
-  - [ ] 定义接口字段前，先搜索共享 DTO/Schema、OpenAPI components、统一响应和分页模型；命中时直接复用，不重复定义，不在 API 文档中输出搜索过程或“复用检查”。
-  - [ ] 定义返回 code 前，先搜索全局错误枚举、code 映射和错误响应外壳；命中时直接复用，仅未命中时才定义局部 code，不在 API 文档中输出搜索过程或“复用检查”。
-  - [ ] 分页接口将每页条数参数定义为可选，可选值必须完整包含 `10`、`20`、`50`、`100`；默认值仅在 Product Requirement 或仓库通用分页定义明确时写入。
-  - [ ] 产品需求优先于现状；业务语义缺失时阻断，不由本 skill 发明产品决策。
-  - [ ] API 文档只保留 HTTP 契约、字段、响应、错误与分页参数；完全移除认证方式、权限要求、业务规则、处理流程、分支逻辑、数据读写逻辑和实现算法及其相关内容。
-  - [ ] API 文档与依赖分析必须从同一模型渲染。
-- [ ] Step 4：生成产物 ⚠️ REQUIRED
-  - [ ] 读取 `references/dependency-analysis-schema.md`。
-  - [ ] API 场景先写 Swagger 风格 Markdown `api-documentation.md`，再写 `dependency-analysis.md`。
-  - [ ] `frontend` 产物只包含前端故事覆盖和前端依赖详情；`backend` 只包含后端故事覆盖、后端依赖详情和适用的 API 映射；`both` 才包含两端。
-  - [ ] `影响文件` 是每个故事的完整权威文件清单，使用 `F1`、`F2` 编号和 add/modify/reuse；其他落点字段引用这些编号，不重复完整路径。
-  - [ ] Dependency 的 API 实现映射只保留 API ID、Operation ID、方法路径和代码入口，不复制故事、AC 或完整接口文档。
-  - [ ] 所有新增产物与 Product Requirement 使用相同 `requirement_id`，同目录引用使用 `./文件名`。
-- [ ] Step 5：验证并交付 ⛔ BLOCKING
-  - [ ] Product Requirement 输入校验必须通过。
-  - [ ] 向 Product Requirement、Dependency 和适用的 API 校验器传入归一化 target；API 场景运行 API 和 Dependency 两个校验器，非 API 场景只运行 Dependency 校验器。
-  - [ ] 覆盖矩阵承担全局追溯，不生成重复的文末追溯汇总。
-  - [ ] 运行 validator matrix，修复全部错误后再声明完成。
-
-完整示例按需读取 `references/example.md`；维护或 forward-test 时读取 `references/forward-test-cases.md`。
-
-## Validation
-
-```bash
-node <skill-root>/scripts/validate-product-requirement-input.mjs <product-requirement.md> --target <frontend|backend|both>
-node <skill-root>/scripts/validate-api-documentation.mjs <product-requirement.md> <api-documentation.md> --target <backend|both>
-node <skill-root>/scripts/validate-dependency-analysis.mjs <product-requirement.md> <dependency-analysis.md> [api-documentation.md] --target <frontend|backend|both>
-node <skill-root>/scripts/test-validators.mjs
-```
-
-非 API 场景省略 API 校验器和 Dependency 校验命令的第三个参数。
-缺少 Product Requirement 的 blocked 场景使用 `none` 作为 Dependency 校验命令的第一个参数。
+---
+name: analyze-product-dependencies
+description: 基于 complete Product Requirement 探索代码库，按 frontend、backend 或 both 范围将故事、输出规范和验收标准映射到真实文件、组件、服务、数据、权限与证据，并仅为 API 型后端故事生成精简 Swagger 风格 Markdown API 文档。用于代码影响分析、依赖分析、API 文档或需求到代码映射。
+---
+
+# Analyze Product Dependencies
+
+IRON LAW：`product-requirement.md` 是唯一需求事实源。不得从原始需求、Product Analysis、Clarification 或聊天重新解释需求，不得修改代码或上游产物。
+
+## 输入与产物
+
+- 必填：complete `product-requirement.md` 的实际路径和可读取代码仓库路径；Product Requirement 必须位于项目根的需求目录。
+- 可选：`target=frontend|backend|both` 或 `--target frontend|backend|both`；两种写法等价，默认继承上游 scope。
+- 输出写回 Product Requirement 所在目录；始终生成 `dependency-analysis.md`，选中 API 型后端故事时额外生成 `api-documentation.md`。
+
+## Workflow
+
+- [ ] Step 0：输入门禁 ⛔ BLOCKING
+  - [ ] 读取 `references/input-contract.md` 并运行 Product Requirement 输入校验器。
+  - [ ] 将 `target=<value>` 和 `--target <value>` 归一化为唯一 target；缺省时继承上游 scope，非法值或冲突的多个值必须停止。
+  - [ ] 从 Product Requirement 继承 `requirement_id`、`project_root` 和输出目录；显式 target 必须是上游 scope 的子集，只校验和分析选中故事。
+  - [ ] 在代码侦察前明确回显“分析范围：frontend | backend | both”；新增产物的 `analysis_scope` 必须等于该归一化 target，后续不得自动扩大范围。
+  - [ ] 门禁失败时只生成 blocked Dependency Analysis，不伪造 API 或代码落点。
+- [ ] Step 1：完整代码侦察 ⚠️ REQUIRED
+  - [ ] 读取 `references/scouting-rules.md`。
+  - [ ] 逐个读取选中故事及其同 ID 输出规范和 AC，再定位入口、调用链、状态、类型、数据、权限、错误、日志和测试；`frontend` 不分析 `BE-US-*`，`backend` 不分析 `FE-US-*`。
+  - [ ] 区分 confirmed、inferred、unknown，并为每项结论提供证据。
+- [ ] Step 2：判断 API 适用性 ⚠️ REQUIRED
+  - [ ] 只要一个选中的 `BE-US-*` 触发方式为 API，就必须生成 API 文档。
+  - [ ] target 为 `frontend` 时不读取或分析后端故事，不生成 API 文档或 API 实现映射。
+  - [ ] 定时任务、事件、消息、数据迁移或纯内部调用且不形成 HTTP 契约时，不生成空 API 文档。
+  - [ ] 无 API 时 Dependency Analysis 使用 `source_api_documentation: none`，API 实现映射明确写不适用。
+- [ ] Step 3：建立 Canonical API Model ⚠️ REQUIRED
+  - [ ] API 场景读取 `references/api-documentation-schema.md`。
+  - [ ] 结合 Product Requirement 的业务契约与仓库现有 API 规范，确定方法、路径、参数、响应、错误、Schema、分页、示例和代码落点。API 文档不输出认证方式或权限要求。
+  - [ ] 定义接口字段前，先搜索共享 DTO/Schema、OpenAPI components、统一响应和分页模型；命中时直接复用，不重复定义，不在 API 文档中输出搜索过程或“复用检查”。
+  - [ ] 定义返回 code 前，先搜索全局错误枚举、code 映射和错误响应外壳；命中时直接复用，仅未命中时才定义局部 code，不在 API 文档中输出搜索过程或“复用检查”。
+  - [ ] 分页接口将每页条数参数定义为可选，可选值必须完整包含 `10`、`20`、`50`、`100`；默认值仅在 Product Requirement 或仓库通用分页定义明确时写入。
+  - [ ] 产品需求优先于现状；业务语义缺失时阻断，不由本 skill 发明产品决策。
+  - [ ] API 文档只保留 HTTP 契约、字段、响应、错误与分页参数；完全移除认证方式、权限要求、业务规则、处理流程、分支逻辑、数据读写逻辑和实现算法及其相关内容。
+  - [ ] API 文档与依赖分析必须从同一模型渲染。
+- [ ] Step 4：生成产物 ⚠️ REQUIRED
+  - [ ] 读取 `references/dependency-analysis-schema.md`。
+  - [ ] API 场景先写 Swagger 风格 Markdown `api-documentation.md`，再写 `dependency-analysis.md`。
+  - [ ] `frontend` 产物只包含前端故事覆盖和前端依赖详情；`backend` 只包含后端故事覆盖、后端依赖详情和适用的 API 映射；`both` 才包含两端。
+  - [ ] `影响文件` 是每个故事的完整权威文件清单，使用 `F1`、`F2` 编号和 add/modify/reuse；其他落点字段引用这些编号，不重复完整路径。
+  - [ ] Dependency 的 API 实现映射只保留 API ID、Operation ID、方法路径和代码入口，不复制故事、AC 或完整接口文档。
+  - [ ] 所有新增产物与 Product Requirement 使用相同 `requirement_id`，同目录引用使用 `./文件名`。
+- [ ] Step 5：验证并交付 ⛔ BLOCKING
+  - [ ] Product Requirement 输入校验必须通过。
+  - [ ] 向 Product Requirement、Dependency 和适用的 API 校验器传入归一化 target；API 场景运行 API 和 Dependency 两个校验器，非 API 场景只运行 Dependency 校验器。
+  - [ ] 覆盖矩阵承担全局追溯，不生成重复的文末追溯汇总。
+  - [ ] 运行 validator matrix，修复全部错误后再声明完成。
+
+完整示例按需读取 `references/example.md`；维护或 forward-test 时读取 `references/forward-test-cases.md`。
+
+## Validation
+
+```bash
+node <skill-root>/scripts/validate-product-requirement-input.mjs <product-requirement.md> --target <frontend|backend|both>
+node <skill-root>/scripts/validate-api-documentation.mjs <product-requirement.md> <api-documentation.md> --target <backend|both>
+node <skill-root>/scripts/validate-dependency-analysis.mjs <product-requirement.md> <dependency-analysis.md> [api-documentation.md] --target <frontend|backend|both>
+node <skill-root>/scripts/test-validators.mjs
+```
+
+非 API 场景省略 API 校验器和 Dependency 校验命令的第三个参数。
+缺少 Product Requirement 的 blocked 场景使用 `none` 作为 Dependency 校验命令的第一个参数。

package/skills/analyze-product-dependencies/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "产品依赖分析"
-  short_description: "把故事、输出规范和验收标准映射到真实代码与 API 文档"
-  default_prompt: "使用 $analyze-product-dependencies 将 Product Requirement 映射到代码，并按需生成 API 文档。"
+interface:
+  display_name: "产品依赖分析"
+  short_description: "把故事、输出规范和验收标准映射到真实代码与 API 文档"
+  default_prompt: "使用 $analyze-product-dependencies 将 Product Requirement 映射到代码，并按需生成 API 文档。"

package/skills/analyze-product-dependencies/references/api-documentation-schema.md

@@ -1,30 +1,30 @@
-# Swagger 风格 Markdown API 文档 V3 契约
-
-文件名固定为 `api-documentation.md`。它采用 Swagger 的信息组织方式，但不是 OpenAPI YAML。
-
-```yaml
----
-artifact_version: "3.0"
-artifact_type: api-documentation
-requirement_id: <与 Product Requirement 一致>
-project_root: ../../..
-api_status: complete
-analysis_scope: backend | both
-source_product_requirement: ./product-requirement.md
-repository_root: ../../..
----
-```
-
-固定章节：通用约定、API 索引、API 详情、数据模型、错误码。API 索引同时承担目录和故事/AC 追溯，不生成重复汇总。API 文档中完全移除认证方式、权限要求、业务规则、业务逻辑、处理逻辑和实现逻辑及其相关内容。
-
-通用约定包含 Base URL、统一响应结构、错误响应结构、分页约定、时间和标识符规范。不输出公共定义的搜索过程、命中证据或“复用检查”章节。
-
-每个接口标题使用 `### API-001 名称`，随后写 Swagger 风格方法路径。固定子章节：基本信息、成功响应、错误响应。非认证请求头、Path 参数、Query 参数、Request Body 按适用性生成；URL 有模板参数时必须生成 Path 参数。字段层面只写名称、类型、必填/可空、格式、枚举、契约约束和语义，不写计算、转换、查询或分支逻辑。
-
-基本信息只包含 Operation ID、变更类型和幂等性，不重复 API ID。API 索引包含 API ID、Method + Path、Operation ID、用户故事、AC、变更类型。
-
-成功响应包含至少一个 2xx 和合法 JSON 示例；错误响应包含至少一个 4xx/5xx 和合法 JSON 示例。变更类型使用新增、修改、复用。
-
-分页接口在 Query 参数中定义每页条数参数：必填性为“否”，允许值完整列为 `10 | 20 | 50 | 100`。参数名优先复用仓库现有约定，例如 `pageSize`、`page_size` 或 `limit`。只有 Product Requirement 或仓库通用分页定义明确时才写默认值，不再生成 `<100`、`=100`、`>100` 分页场景。
-
-“数据模型”只定义实际使用的 Schema 和字段；“错误码”只说明 HTTP 状态、code 和可观测的触发条件。两个章节均不新增“复用检查”，不输出公共定义搜索过程，不展开业务判定或实现逻辑。
+# Swagger 风格 Markdown API 文档 V3 契约
+
+文件名固定为 `api-documentation.md`。它采用 Swagger 的信息组织方式，但不是 OpenAPI YAML。
+
+```yaml
+---
+artifact_version: "3.0"
+artifact_type: api-documentation
+requirement_id: <与 Product Requirement 一致>
+project_root: ../../..
+api_status: complete
+analysis_scope: backend | both
+source_product_requirement: ./product-requirement.md
+repository_root: ../../..
+---
+```
+
+固定章节：通用约定、API 索引、API 详情、数据模型、错误码。API 索引同时承担目录和故事/AC 追溯，不生成重复汇总。API 文档中完全移除认证方式、权限要求、业务规则、业务逻辑、处理逻辑和实现逻辑及其相关内容。
+
+通用约定包含 Base URL、统一响应结构、错误响应结构、分页约定、时间和标识符规范。不输出公共定义的搜索过程、命中证据或“复用检查”章节。
+
+每个接口标题使用 `### API-001 名称`，随后写 Swagger 风格方法路径。固定子章节：基本信息、成功响应、错误响应。非认证请求头、Path 参数、Query 参数、Request Body 按适用性生成；URL 有模板参数时必须生成 Path 参数。字段层面只写名称、类型、必填/可空、格式、枚举、契约约束和语义，不写计算、转换、查询或分支逻辑。
+
+基本信息只包含 Operation ID、变更类型和幂等性，不重复 API ID。API 索引包含 API ID、Method + Path、Operation ID、用户故事、AC、变更类型。
+
+成功响应包含至少一个 2xx 和合法 JSON 示例；错误响应包含至少一个 4xx/5xx 和合法 JSON 示例。变更类型使用新增、修改、复用。
+
+分页接口在 Query 参数中定义每页条数参数：必填性为“否”，允许值完整列为 `10 | 20 | 50 | 100`。参数名优先复用仓库现有约定，例如 `pageSize`、`page_size` 或 `limit`。只有 Product Requirement 或仓库通用分页定义明确时才写默认值，不再生成 `<100`、`=100`、`>100` 分页场景。
+
+“数据模型”只定义实际使用的 Schema 和字段；“错误码”只说明 HTTP 状态、code 和可观测的触发条件。两个章节均不新增“复用检查”，不输出公共定义搜索过程，不展开业务判定或实现逻辑。

package/skills/analyze-product-dependencies/references/dependency-analysis-schema.md

@@ -1,28 +1,28 @@
-# Dependency Analysis V3 输出契约
-
-```yaml
----
-artifact_version: "3.0"
-artifact_type: dependency-analysis
-requirement_id: <与 Product Requirement 一致>
-project_root: ../../..
-analysis_scope: frontend | backend | both
-source_product_requirement: ./product-requirement.md | none
-source_api_documentation: ./api-documentation.md | none
-repository_root: ../../.. | none
-analysis_status: complete | blocked
-blocked_on: none | <原因列表>
----
-```
-
-Complete 固定章节：输入与代码基线、用户故事覆盖矩阵、按 scope 的依赖详情、后端场景的 API 实现映射、跨故事共享依赖、风险与未定位项。覆盖矩阵承担全局追溯，不生成独立分析范围或追溯汇总。
-
-前端详情字段：验收标准、影响文件、页面/路由、组件、状态、API client/类型、状态与边界落点、定位证据、风险、置信度。
-
-后端详情字段：验收标准、API 文档引用、影响文件、路由/入口、Controller/Handler、Service/领域逻辑、DTO/Schema、数据依赖、权限依赖、错误/日志/审计、测试落点、定位证据、风险、置信度。
-
-`影响文件` 是完整权威清单，每项使用唯一 `F<number>`、add/modify/reuse、真实路径和用途；其他代码落点字段引用这些编号，不重复完整路径。
-
-API 实现映射只登记 API ID、Operation ID、方法路径和代码入口。无 API 时写：`不适用。本次需求不涉及 HTTP API。`
-
-Blocked 产物只含分析范围、输入与代码基线、阻断原因、恢复条件，不得包含确定性代码位置或 API 契约。
+# Dependency Analysis V3 输出契约
+
+```yaml
+---
+artifact_version: "3.0"
+artifact_type: dependency-analysis
+requirement_id: <与 Product Requirement 一致>
+project_root: ../../..
+analysis_scope: frontend | backend | both
+source_product_requirement: ./product-requirement.md | none
+source_api_documentation: ./api-documentation.md | none
+repository_root: ../../.. | none
+analysis_status: complete | blocked
+blocked_on: none | <原因列表>
+---
+```
+
+Complete 固定章节：输入与代码基线、用户故事覆盖矩阵、按 scope 的依赖详情、后端场景的 API 实现映射、跨故事共享依赖、风险与未定位项。覆盖矩阵承担全局追溯，不生成独立分析范围或追溯汇总。
+
+前端详情字段：验收标准、影响文件、页面/路由、组件、状态、API client/类型、状态与边界落点、定位证据、风险、置信度。
+
+后端详情字段：验收标准、API 文档引用、影响文件、路由/入口、Controller/Handler、Service/领域逻辑、DTO/Schema、数据依赖、权限依赖、错误/日志/审计、测试落点、定位证据、风险、置信度。
+
+`影响文件` 是完整权威清单，每项使用唯一 `F<number>`、add/modify/reuse、真实路径和用途；其他代码落点字段引用这些编号，不重复完整路径。
+
+API 实现映射只登记 API ID、Operation ID、方法路径和代码入口。无 API 时写：`不适用。本次需求不涉及 HTTP API。`
+
+Blocked 产物只含分析范围、输入与代码基线、阻断原因、恢复条件，不得包含确定性代码位置或 API 契约。

package/skills/analyze-product-dependencies/references/example.md

@@ -1,76 +1,76 @@
-# V3 输出示例
-
-## API 索引与详情
-
-````md
-## 2. API 索引
-| API | Method + Path | Operation ID | 用户故事 | AC | 变更 |
-|---|---|---|---|---|---|
-| API-001 | GET /api/v1/orders/{orderId}/refund-status | getRefundStatus | BE-US-001 | AC-BE-001 | 新增 |
-
-## 3. API 详情
-### API-001 查询退款状态
-> `GET /api/v1/orders/{orderId}/refund-status`
-
-#### 基本信息
-| 字段 | 值 |
-|---|---|
-| Operation ID | getRefundStatus |
-| 变更类型 | 新增 |
-| 幂等性 | 只读请求天然幂等 |
-
-#### Path 参数
-| 参数 | 类型 | 必填 | 语义 |
-|---|---|---|---|
-| orderId | string | 是 | 订单标识 |
-
-#### 成功响应
-- HTTP：200
-```json
-{"data":{"refundStatus":"processing"}}
-```
-
-#### 错误响应
-| 状态码 | 错误码 | 条件 |
-|---|---|---|
-| 403 | FORBIDDEN | 资源访问被拒绝 |
-```json
-{"code":"FORBIDDEN","message":"forbidden"}
-```
-
-````
-
-无 Path、Query、Body 或专属 Header 时省略对应章节。
-
-分页接口在 Query 参数中定义可选的每页条数：
-
-```md
-#### Query 参数
-| 参数 | 类型 | 必填 | 允许值 | 语义 |
-|---|---|---|---|---|
-| pageSize | integer | 否 | 10 \| 20 \| 50 \| 100 | 每页条数 |
-| cursor | string | 否 | - | 下一页游标 |
-```
-
-字段与 code 定义前先在内部搜索仓库共享定义，命中时直接复用；API 文档不生成“复用检查”或搜索证据。
-
-## Dependency 影响文件与 API 映射
-
-```md
-### BE-US-001 查询退款状态
-- 验收标准：AC-BE-001
-- API 文档引用：API-001
-- 影响文件：
-  - F1 modify `src/refund/refund.controller.ts`：增加查询入口
-  - F2 modify `src/refund/refund.service.ts`：组合退款状态
-- 路由/入口：F1 注册退款状态路由
-- Controller/Handler：F1 校验身份和订单 ID
-- Service/领域逻辑：F2 组合状态
-
-## API 实现映射
-| API | Operation ID | 方法与路径 | 代码入口 |
-|---|---|---|---|
-| API-001 | getRefundStatus | GET /api/v1/orders/{orderId}/refund-status | F1 |
-```
-
-`影响文件` 是完整路径清单；其余字段使用 F 编号引用。非 API 后端故事不生成 API 文档。
+# V3 输出示例
+
+## API 索引与详情
+
+````md
+## 2. API 索引
+| API | Method + Path | Operation ID | 用户故事 | AC | 变更 |
+|---|---|---|---|---|---|
+| API-001 | GET /api/v1/orders/{orderId}/refund-status | getRefundStatus | BE-US-001 | AC-BE-001 | 新增 |
+
+## 3. API 详情
+### API-001 查询退款状态
+> `GET /api/v1/orders/{orderId}/refund-status`
+
+#### 基本信息
+| 字段 | 值 |
+|---|---|
+| Operation ID | getRefundStatus |
+| 变更类型 | 新增 |
+| 幂等性 | 只读请求天然幂等 |
+
+#### Path 参数
+| 参数 | 类型 | 必填 | 语义 |
+|---|---|---|---|
+| orderId | string | 是 | 订单标识 |
+
+#### 成功响应
+- HTTP：200
+```json
+{"data":{"refundStatus":"processing"}}
+```
+
+#### 错误响应
+| 状态码 | 错误码 | 条件 |
+|---|---|---|
+| 403 | FORBIDDEN | 资源访问被拒绝 |
+```json
+{"code":"FORBIDDEN","message":"forbidden"}
+```
+
+````
+
+无 Path、Query、Body 或专属 Header 时省略对应章节。
+
+分页接口在 Query 参数中定义可选的每页条数：
+
+```md
+#### Query 参数
+| 参数 | 类型 | 必填 | 允许值 | 语义 |
+|---|---|---|---|---|
+| pageSize | integer | 否 | 10 \| 20 \| 50 \| 100 | 每页条数 |
+| cursor | string | 否 | - | 下一页游标 |
+```
+
+字段与 code 定义前先在内部搜索仓库共享定义，命中时直接复用；API 文档不生成“复用检查”或搜索证据。
+
+## Dependency 影响文件与 API 映射
+
+```md
+### BE-US-001 查询退款状态
+- 验收标准：AC-BE-001
+- API 文档引用：API-001
+- 影响文件：
+  - F1 modify `src/refund/refund.controller.ts`：增加查询入口
+  - F2 modify `src/refund/refund.service.ts`：组合退款状态
+- 路由/入口：F1 注册退款状态路由
+- Controller/Handler：F1 校验身份和订单 ID
+- Service/领域逻辑：F2 组合状态
+
+## API 实现映射
+| API | Operation ID | 方法与路径 | 代码入口 |
+|---|---|---|---|
+| API-001 | getRefundStatus | GET /api/v1/orders/{orderId}/refund-status | F1 |
+```
+
+`影响文件` 是完整路径清单；其余字段使用 F 编号引用。非 API 后端故事不生成 API 文档。

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

@@ -1,35 +1,35 @@
-# Forward-Test Cases
-
-## Case 1：缩小为 frontend
-
-使用 complete、scope 为 both 的 Product Requirement 和真实仓库，指定 `--target frontend`。核对：只生成 `dependency-analysis.md`；`analysis_scope` 为 `frontend`；不生成空 API 文档；没有后端依赖章节、`BE-US-*` 或 API 实现映射；每个 FE 故事有文件证据和状态边界落点。
-
-## Case 2：backend API
-
-```text
-Use $analyze-product-dependencies with a complete backend Product Requirement whose BE-US-001 trigger is API, plus a repository.
-```
-
-核对：两个文件写入 Product Requirement 的同一需求目录；API 索引覆盖 API ID、Operation ID、方法路径、故事和 AC；Dependency 的 API 映射只保留 API ID、Operation ID、方法路径和代码入口；影响文件使用唯一 F 编号。
-
-同时核对：API 文档不含认证方式、权限要求、业务规则、业务逻辑或实现逻辑及其相关内容；字段与 code 在生成前内部搜索共享定义，但 API 文档不输出“复用检查”或搜索证据。若接口分页，每页条数参数必须可选，允许值完整包含 `10/20/50/100`。
-
-## Case 3：backend 定时任务
-
-使用触发方式为定时任务的归档需求。核对：只生成 Dependency；`source_api_documentation: none`；API 映射写不适用；重点定位 scheduler、job、幂等、批次、数据库和恢复测试。
-
-## Case 4：业务契约缺失
-
-使用缺少权限范围或输出语义的 API 型 Product Requirement。核对：不得发明产品决策；生成 blocked 依赖产物并返回上游补充。
-
-## Case 5：不存在的目标能力
-
-代码库中没有对应实现。核对：允许结论为新增，但证据必须展示已搜索范围和邻近模式；不得虚构文件已经存在。
-
-## Case 6：缩小分析范围
-
-使用 scope 为 both 的 Product Requirement，并指定 `target=backend`。核对：输入门禁通过；只要求 BE 故事覆盖；Dependency 和适用的 API 文档使用 `analysis_scope: backend`，不强制生成前端详情。
-
-## Case 7：缺少输入
-
-分别缺少 Product Requirement 和代码仓库。核对：只生成四个固定章节的 blocked Dependency；前者使用 `source_product_requirement: none`，后者允许 `repository_root: none`；不得生成 API 文档或确定性代码位置。
+# Forward-Test Cases
+
+## Case 1：缩小为 frontend
+
+使用 complete、scope 为 both 的 Product Requirement 和真实仓库，指定 `--target frontend`。核对：只生成 `dependency-analysis.md`；`analysis_scope` 为 `frontend`；不生成空 API 文档；没有后端依赖章节、`BE-US-*` 或 API 实现映射；每个 FE 故事有文件证据和状态边界落点。
+
+## Case 2：backend API
+
+```text
+Use $analyze-product-dependencies with a complete backend Product Requirement whose BE-US-001 trigger is API, plus a repository.
+```
+
+核对：两个文件写入 Product Requirement 的同一需求目录；API 索引覆盖 API ID、Operation ID、方法路径、故事和 AC；Dependency 的 API 映射只保留 API ID、Operation ID、方法路径和代码入口；影响文件使用唯一 F 编号。
+
+同时核对：API 文档不含认证方式、权限要求、业务规则、业务逻辑或实现逻辑及其相关内容；字段与 code 在生成前内部搜索共享定义，但 API 文档不输出“复用检查”或搜索证据。若接口分页，每页条数参数必须可选，允许值完整包含 `10/20/50/100`。
+
+## Case 3：backend 定时任务
+
+使用触发方式为定时任务的归档需求。核对：只生成 Dependency；`source_api_documentation: none`；API 映射写不适用；重点定位 scheduler、job、幂等、批次、数据库和恢复测试。
+
+## Case 4：业务契约缺失
+
+使用缺少权限范围或输出语义的 API 型 Product Requirement。核对：不得发明产品决策；生成 blocked 依赖产物并返回上游补充。
+
+## Case 5：不存在的目标能力
+
+代码库中没有对应实现。核对：允许结论为新增，但证据必须展示已搜索范围和邻近模式；不得虚构文件已经存在。
+
+## Case 6：缩小分析范围
+
+使用 scope 为 both 的 Product Requirement，并指定 `target=backend`。核对：输入门禁通过；只要求 BE 故事覆盖；Dependency 和适用的 API 文档使用 `analysis_scope: backend`，不强制生成前端详情。
+
+## Case 7：缺少输入
+
+分别缺少 Product Requirement 和代码仓库。核对：只生成四个固定章节的 blocked Dependency；前者使用 `source_product_requirement: none`，后者允许 `repository_root: none`；不得生成 API 文档或确定性代码位置。

package/skills/analyze-product-dependencies/references/input-contract.md

@@ -1,11 +1,11 @@
-# Product Requirement 输入契约
-
-首选输入为 complete V3 `product-requirement.md`。迁移期允许读取 complete V2，但不修改上游产物；新产物始终使用 V3。
-
-V3 必须包含精简用户故事、同 ID 输出规范和嵌入规范的 AC。故事与规范一一对应，故事 AC 引用与规范内 AC 完全一致。V2 继续按其原有嵌入故事的 AC 读取。
-
-必须提供存在、可读的代码仓库。Product Requirement 位于 `<project-root>/docs/product-analysis/<requirement-id>/`；新增产物写回同目录并继承 ID。显式 target 必须是上游 scope 的子集。
-
-任一选中后端故事的触发方式为 API 时生成 `api-documentation.md`；非 HTTP 触发不得生成空 API 文档。业务输入输出、权限、核心规则或安全边界缺失时阻断。
-
-门禁失败时 Dependency Analysis 只包含分析范围、输入与代码基线、阻断原因、恢复条件。`blocked_on` 使用 requirement-missing、requirement-invalid、requirement-not-complete、repository-missing、repository-unreadable、scope-mismatch、missing-stories、missing-acceptance、api-business-contract-incomplete。
+# Product Requirement 输入契约
+
+首选输入为 complete V3 `product-requirement.md`。迁移期允许读取 complete V2，但不修改上游产物；新产物始终使用 V3。
+
+V3 必须包含精简用户故事、同 ID 输出规范和嵌入规范的 AC。故事与规范一一对应，故事 AC 引用与规范内 AC 完全一致。V2 继续按其原有嵌入故事的 AC 读取。
+
+必须提供存在、可读的代码仓库。Product Requirement 位于 `<project-root>/docs/product-analysis/<requirement-id>/`；新增产物写回同目录并继承 ID。显式 target 必须是上游 scope 的子集。
+
+任一选中后端故事的触发方式为 API 时生成 `api-documentation.md`；非 HTTP 触发不得生成空 API 文档。业务输入输出、权限、核心规则或安全边界缺失时阻断。
+
+门禁失败时 Dependency Analysis 只包含分析范围、输入与代码基线、阻断原因、恢复条件。`blocked_on` 使用 requirement-missing、requirement-invalid、requirement-not-complete、repository-missing、repository-unreadable、scope-mismatch、missing-stories、missing-acceptance、api-business-contract-incomplete。