@tea-agent/loop-agent 0.12.0 → 0.13.0-beta.0

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

@@ -0,0 +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.`);

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

@@ -0,0 +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);

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

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { acceptanceBlocks, assertHeadings, containsUnresolvedBlockingPriority, field, loadMarkdown, metadata, outputSpecBlocks, printResult, section, storyBlocks, validateAcceptance, validateArtifactLocation, validateStorySpecCoverage } from "./validation-helpers.mjs";
+
+const args = process.argv.slice(2);
+const allowPending = args.includes("--allow-pending");
+const targetIndex = args.indexOf("--target");
+const expectedTarget = targetIndex >= 0 ? args[targetIndex + 1] : undefined;
+const fileArg = args.find((arg, index) => !arg.startsWith("--") && (targetIndex < 0 || index !== targetIndex + 1));
+if (!fileArg) {
+  console.error("Usage: node validate-product-requirement.mjs <product-requirement.md> [--target frontend|backend|both] [--allow-pending]");
+  process.exit(2);
+}
+
+let artifact;
+try { artifact = loadMarkdown(fileArg, "Product Requirement"); }
+catch (error) { console.error(error.message); process.exit(2); }
+
+const { path, text } = artifact;
+const errors = [];
+validateArtifactLocation(artifact, errors, "product-requirement.md");
+const scope = metadata(text, "analysis_scope");
+const status = metadata(text, "requirement_status");
+if (metadata(text, "artifact_version") !== "3.0") errors.push("artifact_version must be 3.0.");
+if (metadata(text, "artifact_type") !== "product-requirement") errors.push("artifact_type must be product-requirement.");
+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 (!["pending", "complete"].includes(status)) errors.push("requirement_status must be pending or complete.");
+if (!allowPending && status !== "complete") errors.push("Final Product Requirement must be complete.");
+
+function sourcePath(name) {
+  const value = metadata(text, name);
+  if (!value || ["inline", "none"].includes(value)) return value;
+  return resolve(dirname(path), value);
+}
+for (const name of ["source_requirement", "source_product_analysis", "source_clarification"]) {
+  const value = sourcePath(name);
+  if (!value) errors.push(`${name} is required.`);
+  else if (!["inline", "none"].includes(value) && !existsSync(value)) errors.push(`${name} does not exist: ${value}`);
+}
+for (const name of ["source_product_analysis", "source_clarification"]) {
+  const value = sourcePath(name);
+  if (value && !["inline", "none"].includes(value) && dirname(value) !== dirname(path)) errors.push(`${name} must reference an artifact in the same requirement directory.`);
+}
+
+assertHeadings(text, 2, ["需求概述", "业务目标", "需求范围", "业务规则", "决策追溯"], errors, "Product Requirement");
+const range = section(text, 2, "需求范围") ?? "";
+assertHeadings(range, 3, ["已确认需求", "非目标", "默认假设", "未决事项"], errors, "需求范围");
+if (status === "complete" && containsUnresolvedBlockingPriority(section(range, 3, "未决事项") ?? "")) errors.push("Complete Product Requirement cannot contain unresolved P0/P1 items.");
+if (/^##\s+(?:\d+[.、]?\s*)?(?:用户角色|验收标准汇总)\s*$/m.test(text)) errors.push("Product Requirement must not contain standalone 用户角色 or 验收标准汇总 sections.");
+
+function validateDomain(domain) {
+  const frontend = domain === "frontend";
+  const title = frontend ? "前端" : "后端";
+  const prefix = frontend ? "FE-US" : "BE-US";
+  const acPrefix = frontend ? "AC-FE" : "AC-BE";
+  const storyHeading = `${title}用户故事`;
+  const specHeading = `${title}输出规范`;
+  assertHeadings(text, 2, [storyHeading, specHeading], errors, "Product Requirement");
+  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.`);
+  validateStorySpecCoverage(stories, specs, errors, `${title} scope`);
+  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.`);
+    const spec = specs.find((item) => item.id === story.id);
+    if (!spec) continue;
+    for (const name of specFields) if (!field(spec.text, name)) errors.push(`${spec.id} output specification is missing field ${name}.`);
+    const criteria = acceptanceBlocks(spec, acPrefix);
+    if (!criteria.length) errors.push(`${spec.id} output specification must contain at least one ${acPrefix}-* acceptance criterion.`);
+    for (const item of criteria) validateAcceptance(item.text, item.id, errors);
+    const referenced = [...(field(story.text, "验收标准") ?? "").matchAll(new RegExp(`${acPrefix}-\\d{3,}`, "g"))].map((item) => item[0]).sort();
+    const actual = criteria.map((item) => item.id).sort();
+    if (referenced.join() !== actual.join()) errors.push(`${story.id} acceptance references must match its output specification criteria.`);
+  }
+}
+
+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.");
+
+const clarificationSource = sourcePath("source_clarification");
+if (status === "complete" && clarificationSource && !["inline", "none"].includes(clarificationSource) && existsSync(clarificationSource)) {
+  const clarification = readFileSync(clarificationSource, "utf8");
+  if (metadata(clarification, "clarification_status") !== "complete") errors.push("Complete Product Requirement requires complete source clarification.");
+  const markers = [...clarification.matchAll(/^-\s*决策标记[：:]\s*(DEC-Q-\d{3,})/gm)].map((item) => item[1]);
+  for (const marker of markers) if (!text.includes(marker)) errors.push(`${marker} from source clarification is missing from Product Requirement.`);
+}
+
+printResult("Product Requirement", path, errors);

package/skills/analyze-product-requirements/scripts/validate-requirement-clarification.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { assertHeadings, canonical, field, headings, loadMarkdown, metadata, printResult, section, validateArtifactLocation } from "./validation-helpers.mjs";
+
+const args = process.argv.slice(2);
+const allowPending = args.includes("--allow-pending");
+const positional = args.filter((arg) => !arg.startsWith("--"));
+if (positional.length < 3) {
+  console.error("Usage: node validate-requirement-clarification.mjs <product-analysis.md> <requirement-clarification.md> <product-requirement.md> [--allow-pending]");
+  process.exit(2);
+}
+
+let analysis, clarification, requirement;
+try {
+  analysis = loadMarkdown(positional[0], "Product Analysis");
+  clarification = loadMarkdown(positional[1], "Requirement Clarification");
+  requirement = loadMarkdown(positional[2], "Product Requirement");
+} catch (error) { console.error(error.message); process.exit(2); }
+
+const errors = [];
+validateArtifactLocation(clarification, errors, "requirement-clarification.md");
+const scope = metadata(clarification.text, "analysis_scope");
+const status = metadata(clarification.text, "clarification_status");
+const clarificationRounds = Number(metadata(clarification.text, "clarification_rounds"));
+if (metadata(clarification.text, "artifact_version") !== "3.0") errors.push("artifact_version must be 3.0.");
+if (metadata(clarification.text, "artifact_type") !== "requirement-clarification") errors.push("artifact_type must be requirement-clarification.");
+if (!["frontend", "backend", "both"].includes(scope)) errors.push("analysis_scope must be frontend, backend, or both.");
+if (!["pending", "complete"].includes(status)) errors.push("clarification_status must be pending or complete.");
+if (!Number.isInteger(clarificationRounds) || clarificationRounds < 0 || clarificationRounds > 3) errors.push("clarification_rounds must be an integer from 0 to 3.");
+if (!allowPending && status !== "complete") errors.push("Final Requirement Clarification must be complete.");
+if (scope !== metadata(analysis.text, "analysis_scope")) errors.push("analysis_scope must match Product Analysis.");
+
+const resolveRef = (value) => value ? resolve(dirname(clarification.path), value) : "";
+const source = metadata(clarification.text, "source_product_analysis");
+const target = metadata(clarification.text, "target_product_requirement");
+if (resolveRef(source) !== analysis.path) errors.push("source_product_analysis must reference the supplied Product Analysis.");
+if (resolveRef(target) !== requirement.path) errors.push("target_product_requirement must reference the supplied Product Requirement.");
+if (source && dirname(resolveRef(source)) !== dirname(clarification.path)) errors.push("source_product_analysis must be in the same requirement directory.");
+if (target && dirname(resolveRef(target)) !== dirname(clarification.path)) errors.push("target_product_requirement must be in the same requirement directory.");
+if (source && !existsSync(resolveRef(source))) errors.push(`source_product_analysis does not exist: ${resolveRef(source)}`);
+if (target && !existsSync(resolveRef(target))) errors.push(`target_product_requirement does not exist: ${resolveRef(target)}`);
+
+const analysisStatus = metadata(analysis.text, "analysis_status");
+const questionBlocks = headings(clarification.text, 3).filter((item) => /^Q-\d{3,}\s+/.test(item.title));
+
+if (!questionBlocks.length) {
+  if (clarificationRounds !== 0) errors.push("Compact clarification must set clarification_rounds to 0.");
+  if (analysisStatus !== "no-clarification-required") errors.push("Compact clarification is allowed only when Product Analysis is no-clarification-required.");
+  const required = ["澄清结论", "来源", "合并结果"];
+  assertHeadings(clarification.text, 2, required, errors, "Compact Requirement Clarification");
+  for (const heading of headings(clarification.text, 2)) if (!required.includes(canonical(heading.title))) errors.push(`Compact Requirement Clarification must not contain section ${canonical(heading.title)}.`);
+  if (!/状态[：:]\s*no-clarification-required/.test(section(clarification.text, 2, "澄清结论") ?? "")) errors.push("Compact clarification must declare no-clarification-required.");
+  if (/\b(?:BR|Q|DEC-Q)-\d{3,}\b/.test(clarification.text)) errors.push("Compact clarification must not fabricate BR, Q, or DEC-Q markers.");
+} else {
+  if (clarificationRounds < 1 || clarificationRounds > 3) errors.push("Question-based clarification must set clarification_rounds from 1 to 3.");
+  if (analysisStatus !== "ready-for-clarification") errors.push("Question records require Product Analysis status ready-for-clarification.");
+  assertHeadings(clarification.text, 2, ["澄清来源", "决策分支", "问题记录", "决策索引"], errors, "Requirement Clarification");
+  const branchSection = section(clarification.text, 2, "决策分支") ?? "";
+  const branchIds = [...new Set(branchSection.match(/\bBR-\d{3,}\b/g) ?? [])];
+  if (branchIds.length < 3 || branchIds.length > 6) errors.push("Question-based clarification must define 3–6 top-level BR-* branches.");
+  if (status === "complete") {
+    const unresolved = branchSection.split(/\r?\n/).filter((line) => /\|\s*BR-\d{3,}\s*\|/.test(line) && !/\|\s*resolved\s*\|\s*$/.test(line));
+    if (unresolved.length) errors.push("Complete clarification requires every branch to be resolved.");
+  }
+  const requiredFields = ["澄清轮次", "分支", "优先级", "影响范围", "推荐答案", "推荐理由", "用户回答", "最终决策", "决策来源", "状态", "决策标记", "目标位置"];
+  const markers = new Set();
+  for (const block of questionBlocks) {
+    const id = block.title.match(/^(Q-\d{3,})/)?.[1];
+    for (const name of requiredFields) if (!field(block.text, name)) errors.push(`${id} is missing field ${name}.`);
+    const branch = field(block.text, "分支");
+    const round = Number(field(block.text, "澄清轮次"));
+    const priority = field(block.text, "优先级");
+    const impactScope = field(block.text, "影响范围");
+    const answer = field(block.text, "用户回答");
+    const decisionStatus = field(block.text, "状态");
+    const decisionSource = field(block.text, "决策来源");
+    if (!branchIds.includes(branch)) errors.push(`${id} 分支 must reference a defined BR-* branch.`);
+    if (!Number.isInteger(round) || round < 1 || round > clarificationRounds) errors.push(`${id} 澄清轮次 must be between 1 and clarification_rounds.`);
+    if (!["P0", "P1", "P2"].includes(priority)) errors.push(`${id} 优先级 must be P0, P1, or P2.`);
+    if (!["common", "frontend", "backend", "both"].includes(impactScope)) errors.push(`${id} 影响范围 is invalid.`);
+    if (!["confirmed", "default-confirmed", "pending-blocking", "pending-non-blocking"].includes(decisionStatus)) errors.push(`${id} 状态 is invalid.`);
+    if (!["user", "source-requirement", "code-evidence", "confirmed-default"].includes(decisionSource)) errors.push(`${id} 决策来源 is invalid.`);
+    const marker = field(block.text, "决策标记");
+    if (marker !== `DEC-${id}`) errors.push(`${id} 决策标记 must be DEC-${id}.`);
+    if (markers.has(marker)) errors.push(`Duplicate decision marker: ${marker}.`);
+    markers.add(marker);
+    if (decisionSource === "code-evidence" && !field(block.text, "代码证据")) errors.push(`${id} code-evidence decision requires 代码证据.`);
+    if (decisionStatus === "pending-non-blocking" && !field(block.text, "未确认影响")) errors.push(`${id} pending-non-blocking decision requires 未确认影响.`);
+    if (status === "complete" && ["P0", "P1"].includes(priority) && (decisionStatus !== "confirmed" || decisionSource !== "user" || /^(?:未回答|待确认|无)$/.test(answer ?? ""))) errors.push(`${id} ${priority} must contain an explicit user confirmation.`);
+    if (status === "complete" && marker && !requirement.text.includes(marker)) errors.push(`${marker} is missing from Product Requirement decision traceability.`);
+    if (!(section(clarification.text, 2, "决策索引") ?? "").includes(marker ?? "__missing__")) errors.push(`${marker ?? id} is missing from 决策索引.`);
+  }
+}
+
+if (status === "complete" && metadata(requirement.text, "requirement_status") !== "complete") errors.push("Complete clarification requires a complete Product Requirement.");
+printResult("Requirement Clarification", clarification.path, errors);

package/skills/analyze-product-requirements/scripts/validation-helpers.mjs

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+export function loadMarkdown(fileArg, label = "artifact") {
+  const path = resolve(fileArg);
+  try {
+    return { path, text: readFileSync(path, "utf8") };
+  } catch (error) {
+    throw new Error(`Cannot read ${label} ${path}: ${error.message}`);
+  }
+}
+
+export function frontmatter(text) {
+  return text.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? "";
+}
+
+export function metadata(text, name) {
+  const block = frontmatter(text);
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return block.match(new RegExp(`^${escaped}:[ \\t]*["']?([^"'\\r\\n]+)["']?[ \\t]*$`, "m"))?.[1].trim();
+}
+
+export function headings(text, level) {
+  const prefix = "#".repeat(level);
+  const matches = [...text.matchAll(new RegExp(`^${prefix}\\s+(.+)$`, "gm"))];
+  return matches.map((match, index) => ({
+    title: match[1].trim(),
+    start: match.index,
+    text: text.slice(match.index, matches[index + 1]?.index ?? text.length),
+  }));
+}
+
+export function canonical(title) {
+  return title.replace(/^\d+(?:\.\d+)*[.、]?[ \t]*/, "").trim();
+}
+
+export function section(text, level, title) {
+  return headings(text, level).find((item) => canonical(item.title) === title)?.text;
+}
+
+export function sections(text, level, title) {
+  return headings(text, level).filter((item) => canonical(item.title) === title);
+}
+
+export function hasSubstance(block) {
+  if (!block) return false;
+  return block.split(/\r?\n/).slice(1).some((line) => line.trim() && !/^\|?[-:| ]+\|?$/.test(line.trim()));
+}
+
+export function field(block, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return block.match(new RegExp(`^-[ \\t]*${escaped}[：:][ \\t]*(.+)$`, "m"))?.[1].trim().replace(/[。.]$/, "");
+}
+
+export function storyBlocks(block, prefix) {
+  if (!block) return [];
+  const matches = [...block.matchAll(new RegExp(`^###\\s+(${prefix}-\\d{3,})\\s+(.+)$`, "gm"))];
+  return matches.map((match, index) => ({
+    id: match[1],
+    title: match[2].trim(),
+    text: block.slice(match.index, matches[index + 1]?.index ?? block.length),
+  }));
+}
+
+export function outputSpecBlocks(block, prefix) {
+  return storyBlocks(block, prefix);
+}
+
+export function validateStorySpecCoverage(stories, specs, errors, label) {
+  const storyIds = stories.map((item) => item.id);
+  const specIds = specs.map((item) => item.id);
+  for (const id of new Set(storyIds)) if (storyIds.filter((value) => value === id).length > 1) errors.push(`Duplicate story ID: ${id}.`);
+  for (const id of new Set(specIds)) if (specIds.filter((value) => value === id).length > 1) errors.push(`Duplicate output specification: ${id}.`);
+  for (const id of storyIds) if (!specIds.includes(id)) errors.push(`${label} is missing output specification for ${id}.`);
+  for (const id of specIds) if (!storyIds.includes(id)) errors.push(`${label} contains output specification for unknown story ${id}.`);
+}
+
+export function acceptanceBlocks(story, prefix) {
+  const matches = [...story.text.matchAll(new RegExp(`^####\\s+(${prefix}-\\d{3,})\\s+(.+)$`, "gm"))];
+  return matches.map((match, index) => ({
+    id: match[1],
+    title: match[2].trim(),
+    text: story.text.slice(match.index, matches[index + 1]?.index ?? story.text.length),
+  }));
+}
+
+export function validateAcceptance(block, owner, errors) {
+  const labels = ["Given", "When", "Then", "异常场景"];
+  const positions = labels.map((label) => ({ label, index: block.search(new RegExp(`^${label}[：:]`, "m")) }));
+  for (const item of positions) if (item.index < 0) errors.push(`${owner} is missing ${item.label}.`);
+  if (positions.some((item) => item.index < 0)) return;
+  const counts = positions.map((item, index) => {
+    const end = positions[index + 1]?.index ?? block.length;
+    return (block.slice(item.index, end).match(/^-\s+\S.+$/gm) ?? []).length;
+  });
+  if (counts[0] < 1 || counts[1] < 1 || counts[2] < 2 || counts[3] < 1) {
+    errors.push(`${owner} must contain at least 1 Given, 1 When, 2 Then, and 1 exception bullet.`);
+  }
+  if (counts.reduce((sum, count) => sum + count, 0) < 6) errors.push(`${owner} must contain at least six concrete bullets.`);
+  if (!/(?:不得|不应|禁止|保留|恢复|重试|兜底|回滚|disabled)/.test(block)) {
+    errors.push(`${owner} must include an observable protection or recovery result.`);
+  }
+}
+
+export function containsUnresolvedBlockingPriority(block) {
+  if (!block) return false;
+  return block.split(/\r?\n/).slice(1).some((line) => {
+    const plain = line.trim().replace(/^[-*+]\s*/, "").replace(/^\[[ xX]\]\s*/, "");
+    if (!/\bP[01]\b/.test(plain)) return false;
+    if (/^(?:不存在|没有|无)(?:任何)?(?:尚未|未)?(?:解决|确认|关闭|完成)?(?:的)?\s*P[01]\b/.test(plain)) return false;
+    if (/^P[01]\b/.test(plain)) return true;
+    return /(?:pending(?:-blocking)?|unresolved|未解决|未确认|待确认|未决|阻塞)/i.test(plain);
+  });
+}
+
+export function assertHeadings(text, level, required, errors, owner) {
+  for (const title of required) {
+    const matches = sections(text, level, title);
+    if (matches.length !== 1) errors.push(`${owner} must contain exactly one ${title} heading.`);
+    else if (!hasSubstance(matches[0].text)) errors.push(`${owner} section ${title} must not be empty.`);
+  }
+}
+
+export function printResult(label, path, errors) {
+  if (errors.length) {
+    console.error(`${label} validation failed (${errors.length}):`);
+    for (const error of errors) console.error(`- ${error}`);
+    process.exit(1);
+  }
+  console.log(`${label} validation passed: ${path}`);
+}
+
+export function validateArtifactLocation(artifact, errors, expectedName) {
+  const requirementId = metadata(artifact.text, "requirement_id");
+  const projectRootValue = metadata(artifact.text, "project_root");
+  if (!requirementId || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(requirementId)) {
+    errors.push("requirement_id must use lowercase letters, digits, and single hyphens.");
+    return;
+  }
+  if (!projectRootValue) {
+    errors.push("project_root is required.");
+    return;
+  }
+  const projectRoot = resolve(dirname(artifact.path), projectRootValue);
+  if (!existsSync(projectRoot) || !statSync(projectRoot).isDirectory()) {
+    errors.push(`project_root does not resolve to an existing directory: ${projectRoot}`);
+    return;
+  }
+  const expected = resolve(join(projectRoot, "docs", "product-analysis", requirementId));
+  if (dirname(artifact.path) !== expected) {
+    errors.push(`Artifact must be located under ${expected}.`);
+  }
+  if (expectedName && basename(artifact.path) !== expectedName) {
+    errors.push(`Artifact filename must be ${expectedName}.`);
+  }
+}