@tea-agent/loop-agent 0.25.5 → 0.26.0

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

@@ -1,193 +1,193 @@
-#!/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(), "product-requirement-v3-validators-"));
-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 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 analysis = `---
-artifact_version: "3.0"
-artifact_type: product-analysis
-requirement_id: nickname
-project_root: ../../..
-analysis_scope: frontend
-analysis_status: no-clarification-required
-source_requirement: inline
-repository_root: none
----
-# Product Analysis
-## 1. 原始需求
-登录用户可以修改昵称，长度为 2–20 个字符。
-## 2. 需求概述
-在个人资料页维护展示昵称。
-## 3. 业务目标
-- 允许用户维护展示名称。
-## 4. 需求分析
-### 4.1 明确需求
-- 用户只能修改自己的昵称。
-### 4.2 推断需求
-- 无未经确认的推断。
-### 4.3 待确认问题
-- 无。范围、权限和结果已经明确。
-### 4.4 初步非目标
-- 不修改头像。
-## 5. 外部事实
-### 5.1 知识库事实
-- 未集成知识库。
-### 5.2 代码库事实
-- 未提供代码仓库。
-## 6. 初步前端用户故事
-### FE-US-001 修改昵称
-- 角色：已登录用户
-- 目标：修改自己的展示昵称
-- 价值：保持个人资料准确
-- 入口：个人资料页
-- 验收关注点：合法值可保存；非法值不可提交；失败时保留输入
-## 7. 初步前端输出规范
-### FE-US-001 修改昵称
-- 页面/组件：个人资料页、昵称编辑表单
-- 展示内容：当前昵称、字符计数、校验提示
-- 交互动作：编辑、保存、取消、重试
-- UI 状态：normal、dirty、loading、success、error、disabled
-- 表单校验：昵称长度为 2–20 个字符
-- 权限可见性：仅当前登录用户
-- 边界处理：失败时保留输入，不得静默失败
-`;
-
-const clarification = `---
-artifact_version: "3.0"
-artifact_type: requirement-clarification
-requirement_id: nickname
-project_root: ../../..
-analysis_scope: frontend
-clarification_status: complete
-clarification_rounds: 0
-source_product_analysis: ./product-analysis.md
-target_product_requirement: ./product-requirement.md
----
-# Requirement Clarification
-## 1. 澄清结论
-- 状态：no-clarification-required
-- 原因：范围、权限、数据语义和验收结果已经明确。
-## 2. 来源
-- Product Analysis：./product-analysis.md
-## 3. 合并结果
-- Product Requirement 根据明确需求生成，无额外决策标记。
-`;
-
-const requirement = `---
-artifact_version: "3.0"
-artifact_type: product-requirement
-requirement_id: nickname
-project_root: ../../..
-requirement_status: complete
-analysis_scope: frontend
-source_requirement: inline
-source_product_analysis: ./product-analysis.md
-source_clarification: ./requirement-clarification.md
----
-# Product Requirement
-## 1. 需求概述
-在个人资料页维护当前用户的展示昵称。
-## 2. 业务目标
-- 允许用户维护准确的展示名称。
-## 3. 需求范围
-### 3.1 已确认需求
-- 当前用户可以修改自己的昵称。
-### 3.2 非目标
-- 不修改头像。
-### 3.3 默认假设
-- 无未经确认的默认假设。
-### 3.4 未决事项
-- 无。
-## 4. 业务规则
-- 昵称长度必须为 2–20 个字符。
-## 5. 前端用户故事
-### FE-US-001 修改昵称
-- 角色：已登录用户
-- 目标：修改自己的展示昵称
-- 价值：保持个人资料准确
-- 入口：个人资料页
-- 验收标准：AC-FE-001
-## 6. 前端输出规范
-### FE-US-001 修改昵称
-- 页面/组件：个人资料页、昵称编辑表单
-- 展示内容：当前昵称、字符计数、校验提示
-- 交互动作：编辑、保存、取消、重试
-- UI 状态：normal、dirty、loading、success、error、disabled
-- 表单校验：昵称长度为 2–20 个字符
-- 权限可见性：仅当前登录用户
-- 边界处理：失败时保留输入，不得静默失败
-#### AC-FE-001 保存合法昵称
-Given：
-- 用户已登录并打开个人资料页。
-When：
-- 用户输入合法昵称并点击保存。
-Then：
-- 页面提交昵称修改请求。
-- 保存成功后展示新昵称。
-- 保存期间按钮保持 disabled。
-异常场景：
-- 保存失败时保留输入并提供重试入口。
-## 7. 决策追溯
-- 本轮无需澄清决策标记；需求直接来源于明确需求。
-`;
-
-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; }
-
-expectPass("valid V3 analysis", analysisValidator, [analysisPath, "--target", "frontend"]);
-expectFail("analysis target mismatch", analysisValidator, [analysisPath, "--target", "backend"], "does not match");
-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");
-
-expectPass("valid compact clarification", clarificationValidator, [analysisPath, clarificationPath, requirementPath]);
-expectFail("clarification rounds cannot exceed three", clarificationValidator, [analysisPath, variant("clarification-four-rounds.md", clarification.replace("clarification_rounds: 0", "clarification_rounds: 4")), requirementPath], "from 0 to 3");
-expectFail("compact clarification rejects extra section", clarificationValidator, [analysisPath, variant("clarification-extra.md", clarification + "\n## 4. 完成门禁\n- 已完成。\n"), requirementPath], "must not contain section");
-
-expectPass("valid V3 requirement", requirementValidator, [requirementPath, "--target", "frontend"]);
-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");
-expectFail("requirement rejects standalone roles", requirementValidator, [variant("requirement-roles.md", requirement.replace("## 3. 需求范围", "## 用户角色\n- 已登录用户。\n## 3. 需求范围"))], "must not contain standalone");
-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"));
-expectPass("pending requirement allowed explicitly", requirementValidator, [requirementPath, "--allow-pending"]);
-writeFileSync(requirementPath, requirement);
-
-console.log(`Requirement V3 validator matrix passed: ${checks} checks.`);
+#!/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(), "product-requirement-v3-validators-"));
+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 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 analysis = `---
+artifact_version: "3.0"
+artifact_type: product-analysis
+requirement_id: nickname
+project_root: ../../..
+analysis_scope: frontend
+analysis_status: no-clarification-required
+source_requirement: inline
+repository_root: none
+---
+# Product Analysis
+## 1. 原始需求
+登录用户可以修改昵称，长度为 2–20 个字符。
+## 2. 需求概述
+在个人资料页维护展示昵称。
+## 3. 业务目标
+- 允许用户维护展示名称。
+## 4. 需求分析
+### 4.1 明确需求
+- 用户只能修改自己的昵称。
+### 4.2 推断需求
+- 无未经确认的推断。
+### 4.3 待确认问题
+- 无。范围、权限和结果已经明确。
+### 4.4 初步非目标
+- 不修改头像。
+## 5. 外部事实
+### 5.1 知识库事实
+- 未集成知识库。
+### 5.2 代码库事实
+- 未提供代码仓库。
+## 6. 初步前端用户故事
+### FE-US-001 修改昵称
+- 角色：已登录用户
+- 目标：修改自己的展示昵称
+- 价值：保持个人资料准确
+- 入口：个人资料页
+- 验收关注点：合法值可保存；非法值不可提交；失败时保留输入
+## 7. 初步前端输出规范
+### FE-US-001 修改昵称
+- 页面/组件：个人资料页、昵称编辑表单
+- 展示内容：当前昵称、字符计数、校验提示
+- 交互动作：编辑、保存、取消、重试
+- UI 状态：normal、dirty、loading、success、error、disabled
+- 表单校验：昵称长度为 2–20 个字符
+- 权限可见性：仅当前登录用户
+- 边界处理：失败时保留输入，不得静默失败
+`;
+
+const clarification = `---
+artifact_version: "3.0"
+artifact_type: requirement-clarification
+requirement_id: nickname
+project_root: ../../..
+analysis_scope: frontend
+clarification_status: complete
+clarification_rounds: 0
+source_product_analysis: ./product-analysis.md
+target_product_requirement: ./product-requirement.md
+---
+# Requirement Clarification
+## 1. 澄清结论
+- 状态：no-clarification-required
+- 原因：范围、权限、数据语义和验收结果已经明确。
+## 2. 来源
+- Product Analysis：./product-analysis.md
+## 3. 合并结果
+- Product Requirement 根据明确需求生成，无额外决策标记。
+`;
+
+const requirement = `---
+artifact_version: "3.0"
+artifact_type: product-requirement
+requirement_id: nickname
+project_root: ../../..
+requirement_status: complete
+analysis_scope: frontend
+source_requirement: inline
+source_product_analysis: ./product-analysis.md
+source_clarification: ./requirement-clarification.md
+---
+# Product Requirement
+## 1. 需求概述
+在个人资料页维护当前用户的展示昵称。
+## 2. 业务目标
+- 允许用户维护准确的展示名称。
+## 3. 需求范围
+### 3.1 已确认需求
+- 当前用户可以修改自己的昵称。
+### 3.2 非目标
+- 不修改头像。
+### 3.3 默认假设
+- 无未经确认的默认假设。
+### 3.4 未决事项
+- 无。
+## 4. 业务规则
+- 昵称长度必须为 2–20 个字符。
+## 5. 前端用户故事
+### FE-US-001 修改昵称
+- 角色：已登录用户
+- 目标：修改自己的展示昵称
+- 价值：保持个人资料准确
+- 入口：个人资料页
+- 验收标准：AC-FE-001
+## 6. 前端输出规范
+### FE-US-001 修改昵称
+- 页面/组件：个人资料页、昵称编辑表单
+- 展示内容：当前昵称、字符计数、校验提示
+- 交互动作：编辑、保存、取消、重试
+- UI 状态：normal、dirty、loading、success、error、disabled
+- 表单校验：昵称长度为 2–20 个字符
+- 权限可见性：仅当前登录用户
+- 边界处理：失败时保留输入，不得静默失败
+#### AC-FE-001 保存合法昵称
+Given：
+- 用户已登录并打开个人资料页。
+When：
+- 用户输入合法昵称并点击保存。
+Then：
+- 页面提交昵称修改请求。
+- 保存成功后展示新昵称。
+- 保存期间按钮保持 disabled。
+异常场景：
+- 保存失败时保留输入并提供重试入口。
+## 7. 决策追溯
+- 本轮无需澄清决策标记；需求直接来源于明确需求。
+`;
+
+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; }
+
+expectPass("valid V3 analysis", analysisValidator, [analysisPath, "--target", "frontend"]);
+expectFail("analysis target mismatch", analysisValidator, [analysisPath, "--target", "backend"], "does not match");
+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");
+
+expectPass("valid compact clarification", clarificationValidator, [analysisPath, clarificationPath, requirementPath]);
+expectFail("clarification rounds cannot exceed three", clarificationValidator, [analysisPath, variant("clarification-four-rounds.md", clarification.replace("clarification_rounds: 0", "clarification_rounds: 4")), requirementPath], "from 0 to 3");
+expectFail("compact clarification rejects extra section", clarificationValidator, [analysisPath, variant("clarification-extra.md", clarification + "\n## 4. 完成门禁\n- 已完成。\n"), requirementPath], "must not contain section");
+
+expectPass("valid V3 requirement", requirementValidator, [requirementPath, "--target", "frontend"]);
+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");
+expectFail("requirement rejects standalone roles", requirementValidator, [variant("requirement-roles.md", requirement.replace("## 3. 需求范围", "## 用户角色\n- 已登录用户。\n## 3. 需求范围"))], "must not contain standalone");
+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"));
+expectPass("pending requirement allowed explicitly", requirementValidator, [requirementPath, "--allow-pending"]);
+writeFileSync(requirementPath, requirement);
+
+console.log(`Requirement V3 validator matrix passed: ${checks} checks.`);

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

@@ -1,69 +1,69 @@
-#!/usr/bin/env node
-
-import { assertHeadings, field, loadMarkdown, metadata, outputSpecBlocks, printResult, section, storyBlocks, validateArtifactLocation, 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 = [];
-validateArtifactLocation(artifact, errors, "product-analysis.md");
-const scope = metadata(text, "analysis_scope");
-const status = metadata(text, "analysis_status");
-
-if (metadata(text, "artifact_version") !== "3.0") errors.push("artifact_version must be 3.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.");
-if (!metadata(text, "source_requirement")) errors.push("source_requirement is required.");
-if (!metadata(text, "repository_root")) errors.push("repository_root is required; use none when absent.");
-
-assertHeadings(text, 2, ["原始需求", "需求概述", "业务目标", "需求分析", "外部事实"], errors, "Product Analysis");
-const analysis = section(text, 2, "需求分析") ?? "";
-assertHeadings(analysis, 3, ["明确需求", "推断需求", "待确认问题", "初步非目标"], errors, "需求分析");
-const facts = section(text, 2, "外部事实") ?? "";
-assertHeadings(facts, 3, ["知识库事实", "代码库事实"], errors, "外部事实");
-
-const questions = section(analysis, 3, "待确认问题") ?? "";
-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}.`);
-    if (!frontend && !/^(?:API|定时任务|事件|消息|内部调用|数据迁移)(?:$|[、,，/])/i.test(field(story.text, "触发方式") ?? "")) errors.push(`${story.id} 触发方式 is invalid.`);
-  }
-  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}.`);
-  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);
+#!/usr/bin/env node
+
+import { assertHeadings, field, loadMarkdown, metadata, outputSpecBlocks, printResult, section, storyBlocks, validateArtifactLocation, 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 = [];
+validateArtifactLocation(artifact, errors, "product-analysis.md");
+const scope = metadata(text, "analysis_scope");
+const status = metadata(text, "analysis_status");
+
+if (metadata(text, "artifact_version") !== "3.0") errors.push("artifact_version must be 3.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.");
+if (!metadata(text, "source_requirement")) errors.push("source_requirement is required.");
+if (!metadata(text, "repository_root")) errors.push("repository_root is required; use none when absent.");
+
+assertHeadings(text, 2, ["原始需求", "需求概述", "业务目标", "需求分析", "外部事实"], errors, "Product Analysis");
+const analysis = section(text, 2, "需求分析") ?? "";
+assertHeadings(analysis, 3, ["明确需求", "推断需求", "待确认问题", "初步非目标"], errors, "需求分析");
+const facts = section(text, 2, "外部事实") ?? "";
+assertHeadings(facts, 3, ["知识库事实", "代码库事实"], errors, "外部事实");
+
+const questions = section(analysis, 3, "待确认问题") ?? "";
+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}.`);
+    if (!frontend && !/^(?:API|定时任务|事件|消息|内部调用|数据迁移)(?:$|[、,，/])/i.test(field(story.text, "触发方式") ?? "")) errors.push(`${story.id} 触发方式 is invalid.`);
+  }
+  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}.`);
+  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);