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

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

@@ -0,0 +1,501 @@
+#!/usr/bin/env node
+
+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(), "product-requirement-v4-validators-"));
+process.once("exit", () => rmSync(temp, { recursive: true, force: true }));
+const projectRoot = join(temp, "project");
+const artifactDir = join(projectRoot, "docs", "product-analysis", "nickname");
+mkdirSync(artifactDir, { recursive: true });
+const analysisValidator = join(scriptDir, "validate-product-analysis.mjs");
+const clarificationValidator = join(scriptDir, "validate-requirement-clarification.mjs");
+const requirementValidator = join(scriptDir, "validate-product-requirement.mjs");
+const sourceIdentityTool = join(scriptDir, "compute-source-identity.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 analysisPath = join(artifactDir, "product-analysis.md");
+const clarificationPath = join(artifactDir, "requirement-clarification.md");
+const requirementPath = join(artifactDir, "product-requirement.md");
+const sourceIdentity = `inline:sha256:${"1".repeat(64)}`;
+
+const analysis = `---
+artifact_version: "4.0"
+artifact_type: product-analysis
+requirement_id: nickname
+analysis_scope: frontend
+analysis_status: no-clarification-required
+---
+# Product Analysis
+## 1. 原始需求
+- 原始需求身份：${sourceIdentity}
+登录用户可以修改昵称，长度为 2–20 个字符。
+## 2. 需求概述
+在个人资料页维护展示昵称。
+## 3. 业务目标
+- 允许用户维护展示名称。
+## 4. 需求分析
+### 4.1 明确需求
+- 用户只能修改自己的昵称。
+### 4.2 推断需求
+- 无未确认的推断需求。
+### 4.3 待确认问题
+- 无待确认问题。
+- 理由：范围、权限和结果已经明确。
+### 4.4 初步非目标
+- 不修改头像。
+## 5. 外部事实
+### 5.1 知识库事实
+- 检索状态：executed-no-match。
+### 5.2 代码库事实
+- 未提供代码仓库。
+## 6. 初步前端用户故事
+### FE-US-001 修改昵称
+- 角色：已登录用户
+- 目标：修改自己的展示昵称
+- 价值：保持个人资料准确
+- 入口：个人资料页
+- 验收关注点：合法值可保存；非法值不可提交；失败时保留输入
+## 7. 初步前端输出规范
+### FE-US-001 修改昵称
+- 页面/组件：个人资料页、昵称编辑表单
+- 页面路由：/account/profile
+- 展示内容：当前昵称、字符计数、校验提示
+- 交互动作：编辑、保存、取消、重试
+- UI 状态：normal、dirty、loading、success、error、disabled
+- 表单校验：昵称长度为 2–20 个字符
+- 权限可见性：仅当前登录用户
+- 边界处理：失败时保留输入，不得静默失败
+`;
+const clarification = `---
+artifact_version: "4.0"
+artifact_type: requirement-clarification
+requirement_id: nickname
+analysis_scope: frontend
+clarification_status: complete
+clarification_rounds: 0
+---
+# Requirement Clarification
+## 1. 澄清结论
+- 状态：no-clarification-required
+- 原因：范围、权限、数据语义和验收结果已经明确。
+- 内容补充：用户已确认无需补充
+## 2. 来源
+- Product Analysis：./product-analysis.md
+- 原始需求身份：${sourceIdentity}
+## 3. 合并结果
+- Product Requirement 根据明确需求生成，无额外决策标记。
+`;
+
+const requirement = `---
+artifact_version: "4.0"
+artifact_type: product-requirement
+requirement_id: nickname
+requirement_status: complete
+analysis_scope: frontend
+---
+# Product Requirement
+## 1. 需求概述
+在个人资料页维护当前用户的展示昵称。
+## 2. 业务目标
+- 允许用户维护准确的展示名称。
+## 3. 需求范围
+### 3.1 已确认范围
+- 当前用户可以修改自己的昵称。
+### 3.2 非目标
+- 不修改头像。
+## 4. 业务规则
+- 昵称长度必须为 2–20 个字符。
+## 5. 前端用户故事
+### FE-US-001 修改昵称
+- 角色：已登录用户
+- 目标：修改自己的展示昵称
+- 价值：保持个人资料准确
+- 入口：个人资料页
+- 验收标准：AC-FE-001
+## 6. 前端输出规范
+### FE-US-001 修改昵称
+- 页面/组件：个人资料页、昵称编辑表单
+- 页面路由：/account/profile
+- 展示内容：当前昵称、字符计数、校验提示
+- 交互动作：编辑、保存、取消、重试
+- UI 状态：normal、dirty、loading、success、error、disabled
+- 表单校验：昵称长度为 2–20 个字符
+- 权限可见性：仅当前登录用户
+- 边界处理：失败时保留输入，不得静默失败
+#### AC-FE-001 保存合法昵称
+Given：
+- 用户已登录并打开个人资料页。
+When：
+- 用户输入合法昵称并点击保存。
+Then：
+- 页面提交昵称修改请求。
+- 保存成功后展示新昵称。
+- 保存期间按钮保持 disabled。
+异常场景：
+- 保存失败时保留输入并提供重试入口。
+## 7. 决策追溯
+- 本轮无需澄清决策标记；需求直接来源于明确需求。
+`;
+
+const paginatedRequirement = `---
+artifact_version: "4.0"
+artifact_type: product-requirement
+requirement_id: nickname
+requirement_status: complete
+analysis_scope: backend
+---
+# Product Requirement
+## 1. 需求概述
+提供分页列表查询。
+## 2. 业务目标
+- 稳定查询列表数据。
+## 3. 需求范围
+### 3.1 已确认范围
+- 支持分页查询。
+### 3.2 非目标
+- 不支持批量修改。
+## 4. 业务规则
+- 每页条数参数必填，允许值为 10、20、50、100。
+## 5. 后端用户故事
+### BE-US-001 查询列表
+- 系统能力：分页返回列表
+- 使用方：列表页面
+- 业务价值：按需加载数据
+- 触发方式：API（Web）
+- 验收标准：AC-BE-001
+## 6. 后端输出规范
+### BE-US-001 查询列表
+- 输入语义：pageSize 为必填，每页条数允许值为 10、20、50、100
+- 输出语义：返回列表和分页信息
+- 数据读写：只读列表数据
+- 权限规则：仅允许已授权调用方
+- 业务规则：pageSize 必须属于允许值集合
+- 安全要求：不得泄露未授权数据
+- 幂等与并发：重复查询不修改数据
+- 错误与边界：空数据返回空列表和有效分页信息
+#### AC-BE-001 返回分页列表
+Given：
+- 调用方已获得查询权限。
+When：
+- 调用方使用允许的 pageSize 查询列表。
+Then：
+- 返回成功状态和列表数据。
+- 返回有效分页信息。
+- 查询不得修改业务数据。
+异常场景：
+- pageSize 不在允许集合时返回标准参数错误。
+## 7. 决策追溯
+- 需求直接来源于明确需求。
+`;
+
+const readyAnalysis = analysis
+  .replace("analysis_status: no-clarification-required", "analysis_status: ready-for-clarification")
+  .replace("- 无未确认的推断需求。", "- 推断保存成功后展示项目统一提示。")
+  .replace("- 无待确认问题。", "- P1：保存成功后使用哪种反馈？");
+const pendingFourthRoundClarification = `---
+artifact_version: "4.0"
+artifact_type: requirement-clarification
+requirement_id: nickname
+analysis_scope: frontend
+clarification_status: pending
+clarification_rounds: 4
+---
+# Requirement Clarification
+## 1. 澄清来源
+- Product Analysis：./product-analysis.md
+- 原始需求身份：${sourceIdentity}
+## 2. 决策分支
+| 分支 ID | 名称 | 优先级 | 依赖 | 状态 |
+|---|---|---|---|---|
+| BR-001 | 保存反馈 | P1 | 无 | in-progress |
+## 3. 问题记录
+### Q-001 保存成功反馈
+- 澄清轮次：4
+- 分支：BR-001
+- 优先级：P1
+- 影响范围：frontend
+- 推荐答案：使用项目统一成功提示
+- 推荐理由：保持一致体验
+- 用户回答：待确认
+- 最终决策：未形成
+- 决策来源：user
+- 状态：pending-blocking
+- 决策标记：DEC-Q-001
+- 目标位置：前端输出规范
+## 4. 决策索引
+- DEC-Q-001：待确认
+`;
+
+writeFileSync(analysisPath, analysis);
+writeFileSync(clarificationPath, clarification);
+writeFileSync(requirementPath, requirement);
+
+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; }
+
+const sourceDirA = join(temp, "source-a");
+const sourceDirB = join(temp, "source-b");
+mkdirSync(sourceDirA, { recursive: true });
+mkdirSync(sourceDirB, { recursive: true });
+const sourcePathA = join(sourceDirA, "requirement.md");
+const sourcePathB = join(sourceDirB, "requirement.md");
+writeFileSync(sourcePathA, "same requirement body\n");
+writeFileSync(sourcePathB, "same requirement body\n");
+const fileIdentityA = run(sourceIdentityTool, ["file-source", sourcePathA]);
+const fileIdentityB = run(sourceIdentityTool, ["file-source", sourcePathB]);
+pass("file source identity A", fileIdentityA);
+pass("file source identity B", fileIdentityB);
+if (fileIdentityA.stdout.trim() === fileIdentityB.stdout.trim()) throw new Error("file-source identity must bind normalized path as well as body.");
+checks += 3;
+const inlineIdentityA = run(sourceIdentityTool, ["inline-source", sourcePathA]);
+const inlineIdentityB = run(sourceIdentityTool, ["inline-source", sourcePathB]);
+pass("inline source identity A", inlineIdentityA);
+pass("inline source identity B", inlineIdentityB);
+if (inlineIdentityA.stdout.trim() !== inlineIdentityB.stdout.trim()) throw new Error("inline-source identity must depend only on exact body.");
+checks += 3;
+
+expectPass("valid V4 analysis", analysisValidator, [analysisPath, "--target", "frontend"]);
+expectFail("analysis target mismatch", analysisValidator, [analysisPath, "--target", "backend"], "does not match");
+expectFail("analysis rejects extra frontmatter fields", analysisValidator, [variant("analysis-extra-frontmatter.md", analysis.replace("analysis_status: no-clarification-required", "analysis_status: no-clarification-required\nsource_path: /private/customer/prd.md"))], "unsupported field source_path");
+expectFail("analysis requires source identity", analysisValidator, [variant("analysis-no-source-identity.md", analysis.replace(`- 原始需求身份：${sourceIdentity}\n`, ""))], "原始需求身份");
+const analysisWithKnowledgeHit = analysis.replace("- 检索状态：executed-no-match。", "- 检索状态：executed-hit。\n- KB-FACT-001：采用项目统一空状态组件；来源为当前有效设计系统。");
+writeFileSync(analysisPath, analysisWithKnowledgeHit);
+expectPass("analysis accepts executed-hit with KB fact", analysisValidator, [analysisPath, "--target", "frontend"]);
+writeFileSync(analysisPath, analysis);
+expectFail("analysis requires explicit knowledge status", analysisValidator, [variant("analysis-kb-no-status.md", analysis.replace("- 检索状态：executed-no-match。", "- 未执行知识库。"))], "must contain exactly one knowledge status");
+expectFail("analysis rejects not-executed", analysisValidator, [variant("analysis-kb-not-executed.md", analysis.replace("executed-no-match", "not-executed"))], "must not use not-executed");
+expectFail("analysis executed-hit requires KB fact", analysisValidator, [variant("analysis-kb-hit-no-fact.md", analysis.replace("executed-no-match", "executed-hit"))], "must contain at least one KB-FACT");
+expectFail("analysis KB fact requires executed-hit", analysisValidator, [variant("analysis-kb-fact-wrong-status.md", analysis.replace("- 检索状态：executed-no-match。", "- 检索状态：executed-no-match。\n- KB-FACT-001：不应存在。"))], "require executed-hit");
+expectFail("analysis unavailable requires user skip confirmation", analysisValidator, [variant("analysis-kb-unavailable-no-confirmation.md", analysis.replace("executed-no-match", "unavailable"))], "用户处置：已确认跳过知识库");
+const analysisWithKnowledgeUnavailable = analysis.replace("- 检索状态：executed-no-match。", "- 检索状态：unavailable。\n- 用户处置：已确认跳过知识库");
+writeFileSync(analysisPath, analysisWithKnowledgeUnavailable);
+expectPass("analysis unavailable accepts user skip confirmation", analysisValidator, [analysisPath, "--target", "frontend"]);
+writeFileSync(analysisPath, analysis);
+expectFail("analysis rejects formal AC", analysisValidator, [variant("analysis-ac.md", analysis.replace("验收关注点：", "验收关注点：AC-FE-001 "))], "must use acceptance concerns");
+expectFail("analysis requires matching spec", analysisValidator, [variant("analysis-no-spec.md", analysis.replace("### FE-US-001 修改昵称\n- 页面/组件", "### FE-US-002 修改昵称\n- 页面/组件"))], "missing output specification");
+expectFail("analysis rejects standalone roles", analysisValidator, [variant("analysis-roles.md", analysis.replace("## 4. 需求分析", "## 用户角色\n- 已登录用户。\n## 4. 需求分析"))], "must not contain standalone");
+expectFail("no-clarification analysis rejects unconfirmed inferred requirements", analysisValidator, [variant("analysis-unconfirmed-inference.md", analysis.replace("- 无未确认的推断需求。", "- 推断保存成功后展示通用提示。"))], "must declare no unconfirmed inferred requirements");
+expectFail("no-clarification analysis requires an explicit no-question sentinel", analysisValidator, [variant("analysis-implicit-question.md", analysis.replace("- 无待确认问题。", "- 保存反馈尚未确定。"))], "must declare no pending questions");
+expectFail("no-clarification analysis rejects questions hidden after the sentinel", analysisValidator, [variant("analysis-hidden-question.md", analysis.replace("- 无待确认问题。", "- 无待确认问题。\n- 保存反馈尚未确定。"))], "must declare no pending questions");
+
+expectPass("valid compact clarification", clarificationValidator, [analysisPath, clarificationPath, requirementPath]);
+expectFail("clarification rejects extra frontmatter fields", clarificationValidator, [analysisPath, variant("clarification-extra-frontmatter.md", clarification.replace("clarification_rounds: 0", "clarification_rounds: 0\nsource_path: /private/customer/prd.md")), requirementPath], "unsupported field source_path");
+expectFail("clarification rejects source identity mismatch", clarificationValidator, [analysisPath, variant("clarification-source-identity-mismatch.md", clarification.replace(sourceIdentity, `inline:sha256:${"2".repeat(64)}`)), requirementPath], "原始需求身份 must match");
+expectFail("complete compact clarification requires supplement confirmation", clarificationValidator, [analysisPath, variant("clarification-no-supplement-confirmation.md", clarification.replace("- 内容补充：用户已确认无需补充\n", "")), requirementPath], "内容补充：用户已确认无需补充");
+expectFail("compact clarification must use zero rounds", clarificationValidator, [analysisPath, variant("clarification-nonzero-rounds.md", clarification.replace("clarification_rounds: 0", "clarification_rounds: 4")), requirementPath], "must set clarification_rounds to 0");
+expectFail("compact clarification rejects extra section", clarificationValidator, [analysisPath, variant("clarification-extra.md", clarification + "\n## 4. 完成门禁\n- 已完成。\n"), requirementPath], "must not contain section");
+writeFileSync(analysisPath, readyAnalysis);
+writeFileSync(clarificationPath, pendingFourthRoundClarification);
+expectFail("pending clarification rejects complete requirement", clarificationValidator, [analysisPath, clarificationPath, requirementPath, "--allow-pending"], "same pending/complete status");
+writeFileSync(requirementPath, requirement.replace("requirement_status: complete", "requirement_status: pending").replace("### 3.2 非目标\n- 不修改头像。", "### 3.2 非目标\n- 不修改头像。\n### 3.3 未决事项\n- P1：保存成功提示待用户确认。"));
+expectPass("question clarification supports more than three rounds", clarificationValidator, [analysisPath, clarificationPath, requirementPath, "--allow-pending"]);
+expectFail("question clarification rejects source requirement as a Q decision", clarificationValidator, [analysisPath, variant("clarification-source-question.md", pendingFourthRoundClarification.replace("- 决策来源：user", "- 决策来源：source-requirement")), requirementPath, "--allow-pending"], "must be user");
+expectFail("question clarification rejects removed default status", clarificationValidator, [analysisPath, variant("clarification-default-status.md", pendingFourthRoundClarification.replace("- 状态：pending-blocking", "- 状态：default-confirmed")), requirementPath, "--allow-pending"], "must not use");
+writeFileSync(requirementPath, requirement);
+writeFileSync(analysisPath, analysis);
+writeFileSync(clarificationPath, clarification);
+
+expectPass("valid V4 requirement", requirementValidator, [requirementPath, "--target", "frontend"]);
+expectFail("requirement rejects extra frontmatter fields", requirementValidator, [variant("requirement-extra-frontmatter.md", requirement.replace("analysis_scope: frontend", "analysis_scope: frontend\nsource_path: /private/customer/prd.md"))], "unsupported field source_path");
+expectFail("requirement target mismatch", requirementValidator, [requirementPath, "--target", "backend"], "does not match");
+expectFail("requirement requires role", requirementValidator, [variant("requirement-no-role.md", requirement.replace("- 角色：已登录用户\n", ""))], "missing story field 角色");
+expectFail("requirement requires matching spec", requirementValidator, [variant("requirement-no-spec.md", requirement.replace("### FE-US-001 修改昵称\n- 页面/组件", "### FE-US-002 修改昵称\n- 页面/组件"))], "missing output specification");
+expectFail("requirement AC refs match spec", requirementValidator, [variant("requirement-bad-ac.md", requirement.replace("- 验收标准：AC-FE-001", "- 验收标准：AC-FE-002"))], "must match its output specification");
+const duplicateAcStory = `### FE-US-002 再次修改昵称
+- 角色：已登录用户
+- 目标：再次修改昵称
+- 价值：保持个人资料准确
+- 入口：个人资料页
+- 验收标准：AC-FE-001
+`;
+const duplicateAcSpec = `### FE-US-002 再次修改昵称
+- 页面/组件：个人资料页、昵称编辑表单
+- 页面路由：/account/profile
+- 展示内容：当前昵称
+- 交互动作：保存
+- UI 状态：normal、loading、error、disabled
+- 表单校验：昵称长度为 2–20 个字符
+- 权限可见性：仅当前用户
+- 边界处理：失败时保留输入并允许重试
+#### AC-FE-001 再次保存昵称
+Given：
+- 用户已登录。
+When：
+- 用户点击保存。
+Then：
+- 页面提交请求。
+- 页面展示新昵称。
+- 页面不得泄露他人数据。
+异常场景：
+- 失败时保留输入并允许重试。
+`;
+const duplicateAcRequirement = requirement
+  .replace("## 6. 前端输出规范", `${duplicateAcStory}## 6. 前端输出规范`)
+  .replace("## 7. 决策追溯", `${duplicateAcSpec}## 7. 决策追溯`);
+expectFail("requirement rejects duplicate AC IDs across stories", requirementValidator, [variant("requirement-duplicate-ac.md", duplicateAcRequirement)], "Duplicate acceptance criterion ID");
+expectFail("frontend output requires page route", requirementValidator, [variant("requirement-no-route.md", requirement.replace("- 页面路由：/account/profile\n", ""))], "missing field 页面路由");
+expectFail("frontend route must be a product path", requirementValidator, [variant("requirement-bad-route.md", requirement.replace("- 页面路由：/account/profile", "- 页面路由：ProfileRoute 组件"))], "must start with /");
+writeFileSync(requirementPath, requirement.replace("- 页面路由：/account/profile", "- 页面路由：不适用；嵌入 /account/profile 页面"));
+expectPass("embedded component route is accepted", requirementValidator, [requirementPath]);
+writeFileSync(requirementPath, requirement);
+expectFail("requirement rejects standalone roles", requirementValidator, [variant("requirement-roles.md", requirement.replace("## 3. 需求范围", "## 用户角色\n- 已登录用户。\n## 3. 需求范围"))], "must not contain standalone");
+expectFail("complete requirement rejects default assumptions", requirementValidator, [variant("requirement-defaults.md", requirement.replace("### 3.2 非目标\n- 不修改头像。", "### 3.2 非目标\n- 不修改头像。\n### 3.3 默认假设\n- 使用通用成功提示。"))], "must not contain 默认假设");
+expectFail("complete requirement rejects unresolved items", requirementValidator, [variant("requirement-unresolved.md", requirement.replace("### 3.2 非目标\n- 不修改头像。", "### 3.2 非目标\n- 不修改头像。\n### 3.3 未决事项\n- P2：待确认成功提示。"))], "must not contain 未决事项");
+writeFileSync(requirementPath, requirement.replace("- 昵称长度必须为 2–20 个字符。", "- 昵称长度必须为 2–20 个字符。\n- 审核状态为“待确认”时，页面展示“待确认”标签。"));
+expectPass("complete requirement accepts literal pending business state", requirementValidator, [requirementPath, "--target", "frontend"]);
+writeFileSync(requirementPath, requirement);
+expectFail("pending requirement rejected by default", requirementValidator, [variant("requirement-pending.md", requirement.replace("requirement_status: complete", "requirement_status: pending"))], "must be complete");
+writeFileSync(requirementPath, requirement.replace("requirement_status: complete", "requirement_status: pending").replace("### 3.2 非目标\n- 不修改头像。", "### 3.2 非目标\n- 不修改头像。\n### 3.3 未决事项\n- P1：保存成功提示待用户确认。"));
+expectFail("pending requirement rejects complete source clarification", requirementValidator, [requirementPath, "--allow-pending"], "same pending/complete status");
+writeFileSync(clarificationPath, pendingFourthRoundClarification);
+expectPass("pending requirement allowed explicitly", requirementValidator, [requirementPath, "--allow-pending"]);
+writeFileSync(clarificationPath, clarification);
+const unspecifiedPageSizes = paginatedRequirement
+  .replaceAll("10、20、50、100", "")
+  .replace("- 输入语义：pageSize 为必填，每页条数允许值为 ", "- 输入语义：pageSize 为必填，支持分页")
+  .replace("- 业务规则：pageSize 必须属于允许值集合", "- 业务规则：pageSize 必须合法")
+  .replace("- 每页条数参数必填，允许值为 。", "- 支持分页查询。");
+writeFileSync(requirementPath, unspecifiedPageSizes);
+expectPass("requirement validator does not infer pagination value sets", requirementValidator, [requirementPath, "--target", "backend"]);
+writeFileSync(requirementPath, requirement);
+expectFail("requirement rejects CODE-FACT leakage", requirementValidator, [variant("requirement-code-fact.md", requirement.replace("- 昵称长度必须为 2–20 个字符。", "- 昵称长度必须为 2–20 个字符。\n- 依据 CODE-FACT-001。"))], "must not contain CODE-FACT");
+expectFail("requirement rejects KB-FACT leakage", requirementValidator, [variant("requirement-kb-fact.md", requirement.replace("- 昵称长度必须为 2–20 个字符。", "- 昵称长度必须为 2–20 个字符。\n- 依据 KB-FACT-001。"))], "must not contain KB-FACT");
+expectFail("requirement rejects repository path leakage", requirementValidator, [variant("requirement-path.md", requirement.replace("- 昵称长度必须为 2–20 个字符。", "- 实现位于 src/account/profile.ts。"))], "must not contain repository file paths");
+expectFail("requirement rejects vague AC language", requirementValidator, [variant("requirement-vague-ac.md", requirement.replace("- 保存成功后展示新昵称。", "- 保存后功能正常。"))], "must not use vague acceptance language");
+expectFail("clarification scope must match requirement", clarificationValidator, [analysisPath, clarificationPath, variant("requirement-scope-mismatch.md", requirement.replace("analysis_scope: frontend", "analysis_scope: both"))], "must match Product Requirement");
+
+const bothAnalysis = analysis
+  .replace("analysis_scope: frontend", "analysis_scope: both")
+  .replace("## 6. 初步前端用户故事", `## 6. 初步前端用户故事`)
+  + `
+## 8. 初步后端用户故事
+### BE-US-001 保存昵称
+- 系统能力：更新当前用户昵称
+- 使用方：个人资料页
+- 业务价值：持久化展示名称
+- 触发方式：API（Web）
+- 验收关注点：合法值可保存；非法值拒绝；失败可重试
+## 9. 初步后端输出规范
+### BE-US-001 保存昵称
+- 输入语义：当前用户与新昵称
+- 输出语义：更新后的昵称
+- 数据读写：更新用户资料
+- 权限规则：仅本人
+- 业务规则：长度 2–20
+- 安全要求：不得泄露他人资料
+- 幂等与并发：重复提交不产生脏数据
+- 错误与边界：非法值返回标准错误
+`;
+const bothRequirement = requirement
+  .replace("analysis_scope: frontend", "analysis_scope: both")
+  .replace("## 7. 决策追溯", `## 7. 后端用户故事
+### BE-US-001 保存昵称
+- 系统能力：更新当前用户昵称
+- 使用方：个人资料页
+- 业务价值：持久化展示名称
+- 触发方式：API（Web）
+- 验收标准：AC-BE-001
+## 8. 后端输出规范
+### BE-US-001 保存昵称
+- 输入语义：当前用户与新昵称
+- 输出语义：更新后的昵称
+- 数据读写：更新用户资料
+- 权限规则：仅本人
+- 业务规则：长度 2–20
+- 安全要求：不得泄露他人资料
+- 幂等与并发：重复提交不产生脏数据
+- 错误与边界：非法值返回标准错误
+#### AC-BE-001 保存合法昵称
+Given：
+- 调用方已认证且为目标用户本人。
+When：
+- 调用方提交合法昵称。
+Then：
+- 返回成功状态和新昵称。
+- 昵称被持久化。
+- 保存期间不得产生部分写入。
+异常场景：
+- 非法长度时返回标准参数错误且不得更新昵称。
+## 9. 决策追溯`);
+const bothClarification = clarification
+  .replace("analysis_scope: frontend", "analysis_scope: both");
+writeFileSync(analysisPath, bothAnalysis);
+writeFileSync(clarificationPath, bothClarification);
+writeFileSync(requirementPath, bothRequirement);
+expectPass("both scope analysis/requirement/clarification", analysisValidator, [analysisPath, "--target", "both"]);
+expectFail("plain API trigger requires Web or Remote clarification", analysisValidator, [variant("analysis-plain-api.md", bothAnalysis.replace("API（Web）", "API")), "--target", "both"], "API must declare Web, Remote, or Web + Remote");
+expectPass("both scope requirement", requirementValidator, [requirementPath, "--target", "both"]);
+expectPass("both scope clarification", clarificationValidator, [analysisPath, clarificationPath, requirementPath]);
+
+writeFileSync(analysisPath, readyAnalysis);
+const completeQuestionClarification = `---
+artifact_version: "4.0"
+artifact_type: requirement-clarification
+requirement_id: nickname
+analysis_scope: frontend
+clarification_status: complete
+clarification_rounds: 1
+---
+# Requirement Clarification
+## 1. 澄清来源
+- Product Analysis：./product-analysis.md
+- 原始需求身份：${sourceIdentity}
+## 2. 决策分支
+| 分支 ID | 名称 | 优先级 | 依赖 | 状态 |
+|---|---|---|---|---|
+| BR-001 | 保存反馈 | P1 | 无 | resolved |
+## 3. 问题记录
+### Q-001 保存成功反馈
+- 澄清轮次：1
+- 分支：BR-001
+- 优先级：P1
+- 影响范围：frontend
+- 推荐答案：使用项目统一成功提示
+- 推荐理由：保持一致体验
+- 用户回答：同意使用项目统一成功提示
+- 最终决策：保存成功后展示项目统一成功提示
+- 决策来源：user
+- 状态：confirmed
+- 决策标记：DEC-Q-001
+- 目标位置：前端输出规范
+## 4. 决策索引
+- DEC-Q-001：保存成功后展示项目统一成功提示
+- 共同理解：已确认
+`;
+const requirementWithDecision = requirement.replace("## 7. 决策追溯\n- 本轮无需澄清决策标记；需求直接来源于明确需求。", "## 7. 决策追溯\n- DEC-Q-001：保存成功后展示项目统一成功提示，已合并到前端输出规范。");
+writeFileSync(clarificationPath, completeQuestionClarification);
+writeFileSync(requirementPath, requirementWithDecision);
+expectPass("complete question clarification with DEC markers", clarificationValidator, [analysisPath, clarificationPath, requirementPath]);
+expectFail("complete clarification rejects unformed final decision", clarificationValidator, [analysisPath, variant("clarification-unformed-decision.md", completeQuestionClarification.replace("- 最终决策：保存成功后展示项目统一成功提示", "- 最终决策：未形成")), requirementPath], "must contain a formed final decision");
+expectPass("requirement with DEC markers", requirementValidator, [requirementPath, "--target", "frontend"]);
+expectFail("complete clarification requires shared-understanding marker", clarificationValidator, [analysisPath, variant("clarification-no-shared.md", completeQuestionClarification.replace("- 共同理解：已确认\n", "")), requirementPath], "共同理解：已确认");
+expectFail("analysis frontend output requires page route", analysisValidator, [variant("analysis-no-route.md", analysis.replace("- 页面路由：/account/profile\n", "")), "--target", "frontend"], "missing field 页面路由");
+expectFail("analysis route must be a product path", analysisValidator, [variant("analysis-bad-route.md", analysis.replace("- 页面路由：/account/profile", "- 页面路由：ProfileRoute 组件")), "--target", "frontend"], "must start with /");
+const embeddedRouteAnalysis = analysis.replace("- 页面路由：/account/profile", "- 页面路由：不适用；嵌入 /account/profile 页面");
+writeFileSync(analysisPath, embeddedRouteAnalysis);
+expectPass("analysis embedded component route is accepted", analysisValidator, [analysisPath, "--target", "frontend"]);
+
+writeFileSync(analysisPath, analysis);
+writeFileSync(clarificationPath, clarification);
+writeFileSync(requirementPath, requirement);
+
+console.log(`Requirement V4 validator matrix passed: ${checks} checks.`);

package/skills/analyze-product-requirements/scripts/validate-product-analysis.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+import { assertHeadings, field, loadMarkdown, metadata, outputSpecBlocks, printResult, section, storyBlocks, validateArtifactLocation, validateFrontmatter, validateStorySpecCoverage } from "./validation-helpers.mjs";
+
+const args = process.argv.slice(2);
+const fileArg = args[0];
+const targetIndex = args.indexOf("--target");
+const expectedTarget = targetIndex >= 0 ? args[targetIndex + 1] : undefined;
+if (!fileArg) {
+  console.error("Usage: node validate-product-analysis.mjs <product-analysis.md> [--target frontend|backend|both]");
+  process.exit(2);
+}
+
+let artifact;
+try { artifact = loadMarkdown(fileArg, "Product Analysis"); }
+catch (error) { console.error(error.message); process.exit(2); }
+
+const { path, text } = artifact;
+const errors = [];
+validateFrontmatter(text, ["artifact_version", "artifact_type", "requirement_id", "analysis_scope", "analysis_status"], errors, "Product Analysis");
+validateArtifactLocation(artifact, errors, "product-analysis.md");
+const scope = metadata(text, "analysis_scope");
+const status = metadata(text, "analysis_status");
+
+if (metadata(text, "artifact_version") !== "4.0") errors.push("artifact_version must be 4.0.");
+if (metadata(text, "artifact_type") !== "product-analysis") errors.push("artifact_type must be product-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 (!["ready-for-clarification", "no-clarification-required"].includes(status)) errors.push("analysis_status must be ready-for-clarification or no-clarification-required.");
+
+assertHeadings(text, 2, ["原始需求", "需求概述", "业务目标", "需求分析", "外部事实"], errors, "Product Analysis");
+const originalRequirement = section(text, 2, "原始需求") ?? "";
+const sourceIdentity = field(originalRequirement, "原始需求身份") ?? "";
+if (!/^(?:inline|file):sha256:[a-f0-9]{64}$/.test(sourceIdentity)) {
+  errors.push("原始需求 must contain 原始需求身份 as inline:sha256:<64 hex> or file:sha256:<64 hex>.");
+}
+const analysis = section(text, 2, "需求分析") ?? "";
+assertHeadings(analysis, 3, ["明确需求", "推断需求", "待确认问题", "初步非目标"], errors, "需求分析");
+const facts = section(text, 2, "外部事实") ?? "";
+assertHeadings(facts, 3, ["知识库事实", "代码库事实"], errors, "外部事实");
+const knowledgeFacts = section(facts, 3, "知识库事实") ?? "";
+const knowledgeStatuses = knowledgeFacts.match(/\b(?:executed-hit|executed-no-match|unavailable)\b/g) ?? [];
+if (/\bnot-executed\b/.test(knowledgeFacts)) errors.push("知识库事实 must not use not-executed; every new requirement requires a real knowledge search.");
+if (knowledgeStatuses.length !== 1) errors.push("知识库事实 must contain exactly one knowledge status: executed-hit, executed-no-match, or unavailable.");
+if (knowledgeStatuses[0] === "executed-hit" && !/\bKB-FACT-\d+\b/.test(knowledgeFacts)) errors.push("executed-hit 知识库事实 must contain at least one KB-FACT-* marker.");
+if (knowledgeStatuses[0] !== "executed-hit" && /\bKB-FACT-\d+\b/.test(knowledgeFacts)) errors.push("KB-FACT-* markers require executed-hit knowledge status.");
+if (knowledgeStatuses[0] === "unavailable" && !/^[ \t]*-[ \t]*用户处置[：:][ \t]*已确认跳过知识库\s*$/m.test(knowledgeFacts)) errors.push("unavailable 知识库事实 must record 用户处置：已确认跳过知识库.");
+
+const questions = section(analysis, 3, "待确认问题") ?? "";
+const inferences = section(analysis, 3, "推断需求") ?? "";
+const contentLines = (block) => block.split(/\r?\n/).slice(1).map((line) => line.trim()).filter(Boolean);
+const inferenceLines = contentLines(inferences);
+const questionLines = contentLines(questions);
+const noInferenceSentinel = /^-\s*无未确认的推断需求[。.]?$/.test(inferenceLines[0] ?? "");
+const noQuestionSentinel = /^-\s*无待确认问题[。.]?$/.test(questionLines[0] ?? "");
+const unexpectedQuestionLines = questionLines.slice(1).filter((line) => !/^-\s*理由[：:]\s*\S/.test(line));
+if (status === "no-clarification-required" && (!noInferenceSentinel || inferenceLines.length !== 1)) errors.push("no-clarification-required analysis must declare no unconfirmed inferred requirements.");
+if (status === "no-clarification-required" && (!noQuestionSentinel || unexpectedQuestionLines.length)) errors.push("no-clarification-required analysis must declare no pending questions.");
+if (status === "no-clarification-required" && /(?:\bQ-\d{3,}\b|\bBR-\d{3,}\b|\bP[012]\b|[？?])/.test(questions)) errors.push("no-clarification-required analysis cannot contain question markers, priorities, branches, or question sentences.");
+if (status === "ready-for-clarification" && !/(?:\bP[012]\b|[？?])/.test(questions)) errors.push("ready-for-clarification analysis must contain at least one prioritized or explicit question.");
+if (/\bAC-(?:FE|BE)-\d{3,}\b|^Given[：:]|^When[：:]|^Then[：:]/m.test(text)) errors.push("Product Analysis must use acceptance concerns, not formal AC IDs or Given/When/Then blocks.");
+if (/^##\s+(?:\d+[.、]?\s*)?(?:用户角色|初步验收标准汇总)\s*$/m.test(text)) errors.push("Product Analysis must not contain standalone 用户角色 or 初步验收标准汇总 sections.");
+
+function validateDomain(domain) {
+  const frontend = domain === "frontend";
+  const title = frontend ? "前端" : "后端";
+  const prefix = frontend ? "FE-US" : "BE-US";
+  const storyHeading = `初步${title}用户故事`;
+  const specHeading = `初步${title}输出规范`;
+  assertHeadings(text, 2, [storyHeading, specHeading], errors, "Product Analysis");
+  const stories = storyBlocks(section(text, 2, storyHeading), prefix);
+  const specs = outputSpecBlocks(section(text, 2, specHeading), prefix);
+  if (!stories.length) errors.push(`${storyHeading} must contain at least one ${prefix}-* story.`);
+  const storyFields = frontend ? ["角色", "目标", "价值", "入口", "验收关注点"] : ["系统能力", "使用方", "业务价值", "触发方式", "验收关注点"];
+  const specFields = frontend ? ["页面/组件", "页面路由", "展示内容", "交互动作", "UI 状态", "表单校验", "权限可见性", "边界处理"] : ["输入语义", "输出语义", "数据读写", "权限规则", "业务规则", "安全要求", "幂等与并发", "错误与边界"];
+  for (const story of stories) {
+    for (const name of storyFields) if (!field(story.text, name)) errors.push(`${story.id} is missing story field ${name}.`);
+    const trigger = field(story.text, "触发方式") ?? "";
+    const apiTrigger = /^API[（(](?:Web|Remote|Web\s*\+\s*Remote)[）)]$/i.test(trigger);
+    if (!frontend && !apiTrigger && !/^(?:定时任务|事件|消息|内部调用|数据迁移)$/i.test(trigger)) errors.push(`${story.id} 触发方式 is invalid; API must declare Web, Remote, or Web + Remote.`);
+  }
+  for (const spec of specs) {
+    for (const name of specFields) if (!field(spec.text, name)) errors.push(`${spec.id} output specification is missing field ${name}.`);
+    if (frontend) {
+      const route = field(spec.text, "页面路由") ?? "";
+      const directRoute = /^`?\/[^`\s]+`?(?:\s|$|[；;，,])/.test(route);
+      const embeddedRoute = /^不适用；.+`?\/[^`\s]+`?.*页面/.test(route);
+      if (!directRoute && !embeddedRoute) errors.push(`${spec.id} 页面路由 must start with / or use 不适用； and name its containing page.`);
+      if (/(?:route config|middleware|路由注册文件|路由组件)/i.test(route)) errors.push(`${spec.id} 页面路由 must describe product routing, not implementation files or framework components.`);
+    }
+  }
+  validateStorySpecCoverage(stories, specs, errors, `${title} scope`);
+}
+
+if (scope === "frontend" || scope === "both") validateDomain("frontend");
+if (scope === "backend" || scope === "both") validateDomain("backend");
+if (scope === "frontend" && /(?:^##\s+.*后端|^###\s+BE-US-)/m.test(text)) errors.push("frontend scope must not contain backend sections or stories.");
+if (scope === "backend" && /(?:^##\s+.*前端|^###\s+FE-US-)/m.test(text)) errors.push("backend scope must not contain frontend sections or stories.");
+printResult("Product Analysis", path, errors);