@tea-agent/loop-agent 0.1.0-fe-test.0

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

@@ -0,0 +1,159 @@
+# Agent Worker Operator Reference
+
+`agent-worker` 是 Feature Packet、TaskSpec、Task Pool 与 self-hosting release-train 操作的 outer-loop adapter。它不是 DAG executor。
+
+## Compatibility / Operator Assist
+
+主会话使用本 reference 时是 **operator**，不是 implementer：
+
+| 允许 | 禁止 |
+| --- | --- |
+| `agent-worker` / `loop-agent` CLI | 宿主 Edit/Write 直接改业务实现 |
+| 只读 doctor / observe / report / status | Worker 或 DAG 失败后「救火改文件」 |
+| 冻结 controller identity、选 Ready、retry/reconcile | 跳过 published controller 手写实现收尾 |
+| human gate 记录 | 用聊天完成声明代替 shell / harness 证据 |
+
+实现写入只通过 Worker spawn 的已发布 `loop-agent` DAG。skills 不能替代 writeSet 或 controller identity。
+
+## Routing Boundary
+
+当工作单元是 Feature lifecycle、一组 TaskSpecs、Ready queue、Worker batch 或 candidate takeover 时，选 `agent-worker`。当工作单元是单次受治理 DAG run、node implementation、DAG diagnosis 或 DAG runtime repair 时，选 `loop-agent` CLI。
+
+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
+
+0. **新建 Packet（确定性脚手架，无模型）** — 包内自洽说明见下节 *Feature Packet Scaffold*；不依赖 website 文档站。
+
+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 **经 CLI** 委托给 loop-agent，使用其结构化的 allowed / forbidden paths；主会话不代替 writer。
+5. 根据 canonical run facts 刷新 Feature review、reports 与 Task Pool state。
+6. 重试 Failed task（CLI only；禁止主会话手改实现）：
+
+   ```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. Inspect（原 Observe）只读：仅推荐 `agent-worker console` 的 `/inspect/#/...`；`observe snapshot` 仍可用。`observe serve` 已下线（REMOVED / exit 2）。canonical Task 路由为 `/api/features/:featureId/tasks/:taskId` 与 `#/feature/:featureId/task/:taskId`。8790 `/api/health` 为 `OperatorSurfaceHealthV1`。
+9. Official Console：`agent-worker console|doctor`（默认 loopback；可 `--host 0.0.0.0` / `--debug` / `--no-open`）。Recovery CTA 为 report/doctor/decision/resume/reconcile/regenerate/打开检视；无 Cancel、无主 CTA「直接改代码」。主会话 Compatibility Assist 不得替代 Console/CLI 执法。
+
+## Feature Packet Scaffold
+
+确定性入口：一个纯 BE/FE 需求 → 一个 `features/F-YYYY-NNN/` Packet → Task Pool 串行掘进。主会话只跑 CLI，不手写 TaskGraph。
+
+### 边界（v1）
+
+| 做 | 不做 |
+| --- | --- |
+| 模板 + 槽位确定性生成 | 一键 LLM 生成完整合同 |
+| `profile: generic` 短图 | 默认 `fullstack-v1` / 复制 `F-2026-005` 全图 |
+| 显式 `--verify-command` | 猜测项目测试命令 |
+| 一需求一 Feature 目录 | 跨 Feature 自动 depends / 并行 Pool |
+| 写盘前同源 `task validate-feature` | 读/写 `.harness/**` 或构造 `LoopAgentClient` |
+
+### 三模板
+
+| 模板 | 最小图 |
+| --- | --- |
+| `backend-only` | `BE-IMPL-001`（需 ≥1 `--be-path`） |
+| `frontend-only` | `FE-IMPL-001`（需 ≥1 `--fe-path`） |
+| `fe-with-api` | `CONTRACT-001` → `BE-IMPL-001` + `FE-IMPL-001`（consumers 仅实现节点；两端 path 都要） |
+
+v1 **不**生成 `BE-TEST` / `FE-TEST` / `FINAL-VERIFY`。`feature_id` 强制 `F-YYYY-NNN`（≥3 位序号）。输出固定 `<repo>/features/<feature-id>`；无 `--force` / `--out`；已存在目录（含空目录）一律拒绝。
+
+### 日常命令
+
+```text
+# 可选 dry-run：完整 parse/render/validate，零写入
+agent-worker feature scaffold --repo <repo> --template backend-only \
+  --feature-id F-2026-010 --title "..." \
+  --be-path services/example/** \
+  --verify-command "npm run typecheck" --verify-command "npm test" \
+  --dry-run --json
+
+agent-worker feature scaffold --repo <repo> --template frontend-only \
+  --feature-id F-2026-011 --title "..." \
+  --fe-path apps/web/src/settings/** \
+  --verify-command "npm test" --json
+
+agent-worker feature scaffold --repo <repo> --template fe-with-api \
+  --feature-id F-2026-012 --title "..." \
+  --be-path services/api/** --fe-path apps/web/src/api/** \
+  [--contract-path docs/contracts/F-2026-012/api.md] \
+  --verify-command "npm test" --json
+
+# 机器门禁 → 只读决策 → 串行掘进（固定 published controller）
+agent-worker task validate-feature features/F-2026-010
+agent-worker feature review --feature-dir features/F-2026-010 --repo <repo> --json
+agent-worker feature run --feature-dir features/F-2026-010 --repo <repo> \
+  --loop-agent-bin <published> \
+  --expected-controller-version <version> \
+  --expected-controller-fingerprint sha256:<hex> \
+  --git-mode checkpoint --limit 1 --json
+
+# Failed 只走官方恢复
+agent-worker task retry <taskId> --feature-id F-2026-010 --repo <repo> --reason "..."
+```
+
+### Batch
+
+```text
+agent-worker feature scaffold --repo <repo> --batch <yaml-or-json> [--dry-run] [--json]
+```
+
+- 与单条 flags 互斥；每条必须显式 `feature_id` / `title` / `template` / `verify_commands`。
+- 任一非法、冲突、目标已存在或写盘失败 → **整批零写入**（已提交目录回滚）。
+- 示例形状（包内模板若存在）：`docs/templates/product-line/feature-scaffold-batch.example.yaml`。
+- 三模板生成快照（只读、防漂移，非 live Feature）：`docs/templates/product-line/scaffold-samples/{backend-only,frontend-only,fe-with-api}/`。
+
+### 多需求策略
+
+1. 一个需求条目 → 一个 Feature 目录。
+2. 多个 FE/BE 需求：batch scaffold 后 **串行** `feature run --limit 1`（先完 F-010 再 F-011）。
+3. 后端可独立交付时：先 `backend-only`，再 `frontend-only`（跨 Feature 依赖只写文档，不做自动 depends_on）。
+4. 同 Feature 内 BE+FE 原子交付用 `fe-with-api`。
+
+### 内容与完成定义
+
+- scaffold 只给骨架；`requirement.md` / AC 文案由人或后续「只填槽、不改 graph」skill 填充。
+- v1 完成 = Packet 可 scaffold 且 Pool 可掘进到图内 Task **Done**；`verify-final` / Delivery / Closeout 为 v1.5（ADR 0007），非 scaffold 必经。
+- 已知恢复限制：mid-run `SIGKILL` 可能导致 Pool `Running` 且 `runs.jsonl` 缺失时 reconcile 失败（FC-B）；勿对 worker 随意 SIGKILL；Failed 后用 `task retry`。
+
+## 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。
+- 不要把主会话定位成 Worker/DAG 失败后的实现后备通道。
+
+## 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

@@ -0,0 +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。

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

@@ -0,0 +1,108 @@
+---
+name: analyze-product-dependencies
+description: 面向采用 Product Requirement V4、Web/Remote 接口分类和统一 HTTP 200 响应包络的组织内部项目，先根据选中需求故事强制检索项目知识库，再探索代码库，按 frontend、backend 或 both 范围将故事、验收标准及 API 型后端故事映射到真实文件、路由、组件、服务、数据、权限与证据；API 场景从同一规范中间模型生成纯 HTTP 契约文档，或用 api-only 模式单独更新 API 文档。用于代码影响分析、依赖分析、API 文档或需求到代码映射；也适用于“这个需求要改哪些文件”“帮我生成接口文档”“需求对应到哪段代码”“评估下这个需求的开发影响”这类请求。
+---
+
+# Analyze Product Dependencies
+
+IRON LAW：`product-requirement.md` 是唯一需求事实源。不得从原始需求、Product Analysis、Clarification 或聊天重新解释需求，不得修改代码或上游产物。
+
+## 运行环境与外部能力
+
+- 必需：可读写当前项目文件，并能运行 Node.js `.mjs` 校验器。
+- 前置第三方 skill：`kb-design-assist`，用于根据选中需求故事检索项目知识库中的设计系统、业务规范、API 规范和其他项目约定。
+- 可选能力：隔离的只读代码侦察 agent。
+- 缺少隔离代码侦察 agent 时执行对应 fallback；`kb-design-assist` 为 `unavailable` 时必须先让用户选择“修复后重试”或“跳过知识库”，不得直接 fallback，也不得伪造知识库结果、代码证据或 agent 结果。
+- 调用第三方 skill 时使用当前宿主提供的原生 skill 加载机制，不假定具体命令或工具名称。
+
+## 输入与产物
+
+- 必填：complete `product-requirement.md` 的实际路径和可读取代码仓库路径。Product Requirement 必须位于 `<project-root>/docs/product-analysis/<requirement-id>/`。
+- 可选：`target=frontend|backend|both` 或 `--target frontend|backend|both`；两种写法等价，默认继承上游 scope。
+- 可选：`mode=full|api-only` 或 `--mode full|api-only`；两种写法等价，默认 `full`。`full` 生成依赖分析并按需生成 API 文档；`api-only` 只生成 `api-documentation.md`，不创建或修改 `dependency-analysis.md`。
+- 可选：frontend/both 可传 `api_documentation=<任意可读 Markdown API 文档路径>` 或 `--api-doc <path>`。外部文档只读，前端产物只记录实际引用的 Method+Path。
+- 输出写回 Product Requirement 所在目录。`api-only` 仅适用于 `backend|both` 且至少一个选中后端故事以 API 触发。用户显式要求刷新依赖/API 产物时，视为授权原子更新本 skill 在本次运行创建的文件；覆盖既有 complete 产物、非本 skill 创建的文件或来源无法确认的文件前先确认。
+
+## Workflow
+
+- [ ] Step 0：输入门禁 ⛔ BLOCKING
+  - [ ] 将 `target=<value>` 和 `--target <value>` 归一化为唯一 target；缺省时继承上游 scope，非法值或冲突的多个值必须停止。显式 target 必须是上游 `analysis_scope` 的子集，只分析选中故事，不改写上游产物。
+  - [ ] 将 `mode=<value>` 和 `--mode <value>` 归一化为唯一 mode；缺省时为 `full`，非法值或冲突值必须停止。`api-only + frontend` 或没有 API 型后端故事时必须停止，不得生成空 API 文档。
+  - [ ] 读取 `references/input-contract.md`，向输入校验器传入已归一化 target。输入必须是上游交付的 complete 产物（不得依赖 `--allow-pending`）；V2 + API 触发故事必须先升级为 V4。
+  - [ ] 从 Product Requirement 继承 `requirement_id` 和输出目录；项目根由固定目录结构推导。`requirement-missing` 且无法从用户显式 `requirement_id`/输出路径恢复时：`full` 不写产物，只在会话报告；能恢复 ID 时才写 blocked Dependency。
+  - [ ] 在代码侦察前明确回显“分析范围：frontend | backend | both”；新增产物的 `analysis_scope` 必须等于该归一化 target，后续不得自动扩大范围。
+  - [ ] `full` 门禁失败且可确定输出位置时只生成 blocked Dependency Analysis，不伪造 API 或代码落点；`api-only` 门禁失败时不写任何产物，只报告阻断原因和恢复条件。
+- [ ] Step 1：完整代码侦察 ⚠️ REQUIRED
+  - [ ] 从选中故事、同 ID 输出规范和 AC 提取业务词、领域对象、状态/边界、权限、接口形态与技术约定，形成仅覆盖当前分析范围的知识库检索计划；不得先探索代码库再反推检索词。
+  - [ ] 首先读取 `references/kb-integration.md` 和 `references/scouting-rules.md`，并按前者的状态机、用户确认门禁和降级边界真实调用 `kb-design-assist`。每次分析都必须执行，不得因故事简单或未显式提到项目规范而跳过。
+  - [ ] 知识库状态为 `executed-hit` 或 `executed-no-match`，或 `unavailable` 后用户明确确认跳过，才允许预扫描项目资料并探索代码库；其余情况保持阻断。
+  - [ ] 知识库门禁通过后、常规代码侦察前，依次预扫描 `<project-root>/ai_workspace/project-how-to`、`code-specification`、`project-business`：先枚举文件，再读取入口文档及与选中故事直接相关的内容；缺失目录记录 `not-found` 并继续。
+  - [ ] 按 scouting rules 的只读代码侦察 agent 委派、confirmed/inferred/unknown 分级、双证据要求与前后端必查项执行；当前宿主不支持隔离 agent 时由当前 agent 执行同等范围的定向搜索。当前会话只保留精简规范证据、代码证据、冲突和未定位项。知识库证据不得替代真实代码落点。
+  - [ ] `full` 逐个读取选中故事及其同 ID 输出规范和 AC，再定位入口、调用链、状态、类型、数据、权限、错误、日志和测试；`frontend` 不分析 `BE-US-*`，`backend` 不分析 `FE-US-*`。`api-only` 只侦察生成 HTTP 契约所需的路由惯例、共享 DTO/Schema、统一响应/错误、分页、时间与标识符规范，不做影响文件清单和非 API 依赖分析。
+  - [ ] unknown 不在本 skill 内发起产品澄清：目标行为已明确但代码落点/复用点未知时记入对应故事风险或跨故事未定位项；缺失 API 业务语义、权限、核心规则、安全边界或验收所需产品决策时阻断并返回上游需求 skill，不得自行补齐。
+- [ ] Step 2：判断 API 适用性 ⚠️ REQUIRED
+  - [ ] 只要一个选中的 `BE-US-*` 触发方式为 `API（Web）`、`API（Remote）` 或 `API（Web + Remote）`，就必须生成 API 文档。Web 与 Remote 使用同一 HTTP 契约；Web + Remote 必须建模为两个独立接口，路径以知识库、项目资料与仓库规范为准。
+  - [ ] 笼统的 `触发方式：API` 视为接口范围未确认，阻断并返回上游需求 skill。
+  - [ ] target 为 `frontend` 时不读取或分析后端故事，也不新生成 API 文档；Dependency 仍保留 API 实现映射章节。传入外部 API 文档时，只登记被选中前端故事实际依赖且可在文档中核验的 Method+Path，不记录 API ID、Operation ID、文档路径或完整契约；外部文档中的无关接口不参与孤立检查。未传入或未定位时写带原因的不适用。
+  - [ ] 定时任务、事件、消息、数据迁移或纯内部调用且不形成 HTTP 契约时，不生成空 API 文档。
+  - [ ] 无 API 时 API 实现映射明确写不适用。
+- [ ] Step 3：建立规范 API 中间模型（仅 API 场景）⚠️ REQUIRED when applicable
+  - [ ] 仅当选中范围内存在 API 型后端故事，或 `mode=api-only` 时执行本步；`frontend`、非 API 场景或已判定不适用时跳过，不建立中间模型。
+  - [ ] 读取 `references/api-documentation-schema.md`，按契约建模与渲染。
+  - [ ] 用同一次代码侦察建立不落盘的规范中间模型（最小字段：API ID、Operation ID、Method+Path、变更类型、请求/响应字段、错误码、分页是否适用）；`full` 的 API Documentation 与 Dependency Analysis 的 API 映射均从该模型渲染；`api-only` 只渲染 API Documentation。
+  - [ ] 所有成功与失败响应的 HTTP 状态码统一为 `200`，只通过响应体顶层 `code` 区分结果；成功与失败 `code` 必须不同。定义字段/错误码前，先通过 `kb-design-assist` 检索当前有效的 DTO/Response、统一响应和错误码规范，再核验仓库共享 DTO、响应类型和全局错误枚举；命中则复用，不在 API 文档输出搜索过程、知识库证据或“复用检查”。
+  - [ ] 分页允许值以 Product Requirement 为准；上游确实未说明时按“有效知识库分页规范 > 仓库通用分页定义 > 默认集合 `10`、`20`、`50`、`100`”补齐。参数必填性与默认值沿用 Product Requirement；PR 未规定时优先采用有效知识库规范并由仓库定义核验。
+  - [ ] 产品需求优先于现状；业务语义缺失时阻断，不由本 skill 发明产品决策。
+  - [ ] API 文档只保留 HTTP 契约；不得包含故事/AC 追溯、认证、权限、业务规则与实现逻辑。只有实际分页时才生成“分页约定”。
+- [ ] Step 4：生成产物 ⚠️ REQUIRED
+  - [ ] `full` 读取 `references/dependency-analysis-schema.md`；`api-only` 不读取或生成 Dependency Analysis。
+  - [ ] `full` 的 API 场景先写 `api-documentation.md`，再写 `dependency-analysis.md`；`api-only` 只写 `api-documentation.md`，不得创建、覆盖或追加 `dependency-analysis.md`。
+  - [ ] 按 target 生成对应故事覆盖与依赖详情；三种范围都保留 API 实现映射章节。
+  - [ ] `影响文件` 是每个故事独立完整的权威清单（故事内 `F1`/`F2` + `add|modify|reuse` 或中文同义 `新增|修改|复用`）；不得建立全局文件索引。
+  - [ ] 前端详情必须覆盖 Product Requirement 的目标页面路由。传入外部 API 文档且依赖 HTTP 时只写 Method+Path；否则按 schema 写“`不适用；…`”模板。
+  - [ ] 故事局部风险与文末跨故事风险不得重复；API 实现映射只保留 API ID、Operation ID、方法路径和代码入口（现有路径或拟新增路径，禁止「未定位」占位）。
+  - [ ] 所有新增产物与 Product Requirement 使用相同 `requirement_id`；V4 frontmatter 不记录可由目录或运行参数推导的来源路径。
+- [ ] Step 5：验证并交付 ⛔ BLOCKING
+  - [ ] Product Requirement 输入校验必须通过。
+  - [ ] 向所有适用校验器传入归一化 target。`full` 的 API 场景运行输入、API 和 Dependency 三个校验器；非 API 场景运行输入和 Dependency；`api-only` 只运行输入和 API。
+  - [ ] 当前产物校验通过即可交付。`test-validators.mjs` 仅在修改输出契约、schema、validator、artifact version、示例、forward-test contract，或发布/安装/回归验证时运行。
+
+完整示例按需读取 `references/example.md`；维护或 forward-test 时读取 `references/forward-test-cases.md`。不要为了执行校验而阅读脚本，直接运行。
+
+## Anti-Patterns
+
+- 从聊天、Product Analysis 或 Clarification 重新解释需求。
+- 修改代码或上游 `product-requirement.md`。
+- 消费带 `--allow-pending` 的未交付产物，或对 V2 + API 故事直接生成 API 文档。
+- 在 API 文档写入故事/AC、认证、权限、业务规则或“复用检查”。
+- 在 API 文档写入 `kb-design-assist` 调用过程、`KB-EVIDENCE-*`、知识库路径、命中日志或规范复用证据。
+- Product Requirement 已给出分页允许值时，用知识库规范、默认 `10/20/50/100` 或仓库惯例覆盖。
+- 建立全局文件索引，或把完整 API 契约/JSON 示例复制进 Dependency Analysis。
+- `api-only` 模式下创建或修改 `dependency-analysis.md`。
+- 自行补齐缺失的产品决策而不返回上游需求 skill。
+- `kb-design-assist` 为 `unavailable` 时，未让用户选择修复或跳过就继续代码库降级或生成 complete 产物。
+- 跳过需求驱动的知识库检索、先探索代码库，或用“故事不涉及项目规范”记录未执行状态。
+
+## 交付前自检
+
+声明完成前逐项确认，任一不满足不得交付：
+
+- [ ] 新增 V4 产物与 Product Requirement 同目录、同 `requirement_id`，且 frontmatter 不含可推导的来源、项目根或仓库路径。
+- [ ] 所有产物 `analysis_scope` 等于归一化 target，未自动扩大范围。
+- [ ] 按场景运行对应校验器：`full` API 场景跑「输入 + API + Dependency」，`full` 非 API 场景跑「输入 + Dependency」，`api-only` 只跑「输入 + API」。
+- [ ] 所有适用校验命令返回 exit 0；任一非 0 都不算完成。
+
+## Validation
+
+把 `<skill-root>` 解析为本 `SKILL.md` 所在目录，全部参数使用绝对路径：
+
+```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] [--api-doc <external-api.md>] --target <frontend|backend|both>
+```
+
+`api-only` 只运行前两条适用命令；不得调用 Dependency 校验器。
+非 API 场景省略 API 校验器和 Dependency 校验命令的第三个参数。
+缺少 Product Requirement 的 blocked 场景使用 `none` 作为 Dependency 校验命令的第一个参数。
+维护或发布时额外运行 `node <skill-root>/scripts/test-validators.mjs`。

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

@@ -0,0 +1,35 @@
+# Swagger 风格 Markdown API 文档 V4 契约
+
+文件名固定为 `api-documentation.md`。它采用 Swagger 的信息组织方式，但不是 OpenAPI YAML。
+
+```yaml
+---
+artifact_version: "4.0"
+artifact_type: api-documentation
+requirement_id: <与 Product Requirement 一致>
+api_status: complete
+analysis_scope: backend | both
+---
+```
+
+Frontmatter 只允许以上五个字段，不得增加来源、项目根、仓库路径或其他运行时字段。
+
+固定章节：通用约定、API 索引、API 详情、数据模型、错误码。API Documentation 是完整 HTTP 契约事实源，但不承担故事或 AC 追溯。不得包含 `BE-US-*`、`AC-BE-*`、用户故事列、AC 列、认证方式、权限要求、业务规则、业务逻辑、处理逻辑和实现逻辑。
+
+职责边界：产品权限与业务规则留在 Product Requirement；HTTP 契约留在本文件；代码落点与权限实现映射留在 Dependency Analysis。三份产物不得互相复制对方职责内容。
+
+通用约定固定包含 Base URL、成功响应结构、公共错误响应结构、时间和标识符规范；公共错误响应结构必须包含合法 JSON 示例，且示例包含顶层 `code`。所有成功与失败响应的 HTTP 状态码统一为 `200`，客户端只根据响应体顶层 `code` 判断结果，不得使用 `4xx/5xx` 表达业务失败。只有至少一个接口实际分页时才包含分页约定。非分页文档不得生成空分页章节或“不分页”占位。不输出 `kb-design-assist` 调用过程、`KB-EVIDENCE-*`、知识库/代码搜索过程、命中证据或“复用检查”章节。
+
+每个接口标题使用 `### API-001 名称`，随后写 Swagger 风格方法路径。固定子章节：基本信息、成功响应、错误响应。非认证请求头、Path 参数、Query 参数、Request Body 按适用性生成；URL 有模板参数时必须生成 Path 参数。字段层面只写名称、类型、必填/可空、格式、枚举、契约约束和语义，不写计算、转换、查询或分支逻辑。
+
+基本信息只包含 Operation ID、变更类型和幂等性，不重复 API ID。API 索引只包含 API ID、Method + Path、Operation ID、变更类型。索引与 API 详情必须严格双向一一对应：不得有缺失索引的详情、缺失详情的索引行、重复 API ID 或重复 Operation ID；同一 API 的 Method+Path、Operation ID 和变更类型必须完全一致。
+
+成功响应明确写 `HTTP：200` 并包含合法 JSON 示例；错误响应至少列出一个 HTTP `200` 的错误 code 和合法 JSON 示例。成功与错误 JSON 均包含顶层 `code`，且成功 code 与错误 code 必须不同；错误示例的 `code` 必须出现在错误响应表中。变更类型使用新增、修改、复用。
+
+分页接口在 Query 参数中定义每页条数参数（`pageSize` / `page_size` / `limit`）。仅 cursor、或 Query 字段名碰巧含 `page` 但无条数参数的接口，不算本契约要求的分页接口，不得据此强制生成分页约定或 page-size 行。允许值以 Product Requirement 为准：上游已给出集合时原样列出；上游确实未说明时依次使用当前有效知识库分页规范、仓库通用分页定义和默认集合 `10 | 20 | 50 | 100`。参数名和必填性优先复用 Product Requirement；PR 未规定时先采用有效知识库规范并由仓库现有约定核验。本 skill 不强制该参数为可选。只有 Product Requirement、有效知识库规范或仓库通用分页定义明确时才写默认值，不再生成 `<100`、`=100`、`>100` 分页场景。Validator 必须核对：存在 `pageSize`、`page_size` 或 `limit` Query 参数时恰好有一个“分页约定”，参数行包含数值允许集合且与分页约定一致；Product Requirement 明确允许集合时还必须与其一致；不存在这些参数时禁止“分页约定”。参数来源优先级和默认值来源继续由生成流程与 forward-test 核对。
+
+无对应内容时省略空的 Header、Path、Query 或 Request Body 子章节。Schema 字段只在“数据模型”完整定义一次，接口详情引用 Schema。“数据模型”只定义实际使用的 Schema 和字段；“错误码”只说明 code 和可观测的触发条件，HTTP 状态统一为 `200`。字段、Response、错误码、时间与标识符等技术约定在 Product Requirement 未规定时，优先采用 `kb-design-assist` 返回的当前有效规范，再核验仓库共享定义。两个章节均不新增“复用检查”，不输出知识库或代码搜索过程，不展开业务判定或实现逻辑。
+
+`mode=api-only` 与 `mode=full` 使用完全相同的 API 契约和校验规则。`api-only` 只生成本文件，不创建、覆盖或追加 `dependency-analysis.md`。
+
+`API（Web）` 与 `API（Remote）` 使用同一契约。`API（Web + Remote）` 必须为两条实际接口分别建模，例如项目规范确定的 `GET /order/list` 与 `GET /remote/order/list`；不得把 `/remote` 当作固定前缀，Method+Path 必须来自有效规范或仓库惯例。

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

@@ -0,0 +1,38 @@
+# Dependency Analysis V4 输出契约
+
+```yaml
+---
+artifact_version: "4.0"
+artifact_type: dependency-analysis
+requirement_id: <与 Product Requirement 一致>
+analysis_scope: frontend | backend | both
+analysis_status: complete | blocked
+blocked_on: none | <原因列表>
+---
+```
+
+Frontmatter 只允许以上六个字段，不得增加来源、项目根、仓库路径或其他运行时字段。
+
+Complete 固定章节：输入与代码基线、用户故事覆盖矩阵、按 scope 的依赖详情、API 实现映射、跨故事共享依赖、跨故事风险与未定位项。覆盖矩阵承担全局追溯，不生成独立分析范围、全局文件索引或追溯汇总。“输入与代码基线”记录知识检索状态 `executed-hit | executed-no-match | unavailable`；每次分析都必须真实执行知识检索，不允许未执行状态。若 complete 产物最终仍记录 `unavailable`，必须同时记录 `- 用户处置：已确认跳过知识库`；命中有效规范时可列必要的 `KB-EVIDENCE-*` 摘要。
+
+前端详情字段：验收标准、API 文档引用、影响文件、页面/路由、组件、状态、API client/类型、状态与边界落点、定位证据、风险、置信度。
+
+后端详情字段：验收标准、API 文档引用、影响文件、路由/入口、Controller/Handler、Service/领域逻辑、DTO/Schema、数据依赖、权限依赖、错误/日志/审计、测试落点、定位证据、风险、置信度。
+
+职责边界：Product Requirement 承载产品权限/业务规则；API Documentation 只承载 HTTP 契约；本文件把权限与规则映射到代码落点（如“权限依赖”），不复制完整 API 参数表、响应 JSON 或 Given/When/Then 正文。
+
+`影响文件` 是当前故事独立完整的权威清单，每项使用故事内唯一 `F<number>`、动作词（`add|modify|reuse` 或中文同义 `新增|修改|复用`）、真实路径或「未定位」、以及用途；其他代码落点字段引用当前故事编号，不重复完整路径。同一文件可在不同故事中重复出现。
+
+每个选中故事必须恰好存在一份同 ID 依赖详情；缺失、重复或出现未选中故事都必须失败。
+
+覆盖矩阵维护 `FE/BE-US → AC` 和适用的 API 引用。后端故事的“API 文档引用”列出 API ID。前端故事传入外部 API 文档时只列实际依赖的 `Method + Path`，不记录 API ID、Operation ID、文档路径或完整契约；外部文档可包含无关接口。无 HTTP 依赖的前端故事写“`不适用；本故事无 HTTP API 依赖`”，非 API 后端故事写“`不适用；触发方式为 <实际类型>`”。
+
+前端“页面/路由”必须登记 Product Requirement 的目标路由及实际代码落点，不得改变目标 URL；上游写“不适用”时不得虚构独立路由。
+
+后端 API 实现映射登记 API ID、Operation ID、Method+Path 和代码入口（具体现有路径或拟新增路径；禁止「未定位」占位）。前端使用外部 API 文档时，映射只登记被引用的 Method+Path。生成的 `api-documentation.md` 中每个 API 必须有代码入口、至少被一个 API-backed 后端故事引用且不得孤立；外部前端 API 文档不执行整份文档孤立检查。无 API 时写：`不适用。本次需求不涉及 HTTP API。`
+
+故事局部风险保留在对应故事详情；文末“跨故事风险与未定位项”只记录跨故事、跨前后端或无法归属单故事的风险，同一风险不得重复。状态、空数据、loading、error、disabled、错误文案和恢复入口必须引用项目真实枚举、组件或规范证据；未定位时写入适当风险位置，不得用通用状态名补齐。知识库证据只证明目标规范，代码证据才可证明真实文件、符号和调用关系；二者不一致时必须登记规范迁移/合规风险。知识库文档不得列为“影响文件”。`api-only` 模式不生成本产物。
+
+不得复制 AC 的 Given/When/Then 正文或完整 API 参数、响应、Schema、JSON 示例。
+
+Blocked 产物只含分析范围、输入与代码基线、阻断原因、恢复条件，不得包含确定性代码位置或 API 契约。

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

@@ -0,0 +1,76 @@
+# V4 输出示例
+
+## API 索引与详情
+
+````md
+## 2. API 索引
+| API ID | Method + Path | Operation ID | 变更类型 |
+|---|---|---|---|
+| API-001 | GET /api/v1/orders/{orderId}/refund-status | getRefundStatus | 新增 |
+
+## 3. API 详情
+### API-001 查询退款状态
+> `GET /api/v1/orders/{orderId}/refund-status`
+
+#### 基本信息
+| 字段 | 值 |
+|---|---|
+| Operation ID | getRefundStatus |
+| 变更类型 | 新增 |
+| 幂等性 | 只读请求天然幂等 |
+
+#### Path 参数
+| 参数 | 类型 | 必填 | 语义 |
+|---|---|---|---|
+| orderId | string | 是 | 订单标识 |
+
+#### 成功响应
+- HTTP：200
+```json
+{"code":"SUCCESS","data":{"refundStatus":"processing"}}
+```
+
+#### 错误响应
+| 状态码 | 错误码 | 条件 |
+|---|---|---|
+| 200 | FORBIDDEN | 资源访问被拒绝 |
+```json
+{"code":"FORBIDDEN","message":"forbidden"}
+```
+
+````
+
+无 Path、Query、Body 或专属 Header 时省略对应章节。
+
+本示例沿用项目约定，将每页条数定义为可选；实际必填性以 Product Requirement 或仓库 API 规范为准：
+
+```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 | `src/refund/refund.controller.ts#getRefundStatus` |
+```
+
+`影响文件` 是当前故事的完整路径清单；其余字段使用该故事内的 F 编号引用。API 文档不包含故事或 AC；追溯统一由 Dependency Analysis 维护。非 API 后端故事不生成 API 文档，并在“API 文档引用”中写明触发方式。

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

@@ -0,0 +1,110 @@
+# Forward-Test Cases
+
+在独立 agent 中逐个执行，只提供原始请求与输入产物，不泄露预期正文。
+
+## Case 1：frontend 路由与非 API 引用
+
+使用 complete、scope 为 frontend 的 Product Requirement，其中页面路由为 `/account/orders`，故事无 HTTP 依赖。核对：只生成 Dependency Analysis；详情保留目标 URL；“API 文档引用”写“`不适用；本故事无 HTTP API 依赖`”；API 实现映射明确不适用；不生成空 API 文档。
+
+## Case 2：无独立路由组件
+
+Product Requirement 页面路由写“`不适用；嵌入 /account/orders 页面`”。核对：Dependency 不虚构独立 URL，定位所属页面与组件落点。
+
+## Case 3：backend API
+
+使用 complete backend Product Requirement，`BE-US-001` 触发方式为 `API（Web）`。核对：API Documentation 和 Dependency Analysis 来自同一次侦察及同一规范中间模型；API 文档索引只有 API ID、Method + Path、Operation ID、变更类型，不含 `BE-US-*`、`AC-BE-*`、故事列或 AC 列；Dependency 覆盖矩阵关联故事、AC 与 API。
+
+## Case 4：非分页 API
+
+使用非分页查询 API。核对：通用约定保留 Base URL、成功响应结构、公共错误响应结构及 JSON、时间和标识符规范；成功与错误响应均使用 HTTP 200，响应体顶层 code 不同，客户端仅根据 code 区分结果；不生成“分页约定”或“不分页”占位。
+
+## Case 5：分页 API
+
+分别覆盖：
+- A：Product Requirement 未给出允许值，知识库规范为 `20/50/100` → API 文档使用 `20/50/100`。
+- B：Product Requirement 明确允许值为 `5/10/20` → API 文档必须与之完全一致，不得改回默认集合。
+- C：每页条数参数分别为必填与可选 → 两种文档都应通过。
+- D：实际分页但缺少“分页约定” → validator 与 forward-test 都判定失败。
+- E：非分页 API 出现“分页约定”或“不分页”占位 → validator 与 forward-test 都判定失败。
+- F：page-size 参数允许值与“分页约定”或 Product Requirement 明确集合不一致 → validator 与 forward-test 都判定失败。
+- G：Product Requirement、知识库和仓库均未给出允许值 → API 文档才使用默认 `10/20/50/100`。
+
+## Case 6：backend 定时任务
+
+使用触发方式为定时任务的归档需求。核对：只生成 Dependency；故事“API 文档引用”写“`不适用；触发方式为 定时任务`”；API 映射写不适用；重点定位 scheduler、job、幂等、批次、数据和恢复测试。
+
+## Case 7：API 必要业务契约缺失
+
+分别删除 API 型故事输出规范中的输入语义、输出语义、权限规则、业务规则、安全要求或错误与边界。核对：Product Requirement Input Validator 失败，不重新评价 AC 文案风格。
+
+## Case 8：Input Validator 不重复上游质量检查
+
+使用已通过上游校验且具备故事、同 ID 输出规范、AC ID、触发方式、页面路由或 API 必要业务契约的 Product Requirement，但 AC 正文风格不是下游偏好的写法。核对：Input Validator 仍通过。
+
+## Case 9：完整故事文件清单
+
+使用两个故事且二者影响同一文件。核对：每个故事都有独立完整的“影响文件”清单；F 编号在故事内重新开始并只在该故事内引用；不生成全局文件索引。
+
+## Case 10：故事局部风险
+
+制造一个仅属于 `FE-US-001` 的路由冲突和一个跨前后端共享契约风险。核对：路由冲突只写在故事详情，跨域风险只写在文末“跨故事风险与未定位项”，同一风险不重复。
+
+## Case 11：API 覆盖与孤立检测
+
+让 API-backed 故事漏掉 API ID、API ID 缺少代码入口、或 API 文档新增未被任何故事引用的 API。核对：三种情况都失败；纯前端或非 API 后端故事使用带原因的“不适用”可以通过。
+
+## Case 12：内容边界
+
+尝试把 Given/When/Then 正文、完整 Query 参数、响应、Schema 或 JSON 示例复制到 Dependency Analysis。核对：校验失败；API 实现映射只保留 API ID、Operation ID、Method + Path 和代码入口。
+
+## Case 13：代码位置 unknown
+
+代码库中没有目标能力。核对：继续生成 Dependency，记录搜索范围、原因、下一步和 low 置信度；不向用户询问代码位置，也不虚构文件。
+
+## Case 14：项目规范
+
+使用包含共享状态枚举、空状态组件和同类页面的仓库，并让 `kb-design-assist` 返回当前有效设计系统规范。核对：先获得精简规范证据；当前宿主支持隔离的只读代码侦察 agent 时委派其核验代码落点，不支持时由当前 agent 执行同等范围的定向搜索；Dependency 使用真实枚举、组件、文案与恢复方式，同时区分 `KB-EVIDENCE-*` 与代码证据，不套用 generic 模板。
+
+## Case 15：api-only
+
+使用 complete backend API Product Requirement、真实仓库和 `--mode api-only`。核对：只创建或更新 `api-documentation.md`，已有 Dependency 字节不变；只运行 Product Requirement Input 和 API 两个当前产物校验器，不运行 Dependency 校验器或 validator matrix。
+
+## Case 16：非法 api-only
+
+分别使用 `--mode api-only --target frontend` 和没有 API 型后端故事的需求。核对：停止并报告原因，不生成空 API 文档或 blocked Dependency。
+
+## Case 17：普通执行验证范围
+
+分别运行 frontend、backend 非 API、backend API、api-only 和 blocked 流程。核对：只运行各自当前产物 validator；`test-validators.mjs` 仅在维护或发布回归时运行。
+
+## Case 18：后端规范知识检索
+
+使用 API 型后端故事，并让 `kb-design-assist` 命中 Controller/Service/Entity/Response、Remote、Web API、错误码清单和服务 `interfaces.md`。核对：在代码侦察前执行定向知识检索；API 中间模型优先采用当前有效规范并由仓库共享定义核验；API Documentation 只呈现最终 HTTP 契约，不包含 `KB-EVIDENCE-*`、知识库路径、调用过程或“复用检查”。
+
+## Case 19：知识库与代码现状冲突
+
+知识库要求统一 `ApiResponse` 和新的错误码体系，仓库目标模块仍使用旧响应类型。核对：当前影响文件与调用关系以代码证据为准；有效知识库规范作为目标约束；Dependency 登记规范迁移/合规风险，不把知识库文档列为影响文件，也不静默把旧实现当作规范。
+
+## Case 20：知识库强制前置、未命中与不可用
+
+分别构造“看似不涉及项目规范”的简单故事、相关查询无结果和 `kb-design-assist` 调用失败。核对：简单故事仍先从故事、输出规范和 AC 提取检索计划并真实调用，不允许 `not-executed`；无结果记录 `executed-no-match` 并把项目规范检索降级为受限、定向的代码库搜索；调用失败记录 `unavailable`，必须先说明失败原因并询问用户选择“修复后重试”或“跳过知识库”，未选择前不得预扫描项目资料、侦察代码或生成 complete 产物；选择修复后按重试结果继续，明确选择跳过后才允许降级；仍未查明时按 unknown 处理。不得模拟知识库结果或绕过确认门禁。
+
+## Case 21：Web + Remote 生成两个 API
+
+使用触发方式为 `API（Web + Remote）` 的订单列表故事。核对：同一故事至少引用两个 API ID，分别生成项目规范确定的 Web 与 Remote Method+Path；`/order/list` 和 `/remote/order/list` 仅作为可能示例，不得把 `/remote` 前缀写成固定规则。
+
+## Case 22：frontend 外部 API 文档
+
+使用 scope 为 frontend 的 Product Requirement，并传入需求目录外且包含多个无关接口的 Markdown API 文档。核对：Dependency 只记录当前故事实际引用的 Method+Path；不记录 API ID、Operation ID、文档路径或完整契约；无关接口不触发孤立错误；未传 `--api-doc` 或引用不存在的 Method+Path 时校验失败。
+
+## Case 23：项目资料预扫描
+
+知识库状态确定后提供三个 `ai_workspace` 目录。核对：常规代码侦察前按 `project-how-to`、`code-specification`、`project-business` 顺序枚举并定向读取；缺失目录不阻断；知识库、项目资料和代码冲突时保留差异证据。
+
+## Case 23A：知识库与代码侦察顺序
+
+使用包含状态、权限和 API 线索且仓库已有相似实现的故事。核对执行轨迹严格为：从选中故事、输出规范和 AC 提取检索计划 → 调用 `kb-design-assist` → 项目资料预扫描 → 定向代码侦察 → 汇总双证据与风险。不得先搜索仓库再补做知识库检索。
+
+## Case 24：严格索引与详情唯一性
+
+分别向 V4 frontmatter 注入仓库路径、在 API 索引增加没有详情的 API、修改索引中的 Operation ID、为同一故事复制一份依赖详情，并让两个输入故事复用同一 AC ID。核对：额外 frontmatter 字段、非双向一一对应的 API 索引、重复故事详情和重复 AC ID 都被 validator 拒绝。

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

@@ -0,0 +1,34 @@
+# Product Requirement 输入契约
+
+首选输入为 complete V4 `product-requirement.md`。迁移期允许读取 complete V2/V3，但不修改上游产物；新产物始终使用 V4。
+
+## 校验边界
+
+输入校验器只确认下游能够安全消费 Product Requirement，不重复上游的全部文案与 AC 质量检查。
+
+不重新评价：Given/When/Then 文本质量、最低条目数量、完整决策追溯、Clarification 状态、实现细节泄漏禁语、分页默认补齐策略，以及其他只属于上游生成质量的禁止措辞。实现泄漏禁语信任上游交付路径；本 skill 不复查。
+
+交接门禁：下游只接受上游按交付路径校验通过的 complete Product Requirement（不得携带 `--allow-pending`）。首选 complete V4；迁移期仍可读取 V3 和非 API 的 complete V2（见下文）。本 skill 的 `--target` 可取上游 `analysis_scope` 的子集，不会改写上游产物。
+
+## V3/V4 要求
+
+选中范围内至少一个用户故事、同 ID 输出规范和嵌入规范的 AC ID。故事与规范一一对应，故事 AC 引用与规范内 AC ID 完全一致。前端故事必须包含页面路由；无独立路由时使用“不适用”并说明所属页面。后端故事必须包含合法触发方式。
+Product Requirement frontmatter 只允许对应版本契约定义的字段；AC ID 在整个输入中必须全局唯一。
+
+API 型后端故事必须具备下游建模最小业务契约字段：输入语义、输出语义、权限规则、业务规则、安全要求、错误与边界。触发方式必须明确为 `API（Web）`、`API（Remote）` 或 `API（Web + Remote）`；迁移期 V3 中笼统的 `API` 也必须返回上游确认范围。Web 与 Remote 都生成 HTTP API 契约，Web + Remote 生成两个独立 API。上游输出规范中的「数据读写」「幂等与并发」不作为本 skill 输入门禁字段。
+
+## V2 迁移期
+
+V2 按原有“AC 嵌在故事内”的方式读取，不要求独立输出规范章节。V2 + API 触发故事时，禁止生成 API Documentation 与 complete Dependency Analysis 中的 API 映射路径；输入校验器对此组合直接失败，要求先用需求分析 skill 升级为 V4。非 API 的 V2 仍可做依赖落点分析。
+
+## 仓库、范围与模式
+
+必须提供存在、可读的代码仓库。Product Requirement 位于 `<project-root>/docs/product-analysis/<requirement-id>/`；新增产物写回同目录并继承 ID。显式 target 必须是上游 scope 的子集。
+
+`mode` 使用 `full` 或 `api-only`，默认 `full`。`api-only` 只适用于 target 为 `backend|both` 且至少一个选中后端故事的触发方式为 API；它只生成 `api-documentation.md`，不得创建或修改 `dependency-analysis.md`。其代码侦察仍必须覆盖仓库 API 规范、共享 Schema、统一响应/错误和分页约定。
+
+任一选中后端故事的触发方式为 API 时生成 `api-documentation.md`；非 HTTP 触发不得生成空 API 文档。`frontend` 不新生成 API 文档；可通过 `--api-doc <path>` 消费任意可读 Markdown API 文档，只把当前故事引用且能核验的 Method+Path 写入 Dependency Analysis。外部文档可包含无关接口，不执行整份文档孤立检查，也不持久化文档路径。业务契约字段缺失时阻断；分页契约按 `api-documentation-schema.md` 生成。
+
+## 阻断产物
+
+`full` 门禁失败时：若可从 Product Requirement 路径、用户显式 `requirement_id` 或输出路径确定需求目录，则写入 blocked 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、api-surface-unconfirmed。`api-only` 门禁失败时不生成占位产物，只在会话中报告阻断原因与恢复条件。