@tea-agent/loop-agent 0.25.5 → 0.26.0

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

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

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

@@ -1,146 +1,146 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
-
-export function load(fileArg, label) {
-  const path = resolve(fileArg);
-  try { return { path, text: readFileSync(path, "utf8") }; }
-  catch (error) { throw new Error(`Cannot read ${label} ${path}: ${error.message}`); }
-}
-
-export function metadata(text, name) {
-  const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? "";
-  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return fm.match(new RegExp(`^${escaped}:[ \\t]*["']?([^"'\\r\\n]+)["']?[ \\t]*$`, "m"))?.[1].trim();
-}
-
-export function canonical(title) {
-  return title.replace(/^\d+(?:\.\d+)*[.、]?[ \t]*/, "").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(), text: text.slice(match.index, matches[index + 1]?.index ?? text.length) }));
-}
-
-export function section(text, level, title) {
-  return headings(text, level).find((item) => canonical(item.title) === title)?.text;
-}
-
-export function assertHeadings(text, level, required, errors, owner) {
-  for (const title of required) {
-    const found = headings(text, level).filter((item) => canonical(item.title) === title);
-    if (found.length !== 1) errors.push(`${owner} must contain exactly one ${title} heading.`);
-    else if (!found[0].text.split(/\r?\n/).slice(1).some((line) => line.trim() && !/^\|?[-:| ]+\|?$/.test(line.trim()))) {
-      errors.push(`${owner} section ${title} must not be empty.`);
-    }
-  }
-}
-
-export function storyBlocks(text, prefix) {
-  if (!text) return [];
-  const matches = [...text.matchAll(new RegExp(`^###\\s+(${prefix}-\\d{3,})\\s+(.+)$`, "gm"))];
-  return matches.map((match, index) => ({ id: match[1], text: text.slice(match.index, matches[index + 1]?.index ?? text.length) }));
-}
-
-export function outputSpecBlocks(text, prefix) {
-  return storyBlocks(text, prefix);
-}
-
-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],
-    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 scopeIncludes(upstream, selected) {
-  if (upstream === "both") return ["frontend", "backend", "both"].includes(selected);
-  return upstream === selected;
-}
-
-export function field(text, name) {
-  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return text.match(new RegExp(`^-[ \\t]*${escaped}[：:][ \\t]*(.+)$`, "m"))?.[1].trim().replace(/[。.]$/, "");
-}
-
-export function fieldBlock(text, name) {
-  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const match = new RegExp(`^-[ \\t]*${escaped}[：:][ \\t]*(.*)$`, "m").exec(text);
-  if (!match) return "";
-  const lineEnd = text.indexOf("\n", match.index);
-  const rest = lineEnd < 0 ? "" : text.slice(lineEnd + 1);
-  const next = rest.search(/^-\s*[^\r\n：:]+[：:]/m);
-  return `${match[1]}\n${rest.slice(0, next < 0 ? rest.length : next)}`.trim();
-}
-
-export function tableValue(text, name) {
-  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return text.match(new RegExp(`^\\|[ \\t]*${escaped}[ \\t]*\\|[ \\t]*([^|]+)\\|`, "m"))?.[1].trim();
-}
-
-export function apiBlocks(text) {
-  const details = section(text, 2, "API 详情") ?? "";
-  const matches = [...details.matchAll(/^###\s+(API-\d{3,})\s+(.+)$/gm)];
-  return matches.map((match, index) => ({ id: match[1], title: match[2].trim(), text: details.slice(match.index, matches[index + 1]?.index ?? details.length) }));
-}
-
-export function print(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}.`);
-}
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+export function load(fileArg, label) {
+  const path = resolve(fileArg);
+  try { return { path, text: readFileSync(path, "utf8") }; }
+  catch (error) { throw new Error(`Cannot read ${label} ${path}: ${error.message}`); }
+}
+
+export function metadata(text, name) {
+  const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? "";
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return fm.match(new RegExp(`^${escaped}:[ \\t]*["']?([^"'\\r\\n]+)["']?[ \\t]*$`, "m"))?.[1].trim();
+}
+
+export function canonical(title) {
+  return title.replace(/^\d+(?:\.\d+)*[.、]?[ \t]*/, "").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(), text: text.slice(match.index, matches[index + 1]?.index ?? text.length) }));
+}
+
+export function section(text, level, title) {
+  return headings(text, level).find((item) => canonical(item.title) === title)?.text;
+}
+
+export function assertHeadings(text, level, required, errors, owner) {
+  for (const title of required) {
+    const found = headings(text, level).filter((item) => canonical(item.title) === title);
+    if (found.length !== 1) errors.push(`${owner} must contain exactly one ${title} heading.`);
+    else if (!found[0].text.split(/\r?\n/).slice(1).some((line) => line.trim() && !/^\|?[-:| ]+\|?$/.test(line.trim()))) {
+      errors.push(`${owner} section ${title} must not be empty.`);
+    }
+  }
+}
+
+export function storyBlocks(text, prefix) {
+  if (!text) return [];
+  const matches = [...text.matchAll(new RegExp(`^###\\s+(${prefix}-\\d{3,})\\s+(.+)$`, "gm"))];
+  return matches.map((match, index) => ({ id: match[1], text: text.slice(match.index, matches[index + 1]?.index ?? text.length) }));
+}
+
+export function outputSpecBlocks(text, prefix) {
+  return storyBlocks(text, prefix);
+}
+
+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],
+    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 scopeIncludes(upstream, selected) {
+  if (upstream === "both") return ["frontend", "backend", "both"].includes(selected);
+  return upstream === selected;
+}
+
+export function field(text, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return text.match(new RegExp(`^-[ \\t]*${escaped}[：:][ \\t]*(.+)$`, "m"))?.[1].trim().replace(/[。.]$/, "");
+}
+
+export function fieldBlock(text, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = new RegExp(`^-[ \\t]*${escaped}[：:][ \\t]*(.*)$`, "m").exec(text);
+  if (!match) return "";
+  const lineEnd = text.indexOf("\n", match.index);
+  const rest = lineEnd < 0 ? "" : text.slice(lineEnd + 1);
+  const next = rest.search(/^-\s*[^\r\n：:]+[：:]/m);
+  return `${match[1]}\n${rest.slice(0, next < 0 ? rest.length : next)}`.trim();
+}
+
+export function tableValue(text, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return text.match(new RegExp(`^\\|[ \\t]*${escaped}[ \\t]*\\|[ \\t]*([^|]+)\\|`, "m"))?.[1].trim();
+}
+
+export function apiBlocks(text) {
+  const details = section(text, 2, "API 详情") ?? "";
+  const matches = [...details.matchAll(/^###\s+(API-\d{3,})\s+(.+)$/gm)];
+  return matches.map((match, index) => ({ id: match[1], title: match[2].trim(), text: details.slice(match.index, matches[index + 1]?.index ?? details.length) }));
+}
+
+export function print(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}.`);
+}