@tea-agent/loop-agent 0.33.1 → 0.33.3

package/docs/templates/frontend-test-dag.json

@@ -11,18 +11,19 @@
   "globalConstraints": [
     "Do not generate pytest or Playwright source code.",
     "Only use declared isolated test environments; production URLs and real credentials are blocked.",
-    "Every generated browser start command uses playwright-cli open --browser=chrome followed by the concrete controller-resolved URL (from task source config.md when present, else http://localhost:5173); executable case lines never retain an angle-bracket URL/ref placeholder; subsequent commands stay in that default session and must not use unverified named-session flags.",
+    "Every generated browser start command uses playwright-cli open --browser=chrome followed by the concrete controller-resolved URL (resolved from an explicit allowlist of controller-owned, hash-bound task source/reference documents and URL keys: baseUrl, targetUrl, loginUrl and common case/separator variants; http://localhost:5173 is used only when no allowed candidate exists, and conflicting same-priority candidates fail closed); executable case lines never retain an angle-bracket URL/ref placeholder; subsequent commands stay in that default session and must not use unverified named-session flags.",
     "Case children execute serially. Persist each case result, logs and browser evidence before the next child starts.",
     "A token threshold is a post-case stop check, not a model hard token cap; unstarted cases must be recorded as blocked: token-budget-exhausted.",
     "Default pipeline acceptance is the final frontend-test-result-v1 plus testcase/frontend/reports/frontend-test-report.html",
     "Default frontendTest.reviewMode=off uses mechanical checklist-shell before materialize; set reviewMode=blocking for legacy dual LLM review gate.",
     "playwright-cli-only: generators and executors may call only skill-declared playwright-cli commands; bare playwright / npx playwright / @playwright/test / Playwright source are forbidden with no native Playwright fallback.",
-    "Browser-tool preflight (preflight-frontend-browser-tool-shell) must reject CODE_AGENT_PI_BACKEND=cli-only, verify the Pi SDK structured custom-tool surface, freeze baseUrl from hash-bound task source config.md (or controller default localhost), and confirm the verified playwright-cli launcher + --help contract before any frontend-test Pi node; missing capability/CLI fails with zero Pi calls.",
+    "Browser-tool preflight (preflight-frontend-browser-tool-shell) must reject CODE_AGENT_PI_BACKEND=cli-only, verify the Pi SDK structured custom-tool surface, freeze baseUrl from allowlisted hash-bound task references and explicit baseUrl/targetUrl/loginUrl keys (or controller default localhost only when no candidate exists), and confirm the verified playwright-cli launcher + --help contract before any frontend-test Pi node; missing capability/CLI fails with zero Pi calls.",
     "Case executors use structured playwright_cli custom tool under commandPolicy capability-allowlist; playwright-cli stays capability-gated while ordinary writers have bash.",
     "File outputs use canonical --filename: playwright-cli screenshot --filename final.png (a real target/ref may precede it), playwright-cli pdf --filename final.pdf, and playwright-cli snapshot --filename snapshot.txt only when a snapshot file is needed; a snapshot without filename is response-only. Never use --path, --output, --file, or an output path as a positional target.",
     "Passed cases require same-child ordered controller receipts: successful open → successful find → successful post-execution cleanup. Pre-start cleanup, snapshot/goto/screenshot/request/console, and ordinary interactions cannot establish passed authority; model prose cannot fake green.",
     "Environment preflight must curl-probe the frozen non-production baseUrl before generate; unreachable or curl-unavailable ends preflight as blocked (frontend-base-url-unreachable|curl-unavailable) so generate/map do not run.",
-    "U/D cases must prove current-user data ownership or create cleanable current-user data or authorized Mock; otherwise blocked (current-user-data-unavailable|data-ownership-unverifiable|safe-test-data-setup-unavailable) without cross-user mutation."
+    "U/D cases must prove current-user data ownership or create cleanable current-user data or authorized Mock; otherwise blocked (current-user-data-unavailable|data-ownership-unverifiable|safe-test-data-setup-unavailable) without cross-user mutation.",
+    "Rerun topology is bounded by frontendTest.maxRerunAttempts (0..4, default 2): the runtime hybrid emits one select+map pair per attempt round, each round only candidates blocked or missing-result cases and rewrites the authoritative case-result.json/execution.md, so the final round's evidence controls the report."
   ],
   "tasks": [
     {
@@ -37,8 +38,8 @@
         ".harness/**",
         "artifacts/**"
       ],
-      "outputContract": "Deterministic SDK-only browser-tool preflight before any frontend-test Pi node; freeze a controller-owned origin and fail closed with browser-command-capability-unavailable | playwright-cli-unavailable | playwright-cli-contract-incompatible.",
-      "subtask_prompt": "Reject cli-only rollback, verify the Pi SDK structured custom-tool capability, freeze baseUrl from controller-owned task source/default, and verify the controller-resolved playwright-cli launcher plus --help lists open/close/find/snapshot/click. Do not install packages. Do not start a browser session.",
+      "outputContract": "Deterministic SDK-only browser-tool preflight before any frontend-test Pi node; freeze a controller-owned origin (baseUrl/targetUrl/loginUrl allowlist with deterministic priority and fail-closed ambiguity) and fail closed with browser-command-capability-unavailable | playwright-cli-unavailable | playwright-cli-contract-incompatible.",
+      "subtask_prompt": "Reject cli-only rollback, verify the Pi SDK structured custom-tool capability, freeze baseUrl from controller-owned task source/reference via the explicit document+key allowlist (baseUrl/targetUrl/loginUrl variants; default localhost only when no candidate; fail closed on ambiguity), and verify the controller-resolved playwright-cli launcher plus --help lists open/close/find/snapshot/click. Do not install packages. Do not start a browser session.",
       "shell": {
         "commands": [],
         "frontendBrowserToolPreflight": {},
@@ -120,7 +121,7 @@
         "artifacts/**"
       ],
       "outputContract": "Fail-closed environment preflight: absolute non-production baseUrl + curl HTTP reachability; writes environmentProbe facts; unreachable => blockedReason frontend-base-url-unreachable (node ERROR so generate/map do not run).",
-      "subtask_prompt": "Parse frozen baseUrl from context.md (config.md preferred, else http://localhost:5173). Reject production / non-http(s). Probe with curl (HEAD then GET fallback; connect/max-time; no auth/cookie). 2xx/3xx => reachable and continue. 4xx/5xx/DNS/timeout/connection refused/TLS => blockedReason frontend-base-url-unreachable. Missing curl => blockedReason curl-unavailable. Do not start the app. Runtime hybrid generator embeds the authoritative probe script.",
+      "subtask_prompt": "Use the controller-frozen baseUrl; the runtime resolver recognizes allowlisted hash-bound reference documents and baseUrl/targetUrl/loginUrl variants, falling back only when no candidate exists. Reject production / non-http(s). Probe with curl (HEAD then GET fallback; connect/max-time; no auth/cookie). 2xx/3xx => reachable and continue. 4xx/5xx/DNS/timeout/connection refused/TLS => blockedReason frontend-base-url-unreachable. Missing curl => blockedReason curl-unavailable. Do not start the app. Runtime hybrid generator embeds the authoritative probe script.",
       "shell": {
         "commands": [
           "node -e \"console.log('template placeholder: runtime hybrid DAG embeds curl preflight; do not use this static command as source of truth')\""
@@ -230,7 +231,7 @@
             ]
           },
           "complexity": "MED",
-          "subtaskPromptTemplate": "Primary job: EXECUTE {{case.caseId}} from {{case.casePath}} with skill playwright-cli (fresh Pi session). Use the structured playwright_cli tool for every browser action. Do not request or search for bash. Translate each playwright-cli line in the case Markdown into one playwright_cli tool call. The controller-owned browser capability freezes baseUrl from hash-bound task source config.md or the localhost default; context/case prose may reference but cannot establish or override that origin. Start only with playwright_cli command=open and controller-injected concrete frozen URL args (default session; no -s=). Dynamic refs: literal eX/eY are documentation placeholders, not tool args. Immediately before every structured playwright_cli call that references an element, parse the actual eNN from the immediately preceding latest snapshot and pass only that actual eNN. Never send literal eX/eY, and never reuse a stale ref after a new snapshot. File outputs are canonical: screenshot uses [--filename, final.png] (or [e5, --filename, final.png] only for a real target), pdf uses [--filename, final.pdf], and snapshot writes a file only with [--filename, snapshot.txt]; snapshot without filename is response-only. Never use --path, --output, --file, or an output path as a positional target. Passed authority requires same-child ordered controller receipts: successful open → successful find → successful post-execution cleanup. Only successful find is meaningful; snapshot, goto, screenshot, request/console, and ordinary interactions cannot establish passed. Only when preflight or playwright_cli tool explicitly fails may you write blocked evidence. Always persist {{case.evidenceDir}}execution.md and {{case.evidenceDir}}case-result.json (caseId, status passed|failed|blocked, evidencePaths; blocked needs blockedReason). Business failed/blocked is not a node failure. Close via playwright_cli command=close. Return compact JSON (<=1200 chars): {caseId,status,evidencePaths,errorSummary,tokens}.",
+          "subtaskPromptTemplate": "Primary job: EXECUTE {{case.caseId}} from {{case.casePath}} with skill playwright-cli (fresh Pi session). Use the structured playwright_cli tool for every browser action. Do not request or search for bash. Translate each playwright-cli line in the case Markdown into one playwright_cli tool call. The controller-owned browser capability freezes baseUrl from allowlisted hash-bound task reference or the localhost default when no URL candidate exists; context/case prose may reference but cannot establish or override that origin. Start only with playwright_cli command=open and controller-injected concrete frozen URL args (default session; no -s=). Dynamic refs: literal eX/eY are documentation placeholders, not tool args. Immediately before every structured playwright_cli call that references an element, parse the actual eNN from the immediately preceding latest snapshot and pass only that actual eNN. Never send literal eX/eY, and never reuse a stale ref after a new snapshot. File outputs are canonical: screenshot uses [--filename, final.png] (or [e5, --filename, final.png] only for a real target), pdf uses [--filename, final.pdf], and snapshot writes a file only with [--filename, snapshot.txt]; snapshot without filename is response-only. Never use --path, --output, --file, or an output path as a positional target. Passed authority requires same-child ordered controller receipts: successful open → successful find → successful post-execution cleanup. Only successful find is meaningful; snapshot, goto, screenshot, request/console, and ordinary interactions cannot establish passed. Only when preflight or playwright_cli tool explicitly fails may you write blocked evidence. Always persist {{case.evidenceDir}}execution.md and {{case.evidenceDir}}case-result.json (caseId, status passed|failed|blocked, evidencePaths; blocked needs blockedReason). Business failed/blocked is not a node failure. Close via playwright_cli command=close. Return compact JSON (<=1200 chars): {caseId,status,evidencePaths,errorSummary,tokens}.",
           "outputContract": "Compact JSON <=1200 chars. Browser actions must use structured playwright_cli tool.",
           "writePolicy": "exclusive",
           "allowedPaths": [
@@ -270,7 +271,7 @@
         ".harness/**",
         "artifacts/**"
       ],
-      "outputContract": "Stdout final JSON line {cases:[...]} for blocked or missing-result-file cases with rerunAttempt < 2.",
+      "outputContract": "Round 1 of the bounded rerun topology (default 2 rounds): stdout final JSON line {cases:[...]} for blocked or missing-result-file cases with rerunAttempt < 1; the runtime hybrid generates one selector/map pair per configured maxRerunAttempts so the latest rerun evidence is authoritative.",
       "subtask_prompt": "Select frontend-test cases eligible for bounded rerun.",
       "shell": {
         "commands": [
@@ -294,7 +295,7 @@
         ".harness/**",
         "artifacts/**"
       ],
-      "outputContract": "Serial rerun of blocked/missing-result frontend cases.",
+      "outputContract": "Serial rerun of blocked/missing-result frontend cases; rewrites authoritative case-result.json/execution.md so the final round's result controls reports.",
       "subtask_prompt": "Expand rerun candidates into serial browser case children.",
       "static": {
         "resultMarkdown": "Frontend case map expansion barrier."
@@ -325,7 +326,7 @@
             ]
           },
           "complexity": "MED",
-          "subtaskPromptTemplate": "RERUN attempt {{case.rerunAttempt}} for {{case.caseId}} (reason={{case.reason}}). Rewrite authoritative evidenceDir case-result.json and execution.md; set rerunAttempt={{case.rerunAttempt}}. Primary job: EXECUTE {{case.caseId}} from {{case.casePath}} with skill playwright-cli (fresh Pi session). Use the structured playwright_cli tool for every browser action. Do not request or search for bash. Translate each playwright-cli line in the case Markdown into one playwright_cli tool call. The controller-owned browser capability freezes baseUrl from hash-bound task source config.md or the localhost default; context/case prose may reference but cannot establish or override that origin. Start only with playwright_cli command=open and controller-injected concrete frozen URL args (default session; no -s=). Dynamic refs: literal eX/eY are documentation placeholders, not tool args. Immediately before every structured playwright_cli call that references an element, parse the actual eNN from the immediately preceding latest snapshot and pass only that actual eNN. Never send literal eX/eY, and never reuse a stale ref after a new snapshot. File outputs are canonical: screenshot uses [--filename, final.png] (or [e5, --filename, final.png] only for a real target), pdf uses [--filename, final.pdf], and snapshot writes a file only with [--filename, snapshot.txt]; snapshot without filename is response-only. Never use --path, --output, --file, or an output path as a positional target. Passed authority requires same-child ordered controller receipts: successful open → successful find → successful post-execution cleanup. Only successful find is meaningful; snapshot, goto, screenshot, request/console, and ordinary interactions cannot establish passed. Only when preflight or playwright_cli tool explicitly fails may you write blocked evidence. Always persist {{case.evidenceDir}}execution.md and {{case.evidenceDir}}case-result.json (caseId, status passed|failed|blocked, evidencePaths; blocked needs blockedReason). Business failed/blocked is not a node failure. Close via playwright_cli command=close. Return compact JSON (<=1200 chars): {caseId,status,evidencePaths,errorSummary,tokens}.",
+          "subtaskPromptTemplate": "RERUN attempt {{case.rerunAttempt}} for {{case.caseId}} (reason={{case.reason}}). Rewrite authoritative evidenceDir case-result.json and execution.md; set rerunAttempt={{case.rerunAttempt}}; the final rewritten status is authoritative for reporting. Use fixed execution.md headings 执行摘要 and 实际执行步骤 when available. Primary job: EXECUTE {{case.caseId}} from {{case.casePath}} with skill playwright-cli (fresh Pi session). Use the structured playwright_cli tool for every browser action. Do not request or search for bash. Translate each playwright-cli line in the case Markdown into one playwright_cli tool call. The controller-owned browser capability freezes baseUrl from allowlisted hash-bound task reference or the localhost default when no URL candidate exists; context/case prose may reference but cannot establish or override that origin. Start only with playwright_cli command=open and controller-injected concrete frozen URL args (default session; no -s=). Dynamic refs: literal eX/eY are documentation placeholders, not tool args. Immediately before every structured playwright_cli call that references an element, parse the actual eNN from the immediately preceding latest snapshot and pass only that actual eNN. Never send literal eX/eY, and never reuse a stale ref after a new snapshot. File outputs are canonical: screenshot uses [--filename, final.png] (or [e5, --filename, final.png] only for a real target), pdf uses [--filename, final.pdf], and snapshot writes a file only with [--filename, snapshot.txt]; snapshot without filename is response-only. Never use --path, --output, --file, or an output path as a positional target. Passed authority requires same-child ordered controller receipts: successful open → successful find → successful post-execution cleanup. Only successful find is meaningful; snapshot, goto, screenshot, request/console, and ordinary interactions cannot establish passed. Only when preflight or playwright_cli tool explicitly fails may you write blocked evidence. Always persist {{case.evidenceDir}}execution.md and {{case.evidenceDir}}case-result.json (caseId, status passed|failed|blocked, evidencePaths; blocked needs blockedReason). Business failed/blocked is not a node failure. Close via playwright_cli command=close. Return compact JSON (<=1200 chars): {caseId,status,evidencePaths,errorSummary,tokens}.",
           "outputContract": "Compact JSON <=1200 chars. Browser actions must use structured playwright_cli tool.",
           "writePolicy": "exclusive",
           "allowedPaths": [

package/docs/templates/frontend-test-dag.retrieve-context.prompt.md

@@ -4,7 +4,7 @@ Write only `testcase/frontend/rag/context.md` and `coverage-map.md`. Record trac
 
 ## Controller-frozen Base URL (required)
 
-The preflight controller resolves and freezes one absolute browser base URL from hash-bound task source `config.md` (or the controller default `http://localhost:5173`) before this Pi node runs. Copy that supplied value and source exactly into `context.md` as `baseUrl: <url>` and `baseUrlSource: <source>`.
+The preflight controller resolves and freezes one absolute browser base URL before this Pi node runs. It accepts only controller-owned, hash-bound reference documents on its filename/key allowlists (including `config.md`, `environment.md`, `urls.md` and explicit `baseUrl` / `targetUrl` / `loginUrl` variants); it fails closed on conflicting candidates and uses the localhost default only when no candidate exists. Copy the supplied value and source exactly into `context.md` as `baseUrl: <url>` and `baseUrlSource: <source>`.
 
 - Do not derive, replace, or override the origin from model reasoning, route text, case prose, existing RAG files, or other repository content.
 - Never use production hosts or credentials.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.33.1",
+  "version": "0.33.3",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

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

@@ -1,67 +1,108 @@
 ---
 name: analyze-product-dependencies
-description: 基于 complete Product Requirement 探索代码库，按 frontend、backend 或 both 范围将故事、输出规范和验收标准映射到真实文件、组件、服务、数据、权限与证据，并仅为 API 型后端故事生成精简 Swagger 风格 Markdown API 文档。用于代码影响分析、依赖分析、API 文档或需求到代码映射。
+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 必须位于项目根的需求目录。
+- 必填：complete `product-requirement.md` 的实际路径和可读取代码仓库路径。Product Requirement 必须位于 `<project-root>/docs/product-analysis/<requirement-id>/`。
 - 可选：`target=frontend|backend|both` 或 `--target frontend|backend|both`；两种写法等价，默认继承上游 scope。
-- 输出写回 Product Requirement 所在目录；始终生成 `dependency-analysis.md`，选中 API 型后端故事时额外生成 `api-documentation.md`。
+- 可选：`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
-  - [ ] 读取 `references/input-contract.md` 并运行 Product Requirement 输入校验器。
-  - [ ] 将 `target=<value>` 和 `--target <value>` 归一化为唯一 target；缺省时继承上游 scope，非法值或冲突的多个值必须停止。
-  - [ ] 从 Product Requirement 继承 `requirement_id`、`project_root` 和输出目录；显式 target 必须是上游 scope 的子集，只校验和分析选中故事。
+  - [ ] 将 `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，后续不得自动扩大范围。
-  - [ ] 门禁失败时只生成 blocked Dependency Analysis，不伪造 API 或代码落点。
+  - [ ] `full` 门禁失败且可确定输出位置时只生成 blocked Dependency Analysis，不伪造 API 或代码落点；`api-only` 门禁失败时不写任何产物，只报告阻断原因和恢复条件。
 - [ ] Step 1：完整代码侦察 ⚠️ REQUIRED
-  - [ ] 读取 `references/scouting-rules.md`。
-  - [ ] 逐个读取选中故事及其同 ID 输出规范和 AC，再定位入口、调用链、状态、类型、数据、权限、错误、日志和测试；`frontend` 不分析 `BE-US-*`，`backend` 不分析 `FE-US-*`。
-  - [ ] 区分 confirmed、inferred、unknown，并为每项结论提供证据。
+  - [ ] 从选中故事、同 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，就必须生成 API 文档。
-  - [ ] target 为 `frontend` 时不读取或分析后端故事，不生成 API 文档或 API 实现映射。
+  - [ ] 只要一个选中的 `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 时 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 或仓库通用分页定义明确时写入。
+  - [ ] 无 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 契约、字段、响应、错误与分页参数；完全移除认证方式、权限要求、业务规则、处理流程、分支逻辑、数据读写逻辑和实现算法及其相关内容。
-  - [ ] API 文档与依赖分析必须从同一模型渲染。
+  - [ ] API 文档只保留 HTTP 契约；不得包含故事/AC 追溯、认证、权限、业务规则与实现逻辑。只有实际分页时才生成“分页约定”。
 - [ ] 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`，同目录引用使用 `./文件名`。
+  - [ ] `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 输入校验必须通过。
-  - [ ] 向 Product Requirement、Dependency 和适用的 API 校验器传入归一化 target；API 场景运行 API 和 Dependency 两个校验器，非 API 场景只运行 Dependency 校验器。
-  - [ ] 覆盖矩阵承担全局追溯，不生成重复的文末追溯汇总。
-  - [ ] 运行 validator matrix，修复全部错误后再声明完成。
+  - [ ] 向所有适用校验器传入归一化 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
 
-完整示例按需读取 `references/example.md`；维护或 forward-test 时读取 `references/forward-test-cases.md`。
+- 从聊天、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] --target <frontend|backend|both>
-node <skill-root>/scripts/test-validators.mjs
+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

@@ -1,30 +1,35 @@
-# Swagger 风格 Markdown API 文档 V3 契约
+# Swagger 风格 Markdown API 文档 V4 契约
 
 文件名固定为 `api-documentation.md`。它采用 Swagger 的信息组织方式，但不是 OpenAPI YAML。
 
 ```yaml
 ---
-artifact_version: "3.0"
+artifact_version: "4.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 文档中完全移除认证方式、权限要求、业务规则、业务逻辑、处理逻辑和实现逻辑及其相关内容。
+Frontmatter 只允许以上五个字段，不得增加来源、项目根、仓库路径或其他运行时字段。
 
-通用约定包含 Base URL、统一响应结构、错误响应结构、分页约定、时间和标识符规范。不输出公共定义的搜索过程、命中证据或“复用检查”章节。
+固定章节：通用约定、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、用户故事、AC、变更类型。
+基本信息只包含 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 核对。
 
-成功响应包含至少一个 2xx 和合法 JSON 示例；错误响应包含至少一个 4xx/5xx 和合法 JSON 示例。变更类型使用新增、修改、复用。
+无对应内容时省略空的 Header、Path、Query 或 Request Body 子章节。Schema 字段只在“数据模型”完整定义一次，接口详情引用 Schema。“数据模型”只定义实际使用的 Schema 和字段；“错误码”只说明 code 和可观测的触发条件，HTTP 状态统一为 `200`。字段、Response、错误码、时间与标识符等技术约定在 Product Requirement 未规定时，优先采用 `kb-design-assist` 返回的当前有效规范，再核验仓库共享定义。两个章节均不新增“复用检查”，不输出知识库或代码搜索过程，不展开业务判定或实现逻辑。
 
-分页接口在 Query 参数中定义每页条数参数：必填性为“否”，允许值完整列为 `10 | 20 | 50 | 100`。参数名优先复用仓库现有约定，例如 `pageSize`、`page_size` 或 `limit`。只有 Product Requirement 或仓库通用分页定义明确时才写默认值，不再生成 `<100`、`=100`、`>100` 分页场景。
+`mode=api-only` 与 `mode=full` 使用完全相同的 API 契约和校验规则。`api-only` 只生成本文件，不创建、覆盖或追加 `dependency-analysis.md`。
 
-“数据模型”只定义实际使用的 Schema 和字段；“错误码”只说明 HTTP 状态、code 和可观测的触发条件。两个章节均不新增“复用检查”，不输出公共定义搜索过程，不展开业务判定或实现逻辑。
+`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

@@ -1,28 +1,38 @@
-# Dependency Analysis V3 输出契约
+# Dependency Analysis V4 输出契约
 
 ```yaml
 ---
-artifact_version: "3.0"
+artifact_version: "4.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 实现映射、跨故事共享依赖、风险与未定位项。覆盖矩阵承担全局追溯，不生成独立分析范围或追溯汇总。
+Frontmatter 只允许以上六个字段，不得增加来源、项目根、仓库路径或其他运行时字段。
 
-前端详情字段：验收标准、影响文件、页面/路由、组件、状态、API client/类型、状态与边界落点、定位证据、风险、置信度。
+Complete 固定章节：输入与代码基线、用户故事覆盖矩阵、按 scope 的依赖详情、API 实现映射、跨故事共享依赖、跨故事风险与未定位项。覆盖矩阵承担全局追溯，不生成独立分析范围、全局文件索引或追溯汇总。“输入与代码基线”记录知识检索状态 `executed-hit | executed-no-match | unavailable`；每次分析都必须真实执行知识检索，不允许未执行状态。若 complete 产物最终仍记录 `unavailable`，必须同时记录 `- 用户处置：已确认跳过知识库`；命中有效规范时可列必要的 `KB-EVIDENCE-*` 摘要。
+
+前端详情字段：验收标准、API 文档引用、影响文件、页面/路由、组件、状态、API client/类型、状态与边界落点、定位证据、风险、置信度。
 
 后端详情字段：验收标准、API 文档引用、影响文件、路由/入口、Controller/Handler、Service/领域逻辑、DTO/Schema、数据依赖、权限依赖、错误/日志/审计、测试落点、定位证据、风险、置信度。
 
-`影响文件` 是完整权威清单，每项使用唯一 `F<number>`、add/modify/reuse、真实路径和用途；其他代码落点字段引用这些编号，不重复完整路径。
+职责边界：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` 模式不生成本产物。
 
-API 实现映射只登记 API ID、Operation ID、方法路径和代码入口。无 API 时写：`不适用。本次需求不涉及 HTTP API。`
+不得复制 AC 的 Given/When/Then 正文或完整 API 参数、响应、Schema、JSON 示例。
 
 Blocked 产物只含分析范围、输入与代码基线、阻断原因、恢复条件，不得包含确定性代码位置或 API 契约。

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

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

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

@@ -1,35 +1,110 @@
 # Forward-Test Cases
 
-## Case 1：缩小为 frontend
+在独立 agent 中逐个执行，只提供原始请求与输入产物，不泄露预期正文。
 
-使用 complete、scope 为 both 的 Product Requirement 和真实仓库，指定 `--target frontend`。核对：只生成 `dependency-analysis.md`；`analysis_scope` 为 `frontend`；不生成空 API 文档；没有后端依赖章节、`BE-US-*` 或 API 实现映射；每个 FE 故事有文件证据和状态边界落点。
+## Case 1：frontend 路由与非 API 引用
 
-## Case 2：backend API
+使用 complete、scope 为 frontend 的 Product Requirement，其中页面路由为 `/account/orders`，故事无 HTTP 依赖。核对：只生成 Dependency Analysis；详情保留目标 URL；“API 文档引用”写“`不适用；本故事无 HTTP API 依赖`”；API 实现映射明确不适用；不生成空 API 文档。
 
-```text
-Use $analyze-product-dependencies with a complete backend Product Requirement whose BE-US-001 trigger is API, plus a repository.
-```
+## Case 2：无独立路由组件
 
-核对：两个文件写入 Product Requirement 的同一需求目录；API 索引覆盖 API ID、Operation ID、方法路径、故事和 AC；Dependency 的 API 映射只保留 API ID、Operation ID、方法路径和代码入口；影响文件使用唯一 F 编号。
+Product Requirement 页面路由写“`不适用；嵌入 /account/orders 页面`”。核对：Dependency 不虚构独立 URL，定位所属页面与组件落点。
 
-同时核对：API 文档不含认证方式、权限要求、业务规则、业务逻辑或实现逻辑及其相关内容；字段与 code 在生成前内部搜索共享定义，但 API 文档不输出“复用检查”或搜索证据。若接口分页，每页条数参数必须可选，允许值完整包含 `10/20/50/100`。
+## Case 3：backend API
 
-## Case 3：backend 定时任务
+使用 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。
 
-使用触发方式为定时任务的归档需求。核对：只生成 Dependency；`source_api_documentation: none`；API 映射写不适用；重点定位 scheduler、job、幂等、批次、数据库和恢复测试。
+## Case 4：非分页 API
 
-## Case 4：业务契约缺失
+使用非分页查询 API。核对：通用约定保留 Base URL、成功响应结构、公共错误响应结构及 JSON、时间和标识符规范；成功与错误响应均使用 HTTP 200，响应体顶层 code 不同，客户端仅根据 code 区分结果；不生成“分页约定”或“不分页”占位。
 
-使用缺少权限范围或输出语义的 API 型 Product Requirement。核对：不得发明产品决策；生成 blocked 依赖产物并返回上游补充。
+## Case 5：分页 API
 
-## Case 5：不存在的目标能力
+分别覆盖：
+- 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 定时任务
 
-## Case 6：缩小分析范围
+使用触发方式为定时任务的归档需求。核对：只生成 Dependency；故事“API 文档引用”写“`不适用；触发方式为 定时任务`”；API 映射写不适用；重点定位 scheduler、job、幂等、批次、数据和恢复测试。
 
-使用 scope 为 both 的 Product Requirement，并指定 `target=backend`。核对：输入门禁通过；只要求 BE 故事覆盖；Dependency 和适用的 API 文档使用 `analysis_scope: backend`，不强制生成前端详情。
+## Case 7：API 必要业务契约缺失
 
-## Case 7：缺少输入
+分别删除 API 型故事输出规范中的输入语义、输出语义、权限规则、业务规则、安全要求或错误与边界。核对：Product Requirement Input Validator 失败，不重新评价 AC 文案风格。
 
-分别缺少 Product Requirement 和代码仓库。核对：只生成四个固定章节的 blocked Dependency；前者使用 `source_product_requirement: none`，后者允许 `repository_root: none`；不得生成 API 文档或确定性代码位置。
+## 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 拒绝。