@tea-agent/loop-agent 0.33.1 → 0.33.2

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

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
 
 export function load(fileArg, label) {
   const path = resolve(fileArg);
@@ -7,8 +7,35 @@ export function load(fileArg, label) {
   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 fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? "";
+  const fm = frontmatter(text);
   const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   return fm.match(new RegExp(`^${escaped}:[ \\t]*["']?([^"'\\r\\n]+)["']?[ \\t]*$`, "m"))?.[1].trim();
 }
@@ -55,35 +82,6 @@ export function acceptanceBlocks(story, prefix) {
   }));
 }
 
-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;
@@ -126,21 +124,15 @@ export function print(label, path, errors) {
 
 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 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}.`);
   }
-  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}.`);
 }

package/skills/analyze-product-requirements/SKILL.md

@@ -1,19 +1,28 @@
 ---
 name: analyze-product-requirements
-description: 将自然语言需求或现有需求文档整理为冻结的澄清前分析、按需澄清记录和完整 Product Requirement，按 frontend、backend 或 both 范围生成精简用户故事、逐故事输出规范与 Given/When/Then 验收标准。用于需求分析、需求澄清、PRD 或用户故事拆分。
+description: 面向采用 Product Analysis V4、frontend/backend 范围和 Web/Remote 接口分类的组织内部项目，先根据需求内容强制检索项目知识库，再探索代码库并据此澄清，将自然语言需求或现有需求文档整理为冻结的澄清前分析、逐题澄清记录和完整 Product Requirement，并按项目规范生成用户故事、输出规范与 Given/When/Then 验收标准。用于需求分析、需求澄清、PRD、后端分页契约或用户故事拆分；也适用于“帮我把这个需求写成 PRD”“这个需求怎么拆用户故事”“补一下验收标准”“分析下这个需求要做什么”这类请求。
 ---
 
 # Analyze Product Requirements
 
-IRON LAW：`product-analysis.md` 只能生成一次。首次写入成功后，其正文、frontmatter 和文件路径在当前 requirement 的整个生命周期内都不可变；后续轮次禁止编辑、覆盖、追加、格式化、移动或删除该文件。澄清决策只能写入 `requirement-clarification.md`，并通过重新生成合并到 `product-requirement.md`。原始需求同样只读。
+IRON LAW：`product-analysis.md` 必须先写入正式路径，再对该正式文件运行 Product Analysis validator；首次校验返回 exit 0 时立即冻结。只要同源正式文件尚未通过校验，就视为未冻结草稿，当前或后续轮次都允许根据 validator 错误继续修正；校验通过后，其正文、frontmatter 和文件路径在当前 requirement 的整个生命周期内都不可变。冻结后的轮次禁止编辑、覆盖、追加、格式化、移动或删除该文件，也不得再次对该路径调用写工具。此冻结仅由本 skill 的提示词约束，不创建完整性 sidecar。澄清决策只能写入 `requirement-clarification.md`，并通过重新生成合并到 `product-requirement.md`。原始需求同样只读。
 
 本 skill 只定义需求，不分析完整代码依赖或生成实现代码。可对用户提供的仓库做定向事实搜索，但不得输出文件级影响分析。
 
+## 运行环境与外部能力
+
+- 必需：可读写当前项目文件，并能运行 Node.js `.mjs` 校验器。
+- 前置第三方 skill：`kb-design-assist`，用于根据需求内容检索项目知识库中的设计系统、业务规范、API 规范和其他项目约定。
+- 可选能力：隔离的只读代码侦察 agent。
+- 缺少隔离代码侦察 agent 时执行对应 fallback；`kb-design-assist` 为 `unavailable` 时必须先让用户选择“修复后重试”或“跳过知识库”，不得直接 fallback，也不得伪造知识库结果、代码证据或 agent 结果。
+- 调用第三方 skill 时使用当前宿主提供的原生 skill 加载机制，不假定具体命令或工具名称。
+
 ## 输入与产物
 
 - 必填：自然语言需求或原始需求文档路径。
 - 可选：`target=frontend|backend|both` 或 `--target frontend|backend|both`；两种写法等价，默认 `both`。
-- 可选：代码仓库、知识库、历史需求、API 文档、设计规范、业务规则、`project_root`、`requirement_id` 和 `output_dir`。
+- 可选：代码仓库、知识库、历史需求、API 文档、设计系统/交互规范、业务规则、`project_root`、`requirement_id`。
+- 可选：`output_dir`，仅用于显式确认规范路径；若提供，必须等于 `<project-root>/docs/product-analysis/<requirement-id>`，不得指向其他位置。
 - 默认目录：`<project-root>/docs/product-analysis/<requirement-id>/`。
 - 固定产物：该目录内的 `product-analysis.md`、`requirement-clarification.md`、`product-requirement.md`。
 
@@ -25,57 +34,95 @@ IRON LAW：`product-analysis.md` 只能生成一次。首次写入成功后，
   - [ ] 在生成前明确回显“分析范围：frontend | backend | both”；三个产物的 `analysis_scope` 必须等于该归一化 target，后续不得自动扩大范围。
   - [ ] 确定项目根：显式 `project_root` > 仓库根 > 当前项目根。
   - [ ] 确定 requirement ID：显式值 > 需求标题 slug > `YYYYMMDD-<summary-slug>`；仅小写字母、数字和单连字符。
-  - [ ] 确定目录：显式 `output_dir` 必须等于项目根下 `docs/product-analysis/<requirement-id>`；否则使用该默认目录。
-  - [ ] 创建目录，三个产物写入同一目录；元数据使用同一 `requirement_id` 和相对 `project_root: ../../..`。
-  - [ ] 输出路径不得与原始需求路径相同；已有目录来源不同则停止，不得混写。
-  - [ ] 目标目录已有 `product-analysis.md` 时，验证同源后只读加载并跳过 Step 1；无论 pending 或 complete，都不得对该文件执行任何写操作。
-  - [ ] 已有同源 pending 任务只能继续更新 Clarification 和 Product Requirement；如 Product Analysis 需要更正，停止当前 requirement，使用新的 `requirement_id` 和目录重新开始。其他产物覆盖先确认。
+  - [ ] 确定目录：默认 `<project-root>/docs/product-analysis/<requirement-id>`；显式 `output_dir` 若存在则必须与该路径相同。
+  - [ ] 用 `scripts/compute-source-identity.mjs` 计算原始需求身份：inline 输入将准确正文写入临时 UTF-8 文件后使用 `inline-source`；文件输入使用 `file-source`，其摘要同时绑定规范化真实路径与文件正文。不得自行拼接或伪造摘要。
+  - [ ] 创建目录，三个产物写入同一目录并使用同一 `requirement_id`；产物 frontmatter 不记录可由固定目录推导的项目根或来源路径。
+  - [ ] 输出路径不得与原始需求路径相同。
+  - [ ] 同源判定：同目录且已冻结 Product Analysis 的“原始需求身份”与本次计算值完全一致。不满足则停止，不得混写；需要更正时使用新的 `requirement_id` 与目录。
+  - [ ] 目标目录已有同源 `product-analysis.md` 时，先以只读方式运行 Product Analysis validator：通过则视为已冻结并跳过 Step 1；失败则视为未冻结草稿，继续 Step 1，按 validator 错误修正并重试。只有已通过校验的文件才禁止后续写入；不得把“文件已存在”本身当作冻结依据。
+  - [ ] 已有同源任务中，Product Analysis 未通过校验时继续 Step 1 修正草稿；已通过校验并冻结后只能继续更新 Clarification 和 Product Requirement。用户回答当前澄清问题即授权原子更新本流程创建的 pending 产物。覆盖 complete 产物、非本流程创建的文件或来源无法确认的文件前必须单独确认。如已冻结 Product Analysis 的内容需要更正，停止当前 requirement，使用新的 `requirement_id` 和目录重新开始。
 - [ ] Step 1：一次性生成并冻结 Product Analysis ⚠️ REQUIRED
-  - [ ] 读取 `references/product-analysis-schema.md`。
-  - [ ] 区分明确需求、推断需求和待确认问题。
-  - [ ] 如提供仓库，只定向搜索可验证事实并记录 `CODE-FACT-*` 证据。
+  - [ ] 读取 `references/product-analysis-schema.md`，按契约生成；字段、章节与状态枚举以该文件为准。
+  - [ ] 从原始需求提取业务目标、领域对象、角色、关键动作、状态/边界、权限、接口与分页线索，形成仅覆盖当前需求的知识库检索计划；不得先探索代码库再反推检索词。
+  - [ ] 首先读取并执行 `references/kb-integration.md`，按其状态机调用 `kb-design-assist`。每次新 requirement 都必须真实执行知识检索，不得因需求简单、未显式提到项目规范或模型判断“无需知识库”而跳过。
+  - [ ] 知识库状态为 `executed-hit` 或 `executed-no-match`，或 `unavailable` 后用户明确确认跳过，才允许进入项目资料预扫描与常规代码探索；其余情况保持阻断。
+  - [ ] 知识库门禁通过后，依次预扫描 `<project-root>/ai_workspace/project-how-to`、`code-specification`、`project-business`：先枚举文件，再读取入口文档及与当前需求直接相关的内容；缺失目录记录 `not-found` 并继续，不做无边界加载。
+  - [ ] 然后读取并执行 `references/clarification-and-knowledge.md` 第 1 节，按需求问题和知识库结论定向探索代码库。当前宿主支持隔离的只读代码侦察 agent 时，优先委派限定范围的代码探索；不支持时由当前 agent 执行同等范围的定向搜索并只保留精简结果，不得阻断或扩大搜索范围。知识库结论不得替代代码落点证据。
+  - [ ] 汇总原始需求、`KB-FACT-*`、项目资料与 `CODE-FACT-*`，识别可查明事实、冲突、unknown 和必须由用户选择的目标行为；完成以上顺序后才生成待确认问题并进入 Step 2。
+  - [ ] 区分明确需求、推断需求和待确认问题。推断需求一律视为未确认产品内容；每一项推断需求以及任何含糊、缺失、冲突或存在多种合理解释的产品问题，都必须进入 Step 2 逐题向用户澄清，不得因模型认为推荐答案合理而跳过。
+  - [ ] scope 包含 backend 且需求涉及接口/API 时，必须确认实现范围为 Web、Remote 或 Web + Remote；只写笼统“接口/API”视为待确认问题。不得依据知识库或代码现状替用户选择。
   - [ ] 仅按 target 生成精简故事骨架和逐故事初步输出规范：`frontend` 只生成 `FE-US-*`，`backend` 只生成 `BE-US-*`，`both` 才生成两端。
-  - [ ] Product Analysis 只记录验收关注点，不创建正式 `AC-*` 或完整 Given/When/Then。
-  - [ ] 有问题时使用 `ready-for-clarification`；无问题时使用 `no-clarification-required`。
-  - [ ] 写入前完成全部分析内容，只允许一次创建；写入成功即冻结，当前及后续澄清轮次不得再调用写工具处理该路径。
-- [ ] Step 2：建立澄清决策树 ⚠️ REQUIRED
-  - [ ] 读取 `references/clarification-and-knowledge.md` 和 `references/requirement-clarification-schema.md`。
-  - [ ] 有问题时列出 3–6 个顶层 `BR-*` 分支，按依赖排序，从最基础分支开始。
-  - [ ] 每轮先给推荐答案和理由，只问一个主要问题；可合并同一决策分支内紧密耦合的子项，但不得混合无关分支。
-  - [ ] 用户回答后先复核当前回答是否足以形成明确、唯一、可执行且可验收的最终决策；不得仅因用户已经回答就标记为 confirmed。
-  - [ ] 回答不完整、存在多种合理解释、依赖未定义概念、与原始需求或已有决策冲突，或无法自然合并到范围、规则、输出规范和 AC 时，当前问题仍未解决；下一轮必须优先针对该回答的具体模糊点继续澄清，不得跳到其他分支。
-  - [ ] 后续追问必须指出上一轮回答中仍不明确的内容，并收窄为可直接确认的决策点；不得原样重复上一轮问题。
-  - [ ] 当前回答明确后，再重新识别其他剩余模糊点和回答新引入的模糊点；仅在它们会影响范围、规则、输出或验收时进入下一轮，总轮数不得超过 3 轮。
-  - [ ] 第 3 轮后不得继续提问；仍有 P0/P1 时保持 `pending` 并说明阻断项，仍有 P2 时仅可按已记录的默认行为与影响处理。
-  - [ ] 能由代码或资料确认的事实自行回答并附证据，不把现状当作产品决策。
-  - [ ] 完成一个分支后再进入下一个；不得遗留模糊的“视情况而定”。
-  - [ ] 无需澄清时使用三章精简记录，不伪造 `BR-*`、`Q-*` 或 `DEC-Q-*`。
+  - [ ] Product Analysis 只记录验收关注点，不创建正式 `AC-*` 或完整 Given/When/Then。每个前端故事的同 ID 初步输出规范必须包含“页面路由”：独立页面写以 `/` 开头的目标 URL；组件、弹窗或抽屉无独立路由时写“`不适用；嵌入 /目标路径 页面`”（`/目标路径` 替换为真实路径）。
+  - [ ] “原始需求”必须记录 Step 0 计算的 `原始需求身份`；后续所有 Clarification 的“来源/澄清来源”记录相同的原始需求身份。
+  - [ ] 只要存在任一未确认的推断需求、产品问题或目标行为 unknown，就使用 `ready-for-clarification`。只有“推断需求”明确写 `- 无未确认的推断需求。` 且“待确认问题”明确写 `- 无待确认问题。` 时，才允许使用 `no-clarification-required`。
+  - [ ] 写入前完成全部分析内容。若判断无需澄清，先按 Step 2 直接询问用户是否需要补充；收到“无需补充”或补充内容并重新完成判断后再写入正式文件。
+  - [ ] 将完整分析写入正式 `<project-root>/docs/product-analysis/<requirement-id>/product-analysis.md`，此时标记为“已写入、未冻结”；不得创建空文件、占位文件或另一个候选版本。
+  - [ ] 立即对正式文件运行 `node <skill-root>/scripts/validate-product-analysis.mjs <product-analysis.md> --target <frontend|backend|both>`，target 使用 Step 0 的归一化值。校验失败时，根据明确错误重新生成并覆盖尚未冻结的正式文件，然后重新校验；执行中断后也可在下一轮继续修正同源未冻结草稿。未返回 exit 0 前禁止生成 Clarification 或进入 Step 2 的逐题决策澄清。上一条“无需澄清”场景的内容补充确认是正式写入前的唯一例外。
+  - [ ] 正式文件首次校验返回 exit 0 时，立即在当前执行上下文中把该路径标记为禁止写入并视为冻结；从该时刻起，当前及后续澄清轮次不得再调用写工具处理该路径。不得在校验通过与冻结之间修改、格式化或重新渲染文件。
+- [ ] Step 2：决策树访谈 ⚠️ REQUIRED
+  - [ ] 读取 `references/clarification-and-knowledge.md` 第 2 节（含回答复核）和 `references/requirement-clarification-schema.md`。
+  - [ ] 每轮先给推荐答案和理由，只问一个决策问题并等待回答；不得合并多个问题，也不得仅因用户已回答就标记 confirmed。
+  - [ ] 所有分支收敛后，必须汇总范围、规则、状态/边界、已确认的默认产品行为和非目标，并单独询问用户是否确认以上共同理解或需要补充/修正；未收到明确确认前保持 `pending`。用户补充或修正后重新收敛、重新汇总并再次请求确认。
+  - [ ] 仅当不存在任何未确认推断需求、产品问题或目标行为 unknown 时，才跳过决策问题访谈并直接询问用户是否还有内容需要补充；用户补充后重新判断，只有用户明确表示无需补充或确认继续后，才能生成 complete 产物。
+  - [ ] 本步只做访谈与回答复核，不执行合成规则；合成在 Step 4。
 - [ ] Step 3：记录 Requirement Clarification ⚠️ REQUIRED
-  - [ ] 记录总澄清轮数，并为每个问题记录所属轮次、推荐答案、用户回答、最终决策、来源和目标位置；依赖、备选、代码证据和未确认影响仅在适用时记录。
-  - [ ] P0/P1 未解决时保持 `pending`；P2 延后必须给出默认行为和影响。
+  - [ ] 每轮访谈后更新 Clarification：记录总澄清轮数，并为每个问题记录所属轮次、推荐答案、用户原始回答、最终决策、决策来源和目标位置；依赖和备选仅在适用时记录。
+  - [ ] 所有实际生成的 `Q-*` 都是产品决策，必须由用户确认；P0、P1 或 P2 只要未解决都保持 `pending`，不得通过默认假设完成需求。
+  - [ ] 用户确认共同理解后，在决策索引写入 `- 共同理解：已确认`，再进入 Step 4 将 Clarification/Product Requirement 标为 `complete`。
 - [ ] Step 4：重新生成 Product Requirement ⛔ BLOCKING
-  - [ ] 读取 `references/product-requirement-schema.md` 和 `references/acceptance-criteria.md`。
-  - [ ] 基于原始需求、冻结的 Product Analysis 和 Clarification 重新生成，不做字符串回写。
-  - [ ] 优先级：用户确认决策 > 原始明确需求 > 已确认默认值 > 模型推断；代码库事实只用于理解现状、发现冲突和辅助澄清，不构成独立需求来源。
-  - [ ] 不得把 `CODE-FACT-*`、仓库路径、代码符号、模块结构、数据表或当前实现过程原样写入 Product Requirement；代码事实只有经用户确认或被原始需求明确要求时，才能转换为不含实现细节的产品规则，证据仍只保留在 Product Analysis 和 Clarification。
-  - [ ] 把决策自然合并到范围、规则、故事、逐故事输出规范和 AC，并在决策追溯中登记。
+  - [ ] 读取 `references/product-requirement-schema.md`、`references/acceptance-criteria.md` 和 `references/clarification-and-knowledge.md` 第 3 节；按契约与 AC 规则重新生成，不做字符串回写。
+  - [ ] 澄清进行中：每次合成后重写 `pending` Product Requirement，并保留“未决事项”；不得标为 `complete`。
+  - [ ] pending Clarification 与 pending Product Requirement 写入后，使用 `--allow-pending` 运行二者校验器；两者状态必须一致。`--allow-pending` 仅用于内部中间产物校验，不得用于最终交付或下游消费。
+  - [ ] 共同理解已确认后：生成 `complete` Product Requirement；Clarification 同步为 `complete`。
+  - [ ] 优先级：用户确认决策 > 原始明确需求 > 当前有效的知识库项目规范 > 模型推断；知识库/代码事实只用于理解项目规范与现状、发现冲突和辅助澄清，不得发明产品意图。
+  - [ ] 不得把 `KB-FACT-*`、`CODE-FACT-*`、知识库/仓库路径或代码符号原样写入 Product Requirement。
   - [ ] 用户故事只描述角色/使用方、目标/能力、价值、入口/触发方式和 AC 引用；详细产品行为只写在同 ID 输出规范中，正式 AC 嵌入该输出规范。
-  - [ ] target 为 `backend` 或 `both` 时，后端故事只定义 API 的业务能力、输入输出语义、权限和规则；具体方法、路径及 DTO 留给依赖 skill。
+  - [ ] 逐个检查每个 `FE-US-*` 的同 ID 输出规范并写入“页面路由”，不得因多个故事共享页面而省略或合并该字段。独立页面写以 `/` 开头的目标 URL；组件、弹窗或抽屉无独立路由时写“`不适用；嵌入 /目标路径 页面`”（`/目标路径` 替换为真实路径）。
+  - [ ] target 为 `backend` 或 `both` 时，后端故事只定义 API 的业务能力、输入输出语义、权限和规则；触发方式写 `API（Web）`、`API（Remote）` 或 `API（Web + Remote）`。Web + Remote 表示同一能力需要两个接口；具体 Method+Path 及 DTO 留给依赖 skill。
+  - [ ] 后端分页：每页条数允许值按“原始需求/用户确认 > 有效知识库分页规范 > 默认集合 `10`、`20`、`50`、`100`”确定。参数名、必填性、默认值和其他契约不得从知识库 API 文档自动带入。
 - [ ] Step 5：验证并交付 ⛔ BLOCKING
-  - [ ] 向 Product Analysis 和 Product Requirement 校验器传入归一化 target，再运行三个产物校验器和 validator matrix。
-  - [ ] 确认 `product-analysis.md` 与进入澄清前的冻结版本完全一致。
-  - [ ] 只有所有命令返回 0 才能声明完成。
+  - [ ] 再次以只读方式向已冻结 Product Analysis 和 Product Requirement 校验器传入归一化 target，只运行三个当前产物校验器；Product Analysis 在 Step 1 已通过正式文件校验，本步不得因任何原因修改它。交付路径不得使用 `--allow-pending`。
+  - [ ] Requirement Clarification 校验器核对 Product Analysis/Clarification 的原始需求身份，以及三个产物的 requirement ID、analysis scope 和状态；冻结不做脚本校验。
+  - [ ] 只有所有命令返回 0 才能声明完成。本步只交付 complete V4 Product Requirement；下游 `analyze-product-dependencies` 首选消费该产物，其 `--target` 可为本次 `analysis_scope` 的子集。
+  - [ ] `test-validators.mjs` 仅在修改本 skill 的输出契约、schema、validator、artifact version、示例、forward-test contract，或发布/安装/回归验证时运行；普通需求分析不运行 validator matrix。
 
 完整格式示例按需读取 `references/example.md`；维护或 forward-test 时读取 `references/forward-test-cases.md`。不要为了执行校验而阅读脚本，直接运行。
 
 ## 完成规则
 
-- `no-clarification-required` 仍生成三个产物；Clarification 使用“澄清结论、来源、合并结果”三章精简结构。
-- `complete` Clarification 的全部分支必须 resolved，P0/P1 必须由用户确认，每个决策标记必须进入 Product Requirement 决策追溯。
-- Product Requirement 必须自包含；读者不得依赖聊天、Product Analysis 或 Clarification 才能理解需求。
-- Product Requirement 只描述目标产品行为，不记录代码库事实、证据位置或当前实现；不得出现 `CODE-FACT-*`、仓库文件路径、代码级类/函数/组件符号、模块调用关系、数据表名或实现算法。
+- `no-clarification-required` 仍生成三个产物，但只适用于“推断需求”为 `- 无未确认的推断需求。` 且“待确认问题”为 `- 无待确认问题。` 的场景；Clarification 使用“澄清结论、来源、合并结果”三章精简结构，并记录 `- 内容补充：用户已确认无需补充`；不得仅凭模型判断需求足够明确就自动完成。
+- 需要澄清的 `complete` Clarification：全部分支 resolved，所有实际 `Q-*` 为 `confirmed/user`，决策索引含 `- 共同理解：已确认`，每个 `DEC-Q-*` 进入 Product Requirement 决策追溯。
+- Product Requirement 必须自包含；只描述目标产品行为，不得出现 `KB-FACT-*`、`CODE-FACT-*`、知识库/仓库文件路径、代码级类/函数/组件符号、模块调用关系、数据表名、证据位置或实现算法。
 - 不得生成独立用户角色、验收标准汇总、前后端契约、Open Questions、测试建议或独立边界 case 章节。
 
+## Anti-Patterns
+
+- 把首次写入正式 `product-analysis.md` 等同于冻结，未运行 validator 就进入澄清；或在 validator 非 0 时冻结错误版本。
+- 正式文件校验通过后、冻结前再次渲染或格式化；或冻结后以“修复校验问题”为由继续修改。
+- 回写、覆盖、格式化、移动或删除已冻结的 `product-analysis.md`。
+- 把 `KB-FACT-*`、`CODE-FACT-*`、知识库/仓库路径、`*Controller/*Service` 符号或“证据位置”写入 Product Requirement。
+- 未获用户明确确认（含共同理解确认）就把 Clarification/Product Requirement 标为 `complete`。
+- 无需澄清时未询问用户是否需要补充，或未收到明确的无需补充/继续确认就生成产物。
+- `kb-design-assist` 为 `unavailable` 时，未让用户选择修复或跳过就继续代码库降级或生成 complete 产物。
+- 在每个新 requirement 开始时跳过知识库、先探索代码库，或用“需求简单/未涉及项目规范”记录未执行状态。
+- 用默认假设消掉未解决的 P0/P1/P2。
+- 把推断需求、含糊需求、缺失产品行为、冲突或多种合理解释留在 Product Analysis 中，却不进入用户澄清。
+- 在 Product Analysis 写正式 `AC-*` 或 Given/When/Then。
+- 任何前端故事的同 ID Product Analysis 或 Product Requirement 输出规范缺少“页面路由”，或因共享页面而只在其中一个故事中填写。
+- 输入已给出分页允许值时，用知识库规范或默认 `10/20/50/100` 覆盖；或从知识库/API 文档自动带入路径、方法、参数名、必填性、默认值、响应、错误码或 DTO。
+- 生成独立用户角色、验收标准汇总、前后端契约、Open Questions、测试建议或边界 case 章节。
+
+## 交付前自检
+
+声明完成前逐项确认，任一不满足不得交付：
+
+- [ ] 三个 V4 产物写入同一 `docs/product-analysis/<requirement-id>/`，共享同一 `requirement_id`，且不含可推导的项目根或来源路径 frontmatter。
+- [ ] 正式 `product-analysis.md` 已先写入并使用归一化 target 通过 Product Analysis validator；首次 exit 0 后立即冻结，且冻结前没有开始逐题澄清。
+- [ ] validator 首次通过并冻结后，没有再次对 `product-analysis.md` 调用任何写入、格式化、移动或删除工具，正文、frontmatter 和路径保持不变。
+- [ ] Product Analysis 与 Clarification 记录相同的原始需求身份。
+- [ ] `complete` 场景下所有实际 `Q-*` 均为 `confirmed/user`，无未确认的产品行为或默认假设。
+- [ ] 三个当前产物校验器全部返回 exit 0；任一非 0 都不算完成。
+
 ## Validation
 
 把 `<skill-root>` 解析为本 `SKILL.md` 所在目录，全部参数使用绝对路径：
@@ -84,7 +131,15 @@ IRON LAW：`product-analysis.md` 只能生成一次。首次写入成功后，
 node <skill-root>/scripts/validate-product-analysis.mjs <product-analysis.md> --target <frontend|backend|both>
 node <skill-root>/scripts/validate-product-requirement.mjs <product-requirement.md> --target <frontend|backend|both>
 node <skill-root>/scripts/validate-requirement-clarification.mjs <product-analysis.md> <requirement-clarification.md> <product-requirement.md>
-node <skill-root>/scripts/test-validators.mjs
 ```
 
-澄清中的中间产物可加 `--allow-pending`；通过 pending 校验不代表完成。
+使用以下命令计算原始需求身份：
+
+```bash
+node <skill-root>/scripts/compute-source-identity.mjs inline-source <包含准确 inline 需求正文的临时文件>
+node <skill-root>/scripts/compute-source-identity.mjs file-source <原始需求文件>
+```
+
+需要澄清时，Clarification 与 Product Requirement 都为 `pending` 后才可对二者加 `--allow-pending`。该参数保持默认 fail-closed：不带参数时必须为 `complete`；下游和最终交付禁止使用。
+
+维护或发布时额外运行 `node <skill-root>/scripts/test-validators.mjs`。

package/skills/analyze-product-requirements/references/acceptance-criteria.md

@@ -1,17 +1,11 @@
 # 详细验收标准规则
 
-## 目录
-
-- 基本要求
-- 分段最低要求
-- 前端示例
-- 后端示例
-- 不合格写法
-
 ## 基本要求
 
 每条验收标准必须独立可执行、结果可观察，并使用 Given/When/Then。一个用户故事存在多个关键流程时，拆成多个 AC，不要把互不相关的行为塞入一条 AC。
 
+涉及状态变量、空数据、loading、error、disabled、错误提示或恢复入口时，Then 与异常场景必须使用已查明的项目枚举、共享组件、文案和交互规范；不得用通用占位状态替代项目规范。明确需求与项目规范冲突时先澄清目标行为。
+
 每条 AC 必须说明：
 
 1. Given：用户身份、权限、业务数据、系统状态和必要依赖。
@@ -57,6 +51,8 @@ Then：
 
 ## 后端示例
 
+输出规范与故事不得自行发明 HTTP 方法、路径或 DTO。AC 的 When/Then 使用可观察的业务触发与结果；仅当原始需求或用户澄清已明确给出方法/路径时，才可在 AC 中原样引用。
+
 ```md
 #### AC-BE-001 返回退款处理中状态
 
@@ -65,17 +61,17 @@ Given：
 - 退款记录状态为 processing。
 
 When：
-- 调用 GET /orders/{orderId}/refund-status。
+- 用户请求查询该订单的退款状态。
 
 Then：
-- HTTP 状态码为 200。
+- 返回成功状态。
 - refundStatus 为 processing，failedReason 为 null。
 - currentStep 与退款记录一致，updatedAt 使用约定时间格式。
 - 响应不得包含内部错误堆栈或其他用户数据。
 
 异常场景：
-- 订单不存在时返回 404 和标准错误结构。
-- 无权访问时返回 403，且不得泄露订单详情。
+- 订单不存在时返回标准“资源不存在”错误结构。
+- 无权访问时返回标准“禁止访问”错误，且不得泄露订单详情。
 ```
 
 ## 不合格写法

package/skills/analyze-product-requirements/references/clarification-and-knowledge.md

@@ -2,20 +2,33 @@
 
 ## 1. 知识库与代码事实
 
-未执行知识检索时明确记录 `not-integrated`/`not-executed`，不得声称“未命中”或模拟记录。
+每个新 requirement 先从需求内容形成定向检索计划，再读取并执行 `kb-integration.md`，直接沿用其中的状态机、用户处置和降级边界。知识库门禁通过后才能预扫描项目资料和探索代码库；为核验实际实现而进行的代码搜索仍不得把代码现状冒充项目规范。
 
-提供代码仓库时只做定向事实搜索：认证、权限、状态枚举、相似能力、字段类型、统一错误结构。事实使用 `CODE-FACT-*`，包含事实、证据位置和需求影响。代码只能回答现状，不能替代用户决定目标需求。
+项目资料预扫描的时机与顺序按 `kb-integration.md` 执行；命中内容不得替代真实代码证据。
 
-知识或代码与需求冲突时：保留来源证据、生成澄清问题、用户裁决前不选边。
+有效知识结果使用 `KB-FACT-*`，包含规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响和置信度。知识库用于说明项目要求，代码库用于说明当前实现；知识库命中不能把代码文件、符号或调用关系标记为 confirmed。
+
+提供代码仓库且当前宿主支持隔离的只读代码侦察 agent 时，优先将定向事实搜索交给该 agent：认证、权限、状态枚举、相似能力、字段类型、统一错误结构、设计系统、空数据及 loading/error 展示。委派内容仅包含待查问题、允许搜索的范围和适用的知识库规范结论，当前会话只保留结论、证据位置、置信度和未定位项。当前宿主不支持该能力时，由当前 agent 先限定故事、问题、目录或关键词，再沿直接相关引用定向搜索，不做无边界扫描；不得因此阻断流程或扩大搜索范围。文件搜索优先使用 `rg --files` 和 `rg`，没有 `rg` 时使用宿主提供的等价只读搜索能力，不得降低证据标准。事实使用 `CODE-FACT-*`，包含事实、证据位置和需求影响。代码只能回答现状，不能替代用户决定目标需求。
+
+scope 包含 backend 且涉及分页时：每页条数允许值以原始需求/用户确认为准；未说明时优先采用 `kb-design-assist` 返回的当前有效分页规范，仍未查明才使用默认集合 `10`、`20`、`50`、`100`。不得把知识库/API 文档的路径、方法、参数名、必填性、默认值、响应、错误码或 DTO 自动合并为产品需求。分析状态变量、空数据、loading、error、disabled 或兜底行为时，优先以当前有效知识库规范为项目规范来源，再核验仓库级指令、设计系统、共享组件和同类实现；未查明时写 unknown，不得用通用惯例冒充项目规范。
+
+unknown 按影响分流：会改变范围、权限、业务规则、用户可感知输出/状态/边界或验收结果时，提炼成目标行为的产品决策并进入澄清；只涉及代码位置、符号、实现方式、技术复用或证据缺失时，保留为 `CODE-FACT-*` unknown 并交给依赖分析，不向用户提问，也不进入 Product Requirement。不得询问用户“代码在哪里”；应询问用户希望产品表现为何。
+
+scope 包含 backend 且需求涉及接口/API 时，Web、Remote 或 Web + Remote 属于必须由用户确认的产品范围。只写笼统“接口/API”时生成一个澄清问题；确认结果写入现有“触发方式”，不得新增接口形态字段。Web + Remote 表示同一能力需要两个 HTTP 接口。
+
+知识库、代码或需求之间冲突时：保留来源证据、生成澄清问题、用户裁决前不选边。过期、适用范围不明、互相冲突或无来源定位的知识结果按 unknown 处理。
 
 ## 2. 决策树式访谈
 
-1. 从 Product Analysis 的推断、问题、输出规范和高风险默认值提取 3–6 个顶层 `BR-*` 分支。
+1. 从 Product Analysis 的全部推断需求、待确认问题和输出规范中的未确认产品内容提取顶层 `BR-*` 分支；每一项推断、含糊、缺失、冲突、多种合理解释或目标行为 unknown 都必须进入决策树，覆盖完整分支，不为满足数量制造分支。原始需求已明确且不存在歧义的行为直接作为 `source-requirement` 事实，不创建分支或问题。
 2. 标注分支依赖，从范围、权限、核心流程、数据语义等基础决策开始。
-3. 每轮只处理一个主要问题：先给推荐答案和理由，再提问并等待回答。同分支、同依赖链的子项可合并，不相关问题不得换装为一题。
-4. 收到回答后重新识别剩余模糊点；仅在它们会影响范围、输出或验收时开启下一轮。
-5. 一次助手提问与用户回答记为一轮，总轮数不得超过 3。第 3 轮后仍有 P0/P1 时保持 pending 并阻断 Product Requirement complete；P2 按已记录的默认行为和影响处理。
-6. 所有分支解决后，用一段话总结关键决策。
+3. 每轮只处理一个决策问题：先给推荐答案和理由，再提问并等待回答。任何两个待决子项都不得合并为一次提问。
+4. 收到回答后重新识别剩余推断、模糊点、缺失项、冲突和新引入的未定义产品内容；只要仍存在未确认产品问题或需求，就开启下一轮。
+5. 一次助手提问与用户回答记为一轮；轮数由未解决决策决定，不设置人为上限。
+6. 所有分支解决后，必须总结范围、规则、状态/边界、已确认的默认产品行为和非目标，并单独询问用户“是否确认以上共同理解，或是否需要补充/修正”。用户明确确认前保持 pending：可反复生成 pending Product Requirement（含“未决事项”），但不得标为 complete。
+7. 用户提出补充或修正时，将新内容纳入决策树，重新识别受影响分支与模糊点；收敛后必须重新输出完整的共同理解汇总并再次请求确认。只有用户明确确认当前汇总后，才能在 Clarification 决策索引写入 `- 共同理解：已确认` 并合成 complete Product Requirement。
+
+能从环境、知识库、代码或项目资料查明的是事实，必须按“需求驱动的知识库检索 → 项目资料预扫描 → 定向代码探索”的顺序先查证，不询问用户。完成事实查证后，需要在多个目标行为之间选择的产品决策才逐项交给用户确认。分页沿用第 1 节已确定的来源优先级。
 
 ### 回答复核
 
@@ -24,23 +37,23 @@
 任一条件不满足时：
 
 - 保留用户原始回答，`最终决策` 写“未形成”并说明具体模糊点。
-- P0/P1 使用 `pending-blocking`；P2 使用 `pending-non-blocking`，同时记录默认行为和未确认影响。
+- P0/P1 使用 `pending-blocking`；P2 可使用 `pending-non-blocking` 并记录未确认影响。任何级别未确认时都不得生成 complete Product Requirement。
 - 下一轮优先继续当前分支，明确指出上一轮回答仍不清晰的部分，并将问题收窄为可直接确认的决策点；不得原样重复问题或跳到其他分支。
 - 不得把模型推断、推荐答案或代码现状当作用户确认。
 
-当前问题明确后，再扫描其他未解决问题和本次回答新引入的模糊点。只有会改变范围、权限、核心流程、数据语义、输出行为或验收结果的问题才继续澄清；不影响产品行为的措辞和下游技术细节不消耗澄清轮次。
+当前问题明确后，再扫描全部推断需求、其他未解决问题和本次回答新引入的模糊点。只要内容属于产品需求或目标行为且尚未确认，就必须继续澄清；纯措辞、代码位置、符号、实现方式、技术复用和其他不构成产品需求的下游技术细节不消耗澄清轮次。
 
 问题等级：
 
 - P0：改变范围、权限、关键流程、数据语义或验收结果；必须由用户明确确认。
 - P1：可以推荐默认值，但必须经用户确认。
-- P2：可延后，但必须给出当前默认行为、影响和后续确认入口。
+- P2：可排到后续澄清轮次，但仍须用户确认后才能 complete；只要影响产品行为或验收就必须保持 pending。不影响产品行为的实现问题不属于 P2，按实现事实 unknown 处理。
 
-没有问题时跳过交互访谈，不伪造分支、问题或决策标记，但仍生成完整 Clarification 检查记录。
+只有“推断需求”为 `- 无未确认的推断需求。` 且“待确认问题”为 `- 无待确认问题。` 时，才跳过决策问题访谈；冻结 Product Analysis 和生成正式产物前，仍须直接询问用户“当前需求无需进一步澄清，是否还有内容需要补充”。用户补充内容时，将其并入本次输入后重新判断；只要出现新的推断、含糊、缺失、冲突或多种合理解释，就转入逐题澄清。只有用户明确表示无需补充或确认继续，才能生成 `no-clarification-required` 的 Product Analysis、complete Clarification 和 complete Product Requirement。不得把模型判断的“没有问题”自动视为用户确认，也不得为这次补充确认伪造 `BR-*`、`Q-*` 或 `DEC-Q-*`。
 
 ## 3. 合成规则
 
-Product Analysis 冻结不回写。`最终决策` 是合成最终需求的规范化事实；`目标位置` 指向需求范围、业务规则、故事、输出规范或 AC。
+Product Analysis 必须先写入正式路径，再对正式文件运行 validator；同源文件尚未通过校验时视为未冻结草稿，当前或后续轮次都可按错误继续修正，首次返回 exit 0 时立即冻结。冻结后不得回写，冻结只由 skill 提示词约束。Clarification 的“来源/澄清来源”记录相同的原始需求身份；`最终决策` 是合成最终需求的规范化事实；`目标位置` 指向需求范围、业务规则、故事、输出规范或 AC。
 
 三个产物必须写入同一 `<project-root>/docs/product-analysis/<requirement-id>/`。同目录来源使用相对路径，避免把个人机器绝对路径写入可交接产物。
 
@@ -48,7 +61,8 @@ Product Analysis 冻结不回写。`最终决策` 是合成最终需求的规范
 
 - 用户确认的推断转为正式需求。
 - 用户否定的推断删除或进入非目标。
-- 确认的默认值进入规则和故事。
+- 用户确认的推荐值或默认行为进入规则和故事，并保留用户决策来源。
+- 当前有效知识库规范可用于填补项目既定的状态、组件、文案、交互和分页允许值；合成时转换为产品语言，不保留 `KB-FACT-*`、知识库路径、搜索过程或纯实现规范名称。
 - 代码库事实只用于解释现状、识别冲突和支持澄清，不作为独立需求来源；未经用户确认且未被原始需求明确要求的代码现状不得进入 Product Requirement。
 - 需要合并的代码事实必须转换为目标产品语言，只保留用户可感知的行为、业务规则和验收结果；`CODE-FACT-*`、证据路径、代码符号、模块结构、数据表和实现过程继续留在 Product Analysis 或 Clarification。
 - 决策影响故事时重新生成故事与 AC，不只在决策列表堆积答案。

package/skills/analyze-product-requirements/references/example.md

@@ -1,4 +1,4 @@
-# V3 完整流程示例
+# V4 无需澄清路径示例
 
 需求：登录用户在个人资料页修改昵称；昵称 2–20 个字符；保存失败时保留输入并允许重试；不修改头像。
 
@@ -6,16 +6,28 @@
 
 ```md
 ---
-artifact_version: "3.0"
+artifact_version: "4.0"
 artifact_type: product-analysis
 requirement_id: profile-nickname
-project_root: ../../..
 analysis_scope: frontend
 analysis_status: no-clarification-required
-source_requirement: inline
-repository_root: none
 ---
 
+## 1. 原始需求
+- 原始需求身份：inline:sha256:<64位小写十六进制摘要>
+- 正文：登录用户在个人资料页修改昵称；昵称 2–20 个字符；保存失败时保留输入并允许重试；不修改头像。
+
+## 4. 需求分析
+### 4.1 明确需求
+- 登录用户可以在个人资料页修改自己的昵称。
+### 4.2 推断需求
+- 无未确认的推断需求。
+### 4.3 待确认问题
+- 无待确认问题。
+- 理由：范围、权限、校验、失败恢复和非目标均已由原始需求明确。
+### 4.4 初步非目标
+- 不修改头像。
+
 ## 6. 初步前端用户故事
 ### FE-US-001 修改昵称
 - 角色：已登录用户
@@ -27,6 +39,7 @@ repository_root: none
 ## 7. 初步前端输出规范
 ### FE-US-001 修改昵称
 - 页面/组件：个人资料页、昵称编辑表单
+- 页面路由：/account/profile
 - 展示内容：当前昵称、字符计数、校验提示
 - 交互动作：编辑、保存、取消、重试
 - UI 状态：normal、dirty、loading、success、error、disabled
@@ -35,16 +48,20 @@ repository_root: none
 - 边界处理：保存失败时保留输入，不得静默失败
 ```
 
-Product Analysis 不创建正式 AC。
+Product Analysis 不创建正式 AC；每个前端故事的同 ID 初步输出规范都填写页面路由。
 
 ## 无需澄清记录
 
+生成以下产物前，先询问用户是否还有内容需要补充；用户明确回复无需补充后再冻结 Product Analysis。
+
 ```md
 ## 1. 澄清结论
 - 状态：no-clarification-required
 - 原因：范围、权限、数据语义和验收结果已经明确。
+- 内容补充：用户已确认无需补充
 ## 2. 来源
 - Product Analysis：./product-analysis.md
+- 原始需求身份：inline:sha256:<与 Product Analysis 一致的摘要>
 ## 3. 合并结果
 - Product Requirement 根据明确需求生成，无额外决策标记。
 ```
@@ -63,6 +80,7 @@ Product Analysis 不创建正式 AC。
 ## 6. 前端输出规范
 ### FE-US-001 修改昵称
 - 页面/组件：个人资料页、昵称编辑表单
+- 页面路由：/account/profile
 - 展示内容：当前昵称、字符计数、校验提示
 - 交互动作：编辑、保存、取消、重试
 - UI 状态：normal、dirty、loading、success、error、disabled