forgedock 1.28.0 → 1.29.0

package/bin/lean/testmap.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Optional repo caches for the pre-PR step (#4272): `.forge/test-map.json` (scripts/test-map.sh, file glob → check
+ * command) picks the checks for the lane's changed files; `.forge/repo-facts.json` (scripts/repo-facts.sh) is cited to
+ * the builder by path. The test map's commands are run, so it is read from the base ref, then the main checkout, never
+ * the builder-writable lane worktree (#4297); repo facts are looked up in the worktree, then the main checkout. A missing
+ * or invalid file is absent: the lane keeps forge.yaml `learned.test_commands` and today's prompts.
+ *
+ *   node bin/lean/testmap.mjs --map FILE --select FILE...   print the selected commands, one per line
+ */
+import fs from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { globToRegex, shellQuote } from "../../scripts/ci-local/lib.mjs";
+
+export const TEST_MAP_FILE = ".forge/test-map.json";
+export const REPO_FACTS_FILE = ".forge/repo-facts.json";
+
+/** A parsed test map when valid ({version:1, entries:[{command, globs:string[]}]}), else null. */
+export function parseTestMap(text) {
+  let j;
+  try { j = JSON.parse(text); } catch { return null; }
+  if (!j || j.version !== 1 || !Array.isArray(j.entries)) return null;
+  const ok = j.entries.every((e) => e && typeof e.command === "string" && e.command.trim() && Array.isArray(e.globs) && e.globs.length && e.globs.every((g) => typeof g === "string" && g));
+  return ok ? j : null;
+}
+
+/** The first valid test map under `dirs` (in order), or null; never throws. */
+export async function readTestMap(dirs, read) {
+  if (typeof read !== "function") return null;
+  for (const d of dirs.filter(Boolean)) {
+    let text;
+    try { text = await read(join(d, TEST_MAP_FILE)); } catch { continue; }
+    const map = parseTestMap(String(text ?? ""));
+    if (map) return map;
+  }
+  return null;
+}
+
+/** #4297: the valid test map committed at `ref` (`git show <ref>:.forge/test-map.json`), or null; never throws. */
+export async function readTestMapAtRef(git, ref) {
+  if (typeof git !== "function" || !ref) return null;
+  try { return parseTestMap(String((await git(["show", `${ref}:${TEST_MAP_FILE}`])) ?? "")); } catch { return null; }
+}
+
+/** Commands of entries with a glob matching a changed file: map order, deduped; a non-root cwd runs as `cd <cwd> && cmd`. */
+export function selectCommands(map, files) {
+  const out = [];
+  const changed = (Array.isArray(files) ? files : []).map((f) => String(f).replace(/^\.\//, ""));
+  for (const e of map?.entries ?? []) {
+    const res = e.globs.map((g) => globToRegex(g.replace(/^\.\//, "")));
+    if (!changed.some((f) => res.some((re) => re.test(f)))) continue;
+    const cwd = typeof e.cwd === "string" && e.cwd && e.cwd !== "." ? e.cwd : "";
+    const cmd = cwd ? `cd ${shellQuote(cwd)} && ${e.command.trim()}` : e.command.trim();
+    if (!out.includes(cmd)) out.push(cmd);
+  }
+  return out;
+}
+
+/** The path of the first repo-facts file under `dirs` that exists, or null; never throws. */
+export async function factsPath(dirs, exists) {
+  if (typeof exists !== "function") return null;
+  for (const d of dirs.filter(Boolean)) {
+    const p = join(d, REPO_FACTS_FILE);
+    try { if (await exists(p)) return p; } catch { /* absent */ }
+  }
+  return null;
+}
+
+function main(argv) {
+  const i = argv.indexOf("--map"), j = argv.indexOf("--select");
+  if (i < 0 || !argv[i + 1] || j !== i + 2) { console.error("usage: testmap.mjs --map FILE --select FILE..."); return 2; }
+  let text;
+  try { text = fs.readFileSync(argv[i + 1], "utf8"); } catch { console.error(`testmap: cannot read ${argv[i + 1]}`); return 2; }
+  const map = parseTestMap(text);
+  if (!map) { console.error("testmap: invalid test map"); return 2; }
+  const files = argv.slice(j + 1);
+  for (const c of selectCommands(map, files)) console.log(c);
+  return 0;
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/bin/lean/testmap.test.mjs

@@ -0,0 +1,58 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { parseTestMap, readTestMap, selectCommands, factsPath, TEST_MAP_FILE, REPO_FACTS_FILE } from "./testmap.mjs";
+
+const MAP = {
+  version: 1,
+  entries: [
+    { globs: ["**/*.ts", "**/*.tsx"], command: "pnpm run lint", cwd: ".", source: "package.json#scripts.lint" },
+    { globs: ["packages/ui/**/*.tsx"], command: "pnpm run test", cwd: "packages/ui", source: "packages/ui/package.json#scripts.test" },
+    { globs: ["**/*.py"], command: "uv run pytest", cwd: ".", source: "pyproject.toml#tool.pytest" },
+    { globs: ["**/*.go"], command: "golangci-lint run ./...", cwd: ".", source: ".github/workflows/ci.yml#jobs.lint" },
+    { globs: ["**/*.ts"], command: "pnpm run lint", cwd: ".", source: "dup" },
+    { globs: ["dir with space/**"], command: "make x", cwd: "dir with space", source: "x" },
+  ],
+};
+const reader = (files) => async (p) => { if (!(p in files)) throw new Error("ENOENT"); return files[p]; };
+
+describe("test map (#4272)", () => {
+  it("parseTestMap accepts version 1 with command + globs on every entry, rejects the rest", () => {
+    assert.deepEqual(parseTestMap(JSON.stringify(MAP)), MAP);
+    for (const bad of ["", "nope", "null", "{}", '{"version":2,"entries":[]}', '{"version":1}',
+      '{"version":1,"entries":[{"command":"x"}]}', '{"version":1,"entries":[{"command":"","globs":["**"]}]}',
+      '{"version":1,"entries":[{"command":"x","globs":[]}]}', '{"version":1,"entries":[{"command":"x","globs":[3]}]}']) {
+      assert.equal(parseTestMap(bad), null, bad);
+    }
+  });
+
+  it("readTestMap: worktree before main checkout; missing or invalid files are skipped; never throws", async () => {
+    const other = { version: 1, entries: [{ globs: ["**"], command: "make test" }] };
+    assert.deepEqual(await readTestMap(["/wt", "/main"], reader({ [`/wt/${TEST_MAP_FILE}`]: JSON.stringify(MAP), [`/main/${TEST_MAP_FILE}`]: JSON.stringify(other) })), MAP);
+    assert.deepEqual(await readTestMap(["/wt", "/main"], reader({ [`/main/${TEST_MAP_FILE}`]: JSON.stringify(other) })), other);
+    assert.deepEqual(await readTestMap(["/wt", "/main"], reader({ [`/wt/${TEST_MAP_FILE}`]: "{broken", [`/main/${TEST_MAP_FILE}`]: JSON.stringify(other) })), other);
+    assert.equal(await readTestMap(["/wt", "/main"], reader({})), null);
+    assert.equal(await readTestMap(["/wt"], undefined), null);
+    assert.equal(await readTestMap([null, "/wt"], reader({})), null);
+  });
+
+  it("selectCommands: matching entries in map order, deduped, non-root cwd as cd && cmd", () => {
+    assert.deepEqual(selectCommands(MAP, ["src/a.ts"]), ["pnpm run lint"]);
+    assert.deepEqual(selectCommands(MAP, ["packages/ui/src/b.tsx", "./svc/main.go"]), ["pnpm run lint", "cd packages/ui && pnpm run test", "golangci-lint run ./..."]);
+    assert.deepEqual(selectCommands(MAP, ["a.py"]), ["uv run pytest"], "** matches a root-level file");
+    assert.deepEqual(selectCommands(MAP, ["dir with space/f"]), ["cd 'dir with space' && make x"]);
+    assert.deepEqual(selectCommands(MAP, ["README.md"]), []);
+    assert.deepEqual(selectCommands(MAP, []), []);
+    assert.deepEqual(selectCommands(null, ["a.ts"]), []);
+  });
+
+  it("factsPath: the first existing repo-facts file, else null", async () => {
+    const exists = (set) => async (p) => set.includes(p);
+    assert.equal(await factsPath(["/wt", "/main"], exists([`/main/${REPO_FACTS_FILE}`, `/wt/${REPO_FACTS_FILE}`])), `/wt/${REPO_FACTS_FILE}`);
+    assert.equal(await factsPath(["/wt", "/main"], exists([`/main/${REPO_FACTS_FILE}`])), `/main/${REPO_FACTS_FILE}`);
+    assert.equal(await factsPath(["/wt", "/main"], exists([])), null);
+    assert.equal(await factsPath(["/wt"], undefined), null);
+    assert.equal(await factsPath(["/wt"], async () => { throw new Error("EACCES"); }), null);
+  });
+});

package/bin/lean/verify.mjs

@@ -18,11 +18,16 @@ export const LOG_CAP = 12000;
 /** No run or check for the head after this long means CI is unavailable (local fallback). */
 export const DEFAULT_GRACE_MS = 5 * 60000;
 const LEAN_PREFIX = ".forge-lean/";
+/** The lane's own report-only check run (#4270, `verify.check_run`): never part of ForgeDock's own CI waits. */
+export const VERIFY_CHECK_NAME = "forgedock/verify";
+/** Checks API output.text limit is 65535 characters; stay well under it. */
+export const VERIFY_TEXT_CAP = 60000;
 const OK = ["success", "neutral", "skipped"];
 
 /**
  * forge.yaml `verify:` section (block style; parseForgeYaml gives strings) → {mode, workflow, pathsInput, skipPaths,
- * maxRounds, precheckTimeoutSeconds}. Invalid values fall back to the defaults; mode defaults to local (today's behaviour).
+ * maxRounds, precheckTimeoutSeconds, checkRun}. Invalid values fall back to the defaults; mode defaults to local (today's
+ * behaviour); checkRun (`check_run`, #4270) is true only for the literal `true`.
  */
 export function parseVerify(sec = {}) {
   const s = sec && typeof sec === "object" ? sec : {};
@@ -36,7 +41,8 @@ export function parseVerify(sec = {}) {
   const maxRounds = str(s.max_rounds) !== "" && Number.isInteger(n) && n >= 0 && n <= 10 ? n : DEFAULT_MAX_ROUNDS;
   const t = Number(str(s.precheck_timeout_seconds));
   const precheckTimeoutSeconds = str(s.precheck_timeout_seconds) !== "" && Number.isInteger(t) && t >= 1 && t <= 3600 ? t : DEFAULT_PRECHECK_TIMEOUT_SECONDS;
-  return { mode, workflow, pathsInput, skipPaths, maxRounds, precheckTimeoutSeconds };
+  const checkRun = str(s.check_run).toLowerCase() === "true";
+  return { mode, workflow, pathsInput, skipPaths, maxRounds, precheckTimeoutSeconds, checkRun };
 }
 
 const globRe = (g) => new RegExp(`^${g.split("**").map((p) => p.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")).join(".*")}$`);
@@ -109,7 +115,7 @@ export async function runCiVerify({ io, branch, head, changedFiles, verify, ciMa
       if (!run && now() - startedAt >= graceMs) return unavailable(`no ${v.workflow} run for ${String(head).slice(0, 12)} appeared within ${Math.round(graceMs / 60000)} min`);
     } else {
       let checks = [];
-      try { checks = (await io.commitChecks(head)) ?? []; } catch { checks = []; }
+      try { checks = ((await io.commitChecks(head)) ?? []).filter((c) => c?.name !== VERIFY_CHECK_NAME); } catch { checks = []; }
       if (!checks.length && now() - startedAt >= graceMs) return unavailable(`no checks reported for ${String(head).slice(0, 12)} within ${Math.round(graceMs / 60000)} min`);
       if (checks.length && checks.every((c) => c.state !== "pending")) {
         const failed = checks.filter((c) => c.state === "failure");
@@ -122,3 +128,42 @@ export async function runCiVerify({ io, branch, head, changedFiles, verify, ciMa
     await sleep(ciPollDelayMs(i, random));
   }
 }
+
+const VALIDATE_KINDS = ["validate_missing", "validate_failed"], REQUIREMENT_KINDS = ["requirement_unimplemented", "untracked_deferral"];
+/**
+ * #4270: the `forgedock/verify` check-run payload from the results the lane already computed (no gate logic of its own).
+ * commands: [{command, rc}] of the last declared-check round, or null (none configured); structure: the structure delta or
+ * null; undeclaredEdges: package edges the contract does not name; docs: io.docsFreshness result or null; precheck: the
+ * conformance precheck failures of the last gate() run (null = never ran); amendments: its amendment problems; hotspots:
+ * whether hotspot facts were available. Returns {conclusion, gates: [{id, ok, ran, evidence}], title, summary, text}. A gate
+ * counts only when it ran (#4297): failure if a gate that ran failed, neutral ("no gates ran") when none ran, else success.
+ */
+export function verifyReport({ head = null, commands = null, structure = null, undeclaredEdges = [], docs = null, precheck = null, amendments = [], hotspots = false, contract = null, result = null } = {}) {
+  const NOT_RUN = "not run";
+  const pre = Array.isArray(precheck) ? precheck : [];
+  const details = (kinds) => pre.filter((f) => kinds.includes(f?.kind)).map((f) => String(f.detail ?? f.code ?? ""));
+  const runs = Array.isArray(result?.validation) ? result.validation : [];
+  const reqs = Array.isArray(result?.requirements) ? result.requirements : [];
+  const edges = (xs) => (xs ?? []).map((e) => `${e?.from}→${e?.to}${e?.manifest ? ` (${e.manifest})` : ""}`);
+  const gate = (id, ran, failures, okEvidence) => ({ id, ok: !failures.length, ran: Boolean(ran), evidence: !ran ? NOT_RUN : failures.length ? failures : okEvidence });
+  const gates = [
+    gate("precheck.commands", Array.isArray(commands), (commands ?? []).filter((c) => c.rc !== 0).map((c) => `${c.command} (exit ${c.rc})`),
+      (commands ?? []).map((c) => ({ command: c.command, rc: c.rc }))),
+    gate("structure.edges", Boolean(structure), edges(undeclaredEdges).map((e) => `undeclared ${e}`), { added: edges(structure?.package_edges_added) }),
+    gate("docs.freshness", Boolean(docs), docs && !docs.ok ? [String(docs.output ?? "stale docs").slice(0, 2000)] : [], "ok"),
+    gate("conformance.scope", precheck !== null, details(["scope_creep"]), "every changed file is inside the contract's deliverables"),
+    gate("conformance.validate", precheck !== null, details(VALIDATE_KINDS),
+      (contract?.validate ?? []).map((v) => { const r = runs.find((x) => x?.id === v.id); return { id: v.id, command: v.command, ...(r?.exit !== undefined ? { exit: r.exit } : r?.ci ? { ci: true } : {}) }; })),
+    gate("conformance.requirements", precheck !== null, details(REQUIREMENT_KINDS), reqs.map((r) => ({ id: r?.id, status: r?.status }))),
+    gate("maintenance.hotspot_growth", precheck !== null && Boolean(hotspots), details(["hotspot_growth"]), "no over-threshold file grew past the limit"),
+    gate("conformance.amendments", precheck !== null, (amendments ?? []).map((a) => String(a?.detail ?? a)), "ok"),
+  ];
+  const ran = gates.filter((g) => g.ran), failed = ran.filter((g) => !g.ok);
+  const conclusion = failed.length ? "failure" : ran.length ? "success" : "neutral";
+  const title = failed.length ? `${failed.length} of ${ran.length} deterministic gate(s) failed` : ran.length ? `${ran.length} deterministic gate(s) passed` : "no gates ran";
+  const summary = [`ForgeDock deterministic gates${head ? ` at \`${String(head).slice(0, 12)}\`` : ""}: report only (requiring it is the repository's branch-protection choice).`, "",
+    ...(ran.length ? gates.map((g) => `- ${!g.ran ? "⏭️" : g.ok ? "✅" : "❌"} \`${g.id}\`${g.ran ? "" : " (not run)"}`) : ["no gates ran"])].join("\n");
+  let json = JSON.stringify({ head, conclusion, gates }, null, 2);
+  if (json.length > VERIFY_TEXT_CAP) json = JSON.stringify({ head, conclusion, truncated: true, gates: gates.map((g) => ({ id: g.id, ok: g.ok, ran: g.ran, evidence: JSON.stringify(g.evidence).slice(0, Math.floor(VERIFY_TEXT_CAP / (gates.length + 1))) })) }, null, 2);
+  return { conclusion, gates, title, summary, text: "```json\n" + json + "\n```" };
+}

package/bin/lean/verify.test.mjs

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { parseVerify, matchesGlob, skipsCi, capLogs, runCiVerify, collectFailedLogs, DEFAULT_SKIP_PATHS, LOG_CAP } from "./verify.mjs";
+import { parseVerify, matchesGlob, skipsCi, capLogs, runCiVerify, collectFailedLogs, verifyReport, DEFAULT_SKIP_PATHS, LOG_CAP, VERIFY_CHECK_NAME, VERIFY_TEXT_CAP } from "./verify.mjs";
 import { precheck } from "./conformance.mjs";
 
 const HEAD = "abc123abc123abc123";
@@ -22,9 +22,9 @@ function fake(o = {}) {
 
 describe("verify-by-CI config (#4167)", () => {
   it("parseVerify defaults to local and rejects invalid values", () => {
-    assert.deepEqual(parseVerify({}), { mode: "local", workflow: null, pathsInput: null, skipPaths: [...DEFAULT_SKIP_PATHS], maxRounds: 2, precheckTimeoutSeconds: 300 });
+    assert.deepEqual(parseVerify({}), { mode: "local", workflow: null, pathsInput: null, skipPaths: [...DEFAULT_SKIP_PATHS], maxRounds: 2, precheckTimeoutSeconds: 300, checkRun: false });
     const v = parseVerify({ mode: "ci", workflow: ".github/workflows/verify.yml", paths_input: "changed_paths", skip_paths: "*.md, docs/** ,", max_rounds: "3" });
-    assert.deepEqual(v, { mode: "ci", workflow: ".github/workflows/verify.yml", pathsInput: "changed_paths", skipPaths: ["*.md", "docs/**"], maxRounds: 3, precheckTimeoutSeconds: 300 });
+    assert.deepEqual(v, { mode: "ci", workflow: ".github/workflows/verify.yml", pathsInput: "changed_paths", skipPaths: ["*.md", "docs/**"], maxRounds: 3, precheckTimeoutSeconds: 300, checkRun: false });
     assert.equal(parseVerify({ mode: "remote" }).mode, "local");
     assert.equal(parseVerify({ workflow: "x; rm -rf /" }).workflow, null);
     assert.equal(parseVerify({ max_rounds: "-1" }).maxRounds, 2);
@@ -116,3 +116,81 @@ describe("merge-time fix rounds and declared check commands (#4240)", () => {
     for (const bad of ["0", "-5", "1.5", "abc", "3601"]) assert.equal(parseVerify({ precheck_timeout_seconds: bad }).precheckTimeoutSeconds, 300, bad);
   });
 });
+
+describe("forgedock/verify check run (#4270)", () => {
+  const contract = { requirements: [{ id: "R1", disposition: "deliver" }], deliverables: [{ id: "D1", path: "src/a.ts", change: "x", requirements: ["R1"] }], validate: [{ id: "V1", command: "node --test t.mjs" }, { id: "V2", command: "tsc" }] };
+  const result = { validation: [{ id: "V1", exit: 0 }, { id: "V2", ci: true }], requirements: [{ id: "R1", status: "implemented" }] };
+  const out = (r) => JSON.parse(/```json\n([\s\S]*)\n```/.exec(r.text)[1]);
+
+  it("parseVerify: check_run is true only for the literal true; default false", () => {
+    assert.equal(parseVerify({}).checkRun, false);
+    assert.equal(parseVerify({ check_run: "true" }).checkRun, true);
+    assert.equal(parseVerify({ check_run: true }).checkRun, true);
+    for (const v of ["false", "yes", "1", ""]) assert.equal(parseVerify({ check_run: v }).checkRun, false, v);
+    assert.equal(VERIFY_CHECK_NAME, "forgedock/verify");
+  });
+
+  it("success iff every gate passed; per-gate typed evidence from the computed results", () => {
+    const r = verifyReport({ head: "abc", commands: [{ command: "npm run lint", rc: 0 }], structure: { package_edges_added: [{ from: "@s/a", to: "@s/b", manifest: "packages/a/package.json" }] },
+      docs: { ok: true }, precheck: [], amendments: [], hotspots: true, contract, result });
+    assert.equal(r.conclusion, "success");
+    const g = Object.fromEntries(out(r).gates.map((x) => [x.id, x]));
+    assert.deepEqual(g["precheck.commands"].evidence, [{ command: "npm run lint", rc: 0 }]);
+    assert.deepEqual(g["structure.edges"].evidence, { added: ["@s/a→@s/b (packages/a/package.json)"] });
+    assert.deepEqual(g["conformance.validate"].evidence, [{ id: "V1", command: "node --test t.mjs", exit: 0 }, { id: "V2", command: "tsc", ci: true }]);
+    assert.deepEqual(g["conformance.requirements"].evidence, [{ id: "R1", status: "implemented" }]);
+    assert.ok(Object.values(g).every((x) => x.ok));
+  });
+
+  it("each failing gate is failure with its evidence; gates without input are ok and marked not run", () => {
+    const pre = [
+      { kind: "scope_creep", detail: "changed outside the contract's deliverables: src/x.ts" },
+      { kind: "validate_failed", detail: "validate V1 failed (exit 1)" },
+      { kind: "requirement_unimplemented", detail: "R1 reported \"partial\"" },
+      { kind: "hotspot_growth", detail: "src/big.ts grew by 300 lines" },
+    ];
+    const r = verifyReport({ head: "abc", commands: [{ command: "lint", rc: 2 }], structure: { package_edges_added: [] }, undeclaredEdges: [{ from: "@s/a", to: "@s/b" }],
+      docs: { ok: false, output: "stale devdocs/x.md" }, precheck: pre, amendments: [{ detail: "add-deliverable without why" }], hotspots: true, contract, result });
+    assert.equal(r.conclusion, "failure");
+    const g = Object.fromEntries(r.gates.map((x) => [x.id, x]));
+    assert.ok(r.gates.every((x) => !x.ok), "every gate failed");
+    assert.deepEqual(g["precheck.commands"].evidence, ["lint (exit 2)"]);
+    assert.deepEqual(g["structure.edges"].evidence, ["undeclared @s/a→@s/b"]);
+    assert.match(g["conformance.scope"].evidence[0], /src\/x\.ts/);
+    assert.match(g["maintenance.hotspot_growth"].evidence[0], /src\/big\.ts/);
+    assert.match(r.title, /8 of 8/);
+
+    const none = verifyReport({});
+    assert.ok(none.gates.every((x) => x.ok && !x.ran && x.evidence === "not run"));
+  });
+
+  it("verifyReport with no gate results is neutral with \"no gates ran\" (#4297)", () => {
+    for (const r of [verifyReport({}), verifyReport({ head: "abc" })]) {
+      assert.equal(r.conclusion, "neutral");
+      assert.equal(r.title, "no gates ran");
+      assert.match(r.summary, /no gates ran/);
+      assert.doesNotMatch(`${r.title}\n${r.summary}`, /passed|✅/);
+    }
+    // Only gates that ran are counted: one command round, nothing else.
+    const one = verifyReport({ head: "abc", commands: [{ command: "lint", rc: 0 }] });
+    assert.equal(one.conclusion, "success");
+    assert.equal(one.title, "1 deterministic gate(s) passed");
+    assert.match(one.summary, /`structure\.edges` \(not run\)/);
+    const bad = verifyReport({ head: "abc", commands: [{ command: "lint", rc: 1 }] });
+    assert.equal(bad.conclusion, "failure"); assert.equal(bad.title, "1 of 1 deterministic gate(s) failed");
+  });
+
+  it("the output text stays under the Checks API limit", () => {
+    const r = verifyReport({ precheck: Array.from({ length: 2000 }, (_, i) => ({ kind: "scope_creep", detail: `changed outside: src/${"x".repeat(80)}${i}.ts` })), contract, result });
+    assert.ok(r.text.length < 65535); assert.ok(r.text.length <= VERIFY_TEXT_CAP + 100);
+    assert.equal(r.conclusion, "failure"); assert.equal(out(r).truncated, true);
+  });
+
+  it("runCiVerify never waits on the lane's own forgedock/verify check run", async () => {
+    const f = fake({ checks: [[{ name: "ci", state: "success" }, { name: VERIFY_CHECK_NAME, state: "failure" }]] });
+    const r = await runCiVerify(f.args({ verify: parseVerify({ mode: "ci" }) }));
+    assert.equal(r.result, "pass");
+    const g = fake({ checks: [[{ name: VERIFY_CHECK_NAME, state: "success" }], [{ name: "ci", state: "success" }]] });
+    assert.equal((await runCiVerify(g.args({ verify: parseVerify({ mode: "ci" }) }))).detail, "1 check(s) green", "its own check alone is not CI");
+  });
+});

package/bin/stats/index.mjs

@@ -13,7 +13,7 @@ import { aggregate, DEFAULT_MIN_N } from "./aggregate.mjs";
 import { fetchGithubRecords, isValidRepo, toModel } from "./github-source.mjs";
 import { readLocalRuns, runsDir } from "./local-source.mjs";
 import { renderCompact, renderJson, renderMarkdown } from "./render.mjs";
-import { edgeQuery, parseEdge, verdictMix } from "./query.mjs";
+import { edgeQuery, parseEdge, verdictMix, contextPackAb, renderContextAb } from "./query.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -39,10 +39,14 @@ delta against the previous version and a low-n flag for samples under 10. Missin
 Audit queries (forge#4165; JSON, from structure_delta / run_terminal telemetry, no comment bodies read):
   --edge FROM:TO        merged PRs that added the dependency or import edge FROM -> TO (e.g. @s/web:@s/db)
   --milestone M         conformance verdict mix and per-day structure series for milestone M
+
+Context-pack A/B (forge#4275; local run logs only, no GitHub crawl):
+  --context-ab          first-pass yield, builder turns, cache tokens and cost per lane type (rerun, child,
+                        first) and context_pack mode (on, off, shadow); --json for JSON
 `;
 
 export function parseArgs(argv) {
-  const o = { since: null, repo: null, edge: null, milestone: null, json: false, refresh: false, compact: false, local: true, cache: true, minN: DEFAULT_MIN_N, releaseTimes: null, help: false };
+  const o = { since: null, repo: null, edge: null, milestone: null, contextAb: false, json: false, refresh: false, compact: false, local: true, cache: true, minN: DEFAULT_MIN_N, releaseTimes: null, help: false };
   const val = (i, name) => {
     const v = argv[i + 1];
     if (v == null || v.startsWith("--")) throw new Error(`${name} needs a value`);
@@ -58,6 +62,7 @@ export function parseArgs(argv) {
     else if (name === "--release-times") o.releaseTimes = take();
     else if (name === "--edge") { const v = take(); if (!parseEdge(v)) throw new Error("--edge must be FROM:TO"); o.edge = v; }
     else if (name === "--milestone") o.milestone = take();
+    else if (name === "--context-ab") o.contextAb = true;
     else if (name === "--min-n") { const v = take(); if (!/^\d+$/.test(v)) throw new Error("--min-n must be a non-negative integer"); o.minN = Number(v); }
     else if (name === "--json") o.json = true;
     else if (name === "--refresh") o.refresh = true;
@@ -156,6 +161,10 @@ export async function buildReport(opts, deps = {}) {
   if (opts.releaseTimes) releaseTimes = parseReleaseTimes(readFileSync(opts.releaseTimes, "utf8"));
   else if (deps.releaseTimes) releaseTimes = deps.releaseTimes;
   else releaseTimes = gitTagTimes();
+  if (opts.contextAb) { // forge#4275: run logs only
+    const runs = (deps.localRuns ?? readLocalRuns(runsDir(env))).filter((r) => r.repo == null || r.repo === repo);
+    return { repo, sources: { local: { runs: runs.length } }, query: { context_ab: contextPackAb(runs) } };
+  }
   const bound = sinceToTimestamp(opts.since, releaseTimes);
   if (bound.note) (deps.warn ?? ((m) => process.stderr.write(`forgedock stats: ${m}\n`)))(bound.note);
   const gh = await fetchGithubRecords({ repo, since: bound.since, refresh: opts.refresh, useCache: opts.cache, gh: deps.gh, env,
@@ -190,6 +199,7 @@ export async function runStats(argv, deps = {}) {
   }
   try {
     const report = await buildReport(opts, { onProgress: makeProgressPrinter(), ...deps });
+    if (report.query?.context_ab && !opts.json) { process.stdout.write(`${renderContextAb(report.query.context_ab)}\n`); return 0; }
     process.stdout.write(`${opts.json || report.query ? renderJson(report) : opts.compact ? renderCompact(report) : renderMarkdown(report)}\n`);
     return 0;
   } catch (err) {

package/bin/stats/local-source.mjs

@@ -50,6 +50,13 @@ export function summariseLog(events, fallbackIssue = null) {
     if (attempt && Number.isFinite(e.cost_usd)) p.usd = (p.usd ?? 0) + e.cost_usd;
   }
   const finished = t >= 0 && (r < 0 || t > r);
+  // forge#4275: the context-pack A/B inputs. Builder calls log as phase "implement" (the plan call is the first).
+  const term = finished ? ev[t] : null;
+  const cp = [...ev].reverse().find((e) => e.event === "CONTEXT_PACK");
+  const usage = ev.filter((e) => e.event === "PHASE_ATTEMPT_USAGE");
+  const builderCalls = usage.filter((e) => e.phase === "implement");
+  const reviewCalls = usage.filter((e) => e.phase === "review").length;
+  const contextPack = { mode: term?.context_pack ?? cp?.mode ?? "off", laneType: term?.lane_type ?? cp?.lane_type ?? null };
   const startTs = start.ts ?? null;
   const endTs = finished ? ev[t].ts ?? null : null;
   const a = Date.parse(startTs ?? ""); const b = Date.parse(endTs ?? "");
@@ -60,6 +67,12 @@ export function summariseLog(events, fallbackIssue = null) {
     remediated: ev.some((e) => e.event === "PHASE_COMMIT" && e.phase === "remediate"),
     startTs, endTs, wallMs: finished && !Number.isNaN(a) && !Number.isNaN(b) ? Math.max(0, b - a) : null,
     phases,
+    contextPack,
+    builderTurns: builderCalls.reduce((x, e) => x + n(e.turns), 0),
+    cacheTokens: usage.reduce((x, e) => x + n(e.usage?.cache_read_input_tokens) + n(e.usage?.cache_creation_input_tokens), 0),
+    costUsd: usage.reduce((x, e) => x + n(e.cost_usd), 0),
+    // first pass: merged off one plan + one implement call, at most one review, no CI fix round
+    firstPass: finished && term?.reason === "merged" && builderCalls.length <= 2 && reviewCalls <= 1 && !ev.some((e) => e.event === "CI_FIX_ROUND"),
   };
 }
 

package/bin/stats/query.mjs

@@ -70,3 +70,30 @@ export function verdictMix(records, items = [], milestone = null) {
     series: [...series.values()].sort((a, b) => a.date.localeCompare(b.date)),
   };
 }
+
+/**
+ * forge#4275: the context-pack A/B over local run summaries (local-source.mjs summariseLog), per lane type (rerun,
+ * child, first) and mode (on, off, shadow), never one blended average. First-pass yield: merged with one plan + one
+ * implement builder call and at most one review. Runs without a recorded lane type (older logs) are left out.
+ */
+export const CONTEXT_LANE_TYPES = Object.freeze(["rerun", "child", "first"]);
+export function contextPackAb(runs) {
+  const out = {};
+  const mean = (xs) => (xs.length ? Math.round((xs.reduce((a, b) => a + b, 0) / xs.length) * 1e4) / 1e4 : null);
+  for (const lt of CONTEXT_LANE_TYPES) {
+    out[lt] = {};
+    for (const mode of ["on", "off", "shadow"]) {
+      const rs = runs.filter((r) => r?.finished && r.contextPack?.laneType === lt && r.contextPack?.mode === mode);
+      out[lt][mode] = { n: rs.length, first_pass_yield: mean(rs.map((r) => (r.firstPass ? 1 : 0))), builder_turns: mean(rs.map((r) => r.builderTurns ?? 0)),
+        cache_tokens: mean(rs.map((r) => r.cacheTokens ?? 0)), cost_usd: mean(rs.map((r) => r.costUsd ?? 0)) };
+    }
+  }
+  return out;
+}
+
+/** Markdown table for contextPackAb. */
+export function renderContextAb(ab) {
+  const f = (v) => (v == null ? "n/a" : String(v));
+  const rows = CONTEXT_LANE_TYPES.flatMap((lt) => ["on", "off", "shadow"].map((m) => { const g = ab[lt][m]; return `| ${lt} | ${m} | ${g.n} | ${f(g.first_pass_yield)} | ${f(g.builder_turns)} | ${f(g.cache_tokens)} | ${f(g.cost_usd)} |`; }));
+  return `| Lane type | Mode | n | First-pass yield | Builder turns | Cache tokens | Cost USD |\n| --- | --- | --- | --- | --- | --- | --- |\n${rows.join("\n")}`;
+}

package/bin/stats/stats.test.mjs

@@ -12,9 +12,9 @@ import { aggregate, compareVersions, percentile } from "./aggregate.mjs";
 import { cacheDir } from "./cache.mjs";
 import { fetchGithubRecords, parseTelemetryComments, runsFromRecords, toModel } from "./github-source.mjs";
 import { buildReport, makeProgressPrinter, parseArgs, parseSince, runStats, sinceToTimestamp } from "./index.mjs";
-import { readLocalRuns } from "./local-source.mjs";
+import { readLocalRuns, summariseLog } from "./local-source.mjs";
 import { renderCompact, renderJson, renderMarkdown } from "./render.mjs";
-import { edgeQuery, parseEdge, verdictMix } from "./query.mjs";
+import { edgeQuery, parseEdge, verdictMix, contextPackAb, renderContextAb } from "./query.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const fx = (f) => join(here, "fixtures", f);
@@ -525,3 +525,42 @@ describe("audit queries (forge#4165)", () => {
     assert.deepEqual([parseArgs([]).edge, parseArgs([]).milestone], [null, null]);
   });
 });
+
+describe("context-pack A/B over run logs (forge#4275)", () => {
+  const use = (phase, turns, cr, usd) => ({ event: "PHASE_ATTEMPT_USAGE", phase, turns, cost_usd: usd, usage: { cache_read_input_tokens: cr, cache_creation_input_tokens: 10, output_tokens: 1 } });
+  const log = (mode, lt, { reason = "merged", builds = 2, reviews = 1 } = {}) => [
+    { event: "RUN_START", issue: 1, repo: "o/r", run: "r" },
+    ...(mode !== "off" ? [{ event: "CONTEXT_PACK", mode, lane_type: lt, bytes: 100 }] : []),
+    ...Array.from({ length: builds }, () => use("implement", 5, 1000, 0.5)),
+    ...Array.from({ length: reviews }, () => use("review", 2, 100, 0.1)),
+    { event: "RUN_TERMINAL", reason, code: "x", context_pack: mode, lane_type: lt },
+  ];
+
+  it("summariseLog carries mode, lane type, builder turns, cache tokens, cost and first-pass", () => {
+    const s = summariseLog(log("on", "child"));
+    assert.deepEqual(s.contextPack, { mode: "on", laneType: "child" });
+    assert.deepEqual([s.builderTurns, s.cacheTokens, s.costUsd, s.firstPass], [10, 2130, 1.1, true]);
+    assert.equal(summariseLog(log("on", "child", { builds: 4 })).firstPass, false);
+    assert.equal(summariseLog(log("on", "child", { reason: "needs-human" })).firstPass, false);
+    const fixed = log("on", "child"); fixed.splice(-1, 0, { event: "CI_FIX_ROUND", trigger: "build", round: 1 });
+    assert.equal(summariseLog(fixed).firstPass, false);
+    assert.equal(summariseLog([{ event: "RUN_START", issue: 3 }, { event: "RUN_TERMINAL", reason: "merged" }]).contextPack.mode, "off");
+  });
+
+  it("reports per lane type and mode, never one blended average", () => {
+    const runs = [log("on", "first"), log("on", "first", { builds: 4, reviews: 2 }), log("off", "first"), log("shadow", "rerun"),
+      [{ event: "RUN_START", issue: 2 }, { event: "RUN_TERMINAL", reason: "merged" }]].map((l) => summariseLog(l));
+    const ab = contextPackAb(runs);
+    assert.deepEqual(Object.keys(ab), ["rerun", "child", "first"]);
+    assert.deepEqual(ab.first.on, { n: 2, first_pass_yield: 0.5, builder_turns: 15, cache_tokens: 3195, cost_usd: 1.65 });
+    assert.equal(ab.first.off.n, 1); assert.equal(ab.first.off.first_pass_yield, 1);
+    assert.equal(ab.rerun.shadow.n, 1); assert.equal(ab.child.on.n, 0); assert.equal(ab.child.on.cost_usd, null);
+    assert.match(renderContextAb(ab), /\| first \| on \| 2 \| 0\.5 \| 15 \| 3195 \| 1\.65 \|/);
+  });
+
+  it("--context-ab reads run logs only (no GitHub crawl)", async () => {
+    assert.equal(parseArgs(["--context-ab"]).contextAb, true);
+    const rep = await buildReport({ repo: "o/r", contextAb: true }, { localRuns: [summariseLog(log("on", "first"))], releaseTimes: [], gh: async () => { throw new Error("no network"); } });
+    assert.equal(rep.query.context_ab.first.on.n, 1);
+  });
+});

package/commands/orchestrate.md

@@ -96,7 +96,9 @@ remaining maintenance once no feature is pending; otherwise the rest ends `held
 
   Its first line is `batch: <id> (...)`. The batch state lives in `~/.forge/batches/<id>/` and every lane runs in its
   own session, so the batch survives this session: if the runner dies, run `forgedock orchestrate --resume <id>`
-  (live lanes are re-adopted, nothing is launched twice). Change K of a running batch with
+  (live lanes are re-adopted, nothing is launched twice). The runner is hosted by the detached `forgedock schedd` daemon,
+  which resumes every daemon-hosted batch that has no report yet when it starts, so a closed session needs no manual
+  `--resume`; a batch started without the daemon still needs `forgedock orchestrate --resume <id>`. Change K of a running batch with
   `forgedock orchestrate --set-parallel <id> K`. The runner requeues `deferred` lanes by code (host busy after its
   retry-in, a usage limit holds admissions for that account (backend identity) until the reset, across every batch on
   the host; `forgedock limits show|clear <id>|--all` lists or drops holds; transient merge/push/idle failures back off; non-host
@@ -137,14 +139,58 @@ When a lane finishes (agent lanes; the batch runner applies the same rules itsel
   `**Parent**` and `**Depends on**` lines). Add them to the DAG, launch them, and let the parent's dependents
   wait on the sub-issues.
 - `merged` or `invalid`: start the next ready issue.
-- `needs-human`: an external action agents cannot take (credentials, spend, promotion, customer) or a product
-  decision too critical for agents. Read the issue's last comment for the reason, and mark its dependents skipped. Only
+- `needs-human` with a **recoverable code**: `ci.red`, `base.conflict` (merge conflict), `ci-pending` on a conflicting
+  PR, `contract.invalid` caused by an issue edited mid-run, and `builder.block_untyped` (an in-scope technical choice).
+  These are mechanical. **Do not ask for confirmation on them.** The batch runner recovers each one itself
+  (`orchestration.recovery.max_attempts`, default 1 per issue). It launches one recovery lane under the same lease, lane
+  and admission rules as any lane, with `run-issue --recover <code> [--recover-attempt n]` (core path only:
+  `--path full` rejects `--recover`). That lane:
+  - removes `needs-human`;
+  - resumes the open PR: merges the base, fixes the failed required checks from their logs, and pushes new commits only;
+  - re-queues the issue, keeping its dependents queued in the same batch.
+
+  Report what was recovered afterwards. A failed recovery stays `needs-human` with its evidence, exactly once (failed = `needs-human`, `ci-pending`, or a final `engine-error`/`deferred`; `invalid`, `decomposed` and `dependency-*` are not failures and never re-label), and there
+  is no second attempt beyond `max_attempts`.
+- `needs-human` with a **human code** (`builder.blocked`: product-decision, spend, credentials, promotion, customer): an
+  external action agents cannot take, or a product decision too critical for agents. It is never auto-recovered. Read
+  the issue's last comment for the reason, mark its dependents skipped, and add it to the escalation list (step 4). Only
   explicit or logical edges skip a dependent; an issue that merely overlaps the same file keeps running.
+- `needs-human` with a **terminal code** that is neither recoverable nor human (for example a `conformance.*` code, or
+  `contract.invalid` without a mid-run issue edit): the runner does not recover it and it is not an escalation. The
+  batch report lists it as `unrecovered: #N (<code>: <detail>)`, like a recovery that did not merge. Mark its dependents
+  skipped and leave the issue for a later run once its cause is fixed.
 - `engine-error`: relaunch it once.
-- `ci-pending` or `deferred`: leave it. A later `/orchestrate` resumes it.
+- `ci-pending` (PR not conflicting) or `deferred`: leave it. A later `/orchestrate` resumes it.
+
+**Operational decisions are yours.** Decide them without asking and keep going. Record each one as a
+`<!-- FORGE:DECISION -->` comment (what, why, alternative) on the issue, or on the batch for batch-wide choices. The
+runner posts its own decisions (recovery, relaunch, dependency requeue, sub-issues added). The decisions you take
+yourself:
+- **Recovery and retries:** relaunch, resume, fix-ci, base-sync, and stopping and relaunching a stuck lane.
+- **Scheduling:** K changes under host pressure, ordering, adding logical `Depends on` edges, and adding newly filed or
+  decomposed sub-issues to the running batch.
+- **Engine gaps:** file each engine-gap issue you discover and queue it.
+- **In-scope technical choices** a builder escalates as `untyped` or ambiguous: pick the option most consistent with the
+  issue, the repo's conventions and prior merged decisions, and note the alternative.
+
+Escalate only these:
+- product direction (`product-decision`);
+- spend;
+- credentials;
+- customer-facing actions;
+- staging→main release or deploy, unless the operator approved it for the session.
+
+Collect escalations into one question list and ask it once, at the end of the batch. Never ask per issue, and keep every
+other lane running meanwhile.
 
 ## 4. Report
 
 When all lanes have finished, print one table: issue, outcome, PR, minutes (issues the pre-filter closed
-show `invalid (pre-filter)`). Then the `pre-filter:` line from step 2.2 (count closed and spend avoided), then
-list each `needs-human` or skipped issue with its one-line reason. Nothing else.
+show `invalid (pre-filter)`). Then print:
+1. the `pre-filter:` line from step 2.2 (count closed and spend avoided);
+2. the runner's `recovered: #A (ci.red) #B (base.conflict)` line;
+3. its `unrecovered:` lines (mechanical codes whose recovery did not merge);
+4. each skipped issue with its one-line reason;
+5. one escalation list: the human-code `needs-human` issues only, asked once.
+
+Nothing else.