@tea-agent/loop-agent 0.13.0 → 0.15.0

package/skills/agent-worker/SKILL.md

@@ -1,39 +1,39 @@
----
-name: agent-worker
-description: Use when work involves agent-worker, Feature Packet, TaskSpec, Task Pool, Feature or batch orchestration, controller pinning, versioned self-hosting (自举) release trains, candidate takeover canaries (候选接棒验证), or worker failure recovery; use loop-agent instead for a single DAG implementation or DAG runtime/kernel repair.
-references:
-  - path: references/agent-worker-operator.md
-    required: true
----
-
-# Agent Worker Operator
-
-当工作起点是 Feature Packet、TaskSpec、Task Pool、Worker batch 或 versioned self-hosting release train 时使用本 skill。它负责在单次 loop-agent DAG run 之外选择并监督工作。
-
-## Route the Work
-
-- 用 `agent-worker` 做 Feature validation 与 lifecycle 决策、Ready-task 选择、batch 推进、controller identity freeze、candidate takeover canary，以及失败 Worker run 的恢复。
-- 对单个有界 DAG task、DAG diagnostics、node implementation，或 DAG runtime/kernel 修复，直接用 `loop-agent`。
-- 不要让 DAG leaf node 递归启动 `agent-worker`；Worker 是 outer loop，不是另一个 node executor。
-
-## Boundaries
-
-- `agent-worker` 读取 Feature Packet 与 Task Pool facts，选择任务，冻结 controller identity，启动 Feature/batch lifecycle 命令，并收集 evidence。
-- `loop-agent` 仍是 DAG executor，负责 Pi-only implementation nodes、write-set governance、skill snapshots 与 run facts。
-- Controller identity 冻结驱动 batch 的 published package；loop-agent skill snapshot 则单独冻结注入单次 DAG run 的 instructions。
-- 本 skill 不复制 command catalog。精确 flags 见 CLI help 与同级 `../loop-agent/references/command-reference.md`。
-- 不要把本 skill 加入默认 DAG role skills；仅对 outer-loop operator 工作显式路由。
-
-## Operator Flow
-
-1. 校验 Feature Packet 与 TaskSpecs，再从 Task Pool facts 选择 Ready 工作，而不是从 chat state。Task Pool 身份是 `{ featureId, taskId }`，不是裸 taskId。
-2. 在写入前解析并冻结目标 published controller；在 batch、task 与 run evidence 中保留 controller identity。
-3. 将仓库写入委托给受治理的 loop-agent DAG nodes，并审查其 task boundaries 与 write sets。
-4. 自举时保持 published version N 固定，由它维护 candidate N+1，再通过 deterministic isolated canary 证明 candidate takeover。
-5. 失败时先保留原始 run record、evidence 与 failure handoff，再重试或创建后续工作。
-6. Failed task 重试使用 `agent-worker task retry <task-id> --feature-id <feature-id> --repo <repo> --reason <reason>`；跨 Feature 同名时禁止省略 `--feature-id`。
-7. 升级或发现 legacy state 时先 `pool doctor`，再用 `pool migrate-state`（默认 dry-run；apply 需 `--owner` + `--reason`）。Observe 保持只读。
-
-## References
-
-- `references/agent-worker-operator.md`
+---
+name: agent-worker
+description: Use when work involves agent-worker, Feature Packet, TaskSpec, Task Pool, Feature or batch orchestration, controller pinning, versioned self-hosting (自举) release trains, candidate takeover canaries (候选接棒验证), or worker failure recovery; use loop-agent instead for a single DAG implementation or DAG runtime/kernel repair.
+references:
+  - path: references/agent-worker-operator.md
+    required: true
+---
+
+# Agent Worker Operator
+
+当工作起点是 Feature Packet、TaskSpec、Task Pool、Worker batch 或 versioned self-hosting release train 时使用本 skill。它负责在单次 loop-agent DAG run 之外选择并监督工作。
+
+## Route the Work
+
+- 用 `agent-worker` 做 Feature validation 与 lifecycle 决策、Ready-task 选择、batch 推进、controller identity freeze、candidate takeover canary，以及失败 Worker run 的恢复。
+- 对单个有界 DAG task、DAG diagnostics、node implementation，或 DAG runtime/kernel 修复，直接用 `loop-agent`。
+- 不要让 DAG leaf node 递归启动 `agent-worker`；Worker 是 outer loop，不是另一个 node executor。
+
+## Boundaries
+
+- `agent-worker` 读取 Feature Packet 与 Task Pool facts，选择任务，冻结 controller identity，启动 Feature/batch lifecycle 命令，并收集 evidence。
+- `loop-agent` 仍是 DAG executor，负责 Pi-only implementation nodes、write-set governance、skill snapshots 与 run facts。
+- Controller identity 冻结驱动 batch 的 published package；loop-agent skill snapshot 则单独冻结注入单次 DAG run 的 instructions。
+- 本 skill 不复制 command catalog。精确 flags 见 CLI help 与同级 `../loop-agent/references/command-reference.md`。
+- 不要把本 skill 加入默认 DAG role skills；仅对 outer-loop operator 工作显式路由。
+
+## Operator Flow
+
+1. 校验 Feature Packet 与 TaskSpecs，再从 Task Pool facts 选择 Ready 工作，而不是从 chat state。Task Pool 身份是 `{ featureId, taskId }`，不是裸 taskId。
+2. 在写入前解析并冻结目标 published controller；在 batch、task 与 run evidence 中保留 controller identity。
+3. 将仓库写入委托给受治理的 loop-agent DAG nodes，并审查其 task boundaries 与 write sets。
+4. 自举时保持 published version N 固定，由它维护 candidate N+1，再通过 deterministic isolated canary 证明 candidate takeover。
+5. 失败时先保留原始 run record、evidence 与 failure handoff，再重试或创建后续工作。
+6. Failed task 重试使用 `agent-worker task retry <task-id> --feature-id <feature-id> --repo <repo> --reason <reason>`；跨 Feature 同名时禁止省略 `--feature-id`。
+7. 升级或发现 legacy state 时先 `pool doctor`，再用 `pool migrate-state`（默认 dry-run；apply 需 `--owner` + `--reason`）。Observe 保持只读。
+
+## References
+
+- `references/agent-worker-operator.md`

package/skills/agent-worker/references/agent-worker-operator.md

@@ -1,60 +1,60 @@
-# Agent Worker Operator Reference
-
-`agent-worker` 是 Feature Packet、TaskSpec、Task Pool 与 self-hosting release-train 操作的 outer-loop adapter。它不是 DAG executor。
-
-## Routing Boundary
-
-当工作单元是 Feature lifecycle、一组 TaskSpecs、Ready queue、Worker batch 或 candidate takeover 时，选 `agent-worker`。当工作单元是单次受治理 DAG run、node implementation、DAG diagnosis 或 DAG runtime repair 时，选 `loop-agent`。
-
-Leaf DAG nodes 不得递归启动 `agent-worker`。Worker 负责 DAG 之外的 selection 与 lifecycle state；loop-agent 负责 DAG 内的 execution facts。
-
-## Responsibilities
-
-- 在选工前校验 Feature Packet 与 TaskSpec 关系。
-- 从 Task Pool facts 选择 Ready 工作，定义 batch scope，并选择 recovery actions。
-- 在可写执行前解析并冻结 controller launch identity。
-- 用 pinned controller identity 启动 loop-agent 命令。
-- 收集 canonical run records、reports、closeout drafts 与 failure handoff evidence。
-
-## Feature and Task Pool Flow
-
-1. 阅读 Feature Packet，校验其 TaskSpecs 与 dependency graph。
-2. 从持久化的 Task Pool state 推导下一步动作；不要从 chat history 重建 lifecycle state。canonical state 键是 `{ featureId, taskId }`（路径 `.harness/task-pool/states/<featureId>/<taskId>.json`）。
-3. 对可写 batch 只冻结一次 controller，并将其 identity 传播到下游 evidence。
-4. 将每个选中的 TaskSpec 委托给 loop-agent，使用其结构化的 allowed / forbidden paths。
-5. 根据 canonical run facts 刷新 Feature review、reports 与 Task Pool state。
-6. 重试 Failed task：
-
-   ```text
-   agent-worker task retry <task-id> --feature-id <feature-id> --repo <repo> --reason <reason>
-   ```
-
-   跨 Feature 同名 Task 时省略 `--feature-id` 必须 fail-closed。
-7. 诊断 / 迁移 legacy 扁平 state：
-
-   ```text
-   agent-worker pool doctor --repo <repo> --json
-   agent-worker pool migrate-state --repo <repo>                 # dry-run
-   agent-worker pool migrate-state --repo <repo> --apply --owner <owner> --reason <reason>
-   ```
-
-   doctor 只读；migrate 默认零写入，apply 失败全回滚且不改 JSONL。
-8. Observe（`observe serve|snapshot`）只读；canonical Task 路由为 `/api/features/:featureId/tasks/:taskId` 与 `#/feature/:featureId/task/:taskId`。
-
-## Versioned Self-Hosting
-
-- Published version N 是整个 maintenance batch 的 controller；不要在任务中途切换。
-- Candidate N+1 在 takeover verification 前先构建并安装到 isolated slot。
-- Candidate 命令使用绝对 package entry identities，绝不使用新解析的 global PATH 命令。
-- Controller identity 与 DAG skill snapshot 应对不同漂移风险：前者钉住 runtime/package content，后者钉住单次 run 的 resolved instructions。
-- 失败的 canary 或 Worker run 仍是不可变 evidence。将 retries 与后续工作链接到它，而不是覆盖失败记录。
-
-## Non Responsibilities
-
-- 不要在此实现 node scheduling、write-set enforcement 或 model prompts。
-- 不要在本 skill 中维护一份独立的精确 CLI flags 列表；以 CLI help 与 `../../loop-agent/references/command-reference.md` 为准。
-- 不要把本 skill 路由为 DAG nodes 的默认 role skill。
-
-## Candidate Canary Boundary
-
-Deterministic candidate canary 将 candidate package 安装到 isolated temporary slot，通过该 slot 内的绝对 Node script paths 调用 package bins，避免 model calls，并输出 machine-readable evidence，覆盖 package-root containment、entry hashes、checks 与 verdict。
+# Agent Worker Operator Reference
+
+`agent-worker` 是 Feature Packet、TaskSpec、Task Pool 与 self-hosting release-train 操作的 outer-loop adapter。它不是 DAG executor。
+
+## Routing Boundary
+
+当工作单元是 Feature lifecycle、一组 TaskSpecs、Ready queue、Worker batch 或 candidate takeover 时，选 `agent-worker`。当工作单元是单次受治理 DAG run、node implementation、DAG diagnosis 或 DAG runtime repair 时，选 `loop-agent`。
+
+Leaf DAG nodes 不得递归启动 `agent-worker`。Worker 负责 DAG 之外的 selection 与 lifecycle state；loop-agent 负责 DAG 内的 execution facts。
+
+## Responsibilities
+
+- 在选工前校验 Feature Packet 与 TaskSpec 关系。
+- 从 Task Pool facts 选择 Ready 工作，定义 batch scope，并选择 recovery actions。
+- 在可写执行前解析并冻结 controller launch identity。
+- 用 pinned controller identity 启动 loop-agent 命令。
+- 收集 canonical run records、reports、closeout drafts 与 failure handoff evidence。
+
+## Feature and Task Pool Flow
+
+1. 阅读 Feature Packet，校验其 TaskSpecs 与 dependency graph。
+2. 从持久化的 Task Pool state 推导下一步动作；不要从 chat history 重建 lifecycle state。canonical state 键是 `{ featureId, taskId }`（路径 `.harness/task-pool/states/<featureId>/<taskId>.json`）。
+3. 对可写 batch 只冻结一次 controller，并将其 identity 传播到下游 evidence。
+4. 将每个选中的 TaskSpec 委托给 loop-agent，使用其结构化的 allowed / forbidden paths。
+5. 根据 canonical run facts 刷新 Feature review、reports 与 Task Pool state。
+6. 重试 Failed task：
+
+   ```text
+   agent-worker task retry <task-id> --feature-id <feature-id> --repo <repo> --reason <reason>
+   ```
+
+   跨 Feature 同名 Task 时省略 `--feature-id` 必须 fail-closed。
+7. 诊断 / 迁移 legacy 扁平 state：
+
+   ```text
+   agent-worker pool doctor --repo <repo> --json
+   agent-worker pool migrate-state --repo <repo>                 # dry-run
+   agent-worker pool migrate-state --repo <repo> --apply --owner <owner> --reason <reason>
+   ```
+
+   doctor 只读；migrate 默认零写入，apply 失败全回滚且不改 JSONL。
+8. Observe（`observe serve|snapshot`）只读；canonical Task 路由为 `/api/features/:featureId/tasks/:taskId` 与 `#/feature/:featureId/task/:taskId`。
+
+## Versioned Self-Hosting
+
+- Published version N 是整个 maintenance batch 的 controller；不要在任务中途切换。
+- Candidate N+1 在 takeover verification 前先构建并安装到 isolated slot。
+- Candidate 命令使用绝对 package entry identities，绝不使用新解析的 global PATH 命令。
+- Controller identity 与 DAG skill snapshot 应对不同漂移风险：前者钉住 runtime/package content，后者钉住单次 run 的 resolved instructions。
+- 失败的 canary 或 Worker run 仍是不可变 evidence。将 retries 与后续工作链接到它，而不是覆盖失败记录。
+
+## Non Responsibilities
+
+- 不要在此实现 node scheduling、write-set enforcement 或 model prompts。
+- 不要在本 skill 中维护一份独立的精确 CLI flags 列表；以 CLI help 与 `../../loop-agent/references/command-reference.md` 为准。
+- 不要把本 skill 路由为 DAG nodes 的默认 role skill。
+
+## Candidate Canary Boundary
+
+Deterministic candidate canary 将 candidate package 安装到 isolated temporary slot，通过该 slot 内的绝对 Node script paths 调用 package bins，避免 model calls，并输出 machine-readable evidence，覆盖 package-root containment、entry hashes、checks 与 verdict。

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 契约。