@tea-agent/loop-agent 0.33.1 → 0.33.3

package/skills/analyze-product-dependencies/scripts/test-validators.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 
-import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 
 const scriptDir = dirname(fileURLToPath(import.meta.url));
-const temp = mkdtempSync(join(tmpdir(), "dependency-v3-validators-"));
+const temp = mkdtempSync(join(tmpdir(), "dependency-v4-validators-"));
+process.once("exit", () => rmSync(temp, { recursive: true, force: true }));
 const repo = join(temp, "repo");
 const artifactDir = join(repo, "docs", "product-analysis", "refund-status");
 mkdirSync(artifactDir, { recursive: true });
@@ -34,15 +35,11 @@ const apiPath = join(artifactDir, "api-documentation.md");
 const dependencyPath = join(artifactDir, "dependency-analysis.md");
 
 const requirement = `---
-artifact_version: "3.0"
+artifact_version: "4.0"
 artifact_type: product-requirement
 requirement_id: refund-status
-project_root: ../../..
 requirement_status: complete
 analysis_scope: backend
-source_requirement: inline
-source_product_analysis: none
-source_clarification: none
 ---
 # Product Requirement
 ## 1. 需求概述
@@ -50,14 +47,10 @@ source_clarification: none
 ## 2. 业务目标
 - 提供可解释的退款进度。
 ## 3. 需求范围
-### 3.1 已确认需求
+### 3.1 已确认范围
 - 仅订单所属用户可查询。
 ### 3.2 非目标
 - 不修改退款流程。
-### 3.3 默认假设
-- 无。
-### 3.4 未决事项
-- 无。
 ## 4. 业务规则
 - 不得泄露其他用户订单。
 ## 5. 后端用户故事
@@ -65,7 +58,7 @@ source_clarification: none
 - 系统能力：返回指定订单的退款状态
 - 使用方：订单详情页
 - 业务价值：让用户了解退款进度
-- 触发方式：API
+- 触发方式：API（Web）
 - 验收标准：AC-BE-001
 ## 6. 后端输出规范
 ### BE-US-001 查询退款状态
@@ -87,37 +80,35 @@ Then：
 - 返回 refundStatus 和 updatedAt。
 - 查询不得修改退款记录。
 异常场景：
-- 无权访问时返回 403 且不得泄露订单详情。
+- 无权访问时返回 code=FORBIDDEN 且不得泄露订单详情。
 ## 7. 决策追溯
 - 需求直接来源于明确需求。
 `;
 
 const api = `---
-artifact_version: "3.0"
+artifact_version: "4.0"
 artifact_type: api-documentation
 requirement_id: refund-status
-project_root: ../../..
 api_status: complete
 analysis_scope: backend
-source_product_requirement: ./product-requirement.md
-repository_root: ../../..
 ---
 # API Documentation
 ## 1. 通用约定
 ### 1.1 Base URL
 - /api/v1
-### 1.2 统一响应结构
-- data 包裹成功响应。
-### 1.3 错误响应结构
+### 1.2 成功响应结构
+- code 标识结果，data 包裹成功响应。
+### 1.3 公共错误响应结构
 - code 和 message。
-### 1.4 分页约定
-- 本接口不分页。
-### 1.5 时间和标识符规范
+\`\`\`json
+{"code":"INVALID_ARGUMENT","message":"invalid argument"}
+\`\`\`
+### 1.4 时间和标识符规范
 - ISO 8601 和字符串 ID。
 ## 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 查询退款状态
 > \`GET /api/v1/orders/{orderId}/refund-status\`
@@ -134,12 +125,12 @@ repository_root: ../../..
 #### 成功响应
 - HTTP：200
 \`\`\`json
-{"data":{"refundStatus":"processing","updatedAt":"2026-01-01T00:00:00Z"}}
+{"code":"SUCCESS","data":{"refundStatus":"processing","updatedAt":"2026-01-01T00:00:00Z"}}
 \`\`\`
 #### 错误响应
 | 状态码 | 错误码 | 条件 |
 |---|---|---|
-| 403 | FORBIDDEN | 资源访问被拒绝 |
+| 200 | FORBIDDEN | 资源访问被拒绝 |
 \`\`\`json
 {"code":"FORBIDDEN","message":"forbidden"}
 \`\`\`
@@ -150,14 +141,10 @@ repository_root: ../../..
 `;
 
 const dependency = `---
-artifact_version: "3.0"
+artifact_version: "4.0"
 artifact_type: dependency-analysis
 requirement_id: refund-status
-project_root: ../../..
 analysis_scope: backend
-source_product_requirement: ./product-requirement.md
-source_api_documentation: ./api-documentation.md
-repository_root: ../../..
 analysis_status: complete
 blocked_on: none
 ---
@@ -165,6 +152,7 @@ blocked_on: none
 ## 1. 输入与代码基线
 - 需求：./product-requirement.md
 - 仓库：../../..
+- 知识检索状态：executed-no-match
 ## 2. 用户故事覆盖矩阵
 | 故事 | AC | API | 主要代码入口 | 状态 |
 |---|---|---|---|---|
@@ -183,7 +171,7 @@ blocked_on: none
 - DTO/Schema：F1 复用统一响应结构
 - 数据依赖：F3 读取退款记录
 - 权限依赖：F1 校验订单归属
-- 错误/日志/审计：F1 映射 403 和 404
+- 错误/日志/审计：F1 映射 FORBIDDEN 和 NOT_FOUND code
 - 测试落点：F1、F2 的相邻测试文件
 - 定位证据：现有订单路由调用 F2，F2 注入 F3
 - 风险：旧退款记录可能缺少 updatedAt
@@ -191,10 +179,10 @@ blocked_on: none
 ## 4. 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\` |
 ## 5. 跨故事共享依赖
 - 复用订单鉴权和统一错误结构。
-## 6. 风险与未定位项
+## 6. 跨故事风险与未定位项
 - 需要确认历史数据的 updatedAt 完整性。
 `;
 
@@ -205,48 +193,204 @@ writeFileSync(dependencyPath, dependency);
 const paginationSections = `#### Query 参数
 | 参数 | 类型 | 必填 | 允许值 | 语义 |
 |---|---|---|---|---|
-| pageSize | integer | 否 | 10 \| 20 \| 50 \| 100 | 每页条数 |
+| pageSize | integer | 否 | 10 \\| 20 \\| 50 \\| 100 | 每页条数 |
 | cursor | string | 否 | - | 下一页游标 |
 `;
-const paginatedApi = api.replace("#### 成功响应", `${paginationSections}#### 成功响应`);
+const paginatedApi = api
+  .replace("### 1.4 时间和标识符规范", "### 1.4 分页约定\n- pageSize 允许值为 10、20、50、100。\n### 1.5 时间和标识符规范")
+  .replace("#### 成功响应", `${paginationSections}#### 成功响应`);
 
 let checks = 0;
 function expectPass(name, script, args) { pass(name, run(script, args)); checks += 1; }
 function expectFail(name, script, args, message) { fail(name, run(script, args), message); checks += 1; }
 
-expectPass("valid V3 requirement input", requirementValidator, [requirementPath, "--target", "backend"]);
+expectPass("valid V4 requirement input", requirementValidator, [requirementPath, "--target", "backend"]);
+expectFail("input rejects extra frontmatter fields", requirementValidator, [variant("requirement-extra-frontmatter.md", requirement.replace("analysis_scope: backend", "analysis_scope: backend\nsource_path: /private/customer/prd.md")), "--target", "backend"], "unsupported field source_path");
+const backendStoryStart = requirement.indexOf("### BE-US-001");
+const backendSpecHeading = requirement.indexOf("## 6. 后端输出规范");
+const backendSpecStart = requirement.indexOf("### BE-US-001", backendSpecHeading);
+const backendTraceHeading = requirement.indexOf("## 7. 决策追溯");
+const duplicateAcInput = requirement
+  .slice(0, backendSpecHeading)
+  + requirement.slice(backendStoryStart, backendSpecHeading).replace("BE-US-001", "BE-US-002")
+  + requirement.slice(backendSpecHeading, backendTraceHeading)
+  + requirement.slice(backendSpecStart, backendTraceHeading).replace("BE-US-001", "BE-US-002")
+  + requirement.slice(backendTraceHeading);
+expectFail("input rejects duplicate AC IDs across stories", requirementValidator, [variant("requirement-duplicate-ac.md", duplicateAcInput), "--target", "backend"], "Duplicate acceptance criterion ID");
+expectFail("plain API trigger requires surface clarification", requirementValidator, [variant("requirement-plain-api.md", requirement.replace("API（Web）", "API"))], "API must declare Web, Remote, or Web + Remote");
+writeFileSync(requirementPath, requirement.replace("API（Web）", "API（Remote）"));
+expectPass("Remote API trigger is accepted", requirementValidator, [requirementPath, "--target", "backend"]);
+writeFileSync(requirementPath, requirement);
 expectFail("reject scope expansion", requirementValidator, [requirementPath, "--target", "both"], "not included");
 expectFail("require matching output spec", requirementValidator, [variant("requirement-no-spec.md", requirement.replace("### BE-US-001 查询退款状态\n- 输入语义", "### BE-US-002 查询退款状态\n- 输入语义"))], "Missing output specification");
 expectFail("require matching AC", requirementValidator, [variant("requirement-bad-ac.md", requirement.replace("- 验收标准：AC-BE-001", "- 验收标准：AC-BE-002"))], "must match");
+expectFail("API input requires permission semantics", requirementValidator, [variant("requirement-no-permission.md", requirement.replace("- 权限规则：仅订单所属用户\n", ""))], "API business contract is missing field 权限规则");
+writeFileSync(requirementPath, requirement.replace(/Given：[\s\S]*?异常场景：\n- 无权访问时返回 code=FORBIDDEN 且不得泄露订单详情。/, "验收说明：调用后返回可观察结果。"));
+expectPass("input validator does not recheck AC prose style", requirementValidator, [requirementPath, "--target", "backend"]);
+writeFileSync(requirementPath, requirement);
 
 expectPass("valid compact API documentation", apiValidator, [requirementPath, apiPath, "--target", "backend"]);
+expectPass("api-only validation path", apiValidator, [requirementPath, apiPath, "--target", "backend"]);
+expectFail("API rejects extra frontmatter fields", apiValidator, [requirementPath, variant("api-extra-frontmatter.md", api.replace("analysis_scope: backend", "analysis_scope: backend\nrepository_path: /private/repo")), "--target", "backend"], "unsupported field repository_path");
+expectFail("API index rejects rows without details", apiValidator, [requirementPath, variant("api-orphan-index-row.md", api.replace("| API-001 | GET /api/v1/orders/{orderId}/refund-status | getRefundStatus | 新增 |", "| API-001 | GET /api/v1/orders/{orderId}/refund-status | getRefundStatus | 新增 |\n| API-999 | DELETE /ghost | ghostDelete | 新增 |"))], "without a matching API detail");
+expectFail("API index Operation ID must match detail", apiValidator, [requirementPath, variant("api-index-operation-mismatch.md", api.replace("| API-001 | GET /api/v1/orders/{orderId}/refund-status | getRefundStatus | 新增 |", "| API-001 | GET /api/v1/orders/{orderId}/refund-status | wrongOperation | 新增 |"))], "Operation ID does not match API index");
+writeFileSync(apiPath, api.replace("### 1.4 时间和标识符规范", "### 1.4 分页约定\n- 本接口不分页。\n### 1.5 时间和标识符规范"));
+expectFail("non-paginated API rejects pagination conventions", apiValidator, [requirementPath, apiPath], "must not contain 分页约定");
+writeFileSync(apiPath, paginatedApi.replace("### 1.4 分页约定\n- pageSize 允许值为 10、20、50、100。\n", ""));
+expectFail("paginated API requires pagination conventions", apiValidator, [requirementPath, apiPath], "must contain exactly one 分页约定");
 writeFileSync(apiPath, paginatedApi);
-expectPass("valid optional page sizes", apiValidator, [requirementPath, apiPath]);
+expectPass("valid paginated API documentation", apiValidator, [requirementPath, apiPath]);
+expectFail("pagination parameter requires allowed values", apiValidator, [requirementPath, variant("api-pagination-no-values.md", paginatedApi.replace("| pageSize | integer | 否 | 10 \\| 20 \\| 50 \\| 100 | 每页条数 |", "| pageSize | integer | 否 | - | 每页条数 |"))], "must declare numeric");
+expectFail("pagination parameter values match conventions", apiValidator, [requirementPath, variant("api-pagination-convention-mismatch.md", paginatedApi.replace("pageSize 允许值为 10、20、50、100", "pageSize 允许值为 20、50、100"))], "must match 分页约定");
+const cursorOnlyApi = api.replace("#### 成功响应", "#### Query 参数\n| 参数 | 类型 | 必填 | 语义 |\n|---|---|---|---|\n| cursor | string | 否 | 下一页游标 |\n#### 成功响应");
+writeFileSync(apiPath, cursorOnlyApi);
+expectPass("cursor-only API does not require pagination conventions", apiValidator, [requirementPath, apiPath]);
+const explicitPaginationRequirement = requirement
+  .replace("- 不得泄露其他用户订单。", "- 不得泄露其他用户订单。\n- pageSize 允许值为 5、10、20。");
+writeFileSync(requirementPath, explicitPaginationRequirement);
+writeFileSync(apiPath, paginatedApi);
+expectFail("pagination values must match Product Requirement", apiValidator, [requirementPath, apiPath], "must match Product Requirement");
+writeFileSync(requirementPath, requirement);
 writeFileSync(apiPath, api);
-expectFail("pagination requires all page sizes", apiValidator, [requirementPath, variant("api-pagination-incomplete.md", paginatedApi.replace("10 | 20 | 50 | 100", "10 | 20 | 50"))], "exactly 10, 20, 50, and 100");
-expectFail("pagination page size must be optional", apiValidator, [requirementPath, variant("api-pagination-required.md", paginatedApi.replace("| pageSize | integer | 否 |", "| pageSize | integer | 是 |"))], "must be optional");
-expectFail("API index covers story", apiValidator, [requirementPath, variant("api-no-story.md", api.replace("BE-US-001 | AC-BE-001", "BE-US-999 | AC-BE-001"))], "does not cover");
-expectFail("API success JSON must parse", apiValidator, [requirementPath, variant("api-bad-json.md", api.replace("{\"data\":{\"refundStatus\":\"processing\",\"updatedAt\":\"2026-01-01T00:00:00Z\"}}", "{bad json}"))], "must be valid JSON");
+expectFail("API documentation rejects story traceability", apiValidator, [requirementPath, variant("api-story-trace.md", api.replace("| API ID | Method + Path | Operation ID | 变更类型 |", "| API ID | Method + Path | Operation ID | 用户故事 | 变更类型 |").replace("|---|---|---|---|", "|---|---|---|---|---|").replace("| API-001 | GET /api/v1/orders/{orderId}/refund-status | getRefundStatus | 新增 |", "| API-001 | GET /api/v1/orders/{orderId}/refund-status | getRefundStatus | BE-US-001 | 新增 |"))], "must not contain user-story");
+expectFail("API success JSON must parse", apiValidator, [requirementPath, variant("api-bad-json.md", api.replace("{\"code\":\"SUCCESS\",\"data\":{\"refundStatus\":\"processing\",\"updatedAt\":\"2026-01-01T00:00:00Z\"}}", "{bad json}"))], "must be valid JSON");
+expectFail("API success must use HTTP 200", apiValidator, [requirementPath, variant("api-success-201.md", api.replace("- HTTP：200", "- HTTP：201"))], "success response must use HTTP 200");
+expectFail("API error must use HTTP 200", apiValidator, [requirementPath, variant("api-error-403.md", api.replace("| 200 | FORBIDDEN |", "| 403 | FORBIDDEN |"))], "error responses must use HTTP 200");
+expectFail("API success requires top-level code", apiValidator, [requirementPath, variant("api-success-no-code.md", api.replace("{\"code\":\"SUCCESS\",\"data\":", "{\"data\":"))], "success example must contain top-level code");
+expectFail("API success and error codes differ", apiValidator, [requirementPath, variant("api-same-code.md", api.replace("\"code\":\"SUCCESS\"", "\"code\":\"FORBIDDEN\""))], "success and error codes must be different");
+expectFail("API error example code must be listed", apiValidator, [requirementPath, variant("api-error-code-unlisted.md", api.replace("{\"code\":\"FORBIDDEN\",\"message\":\"forbidden\"}", "{\"code\":\"NOT_FOUND\",\"message\":\"not found\"}"))], "error example code must be listed");
 expectFail("API does not repeat ID", apiValidator, [requirementPath, variant("api-repeat-id.md", api.replace("| Operation ID | getRefundStatus |", "| API ID | API-001 |\n| Operation ID | getRefundStatus |"))], "must not repeat API ID");
-expectFail("API rejects authentication sections", apiValidator, [requirementPath, variant("api-auth.md", api.replace("### 1.2 统一响应结构", "### 1.2 认证方式\n- Bearer token\n### 1.3 统一响应结构"))], "must not contain authentication");
+expectFail("API omits empty optional parameter sections", apiValidator, [requirementPath, variant("api-empty-query.md", api.replace("#### 成功响应", "#### Query 参数\n\n#### 成功响应"))], "must omit empty Query 参数");
+expectFail("API rejects authentication sections", apiValidator, [requirementPath, variant("api-auth.md", api.replace("### 1.2 成功响应结构", "### 1.2 认证方式\n- Bearer token\n### 1.3 成功响应结构"))], "must not contain authentication");
 expectFail("API rejects reuse-check output", apiValidator, [requirementPath, variant("api-reuse-check.md", api.replace("## 4. 数据模型", "## 4. 数据模型\n### 4.1 复用检查"))], "must not contain reuse-check");
 
-expectPass("valid V3 dependency analysis", dependencyValidator, [requirementPath, dependencyPath, apiPath, "--target", "backend"]);
+expectPass("valid V4 dependency analysis", dependencyValidator, [requirementPath, dependencyPath, apiPath, "--target", "backend"]);
+expectFail("dependency rejects extra frontmatter fields", dependencyValidator, [requirementPath, variant("dependency-extra-frontmatter.md", dependency.replace("blocked_on: none", "blocked_on: none\nrepository_path: /private/repo")), apiPath, "--target", "backend"], "unsupported field repository_path");
+const dependencyDetailStart = dependency.indexOf("### BE-US-001");
+const dependencyDetailEnd = dependency.indexOf("## 4. API 实现映射");
+const duplicateDependencyDetail = dependency.slice(0, dependencyDetailEnd)
+  + dependency.slice(dependencyDetailStart, dependencyDetailEnd)
+  + dependency.slice(dependencyDetailEnd);
+expectFail("dependency rejects duplicate story details", dependencyValidator, [requirementPath, variant("dependency-duplicate-detail.md", duplicateDependencyDetail), apiPath, "--target", "backend"], "duplicate 后端依赖详情");
+writeFileSync(requirementPath, requirement.replace("API（Web）", "API（Web + Remote）"));
+expectPass("Web + Remote API trigger is accepted", requirementValidator, [requirementPath, "--target", "backend"]);
+expectFail("Web + Remote requires two API references", dependencyValidator, [requirementPath, dependencyPath, apiPath, "--target", "backend"], "must reference at least two API IDs");
+writeFileSync(requirementPath, requirement);
+writeFileSync(dependencyPath, dependency.replace("- 知识检索状态：executed-no-match", "- 知识检索状态：executed-hit\n- KB-EVIDENCE-001：当前有效 Web API 规范要求统一响应外壳。"));
+expectPass("dependency accepts executed-hit with KB evidence", dependencyValidator, [requirementPath, dependencyPath, apiPath, "--target", "backend"]);
+writeFileSync(dependencyPath, dependency);
+expectFail("dependency requires explicit knowledge status", dependencyValidator, [requirementPath, variant("dependency-kb-no-status.md", dependency.replace("- 知识检索状态：executed-no-match\n", "")), apiPath], "must contain exactly one knowledge status");
+expectFail("dependency rejects not-executed", dependencyValidator, [requirementPath, variant("dependency-kb-not-executed.md", dependency.replace("executed-no-match", "not-executed")), apiPath], "must not use not-executed");
+expectFail("dependency executed-hit requires KB evidence", dependencyValidator, [requirementPath, variant("dependency-kb-hit-no-evidence.md", dependency.replace("executed-no-match", "executed-hit")), apiPath], "must contain at least one KB-EVIDENCE");
+expectFail("dependency KB evidence requires executed-hit", dependencyValidator, [requirementPath, variant("dependency-kb-evidence-wrong-status.md", dependency.replace("- 知识检索状态：executed-no-match", "- 知识检索状态：executed-no-match\n- KB-EVIDENCE-001：不应存在。")), apiPath], "require executed-hit");
+expectFail("dependency unavailable requires user skip confirmation", dependencyValidator, [requirementPath, variant("dependency-kb-unavailable-no-confirmation.md", dependency.replace("executed-no-match", "unavailable")), apiPath], "用户处置：已确认跳过知识库");
+writeFileSync(dependencyPath, dependency.replace("- 知识检索状态：executed-no-match", "- 知识检索状态：unavailable\n- 用户处置：已确认跳过知识库"));
+expectPass("dependency unavailable accepts user skip confirmation", dependencyValidator, [requirementPath, dependencyPath, apiPath, "--target", "backend"]);
+writeFileSync(dependencyPath, dependency);
 expectFail("impact files are required", dependencyValidator, [requirementPath, variant("dependency-no-impact.md", dependency.replace(/- 影响文件：[\s\S]*?- 路由\/入口：/, "- 路由/入口：")), apiPath], "missing field 影响文件");
 expectFail("impact file IDs must be declared", dependencyValidator, [requirementPath, variant("dependency-bad-file-ref.md", dependency.replace("- Service/领域逻辑：F2", "- Service/领域逻辑：F9")), apiPath], "undeclared impact file F9");
 expectFail("dependency rejects trace summary", dependencyValidator, [requirementPath, variant("dependency-trace.md", dependency + "\n## 7. 追溯汇总\n- BE-US-001。\n"), apiPath], "must not contain 分析范围 or 追溯汇总");
-expectFail("API mapping keeps operation", dependencyValidator, [requirementPath, variant("dependency-no-operation.md", dependency.replace("getRefundStatus", "missingOperation")), apiPath], "missing Operation ID getRefundStatus");
+expectFail("API mapping keeps operation", dependencyValidator, [requirementPath, variant("dependency-no-operation.md", dependency.replace("| API-001 | getRefundStatus |", "| API-001 | missingOperation |")), apiPath], "missing Operation ID getRefundStatus");
+expectFail("API mapping requires concrete code entry", dependencyValidator, [requirementPath, variant("dependency-no-code-entry.md", dependency.replace("`src/refund/refund.controller.ts#getRefundStatus`", "未定位")), apiPath], "must map to a concrete code entry");
+expectFail("API mapping rejects story-local file ID as code entry", dependencyValidator, [requirementPath, variant("dependency-local-file-id-entry.md", dependency.replace("`src/refund/refund.controller.ts#getRefundStatus`", "F1")), apiPath], "must map to a concrete code entry");
 expectFail("dependency AC matches requirement", dependencyValidator, [requirementPath, variant("dependency-bad-ac.md", dependency.replace("- 验收标准：AC-BE-001", "- 验收标准：AC-BE-002")), apiPath], "must match Product Requirement");
+expectFail("dependency rejects copied API contract", dependencyValidator, [requirementPath, variant("dependency-api-contract.md", dependency.replace("## 5. 跨故事共享依赖", "#### Query 参数\n| pageSize | integer |\n## 5. 跨故事共享依赖")), apiPath], "must not copy full API contract");
+expectFail("local risk must not be duplicated globally", dependencyValidator, [requirementPath, variant("dependency-duplicate-risk.md", dependency.replace("- 需要确认历史数据的 updatedAt 完整性。", "- 旧退款记录可能缺少 updatedAt。")), apiPath], "risk is duplicated");
+
+const frontendRequirement = `---
+artifact_version: "4.0"
+artifact_type: product-requirement
+requirement_id: refund-status
+requirement_status: complete
+analysis_scope: frontend
+---
+# Product Requirement
+## 1. 前端用户故事
+### FE-US-001 查看订单
+- 验收标准：AC-FE-001
+## 2. 前端输出规范
+### FE-US-001 查看订单
+- 页面路由：/account/orders
+#### AC-FE-001 展示订单
+- 用户可以看到订单。
+`;
+const frontendDependency = `---
+artifact_version: "4.0"
+artifact_type: dependency-analysis
+requirement_id: refund-status
+analysis_scope: frontend
+analysis_status: complete
+blocked_on: none
+---
+# Dependency Analysis
+## 1. 输入与代码基线
+- 已读取需求和仓库。
+- 知识检索状态：executed-no-match
+## 2. 用户故事覆盖矩阵
+| 故事 | AC | API | 状态 |
+|---|---|---|---|
+| FE-US-001 | AC-FE-001 | 不适用 | confirmed |
+## 3. 前端依赖详情
+### FE-US-001 查看订单
+- 验收标准：AC-FE-001
+- API 文档引用：不适用；本故事无 HTTP API 依赖
+- 影响文件：
+  - F1 modify \`src/pages/orders.tsx\`：展示订单
+- 页面/路由：
+  - 目标路由：/account/orders
+  - F1 作为页面组件
+- 组件：F1
+- 状态：F1
+- API client/类型：不适用；本故事无 HTTP API 依赖
+- 状态与边界落点：F1
+- 定位证据：F1 已注册为订单页
+- 风险：无
+- 置信度：high
+## 4. API 实现映射
+- 不适用。本次需求不涉及 HTTP API。
+## 5. 跨故事共享依赖
+- 无。
+## 6. 跨故事风险与未定位项
+- 无。
+`;
+writeFileSync(requirementPath, frontendRequirement);
+writeFileSync(dependencyPath, frontendDependency);
+expectPass("frontend input accepts required downstream contract", requirementValidator, [requirementPath, "--target", "frontend"]);
+expectPass("frontend dependency preserves target route and N/A API reason", dependencyValidator, [requirementPath, dependencyPath, "--target", "frontend"]);
+expectFail("frontend dependency rejects route drift", dependencyValidator, [requirementPath, variant("dependency-route-drift.md", frontendDependency.replaceAll("/account/orders", "/orders")), "--target", "frontend"], "page route must match");
+expectFail("frontend dependency requires N/A API reason", dependencyValidator, [requirementPath, variant("dependency-api-na-reason.md", frontendDependency.replace("- API 文档引用：不适用；本故事无 HTTP API 依赖", "- API 文档引用：不适用")), "--target", "frontend"], "must list Method + Path or use 不适用");
+const externalApiPath = join(temp, "shared-api.md");
+writeFileSync(externalApiPath, "# Shared API\n- GET /order/list\n- POST /unrelated/create\n");
+const frontendWithExternalApi = frontendDependency
+  .replace("| FE-US-001 | AC-FE-001 | 不适用 | confirmed |", "| FE-US-001 | AC-FE-001 | GET /order/list | confirmed |")
+  .replace("- API 文档引用：不适用；本故事无 HTTP API 依赖", "- API 文档引用：GET /order/list")
+  .replace("- 不适用。本次需求不涉及 HTTP API。", "- GET /order/list");
+writeFileSync(dependencyPath, frontendWithExternalApi);
+expectPass("frontend accepts arbitrary external API path and Method + Path only", dependencyValidator, [requirementPath, dependencyPath, "--api-doc", externalApiPath, "--target", "frontend"]);
+expectFail("frontend Method + Path requires external API input", dependencyValidator, [requirementPath, dependencyPath, "--target", "frontend"], "no --api-doc input");
+const missingExternalApiPath = join(temp, "external-api-missing.md");
+writeFileSync(missingExternalApiPath, "# API\n- POST /other\n");
+expectFail("frontend rejects missing external Method + Path", dependencyValidator, [requirementPath, dependencyPath, "--api-doc", missingExternalApiPath, "--target", "frontend"], "not found in external API Documentation");
+writeFileSync(requirementPath, requirement);
+writeFileSync(dependencyPath, dependency);
+
+const nonApiRequirement = requirement.replace("- 触发方式：API（Web）", "- 触发方式：定时任务");
+const nonApiDependency = dependency
+  .replace("| BE-US-001 | AC-BE-001 | API-001 | F1 | confirmed |", "| BE-US-001 | AC-BE-001 | 不适用 | F1 | confirmed |")
+  .replace("- API 文档引用：API-001", "- API 文档引用：不适用；触发方式为 定时任务")
+  .replace(/\| API-001 \| getRefundStatus \| GET \/api\/v1\/orders\/\{orderId\}\/refund-status \| [^\n]+\|/, "- 不适用。本次需求不涉及 HTTP API。");
+writeFileSync(requirementPath, nonApiRequirement);
+writeFileSync(dependencyPath, nonApiDependency);
+expectPass("non-API backend uses reasoned N/A reference", dependencyValidator, [requirementPath, dependencyPath, "--target", "backend"]);
+expectFail("non-API backend rejects unexplained N/A", dependencyValidator, [requirementPath, variant("dependency-non-api-na.md", nonApiDependency.replace("- API 文档引用：不适用；触发方式为 定时任务", "- API 文档引用：不适用")), "--target", "backend"], "must use 不适用；触发方式为");
+writeFileSync(requirementPath, requirement);
+writeFileSync(dependencyPath, dependency);
 
 const blocked = `---
-artifact_version: "3.0"
+artifact_version: "4.0"
 artifact_type: dependency-analysis
 requirement_id: refund-status
-project_root: ../../..
 analysis_scope: backend
-source_product_requirement: none
-source_api_documentation: none
-repository_root: none
 analysis_status: blocked
 blocked_on: requirement-missing repository-missing
 ---
@@ -262,6 +406,55 @@ blocked_on: requirement-missing repository-missing
 `;
 writeFileSync(dependencyPath, blocked);
 expectPass("valid blocked dependency", dependencyValidator, ["none", dependencyPath, "--target", "backend"]);
+
+const incompleteContractBlocked = `---
+artifact_version: "4.0"
+artifact_type: dependency-analysis
+requirement_id: refund-status
+analysis_scope: backend
+analysis_status: blocked
+blocked_on: api-business-contract-incomplete
+---
+# Dependency Analysis
+## 1. 分析范围
+- backend
+## 2. 输入与代码基线
+- 已读取 Product Requirement 与仓库。
+## 3. 阻断原因
+- API 业务契约不完整，缺少权限或安全边界。
+## 4. 恢复条件
+- 返回上游需求 skill 补齐 API 业务契约后重试。
+`;
+writeFileSync(requirementPath, requirement);
+writeFileSync(dependencyPath, incompleteContractBlocked);
+expectPass("blocked on api-business-contract-incomplete", dependencyValidator, [requirementPath, dependencyPath, "--target", "backend"]);
+
+const v2NonApiRequirement = `---
+artifact_version: "2.0"
+artifact_type: product-requirement
+requirement_id: refund-status
+requirement_status: complete
+analysis_scope: backend
+---
+# Product Requirement
+## 1. 后端用户故事
+### BE-US-001 归档通知
+- 触发方式：定时任务
+- 验收标准：AC-BE-001
+#### AC-BE-001 归档完成
+- 任务可重复执行且不重复归档。
+`;
+const v2ApiRequirement = v2NonApiRequirement
+  .replace("### BE-US-001 归档通知", "### BE-US-001 查询退款状态")
+  .replace("- 触发方式：定时任务", "- 触发方式：API")
+  .replace("#### AC-BE-001 归档完成\n- 任务可重复执行且不重复归档。", "#### AC-BE-001 返回退款状态\n- 用户可查询退款状态。");
+writeFileSync(requirementPath, v2NonApiRequirement);
+expectPass("V2 non-API requirement input remains accepted", requirementValidator, [requirementPath, "--target", "backend"]);
+writeFileSync(requirementPath, v2ApiRequirement);
+expectFail("V2 API requirement must upgrade to V4", requirementValidator, [requirementPath, "--target", "backend"], "must be upgraded to V4");
+
+writeFileSync(requirementPath, requirement);
 writeFileSync(dependencyPath, dependency);
+writeFileSync(apiPath, api);
 
-console.log(`Dependency V3 validator matrix passed: ${checks} checks.`);
+console.log(`Dependency V4 validator matrix passed: ${checks} checks.`);