@tea-agent/loop-agent 0.39.0-next.9 → 0.39.1

package/scripts/next-publish-gate.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * next-publish-gate: throttle main -> npm `next` publishing.
+ *
+ * Every main push used to publish a new next build. With this gate a
+ * push-triggered run only publishes when HEAD is at least COMMIT_THRESHOLD
+ * commits ahead of the commit that produced the current dist-tags.next
+ * build (read from the published tarball's dist/build-stamp.json).
+ *
+ * Bypasses (publish regardless of the count):
+ *   - workflow_dispatch runs (manual trigger, e.g. right before cutting a
+ *     release line); the workflow passes --force for those.
+ *   - recovery: HEAD already IS the source of the current next build, so
+ *     re-publishing would be the same version anyway.
+ *   - unknown last-published SHA (no npm history / unreadable stamp /
+ *     SHA not an ancestor of HEAD): fail open — a missed next build is
+ *     cheap, permanently stuck publishing is not.
+ *
+ * Exit codes: 0 = publish, 2 = skip (gate), 1 = hard error. The workflow
+ * maps skip to a successful early exit so non-publishing runs are green.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+import { readTarballBuildStamp } from "./release-source-binding.mjs";
+
+export const COMMIT_THRESHOLD_DEFAULT = 5;
+const SKIP_EXIT_CODE = 2;
+
+/** Run a command and return trimmed stdout; injected for tests. */
+function normalizeWindowsTarArg(value) {
+	const match = /^([A-Za-z]):[\\/](.*)$/.exec(String(value));
+	if (!match) return value;
+	return `/${match[1].toLowerCase()}/${match[2].replaceAll("\\", "/")}`;
+}
+
+export function normalizeCommandArgs(cmd, args, platform = process.platform) {
+	if (platform !== "win32" || cmd !== "tar") return args;
+	return args.map(normalizeWindowsTarArg);
+}
+
+export function commandLaunch(cmd, args, platform = process.platform) {
+	if (platform === "win32" && cmd === "npm") {
+		return {
+			cmd: process.env.ComSpec || "cmd.exe",
+			args: ["/d", "/s", "/c", "npm", ...args],
+		};
+	}
+	return { cmd, args };
+}
+
+export function defaultRun(cmd, args) {
+	const launch = commandLaunch(cmd, normalizeCommandArgs(cmd, args));
+	return execFileSync(launch.cmd, launch.args, {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+}
+
+export function npmViewDistTags(run = defaultRun) {
+	const out = run("npm", [
+		"view",
+		"@tea-agent/loop-agent",
+		"dist-tags",
+		"--json",
+	]);
+	const trimmed = String(out ?? "").trim();
+	if (!trimmed) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse(trimmed);
+	} catch {
+		return {};
+	}
+	return parsed && typeof parsed === "object" ? parsed : {};
+}
+
+/** Download the exact published next version and read its build stamp. */
+export function defaultStampProbe(version) {
+	const dir = mkdtempSync(join(tmpdir(), "loop-agent-next-gate-"));
+	try {
+		defaultRun("npm", [
+			"pack",
+			`@tea-agent/loop-agent@${version}`,
+			"--pack-destination",
+			dir,
+		]);
+		const file = readdirSync(dir).find((entry) => entry.endsWith(".tgz"));
+		if (!file) return null;
+		try {
+			return readTarballBuildStamp(join(dir, file), defaultRun);
+		} catch {
+			return null;
+		}
+	} catch {
+		return null;
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+}
+
+export function isAncestor(sha, head, run = defaultRun) {
+	try {
+		run("git", ["merge-base", "--is-ancestor", sha, head]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Pure decision. Inputs:
+ *   - threshold: minimum commits ahead of lastPublishedSha to publish
+ *   - aheadBy: commits between lastPublishedSha and headSha (null = unknown)
+ *   - lastPublishedSha / headSha: for the recovery equality check
+ * Returns { publish, reason, aheadBy }.
+ */
+export function shouldPublishNext({
+	threshold = COMMIT_THRESHOLD_DEFAULT,
+	lastPublishedSha,
+	headSha,
+	aheadBy,
+	force = false,
+}) {
+	if (force) {
+		return { publish: true, reason: "force-bypass", aheadBy };
+	}
+	if (!headSha) {
+		return { publish: true, reason: "head-unknown-fail-open", aheadBy };
+	}
+	if (!lastPublishedSha) {
+		return {
+			publish: true,
+			reason: "last-published-sha-unknown-fail-open",
+			aheadBy,
+		};
+	}
+	const last = String(lastPublishedSha).toLowerCase();
+	const head = String(headSha).toLowerCase();
+	if (last === head) {
+		return { publish: true, reason: "same-commit-recovery", aheadBy: 0 };
+	}
+	if (aheadBy === null || aheadBy === undefined || !Number.isFinite(aheadBy)) {
+		return { publish: true, reason: "ahead-unknown-fail-open", aheadBy: null };
+	}
+	const normalizedThreshold = Number(threshold);
+	if (!Number.isFinite(normalizedThreshold) || normalizedThreshold <= 0) {
+		return { publish: true, reason: "threshold-invalid-fail-open", aheadBy };
+	}
+	if (aheadBy >= normalizedThreshold) {
+		return { publish: true, reason: "ahead-threshold-met", aheadBy };
+	}
+	return { publish: false, reason: "below-threshold-skip", aheadBy };
+}
+
+function parseArgs(argv) {
+	return Object.fromEntries(
+		argv
+			.filter((arg) => arg.startsWith("--"))
+			.map((arg) => {
+				const [key, ...value] = arg.replace(/^--/, "").split("=");
+				return [key, value.join("=") || "true"];
+			}),
+	);
+}
+
+function main() {
+	const args = parseArgs(process.argv.slice(2));
+	const threshold = Number(args.threshold || COMMIT_THRESHOLD_DEFAULT);
+	const distTags = npmViewDistTags();
+	const currentNext = distTags.next ? String(distTags.next) : null;
+	let lastPublishedSha = null;
+	let currentNextNote = "no dist-tags.next";
+	if (currentNext) {
+		const stamp = defaultStampProbe(currentNext);
+		if (stamp && stamp.gitSha) {
+			lastPublishedSha = stamp.gitSha;
+			currentNextNote = `next=${currentNext} from ${stamp.gitSha.slice(0, 10)}`;
+		} else {
+			currentNextNote = `next=${currentNext} (stamp unreadable)`;
+		}
+	}
+	let headSha = null;
+	let aheadBy = null;
+	try {
+		headSha = defaultRun("git", ["rev-parse", "HEAD"]).trim();
+	} catch {
+		headSha = null;
+	}
+	if (headSha && lastPublishedSha) {
+		if (!isAncestor(lastPublishedSha, headSha)) {
+			aheadBy = null;
+		} else {
+			aheadBy = Number(
+				defaultRun("git", [
+					"rev-list",
+					"--count",
+					`${lastPublishedSha}..${headSha}`,
+				]).trim(),
+			);
+		}
+	}
+	const decision = shouldPublishNext({
+		threshold,
+		lastPublishedSha,
+		headSha,
+		aheadBy,
+		force: args.force === "true",
+	});
+	process.stdout.write(
+		`next-publish-gate: ${currentNextNote}\n` +
+			`next-publish-gate: head=${headSha ? headSha.slice(0, 10) : "unknown"} ` +
+			`aheadBy=${aheadBy === null ? "unknown" : aheadBy} ` +
+			`threshold=${threshold}\n` +
+			`next-publish-gate: ${decision.publish ? "PUBLISH" : "SKIP"} ` +
+			`(${decision.reason})\n`,
+	);
+	process.exit(decision.publish ? 0 : SKIP_EXIT_CODE);
+}
+
+// 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) {
+	main();
+}

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，已合并到后端输出规范分页约定。
+```