@tea-agent/loop-agent 0.39.0-beta.2 → 0.39.0-beta.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/codebase-scout/SKILL.md

@@ -10,7 +10,7 @@ description: 用于只读 scout 节点，在实现前定位现有代码、测试
 ## 规则
 
 - 从 repo 指令、task source 与邻近测试入手。
-- 可用时优先 CodeGraph；否则用 `rg` 与聚焦文件阅读。
+- 可用时优先 CodeGraph；否则 Shell 搜索优先 `rg`，按名找文件优先 `fd`，再聚焦阅读文件。
 - 在提议新抽象前，识别现有 helper 与 ownership 边界。
 - 只返回事实，不做编辑。
 

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/frontend-implementation/SKILL.md

@@ -5,12 +5,12 @@ description: >-
 references:
   - path: references/node-contracts.md
     required: true
-    # Compact contract index must stay under skill total budget (~10k with body + other refs).
-    # Headroom above current ~4k file; do not raise alone without checking totalMaxChars.
-    maxChars: 6000
+    # Current file is ~6.3KB; cap aligned with actual size so the required
+    # reference injects untruncated.
+    maxChars: 7000
   - path: references/design-spec.md
     required: true
-    maxChars: 3000
+    maxChars: 3500
   - path: references/code-standards.md
     required: true
     maxChars: 3000

package/skills/frontend-implementation/references/design-spec.md

@@ -6,9 +6,10 @@ Knowledge base, OpenSpec, and `ai_workspace/` are parallel specification sources
 
 1. Attempt the configured component/design knowledge-base query first when a
    connector is available.
-2. Regardless of knowledge-base success/failure/timeout/no-match, also
-   recursively search `openspec/schemas/`, `openspec/project-specs/`, and
-   `ai_workspace/` for index files and relevant content.
+2. Regardless of knowledge-base success/failure/timeout/no-match, use the
+   generation-frozen local-spec capability context and cited candidate set. For
+   unresolved task terms, search the three local roots in a bounded way; do not
+   recursively read every supported file merely because it exists.
 3. Treat relevant matches from both sources as the current project's
    specification for this run.
 4. Only then use component source, tokens, stories, tests, and pages as
@@ -23,10 +24,13 @@ Connector format is TODO; attempt only an available connector, otherwise record
 
 ## openspec Fallback Procedure
 
-- Inspect `<repoRoot>/openspec/schemas/`, `<repoRoot>/openspec/project-specs/`,
-  and `<repoRoot>/ai_workspace/` when present; enumerate supported files recursively.
-- Read indexes first, then search names/content using task, route, component,
-  interaction, theme, token, and state terms.
+- Start with the generation-frozen classified paths and `frontendOpenspec`
+  candidates. Read their indexes or relevant sections first, then use task,
+  route, component, interaction, theme, token, and state terms for bounded
+  local searches under `<repoRoot>/openspec/schemas/`,
+  `<repoRoot>/openspec/project-specs/`, and `<repoRoot>/ai_workspace/`.
+- Do not turn local fallback into a full-directory read. If a searched path is
+  relevant, record why it was selected and read it in context.
 - Read matches in context; a filename-only hit is not a rule.
 - Record search terms, inspected/matched paths, headings or tight line ranges,
   applied rules, and conflicts.

package/skills/frontend-implementation/references/node-contracts.md

@@ -5,27 +5,36 @@ Pre-write nodes are read-only. Preserve IDs, labels, commands, language, require
 ## Core nodes
 
 - **`frontend-contract-pi`**: `Scope`, `Non-goals`, `Acceptance Criteria`, `UI States`, `Target Runtime Environment`, `Risks`, `Verification Expectations`; no guessed requirements.
-- **`frontend-scout-pi`**: routes, components, tokens, data/API/Mock, scripts, tests, assets; fact vs inference vs gap. Search+read `openspec/schemas/`, `openspec/project-specs/`, `ai_workspace/` first. Output stack, styling, conventions, state/data, test entry points, reuse, risks.
-- **`frontend-plan-pi` + conditional design loop**: AC → observable `expectedOutcome`; interactions → `trigger`+`expectedBehavior`; include steps, in-bound files, UI states, reuse, deps, Mock/API, frozen verify entrypoints and integration gaps. DAG freezes a protected skeleton (`schemaVersion`, `sourceBinding`, `riskLevel`, `targets.files`, `mockApi.productionDefaultOff`). Model returns a **JSON-only** editable RFC 7386 patch (`frontend-implementation-contract-plan-patch-v1`) plus one `openspec-citations` block. Runtime compiles canonical `frontend-implementation-contract-v1` and archives raw/extracted/normalized/validation candidates; unresolved optional symbols are dropped and audited. No plan prose; gate renders plan.md. IDs+paths ≠ behavior semantics. Applicable UI states need behavior/implementation/verification; non-applicable states need reasons. Active Mock needs frozen commands; `auto` without confirmed capability/command → `not-needed`; `required` without command → generation-time blocked. Only `request-revision` runs revision+final review; small-risk gets one review.
+- **`frontend-contract-pi`**（仅 cited 且候选非空）：在既有 Markdown contract 的末尾输出一个 `frontend-openspec-selection-v1` JSON block，对 generation-frozen specRoots 候选逐一分类为 `required` / `relevant` / `irrelevant`；显式 `requiredReadPaths` 和任务源文件引用必须为 `required`。只读，不改 task.json，不新增节点。
+- **`frontend-scout-pi`**: routes, components, tokens, data/API/Mock, scripts, tests, assets; fact vs inference vs gap. Start from the generation-frozen OpenSpec capability context and contract selection block; then perform bounded task-term searches only for unresolved relevant rules. Do not recursively read every candidate directory. Output stack, styling, conventions, state/data, test entry points, reuse, risks.
+- **`frontend-plan-pi`**: AC → observable `expectedOutcome`; interactions → `trigger`+`expectedBehavior`; include steps, in-bound files, UI states, reuse, deps, Mock/API, frozen verify entrypoints and integration gaps. DAG freezes a protected skeleton (`schemaVersion`, `sourceBinding`, `riskLevel`, `targets.files`, `mockApi.productionDefaultOff`). The model commits the plan decision ledger incrementally through typed `record_*` tools (target-surface / component-choice / state-flow / data-flow / mock-api / design-deviation / dependency) and closes with exactly one `finalize_plan`; narrative prose stays free-form context and is never the compile authority. `frontend-design-policy-shell` assembles the canonical contract from committed facts (validated, fail-closed — no fenced-JSON text parsing) and materializes `frontend-implementation-contract-v1`; unresolved optional symbols are dropped and audited. `frontend-design-policy-shell` deterministically renders plan.md. IDs+paths ≠ behavior semantics. Applicable UI states need behavior/implementation/verification; non-applicable states need reasons. Active Mock needs frozen commands; `auto` without confirmed capability/command → `not-needed`; `required` without command → generation-time blocked.
   - `uiComponentChoices[]` (optional): `{purpose, component, decision, specReference, rationale}`; `specified` needs `specReference{path,section,line}`; `new` needs null ref+rationale.
-- **`frontend-prewrite-gate-shell`**: sole write authorization. Resolve effective plan (revised if revision ran, else original) + review; require exact pass; retain every REQ/BR/AC id; enforce Mock policy; validate schema/source binding+writeSet containment; materialize `contracts/frontend-implementation-contract.json` from the **single** fenced contract block (multiple candidates fail closed `invalid-output`). Fallback only when conditional primary absent; malformed primary fails closed. Generation-time blocked Mock yields one blocking shell node, no writer.
+- **`frontend-design-policy-shell`**: read-only deterministic design check (UI coverage, evidence resolvable/fresh, Mock strategy bound to frozen commands, component choice `specReference`, targetPaths boundary, dependency authorization, UI state ownership, requirement coverage); passes by materializing the single authoritative `frontend-implementation-contract-v1`. Blocked ends the run without a model reformat step.
   - `verificationTarget.commandLabel` must be a **frozen command label** from `verifyEvidence.commandLabels`; others fail closed (`invalid-output`). Empty frozen set (no `run.json`) skips check.
   - `mockApi.strategy !== "not-needed"` fails closed when `mockCommandLabels` empty (`no authorized Mock verification commands`).
-  - OpenSpec policy: `task.json.frontendOpenspec.policy` (default `cited`); candidates = `requiredReadPaths` ∪ task-source citations; effective plan must append one fenced `openspec-citations` block (one JSON `{"path","section","line"}` per line). Candidates non-empty but block missing/unparseable → `openspec-citation-block-unparseable`; candidate not cited → `openspec-not-cited`; cited path without read event → `openspec-citation-not-read` (anti-fabrication). Empty candidates skip enforcement. `scan-strict` keeps full-read semantics (`openspec-not-read`); both modes keep `candidate-missing-drift`.
-  - Component conformance: missing `uiComponentChoices` (frozen bucket non-empty + UI-visible work) → `component-choices-missing`; bad/uncited `specReference.path` → `component-spec-reference-invalid` / `component-spec-not-cited`.
-  - revisionPatch mode: revision output is an RFC 7386 merge-patch delta applied on the original canonical contract node (`planFallbackFromNodeIds[0]`); protected skeleton paths remain immutable. Legacy DAGs keep full-contract semantics. Size guard: canonical serialization >64KB → `retryable-invalid` + `contract-too-large`.
+  - OpenSpec policy: `task.json.frontendOpenspec.policy` (default `cited`); `specRoots` defaults to OpenSpec + ai_workspace and may be fixed during task preparation from an explicitly named normative directory. In cited mode the selector determines the required subset; declared paths/task-source citations cannot be downgraded. Effective plan cites only its required/used specs in one fenced `openspec-citations` block. `scan-strict` keeps full-read semantics (`openspec-not-read`); both modes keep `candidate-missing-drift`.
+  - Component conformance: missing `uiComponentChoices` (frozen bucket non-empty + UI-visible work) → `component-choices-missing`; bad/uncited `specReference.path` → `component-spec-reference-invalid` / `component-spec-not-cited`; at least one `decision=specified` choice must bind to the frozen component/theme bucket → `component-spec-choice-unbound`.
+  - Canonical serialization (UTF-8) >64KB → `retryable-invalid` + `contract-too-large`.
+- **`frontend-writer-admission-shell`**: sole write authorization for `frontend-implement-pi`. Derives and freezes the concrete writeSet (implementation targets ∪ non-static verification target files), pre-writer baseline, and admission digest (Mock strategy, allowed strategies digest, frozen command digest, `productionDefaultOff`, real-integration expectation); writes `contracts/frontend-writer-admission-result.json` (schemaId `frontend-writer-admission-shell-v1`). The scheduler checks before queueing and before executing the writer: only `admitted` releases it, otherwise SKIPPED + `frontend-prewrite-not-authorized`. Admission blocked (`candidate-contract-invalid` / `prewrite-blocked`) is forced `failed` at aggregation.
 - **`frontend-implement-pi`**: sole regular exclusive writer; uses `frontend-bounded-implement` (not this skill). Stay in `writeSet`; real requests default-on. Atomic handler/intercept/adapter with tests. Stop on forbidden paths/guesses. First line `IMPLEMENTATION_OUTCOME: changed|already-satisfied|blocked`; runtime checks against attributed diff. Optional mock-verify when frozen; static+behavior always; behavior must prove page consumption. `not-needed` keeps real integration pending unless real backend has fresh evidence.
 
+## Typed terminal protocol
+
+- `frontend-plan-pi` commits incremental `record_*` facts plus one `finalize_plan` (plan).
+- `frontend-design-review-pi` commits `approve_design` | `request_design_changes` (request carries typed issueCategory + evidenceRefs + findings).
+- `frontend-review-pi` commits `approve_review` | `request_review_changes` (request carries typed issueCategory + evidenceRefs + findings).
+- These committed typed tools replace `VERDICT:` first-line parsing; the verdict is consumed only as deterministic data input by downstream admission/closeout.
+
 ## Contract / trace / stages (M1–M2)
 
-- `frontend-verify-assess-shell` runs Mock/static/behavior groups, binds `verificationTargets` to command labels+evidence, writes `frontend-verification-trace.json`+`frontend-repair-assessment.json`; browser/visual stay `not-run`.
-- `frontend-review-context-shell` captures real diff; combines contract, effective trace, repair assessment, diff into `contracts/frontend-review-context.json`.
+- `frontend-verify-shell` runs frozen lint/Mock/static/behavior groups, binds `verificationTargets` to command labels+evidence, writes `frontend-lint-assessment.json` + `frontend-verification-trace.json`; any verification failure is terminal and materializes `frontend-verify-failure-v1` (failureClass / failureOwner / restartPhase) for recovery routing — no same-run repair. Browser/visual stay `not-run`.
+- `frontend-review-context-shell` captures the real diff after the pre-writer baseline; combines contract, lint assessment, effective trace, and diff into `contracts/frontend-review-context.json`.
 - Implement stages: (1) contract confirm (2) tests sync (3) component/UI (4) API/Mock (5) frozen checks (6) diff cleanup. Summary: Contract Ref, Changed Files, Requirements, UI States, Tests, Verification Attempts, Deviations, Residual Risks.
 
-## Repair (M3)
+## Terminal failure & recovery (M3)
 
-Only `eligible=true` runs `frontend-repair-pi` (same writeSet; no re-spec; max 1 attempt) + `frontend-reverify-shell`. No-failure skips both. Non-repairable contract/path/dependency/credential/deploy/spec-unclear failures fail closed.
+Verification, design-review, or final-review failure is terminal — no same-run repair. `frontend-verify-shell` materializes `frontend-verify-failure-v1`; `request_design_changes` / `request_review_changes` block downstream admission/closeout. Recovery routes through the recovery capsule / new-dag; there is no same-run repair branch.
 
 ## Risk & capability (M4–M6)
 
-Deterministic risk, no model; high-risk beats small; supervised never small. Standard/high-risk: 15 top-level nodes; small: 13 (omits revision + final review). Capability seed injects adapters; openspec specs and task sources outrank adapter guidance. A11y: static/component tools only when present; Browser a11y always not-run.
+Deterministic risk, no model; high-risk beats small; supervised never small. Topology by shape: Micro 7 (`frontend-contract-import-shell` → `frontend-writer-admission-shell` → `frontend-implement-pi` → `frontend-verify-shell` → `frontend-review-context-shell` → `frontend-review-pi` → `frontend-closeout-shell`), Small 10 (main chain minus the independent `frontend-design-review-pi`), Standard/High 11 (`frontend-contract-pi` → `frontend-scout-pi` → `frontend-plan-pi` → `frontend-design-policy-shell` → `frontend-design-review-pi` → `frontend-writer-admission-shell` → `frontend-implement-pi` → `frontend-verify-shell` → `frontend-review-context-shell` → `frontend-review-pi` → `frontend-closeout-shell`). Capability seed injects adapters; openspec specs and task sources outrank adapter guidance. A11y: static/component tools only when present; Browser a11y always not-run.

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/loop-agent/references/hybrid-dag.md

@@ -16,7 +16,7 @@
 
 对于默认 `standard` 任务，生成器先读取 `source/需求.md` 中的结构化任务类型，再结合 `allowedPaths` 与 React/Next/Vue 强工程证据做确定性分类。确认是前端项目且任务不是明确后端、前后端混合、排除前端或仅文档/测试范围时，默认选择 `frontend-implementation` DAG，不依赖需求关键词。分类不会把普通后端实现路由到 `backend-test`；显式 profile、`workflowPolicy` 或 supervised quality gate 只记录治理强度，不把已识别的前端业务 workflow 换回通用模板。
 
-前端专用链保留独立 contract/scout；plan 同时选择 Mock/API 策略并输出结构化 implementation contract。design initial pass 直接使用原计划，只有 request-revision 才运行 revision/final review；small-risk 只执行一次 design review。`frontend-prewrite-gate-shell` 合并生效 verdict、REQ/BR/AC 覆盖、Mock policy 和 contract 物化，是唯一写入授权。实现后 `frontend-verify-assess-shell` 合并 Mock/static/behavior/trace/assessment；只有 `eligible=true` 才运行同 writeSet 的 repair 和 `frontend-reverify-shell`。`frontend-review-context-shell` 绑定真实 diff 与有效验证证据后再 review/closeout。standard/high-risk 为 15 个顶层节点，small-risk 为 13；绿色路径执行 11 个节点、7 次 Pi。生成期 blocked Mock 只生成一个确定性阻塞节点且没有 writer。
+前端专用链保留独立 contract/scout；plan 通过增量 typed `record_*` 工具提交决策账本并以唯一 `finalize_plan` 收口（无 fenced JSON 文本协议）。写授权由 `frontend-design-policy-shell`（确定性设计检查 + 物化唯一 authoritative `frontend-implementation-contract-v1`）与 `frontend-writer-admission-shell`（唯一写入授权：派生并冻结 writeSet、pre-writer baseline、admission digest，`admitted` 才放行 writer）承接；design review 与 final review 的权威终态是 committed typed tool（`approve_design|request_design_changes`、`approve_review|request_review_changes`）。实现后 `frontend-verify-shell` 合并 lint/Mock/static/behavior/trace；任何验证失败都是 terminal，物化 `frontend-verify-failure-v1` 供 recovery 路由，无同 run repair。`frontend-review-context-shell` 绑定真实 diff 与有效验证证据后再 review/closeout。拓扑按 shape 路由：Micro 7 / Small 10 / Standard-High 11 个顶层节点；Standard/High 完整主链为 `frontend-contract-pi` → `frontend-scout-pi` → `frontend-plan-pi` → `frontend-design-policy-shell` → `frontend-design-review-pi` → `frontend-writer-admission-shell` → `frontend-implement-pi` → `frontend-verify-shell` → `frontend-review-context-shell` → `frontend-review-pi` → `frontend-closeout-shell`，Small 去掉独立 `frontend-design-review-pi`，Micro 为 `frontend-contract-import-shell` → `frontend-writer-admission-shell` → `frontend-implement-pi` → `frontend-verify-shell` → `frontend-review-context-shell` → `frontend-review-pi` → `frontend-closeout-shell`。生成期 blocked Mock 只生成一个确定性阻塞节点且没有 writer。
 
 > Backend-test Markdown-first：先由确定性环境 Shell 检查 clean env 中 Python/pytest、常见配置、conftest/fixture、test root、server entry 和 HTML renderer，失败时不消耗模型调用。随后 Pi 生成中文 README 索引与模块用例卡片并独立 Review `testcase/md/**`。第 4 节点只把前置条件、操作步骤、预期结果作为必选章节，并检查 Case ID、业务 AC、步骤/预期和占位措辞；不校验需求来源引用有效性或 Markdown sensitive-shaped 内容。pytest writer 为每次真实接口调用记录脱敏、有界的请求 method/URL/参数摘要和响应 status/body 摘要。第 6 节点只扫描每条 Case 明确映射的 pytest 脚本，同时支持模块级函数和 pytest class 方法，并把缺少请求/响应日志、递归脱敏或有界截断证据记录为 advisory。第 4/6 节点均写 PASS/FAIL findings 而不阻断后续；pytest 仍只运行一次，生成 JUnit，并把 Markdown 名称/场景/脚本映射与同一 JUnit 合成为按测试概览、质量校验、失败概览、用例执行明细和技术证据组织的中文 self-contained HTML 与 Markdown facts。最终 Pi 按固定简洁结构汇总 advisory 状态、执行事实和 L-5 结论。active 流程不要求模型生成 backend-test 业务 JSON。