@tea-agent/loop-agent 0.38.3 → 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/fe-test-ui-scout/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: fe-test-ui-scout
+description: 在写 frontend-test Wave PRD/回归目录之前，对真实运行的被测页面做只读锚点侦察，产出并维护 testcase/frontend/rag/ui-anchors.md 锚点台账。用 playwright-cli snapshot/find 逐字面验证命中数与唯一性，防止 PRD 验收标准引用不存在或不唯一的文案。触发词：frontend-test、锚点、台账、ui-anchors、侦察、写 PRD 前、snapshot/find 校准、Wave PRD。
+references:
+  - path: references/ledger-schema.md
+    required: true
+  - path: references/recon-protocol.md
+    required: true
+---
+
+# FE-Test UI Scout（锚点侦察）
+
+## 定位
+
+写 Wave PRD / 校准回归目录 AC **之前**的前置侦察。产出锚点台账
+`testcase/frontend/rag/ui-anchors.md`：每个「页面 × 状态」下真实可见、
+`find` 可命中的字面清单。PRD 的每条 `find "..."` 断言必须能在台账找到对应行；
+台账没有的字面禁止写进验收标准。
+
+本 skill **不生成用例、不执行用例、不点任何写控件**。生成由
+`playwright-cli-case-generator`（DAG generate 节点）负责，执行由
+`playwright-cli`（DAG execute 节点）负责；本 skill 只在 DAG 之外的主会话使用。
+
+## 输入
+
+- 被测 baseUrl（来自 `testcase/frontend/rag/context.md` 的 `environmentProbe=reachable` URL）
+- 目标 Wave 的 AC 清单（回归目录中本 Wave 范围的行）
+- 既有台账（增量更新，不整表重写）
+
+## 流程
+
+1. **读取范围**：从回归目录取本 Wave AC 的「页面 + 测试点 + 验收标准」，
+   提取所有候选字面（引号内文案、aria-label、控件名）。
+2. **逐状态侦察**：对每个涉及页面/状态组合：
+   `playwright-cli open --browser=chrome <baseUrl>/#/<route>` → `snapshot` →
+   逐候选 `find "<字面>"`，记录命中数与命中位置。
+3. **记录陷阱**：拆节点（`<kbd>`+`<span>`、文本+`<code>`）、同名多控件、
+   aria-label 与可见文本不一致、状态前置（no-session / has-session / empty、
+   setup-required）都要写进备注列。
+4. **增量写台账**：按 [references/ledger-schema.md](references/ledger-schema.md)
+   的表结构与分节规则追加/修订行，保留既有行历史（用备注标注失效原因，
+   不删行）。
+5. **报告**：侦察完成后输出小结（新增/修订/失效行数、命中率、给 PRD 的
+   可用锚点清单与禁用清单）。
+
+## 硬规则
+
+- 只读：不点提交/保存/发送类控件、不创建会话以外的任何状态（「新建空白
+  对话」CTA 允许点击一次以进入 has-session 状态，属于台账明确的状态夹具）。
+- 命中 0 或命中数 >1 且无法用状态/作用域区分的字面，标记 `不可断言`，
+  禁止进入 PRD `find` 断言。
+- 台账每行必须带验证时间与当时 baseUrl；页面改版后旧行标 `失效` 而非删除。
+- 不猜测：没跑过 `find` 的字面不进台账。
+- PRD 正文（含背景/夹具段）不得出现会被需求 id 扫描捕获的形态：大写或小写的 REQ/BR/AC 前缀 + 连字符 + hash/序号（如夹具任务 id 里的 req 段、或自示范用的「req 加连字符 hash」字面）。夹具引用只写日期 + 短 hash（如 f03535aa），规则说明文字用中文描述或代码块包裹仍可能被扫——一律避免连写。
+- PRD 验收标准只用**目录 AC id**（如 AC-FE-INS-005）作条目 id；不要写本地序号前缀（如 AC-003 加粗目录 id 的双 id 形态）——双 id 会被同时提取，生成器只引用其一，另一个落入 acceptanceCoverage.missing。
+
+## 输出
+
+- `testcase/frontend/rag/ui-anchors.md`（增量更新）
+- 侦察小结（对话内输出，不落盘；结论回写 PRD 草稿的锚点引用）
+
+## References
+
+- [references/ledger-schema.md](references/ledger-schema.md) — 台账表结构与分节规则
+- [references/recon-protocol.md](references/recon-protocol.md) — 逐状态侦察操作协议与陷阱清单

package/skills/fe-test-ui-scout/references/ledger-schema.md

@@ -0,0 +1,62 @@
+# 台账（ui-anchors.md）表结构与分节规则
+
+## 文件位置与命名
+
+- 路径：`testcase/frontend/rag/ui-anchors.md`
+- 编码：UTF-8，LF；表格用 GitHub Flavored Markdown。
+- 台账是**增量账本**：修订不删除历史行；失效行改状态列并注明原因。
+
+## 顶层结构
+
+```markdown
+# UI 锚点台账（frontend-test）
+
+- baseUrl：<验证时的绝对 URL>
+- 更新时间：<YYYY-MM-DD HH:mm（本地时区）>
+- 维护：fe-test-ui-scout skill
+
+## <页面路由> · <状态>
+
+| 字面（find 原文） | 命中 | 唯一 | 控件/位置 | 状态 | 备注 | 验证时间 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 后端研发（默认 DAG） | 1 | 是 | workflow-kind-select option | 有效 | 括号必须带全 | 2026-08-22 15:00 |
+```
+
+## 分节规则
+
+- 一节 = 一个「页面路由 × 状态」组合。路由用 hash 形式（`#/tasks`、
+  `#/chat`、`/inspect/#/dags`）；状态至少区分：
+  - `no-session`（无会话 landing）
+  - `has-session`（已存在会话，composer 可见）
+  - `empty-session`（新建空会话，无消息）
+  - 页面特有态（如 `#/night · 无计划`、`#/recovery · 无候选`、
+    setup-required）随需追加，节名写清楚。
+- 同一页面多个状态各自成节；不要把跨状态结果合并进一行。
+
+## 列语义
+
+| 列 | 说明 |
+| --- | --- |
+| 字面（find 原文） | `playwright-cli find "<字面>"` 的唯一入参原文，逐字节照抄（含括号、空格、中点） |
+| 命中 | 侦察时 `find` 实际返回的匹配数（0/1/N） |
+| 唯一 | 是/否/不适用；命中=1 且作用于目标控件才算「是」 |
+| 控件/位置 | 命中元素的角色与位置（如 `h2`、`oc-suggestion strong`、`aria-label`） |
+| 状态 | `有效` / `失效` / `待复核`；失效须在备注注明原因与替代字面 |
+| 备注 | 陷阱与前置：拆节点（kbd+span、text+code）、同名多控件、aria-label≠可见文本、状态前置、setup 门 |
+| 验证时间 | YYYY-MM-DD HH:mm |
+
+## 有效 / 失效判定
+
+- **有效**：命中=1、目标控件、字面在当前 build 下可复现。
+- **不可断言**：命中 0（字面不存在或被拆节点）、命中 >1 且状态/作用域
+  无法区分（如「发送」同时命中 tips 与按钮）。这类行保留在台账里，
+  状态列写 `不可断言`，备注写原因——它们正是 PRD 的「禁用清单」。
+- **失效**：页面改版后不再命中。不删行，改状态 + 备注（替代字面是什么）。
+
+## 与 PRD / 目录的关系
+
+- PRD 每条 `find "..."` 断言的字面必须出自台账某行且该行状态为
+  `有效`（或备注给出拆节点断言替代方案，如 `find "taskKind="` 与
+  `find "frontend-test"` 二选一）。
+- 目录 AC 的 live 校准注记引用台账行（日期 + 路由+状态），保持
+  「AC ↔ 台账」双向可追溯。

package/skills/fe-test-ui-scout/references/recon-protocol.md

@@ -0,0 +1,54 @@
+# 逐状态侦察操作协议与陷阱清单
+
+## 前置检查
+
+1. 确认 SUT 健康：`curl -s -o /dev/null -w '%{http_code}' <baseUrl>/api/health`
+   返回 200；非 200 先解决环境，不侦察。
+2. 确认 SUT 跑的是当前 build（改过 `src/**` 后必须 `npm run build` 并重启
+   SUT，否则台账记录的是旧页面）。
+3. 准备隔离 app-data（SUT 启动参数已带 `/tmp` 隔离目录时无需额外动作）；
+   侦察结束把 no-session 状态还原（关闭页面即可；若点了「新建空白对话」
+   产生空会话，记录在案即可，不必清理 app-data）。
+
+## 每个页面 × 状态的标准动作序列
+
+```text
+playwright-cli open --browser=chrome <baseUrl>/#/<route>
+playwright-cli snapshot
+playwright-cli find "<候选字面 1>"
+playwright-cli find "<候选字面 2>"
+...
+playwright-cli close
+```
+
+- `snapshot` 先行：从 snapshot 里核对候选字面的真实渲染形态（是否拆节点、
+  是否 aria-label、是否在折叠组内需先展开）。
+- 每个候选字面必须真实 `find` 一次；snapshot 里「看起来有」不算数。
+- 折叠组（如「工程边界（可选，人类确认）」）：先记录折叠态的组标题字面，
+  再展开后侦察组内字段；两种形态分两行记。
+- 需要状态夹具的节（has-session）：点一次「新建空白对话」CTA 进入；
+  这是协议允许的唯一写动作。
+
+## 陷阱清单（出现即写进备注列）
+
+| 陷阱 | 症状 | 台账记法 |
+| --- | --- | --- |
+| 拆节点 | `find "Enter 发送"` 0 命中；DOM 是 `<kbd>Enter</kbd><span>发送</span>` | 字面行记完整原文 + 命中 0 + 状态 `不可断言`；备注给出替代（`find "发送"` 或 `find "Enter"`）并说明拆法 |
+| text+code 拆分 | `taskKind=frontend-test` 渲染为 `taskKind=` + `<code>frontend-test</code>` | 同上 |
+| 同名多控件 | 「发送」同时命中 tips span 与发送按钮 aria-label | 命中 N>1，唯一=否；备注指明各自位置，PRD 需换更独特字面或限定状态 |
+| 同名多行按钮（列表态） | 「重命名会话」在 3 行会话各自命中 1，全局命中 3；单会话态侦察时命中 1 | 备注标「会话数依赖」；断言法降级为 hover 目标行 → snapshot 解析该行真实 ref（存在即通过），禁止声明 find 命中数=1；或确保夹具为单行态（清 app-data） |
+| aria-label ≠ 可见文本 | 控件可访问名是 aria-label，渲染文本不同 | 字面列记 aria-label 值，备注「aria-label；可见文本为 X」 |
+| 无名 flex 子项 | flex 匿名文本无 name-from-content，find 不到 | 记录控件缺 aria-label → 这是**产品可修问题**，报告给修复决策树（页面象限），台账暂记 `不可断言` |
+| 括号/全半角 | 「后端研发（默认 DAG）」少括号 0 命中 | 字面逐字节照抄；备注提醒 |
+| 状态前置 | 控件只在 has-session / setup-required 等状态下存在 | 分节记录；PRD 引用时必须声明状态夹具 |
+| 折叠组 | 字面在 `<details>` 内，未展开时 find 0 | 两种形态分行记录（折叠标题/展开后字段） |
+| 瞬态文案 | 「正在加载…」类短暂存在 | 备注标「瞬态」，PRD 不引用 |
+
+## 输出纪律
+
+- find 命中数以工具返回为准，不目测。
+- 每节侦察完立即写台账（不攒到最后凭记忆写）。
+- 侦察小结按 SKILL.md 第 5 步输出：新增/修订/失效行数、命中率、
+  PRD 可用锚点清单与禁用清单。
+- 发现疑似产品缺陷（白屏、文案缺失、aria 错误）：记入小结的「移交修复」
+  段，不在台账内修，不因缺陷跳过其余候选字面的侦察。

package/skills/loop-agent/references/command-reference.md

@@ -100,6 +100,8 @@ loop-agent --help
 ```bash
 loop-agent inspect                                           # 当前 repo（自动检测）
 loop-agent --repo-root /path/to/target-repo inspect           # 指定 repo
+loop-agent inspect next                                      # 当前 npm next 绑定（version / SHA / unpublished commits）
+loop-agent inspect next --json
 ```
 
 ### 健康检查
@@ -132,13 +134,18 @@ SDK 回归或 SDK 可选依赖不可用时用 `cli-only` 诊断。CLI fallback
 
 ```bash
 loop-agent init instructions --repo-root <target-repo>
+loop-agent init model-catalog --repo-root <target-repo> --json
 loop-agent init --repo-root <target-repo> --profile full --merge \
-  --provider deepseek --model deepseek/deepseek-v4-flash
+  --low-model deepseek/deepseek-chat \
+  --med-model deepseek/deepseek-v4-flash \
+  --high-model deepseek/deepseek-v4-pro
 loop-agent init doctor --repo-root <target-repo>
 loop-agent init check-update --repo-root <target-repo> --json
 loop-agent init check-update --repo-root <target-repo> --markdown
 loop-agent init update --repo-root <target-repo> --bootstrap-surface
 loop-agent init update --repo-root <target-repo> --apply-safe
+loop-agent init update --repo-root <target-repo> --apply-safe \
+  --low-model <current-or-selected> --med-model <current-or-selected> --high-model <current-or-selected>
 loop-agent init reconcile --repo-root <target-repo> [--json|--markdown]  # compatibility low-level diagnostic
 loop-agent init upgrade --repo-root <target-repo> --json
 loop-agent init upgrade --repo-root <target-repo> --run-id <run-id> --status --json
@@ -146,13 +153,13 @@ loop-agent init upgrade --repo-root <target-repo> --run-id <run-id> --continue -
 loop-agent init upgrade --repo-root <target-repo> --run-id <run-id> --report --markdown
 ```
 
-fresh init 将精确引用写到 `executors.pi.LOW/MED/HIGH`。fresh `loop-agent init` 会将合格且完整的 `provider/model` 引用投影到 `executors.pi.LOW/MED/HIGH`，即 `executors.pi.LOW`、`executors.pi.MED` 和 `executors.pi.HIGH`。三个 tier 齐全时不会写入 `defaultModel`，也不会恢复或建议旧顶层 routing 字段。
+fresh init 将精确引用写到 `executors.pi.LOW/MED/HIGH`。模型先运行只读 `init model-catalog`：Pi SDK runtime 与 OpenCode 非 verbose 列表由代码确定性发现，只向模型暴露 provider/model、能力/成本/窗口元数据、Pi setup、兼容性与 credential-ready 布尔值，不暴露原始配置和凭据。已有档位仍存在于 Pi 时原样保留，只重选失效/缺失档位；代码在 update 时拒绝替换仍有效档位。Pi 无定义时先向用户补齐必要模型元数据并帮助字段级配置 `models.json`；只有认证缺失时保留 harness 并修复认证。三个 tier 齐全时不会写入 `defaultModel`，也不会恢复旧顶层 routing 字段。
 
 `init check-update` 是只读升级报告，用于发现目标项目是否落后于当前包内初始化 surface。输出会区分 deterministic actions、model merge tasks、human decisions 和 recommended next。`--markdown` 会渲染可直接交给模型执行的合并指引，包含 `allowedPaths`、`forbiddenPaths`、`mergeRules` 和 `verification`。
 
-`init update --bootstrap-surface` 为旧项目写入 `.harness/init-surface.json` 的 `inferred-baseline`，不伪装成历史 recorded baseline。`init update --apply-safe` 只执行确定性安全动作：补缺失文件、创建目录、刷新 managed block；已有但无法确认与当前包一致的文件会进入 model merge tasks，不会被覆盖。模型 merge 只会自动展开不含 tier 或其他旧字段的唯一、完整且可证明等价的旧 `defaultModel: "provider/model"`；顶层 `model`、`models`、`modelProfiles`、`modelRouting`、`verify`、`sequentialWorkflowRole`、部分/对象 tier、bare model、冲突 provider 或未知语义均 fail closed，并保留原始 `harness.json`。
+`init update --bootstrap-surface` 为旧项目写入 `.harness/init-surface.json` 的 `inferred-baseline`，不伪装成历史 recorded baseline。`init update --apply-safe` 只执行确定性安全动作：补缺失文件、创建目录、刷新 managed block；`harness.json` 永不走整文件 `refresh-owned-file`，即使它仍与旧 recorded hash 一致，也只允许字段级确定性迁移或 bounded merge。带完整三档参数的 update 只替换 catalog 已判定失效的档位，仍有效档位的对象形态与 thinking 配置保持不变。模型 merge 只会自动展开不含 tier 或其他旧字段的唯一、完整且可证明等价的旧 `defaultModel: "provider/model"`；其他歧义均 fail closed 并保留原文件。
 
-`init upgrade` 是写入型升级入口：首次运行冻结 controller identity、检查 npm latest、扫描 surface、自动执行安全动作，并把 run facts 持久化到 `.harness/init-upgrades/<run-id>/`。`--status` 与 `--report` 严格只读；`--continue` 会重新核验 identity、当前 hash 与不变量。版本选择、无法判定冲突、凭据、破坏性删除或 active writer 才进入 human decision。普通语义冲突返回具体单文件 `allowedPaths` merge task，主会话必须合并后继续，不能把 `needs-model-merge` 作为完成。默认管理项目级 OpenCode/Pi recovery 与 `.pi/settings.json` nested merge，保留显式 disabled，Pi trust 后才加载；默认不读写 `~/.pi/agent/settings.json`。旧 `init reconcile` 保留为兼容低层诊断。
+`init upgrade` 是写入型升级入口：首次运行冻结 controller identity 与脱敏模型目录，检查 npm latest，并用一次 surface scan 形成完整计划。固定投影按 recorded bytes 确定性增删改；recorded `harness.json` 按属性树增删字段并保留项目值、同步 schema；项目自适应内容由模型决定。多个语义合并在同一计划中串行排队，每次仍只开放一个文件的 `allowedPaths`；接受后直接激活下一项，不重复版本发现/规划，队列清空后只跑一次最终验证。确定性收敛最多两轮。完成态的 verification/report 均有 controller hash anchor，`--status`、`--report` 和已完成 run 的幂等 `--continue` 只读持久化证据，不重新跑项目校验。默认管理项目级 OpenCode/Pi recovery 与 `.pi/settings.json` nested merge，默认不读写 `~/.pi/agent/settings.json`。旧 `init reconcile` 保留为兼容低层诊断。
 
 升级在 managed block 收敛后生成只读 gitignore 迁移评估（`.harness/init-upgrades/<run-id>/gitignore-migration.json`）：inventory 已跟踪的 `.harness/**` 与 `.agents/**`，建议 index-only 命令 `git rm -r --cached --ignore-unmatch .harness` / `.agents`（只改 index、保留工作区文件；`scripts/**` 与 `ai_workspace/loop-agent/**` 永不出现）。`.agents` 已跟踪内容会触发 human-decision 暂停等待审查；非 Git 仓库、git 查询失败或存在 staged 条目时 `status: blocked` 且无命令建议。controller 不自动修改 Git index。
 

package/skills/playwright-cli/SKILL.md

@@ -25,6 +25,7 @@ close
 goto
 snapshot
 find
+find-unique
 click
 dblclick
 fill
@@ -71,6 +72,16 @@ playwright-cli close
 普通交互和控制台输出均不能单独取得 passed authority。通过的 case 还需要同一 child 的有序
 controller receipts：successful `open` → successful `find` → successful post-execution cleanup。
 
+### 唯一性断言优先用 find-unique
+
+当语义要求「全页恰好一个」时，用 `playwright-cli find-unique "字面"` 代替人工数命中数：它内部
+执行 find 并在解析命中数 ≠ 1 时以非零退出码失败（零命中/多命中/输出不可解析均 fail），错误
+信息直接给出 `expected exactly 1 match, got N`。它只接受一个文本字面量、不接受 `--regex` 等
+flag。台账中标注 `==1` 的锚点、以及「唯一命中」类 AC 应优先用它；`>=N` 存在性断言仍用
+`find`（find-unique 会拒绝多命中）。controller 会解析两类命令的命中数写入 receipt，finalize
+时用 case 文档声明的 `find "字面" >=N / ==N` 对照 receipt 复核，缺失或不满足会把 passed
+降级为 blocked（assertion-not-receipt-backed），因此声明的断言必须真的执行。
+
 ## 受限证据采集
 
 - UI 状态：先 `snapshot`，完成交互后以成功 `find` 证明用户可见结果。
@@ -91,3 +102,14 @@ controller receipts：successful `open` → successful `find` → successful pos
 当环境、数据、权限、时序、异常路径或响应内容无法用 RAG、已验证 context URL 和 runtime allowlist 证明时，
 写入 `blocked` evidence，并提供具体 `blockedReason`。不要引入替代执行路径，也不要把隐藏状态或
 未观察到的网络结果当作通过证据。
+
+### 唯一控件早停（unique-control-unavailable）
+
+- 适用：AC 点名的具体控件在到达目标状态后的**首个 post-navigation snapshot** 中缺失，且页面没有
+  setup-required 门（如「需先完成 Pi setup」）。
+- 判定：用 case 给出的字面做**单次** `find`；返回 0 命中即为充分证据，直接写
+  `status=blocked`、`blockedReason=unique-control-unavailable`，在 execution.md 中引用该次 find 结果。
+- 禁止：换字面重试、反复 snapshot、绕路导航、多轮探索或请求 rerun。这些都产生无放大的 token
+  成本且不改变结论（Wave 3 教训：反复探测不存在控件耗掉约 717k input tokens）。
+- 若 snapshot 显示存在 setup-required 门或状态前置未满足，按其对应 blockedReason 记录
+  （环境/状态类），不属于本早停。

package/skills/playwright-cli-case-generator/SKILL.md

@@ -14,11 +14,21 @@ description: 根据 FE-test RAG 知识包生成可由受限 playwright_cli runti
 ## 输入与边界
 
 - 只读取 `testcase/frontend/rag/context.md`、`coverage-map.md` 与已有 `testcase/frontend/cases/`。
+- 若存在 `testcase/frontend/rag/ui-anchors.md` 锚点台账，必须一并读取并作为 UI 断言的唯一事实源；台账缺失时按 RAG 知识包生成，但不得引用台账外的具体控件字面（缺失信息标 `blocked`）。
 - 只写 `testcase/frontend/cases/**`；不得回读 PRD、读取 `.harness/`，或写
   `testcase/frontend/evidence/**`。
 - 所有 API、字段限制、状态流转、数据来源、SLA、URL 与账号要求必须能在 RAG 知识包中追溯。
   缺失信息标记 `blocked` 或“需人工确认”，不得猜测。
 
+### 锚点台账规则（存在 ui-anchors.md 时）
+
+- case 中每条拟通过的 `find "<字面>"` 断言必须能在台账对应「页面 × 状态」节找到
+  状态为 `有效` 的行；台账 `不可断言` / `失效` 行的字面**禁止**作为通过断言。
+- AC 点名的控件在台账对应状态节缺失（0 命中或无行）时，该 AC 的 case 生成
+  `blocked` 语义说明（或从本批剔除该 AC），`blockedReason` 用
+  `unique-control-unavailable`，不得生成探测性步骤反复 find。
+- 台账行备注中的替代断言方案（如拆节点后的短字面二选一）按备注执行。
+
 ## 输出
 
 - 写 `index.md`、`manifest.draft.json`（生成阶段；materialize 会写成 `manifest.json`）与独立 case 文件
@@ -51,7 +61,16 @@ description: 根据 FE-test RAG 知识包生成可由受限 playwright_cli runti
    占位符仅表示从紧邻其前、最新一次 `snapshot` 输出解析出的真实 `eNN` ref。生成的 case 必须在每次
    引用元素前写明 fresh snapshot；`eX`/`eY` 不是可传给 structured tool 的 literal ref，新的 snapshot
    会使旧 ref 失效，不得复用 stale ref。
-5. 明确的 UI/API 预期与数据清理结果；无法满足的环境或数据依赖必须写为 `blocked`。
+5. **期望命中数不得内联进命令行（硬约束）**：如需声明 find 期望命中数，写在「预期结果」区或
+   列表项的说明文字中（如 “预期唯一命中”）；命令行只写纯命令 `playwright-cli find "<字面>"`。
+   禁止 `find "<字面>">=N`、`≥N`、`（≥N）` 等计数后缀内联进命令 token。
+6. **唯一性断言优先 find-unique**：台账或 AC 标注 `==1`/「唯一命中」的锚点，生成
+   `playwright-cli find-unique "<字面>"`（仅一个文本字面量，无 flag；多命中/零命中即命令失败）；
+   `>=N` 存在性断言仍用 `find`。finalize 会用 case 文档中 `find "字面" >=N / ==N` 声明对照
+   controller receipt 的解析命中数复核，声明的断言未真正执行或命中数不满足会把 passed 降级为
+   blocked（assertion-not-receipt-backed）——因此「测试点」里声明的每个 find 断言都必须在步骤中
+   真实执行且字面完全一致。
+7. 明确的 UI/API 预期与数据清理结果；无法满足的环境或数据依赖必须写为 `blocked`。
 
 所有文件型输出均由 controller 绑定到执行节点提供的
 `testcase/frontend/evidence/<case-id>/` 工作目录。截图一律使用 canonical 语法

package/dist/worker/console/static/assets/channel-CPF4N7pf.js

@@ -1 +0,0 @@
-import{ag as o,ah as n}from"./mermaid.core-BVjAT9b8.js";const t=(a,r)=>o.lang.round(n.parse(a)[r]);export{t as c};

package/dist/worker/console/static/assets/classDiagram-JCYQIIEL-C2DwA_Y1.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-GF5L2VYU-CPcdNeew.js";import{_ as i}from"./mermaid.core-BVjAT9b8.js";import"./chunk-5VM5RSS4-CtiPlKel.js";import"./chunk-XXDRQBXY-UrVoM9z1.js";import"./chunk-KBJHAD2P-DQ_T-hg8.js";import"./chunk-2GRJ4B5K-K0C744p1.js";import"./index-DTZOKgAn.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};

package/dist/worker/console/static/assets/classDiagram-v2-OCEON4UE-C2DwA_Y1.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-GF5L2VYU-CPcdNeew.js";import{_ as i}from"./mermaid.core-BVjAT9b8.js";import"./chunk-5VM5RSS4-CtiPlKel.js";import"./chunk-XXDRQBXY-UrVoM9z1.js";import"./chunk-KBJHAD2P-DQ_T-hg8.js";import"./chunk-2GRJ4B5K-K0C744p1.js";import"./index-DTZOKgAn.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};

package/dist/worker/console/static/assets/stateDiagram-v2-UEYNNEHI-B8FB_cNk.js

@@ -1 +0,0 @@
-import{s as r,b as e,a,S as s}from"./chunk-5RXB4S5H-DjLaSDUO.js";import{_ as i}from"./mermaid.core-BVjAT9b8.js";import"./chunk-XXDRQBXY-UrVoM9z1.js";import"./chunk-KBJHAD2P-DQ_T-hg8.js";import"./chunk-2GRJ4B5K-K0C744p1.js";import"./index-DTZOKgAn.js";var u={parser:a,get db(){return new s(2)},renderer:e,styles:r,init:i(t=>{t.state||(t.state={}),t.state.arrowMarkerAbsolute=t.arrowMarkerAbsolute},"init")};export{u as diagram};

package/dist/worker/console/static/assets/swimlanesDiagram-ULZ7WXOC-CrZYaWfx.js

@@ -1,8 +0,0 @@
-import{c as r,s as e}from"./flowDiagram-UKHOOZJN-CihnROSm.js";import{_ as a}from"./mermaid.core-BVjAT9b8.js";import"./chunk-5VM5RSS4-CtiPlKel.js";import"./chunk-XXDRQBXY-UrVoM9z1.js";import"./chunk-KBJHAD2P-DQ_T-hg8.js";import"./chunk-2GRJ4B5K-K0C744p1.js";import"./channel-CPF4N7pf.js";import"./index-DTZOKgAn.js";var o=a(t=>`${e(t)}
-  .swimlane.cluster rect {
-    stroke: ${t.clusterBorder} !important;
-  }
-  [data-look="neo"].cluster rect {
-    filter: none;
-  }
-`,"getStyles"),s=o,n=r({defaultLayout:"swimlane",styles:s});export{n as diagram};