android2harmony 0.1.6 → 0.1.8

package/skills/a2h-spec-implement/scripts/test/l2_run.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+// l2_run.mjs — L2 execution-chain script: device-side E2E suite aa test → observation pull-back → observations.json bundling, one invocation.
+//
+// Execution vehicle for hmos-logic-code L2 self-test (TPs live in suite code, asserted on device; l2-e2e-uitest.md):
+// the deterministic pipeline (execute / pull back / bundle / mechanical routing) belongs to the script. Multiple cases per invocation (serial within batch, same device).
+// Before the batch the script itself force-stops + bm clean -d to reset fixtures (no switch): green must be earned from an empty fixture.
+// L3 acceptance is a separate layer: the orchestrator's 步骤④.7 hands the frozen TEST_CASE to a2h-integration-test, which drives the device through the self-tester agent. This script is the delivery bar, that one is acceptance.
+//
+// Usage:
+//   node scripts/test/l2_run.mjs --device <sn> --bundle <bundle> --out-dir <round-dev-dir>/l2 \
+//       --cases E2E_<feat>_1_1,E2E_<feat>_1_4@pair [--timeout 300000] [--density 3.375] [--display 1272x2756]
+//
+// stdout: summary JSON (per suite: execution_status / bundle path / failure digest) for the agent to read and judge.
+//
+// execution_status mechanical routing (l2-e2e-uitest.md routing table; string matching only, semantics belong to judge):
+//   EXEC-GAP step N present → STUCK; TP-n assertion failure → COMPLETE (with device-assertions failure items);
+//   Failure:0 and Error:0 → COMPLETE(pass); no runner summary / infrastructure error → BLOCKED.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { hdcRun } from "../device_ui_core.mjs";
+import { emit } from "../_lib/common.mjs";
+
+const DEVICE_FILES = "/data/app/el2/100/base/{bundle}/files"; // physical path (recv does not resolve sandbox paths; verified)
+const HDC_HOST_TIMEOUT_BUFFER_MS = 90000; // aa test host-side hdc wait = device-side timeout + this buffer (ms), so the device's own timeout log is read instead of the host killing hdc first
+
+// hdc failure classification: command-not-found vs timeout/OS error.
+// spawnSync does not throw; failure lands in result.error — converted to exceptions here so callers route via try/catch.
+class HdcNotFound extends Error {}
+class HdcError extends Error {
+  constructor(kind, detail) { super(`${kind}: ${detail}`); this.kind = kind; this.detail = detail; }
+}
+
+function kindOf(e) {
+  // Map a caught exception to its classification tag for branch routing. Unmanaged exceptions return null → rethrow.
+  if (e instanceof HdcNotFound) return "not-found";
+  if (e instanceof HdcError) return e.kind;
+  if (e && typeof e.code === "string" && e.syscall) return e.code === "ENOENT" ? "not-found" : "os-error";
+  return null;
+}
+const detailOf = (e) => (e instanceof HdcError ? e.detail : String((e && e.message) || e));
+
+function hdc(device, args, timeoutMs = 120000) {
+  // Delegates to device_ui_core.hdcRun (single spawnSync/windowsHide source; list args, no shell →
+  // immune to MSYS path rewriting). Keeps L2's error classification; timeout unit = ms (uniform across hdc wrappers).
+  const p = hdcRun(device, args, timeoutMs);
+  if (p.error) {
+    if (p.error.code === "ENOENT") throw new HdcNotFound("hdc executable not found");
+    const isTimeout = p.error.code === "ETIMEDOUT" || !!p.signal;
+    throw new HdcError(isTimeout ? "timeout" : "os-error", String(p.error.message || p.error.code || p.error));
+  }
+  return [p.status ?? -1, (p.stdout || "") + (p.stderr || "")]; // encoding:utf8 decodes invalid bytes with replacement chars
+}
+
+function moveFile(src, dest) {
+  // Same-volume rename; falls back to copy+unlink across volumes.
+  try { fs.renameSync(src, dest); }
+  catch (e) { if (e.code === "EXDEV") { fs.copyFileSync(src, dest); fs.unlinkSync(src); } else throw e; }
+}
+
+function recv(device, remote, destDir) {
+  // Pull back via an ASCII temp dir: hdc.exe garbles and fails to write local paths containing CJK (verified); Node's move is unaffected.
+  // Returns [ok, tail of hdc output]: recv failures must leave a trace so the judge can separate "recv fault" from "material gap".
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "runcase_"));
+  try {
+    const [rc, out] = hdc(device, ["file", "recv", remote, tmp]);
+    let moved = 0;
+    for (const name of fs.readdirSync(tmp)) { moveFile(path.join(tmp, name), path.join(destDir, name)); moved += 1; }
+    const ok = moved > 0 && rc === 0 && !out.includes("[Fail]");
+    return [ok, out.trim().slice(-200)];
+  } finally {
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* never leave the temp dir behind, even on error */ }
+  }
+}
+
+function aaTest(device, bundle, suite, timeoutMs, logPath) {
+  const [, out] = hdc(device, ["shell", "aa", "test", "-b", bundle, "-m", "entry_test",
+    "-s", "unittest", "OpenHarmonyTestRunner",
+    "-s", "class", suite, "-s", "timeout", String(timeoutMs)],
+    timeoutMs + HDC_HOST_TIMEOUT_BUFFER_MS);
+  fs.writeFileSync(logPath, out, "utf8");
+  return out;
+}
+
+function route(logText) {
+  // Mechanical routing: prefix contract only (phase-marked throws), no semantic judgment.
+  const gap = logText.match(/EXEC-GAP step \d+[^\r\n]*/);
+  if (gap) return ["STUCK", [gap[0]]];
+  const fails = logText.match(/TP-\d+[^\r\n]*/g) || [];
+  const mF = logText.match(/Failure:\s*(\d+)/);
+  const mE = logText.match(/Error:\s*(\d+)/);
+  if (fails.length) return ["COMPLETE", fails];
+  if (/Tests run:\s*0/.test(logText)) { // 0 tests run = suite unregistered / wrong name, not a pass
+    return ["BLOCKED", ["Tests run: 0 — 套件未注册或套件名不对(查 List.test.ets 与 E2E_<feature>_<caseId>)"]];
+  }
+  if (mF && mE && mF[1] === "0" && mE[1] === "0") return ["COMPLETE", []];
+  return ["BLOCKED", [logText.slice(-500).trim()]]; // no summary / infra error → environment; raw log tail left for judge
+}
+
+function routeLogs(logPaths) {
+  // Route each suite log separately, keep the worst status — joining pair logs first lets the
+  // _pre runner summary mask a summary-less _post failure (false COMPLETE).
+  const rank = { COMPLETE: 0, BLOCKED: 1, STUCK: 2 };
+  let status = "COMPLETE";
+  const notes = [];
+  for (const p of logPaths) {
+    const [s, n] = route(fs.readFileSync(p, "utf8"));
+    if (rank[s] > rank[status]) status = s;
+    const tag = logPaths.length > 1 ? `[${path.basename(p, ".log")}] ` : "";
+    notes.push(...n.map((x) => tag + x));
+  }
+  return [status, notes];
+}
+
+function runOne(suite, pair, device, bundle, outDir, timeoutMs, density, display) {
+  const d = path.join(outDir, suite);
+  fs.mkdirSync(d, { recursive: true });
+  const logs = [];
+  if (pair) {
+    for (const phase of ["pre", "post"]) {
+      const log = path.join(d, `aa-test-${phase}.log`);
+      aaTest(device, bundle, `${suite}_${phase}`, timeoutMs, log);
+      logs.push(log);
+      if (phase === "pre") hdc(device, ["shell", "aa", "force-stop", bundle]);
+    }
+  } else {
+    const log = path.join(d, "aa-test.log");
+    aaTest(device, bundle, suite, timeoutMs, log);
+    logs.push(log);
+  }
+  const [status, notes] = routeLogs(logs);
+
+  // Observation pull-back: obs json (both pair suites write the same one) + screenshots listed in its anchors
+  const remote = DEVICE_FILES.replace("{bundle}", bundle);
+  const obsName = `obs_${suite}.json`;
+  const [, obsErr] = recv(device, `${remote}/${obsName}`, d);
+  let anchors = {};
+  const obsPath = path.join(d, obsName);
+  if (fs.existsSync(obsPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(obsPath, "utf8"));
+      anchors = (parsed && parsed.anchors) || {};
+    } catch { notes.push(`obs JSON 解析失败: ${obsName}`); }
+    for (const a of Object.values(anchors)) {
+      const shot = a && a.screenshot;
+      if (shot) {
+        const [shotOk, shotErr] = recv(device, `${remote}/${shot}`, d);
+        if (!shotOk || !fs.existsSync(path.join(d, path.basename(shot)))) notes.push(`截图回拉失败: ${shot}: ${shotErr}`);
+      }
+    }
+  } else if (status === "COMPLETE") {
+    notes.push(`obs 文件缺失（judge 按材料缺口处理; recv: ${obsErr || "no output"}）`);
+  }
+
+  const bundleObj = {
+    case: suite, "execution-status": status,
+    "device-assertions": status === "COMPLETE" && notes.length === 0 ? "pass" : notes,
+    anchors, density, display, "aa-test-log": logs, "obs-file": fs.existsSync(obsPath) ? obsPath : null,
+  };
+  fs.writeFileSync(path.join(d, "observations.json"), JSON.stringify(bundleObj, null, 2), "utf8");
+  return { case: suite, execution_status: status, notes, bundle: path.join(d, "observations.json") };
+}
+
+// Kept independent of _lib/common.mjs parseFlags: this coerces typed values (--timeout int,
+// --density float) and enforces its own required-flag set; the shared flat parser is string-only.
+function parseArgs(argv) {
+  const a = { timeout: 30000, density: null, display: null };
+  const map = { "--device": "device", "--bundle": "bundle", "--out-dir": "outDir",
+    "--cases": "cases", "--timeout": "timeout", "--density": "density", "--display": "display" };
+  for (let i = 0; i < argv.length; i++) {
+    let t = argv[i], inline = null;
+    const eq = t.indexOf("=");
+    if (t.startsWith("--") && eq !== -1) { inline = t.slice(eq + 1); t = t.slice(0, eq); }
+    if (!(t in map)) { process.stderr.write(`未知参数: ${t}\n`); process.exit(2); }
+    let val;
+    if (inline !== null) val = inline;
+    else { val = argv[++i]; if (val == null) { process.stderr.write(`${t} 缺值\n`); process.exit(2); } }
+    const key = map[t];
+    if (key === "timeout") {
+      a.timeout = parseInt(val, 10);
+      if (!Number.isFinite(a.timeout) || a.timeout <= 0) { process.stderr.write(`--timeout 非法整数: ${val}\n`); process.exit(2); }
+    } else if (key === "density") {
+      a.density = parseFloat(val);
+      if (!Number.isFinite(a.density) || a.density <= 0) { process.stderr.write(`--density 非法数值: ${val}\n`); process.exit(2); }
+    } else a[key] = val;
+  }
+  for (const [flag, key] of [["--device", "device"], ["--bundle", "bundle"], ["--out-dir", "outDir"], ["--cases", "cases"]]) {
+    if (a[key] == null) { process.stderr.write(`缺少必填参数 ${flag}\n`); process.exit(2); }
+  }
+  return a;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const display = args.display ? args.display.toLowerCase().split("x").map((x) => parseInt(x, 10)) : null;
+  if (display && (display.length !== 2 || display.some((n) => !Number.isFinite(n) || n <= 0))) {
+    process.stderr.write(`--display 非法(期望 WxH): ${args.display}\n`); process.exit(2);
+  }
+  // Mandatory fixture reset (mechanical, no switch): suite green must be earned from an empty fixture. Clears app data (DB/grants);
+  // /storage media files are unaffected; rebuild is done by the suite's establish.
+  let fixtureReset;
+  try {
+    hdc(args.device, ["shell", "aa", "force-stop", args.bundle]);
+    const [rcC, outC] = hdc(args.device, ["shell", "bm", "clean", "-n", args.bundle, "-d"]);
+    fixtureReset = rcC === 0 && outC.toLowerCase().includes("success") ? "ok" : outC.trim().slice(-120);
+  } catch (e) {
+    const kind = kindOf(e);
+    if (kind === "not-found") {
+      emit({ ok: false, error: "hdc 不可执行（未找到命令），整批终止", results: [] });
+      process.exit(2);
+    } else if (kind === "timeout" || kind === "os-error") {
+      fixtureReset = `${kind}: ${detailOf(e)}`; // record reset failure; batch still runs (aa test will surface it)
+    } else throw e;
+  }
+  const results = [];
+  for (let spec of args.cases.split(",")) {
+    spec = spec.trim();
+    const pair = spec.endsWith("@pair");
+    const suite = pair ? spec.slice(0, -5) : spec;
+    try {
+      results.push(runOne(suite, pair, args.device, args.bundle, args.outDir, args.timeout, args.density, display));
+    } catch (e) {
+      const kind = kindOf(e);
+      if (kind === "not-found") {
+        // hdc itself not executable → whole-batch environment fault; still finish via the stdout JSON contract (never a bare traceback)
+        results.push({ case: suite, execution_status: "BLOCKED", notes: ["hdc 不可执行（未找到命令）"], bundle: null });
+        emit({ ok: false, error: "hdc 不可执行（未找到命令），整批终止", results });
+        process.exit(2);
+      } else if (kind === "timeout" || kind === "os-error") {
+        // Per-case environment fault (hdc timeout / recv IO error) → this case BLOCKED, remaining cases still run
+        results.push({ case: suite, execution_status: "BLOCKED", notes: [`${kind}: ${detailOf(e)}`], bundle: null });
+      } else throw e;
+    }
+  }
+  emit({ ok: true, fixture_reset: fixtureReset, results });
+}
+
+export { route, routeLogs }; // pure routing, exported for offline log-fixture tests
+
+// Run only when invoked directly (realpath tolerates junction/symlink invocation).
+let isMain = false;
+try { isMain = import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href; } catch { /* no argv[1] */ }
+if (isMain) main();

package/skills/a2h-spec-implement/scripts/test/tp_coverage.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * tp_coverage.mjs — 核对 E2E 套件对 test_case.md 测试点(TP)的覆盖情况。
+ *
+ * 防自证门禁：断言是拿来判 coder 自己写的代码的，所以每个 TP 都必须有一条
+ * 对应断言。本脚本机械核对这一点，避免"少写/弱化/跳过测试点"被当成场景属性混过去。
+ *
+ * 用法：
+ *   node tp_coverage.mjs --test-case <test_case.md> --suites-dir <ohosTest 目录>
+ *                        [--case-ids 1-1,1-2] [--format json|text]
+ *
+ * 约定（来源：a2h-test-case-generation/references/contract.md §3 用例格式
+ *              与 a2h-spec-implement/references/l3-e2e-uitest.md）：
+ *   用例头   `### Scenario <id>: <标题> [PX] [类型] [SKIP: reason]`
+ *   测试点   `- 测试点：` 段内每行 `TP-N（步骤M后）: <断言>`
+ *   套件     `describe('E2E_<feature>_<caseId>' ...)`，caseId 中 `-` 记为 `_`
+ *   断言     `it('TP-N: <简述>' ...)` —— it 名以 TP 编号开头，使覆盖可机械核对
+ *
+ * 退出码：0 = 全覆盖；1 = 存在缺口；2 = 用法/读取错误。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ---------- 参数 ----------
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) out[key] = true;
+    else { out[key] = next; i++; }
+  }
+  return out;
+}
+
+const args = parseArgs(process.argv.slice(2));
+
+if (!args['test-case'] || !args['suites-dir']) {
+  console.error('用法: node tp_coverage.mjs --test-case <test_case.md> --suites-dir <dir> [--case-ids a,b] [--format json|text]');
+  process.exit(2);
+}
+
+const testCasePath = args['test-case'];
+const suitesDir = args['suites-dir'];
+const format = args['format'] === 'text' ? 'text' : 'json';
+const onlyCaseIds = typeof args['case-ids'] === 'string'
+  ? args['case-ids'].split(',').map(s => s.trim()).filter(Boolean)
+  : null;
+
+// ---------- 解析 test_case.md ----------
+
+/** 场景头：### Scenario 1-2: 标题 [P0] [COUNTEREXAMPLE] [SKIP: reason] */
+const SCENARIO_RE = /^#{2,4}\s*Scenario\s+([^\s:：]+)\s*[:：]\s*(.*)$/;
+/** 测试点行：TP-3（步骤2后）: 断言  —— 允许前置的 `-`/`*`/空白 */
+const TP_LINE_RE = /^\s*(?:[-*]\s*)?TP[-_]?(\d+)\s*(?:（[^）]*）|\([^)]*\))?\s*[:：]/;
+/** 测试点段起始 */
+const TP_HEADER_RE = /^\s*[-*]?\s*测试点\s*[:：]/;
+/** 其它字段行（用于判定测试点段结束） */
+const FIELD_RE = /^\s*[-*]\s*(前置条件|依赖|动作|预期结果|知识库)\s*[:：]/;
+
+function parseTestCases(text) {
+  const lines = text.split(/\r?\n/);
+  const cases = [];
+  let cur = null;
+  let inTpBlock = false;
+
+  for (const line of lines) {
+    const m = SCENARIO_RE.exec(line);
+    if (m) {
+      if (cur) cases.push(cur);
+      const id = m[1].trim();
+      const rest = m[2] || '';
+      const tags = [...rest.matchAll(/\[([^\]]+)\]/g)].map(t => t[1].trim());
+      cur = {
+        case_id: id,
+        title: rest.replace(/\[[^\]]*\]/g, '').trim(),
+        tags,
+        skip: tags.some(t => /^SKIP\s*[:：]?/i.test(t)),
+        counterexample: tags.some(t => /COUNTEREXAMPLE/i.test(t)),
+        tps: [],
+      };
+      inTpBlock = false;
+      continue;
+    }
+    if (!cur) continue;
+
+    if (TP_HEADER_RE.test(line)) { inTpBlock = true; continue; }
+    // 遇到其它字段或新标题，测试点段结束
+    if (inTpBlock && (FIELD_RE.test(line) || /^#{1,4}\s/.test(line))) inTpBlock = false;
+
+    // TP 行本身即可识别，不强制依赖段落状态（容忍格式漂移）
+    const tp = TP_LINE_RE.exec(line);
+    if (tp && (inTpBlock || true)) {
+      const n = Number(tp[1]);
+      if (!cur.tps.includes(n)) cur.tps.push(n);
+    }
+  }
+  if (cur) cases.push(cur);
+  return cases;
+}
+
+// ---------- 解析 E2E 套件 ----------
+
+const DESCRIBE_RE = /describe\s*\(\s*['"`]([^'"`]+)['"`]/g;
+const IT_RE = /\bit\s*\(\s*['"`]([^'"`]+)['"`]/g;
+/** it 名中的 TP 编号：TP-2 / TP_2 / tp2 开头 */
+const IT_TP_RE = /^\s*TP[-_]?(\d+)\b/i;
+
+function walk(dir, acc = []) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return acc; }
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walk(p, acc);
+    else if (e.isFile() && /\.test\.ets$/i.test(e.name) && /^E2E_/i.test(e.name)) acc.push(p);
+  }
+  return acc;
+}
+
+function parseSuites(files) {
+  const suites = [];
+  for (const f of files) {
+    let src;
+    try { src = fs.readFileSync(f, 'utf8'); } catch { continue; }
+    const names = [...src.matchAll(DESCRIBE_RE)].map(m => m[1]);
+    const its = [...src.matchAll(IT_RE)].map(m => m[1]);
+    const tps = [];
+    for (const n of its) {
+      const m = IT_TP_RE.exec(n);
+      if (m) { const v = Number(m[1]); if (!tps.includes(v)) tps.push(v); }
+    }
+    for (const name of names.filter(n => /^E2E_/i.test(n))) {
+      suites.push({ suite: name, file: f, its, tp_ids: tps });
+    }
+    // 文件名是 E2E_* 但没有匹配的 describe —— 仍记录，便于诊断
+    if (!names.some(n => /^E2E_/i.test(n))) {
+      suites.push({ suite: path.basename(f).replace(/\.test\.ets$/i, ''), file: f, its, tp_ids: tps, describe_missing: true });
+    }
+  }
+  return suites;
+}
+
+/** caseId `1-2` → 套件后缀 `_1_2`；套件名 E2E_<feature>_<caseId> 按后缀匹配 */
+function matchSuites(caseId, suites) {
+  const sanitized = caseId.replace(/-/g, '_');
+  return suites.filter(s => {
+    const n = s.suite;
+    return n === `E2E_${sanitized}` || n.endsWith(`_${sanitized}`);
+  });
+}
+
+// ---------- 核对 ----------
+
+let text;
+try { text = fs.readFileSync(testCasePath, 'utf8'); }
+catch (e) { console.error(`读取失败: ${testCasePath} — ${e.message}`); process.exit(2); }
+
+const allCases = parseTestCases(text);
+const suiteFiles = walk(suitesDir);
+const suites = parseSuites(suiteFiles);
+
+const selected = onlyCaseIds
+  ? allCases.filter(c => onlyCaseIds.includes(c.case_id))
+  : allCases;
+
+const report = [];
+for (const c of selected) {
+  const matched = matchSuites(c.case_id, suites);
+  const covered = [...new Set(matched.flatMap(s => s.tp_ids))].sort((a, b) => a - b);
+  const expected = [...c.tps].sort((a, b) => a - b);
+  const missing = expected.filter(n => !covered.includes(n));
+  const extra = covered.filter(n => !expected.includes(n));
+
+  let status;
+  if (c.skip) status = 'SKIPPED_CASE';                        // 用例本身标了 [SKIP:]，不要求转写
+  else if (matched.length === 0) status = 'NO_SUITE';         // 完全没有对应套件
+  else if (c.counterexample) status = matched.some(s => s.its.length > 0) ? 'OK' : 'NO_ASSERTION';
+  else if (expected.length === 0) status = 'NO_TP_DECLARED';  // 普通用例却没写测试点 → 用例侧缺陷
+  else if (missing.length > 0) status = 'MISSING_TP';
+  else status = 'OK';
+
+  report.push({
+    case_id: c.case_id,
+    title: c.title,
+    tags: c.tags,
+    status,
+    expected_tps: expected,
+    covered_tps: covered,
+    missing_tps: missing,
+    unmapped_its: extra,
+    suites: matched.map(s => s.suite),
+  });
+}
+
+const gapStatuses = new Set(['NO_SUITE', 'MISSING_TP', 'NO_ASSERTION', 'NO_TP_DECLARED']);
+const gaps = report.filter(r => gapStatuses.has(r.status));
+const ok = gaps.length === 0;
+
+const summary = {
+  ok,
+  test_case: testCasePath,
+  suites_dir: suitesDir,
+  cases_checked: report.length,
+  cases_ok: report.filter(r => r.status === 'OK').length,
+  cases_skipped: report.filter(r => r.status === 'SKIPPED_CASE').length,
+  cases_with_gaps: gaps.length,
+  tps_expected: report.reduce((a, r) => a + r.expected_tps.length, 0),
+  tps_covered: report.reduce((a, r) => a + r.expected_tps.filter(n => r.covered_tps.includes(n)).length, 0),
+  suites_found: suites.length,
+  gaps,
+  per_case: report,
+};
+
+if (format === 'text') {
+  console.log(`TP 覆盖核对 — ${ok ? 'PASS' : 'FAIL'}`);
+  console.log(`用例 ${summary.cases_checked}（OK ${summary.cases_ok} / 跳过 ${summary.cases_skipped} / 有缺口 ${summary.cases_with_gaps}），测试点 ${summary.tps_covered}/${summary.tps_expected}，套件 ${summary.suites_found}`);
+  for (const r of report) {
+    if (r.status === 'OK' || r.status === 'SKIPPED_CASE') continue;
+    const detail = r.status === 'MISSING_TP' ? ` 缺 TP: ${r.missing_tps.join(',')}` : '';
+    console.log(`  [${r.status}] ${r.case_id} ${r.title}${detail}`);
+  }
+} else {
+  console.log(JSON.stringify(summary, null, 2));
+}
+
+process.exit(ok ? 0 : 1);

package/skills/a2h-spec-implement/scripts/ui_memory.mjs

@@ -0,0 +1,161 @@
+// UI-memory CLI —— index / point-read / validated append / physical compaction over the two
+// append-only UI-memory jsonl files (ui-nav.jsonl keyed by page, ui-flows.jsonl keyed by flow).
+//
+// Protocol authority: rules/pipeline/memory/ui-memory.md. Readers NEVER load the whole files:
+// `keys` is the recall index (every key, one line each), `get` folds one key. Folding = latest
+// line per key for code-seeded content; coordinate residue is device-scoped, so `get --device P`
+// prefers the newest line verified on P (matched_device=true) and otherwise returns the newest
+// any-device line whose coordinate hops the caller must re-confirm. `compact` keeps, per
+// (key, device), only the newest line — run by the orchestrator preflight to bound file growth.
+//
+// Key alias: in ui-nav, `target` is a legal alias of `page` — the two fold as one key.
+// Records with neither key are ignored by keys/get and dropped by compact (reported in `unkeyed`).
+//
+// Commands:
+//   keys    --dir D [--file nav|flows|both]
+//   get     --dir D (--page K | --flow K) [--device P]
+//   append  --dir D --file nav|flows (--json '<obj>' | --json-file P)
+//   compact --dir D [--file nav|flows|both] [--dry-run true]
+import fs from "node:fs";
+import path from "node:path";
+
+import { emit, loadJsonl, lockedAppend, parseFlags, requireFlags, defaultDie as die } from "./_lib/common.mjs";
+
+const FILES = { nav: "ui-nav.jsonl", flows: "ui-flows.jsonl" };
+const keyOf = { nav: (e) => e.page ?? e.target, flows: (e) => e.flow };
+
+// Coordinate residue marker — anything binding a record to one device's pixel space:
+// xy selectors, coordinate swipe/drag endpoints ("from" as a bare [x,y] array; selector-form
+// from is device-invariant), gesture tracks — in both dialects (CLI flags in hop strings, JSON steps).
+const RESIDUE_RE = /--xy\s|"xy"\s*:|--from\s+\d|"from"\s*:\s*\[|--track\s|"tracks?"\s*:/;
+const hasResidue = (entry) => RESIDUE_RE.test(JSON.stringify(entry));
+
+function fileArg(v, dflt = "both") {
+  const f = v.file || dflt;
+  if (!["nav", "flows", "both"].includes(f)) die(`argument --file: invalid choice: '${f}' (choose from 'nav', 'flows', 'both')`);
+  return f === "both" ? ["nav", "flows"] : [f];
+}
+
+function loadKeyed(dir, kind) {
+  // Ordered entries of one file, each tagged with its folded key (null = unkeyed).
+  const entries = loadJsonl(path.join(dir, FILES[kind]));
+  return entries.map((e) => ({ key: keyOf[kind](e) ?? null, entry: e }));
+}
+
+function cmdKeys(argv) {
+  const v = parseFlags(argv, { dir: "dir", file: "file" });
+  requireFlags(v, [{ key: "dir", flag: "dir" }]);
+  const out = {};
+  for (const kind of fileArg(v)) {
+    const by = new Map(); // key → { lines, devices:Set, head (newest), residue }
+    let unkeyed = 0;
+    for (const { key, entry } of loadKeyed(v.dir, kind)) {
+      if (key === null) { unkeyed++; continue; }
+      const cur = by.get(key) || { lines: 0, devices: new Set(), head: null, residue: false };
+      cur.lines++;
+      if (entry.device) cur.devices.add(entry.device);
+      cur.head = entry.head ?? cur.head;
+      cur.residue = cur.residue || hasResidue(entry);
+      by.set(key, cur);
+    }
+    out[kind] = {
+      keys: [...by.entries()].map(([key, c]) => ({ key, lines: c.lines, devices: [...c.devices], head: c.head, residue: c.residue })),
+      unkeyed,
+    };
+  }
+  emit(out);
+}
+
+function cmdGet(argv) {
+  const v = parseFlags(argv, { dir: "dir", page: "page", flow: "flow", device: "device" });
+  requireFlags(v, [{ key: "dir", flag: "dir" }]);
+  if (!v.page === !v.flow) die("exactly one of --page / --flow is required");
+  const kind = v.page ? "nav" : "flows";
+  const want = v.page ?? v.flow;
+  const lines = loadKeyed(v.dir, kind).filter(({ key }) => key === want).map(({ entry }) => entry);
+  if (!lines.length) { emit({ found: false, key: want }); return; }
+  const newest = lines[lines.length - 1];
+  const deviceLines = v.device ? lines.filter((e) => e.device === v.device) : [];
+  const record = deviceLines.length ? deviceLines[deviceLines.length - 1] : newest;
+  const meta = {
+    lines: lines.length,
+    devices: [...new Set(lines.map((e) => e.device).filter(Boolean))],
+    matched_device: deviceLines.length > 0,
+    residue: hasResidue(record),
+  };
+  // The device-matched line may predate a re-seed: hand the caller the newest line too so
+  // the head/stale machinery can reconcile code-seeded fields (protocol § Folding).
+  if (meta.matched_device && record !== newest) meta.newer_seed = newest;
+  emit({ found: true, key: want, record, _meta: meta });
+}
+
+async function cmdAppend(argv) {
+  const v = parseFlags(argv, { dir: "dir", file: "file", json: "json", "json-file": "json_file" });
+  requireFlags(v, [{ key: "dir", flag: "dir" }, { key: "file", flag: "file" }]);
+  const [kind] = fileArg(v, v.file);
+  if (v.file === "both") die("append needs --file nav|flows (not both)");
+  if (!v.json === !v.json_file) die("exactly one of --json / --json-file is required");
+  let entry;
+  try { entry = JSON.parse(v.json ?? fs.readFileSync(v.json_file, "utf8")); }
+  catch (e) { die(`record is not valid JSON: ${e.message}`); }
+
+  const missing = [];
+  if (keyOf[kind](entry) == null) missing.push(kind === "nav" ? "page" : "flow");
+  if (!entry.head) missing.push("head");
+  if (kind === "nav" && !Array.isArray(entry.path)) missing.push("path[]");
+  if (kind === "flows") {
+    if (!Array.isArray(entry.steps)) missing.push("steps[]");
+    if (!entry.commit_control) missing.push("commit_control");
+    if (!entry.success_signal) missing.push("success_signal");
+  }
+  if (hasResidue(entry) && !entry.device) missing.push("device (record carries coordinate residue — xy/track/from — which is device-scoped)");
+  if (missing.length) die(`record rejected, missing/invalid: ${missing.join(", ")}`);
+
+  const file = path.join(v.dir, FILES[kind]);
+  fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+  await lockedAppend(file, (append) => { append(JSON.stringify(entry) + "\n"); });
+  emit({ ok: true, file: FILES[kind], key: keyOf[kind](entry) });
+}
+
+async function cmdCompact(argv) {
+  const v = parseFlags(argv, { dir: "dir", file: "file", "dry-run": "dry_run" });
+  requireFlags(v, [{ key: "dir", flag: "dir" }]);
+  const dry = v.dry_run === "true";
+  const out = [];
+  for (const kind of fileArg(v)) {
+    const file = path.join(v.dir, FILES[kind]);
+    const keyed = loadKeyed(v.dir, kind);
+    if (!keyed.length) { out.push({ file: FILES[kind], kept: 0, dropped: 0, unkeyed: 0 }); continue; }
+    // Keep, per (key, device), only the last line; preserve original order of the kept lines.
+    const lastIdx = new Map();
+    keyed.forEach(({ key, entry }, i) => { if (key !== null) lastIdx.set(`${key}\u0000${entry.device ?? ""}`, i); });
+    const keepSet = new Set(lastIdx.values());
+    const kept = keyed.filter((_, i) => keepSet.has(i));
+    const unkeyed = keyed.filter(({ key }) => key === null).length;
+    const stat = { file: FILES[kind], kept: kept.length, dropped: keyed.length - kept.length - unkeyed, unkeyed };
+    if (!dry && (stat.dropped || unkeyed)) {
+      // lockedAppend's sidecar lock guards the rewrite against concurrent appenders.
+      await lockedAppend(file, () => {
+        fs.copyFileSync(file, file + ".bak");
+        fs.writeFileSync(file, kept.map(({ entry }) => JSON.stringify(entry)).join("\n") + "\n", "utf8");
+      });
+      stat.backup = FILES[kind] + ".bak";
+    }
+    out.push(stat);
+  }
+  emit({ dry_run: dry, files: out });
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+  const rest = argv.slice(1);
+  if (cmd === "keys") cmdKeys(rest);
+  else if (cmd === "get") cmdGet(rest);
+  else if (cmd === "append") await cmdAppend(rest);
+  else if (cmd === "compact") await cmdCompact(rest);
+  else if (cmd === undefined) die("the following arguments are required: cmd");
+  else die(`argument cmd: invalid choice: '${cmd}' (choose from 'keys', 'get', 'append', 'compact')`);
+}
+
+main();