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

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

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { acceptanceBlocks, assertHeadings, field, loadMarkdown, metadata, outputSpecBlocks, printResult, section, storyBlocks, validateAcceptance, validateArtifactLocation, validateFrontmatter, validateNoImplementationLeakage, 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 = [];
+validateFrontmatter(text, ["artifact_version", "artifact_type", "requirement_id", "requirement_status", "analysis_scope"], errors, "Product Requirement");
+validateArtifactLocation(artifact, errors, "product-requirement.md");
+const scope = metadata(text, "analysis_scope");
+const status = metadata(text, "requirement_status");
+if (metadata(text, "artifact_version") !== "4.0") errors.push("artifact_version must be 4.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.");
+
+validateNoImplementationLeakage(text, errors);
+assertHeadings(text, 2, ["需求概述", "业务目标", "需求范围", "业务规则", "决策追溯"], errors, "Product Requirement");
+const range = section(text, 2, "需求范围") ?? "";
+assertHeadings(range, 3, ["已确认范围", "非目标"], errors, "需求范围");
+if (/^###\s+(?:\d+(?:\.\d+)*[.、]?\s*)?默认假设\s*$/m.test(range)) errors.push("Product Requirement must not contain 默认假设.");
+const pendingSection = section(range, 3, "未决事项");
+if (status === "complete" && pendingSection) errors.push("Complete Product Requirement must not contain 未决事项.");
+if (status === "pending") assertHeadings(range, 3, ["未决事项"], errors, "Pending Product Requirement");
+if (status === "complete" && /(?:pending-(?:blocking|non-blocking)|未形成|尚未确认|未决)/i.test(text)) errors.push("Complete Product Requirement must not contain unconfirmed product behavior.");
+if (/^##\s+(?:\d+[.、]?\s*)?(?:用户角色|验收标准汇总|前后端契约|Open Questions|测试建议|边界 case|边界Case)\s*$/im.test(text)) {
+  errors.push("Product Requirement must not contain standalone 用户角色, 验收标准汇总, 前后端契约, Open Questions, 测试建议, or 边界 case sections.");
+}
+
+const acceptanceIds = new Set();
+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}.`);
+    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.`);
+    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}.`);
+    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.`);
+    }
+    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) {
+      if (acceptanceIds.has(item.id)) errors.push(`Duplicate acceptance criterion ID: ${item.id}.`);
+      acceptanceIds.add(item.id);
+      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 = join(dirname(path), "requirement-clarification.md");
+if (!existsSync(clarificationSource)) {
+  errors.push("Product Requirement requires requirement-clarification.md in the same requirement directory.");
+} else {
+  const clarification = readFileSync(clarificationSource, "utf8");
+  const clarificationStatus = metadata(clarification, "clarification_status");
+  if (clarificationStatus !== status) errors.push("Product Requirement and source clarification must have the same pending/complete status.");
+  if (status === "complete") {
+    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,109 @@
+#!/usr/bin/env node
+
+import { dirname } from "node:path";
+import { assertHeadings, canonical, field, headings, loadMarkdown, metadata, printResult, section, validateArtifactLocation, validateFrontmatter } 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 = [];
+validateFrontmatter(clarification.text, ["artifact_version", "artifact_type", "requirement_id", "analysis_scope", "clarification_status", "clarification_rounds"], errors, "Requirement Clarification");
+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") !== "4.0") errors.push("artifact_version must be 4.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) errors.push("clarification_rounds must be a non-negative integer.");
+if (!allowPending && status !== "complete") errors.push("Final Requirement Clarification must be complete.");
+const requirementStatus = metadata(requirement.text, "requirement_status");
+if (status !== requirementStatus) errors.push("Requirement Clarification and Product Requirement must have the same pending/complete status.");
+if (scope !== metadata(analysis.text, "analysis_scope")) errors.push("analysis_scope must match Product Analysis.");
+if (scope !== metadata(requirement.text, "analysis_scope")) errors.push("analysis_scope must match Product Requirement.");
+
+if (dirname(analysis.path) !== dirname(clarification.path) || dirname(requirement.path) !== dirname(clarification.path)) errors.push("All requirement artifacts must be in the same requirement directory.");
+const requirementId = metadata(clarification.text, "requirement_id");
+if (requirementId !== metadata(analysis.text, "requirement_id") || requirementId !== metadata(requirement.text, "requirement_id")) errors.push("requirement_id must match across all requirement artifacts.");
+
+const analysisStatus = metadata(analysis.text, "analysis_status");
+const questionBlocks = headings(clarification.text, 3).filter((item) => /^Q-\d{3,}\s+/.test(item.title));
+const sourceSection = section(clarification.text, 2, questionBlocks.length ? "澄清来源" : "来源") ?? "";
+const recordedSourceIdentity = field(sourceSection, "原始需求身份") ?? "";
+const analysisSourceIdentity = field(section(analysis.text, 2, "原始需求") ?? "", "原始需求身份") ?? "";
+if (!/^(?:inline|file):sha256:[a-f0-9]{64}$/.test(recordedSourceIdentity)) errors.push("Clarification source must contain a valid 原始需求身份.");
+else if (recordedSourceIdentity !== analysisSourceIdentity) errors.push("原始需求身份 must match Product Analysis.");
+if (/(?:default-confirmed|confirmed-default)/.test(clarification.text)) errors.push("Requirement Clarification must not use default-confirmed or confirmed-default.");
+
+if (!questionBlocks.length) {
+  if (status !== "complete") errors.push("Compact no-clarification-required artifacts must be complete.");
+  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)}.`);
+  const conclusion = section(clarification.text, 2, "澄清结论") ?? "";
+  if (!/状态[：:]\s*no-clarification-required/.test(conclusion)) errors.push("Compact clarification must declare no-clarification-required.");
+  if (status === "complete" && !/^[ \t]*-[ \t]*内容补充[：:][ \t]*用户已确认无需补充\s*$/m.test(conclusion)) {
+    errors.push("Complete compact clarification must record 内容补充：用户已确认无需补充.");
+  }
+  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) errors.push("Question-based clarification must set clarification_rounds to a positive integer.");
+  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 < 1) errors.push("Question-based clarification must define at least one top-level BR-* branch.");
+  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 finalDecision = 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", "pending-blocking", "pending-non-blocking"].includes(decisionStatus)) errors.push(`${id} 状态 is invalid.`);
+    if (decisionSource !== "user") errors.push(`${id} 决策来源 must be user; source requirements and code facts must not be represented as Q-* decisions.`);
+    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 (decisionStatus === "pending-non-blocking" && !field(block.text, "未确认影响")) errors.push(`${id} pending-non-blocking decision requires 未确认影响.`);
+    if (status === "complete" && (decisionStatus !== "confirmed" || decisionSource !== "user" || /^(?:未回答|待确认|无)$/.test(answer ?? ""))) errors.push(`${id} must be confirmed by an explicit user answer before clarification can be complete.`);
+    if (status === "complete" && /^(?:未形成|未回答|待确认|尚未确认|无)$/.test(finalDecision ?? "")) errors.push(`${id} must contain a formed final decision before clarification can be complete.`);
+    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" && !/^[ \t]*-[ \t]*共同理解[：:][ \t]*已确认\s*$/m.test(section(clarification.text, 2, "决策索引") ?? "")) {
+    errors.push("Complete question-based clarification must record 共同理解：已确认 in 决策索引.");
+  }
+}
+
+printResult("Requirement Clarification", clarification.path, errors);

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

@@ -0,0 +1,175 @@
+import { readFileSync } from "node:fs";
+import { basename, dirname, 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 validateFrontmatter(text, allowedKeys, errors, owner) {
+  const block = frontmatter(text);
+  if (!block) {
+    errors.push(`${owner} must contain YAML frontmatter.`);
+    return;
+  }
+  const keys = [];
+  for (const line of block.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const match = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):[ \t]*(.*)$/);
+    if (!match) {
+      errors.push(`${owner} frontmatter must contain only top-level scalar fields.`);
+      continue;
+    }
+    keys.push(match[1]);
+  }
+  for (const key of new Set(keys)) {
+    if (keys.filter((value) => value === key).length > 1) errors.push(`${owner} frontmatter contains duplicate field ${key}.`);
+    if (!allowedKeys.includes(key)) errors.push(`${owner} frontmatter contains unsupported field ${key}.`);
+  }
+  for (const key of allowedKeys) if (!keys.includes(key)) errors.push(`${owner} frontmatter is missing field ${key}.`);
+}
+
+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.`);
+  }
+  if (/(?:功能正常|应正常展示|展示正确|接口可用|数据正确|符合预期|妥善处理|合理处理|无异常情况|没有需要处理的异常场景|无需处理失败)/.test(block)) {
+    errors.push(`${owner} must not use vague acceptance language.`);
+  }
+}
+
+export function validateNoImplementationLeakage(text, errors, owner = "Product Requirement") {
+  if (/\bKB-FACT-\d+\b/.test(text)) errors.push(`${owner} must not contain KB-FACT-* markers.`);
+  if (/\bCODE-FACT-\d+\b/.test(text)) errors.push(`${owner} must not contain CODE-FACT-* markers.`);
+  if (/(?:^|[\s`'(])(?:\.\/|\.\.\/)?(?:src|app|packages|lib|internal|cmd|pkg)\/[^\s`')]+/m.test(text)) {
+    errors.push(`${owner} must not contain repository file paths.`);
+  }
+  if (/\b[A-Z][A-Za-z0-9]*(?:Controller|Service|Repository|Handler|Middleware)\b/.test(text)) {
+    errors.push(`${owner} must not contain code-level class or component symbols.`);
+  }
+  if (/证据位置/.test(text)) errors.push(`${owner} must not contain 证据位置.`);
+}
+
+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");
+  if (!requirementId || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(requirementId)) {
+    errors.push("requirement_id must use lowercase letters, digits, and single hyphens.");
+    return;
+  }
+  const artifactDir = dirname(artifact.path);
+  const productAnalysisDir = dirname(artifactDir);
+  const docsDir = dirname(productAnalysisDir);
+  if (basename(artifactDir) !== requirementId || basename(productAnalysisDir) !== "product-analysis" || basename(docsDir) !== "docs") {
+    errors.push(`Artifact must be located under <project-root>/docs/product-analysis/${requirementId}.`);
+  }
+  if (expectedName && basename(artifact.path) !== expectedName) {
+    errors.push(`Artifact filename must be ${expectedName}.`);
+  }
+}

package/skills/browser-tools/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: browser-tools
+description: Interactive browser automation via Chrome DevTools Protocol. Use when you need to interact with web pages, test frontends, or when user interaction with a visible browser is required.
+---
+
+# Browser Tools
+
+Chrome DevTools Protocol tools for agent-assisted web automation. These tools connect to Chrome running on `:9222` with remote debugging enabled.
+
+## Setup
+
+Run once before first use:
+
+```bash
+cd {baseDir}/browser-tools
+npm install
+```
+
+## Start Chrome
+
+```bash
+{baseDir}/browser-start.js              # Fresh profile
+{baseDir}/browser-start.js --profile    # Copy user's profile (cookies, logins)
+```
+
+Launch Chrome with remote debugging on `:9222`. Use `--profile` to preserve user's authentication state.
+
+## Navigate
+
+```bash
+{baseDir}/browser-nav.js https://example.com
+{baseDir}/browser-nav.js https://example.com --new
+```
+
+Navigate to URLs. Use `--new` flag to open in a new tab instead of reusing current tab.
+
+## Evaluate JavaScript
+
+```bash
+{baseDir}/browser-eval.js 'document.title'
+{baseDir}/browser-eval.js 'document.querySelectorAll("a").length'
+```
+
+Execute JavaScript in the active tab. Code runs in async context. Use this to extract data, inspect page state, or perform DOM operations programmatically.
+
+## Screenshot
+
+```bash
+{baseDir}/browser-screenshot.js
+```
+
+Capture current viewport and return temporary file path. Use this to visually inspect page state or verify UI changes.
+
+## Pick Elements
+
+```bash
+{baseDir}/browser-pick.js "Click the submit button"
+```
+
+**IMPORTANT**: Use this tool when the user wants to select specific DOM elements on the page. This launches an interactive picker that lets the user click elements to select them. The user can select multiple elements (Cmd/Ctrl+Click) and press Enter when done. The tool returns CSS selectors for the selected elements.
+
+Common use cases:
+- User says "I want to click that button" → Use this tool to let them select it
+- User says "extract data from these items" → Use this tool to let them select the elements
+- When you need specific selectors but the page structure is complex or ambiguous
+
+## Cookies
+
+```bash
+{baseDir}/browser-cookies.js
+```
+
+Display all cookies for the current tab including domain, path, httpOnly, and secure flags. Use this to debug authentication issues or inspect session state.
+
+## Extract Page Content
+
+```bash
+{baseDir}/browser-content.js https://example.com
+```
+
+Navigate to a URL and extract readable content as markdown. Uses Mozilla Readability for article extraction and Turndown for HTML-to-markdown conversion. Works on pages with JavaScript content (waits for page to load).
+
+## When to Use
+
+- Testing frontend code in a real browser
+- Interacting with pages that require JavaScript
+- When user needs to visually see or interact with a page
+- Debugging authentication or session issues
+- Scraping dynamic content that requires JS execution
+
+---
+
+## Efficiency Guide
+
+### DOM Inspection Over Screenshots
+
+**Don't** take screenshots to see page state. **Do** parse the DOM directly:
+
+```javascript
+// Get page structure
+document.body.innerHTML.slice(0, 5000)
+
+// Find interactive elements
+Array.from(document.querySelectorAll('button, input, [role="button"]')).map(e => ({
+  id: e.id,
+  text: e.textContent.trim(),
+  class: e.className
+}))
+```
+
+### Complex Scripts in Single Calls
+
+Wrap everything in an IIFE to run multi-statement code:
+
+```javascript
+(function() {
+  // Multiple operations
+  const data = document.querySelector('#target').textContent;
+  const buttons = document.querySelectorAll('button');
+
+  // Interactions
+  buttons[0].click();
+
+  // Return results
+  return JSON.stringify({ data, buttonCount: buttons.length });
+})()
+```
+
+### Batch Interactions
+
+**Don't** make separate calls for each click. **Do** batch them:
+
+```javascript
+(function() {
+  const actions = ["btn1", "btn2", "btn3"];
+  actions.forEach(id => document.getElementById(id).click());
+  return "Done";
+})()
+```
+
+### Typing/Input Sequences
+
+```javascript
+(function() {
+  const text = "HELLO";
+  for (const char of text) {
+    document.getElementById("key-" + char).click();
+  }
+  document.getElementById("submit").click();
+  return "Submitted: " + text;
+})()
+```
+
+### Reading App/Game State
+
+Extract structured state in one call:
+
+```javascript
+(function() {
+  const state = {
+    score: document.querySelector('.score')?.textContent,
+    status: document.querySelector('.status')?.className,
+    items: Array.from(document.querySelectorAll('.item')).map(el => ({
+      text: el.textContent,
+      active: el.classList.contains('active')
+    }))
+  };
+  return JSON.stringify(state, null, 2);
+})()
+```
+
+### Waiting for Updates
+
+If DOM updates after actions, add a small delay with bash:
+
+```bash
+sleep 0.5 && {baseDir}/browser-eval.js '...'
+```
+
+### Investigate Before Interacting
+
+Always start by understanding the page structure:
+
+```javascript
+(function() {
+  return {
+    title: document.title,
+    forms: document.forms.length,
+    buttons: document.querySelectorAll('button').length,
+    inputs: document.querySelectorAll('input').length,
+    mainContent: document.body.innerHTML.slice(0, 3000)
+  };
+})()
+```
+
+Then target specific elements based on what you find.