@tea-agent/loop-agent 0.13.0-alpha.0 → 0.13.0

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

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+
+import { mkdirSync, mkdtempSync, 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 repo = join(temp, "repo");
+const artifactDir = join(repo, "docs", "product-analysis", "refund-status");
+mkdirSync(artifactDir, { recursive: true });
+const requirementValidator = join(scriptDir, "validate-product-requirement-input.mjs");
+const apiValidator = join(scriptDir, "validate-api-documentation.mjs");
+const dependencyValidator = join(scriptDir, "validate-dependency-analysis.mjs");
+
+const run = (script, args) => spawnSync(process.execPath, [script, ...args], { encoding: "utf8" });
+function pass(name, result) {
+  if (result.status !== 0) throw new Error(`${name} should pass:\n${result.stderr}${result.stdout}`);
+}
+function fail(name, result, message) {
+  if (result.status === 0) throw new Error(`${name} should fail.`);
+  if (message && !`${result.stderr}${result.stdout}`.includes(message)) throw new Error(`${name} should mention ${message}:\n${result.stderr}${result.stdout}`);
+}
+function variant(name, text) {
+  const path = join(artifactDir, name);
+  writeFileSync(path, text);
+  return path;
+}
+
+const requirementPath = join(artifactDir, "product-requirement.md");
+const apiPath = join(artifactDir, "api-documentation.md");
+const dependencyPath = join(artifactDir, "dependency-analysis.md");
+
+const requirement = `---
+artifact_version: "3.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. 需求概述
+订单所属用户可以查询退款状态。
+## 2. 业务目标
+- 提供可解释的退款进度。
+## 3. 需求范围
+### 3.1 已确认需求
+- 仅订单所属用户可查询。
+### 3.2 非目标
+- 不修改退款流程。
+### 3.3 默认假设
+- 无。
+### 3.4 未决事项
+- 无。
+## 4. 业务规则
+- 不得泄露其他用户订单。
+## 5. 后端用户故事
+### BE-US-001 查询退款状态
+- 系统能力：返回指定订单的退款状态
+- 使用方：订单详情页
+- 业务价值：让用户了解退款进度
+- 触发方式：API
+- 验收标准：AC-BE-001
+## 6. 后端输出规范
+### BE-US-001 查询退款状态
+- 输入语义：当前用户和订单 ID
+- 输出语义：退款状态、步骤和更新时间
+- 数据读写：只读订单及退款记录
+- 权限规则：仅订单所属用户
+- 业务规则：按最新退款记录返回
+- 安全要求：不得泄露内部错误或其他用户数据
+- 幂等与并发：重复查询不修改数据
+- 错误与边界：订单不存在返回标准错误
+#### AC-BE-001 返回退款状态
+Given：
+- 请求用户已认证且拥有目标订单。
+When：
+- 用户请求目标订单退款状态。
+Then：
+- HTTP 状态码为 200。
+- 返回 refundStatus 和 updatedAt。
+- 查询不得修改退款记录。
+异常场景：
+- 无权访问时返回 403 且不得泄露订单详情。
+## 7. 决策追溯
+- 需求直接来源于明确需求。
+`;
+
+const api = `---
+artifact_version: "3.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 错误响应结构
+- code 和 message。
+### 1.4 分页约定
+- 本接口不分页。
+### 1.5 时间和标识符规范
+- 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 | 新增 |
+## 3. API 详情
+### API-001 查询退款状态
+> \`GET /api/v1/orders/{orderId}/refund-status\`
+#### 基本信息
+| 字段 | 值 |
+|---|---|
+| Operation ID | getRefundStatus |
+| 变更类型 | 新增 |
+| 幂等性 | 只读请求天然幂等 |
+#### Path 参数
+| 参数 | 类型 | 必填 | 语义 |
+|---|---|---|---|
+| orderId | string | 是 | 订单标识 |
+#### 成功响应
+- HTTP：200
+\`\`\`json
+{"data":{"refundStatus":"processing","updatedAt":"2026-01-01T00:00:00Z"}}
+\`\`\`
+#### 错误响应
+| 状态码 | 错误码 | 条件 |
+|---|---|---|
+| 403 | FORBIDDEN | 资源访问被拒绝 |
+\`\`\`json
+{"code":"FORBIDDEN","message":"forbidden"}
+\`\`\`
+## 4. 数据模型
+- RefundStatus 包含 refundStatus 和 updatedAt。
+## 5. 错误码
+- FORBIDDEN：请求被拒绝。
+`;
+
+const dependency = `---
+artifact_version: "3.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
+---
+# Dependency Analysis
+## 1. 输入与代码基线
+- 需求：./product-requirement.md
+- 仓库：../../..
+## 2. 用户故事覆盖矩阵
+| 故事 | AC | API | 主要代码入口 | 状态 |
+|---|---|---|---|---|
+| BE-US-001 | AC-BE-001 | API-001 | F1 | confirmed |
+## 3. 后端依赖详情
+### BE-US-001 查询退款状态
+- 验收标准：AC-BE-001
+- API 文档引用：API-001
+- 影响文件：
+  - F1 modify \`src/refund/refund.controller.ts\`：增加查询入口
+  - F2 modify \`src/refund/refund.service.ts\`：组合退款状态
+  - F3 reuse \`src/refund/refund.repository.ts\`：读取退款记录
+- 路由/入口：F1 注册退款状态路由
+- Controller/Handler：F1 校验身份和订单 ID
+- Service/领域逻辑：F2 组合状态和更新时间
+- DTO/Schema：F1 复用统一响应结构
+- 数据依赖：F3 读取退款记录
+- 权限依赖：F1 校验订单归属
+- 错误/日志/审计：F1 映射 403 和 404
+- 测试落点：F1、F2 的相邻测试文件
+- 定位证据：现有订单路由调用 F2，F2 注入 F3
+- 风险：旧退款记录可能缺少 updatedAt
+- 置信度：high
+## 4. API 实现映射
+| API | Operation ID | 方法与路径 | 代码入口 |
+|---|---|---|---|
+| API-001 | getRefundStatus | GET /api/v1/orders/{orderId}/refund-status | F1 |
+## 5. 跨故事共享依赖
+- 复用订单鉴权和统一错误结构。
+## 6. 风险与未定位项
+- 需要确认历史数据的 updatedAt 完整性。
+`;
+
+writeFileSync(requirementPath, requirement);
+writeFileSync(apiPath, api);
+writeFileSync(dependencyPath, dependency);
+
+const paginationSections = `#### Query 参数
+| 参数 | 类型 | 必填 | 允许值 | 语义 |
+|---|---|---|---|---|
+| pageSize | integer | 否 | 10 \| 20 \| 50 \| 100 | 每页条数 |
+| cursor | string | 否 | - | 下一页游标 |
+`;
+const paginatedApi = api.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"]);
+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");
+
+expectPass("valid compact API documentation", apiValidator, [requirementPath, apiPath, "--target", "backend"]);
+writeFileSync(apiPath, paginatedApi);
+expectPass("valid optional page sizes", apiValidator, [requirementPath, apiPath]);
+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 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 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"]);
+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("dependency AC matches requirement", dependencyValidator, [requirementPath, variant("dependency-bad-ac.md", dependency.replace("- 验收标准：AC-BE-001", "- 验收标准：AC-BE-002")), apiPath], "must match Product Requirement");
+
+const blocked = `---
+artifact_version: "3.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
+---
+# Dependency Analysis
+## 1. 分析范围
+- backend
+## 2. 输入与代码基线
+- 未提供需求和仓库。
+## 3. 阻断原因
+- 缺少 Product Requirement。
+## 4. 恢复条件
+- 提供 complete Product Requirement 和仓库。
+`;
+writeFileSync(dependencyPath, blocked);
+expectPass("valid blocked dependency", dependencyValidator, ["none", dependencyPath, "--target", "backend"]);
+writeFileSync(dependencyPath, dependency);
+
+console.log(`Dependency V3 validator matrix passed: ${checks} checks.`);

package/skills/analyze-product-dependencies/scripts/validate-api-documentation.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+import { existsSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { apiBlocks, assertHeadings, field, headings, load, metadata, print, scopeIncludes, section, storyBlocks, tableValue, validateArtifactLocation } from "./validation-helpers.mjs";
+
+const args = process.argv.slice(2);
+const targetIndex = args.indexOf("--target");
+const expectedTarget = targetIndex >= 0 ? args[targetIndex + 1] : undefined;
+const positional = args.filter((_, index) => targetIndex < 0 || (index !== targetIndex && index !== targetIndex + 1));
+if (positional.length < 2) {
+  console.error("Usage: node validate-api-documentation.mjs <product-requirement.md> <api-documentation.md> [--target backend|both]");
+  process.exit(2);
+}
+let requirement, api;
+try { requirement = load(positional[0], "Product Requirement"); api = load(positional[1], "API Documentation"); }
+catch (error) { console.error(error.message); process.exit(2); }
+
+const errors = [];
+validateArtifactLocation(api, errors, "api-documentation.md");
+const scope = metadata(api.text, "analysis_scope");
+const upstreamScope = metadata(requirement.text, "analysis_scope");
+if (metadata(api.text, "artifact_version") !== "3.0") errors.push("artifact_version must be 3.0.");
+if (metadata(api.text, "artifact_type") !== "api-documentation") errors.push("artifact_type must be api-documentation.");
+if (metadata(api.text, "api_status") !== "complete") errors.push("api_status must be complete.");
+if (!["backend", "both"].includes(scope)) errors.push("analysis_scope must be backend or both for API Documentation.");
+if (targetIndex >= 0 && !["backend", "both"].includes(expectedTarget)) errors.push("--target must be backend or both for API Documentation.");
+else if (expectedTarget && scope !== expectedTarget) errors.push(`analysis_scope ${scope} does not match requested target ${expectedTarget}.`);
+if (!scopeIncludes(upstreamScope, scope)) errors.push("analysis_scope must be included in Product Requirement scope.");
+if (metadata(api.text, "requirement_id") !== metadata(requirement.text, "requirement_id")) errors.push("requirement_id must match Product Requirement.");
+const source = metadata(api.text, "source_product_requirement");
+if (!source || resolve(dirname(api.path), source) !== requirement.path) errors.push("source_product_requirement must reference the supplied Product Requirement.");
+if (dirname(requirement.path) !== dirname(api.path)) errors.push("API Documentation and Product Requirement must be in the same requirement directory.");
+const repo = metadata(api.text, "repository_root");
+const repoPath = repo ? resolve(dirname(api.path), repo) : "";
+if (!repoPath || !existsSync(repoPath) || !statSync(repoPath).isDirectory()) errors.push("repository_root must be an existing readable directory.");
+const projectRoot = resolve(dirname(api.path), metadata(api.text, "project_root") ?? "");
+if (repoPath && projectRoot && repoPath !== projectRoot) errors.push("repository_root must resolve to project_root.");
+
+assertHeadings(api.text, 2, ["通用约定", "API 索引", "API 详情", "数据模型", "错误码"], errors, "API Documentation");
+const conventions = section(api.text, 2, "通用约定") ?? "";
+assertHeadings(conventions, 3, ["Base URL", "统一响应结构", "错误响应结构", "分页约定", "时间和标识符规范"], errors, "通用约定");
+if (/(?:认证方式|认证要求|鉴权方式|鉴权要求|权限要求|权限规则|访问控制要求|Authorization|Bearer|X-API-Key|access[_-]?token|id[_-]?token|业务规则|业务逻辑|实现逻辑|处理逻辑|分支逻辑|数据读写逻辑|实现算法)/i.test(api.text)) errors.push("API Documentation must not contain authentication, permission, business-rule, or implementation-logic content.");
+if (/(?:复用检查|通用定义复用)/.test(api.text)) errors.push("API Documentation must not contain reuse-check sections or search evidence.");
+const index = section(api.text, 2, "API 索引") ?? "";
+const blocks = apiBlocks(api.text);
+if (!blocks.length) errors.push("API Documentation must contain at least one API-* detail.");
+const ids = new Set();
+const operations = new Set();
+for (const block of blocks) {
+  if (ids.has(block.id)) errors.push(`Duplicate API ID: ${block.id}.`);
+  ids.add(block.id);
+  const operation = tableValue(block.text, "Operation ID");
+  if (!operation) errors.push(`${block.id} is missing Operation ID.`);
+  else if (operations.has(operation)) errors.push(`Duplicate Operation ID: ${operation}.`);
+  else operations.add(operation);
+  for (const name of ["Operation ID", "变更类型", "幂等性"]) if (!tableValue(block.text, name)) errors.push(`${block.id} is missing basic information field ${name}.`);
+  if (tableValue(block.text, "API ID")) errors.push(`${block.id} basic information must not repeat API ID.`);
+  if (tableValue(block.text, "变更类型") && !["新增", "修改", "复用"].includes(tableValue(block.text, "变更类型"))) errors.push(`${block.id} 变更类型 is invalid.`);
+  const signature = block.text.match(/^>\s*`(GET|POST|PUT|PATCH|DELETE)\s+(\/[^`]+)`/m);
+  if (!signature) errors.push(`${block.id} is missing a Swagger-style method and path signature.`);
+  for (const title of ["基本信息", "成功响应", "错误响应"]) if (!headings(block.text, 4).some((item) => item.title.trim() === title)) errors.push(`${block.id} is missing section ${title}.`);
+  const query = section(block.text, 4, "Query 参数") ?? "";
+  if (/\b(?:pageSize|page_size|limit|cursor|page)\b/i.test(query)) {
+    const pageSizeRow = query.split(/\r?\n/).find((line) => /^\|\s*(?:pageSize|page_size|limit)\s*\|/i.test(line));
+    if (!pageSizeRow) errors.push(`${block.id} paginated API must define an optional page-size parameter.`);
+    else {
+      if (!/^\|\s*(?:pageSize|page_size|limit)\s*\|\s*[^|]+\|\s*(?:否|可选)\s*\|/i.test(pageSizeRow)) errors.push(`${block.id} page-size parameter must be optional.`);
+      const values = [...new Set(pageSizeRow.match(/\b\d+\b/g) ?? [])].sort((a, b) => Number(a) - Number(b));
+      if (values.join(",") !== "10,20,50,100") errors.push(`${block.id} page-size values must be exactly 10, 20, 50, and 100.`);
+    }
+  }
+  if (signature) {
+    const parameters = signature[2].match(/\{([^}]+)\}/g) ?? [];
+    const pathSection = section(block.text, 4, "Path 参数") ?? "";
+    if (parameters.length && !pathSection) errors.push(`${block.id} path template requires Path 参数.`);
+    for (const parameter of parameters) {
+      const name = parameter.slice(1, -1);
+      if (!new RegExp(`^\\|\\s*${name}\\s*\\|`, "m").test(pathSection)) errors.push(`${block.id} path parameter ${name} is not documented.`);
+    }
+  }
+  const success = section(block.text, 4, "成功响应") ?? "";
+  const error = section(block.text, 4, "错误响应") ?? "";
+  if (!/HTTP(?: 状态码)?[：:]\s*2\d\d/.test(success)) errors.push(`${block.id} must define a 2xx success response.`);
+  if (!/^\|\s*[45]\d\d\s*\|/m.test(error)) errors.push(`${block.id} must define at least one 4xx or 5xx error response.`);
+  for (const [content, label] of [[success, "success"], [error, "error"]]) {
+    const example = content.match(/```json\s*([\s\S]*?)```/)?.[1];
+    if (!example) errors.push(`${block.id} must include a JSON ${label} example.`);
+    else try { JSON.parse(example); } catch { errors.push(`${block.id} ${label} example must be valid JSON.`); }
+  }
+  if (!index.includes(block.id)) errors.push(`${block.id} is missing from API index.`);
+  if (operation && !index.includes(operation)) errors.push(`${block.id} Operation ID is missing from API index.`);
+  if (signature && !index.includes(`${signature[1]} ${signature[2]}`)) errors.push(`${block.id} method and path are missing from API index.`);
+}
+
+const requiredApiStories = storyBlocks(section(requirement.text, 2, "后端用户故事"), "BE-US").filter((story) => /\bAPI\b/i.test(field(story.text, "触发方式") ?? ""));
+for (const story of requiredApiStories) {
+  if (!index.includes(story.id)) errors.push(`API index does not cover API-triggered story ${story.id}.`);
+  for (const ac of field(story.text, "验收标准")?.match(/AC-BE-\d{3,}/g) ?? []) if (!index.includes(ac)) errors.push(`API index does not trace ${ac}.`);
+}
+print("API Documentation", api.path, errors);

package/skills/analyze-product-dependencies/scripts/validate-dependency-analysis.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+import { existsSync, statSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { apiBlocks, assertHeadings, canonical, field, fieldBlock, headings, load, metadata, print, scopeIncludes, section, storyBlocks, tableValue, validateArtifactLocation } from "./validation-helpers.mjs";
+
+const args = process.argv.slice(2);
+const targetIndex = args.indexOf("--target");
+const expectedTarget = targetIndex >= 0 ? args[targetIndex + 1] : undefined;
+const positional = args.filter((_, index) => targetIndex < 0 || (index !== targetIndex && index !== targetIndex + 1));
+const [requirementArg, dependencyArg, apiArg] = positional;
+if (!requirementArg || !dependencyArg) {
+  console.error("Usage: node validate-dependency-analysis.mjs <product-requirement.md|none> <dependency-analysis.md> [api-documentation.md] [--target frontend|backend|both]");
+  process.exit(2);
+}
+let requirement, dependency, api;
+try {
+  if (requirementArg !== "none") requirement = load(requirementArg, "Product Requirement");
+  dependency = load(dependencyArg, "Dependency Analysis");
+  if (apiArg) api = load(apiArg, "API Documentation");
+} catch (error) { console.error(error.message); process.exit(2); }
+
+const errors = [];
+validateArtifactLocation(dependency, errors, "dependency-analysis.md");
+const scope = metadata(dependency.text, "analysis_scope");
+const status = metadata(dependency.text, "analysis_status");
+const blockedOn = metadata(dependency.text, "blocked_on") ?? "";
+const blockedReasons = blockedOn.split(/[\s,，]+/).filter(Boolean);
+const source = metadata(dependency.text, "source_product_requirement");
+const sourceApi = metadata(dependency.text, "source_api_documentation");
+const repo = metadata(dependency.text, "repository_root");
+const repoPath = repo && repo !== "none" ? resolve(dirname(dependency.path), repo) : "";
+const repoExists = Boolean(repoPath && existsSync(repoPath) && statSync(repoPath).isDirectory());
+const projectRoot = resolve(dirname(dependency.path), metadata(dependency.text, "project_root") ?? "");
+
+if (metadata(dependency.text, "artifact_version") !== "3.0") errors.push("artifact_version must be 3.0.");
+if (metadata(dependency.text, "artifact_type") !== "dependency-analysis") errors.push("artifact_type must be dependency-analysis.");
+if (!["frontend", "backend", "both"].includes(scope)) errors.push("analysis_scope must be frontend, backend, or both.");
+if (targetIndex >= 0 && !["frontend", "backend", "both"].includes(expectedTarget)) errors.push("--target must be frontend, backend, or both.");
+else if (expectedTarget && scope !== expectedTarget) errors.push(`analysis_scope ${scope} does not match requested target ${expectedTarget}.`);
+if (!["complete", "blocked"].includes(status)) errors.push("analysis_status must be complete or blocked.");
+
+function validateRequirementLink({ allowScopeMismatch = false } = {}) {
+  if (!requirement) return;
+  if (basename(requirement.path) !== "product-requirement.md") errors.push("Product Requirement filename must be product-requirement.md.");
+  if (!allowScopeMismatch && !scopeIncludes(metadata(requirement.text, "analysis_scope"), scope)) errors.push("analysis_scope must be included in Product Requirement scope.");
+  if (metadata(dependency.text, "requirement_id") !== metadata(requirement.text, "requirement_id")) errors.push("requirement_id must match Product Requirement.");
+  if (!source || resolve(dirname(dependency.path), source) !== requirement.path) errors.push("source_product_requirement must reference the supplied Product Requirement.");
+  if (dirname(requirement.path) !== dirname(dependency.path)) errors.push("Dependency Analysis and Product Requirement must be in the same requirement directory.");
+}
+
+if (status === "blocked") {
+  const allowed = new Set(["requirement-missing", "requirement-invalid", "requirement-not-complete", "repository-missing", "repository-unreadable", "scope-mismatch", "missing-stories", "missing-acceptance", "api-business-contract-incomplete"]);
+  if (!blockedReasons.length || blockedOn === "none") errors.push("blocked analysis must declare blocked_on reasons.");
+  for (const reason of blockedReasons) if (!allowed.has(reason)) errors.push(`Unknown blocked_on reason: ${reason}.`);
+  if (requirement) validateRequirementLink({ allowScopeMismatch: blockedReasons.includes("scope-mismatch") });
+  else {
+    if (!blockedReasons.includes("requirement-missing")) errors.push("A missing Product Requirement requires blocked_on: requirement-missing.");
+    if (source !== "none") errors.push("Missing Product Requirement must use source_product_requirement: none.");
+  }
+  if (!blockedReasons.some((reason) => ["repository-missing", "repository-unreadable"].includes(reason)) && !repoExists) errors.push("repository_root must be readable unless blocked on repository availability.");
+  if (sourceApi !== "none") errors.push("Blocked Dependency Analysis must use source_api_documentation: none.");
+  const required = ["分析范围", "输入与代码基线", "阻断原因", "恢复条件"];
+  assertHeadings(dependency.text, 2, required, errors, "Blocked Dependency Analysis");
+  for (const heading of headings(dependency.text, 2)) if (!required.includes(canonical(heading.title))) errors.push(`Blocked Dependency Analysis must not contain section ${canonical(heading.title)}.`);
+  print("Dependency Analysis", dependency.path, errors);
+  process.exit(0);
+}
+
+if (!requirement) errors.push("Complete Dependency Analysis requires Product Requirement input.");
+else validateRequirementLink();
+if (blockedOn !== "none") errors.push("complete analysis must use blocked_on: none.");
+if (!repoExists) errors.push("repository_root must be an existing readable directory.");
+if (repoPath && repoPath !== projectRoot) errors.push("repository_root must resolve to project_root.");
+assertHeadings(dependency.text, 2, ["输入与代码基线", "用户故事覆盖矩阵", "跨故事共享依赖", "风险与未定位项"], errors, "Dependency Analysis");
+if (/^##\s+(?:\d+[.、]?\s*)?(?:分析范围|追溯汇总)\s*$/m.test(dependency.text)) errors.push("Complete V3 Dependency Analysis must not contain 分析范围 or 追溯汇总 sections.");
+if (scope === "frontend" || scope === "both") assertHeadings(dependency.text, 2, ["前端依赖详情"], errors, "Dependency Analysis");
+if (scope === "backend" || scope === "both") assertHeadings(dependency.text, 2, ["后端依赖详情", "API 实现映射"], errors, "Dependency Analysis");
+if (scope === "frontend" && /(?:^##\s+.*(?:后端依赖详情|API 实现映射)|\bBE-US-\d{3,}\b|\bAC-BE-\d{3,}\b|\bAPI-\d{3,}\b)/m.test(dependency.text)) errors.push("frontend scope must not contain backend dependency details or API mappings.");
+if (scope === "backend" && /(?:^##\s+.*前端依赖详情|\bFE-US-\d{3,}\b|\bAC-FE-\d{3,}\b)/m.test(dependency.text)) errors.push("backend scope must not contain frontend dependency details.");
+
+const frontendStories = requirement && (scope === "frontend" || scope === "both") ? storyBlocks(section(requirement.text, 2, "前端用户故事"), "FE-US") : [];
+const backendStories = requirement && (scope === "backend" || scope === "both") ? storyBlocks(section(requirement.text, 2, "后端用户故事"), "BE-US") : [];
+const apiRequired = backendStories.some((story) => /\bAPI\b/i.test(field(story.text, "触发方式") ?? ""));
+if (apiRequired) {
+  if (!api) errors.push("API-triggered backend stories require api-documentation.md.");
+  if (!sourceApi || sourceApi === "none") errors.push("API-triggered backend stories require source_api_documentation.");
+  if (api && resolve(dirname(dependency.path), sourceApi) !== api.path) errors.push("source_api_documentation must reference the supplied API Documentation.");
+} else {
+  if (api) errors.push("API Documentation must not be supplied when no selected backend story uses API.");
+  if (sourceApi !== "none") errors.push("Non-API analysis must use source_api_documentation: none.");
+  if ((scope === "backend" || scope === "both") && !/不适用.*不涉及 HTTP API/s.test(section(dependency.text, 2, "API 实现映射") ?? "")) errors.push("Non-API analysis must mark API 实现映射 not applicable.");
+}
+
+function validateDetails(frontend, expectedStories) {
+  const title = frontend ? "前端依赖详情" : "后端依赖详情";
+  const prefix = frontend ? "FE-US" : "BE-US";
+  const acPrefix = frontend ? "AC-FE" : "AC-BE";
+  const requiredFields = frontend
+    ? ["验收标准", "页面/路由", "组件", "状态", "API client/类型", "状态与边界落点", "定位证据", "风险", "置信度"]
+    : ["验收标准", "API 文档引用", "路由/入口", "Controller/Handler", "Service/领域逻辑", "DTO/Schema", "数据依赖", "权限依赖", "错误/日志/审计", "测试落点", "定位证据", "风险", "置信度"];
+  const details = storyBlocks(section(dependency.text, 2, title), prefix);
+  for (const story of expectedStories) if (!details.some((item) => item.id === story.id)) errors.push(`Dependency Analysis is missing ${title} for ${story.id}.`);
+  for (const detail of details) {
+    const story = expectedStories.find((item) => item.id === detail.id);
+    if (!story) errors.push(`Dependency Analysis contains unselected story ${detail.id}.`);
+    for (const name of requiredFields) if (!field(detail.text, name)) errors.push(`${detail.id} dependency detail is missing field ${name}.`);
+    const impact = fieldBlock(detail.text, "影响文件");
+    if (!impact) errors.push(`${detail.id} dependency detail is missing field 影响文件.`);
+    const declarations = [...impact.matchAll(/^\s*-\s*(F\d+)\s+(add|modify|reuse|新增|修改|复用)\s+`?([^`\r\n]+)`?/gmi)];
+    if (!declarations.length) errors.push(`${detail.id} 影响文件 must declare F<number>, add/modify/reuse, and a path.`);
+    const declared = declarations.map((item) => item[1]);
+    if (new Set(declared).size !== declared.length) errors.push(`${detail.id} 影响文件 contains duplicate file IDs.`);
+    for (const ref of detail.text.match(/\bF\d+\b/g) ?? []) if (!declared.includes(ref)) errors.push(`${detail.id} references undeclared impact file ${ref}.`);
+    if (!/^(?:high|medium|low)$/i.test(field(detail.text, "置信度") ?? "")) errors.push(`${detail.id} 置信度 must be high, medium, or low.`);
+    if (story) {
+      const expected = field(story.text, "验收标准")?.match(new RegExp(`${acPrefix}-\\d{3,}`, "g")) ?? [];
+      const actual = field(detail.text, "验收标准")?.match(new RegExp(`${acPrefix}-\\d{3,}`, "g")) ?? [];
+      if ([...expected].sort().join() !== [...actual].sort().join()) errors.push(`${detail.id} acceptance references must match Product Requirement.`);
+    }
+  }
+}
+
+if (scope === "frontend" || scope === "both") validateDetails(true, frontendStories);
+if (scope === "backend" || scope === "both") validateDetails(false, backendStories);
+const coverage = section(dependency.text, 2, "用户故事覆盖矩阵") ?? "";
+for (const story of [...frontendStories, ...backendStories]) {
+  if (!coverage.includes(story.id)) errors.push(`Coverage matrix is missing ${story.id}.`);
+  for (const ac of field(story.text, "验收标准")?.match(/AC-(?:FE|BE)-\d{3,}/g) ?? []) if (!coverage.includes(ac)) errors.push(`Coverage matrix is missing ${ac}.`);
+}
+
+if (api) {
+  const mapping = section(dependency.text, 2, "API 实现映射") ?? "";
+  for (const item of apiBlocks(api.text)) {
+    const operation = tableValue(item.text, "Operation ID");
+    const signature = item.text.match(/^>\s*`((?:GET|POST|PUT|PATCH|DELETE)\s+\/[^`]+)`/m)?.[1];
+    if (!mapping.includes(item.id)) errors.push(`API 实现映射 is missing ${item.id}.`);
+    if (operation && !mapping.includes(operation)) errors.push(`API 实现映射 is missing Operation ID ${operation}.`);
+    if (signature && !mapping.includes(signature)) errors.push(`API 实现映射 is missing ${signature}.`);
+  }
+}
+print("Dependency Analysis", dependency.path, errors);

package/skills/analyze-product-dependencies/scripts/validate-product-requirement-input.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { acceptanceBlocks, assertHeadings, containsUnresolvedBlockingPriority, field, load, metadata, outputSpecBlocks, print, scopeIncludes, section, storyBlocks, validateAcceptance, validateArtifactLocation } from "./validation-helpers.mjs";
+
+const args = process.argv.slice(2);
+const fileArg = args[0];
+const targetIndex = args.indexOf("--target");
+const target = targetIndex >= 0 ? args[targetIndex + 1] : args[1];
+if (!fileArg) {
+  console.error("Usage: node validate-product-requirement-input.mjs <product-requirement.md> [frontend|backend|both] | [--target frontend|backend|both]");
+  process.exit(2);
+}
+let artifact;
+try { artifact = load(fileArg, "Product Requirement"); }
+catch (error) { console.error(error.message); process.exit(2); }
+
+const errors = [];
+validateArtifactLocation(artifact, errors, "product-requirement.md");
+const version = metadata(artifact.text, "artifact_version");
+const upstreamScope = metadata(artifact.text, "analysis_scope");
+const scope = target ?? upstreamScope;
+if (!["2.0", "3.0"].includes(version)) errors.push("artifact_version must be 2.0 or 3.0.");
+if (metadata(artifact.text, "artifact_type") !== "product-requirement") errors.push("artifact_type must be product-requirement.");
+if (metadata(artifact.text, "requirement_status") !== "complete") errors.push("requirement_status must be complete.");
+if (!["frontend", "backend", "both"].includes(upstreamScope)) errors.push("analysis_scope must be frontend, backend, or both.");
+if (!["frontend", "backend", "both"].includes(scope)) errors.push("target must be frontend, backend, or both.");
+else if (!scopeIncludes(upstreamScope, scope)) errors.push(`target ${scope} is not included in upstream scope ${upstreamScope}.`);
+
+if (version === "3.0") {
+  assertHeadings(artifact.text, 2, ["需求概述", "业务目标", "需求范围", "业务规则", "决策追溯"], errors, "Product Requirement");
+  if (/^##\s+(?:\d+[.、]?\s*)?(?:用户角色|验收标准汇总)\s*$/m.test(artifact.text)) errors.push("V3 Product Requirement must not contain standalone 用户角色 or 验收标准汇总 sections.");
+} else {
+  assertHeadings(artifact.text, 2, ["需求背景", "需求摘要", "业务目标", "用户角色", "需求范围", "业务规则", "验收标准汇总", "决策追溯"], errors, "V2 Product Requirement");
+}
+const range = section(artifact.text, 2, "需求范围") ?? "";
+assertHeadings(range, 3, ["已确认需求", "非目标", "默认假设", "未决事项"], errors, "需求范围");
+if (containsUnresolvedBlockingPriority(section(range, 3, "未决事项") ?? "")) errors.push("Product Requirement contains unresolved P0/P1 items.");
+
+function validateDomain(name) {
+  const frontend = name === "frontend";
+  const title = frontend ? "前端" : "后端";
+  const prefix = frontend ? "FE-US" : "BE-US";
+  const acPrefix = frontend ? "AC-FE" : "AC-BE";
+  const storyFields = version === "3.0"
+    ? (frontend ? ["角色", "目标", "价值", "入口", "验收标准"] : ["系统能力", "使用方", "业务价值", "触发方式", "验收标准"])
+    : (frontend ? ["用户角色", "用户目标", "页面/入口", "页面/组件", "展示内容", "交互动作", "UI 状态", "权限可见性", "前端边界处理", "验收标准"] : ["系统能力", "使用方", "触发方式", "输入语义", "输出语义", "数据读写", "权限规则", "业务规则", "安全要求", "后端边界处理", "验收标准"]);
+  assertHeadings(artifact.text, 2, [`${title}用户故事`, `${title}输出规范`], errors, "Product Requirement");
+  const stories = storyBlocks(section(artifact.text, 2, `${title}用户故事`), prefix);
+  if (!stories.length) errors.push(`Missing ${prefix}-* stories.`);
+  const specs = version === "3.0" ? outputSpecBlocks(section(artifact.text, 2, `${title}输出规范`), prefix) : [];
+  const specFields = frontend ? ["页面/组件", "展示内容", "交互动作", "UI 状态", "表单校验", "权限可见性", "边界处理"] : ["输入语义", "输出语义", "数据读写", "权限规则", "业务规则", "安全要求", "幂等与并发", "错误与边界"];
+  const seen = new Set();
+  for (const story of stories) {
+    if (seen.has(story.id)) errors.push(`Duplicate story ID: ${story.id}.`);
+    seen.add(story.id);
+    for (const fieldName of storyFields) if (!field(story.text, fieldName)) errors.push(`${story.id} is missing field ${fieldName}.`);
+    if (!frontend && !/^(?:API|定时任务|事件|消息|内部调用|数据迁移)(?:$|[、,，/])/i.test(field(story.text, "触发方式") ?? "")) errors.push(`${story.id} 触发方式 is invalid.`);
+    const container = version === "3.0" ? specs.find((spec) => spec.id === story.id) : story;
+    if (!container) {
+      errors.push(`Missing output specification for ${story.id}.`);
+      continue;
+    }
+    if (version === "3.0") for (const fieldName of specFields) if (!field(container.text, fieldName)) errors.push(`${story.id} output specification is missing field ${fieldName}.`);
+    const criteria = acceptanceBlocks(container, acPrefix);
+    if (!criteria.length) errors.push(`${story.id} is missing embedded acceptance criteria.`);
+    const actual = criteria.map((item) => item.id).sort();
+    const referenced = [...(field(story.text, "验收标准") ?? "").matchAll(new RegExp(`${acPrefix}-\\d{3,}`, "g"))].map((item) => item[0]).sort();
+    if (actual.join() !== referenced.join()) errors.push(`${story.id} acceptance references must match its embedded criteria.`);
+    for (const item of criteria) validateAcceptance(item.text, item.id, errors);
+  }
+  if (version === "3.0") for (const spec of specs) if (!stories.some((story) => story.id === spec.id)) errors.push(`Output specification references unknown story ${spec.id}.`);
+}
+
+if (scope === "frontend" || scope === "both") validateDomain("frontend");
+if (scope === "backend" || scope === "both") validateDomain("backend");
+print("Product Requirement input", artifact.path, errors);