@tea-agent/loop-agent 0.38.2 → 0.38.4

package/scripts/release-source-binding.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * release-source-binding: resolve the exact source SHA behind a selected next
+ * build, and validate cut-release-line preconditions.
+ *
+ * The next tarball carries dist/build-stamp.json { version, gitSha }. A release
+ * line must be cut from THAT commit — never from a floating main HEAD at
+ * workflow runtime. This module provides:
+ *
+ * - resolveSourceBinding: given a next version, return its gitSha (from the
+ *   registry tarball build stamp) and validated facts.
+ * - validateCutPreconditions: line monotonicity, branch absence, no parallel
+ *   un-promoted train, source sha on main.
+ */
+import { execFileSync } from "node:child_process";
+import process from "node:process";
+
+export const NEXT_TARGET_ENV = "LOOP_AGENT_NEXT_TARGET";
+
+const FORMAL_LINE_RE = /^\d+\.\d+$/;
+
+/**
+ * Read build stamp fields from a packed tarball without installing it.
+ * @param {string} tarballPath
+ * @param {(cmd: string, args: string[]) => string} [run]
+ */
+export function readTarballBuildStamp(tarballPath, run = runCommand) {
+	const listing = run("tar", ["-tzf", tarballPath]);
+	const stampEntry = listing
+		.split("\n")
+		.map((line) => line.trim())
+		.find((line) => /\/dist\/build-stamp\.json$/.test(line));
+	if (!stampEntry) {
+		throw new Error(`tarball ${tarballPath} does not contain dist/build-stamp.json`);
+	}
+	const stampJson = run("tar", ["-xzf", tarballPath, "-O", stampEntry]);
+	let parsed;
+	try {
+		parsed = JSON.parse(stampJson);
+	} catch (error) {
+		throw new Error(
+			`build stamp is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	if (typeof parsed.gitSha !== "string" || !/^[0-9a-f]{7,40}$/i.test(parsed.gitSha)) {
+		throw new Error("build stamp gitSha missing or malformed");
+	}
+	return { gitSha: parsed.gitSha, version: parsed.version ?? null };
+}
+
+function runCommand(cmd, args) {
+	return execFileSync(cmd, args, {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+}
+
+/**
+ * Download an exact next version tarball (without install scripts) into a
+ * directory and return its path.
+ */
+export function downloadNpmTarball(version, destDir, run = runCommand) {
+	run("npm", [
+		"pack",
+		`@tea-agent/loop-agent@${version}`,
+		"--pack-destination",
+		destDir,
+	]);
+	const listing = run("ls", [destDir]);
+	const file = listing
+		.split("\n")
+		.map((line) => line.trim())
+		.find((line) => line.endsWith(".tgz"));
+	if (!file) throw new Error(`npm pack did not produce a tarball in ${destDir}`);
+	return `${destDir}/${file}`;
+}
+
+/**
+ * Pure checks for cutting a release line.
+ *
+ * @param {object} input
+ * @param {string} input.selectedNextVersion e.g. "0.37.0-next.42"
+ * @param {string} input.releaseLine e.g. "0.37"
+ * @param {string} input.sourceSha commit the next tarball was built from
+ * @param {string[]} input.remoteBranches remote release branch names (e.g. ["release/0.36"])
+ * @param {string|null} [input.latestFormalVersion] current npm latest (for reference in results)
+ * @param {(sha: string) => boolean} [input.shaOnMain] whether sha is an ancestor of origin/main
+ * @returns {{ok: true} | {ok: false, reason: string, detail?: string}}
+ */
+export function validateCutPreconditions(input) {
+	const nextMatch = /^(\d+)\.(\d+)\.(0|[1-9]\d*)-next\.([0-9]\d*)$/.exec(
+		String(input.selectedNextVersion ?? ""),
+	);
+	if (!nextMatch) {
+		return {
+			ok: false,
+			reason: "invalid-selected-next",
+			detail: `selectedNextVersion=${input.selectedNextVersion}`,
+		};
+	}
+	const nextLine = `${nextMatch[1]}.${nextMatch[2]}`;
+	const patch = nextMatch[3];
+	if (patch !== "0") {
+		return {
+			ok: false,
+			reason: "selected-next-not-minor-zero",
+			detail: `next target patch must be 0, got ${patch}`,
+		};
+	}
+	if (!FORMAL_LINE_RE.test(String(input.releaseLine ?? ""))) {
+		return {
+			ok: false,
+			reason: "invalid-release-line",
+			detail: `releaseLine=${input.releaseLine}`,
+		};
+	}
+	if (input.releaseLine !== nextLine) {
+		return {
+			ok: false,
+			reason: "line-mismatch",
+			detail: `selected next ${nextLine} vs release line ${input.releaseLine}`,
+		};
+	}
+	if (!/^[0-9a-f]{7,40}$/i.test(String(input.sourceSha ?? ""))) {
+		return {
+			ok: false,
+			reason: "invalid-source-sha",
+			detail: `sourceSha=${input.sourceSha}`,
+		};
+	}
+	const branches = Array.isArray(input.remoteBranches)
+		? input.remoteBranches
+		: [];
+	const existing = branches.find((b) => b === `release/${input.releaseLine}`);
+	if (existing) {
+		return {
+			ok: false,
+			reason: "release-branch-exists",
+			detail: existing,
+		};
+	}
+	const existingLines = branches
+		.map((b) => /^release\/(\d+)\.(\d+)$/.exec(b))
+		.filter(Boolean)
+		.map((m) => ({ major: Number(m[1]), minor: Number(m[2]), name: m[0] }));
+	const [cutMajor, cutMinor] = input.releaseLine.split(".").map(Number);
+	const higher = existingLines.find(
+		(l) => l.major > cutMajor || (l.major === cutMajor && l.minor > cutMinor),
+	);
+	if (higher) {
+		return {
+			ok: false,
+			reason: "line-not-monotonic",
+			detail: `higher release branch exists: ${higher.name}`,
+		};
+	}
+	if (input.shaOnMain !== undefined && input.shaOnMain(input.sourceSha) === false) {
+		return {
+			ok: false,
+			reason: "source-sha-not-on-main",
+			detail: input.sourceSha,
+		};
+	}
+	return { ok: true };
+}
+
+/**
+ * Resolve the next target line from env override (LOOP_AGENT_NEXT_TARGET).
+ * Returns null when unset/invalid — callers decide the fallback derivation.
+ */
+export function nextTargetFromEnv(env = process.env) {
+	const raw = env[NEXT_TARGET_ENV];
+	if (!raw) return null;
+	return /^\d+\.\d+\.0$/.test(raw) ? raw : null;
+}
+
+// CLI 入口安全判断（argv[1] 非合法 file: URL 时 new URL 会抛异常）
+function scriptEntryHref(argv1) {
+	try {
+		return argv1 ? new URL(`file://${argv1}`).href : "";
+	} catch {
+		return "";
+	}
+}
+
+const invokedAsScript =
+	Boolean(process.argv[1]) && import.meta.url === scriptEntryHref(process.argv[1]);
+
+if (invokedAsScript) {
+	const args = Object.fromEntries(
+		process.argv
+			.filter((arg) => arg.startsWith("--"))
+			.map((arg) => {
+				const [key, ...value] = arg.replace(/^--/, "").split("=");
+				return [key, value.join("=") || "true"];
+			}),
+	);
+	if (args["self-test"]) {
+		const scenario = String(args["self-test"]);
+		const scenarios = {
+			"cut-ok": () =>
+				validateCutPreconditions({
+					selectedNextVersion: "0.37.0-next.42",
+					releaseLine: "0.37",
+					sourceSha: "abc1234567890abcdef",
+					remoteBranches: ["release/0.36"],
+				}),
+			"cut-exists": () =>
+				validateCutPreconditions({
+					selectedNextVersion: "0.37.0-next.42",
+					releaseLine: "0.37",
+					sourceSha: "abc1234567890abcdef",
+					remoteBranches: ["release/0.36", "release/0.37"],
+				}),
+			"cut-not-monotonic": () =>
+				validateCutPreconditions({
+					selectedNextVersion: "0.37.0-next.42",
+					releaseLine: "0.37",
+					sourceSha: "abc1234567890abcdef",
+					remoteBranches: ["release/0.38"],
+				}),
+			"cut-line-mismatch": () =>
+				validateCutPreconditions({
+					selectedNextVersion: "0.37.0-next.42",
+					releaseLine: "0.38",
+					sourceSha: "abc1234567890abcdef",
+					remoteBranches: [],
+				}),
+			"cut-sha-not-on-main": () =>
+				validateCutPreconditions({
+					selectedNextVersion: "0.37.0-next.42",
+					releaseLine: "0.37",
+					sourceSha: "abc1234567890abcdef",
+					remoteBranches: [],
+					shaOnMain: () => false,
+				}),
+		};
+		const run = scenarios[scenario];
+		if (!run) {
+			process.stderr.write(`unknown self-test scenario: ${scenario}\n`);
+			process.exitCode = 2;
+		} else {
+			process.stdout.write(`${JSON.stringify(run())}\n`);
+		}
+	} else {
+		process.stderr.write(
+			"usage: node scripts/release-source-binding.mjs --self-test=<scenario>\n",
+		);
+		process.exitCode = 2;
+	}
+}

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

@@ -48,8 +48,9 @@ IRON LAW：`product-analysis.md` 必须先写入正式路径，再对该正式
   - [ ] 知识库状态为 `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-*`、ai_workspace 项目资料、仓库规范文档）及代码现状事实（`CODE-FACT-*`）逐条比对，分类为 一致 / 规范补充 / 冲突 / 无规则。分类为"冲突"的条目必须逐条进入待确认问题，标注"输入声明 vs 规范/代码声明"与冲突来源，用户裁决前不选边。该核对是强制步骤，任何"输入明确"都不构成豁免；规范补充仅适用于规范类事实，代码现状在输入未说明时按 unknown 分流，不得静默填补。
   - [ ] 汇总原始需求、`KB-FACT-*`、项目资料与 `CODE-FACT-*`，识别可查明事实、冲突、unknown 和必须由用户选择的目标行为；完成以上顺序后才生成待确认问题并进入 Step 2。
-  - [ ] 区分明确需求、推断需求和待确认问题。推断需求一律视为未确认产品内容；每一项推断需求以及任何含糊、缺失、冲突或存在多种合理解释的产品问题，都必须进入 Step 2 逐题向用户澄清，不得因模型认为推荐答案合理而跳过。
+  - [ ] 区分明确需求、推断需求和待确认问题。推断需求一律视为未确认产品内容；每一项推断需求以及任何含糊、缺失、冲突或存在多种合理解释的产品问题，都必须进入 Step 2 逐题向用户澄清，不得因模型认为推荐答案合理而跳过。与有效规范或代码现状冲突的行为不属于"明确需求"，不得按 `source-requirement` 直接合并；冲突按 unknown 同款边界分流：影响范围、权限、业务规则、用户可感知输出/状态/边界或验收结果的冲突必须澄清，纯实现/技术细节冲突只记录事实、不生成问题。
   - [ ] scope 包含 backend 且需求涉及接口/API 时，必须确认实现范围为 Web、Remote 或 Web + Remote；只写笼统“接口/API”视为待确认问题。不得依据知识库或代码现状替用户选择。
   - [ ] 仅按 target 生成精简故事骨架和逐故事初步输出规范：`frontend` 只生成 `FE-US-*`，`backend` 只生成 `BE-US-*`，`both` 才生成两端。
   - [ ] Product Analysis 只记录验收关注点，不创建正式 `AC-*` 或完整 Given/When/Then。每个前端故事的同 ID 初步输出规范必须包含“页面路由”：独立页面写以 `/` 开头的目标 URL；组件、弹窗或抽屉无独立路由时写“`不适用；嵌入 /目标路径 页面`”（`/目标路径` 替换为真实路径）。
@@ -74,23 +75,23 @@ IRON LAW：`product-analysis.md` 必须先写入正式路径，再对该正式
   - [ ] 澄清进行中：每次合成后重写 `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 嵌入该输出规范。
   - [ ] 逐个检查每个 `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 文档自动带入。
+  - [ ] 后端分页：每页条数允许值与其他规则同等参与「输入↔规范一致性核对」。输入与有效分页规范冲突（含允许值集合的差异、子集或超集）时必须进入待确认问题澄清，用户裁决后以确认值为准；无冲突时按”用户确认 > 原始需求 > 有效知识库分页规范 > 默认集合 `10`、`20`、`50`、`100`”确定。参数名、必填性、默认值和其他契约不得从知识库 API 文档自动带入。
 - [ ] Step 5：验证并交付 ⛔ BLOCKING
   - [ ] 再次以只读方式向已冻结 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`。不要为了执行校验而阅读脚本，直接运行。
+完整格式示例按需读取 `references/example.md`（含无需澄清与输入↔规范冲突澄清两条路径）；维护或 forward-test 时读取 `references/forward-test-cases.md`。不要为了执行校验而阅读脚本，直接运行。
 
 ## 完成规则
 
-- `no-clarification-required` 仍生成三个产物，但只适用于“推断需求”为 `- 无未确认的推断需求。` 且“待确认问题”为 `- 无待确认问题。` 的场景；Clarification 使用“澄清结论、来源、合并结果”三章精简结构，并记录 `- 内容补充：用户已确认无需补充`；不得仅凭模型判断需求足够明确就自动完成。
+- `no-clarification-required` 仍生成三个产物，但只适用于”推断需求”为 `- 无未确认的推断需求。` 且”待确认问题”为 `- 无待确认问题。` 的场景，且必须完成「输入↔规范一致性核对」并在待确认问题记录 `- 一致性核对：…未发现冲突条目。`；Clarification 使用”澄清结论、来源、合并结果”三章精简结构，并记录 `- 内容补充：用户已确认无需补充`；不得仅凭模型判断需求足够明确就自动完成。
 - 需要澄清的 `complete` Clarification：全部分支 resolved，所有实际 `Q-*` 为 `confirmed/user`，决策索引含 `- 共同理解：已确认`，每个 `DEC-Q-*` 进入 Product Requirement 决策追溯。
 - Product Requirement 必须自包含；只描述目标产品行为，不得出现 `KB-FACT-*`、`CODE-FACT-*`、知识库/仓库文件路径、代码级类/函数/组件符号、模块调用关系、数据表名、证据位置或实现算法。
 - 不得生成独立用户角色、验收标准汇总、前后端契约、Open Questions、测试建议或独立边界 case 章节。
@@ -110,6 +111,8 @@ IRON LAW：`product-analysis.md` 必须先写入正式路径，再对该正式
 - 在 Product Analysis 写正式 `AC-*` 或 Given/When/Then。
 - 任何前端故事的同 ID Product Analysis 或 Product Requirement 输出规范缺少“页面路由”，或因共享页面而只在其中一个故事中填写。
 - 输入已给出分页允许值时，用知识库规范或默认 `10/20/50/100` 覆盖；或从知识库/API 文档自动带入路径、方法、参数名、必填性、默认值、响应、错误码或 DTO。
+- 输入与有效规范（知识库、ai_workspace、仓库规范）或代码现状冲突时，按"原始需求优先"静默采用输入而不进入澄清；分页允许值冲突也不例外。
+- 「输入↔规范一致性核对」漏掉任一证据通道，或把"规范补充"误判为"冲突"、把"冲突"静默当作"规范补充"处理，或用代码现状填补输入未说明的产品行为。
 - 生成独立用户角色、验收标准汇总、前后端契约、Open Questions、测试建议或边界 case 章节。
 
 ## 交付前自检

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

@@ -4,7 +4,7 @@
 
 每条验收标准必须独立可执行、结果可观察，并使用 Given/When/Then。一个用户故事存在多个关键流程时，拆成多个 AC，不要把互不相关的行为塞入一条 AC。
 
-涉及状态变量、空数据、loading、error、disabled、错误提示或恢复入口时，Then 与异常场景必须使用已查明的项目枚举、共享组件、文案和交互规范；不得用通用占位状态替代项目规范。明确需求与项目规范冲突时先澄清目标行为。
+涉及状态变量、空数据、loading、error、disabled、错误提示或恢复入口时，Then 与异常场景必须使用已查明的项目枚举、共享组件、文案和交互规范；不得用通用占位状态替代项目规范。明确需求与项目规范或代码现状冲突时先澄清目标行为。
 
 每条 AC 必须说明：
 

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

@@ -6,21 +6,21 @@
 
 项目资料预扫描的时机与顺序按 `kb-integration.md` 执行；命中内容不得替代真实代码证据。
 
-有效知识结果使用 `KB-FACT-*`，包含规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响和置信度。知识库用于说明项目要求，代码库用于说明当前实现；知识库命中不能把代码文件、符号或调用关系标记为 confirmed。
+有效知识结果使用 `KB-FACT-*`，包含规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响、置信度和与输入关系（一致 | 补充 | 冲突）。知识库用于说明项目要求，代码库用于说明当前实现；知识库命中不能把代码文件、符号或调用关系标记为 confirmed。
 
-提供代码仓库且当前宿主支持隔离的只读代码侦察 agent 时，优先将定向事实搜索交给该 agent：认证、权限、状态枚举、相似能力、字段类型、统一错误结构、设计系统、空数据及 loading/error 展示。委派内容仅包含待查问题、允许搜索的范围和适用的知识库规范结论，当前会话只保留结论、证据位置、置信度和未定位项。当前宿主不支持该能力时，由当前 agent 先限定故事、问题、目录或关键词，再沿直接相关引用定向搜索，不做无边界扫描；不得因此阻断流程或扩大搜索范围。文件搜索优先使用 `rg --files` 和 `rg`，没有 `rg` 时使用宿主提供的等价只读搜索能力，不得降低证据标准。事实使用 `CODE-FACT-*`，包含事实、证据位置和需求影响。代码只能回答现状，不能替代用户决定目标需求。
+提供代码仓库且当前宿主支持隔离的只读代码侦察 agent 时，优先将定向事实搜索交给该 agent：认证、权限、状态枚举、相似能力、字段类型、统一错误结构、设计系统、空数据及 loading/error 展示。委派内容仅包含待查问题、允许搜索的范围和适用的知识库规范结论，当前会话只保留结论、证据位置、置信度和未定位项。当前宿主不支持该能力时，由当前 agent 先限定故事、问题、目录或关键词，再沿直接相关引用定向搜索，不做无边界扫描；不得因此阻断流程或扩大搜索范围。文件搜索优先使用 `rg --files` 和 `rg`，没有 `rg` 时使用宿主提供的等价只读搜索能力，不得降低证据标准。事实使用 `CODE-FACT-*`，包含事实、证据位置、需求影响、证据类别（项目规范 | 代码现状）和与输入关系（一致 | 补充 | 冲突）。ai_workspace 项目资料与仓库规范文档统一记录为 `CODE-FACT-*` 并标注证据类别：项目规范；代码现状标注证据类别：代码现状。代码只能回答现状，不能替代用户决定目标需求。
 
-scope 包含 backend 且涉及分页时：每页条数允许值以原始需求/用户确认为准；未说明时优先采用 `kb-design-assist` 返回的当前有效分页规范，仍未查明才使用默认集合 `10`、`20`、`50`、`100`。不得把知识库/API 文档的路径、方法、参数名、必填性、默认值、响应、错误码或 DTO 自动合并为产品需求。分析状态变量、空数据、loading、error、disabled 或兜底行为时，优先以当前有效知识库规范为项目规范来源，再核验仓库级指令、设计系统、共享组件和同类实现；未查明时写 unknown，不得用通用惯例冒充项目规范。
+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 处理。
+执行「输入↔规范一致性核对」：将原始需求的每条明确声明与有效规范证据（`KB-FACT-*`、ai_workspace 项目资料、仓库规范文档，统一以 `KB-FACT-*`/`CODE-FACT-*` 记录并标注与输入关系）及代码现状事实（`CODE-FACT-*`）逐条比对，分类为 一致 / 规范补充 / 冲突 / 无规则。分类为"冲突"的条目必须进入待确认问题，保留双方声明与来源证据，用户裁决前不选边；"输入明确"不构成豁免。规范补充仅适用于规范类事实（`KB-FACT-*` 及"证据类别：项目规范"的 `CODE-FACT-*`），输入未说明时直接并入、不生成问题；代码现状不得静默填补产品行为。冲突按 unknown 同款边界分流：影响范围、权限、业务规则、用户可感知输出/状态/边界或验收结果的冲突必须逐条澄清；纯实现/技术细节冲突只标"与输入关系：冲突"、不生成问题，留待依赖分析。过期、适用范围不明、互相冲突或无来源定位的知识结果按 unknown 处理。
 
 ## 2. 决策树式访谈
 
-1. 从 Product Analysis 的全部推断需求、待确认问题和输出规范中的未确认产品内容提取顶层 `BR-*` 分支；每一项推断、含糊、缺失、冲突、多种合理解释或目标行为 unknown 都必须进入决策树，覆盖完整分支，不为满足数量制造分支。原始需求已明确且不存在歧义的行为直接作为 `source-requirement` 事实，不创建分支或问题。
+1. 从 Product Analysis 的全部推断需求、待确认问题和输出规范中的未确认产品内容提取顶层 `BR-*` 分支；每一项推断、含糊、缺失、冲突、多种合理解释或目标行为 unknown 都必须进入决策树，覆盖完整分支，不为满足数量制造分支。原始需求已明确、与有效规范及代码现状核对一致且不存在歧义的行为直接作为 `source-requirement` 事实，不创建分支或问题；与有效规范或代码现状冲突的行为视为存在歧义，必须进入决策树。
 2. 标注分支依赖，从范围、权限、核心流程、数据语义等基础决策开始。
 3. 每轮只处理一个决策问题：先给推荐答案和理由，再提问并等待回答。任何两个待决子项都不得合并为一次提问。
 4. 收到回答后重新识别剩余推断、模糊点、缺失项、冲突和新引入的未定义产品内容；只要仍存在未确认产品问题或需求，就开启下一轮。
@@ -32,7 +32,7 @@ scope 包含 backend 且需求涉及接口/API 时，Web、Remote 或 Web + Remo
 
 ### 回答复核
 
-收到用户回答后，先判断它是否直接覆盖当前问题的关键决策点、是否只有一种合理的产品解释、是否足以写成明确的范围/规则/输出行为/验收结果、是否与原始明确需求或已有决策冲突，以及是否引入新的未定义概念、例外条件或依赖关系。全部满足时才形成最终决策并标记为 confirmed。
+收到用户回答后，先判断它是否直接覆盖当前问题的关键决策点、是否只有一种合理的产品解释、是否足以写成明确的范围/规则/输出行为/验收结果、是否与原始明确需求、已有决策、有效规范或代码现状冲突，以及是否引入新的未定义概念、例外条件或依赖关系。全部满足时才形成最终决策并标记为 confirmed。
 
 任一条件不满足时：
 
@@ -43,6 +43,10 @@ scope 包含 backend 且需求涉及接口/API 时，Web、Remote 或 Web + Remo
 
 当前问题明确后，再扫描全部推断需求、其他未解决问题和本次回答新引入的模糊点。只要内容属于产品需求或目标行为且尚未确认，就必须继续澄清；纯措辞、代码位置、符号、实现方式、技术复用和其他不构成产品需求的下游技术细节不消耗澄清轮次。
 
+### 澄清轮中的规范冲突
+
+Product Analysis 冻结后，回答复核、用户回答或新证据暴露"用户回答或新增内容与有效规范/代码现状冲突"时：不得标记 confirmed；下一轮继续当前分支，把冲突双方声明与来源（`KB-FACT-*`/`CODE-FACT-*`）并列呈现，并在 Q-* 的"推荐理由"中成对写明，`最终决策` 记录用户裁决结果。已冻结的 Product Analysis 不回写。
+
 问题等级：
 
 - P0：改变范围、权限、关键流程、数据语义或验收结果；必须由用户明确确认。

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

@@ -24,6 +24,7 @@ analysis_status: no-clarification-required
 - 无未确认的推断需求。
 ### 4.3 待确认问题
 - 无待确认问题。
+- 一致性核对：已逐条比对知识库、ai_workspace、仓库规范与代码现状，未发现冲突条目。
 - 理由：范围、权限、校验、失败恢复和非目标均已由原始需求明确。
 ### 4.4 初步非目标
 - 不修改头像。
@@ -102,3 +103,52 @@ Then：
 ```
 
 故事与输出规范使用同一 ID；故事只引用 AC，AC 正文只在对应输出规范中出现一次。
+
+# 需要澄清路径示例（输入 ↔ 规范冲突）
+
+需求：查询订单列表支持分页，pageSize 允许值为 5、10、20。
+知识库命中分页规范：允许值为 20、50、100。
+
+## Product Analysis 外部事实与冲突条目
+
+```md
+## 5. 外部事实
+### 5.1 知识库事实
+- 检索状态：executed-hit。
+- KB-FACT-001：分页允许值为 20、50、100；来源：分页规范 v3 §2；版本：当前有效；与输入关系：冲突。
+### 5.2 代码库事实
+- CODE-FACT-001：列表接口已存在，pageSize 为必填；证据位置：列表 controller；证据类别：代码现状；与输入关系：一致。
+
+## 4. 需求分析
+### 4.3 待确认问题
+- P0：分页允许值集合冲突；冲突描述：输入声明「5、10、20」vs 规范声明「20、50、100」；冲突来源：KB-FACT-001；影响范围：backend。
+```
+
+## Clarification Q-* 冲突记录
+
+澄清轮中不新增字段，冲突双方声明成对写入推荐理由，最终决策记录裁决结果。
+
+```md
+### Q-001 分页允许值
+- 澄清轮次：1
+- 分支：BR-001
+- 优先级：P0
+- 影响范围：backend
+- 推荐答案：采用项目分页规范 20、50、100
+- 推荐理由：输入声明为 5、10、20，项目规范（KB-FACT-001：分页规范 v3 §2）为 20、50、100，两者冲突；代码现状（CODE-FACT-001）未约束允许值集合，需用户裁决。
+- 用户回答：仍使用 5、10、20
+- 最终决策：分页允许值为 5、10、20，覆盖项目分页规范默认值
+- 决策来源：user
+- 状态：confirmed
+- 决策标记：DEC-Q-001
+- 目标位置：后端输出规范分页约定
+```
+
+## Product Requirement 合成
+
+```md
+## 4. 业务规则
+- 分页允许值集合为 5、10、20（用户裁决，覆盖项目分页规范默认值）。
+## 7. 决策追溯
+- DEC-Q-001：分页允许值为 5、10、20，已合并到后端输出规范分页约定。
+```

package/skills/analyze-product-requirements/references/forward-test-cases.md

@@ -9,7 +9,7 @@
 需求：登录用户在个人资料页修改自己的昵称；昵称 2–20 个字符；保存失败时保留输入并允许重试；不修改头像。
 ```
 
-核对：生成产物前直接询问用户是否还有内容需要补充；未收到明确的“无需补充/确认继续”前不冻结 Product Analysis、不生成 complete 产物；用户确认后，三个产物都在 `<project-root>/docs/product-analysis/<requirement-id>/`，三者 `analysis_scope` 均为 `frontend`；Product Analysis 为 `no-clarification-required` 且不含正式 AC，其“原始需求”包含有效 `inline:sha256:*` 身份，每个前端初步输出规范包含有效页面路由；Clarification 使用三章精简结构、记录相同的原始需求身份和 `内容补充：用户已确认无需补充`，且没有 BR/Q/DEC；Product Requirement 为 complete，不含“默认假设”或“未决事项”；故事与同 ID 输出规范一一对应，每个前端规范均包含有效页面路由。
+核对：生成产物前直接询问用户是否还有内容需要补充；未收到明确的“无需补充/确认继续”前不冻结 Product Analysis、不生成 complete 产物；用户确认后，三个产物都在 `<project-root>/docs/product-analysis/<requirement-id>/`，三者 `analysis_scope` 均为 `frontend`；Product Analysis 为 `no-clarification-required` 且不含正式 AC，其“原始需求”包含有效 `inline:sha256:*` 身份，“待确认问题”包含 `- 一致性核对：…未发现冲突条目。` 行且无任何“与输入关系：冲突”事实，每个前端初步输出规范包含有效页面路由；Clarification 使用三章精简结构、记录相同的原始需求身份和 `内容补充：用户已确认无需补充`，且没有 BR/Q/DEC；Product Requirement 为 complete，不含“默认假设”或“未决事项”；故事与同 ID 输出规范一一对应，每个前端规范均包含有效页面路由。
 
 ## Case 2：需要逐题澄清
 
@@ -65,7 +65,7 @@
 
 核对：Product Analysis 可记录 `CODE-FACT-*`、证据路径和现状；Clarification 可引用该证据辅助判断，但不得把现状自动视为目标决策；Product Requirement 只写“仅管理员可以导出用户数据”等产品规则，不包含 `CODE-FACT-*`、`src/auth/permission.ts`、`role=admin`、代码符号、模块结构或当前实现过程。
 
-## Case 8：分页允许值来源
+## Case 8：分页允许值来源与冲突澄清
 
 ```text
 显式调用 `analyze-product-requirements` skill，参数：`target=backend`。
@@ -73,7 +73,7 @@ A：需求明确 pageSize 为必填，但未给出允许值集合。
 B：需求明确 pageSize 允许值为 5、10、20。
 ```
 
-知识库分页规范允许值为 `20/50/100`。核对：A 使用有效知识库规范的 `20/50/100`；B 原样沿用 `5/10/20`，不得被知识库或默认集合覆盖。知识库不可用或未命中时，A 才使用默认集合 `10/20/50/100`。不得从知识库/API 文档自动带入路径、方法、参数名、必填性、默认值、响应、错误码或 DTO。
+知识库分页规范允许值为 `20/50/100`。核对：A 使用有效知识库规范的 `20/50/100`；B 的输入值与知识库规范冲突（集合差异），必须进入待确认问题（对应事实标记 `与输入关系：冲突`，条目含 `冲突来源` 引用）并向用户逐题澄清，不得静默采用输入或规范；用户裁决后以确认值为准。知识库不可用或未命中时，A 才使用默认集合 `10/20/50/100`。不得从知识库/API 文档自动带入路径、方法、参数名、必填性、默认值、响应、错误码或 DTO。
 
 ## Case 9：项目状态与空数据规范
 
@@ -89,7 +89,7 @@ B：需求明确 pageSize 允许值为 5、10、20。
 
 ## Case 12：原始明确行为不伪造问题
 
-原始需求明确指定页面路由、权限和错误恢复方式。核对：这些内容以 `source-requirement` 事实直接合并，不生成 `Q-*`、`DEC-Q-*` 或二次确认。
+原始需求明确指定页面路由、权限和错误恢复方式，且与有效规范（知识库、ai_workspace、仓库规范）及代码现状核对一致。核对：这些内容以 `source-requirement` 事实直接合并，不生成 `Q-*`、`DEC-Q-*` 或二次确认；任一通道与输入冲突时不得免澄清。
 
 ## Case 13：页面路由
 
@@ -111,9 +111,9 @@ B：需求明确 pageSize 允许值为 5、10、20。
 
 分别使用“看似不涉及项目规范”的简单需求、让 `kb-design-assist` 返回无结果，以及让调用失败。核对：简单需求仍先从需求提取检索词并真实调用知识库，不允许 `not-executed`；无结果记录 `executed-no-match`，在有仓库时降级为受限、定向的代码库规范搜索，无仓库时按 unknown 分流；调用失败记录 `unavailable`，必须先说明失败原因并询问用户选择“修复后重试”或“跳过知识库”，未选择前不得预扫描项目资料、探索代码库或生成 complete 产物；选择修复后按重试结果继续，明确选择跳过后才允许降级。不得把“未执行”误写成“未命中”，也不得绕过确认门禁。
 
-## Case 18：知识库与需求冲突
+## Case 18：知识库与需求冲突（四通道）
 
-原始需求明确分页允许值为 `5/10/20`，知识库规范为 `20/50/100`；另提供一份与原始错误恢复行为冲突的设计规范。核对：分页沿用原始需求；用户可见行为冲突进入逐题澄清，用户裁决前保持 pending；不得静默采用知识库结果。
+原始需求明确分页允许值为 `5/10/20`，知识库规范为 `20/50/100`；另提供与原始错误恢复行为冲突的设计规范、ai_workspace 校验规则冲突和代码现状冲突各一份。核对：四类冲突全部进入待确认问题并逐题澄清（含分页允许值，不得静默采用输入或规范）；每条冲突条目成对列出输入声明与规范/代码声明、标注 `冲突来源`，对应事实标记 `与输入关系：冲突`；用户裁决前保持 pending，裁决后以确认值为准。
 
 ## Case 19：Web + Remote 接口范围
 
@@ -125,7 +125,7 @@ B：需求明确 pageSize 允许值为 5、10、20。
 
 ## Case 20A：知识库、代码库与澄清顺序
 
-使用同时包含权限歧义、状态约定和已有相似实现的需求。核对执行轨迹严格为：从原始需求提取检索计划 → 调用 `kb-design-assist` → 项目资料预扫描 → 按知识结论定向探索代码库 → 汇总冲突与 unknown → 逐题向用户澄清。不得在知识库门禁通过前搜索代码，也不得在代码事实尚可查证时提前询问用户。
+使用同时包含权限歧义、状态约定和已有相似实现的需求。核对执行轨迹严格为：从原始需求提取检索计划 → 调用 `kb-design-assist` → 项目资料预扫描 → 按知识结论定向探索代码库 → 执行「输入↔规范一致性核对」→ 汇总冲突与 unknown → 逐题向用户澄清。不得在知识库门禁通过前搜索代码，也不得在代码事实尚可查证时提前询问用户。
 
 ## Case 21：提示词冻结与来源身份
 
@@ -142,3 +142,7 @@ B：需求明确 pageSize 允许值为 5、10、20。
 ## Case 23：严格结构与全局唯一性
 
 分别向三个产物 frontmatter 注入 `source_path`，让两个故事复用同一个 AC ID，并把 complete Clarification 的“最终决策”改为“未形成”。核对：额外 frontmatter 字段、重复 AC ID 和未形成最终决策都被 validator 拒绝。
+
+## Case 24：输入与规范冲突必须澄清
+
+需求：昵称 1–30 个字符；知识库/ai_workspace 规范为 2–20 个字符。核对：输入声明与规范冲突必须进入待确认问题（冲突描述成对列出双方声明、含 `冲突来源` 引用，对应事实标记 `与输入关系：冲突`），逐题澄清，用户裁决前保持 pending；用户确认后 Q-* 为 confirmed/user，Product Requirement 采用确认值。构造以下 Product Analysis 时 validator 必须拒绝：(a) 事实标记 `与输入关系：冲突` 但待确认问题未引用其 ID；(b) `no-clarification-required` 且存在冲突标记；(c) `no-clarification-required` 且待确认问题缺少 `- 一致性核对：…未发现冲突条目。` 行；构造 Clarification 未覆盖 PA 冲突条目（冲突事实 ID 未出现在任何 Q-*）时，complete 校验必须拒绝。

package/skills/analyze-product-requirements/references/kb-integration.md

@@ -13,7 +13,7 @@
 
 需求分析优先查询设计系统、交互/文案规范、用户可见状态枚举、共享状态组件、权限可见性、错误语义和分页允许值。Controller、Service、Entity、Response、Remote、Web API 或 `interfaces.md` 等纯实现规范仅用于判断当前问题是否属于下游技术设计，不得据此扩写产品需求。
 
-知识库状态已确定或用户确认跳过后，再按固定顺序预扫描 `<project-root>/ai_workspace/project-how-to`、`code-specification`、`project-business`，然后才进入常规代码搜索。目录缺失不阻断；命中内容作为项目资料事实记录，并按知识库、项目资料、代码现状之间的冲突规则处理。
+知识库状态已确定或用户确认跳过后，再按固定顺序预扫描 `<project-root>/ai_workspace/project-how-to`、`code-specification`、`project-business`，然后才进入常规代码搜索。目录缺失不阻断；命中内容统一记录为 `CODE-FACT-*` 条目并标注证据类别：项目规范，参与「输入↔规范一致性核对」。仓库规范文档（仓库级指令、README、设计系统、架构规范）同样记录为 `CODE-FACT-*` 并标注证据类别：项目规范。
 
 ## 结果状态
 
@@ -36,18 +36,18 @@
 
 ## 事实与优先级
 
-每条有效结果使用 `KB-FACT-*`，记录规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响和置信度。过期、适用范围不明、相互冲突或无法定位来源的结果不得作为已确认规范，只能记录为冲突或 unknown。
+每条有效结果使用 `KB-FACT-*`，记录规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响、置信度和与输入关系（一致 | 补充 | 冲突）。事实条目使用单行格式：`- <KB|CODE>-FACT-<编号>：<事实>；来源：<文档/证据定位>；证据类别：<项目规范|代码现状>（仅 CODE-FACT）；与输入关系：<一致|补充|冲突>`。标记为"冲突"的事实必须被 Product Analysis"待确认问题"的冲突条目引用。过期、适用范围不明、相互冲突或无法定位来源的结果不得作为已确认规范，只能记录为冲突或 unknown。
 
-产品行为来源优先级：
+产品行为来源优先级（仅用于「输入↔规范一致性核对」与冲突澄清完成、用户裁决后的合成默认，不构成跳过澄清的依据）：
 
 1. 用户已确认决策。
 2. 原始需求明确内容。
 3. 当前有效且适用于本项目的知识库规范。
 4. 模型推断或通用兜底。
 
-知识库与用户决策、原始需求或另一份有效规范冲突时，保留证据并生成产品澄清问题，用户裁决前不得选边。知识库事实只能填补项目规范，不得发明业务范围、业务规则或用户意图。
+"原始需求明确内容"不等于"无冲突"：输入声明与有效规范（知识库、ai_workspace 项目资料、仓库规范文档）或代码现状冲突时，保留证据并生成产品澄清问题，用户裁决前不得按优先级静默采用输入或规范。知识库事实只能填补项目规范，不得发明业务范围、业务规则或用户意图。
 
-分页允许值遵循：原始需求/用户确认 > 有效知识库分页规范 > 固定兜底 `10/20/50/100`。即使知识库命中 API 文档，也不得自动带入路径、方法、参数名、必填性、默认值、响应结构、错误码或 DTO。
+分页允许值与其他规则一样参与「输入↔规范一致性核对」：输入与有效知识库分页规范冲突（含集合差异、子集或超集）时进入澄清，用户裁决后以确认值为准；无冲突时遵循：原始需求/用户确认 > 有效知识库分页规范 > 固定兜底 `10/20/50/100`。即使知识库命中 API 文档，也不得自动带入路径、方法、参数名、必填性、默认值、响应结构、错误码或 DTO。
 
 ## 产物边界
 

package/skills/analyze-product-requirements/references/product-analysis-schema.md

@@ -18,7 +18,9 @@ Frontmatter 只允许以上五个字段，不得增加来源路径、项目根
 
 固定章节：原始需求、需求概述、业务目标、需求分析、外部事实。原始需求必须包含 `- 原始需求身份：inline:sha256:<64位小写十六进制>` 或 `- 原始需求身份：file:sha256:<64位小写十六进制>`，并保留准确原文；inline 摘要只绑定正文，file 摘要同时绑定规范化真实路径与正文，均使用 `scripts/compute-source-identity.mjs` 生成。不得把原始路径另写入 frontmatter。
 
-需求分析包含明确需求、推断需求、待确认问题、初步非目标；外部事实包含知识库事实、代码库事实。“知识库事实”必须先记录 `executed-hit | executed-no-match | unavailable` 状态；每个新 requirement 都必须真实执行知识检索，不允许未执行状态。若 complete 流程最终仍记录 `unavailable`，必须同时记录 `- 用户处置：已确认跳过知识库`，否则不得生成本产物。有效事实使用 `KB-FACT-*`，包含规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响和置信度。“代码库事实”继续使用 `CODE-FACT-*`。
+需求分析包含明确需求、推断需求、待确认问题、初步非目标；外部事实包含知识库事实、代码库事实。”知识库事实”必须先记录 `executed-hit | executed-no-match | unavailable` 状态；每个新 requirement 都必须真实执行知识检索，不允许未执行状态。若 complete 流程最终仍记录 `unavailable`，必须同时记录 `- 用户处置：已确认跳过知识库`，否则不得生成本产物。有效事实使用 `KB-FACT-*`，包含规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响、置信度和与输入关系。”代码库事实”继续使用 `CODE-FACT-*`（ai_workspace 项目资料与仓库规范文档统一归入此节），除上述字段外必须标注证据类别（项目规范 | 代码现状）和与输入关系。
+
+事实条目强制使用单行格式：`- <KB|CODE>-FACT-<编号>：<事实>；来源：<文档/证据定位>；证据类别：<项目规范|代码现状>（仅 CODE-FACT 必填）；与输入关系：<一致|补充|冲突>`。与输入关系为”冲突”的事实，其 ID 必须被”待确认问题”的冲突条目引用。
 
 按 scope 追加“初步前端用户故事/初步前端输出规范”或“初步后端用户故事/初步后端输出规范”。不得生成独立用户角色或验收标准汇总。
 
@@ -32,10 +34,12 @@ Frontmatter 只允许以上五个字段，不得增加来源路径、项目根
 
 状态变量、UI 状态、空数据、loading、error、disabled、错误文案和兜底行为必须优先采用 `kb-design-assist` 查明的当前有效项目规范，再核验设计系统、共享组件和同类实现；未查明时标为 unknown，不得把通用模式写成项目事实。影响产品行为或验收的 unknown 进入待确认问题；纯实现/代码落点 unknown 只保留在外部事实中。
 
-后端分页：以原始需求/用户确认为准。输入已给出每页条数允许值时原样记录；未说明时优先使用 `kb-design-assist` 返回的当前有效分页规范，仍未查明才按默认集合 `10`、`20`、`50`、`100` 生成。不得因此把知识库/API 文档的路径、方法、参数名、必填性、默认值、响应、错误码或 DTO 自动带入。Validator 不解析或推断分页允许值集合；该规则由生成流程和 forward-test 核对。
+后端分页：每页条数允许值参与「输入↔规范一致性核对」。输入与有效分页规范冲突（含集合差异、子集或超集）时，该冲突必须进入待确认问题澄清，用户裁决后以确认值为准；输入未说明时优先使用 `kb-design-assist` 返回的当前有效分页规范，仍未查明才按默认集合 `10`、`20`、`50`、`100` 生成。不得因此把知识库/API 文档的路径、方法、参数名、必填性、默认值、响应、错误码或 DTO 自动带入。Validator 不解析或推断分页允许值集合；该规则由生成流程和 forward-test 核对。
 
 Product Analysis 只记录验收关注点，不得出现正式 `AC-FE-*`、`AC-BE-*` 或 Given/When/Then 块。
 
-推断需求一律属于未确认产品内容。任何推断需求，以及原始需求、知识库、代码核验或分析过程中发现的含糊、缺失、冲突、多种合理解释或目标行为 unknown，都必须进入待确认问题并在后续逐题向用户澄清。纯代码位置、符号、复用点和实现方式不属于产品需求，继续留在代码库事实中。
+推断需求一律属于未确认产品内容。任何推断需求，以及原始需求、知识库、项目资料、仓库规范文档、代码核验或分析过程中发现的含糊、缺失、冲突、多种合理解释或目标行为 unknown，都必须进入待确认问题并在后续逐题向用户澄清。纯代码位置、符号、复用点和实现方式不属于产品需求，继续留在代码库事实中；纯实现/技术细节冲突只记录"与输入关系：冲突"的事实，不生成问题。
+
+「输入↔规范一致性核对」标记为"冲突"的条目必须进入待确认问题，采用如下结构：冲突描述（`输入声明：…` 与 `规范/代码声明：…` 成对列出）、`冲突来源：<KB-FACT-编号 | CODE-FACT-编号>`、影响范围（`common | frontend | backend | both`）与优先级（默认 P0）。冲突条目只陈述双方声明与来源，不得预选边；推荐职能由 Step 2 访谈轮承担。
 
-`no-clarification-required` 只允许在“推断需求”包含独立一行 `- 无未确认的推断需求。` 且“待确认问题”包含独立一行 `- 无待确认问题。` 时使用；待确认问题可另写理由，但不得出现问题标记、优先级、问句或其他未确认产品内容。`ready-for-clarification` 至少包含一个带优先级或问号的问题。
+`no-clarification-required` 只允许在”推断需求”包含独立一行 `- 无未确认的推断需求。` 且”待确认问题”包含独立一行 `- 无待确认问题。` 时使用；待确认问题可另写理由和一行 `- 一致性核对：…未发现冲突条目。`，但不得出现问题标记、优先级、问句或其他未确认产品内容；存在任何”与输入关系：冲突”的事实不得使用本状态。`ready-for-clarification` 至少包含一个带优先级或问号的问题。

package/skills/analyze-product-requirements/references/product-requirement-schema.md

@@ -16,7 +16,7 @@ Frontmatter 只允许以上五个字段，不得增加来源路径、项目根
 
 固定章节：需求概述、业务目标、需求范围、业务规则、决策追溯。需求范围包含“已确认范围”和“非目标”。`pending` 与 `complete` 均禁止“默认假设”章节。`pending` 文档另含“未决事项”；`complete` 文档禁止“未决事项”。不得生成独立用户角色、验收标准汇总、前后端契约、Open Questions、测试建议或独立边界 case 章节。
 
-Product Requirement 只描述目标产品行为，不承载知识检索或代码侦察记录。不得包含 `KB-FACT-*`、`CODE-FACT-*`、知识库/仓库文件路径、代码级类/函数/组件符号、模块调用关系、数据表名、证据位置、当前实现过程或实现算法。产品层的页面或组件名称仍可用于描述用户可见输出。当前有效知识库规范只能在不与用户决策或原始需求冲突时转换为项目既定的产品规则；代码库事实只可在经用户确认或被原始需求明确要求后转换为不含实现细节的产品规则。原始证据保留在 Product Analysis 或 Clarification。
+Product Requirement 只描述目标产品行为，不承载知识检索或代码侦察记录。不得包含 `KB-FACT-*`、`CODE-FACT-*`、知识库/仓库文件路径、代码级类/函数/组件符号、模块调用关系、数据表名、证据位置、当前实现过程或实现算法。产品层的页面或组件名称仍可用于描述用户可见输出。当前有效知识库规范在不与用户决策或原始需求冲突时可转换为项目既定的产品规则；与输入冲突时必须先经澄清、由用户裁决，裁决后方可转换。代码库事实只可在经用户确认或被原始需求明确要求后转换为不含实现细节的产品规则。原始证据保留在 Product Analysis 或 Clarification。
 
 机器校验至少拦截：`KB-FACT-*`、`CODE-FACT-*`、常见仓库路径（如 `src/`）、`*Controller/*Service/*Repository/*Handler/*Middleware` 符号，以及“证据位置”。其余实现泄漏仍按本契约人工遵守。知识库/仓库 API 技术惯例仅可在分析与澄清中查证；写入本产物的参数名、必填性、默认值必须来自原始需求或用户确认。
 
@@ -30,7 +30,7 @@ Product Requirement 只描述目标产品行为，不承载知识检索或代码
 
 状态变量、UI 状态、空数据、loading、error、disabled、错误文案和兜底行为必须遵循 `kb-design-assist` 或项目资料查明的当前有效规范，保留项目真实枚举、共享组件、文案和交互方式；影响产品行为的 unknown 未澄清前不得 complete，纯实现/代码落点 unknown 不进入本产物。
 
-后端分页允许值按“原始需求/用户确认 > 当前有效知识库分页规范 > 默认集合 `10`、`20`、`50`、`100`”确定。参数名、必填性、默认值和其他 API 契约必须来自原始需求或用户确认，不得从知识库/API 文档自动带入。Validator 不解析或推断分页允许值集合；该规则由生成流程和 forward-test 核对。
+后端分页允许值在澄清完成后按”用户确认/原始需求 > 当前有效知识库分页规范 > 默认集合 `10`、`20`、`50`、`100`”确定；输入与有效分页规范冲突（含集合差异、子集或超集）必须先经澄清、由用户裁决，未裁决不得 complete。参数名、必填性、默认值和其他 API 契约必须来自原始需求或用户确认，不得从知识库/API 文档自动带入。Validator 不解析或推断分页允许值集合；该规则由生成流程和 forward-test 核对。
 
 正式 `AC-FE-*` 或 `AC-BE-*` 作为四级标题嵌入对应输出规范。故事的验收标准引用必须与该规范中的 AC 完全一致；AC 遵循 `acceptance-criteria.md`。
 每个 AC ID 在整个 Product Requirement 中必须全局唯一，不得在不同故事或不同输出规范中复用。

package/skills/analyze-product-requirements/references/requirement-clarification-schema.md

@@ -53,7 +53,7 @@ Frontmatter 只允许以上六个字段，不得增加来源路径、项目根
 
 Clarification 与 Product Requirement 的状态必须一致：`pending` 只能配对 `pending`，`complete` 只能配对 `complete`。`--allow-pending` 只允许校验前一种内部中间状态；不带参数的交付校验只接受后一种。无需澄清的精简结构只能直接生成 complete，不存在 pending 精简结构。
 
-原始需求已经明确的产品行为作为 `source-requirement` 事实直接合并，不生成 `Q-*`、`DEC-Q-*` 或 `confirmed/user` 伪记录。代码事实用于查证现状，不作为产品决策来源；实现事实 unknown 不生成澄清问题。
+原始需求已经明确、与有效规范及代码现状核对一致且不存在冲突的产品行为作为 `source-requirement` 事实直接合并，不生成 `Q-*`、`DEC-Q-*` 或 `confirmed/user` 伪记录；输入与有效规范或代码现状冲突时不得免澄清。代码事实用于查证现状，不作为产品决策来源；实现事实 unknown 不生成澄清问题。
 
 `complete` 要求：