forgedock 1.18.0 → 1.19.0

package/bin/stats/stats.test.mjs

@@ -1,8 +1,9 @@
 // SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import { tmpDir } from "../tests/_tmp.mjs";
 import { describe, it, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -10,7 +11,7 @@ import { spawnSync } from "node:child_process";
 import { aggregate, compareVersions, percentile } from "./aggregate.mjs";
 import { cacheDir } from "./cache.mjs";
 import { fetchGithubRecords, parseTelemetryComments, runsFromRecords, toModel } from "./github-source.mjs";
-import { buildReport, parseArgs, parseSince, runStats } from "./index.mjs";
+import { buildReport, makeProgressPrinter, parseArgs, parseSince, runStats, sinceToTimestamp } from "./index.mjs";
 import { readLocalRuns } from "./local-source.mjs";
 import { renderCompact, renderJson, renderMarkdown } from "./render.mjs";
 
@@ -29,6 +30,10 @@ function fakeGh() {
     const path = args.find((a) => a.startsWith("repos/"));
     const m = /issues\/(\d+)\/comments$/.exec(path);
     if (m) return JSON.stringify(comments[m[1]] ?? []);
+    if (/issues\/comments\?/.test(path)) { // repo-wide endpoint: every comment, tagged with its issue (fixtures carry no updated_at)
+      const all = Object.entries(comments).flatMap(([n, list]) => list.map((c) => ({ ...c, issue_url: `https://api.github.com/repos/o/r/issues/${n}` })));
+      return JSON.stringify(/page=1(&|$)/.test(path) ? all : []);
+    }
     const since = /since=([^&]+)/.exec(path)?.[1];
     return JSON.stringify(issues.filter((i) => !since || i.updated_at >= since));
   };
@@ -36,7 +41,7 @@ function fakeGh() {
 }
 
 let td;
-beforeEach(() => { td = mkdtempSync(join(tmpdir(), "stats-")); });
+beforeEach(() => { td = tmpDir("stats-"); });
 afterEach(() => rmSync(td, { recursive: true, force: true }));
 
 describe("telemetry comment parsing", () => {
@@ -58,9 +63,9 @@ describe("telemetry comment parsing", () => {
 });
 
 describe("GitHub-only report (fresh machine)", () => {
-  it("rebuilds cost, time, flow, funnel, gates and issue flow from GitHub alone", () => {
+  it("rebuilds cost, time, flow, funnel, gates and issue flow from GitHub alone", async () => {
     const { gh } = fakeGh();
-    const report = buildReport({ repo: "o/r", local: false, cache: false, minN: 10 }, { gh, env: ENV, releaseTimes: [] });
+    const report = await buildReport({ repo: "o/r", local: false, cache: false, minN: 10 }, { gh, env: ENV, releaseTimes: [] });
     const g = report.groups.find((x) => x.version === "1.17.0");
     assert.equal(g.n, 1);
     assert.equal(g.cost.cacheReadMean, 3000000);
@@ -85,6 +90,8 @@ describe("GitHub-only report (fresh machine)", () => {
     assert.equal(u.funnel.falsePositive, 1);
     assert.equal(u.issueFlow.net, 2);
     assert.equal(u.issueFlow.findingsPerMerge, null);
+    assert.equal(g.funnel.introduced, 2, "only events carrying scope=introduced are counted");
+    assert.equal(g.issueFlow.introducedPerMerge, (g.issueFlow.closed.merged ?? 0) > 0 ? 2 / g.issueFlow.closed.merged : null);
     assert.ok(!JSON.stringify(report).includes("999999999"), "untrusted record leaked into the report");
   });
   it("matches the run-record field names written by the engine seam", () => {
@@ -138,6 +145,15 @@ describe("local runs, joins, version delta and low-n", () => {
     assert.equal(legacy.cost.cacheReadMean, 4000000, "legacy PHASE_COMMIT usage counted when no attempt events exist");
     assert.equal(legacy.flow.codesN, 0, "old logs have no outcome codes");
   });
+  it("reports introduced findings per merged issue", () => {
+    const ev = (eid, scope) => ({ event: "finding_disposition", eid, repo: "o/r", pr: 1, issue: eid === "d" ? 2 : 1, version: "1.18.0", severity: "MEDIUM", disposition: "INPR_FIX", ...(scope ? { scope } : {}) });
+    const issue = (number) => ({ number, repo: "o/r", isPr: false, labels: ["workflow:merged"], createdAt: "2026-10-06T00:00:00Z", closedAt: "2026-10-07T00:00:00Z" });
+    const r = aggregate({ events: [ev("a", "introduced"), ev("b", "introduced"), ev("c", "pre-existing"), ev("d")], issues: [issue(1), issue(2)] }, { releaseTimes: [] });
+    const g = r.groups.find((x) => x.version === "1.18.0");
+    assert.equal(g.funnel.introduced, 2);
+    assert.equal(g.issueFlow.introducedPerMerge, 1);
+    assert.match(renderMarkdown(r), /introduced findings per merged issue/);
+  });
   it("computes the delta against the previous version of the same repo", () => {
     const g = agg().groups.find((x) => x.version === "1.17.0");
     assert.equal(g.delta.against, "1.16.0");
@@ -178,9 +194,9 @@ describe("n/a degradation and rendering", () => {
     assert.match(renderMarkdown(aggregate({})), /No data/);
     assert.equal(percentile([], 90), null);
   });
-  it("json output is parseable and carries every section", () => {
+  it("json output is parseable and carries every section", async () => {
     const { gh } = fakeGh();
-    const report = buildReport({ repo: "o/r", local: false, cache: false, minN: 10 }, { gh, env: ENV, releaseTimes: [] });
+    const report = await buildReport({ repo: "o/r", local: false, cache: false, minN: 10 }, { gh, env: ENV, releaseTimes: [] });
     const parsed = JSON.parse(renderJson(report));
     for (const k of ["cost", "time", "flow", "funnel", "gates", "issueFlow"]) assert.ok(k in parsed.groups[0]);
     const md = renderMarkdown(report);
@@ -193,56 +209,173 @@ describe("n/a degradation and rendering", () => {
 });
 
 describe("cache", () => {
-  it("refreshes incrementally from the updated_at watermark and survives deletion or corruption", () => {
+  it("refreshes incrementally from the updated_at watermark and survives deletion or corruption", async () => {
     const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache") };
     const a = fakeGh();
-    const first = fetchGithubRecords({ repo: "o/r", gh: a.gh, env });
+    const first = await fetchGithubRecords({ repo: "o/r", gh: a.gh, env });
     assert.equal(first.fromCache, false);
     assert.ok(!a.calls[0].includes("since="));
     const b = fakeGh();
-    const second = fetchGithubRecords({ repo: "o/r", gh: b.gh, env });
+    const second = await fetchGithubRecords({ repo: "o/r", gh: b.gh, env });
     assert.equal(second.fromCache, true);
     assert.match(b.calls[0], /since=2026-10-06T12:55:00Z/); // watermark minus the 5 minute overlap window
     assert.deepEqual(second.records.map((r) => r.eid).sort(), first.records.map((r) => r.eid).sort());
     // corrupt cache -> treated as empty -> same result from a full fetch
     writeFileSync(join(cacheDir("o/r", env), "cache.json"), "{not json");
     const c = fakeGh();
-    const third = fetchGithubRecords({ repo: "o/r", gh: c.gh, env });
+    const third = await fetchGithubRecords({ repo: "o/r", gh: c.gh, env });
     assert.equal(third.fromCache, false);
     assert.equal(third.records.length, first.records.length);
     // --refresh ignores a good cache
     const d = fakeGh();
-    fetchGithubRecords({ repo: "o/r", gh: d.gh, env, refresh: true });
+    await fetchGithubRecords({ repo: "o/r", gh: d.gh, env, refresh: true });
     assert.ok(!d.calls[0].includes("since="));
     assert.equal(toModel("o/r", third).issues.length, 5);
   });
-  it("saves a partial checkpoint on a mid-crawl failure and the next run resumes from it", () => {
-    const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-partial") };
-    const ok = fakeGh();
-    const full = fetchGithubRecords({ repo: "o/r", gh: ok.gh, env: { ...ENV }, useCache: false });
-    const withComments = full.items.filter((i) => ok.calls.some((c) => c.includes(`/issues/${i.number}/comments`)));
-    assert.ok(withComments.length >= 2, "fixture needs at least two items with comments");
-    let commentCalls = 0;
-    // The real API honours sort=updated&direction=asc, which the watermark resume relies on; the fixture is unsorted.
-    const asc = (gh) => (args) => {
-      const out = gh(args);
-      return args.some((a) => /\/issues\?/.test(a)) ? JSON.stringify(JSON.parse(out).sort((x, y) => x.updated_at.localeCompare(y.updated_at))) : out;
+  // Page-aware fake of the issues API over a synthetic store; the repo-wide comments endpoint is empty unless `comments` is given.
+  const storeGh = (store, { comments = [], failOnListCall = 0 } = {}) => {
+    const calls = [];
+    let listCalls = 0;
+    const gh = (args) => {
+      const path = args.find((a) => a.startsWith("repos/"));
+      calls.push(path);
+      const q = new URLSearchParams(path.split("?")[1] ?? "");
+      if (/issues\/comments\?/.test(path)) {
+        const since = q.get("since"), page = Number(q.get("page") ?? 1);
+        return JSON.stringify(comments.filter((c) => !since || c.updated_at >= since).slice((page - 1) * 100, page * 100));
+      }
+      const m = /issues\/(\d+)\/comments$/.exec(path);
+      if (m) return JSON.stringify(comments.filter((c) => c.issue_url.endsWith(`/issues/${m[1]}`)));
+      const one = /issues\/(\d+)$/.exec(path);
+      if (one) return JSON.stringify(store.find((i) => i.number === Number(one[1])));
+      if (++listCalls === failOnListCall) throw new Error("rate limited");
+      const since = q.get("since");
+      const sorted = store.filter((i) => !since || i.updated_at >= since).sort((x, y) => x.updated_at.localeCompare(y.updated_at) || x.number - y.number);
+      const per = Number(q.get("per_page")), page = Number(q.get("page") ?? 1);
+      return JSON.stringify(sorted.slice((page - 1) * per, page * per));
     };
-    const flaky = asc((args) => {
-      if (args[args.length - 1].endsWith("/comments") && ++commentCalls === 2) throw new Error("rate limited");
-      return ok.gh(args);
-    });
-    assert.throws(() => fetchGithubRecords({ repo: "o/r", gh: flaky, env }), /rate limited/);
+    return { gh, calls };
+  };
+  const ts = (n) => new Date(Date.UTC(2026, 9, 1) + n * 3600000).toISOString().replace(/\.\d{3}Z$/, "Z");
+  const mkItems = (n) => Array.from({ length: n }, (_, i) => ({ number: i + 1, updated_at: ts(i + 1), created_at: ts(0), state: "open", comments: 0, labels: [], user: { type: "Bot" } }));
+  const telemetryComment = (issue, eid, event, updated, extra = {}) => ({ id: issue * 1000 + Number(eid.replace(/\D/g, "")), updated_at: updated, user: { type: "Bot" },
+    issue_url: `https://api.github.com/repos/o/r/issues/${issue}`,
+    body: `<!-- FORGE:TELEMETRY v1 -->\n\`\`\`jsonl\n${JSON.stringify({ v: 1, ts: updated, forge_version: "1.18.0", repo: "o/r", issue, run: `r_${issue}`, eid, event, phase: "build", cache_read_tokens: 100, ...extra })}\n\`\`\`` });
+
+  it("saves a partial checkpoint on a mid-crawl failure and the next run resumes from it", async () => {
+    const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-partial") };
+    const store = mkItems(250);
+    await assert.rejects(() => fetchGithubRecords({ repo: "o/r", gh: storeGh(store, { failOnListCall: 3 }).gh, env }), /rate limited/);
     const saved = JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8"));
     assert.ok(saved.watermark, "partial watermark persisted");
-    assert.ok(Object.keys(saved.items).length > 0 && Object.keys(saved.items).length < full.items.length);
-    const b = fakeGh();
-    const resumed = fetchGithubRecords({ repo: "o/r", gh: asc(b.gh), env });
+    assert.ok(Object.keys(saved.items).length >= 100 && Object.keys(saved.items).length < 250);
+    const b = storeGh(store);
+    const resumed = await fetchGithubRecords({ repo: "o/r", gh: b.gh, env });
     assert.equal(resumed.fromCache, true);
-    assert.match(b.calls[0], /since=/);
-    assert.deepEqual(resumed.records.map((r) => r.eid).sort(), full.records.map((r) => r.eid).sort());
+    assert.ok(b.calls[0].includes("since="), "resumes from the watermark");
+    assert.equal(resumed.items.length, 250);
   });
-  it("never skips an item updated mid-crawl (keyset crawl, not page-number pagination)", () => {
+  it("a mid-crawl failure never advances the watermark past unpersisted telemetry (resume still finds it)", async () => {
+    const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-pending-telemetry") };
+    const store = mkItems(250);
+    // A telemetry comment on the NEWEST issue (listed last), posted before the failing run starts.
+    const comments = [telemetryComment(250, "z1", "phase_attempt", ts(250))];
+    await assert.rejects(() => fetchGithubRecords({ repo: "o/r", gh: storeGh(store, { comments, failOnListCall: 3 }).gh, env }), /rate limited/);
+    const saved = JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8"));
+    assert.ok(!saved.watermark, "watermark must not be persisted while telemetry records are unpersisted");
+    // Resume: the comment is older than any watermark a buggy checkpoint would have saved.
+    const resumed = await fetchGithubRecords({ repo: "o/r", gh: storeGh(store, { comments }).gh, env });
+    assert.equal(resumed.items.length, 250);
+    assert.deepEqual(resumed.records.map((r) => r.eid), ["z1"]);
+    assert.equal(resumed.items.find((i) => i.number === 250).records.length, 1);
+  });
+  it("bounds the crawl by the window: API calls track the window, not the repo size", async () => {
+    const store = mkItems(3000); // 3000 items, one per hour
+    const from = ts(2990);
+    const windowItems = store.filter((i) => i.updated_at >= from).length;
+    const comments = store.slice(-5).map((i) => telemetryComment(i.number, `x${i.number}`, "phase_attempt", i.updated_at));
+    const { gh, calls } = storeGh(store, { comments });
+    const r = await fetchGithubRecords({ repo: "o/r", gh, useCache: false, since: from, env: ENV });
+    assert.equal(r.items.length, windowItems);
+    // 1 comments page + one refetch per telemetry issue + ceil(window / 100) list pages; never one call per repo item.
+    const bound = 1 + comments.length + Math.ceil(windowItems / 100) + 1;
+    assert.ok(r.apiCalls <= bound, `api calls ${r.apiCalls} exceed window bound ${bound}`);
+    assert.equal(calls.length, r.apiCalls);
+    assert.ok(calls.length < 30 && store.length > 100 * calls.length, `calls.length ${calls.length} must be far below the repo size`);
+    assert.ok(calls.some((c) => /issues\/comments\?.*since=/.test(c)), "comments come from the repo-wide since= endpoint");
+    assert.ok(!calls.some((c) => /issues\/\d+\/comments$/.test(c) && !comments.some((x) => x.issue_url.endsWith(c.match(/issues\/(\d+)\//)[1]))), "no comment call for items without telemetry");
+    assert.equal(r.records.length, comments.length);
+  });
+  it("re-reads every part of an issue whose telemetry was touched in the window, and only those", async () => {
+    const store = mkItems(20);
+    const comments = [telemetryComment(7, "e1", "phase_attempt", ts(1)), telemetryComment(7, "e2", "run_terminal", ts(15), { reason: "merged" }),
+      telemetryComment(9, "e1", "phase_attempt", ts(2))];
+    const { gh, calls } = storeGh(store, { comments });
+    const r = await fetchGithubRecords({ repo: "o/r", gh, useCache: false, since: ts(10), env: ENV });
+    assert.deepEqual(r.records.filter((x) => x.issue === 7).map((x) => x.event).sort(), ["phase_attempt", "run_terminal"], "the pre-window part is fetched too");
+    assert.equal(calls.filter((c) => /issues\/7\/comments$/.test(c)).length, 1);
+    assert.equal(calls.filter((c) => /issues\/9\/comments$/.test(c)).length, 0, "issue 9 has no telemetry in the window");
+  });
+  it("accepts an async gh and awaits it", async () => {
+    const store = mkItems(5);
+    const { gh } = storeGh(store);
+    const r = await fetchGithubRecords({ repo: "o/r", gh: async (a) => gh(a), useCache: false, env: ENV });
+    assert.equal(r.items.length, 5);
+  });
+  it("records the coverage floor, crawls only the gap for a wider window and resets on --refresh", async () => {
+    const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-floor") };
+    const store = mkItems(100);
+    const w1 = storeGh(store);
+    const narrow = await fetchGithubRecords({ repo: "o/r", gh: w1.gh, env, since: ts(90) });
+    assert.equal(narrow.items.length, 11);
+    assert.equal(JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8")).coveredFrom, ts(90));
+    // same or narrower window: incremental from the watermark, floor unchanged
+    const same = storeGh(store);
+    await fetchGithubRecords({ repo: "o/r", gh: same.gh, env, since: ts(95) });
+    assert.ok(/since=/.test(same.calls[0]) && !same.calls[0].includes(`since=${ts(95)}`), "resumes from the watermark, not the window start");
+    assert.equal(JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8")).coveredFrom, ts(90));
+    // wider window: the uncovered gap is crawled (from the new start), then the floor is lowered
+    const wide = storeGh(store);
+    const r = await fetchGithubRecords({ repo: "o/r", gh: wide.gh, env, since: ts(50) });
+    assert.ok(wide.calls[0].includes(`since=${ts(50)}`));
+    assert.equal(r.items.length, 51, "the pre-window gap is not silently treated as covered");
+    assert.equal(JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8")).coveredFrom, ts(50));
+    // no --since after a windowed run: full history is crawled and the floor becomes null
+    const all = storeGh(store);
+    assert.equal((await fetchGithubRecords({ repo: "o/r", gh: all.gh, env })).items.length, 100);
+    assert.equal(JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8")).coveredFrom, null);
+    // --refresh ignores the cache and its floor
+    const fresh = storeGh(store);
+    await fetchGithubRecords({ repo: "o/r", gh: fresh.gh, env, refresh: true, since: ts(80) });
+    assert.equal(JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8")).coveredFrom, ts(80));
+  });
+  it("does not trust a legacy cache (no coveredFrom) for a window and never lowers the floor on failure", async () => {
+    const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-legacy") };
+    const store = mkItems(250);
+    mkdirSync(cacheDir("o/r", env), { recursive: true });
+    writeFileSync(join(cacheDir("o/r", env), "cache.json"), JSON.stringify({ v: 1, watermark: ts(250), items: {} }));
+    const g = storeGh(store, { failOnListCall: 2 });
+    await assert.rejects(() => fetchGithubRecords({ repo: "o/r", gh: g.gh, env, since: ts(10) }), /rate limited/);
+    const saved = JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8"));
+    assert.equal(saved.watermark, ts(250), "failed gap crawl keeps the old watermark");
+    assert.ok(!("coveredFrom" in saved) || saved.coveredFrom == null || saved.coveredFrom === undefined);
+    const h = storeGh(store);
+    const r = await fetchGithubRecords({ repo: "o/r", gh: h.gh, env, since: ts(10) });
+    assert.ok(h.calls[0].includes(`since=${ts(10)}`));
+    assert.equal(r.items.length, 241);
+  });
+  it("reports progress through onProgress and backs off when the rate limit is low", async () => {
+    const store = mkItems(6000);
+    const events = [];
+    await fetchGithubRecords({ repo: "o/r", gh: storeGh(store).gh, useCache: false, env: ENV, onProgress: (e) => events.push(e) });
+    assert.ok(events.some((e) => e.phase === "comments") && events.some((e) => e.phase === "issues" && e.done === 6000));
+    const slept = [];
+    const base = storeGh(store).gh;
+    const gh = (args) => (args.join(" ") === "api rate_limit" ? JSON.stringify({ resources: { core: { remaining: 3, reset: 1_000_100 } } }) : base(args));
+    await fetchGithubRecords({ repo: "o/r", gh, useCache: false, env: ENV, rateCheck: true, now: () => 1_000_000_000, sleep: async (ms) => { slept.push(ms); } });
+    assert.ok(slept.length > 0 && slept[0] === 101000, `slept ${slept}`);
+  });
+  it("never skips an item updated mid-crawl (keyset crawl, not page-number pagination)", async () => {
     const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-midcrawl") };
     const ts = (n) => new Date(Date.UTC(2026, 9, 1) + n * 60000).toISOString().replace(/\.\d{3}Z$/, "Z");
     const store = Array.from({ length: 250 }, (_, i) => ({ number: i + 1, updated_at: ts(i + 1), created_at: ts(0), state: "open", comments: 0, labels: [], user: { type: "Bot" } }));
@@ -252,6 +385,7 @@ describe("cache", () => {
     // listing call an already-served item is bumped, which moves it to the end of the ordering.
     const gh = (args) => {
       const path = args.find((a) => a.startsWith("repos/"));
+      if (/issues\/comments\?/.test(path)) return "[]";
       const q = new URLSearchParams(path.split("?")[1]);
       listCalls++;
       const since = q.get("since");
@@ -261,31 +395,32 @@ describe("cache", () => {
       if (listCalls === 1) store[4].updated_at = ts(++maxUpdated);
       return out;
     };
-    const first = fetchGithubRecords({ repo: "o/r", gh, env });
+    const first = await fetchGithubRecords({ repo: "o/r", gh, env });
     assert.equal(first.items.length, 250, "every item is cached after the crawl, none skipped by the shift");
     assert.equal(new Set(first.items.map((i) => i.number)).size, 250);
     // The bumped item moved past the crawl cursor, so the next incremental run (and its overlap window) still sees it.
     store[9].updated_at = ts(++maxUpdated); // another item updated after the first run
-    const second = fetchGithubRecords({ repo: "o/r", gh, env });
+    const second = await fetchGithubRecords({ repo: "o/r", gh, env });
     assert.equal(second.fromCache, true);
     assert.equal(second.items.length, 250);
     assert.equal(second.items.find((i) => i.number === 10).updatedAt, store[9].updated_at);
     assert.equal(second.items.find((i) => i.number === 5).updatedAt, store[4].updated_at);
   });
-  it("terminates and drains a full page whose items all share one updated_at", () => {
+  it("terminates and drains a full page whose items all share one updated_at", async () => {
     const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-sameTs") };
     const store = Array.from({ length: 230 }, (_, i) => ({ number: i + 1, updated_at: "2026-10-02T00:00:00Z", created_at: "2026-10-01T00:00:00Z", comments: 0, labels: [], user: { type: "Bot" } }));
     const gh = (args) => {
+      if (/issues\/comments\?/.test(args.find((a) => a.startsWith("repos/")))) return "[]";
       const q = new URLSearchParams(args.find((a) => a.startsWith("repos/")).split("?")[1]);
       const per = Number(q.get("per_page")), page = Number(q.get("page") ?? 1);
       const since = q.get("since");
       return JSON.stringify(store.filter((i) => !since || i.updated_at >= since).slice((page - 1) * per, page * per));
     };
-    assert.equal(fetchGithubRecords({ repo: "o/r", gh, env }).items.length, 230);
+    assert.equal((await fetchGithubRecords({ repo: "o/r", gh, env })).items.length, 230);
   });
-  it("rejects an unsafe repo before any gh call", () => {
+  it("rejects an unsafe repo before any gh call", async () => {
     const { gh, calls } = fakeGh();
-    assert.throws(() => fetchGithubRecords({ repo: "o/r; rm -rf /", gh }), /invalid repo/);
+    await assert.rejects(() => fetchGithubRecords({ repo: "o/r; rm -rf /", gh }), /invalid repo/);
     assert.equal(calls.length, 0);
   });
 });
@@ -298,6 +433,32 @@ describe("cli", () => {
     assert.throws(() => parseArgs(["--bogus"]), /unknown argument/);
     assert.throws(() => parseSince("yesterday"), /--since must be/);
   });
+  it("resolves --since to a crawl lower bound (date as is, version via release time minus a margin)", () => {
+    assert.equal(sinceToTimestamp("2026-10-01").since, "2026-10-01T00:00:00Z");
+    assert.equal(sinceToTimestamp(undefined).since, null);
+    const v = sinceToTimestamp("v1.16.0", [{ v: "1.16.0", t: Date.parse("2026-10-05T00:00:00Z") / 1000 }]);
+    assert.equal(v.since, "2026-10-04T00:00:00Z");
+    const unknown = sinceToTimestamp("1.99.0", []);
+    assert.equal(unknown.since, null);
+    assert.match(unknown.note, /full history/);
+  });
+  it("prints progress to stderr only, throttled, and keeps --json stdout parseable", async () => {
+    const out = [];
+    let t = 0;
+    const print = makeProgressPrinter((x) => out.push(x), () => t);
+    print({ phase: "issues", done: 100, total: null });
+    t += 500; print({ phase: "issues", done: 200, total: null });
+    t += 2000; print({ phase: "issues", done: 300, total: null });
+    assert.equal(out.length, 2);
+    const { gh } = fakeGh();
+    const realOut = process.stdout.write, realErr = process.stderr.write;
+    let stdout = "", stderr = "";
+    process.stdout.write = (c) => { stdout += c; return true; };
+    process.stderr.write = (c) => { stderr += c; return true; };
+    try { assert.equal(await runStats(["--repo", "o/r", "--json", "--no-cache", "--no-local"], { gh, env: ENV, releaseTimes: [] }), 0); } finally { process.stdout.write = realOut; process.stderr.write = realErr; }
+    assert.ok(JSON.parse(stdout).groups, "stdout is only the JSON report");
+    assert.match(stderr, /forgedock stats: (comments|issues) /);
+  });
   it("--help exits 0 and importing the module did not run it", () => {
     const r = spawnSync(process.execPath, [join(here, "index.mjs"), "--help"], { encoding: "utf8" });
     assert.equal(r.status, 0);

package/commands/review-pr-staging.md

@@ -471,7 +471,7 @@ if [ -n "$TRUSTED_SCRIPT" ] && [ -n "${ALL_PR_NUMBERS:-}" ] && [ -n "${PR_NUMBER
     # Reviewed = trusted FORGE:REVIEW_ROUTE (a real review mode) whose sha is the PR's FINAL head, plus at least one review-agent comment
     # carrying the full-length `Reviewed-SHA: <head>` line and a findings block (same predicate as review-pr.md Phase 5; a 7-char substring or a comment with no findings block never counts), and no degraded/blocked review marker. A PR pushed to after its review has a stale sha: the exact-head gate gives it no credit, and only the delta branch below (shared resolver `scripts/review-delta.sh`) may credit the commits an earlier trusted complete panel covered or a trusted `FORGE:REVIEW-CARRIED` base sync carried; everything else stays UNREVIEWED.
     _ROUTE=$(printf '%s' "$_CM" | bash "$TRUSTED_SCRIPT" count "^<!-- FORGE:REVIEW_ROUTE mode=(?!spec-evolution-blocked)[^ ]+ spec=review-pr.md sha=${_HEAD7} -->") || { SCOPE_MODE=full; break; }
-    _AGENT=$(printf '%s' "$_CM" | bash "$TRUSTED_SCRIPT" count "^(?=[\\s\\S]*<!-- REVIEW-FINDINGS-START -->)<!-- FORGE:REVIEW-AGENT:[a-z-]+ -->[\\s\\S]*(^|\\n)Reviewed-SHA: ${_HEAD}(\\r?\\n|$)") || { SCOPE_MODE=full; break; }
+    _AGENT=$(printf '%s' "$_CM" | bash "$TRUSTED_SCRIPT" count "^(?=[\\s\\S]*<!-- REVIEW-FINDINGS-START -->[\\s\\S]*<!-- REVIEW-FINDINGS-END -->)<!-- FORGE:REVIEW-AGENT:[a-z-]+ -->[\\s\\S]*(^|\\n)Reviewed-SHA: ${_HEAD}(\\r?\\n|$)") || { SCOPE_MODE=full; break; }
     _DEGRADED=$(printf '%s' "$_CM" | bash "$TRUSTED_SCRIPT" count "^<!-- FORGE:(REVIEW_DEGRADED|REVIEW_BLOCKED)") || { SCOPE_MODE=full; break; }
     case "$_ROUTE$_AGENT$_DEGRADED" in ''|*[!0-9]*) SCOPE_MODE=full; break ;; esac
     if [ "$_ROUTE" -ge 1 ] && [ "$_AGENT" -ge 1 ] && [ "$_DEGRADED" -eq 0 ] && [ "$(printf '%s' "$_J" | jq '.commits|length')" -lt 100 ]; then
@@ -1044,7 +1044,7 @@ for AGENT_DOMAIN in $LAUNCHED_REVIEW_AGENTS; do
   AGENT_COMMENT_COUNT=0
   if [ -n "$REVIEW_SHA_FULL" ] && [ -n "$TRUSTED_SCRIPT" ]; then
     AGENT_COMMENT_COUNT=$(gh api --paginate "repos/${GH_REPO}/issues/${PR_NUMBER}/comments" 2>/dev/null \
-      | bash "$TRUSTED_SCRIPT" count "^<!-- FORGE:REVIEW-AGENT:${AGENT_DOMAIN} -->[\\s\\S]*(^|\\n)Reviewed-SHA:[ ]${REVIEW_SHA_FULL}(\\r?\\n|$)" 2>/dev/null || echo 0)
+      | bash "$TRUSTED_SCRIPT" count "^(?=[\\s\\S]*<!-- REVIEW-FINDINGS-START -->[\\s\\S]*<!-- REVIEW-FINDINGS-END -->)<!-- FORGE:REVIEW-AGENT:${AGENT_DOMAIN} -->[\\s\\S]*(^|\\n)Reviewed-SHA:[ ]${REVIEW_SHA_FULL}(\\r?\\n|$)" 2>/dev/null || echo 0)
   fi
   case "$AGENT_COMMENT_COUNT" in ''|*[!0-9]*) AGENT_COMMENT_COUNT=0 ;; esac   # fail closed: counts as missing
   if [ "${AGENT_COMMENT_COUNT:-0}" -lt 1 ]; then
@@ -1054,7 +1054,7 @@ done
 
 if [ -n "$MISSING_AGENT_COMMENTS" ]; then
   echo "REVIEW DELIVERY FAILURE: missing findings comment(s) for:${MISSING_AGENT_COMMENTS}"
-  echo "Recover each agent's returned verdict, findings, and durable body path before rerunning review."
+  echo "A comment without a REVIEW-FINDINGS-START block counts as missing. Re-dispatch the missing agent once with the note: structured findings block required. A second miss is a degraded panel. Recover each agent's returned verdict, findings, and durable body path before rerunning review."
   exit 1
 fi
 ```
@@ -1086,7 +1086,7 @@ bash "$RF" classify --pr "$PR_NUMBER" --repo "$GH_REPO" --context "$CTX" --out-d
 cat "$OUT_DIR/note-list.txt" 2>/dev/null
 ```
 
-Read `FINDINGS_KEPT`, `FINDINGS_DROPPED_STALE`, `FINDINGS_PREEXISTING` and `NOTES_DEMOTED_NO_SCENARIO` for the summary. With no kept finding and no unstructured finding in the trusted reviewer bodies, skip to Phase 8.
+Read `FINDINGS_KEPT`, `FINDINGS_DROPPED_STALE`, `FINDINGS_PREEXISTING` and `NOTES_DEMOTED_NO_SCENARIO` for the summary. Findings come only from `FINDING:` markers, never from free text. If `AGENTS_WITHOUT_BLOCK` is non-empty those agents are undelivered (no findings block): re-dispatch them once with the note "structured findings block required", else take the degraded-panel path; `CLEAN_STRUCTURED` is withheld meanwhile. With no kept finding and `CLEAN_STRUCTURED=true`, skip to Phase 8. A marker-less finding is classified with `classify-finding.sh --unstructured` (empty or unparseable severity is `NOTE unstructured`, never ISSUE).
 
 ### 7B: Note disposition (same damper and classifier as `/review-pr` §6B.5)
 

package/commands/review-pr.md

@@ -367,6 +367,8 @@ Reviewer roster tier \`${ROSTER_TIER}\`: ${ROSTER_REASON}. Roster: ${SELECTED_AG
 
 **Extended review (`REVIEW_DEPTH=EXTENDED`)** <!-- Added: forge#3862 -->: the roster script has already lifted a small, medium or fix-pr roster to standard and widened the standard baseline to the top-3 domains. Additionally dispatch each selected domain agent once per slice of at most `review.depth.slice_files` changed files (default 12; one slice when the PR has no more files), each slice carrying only its files' diff and the shared PR context, and merge the per-slice findings in Phase 5 (the dedup there treats the same `file:line` from two slices as one). The Security agent always reviews the whole diff, never a slice. Extended depth never skips a Phase 2 check, never weakens the Security floor, and never blocks the merge by itself; it is not a finding.
 
+**Degraded gate** <!-- Added: forge#3628 -->: when `MERGE_ISSUE` is set, read the `**Degraded**:` line of its newest trusted `FORGE:QUALITY_GATE` and the `FORGE:ACCEPTANCE_GATE:DEGRADED` list (via `scripts/trusted-comments.sh`). A non-`none` list means a check ran nothing (tests skipped or not run, known-slow skip, blast-radius incomplete). Give each domain agent that list as "Degraded checks to review by hand": it must read the code those checks would have exercised. Post the section in a PR comment whose first line is `<!-- FORGE:REVIEW-AGENT:{domain} -->` (or the synthesis marker) and which carries a `Reviewed-SHA: ${REVIEW_SHA}` line for the current head. Under `### Degraded Paths Reviewed`, write one list item per degraded check as `- <exact name>: <how its path was reviewed>`; a generic section, a stale-head comment, or an item saying the check was NOT reviewed does not satisfy Phase 8 (forge#3995).
+
 ### 3B.5: Provenance-Based Trust Escalation (Conditional)
 
 Proven `(task-type × module-set)` combinations may drop optional judgment agents; novel ones widen to the full affected-domain panel (`NOVEL_NEEDS_HUMAN` also sets `needs-human` on merge). **Hard floor**: Security and every Phase 2 check run at every tier. **Application is skipped** (the lookup still runs, recording the calibration cell key) for `THOROUGH`, milestone-to-staging, `BASE_SYNC_ONLY`, and a `DELTA` head past two full rounds. **Default is SHADOW**: any error path (absent table, parse failure, git error) logs and leaves the roster unchanged, never looser or tighter; `review.trust_shadow_mode: "false"` enforces. `PROVEN` narrows only to Security plus hard-signal agents (AUTH, BILLING, DATABASE or INFRA score >= 3) and never under churn escalation or a danger zone. <!-- forge#1745, forge#1804 -->
@@ -437,7 +439,7 @@ Re-reviewing a head that only moved does not need the whole panel over the whole
 
 Phase 2, the §6B.4 gates (full PR diff at the current head) and the 7B/8 gates run unchanged in every mode.
 
-**Reviewer-comment trust and shape (applies to every check below and in Phase 4)**: a reviewer comment counts only when it is from a trusted author (`scripts/trusted-comments.sh`, the same predicate as the in-PR fix gate and `verify-phase-trail.sh`: trusted association, Bot account, or `FORGE_TRAIL_TRUSTED_LOGINS`), its body **starts with** `<!-- FORGE:REVIEW-AGENT:{domain} -->`, and it carries a line `Reviewed-SHA: ${REVIEW_SHA}` for the current head. The head SHA is public, so the SHA line alone proves nothing: an untrusted commenter must never suppress dispatch or satisfy the panel guard. An unresolved trust script or a non-integer count means **not posted** (fail closed).
+**Reviewer-comment trust and shape (applies to every check below and in Phase 4)**: a reviewer comment counts only when it is from a trusted author (`scripts/trusted-comments.sh`, the same predicate as the in-PR fix gate and `verify-phase-trail.sh`: trusted association, Bot account, or `FORGE_TRAIL_TRUSTED_LOGINS`), its body **starts with** `<!-- FORGE:REVIEW-AGENT:{domain} -->`, it carries a line `Reviewed-SHA: ${REVIEW_SHA}` for the current head, and it carries a `<!-- REVIEW-FINDINGS-START -->` ... `<!-- REVIEW-FINDINGS-END -->` block (empty allowed). A verdict without the block ("APPROVE, no findings") is **undelivered**, never read as clean and never scanned for free-text findings. The head SHA is public, so the SHA line alone proves nothing: an untrusted commenter must never suppress dispatch or satisfy the panel guard. An unresolved trust script or a non-integer count means **not posted** (fail closed).
 
 **Pre-dispatch fence.** For `BASE_SYNC_ONLY` it dispatches zero reviewers and posts the carry record (then go straight to Phase 4). Otherwise it implements **idempotent re-entry**: a re-invoked review reuses reviewers that already posted for the current head, so it prints `PENDING_AGENTS` (the domains of the effective roster with no trusted current-SHA comment; comments for another SHA never count) and the linked issue's `BLAST_RADIUS_MANIFEST` (advisory; any failure prints it empty).
 
@@ -479,7 +481,7 @@ agent_domain() { local l; l=$(printf '%s' "${1}" | tr '[:upper:]' '[:lower:]');
 for AGENT in $SELECTED_AGENTS; do
   AGENT_DOMAIN=$(agent_domain "$AGENT"); HAVE=""
   if [ -n "$TRUSTED_SCRIPT" ]; then
-    HAVE=$(printf '%s' "$COMMENTS_JSON" | bash "$TRUSTED_SCRIPT" count "^<!-- FORGE:REVIEW-AGENT:${AGENT_DOMAIN} -->[\\s\\S]*(^|\\n)Reviewed-SHA: ${REVIEW_SHA}(\\r?\\n|$)" 2>/dev/null || echo "")
+    HAVE=$(printf '%s' "$COMMENTS_JSON" | bash "$TRUSTED_SCRIPT" count "^(?=[\\s\\S]*<!-- REVIEW-FINDINGS-START -->[\\s\\S]*<!-- REVIEW-FINDINGS-END -->)<!-- FORGE:REVIEW-AGENT:${AGENT_DOMAIN} -->[\\s\\S]*(^|\\n)Reviewed-SHA: ${REVIEW_SHA}(\\r?\\n|$)" 2>/dev/null || echo "")
   fi
   case "$HAVE" in ''|*[!0-9]*) HAVE=0 ;; esac   # fail closed: unreadable or untrusted counts as not posted
   [ "$HAVE" -lt 1 ] && PENDING_AGENTS="${PENDING_AGENTS} ${AGENT}"
@@ -548,7 +550,7 @@ Each agent's `[FILE_LIST]` is `slices.<domain>.paths` from the context: the Secu
 
 ## Phase 4: Wait for Agents
 
-Completion is read from GitHub, never from notifications. A reviewer is complete only when a **trusted** comment (3C trust rule) starting with `<!-- FORGE:REVIEW-AGENT:{domain} -->` carries `Reviewed-SHA: <current head>`.
+Completion is read from GitHub, never from notifications. A reviewer is complete only when a **trusted** comment (3C trust rule) starting with `<!-- FORGE:REVIEW-AGENT:{domain} -->` carries `Reviewed-SHA: <current head>` and a findings block (`REVIEW-FINDINGS-START` ... `REVIEW-FINDINGS-END`, empty allowed). A domain whose comment lacks the block is missing: re-dispatch it **once** (3C, with the note "structured findings block required: end your comment with REVIEW-FINDINGS-START/END, empty if no findings"), then re-run this phase; a second miss is a delivery failure and takes the existing degraded-panel hard stop below. Never loop beyond that one re-dispatch.
 
 - **Joined tools** (`Task`, `task`): the reviewers already returned, so one pass decides; anything missing is a delivery failure.
 - **Async `Agent`**: bounded wait, **one poll pass per Bash call** (a call is capped at 120s, 600s max, so one long loop would be killed before the hard stop ran). The first pass records an epoch deadline in a private absolute file keyed by PR and head SHA; every exit removes it and 3C removes it before (re)dispatch, so a re-review never inherits an expired window. Re-run while it prints `PANEL_STATUS: WAITING`.
@@ -590,7 +592,7 @@ agent_domain() { local l; l=$(printf '%s' "${1}" | tr '[:upper:]' '[:lower:]');
 for AGENT in $SELECTED_AGENTS; do
   AGENT_DOMAIN=$(agent_domain "$AGENT"); N=""
   if [ -n "$TRUSTED_SCRIPT" ] && [ -n "$COMMENTS_JSON" ]; then
-    N=$(printf '%s' "$COMMENTS_JSON" | bash "$TRUSTED_SCRIPT" count "^<!-- FORGE:REVIEW-AGENT:${AGENT_DOMAIN} -->[\\s\\S]*(^|\\n)Reviewed-SHA: ${REVIEW_SHA}(\\r?\\n|$)" 2>/dev/null || echo "")
+    N=$(printf '%s' "$COMMENTS_JSON" | bash "$TRUSTED_SCRIPT" count "^(?=[\\s\\S]*<!-- REVIEW-FINDINGS-START -->[\\s\\S]*<!-- REVIEW-FINDINGS-END -->)<!-- FORGE:REVIEW-AGENT:${AGENT_DOMAIN} -->[\\s\\S]*(^|\\n)Reviewed-SHA: ${REVIEW_SHA}(\\r?\\n|$)" 2>/dev/null || echo "")
   fi
   case "$N" in ''|*[!0-9]*) N=0 ;; esac   # fail closed
   if [ "$N" -lt 1 ]; then MISSING_AGENT_COMMENTS="${MISSING_AGENT_COMMENTS} ${AGENT_DOMAIN}"; else ACTUAL_AGENT_COUNT=$(( ACTUAL_AGENT_COUNT + 1 )); fi
@@ -655,7 +657,7 @@ cat "$OUT_DIR/note-list.txt" 2>/dev/null
 
 `extract` reads the trusted synthesized block for the head, else its trusted agent bodies (`BASE_SYNC_ONLY`: the carried head; `DELTA`: this head plus the earlier reviewed one), parses every `<!-- FINDING:... -->` marker (an unparseable marker blocks the review), dedupes by file + line range ±5 and by title (3+ shared keywords, higher confidence wins), and applies the **§6B.4 gates** in order, each keeping the finding when its input is unreadable: (1) **head-SHA**: a cited line past the end of the file at `REVIEW_SHA` is stale and DROPPED (`findings_dropped_stale`); (2) **introduced-line**: a MEDIUM-or-lower finding whose range (±5) misses the PR's added lines is `pre-existing` (**CRITICAL/HIGH are never routed as pre-existing**, whatever their confidence, `protocols.md` §5; input comes from the diff, never a reviewer's `**Scope**` tag; deleted, renamed and patch-less files always intersect); (3) **concrete-failure**: a MEDIUM-or-lower finding without a `**Failure scenario**` becomes a NOTE (`notes_demoted_no_scenario`).
 
-Read `STRUCTURED_FINDINGS`, `FINDINGS_KEPT`, `FINDINGS_DROPPED_STALE`, `FINDINGS_PREEXISTING` and `NOTES_DEMOTED_NO_SCENARIO` for the record and summary. The caller's part of 6A: add the Phase 2.5 `INTEG-N` findings no reviewer covered (CONFIRMED HIGH, so ISSUE, filed in 6C); on `CLEAN_STRUCTURED=true` scan the trusted agent comments for unstructured findings (lines starting "Finding", "Issue", "Bug", "Warning"), and with none and no `INTEG-N` the review is clean: skip to Phase 7. **Pre-existing route**: a pre-existing finding (MEDIUM or lower) is never filed as `review-finding`/`needs-validation` nor linked to this PR (it stays out of findings-per-PR and the amplification ratio); it still passes the §6B.5 classifier, is listed once in the summary, and at most 3 per review (highest severity first) are filed with the `pre-existing` label plus `priority:*`, citing this PR (`preexisting_filed`, not `findings_filed`).
+Read `STRUCTURED_FINDINGS`, `FINDINGS_KEPT`, `FINDINGS_DROPPED_STALE`, `FINDINGS_PREEXISTING` and `NOTES_DEMOTED_NO_SCENARIO` for the record and summary. The caller's part of 6A: add the Phase 2.5 `INTEG-N` findings no reviewer covered (CONFIRMED HIGH, so ISSUE, filed in 6C); findings come only from `FINDING:` markers, never from free text. If `AGENTS_WITHOUT_BLOCK` is non-empty those agents are undelivered: re-dispatch them once (Phase 4 rule), else take the degraded-panel path; `CLEAN_STRUCTURED` is withheld while it is non-empty. On `CLEAN_STRUCTURED=true` and no `INTEG-N` the review is clean: skip to Phase 7. A finding that somehow has no marker is classified with `classify-finding.sh --unstructured` (empty or unparseable severity gives `NOTE unstructured`, never ISSUE). **Pre-existing route**: a pre-existing finding (MEDIUM or lower) is never filed as `review-finding`/`needs-validation` nor linked to this PR (it stays out of findings-per-PR and the amplification ratio); it still passes the §6B.5 classifier, is listed once in the summary, and at most 3 per review (highest severity first) are filed with the `pre-existing` label plus `priority:*`, citing this PR (`preexisting_filed`, not `findings_filed`).
 
 ### 6B.5: Non-blocking note disposition (MANDATORY before 6C)
 
@@ -674,7 +676,7 @@ Each NOTE gets one disposition: (1) **fix in this PR**, only comment, documentat
 
 ### 6B.6: In-PR fix gate
 
-A CONFIRMED MEDIUM-or-higher defect in a file this PR changed is cheaper to fix before merge than through a separate `/work-on` cycle: `classify` marks it `INPR_FIX` and posts the `FORGE:INPR_FIX` request after the disposition marker (`INPR_FIX_POSTED=true`), so do NOT file those findings in 6C. Narrow by design: auto-merge reviews with `--issue`, files in the PR diff, one round per PR (any trusted `FORGE:INPR_FIX*` marker ends it). Phase 8 then refuses to merge this head (blocker `in-pr fix required`). If the round fails, `/work-on` waives it for MEDIUM and files the findings (`work-on/review.md` R4); HIGH/CRITICAL are never waived and end at `needs-human`.
+A CONFIRMED MEDIUM-or-higher defect, or a LIKELY MEDIUM defect whose line the PR introduced (`scope=introduced`), in a file this PR changed is cheaper to fix before merge than through a separate `/work-on` cycle: `classify` marks it `INPR_FIX` and posts the `FORGE:INPR_FIX` request after the disposition marker (`INPR_FIX_POSTED=true`), so do NOT file those findings in 6C. `review-finalize.sh extract` computes `scope` (`introduced` | `pre-existing` | `unknown`) per finding from the PR diff (the added-line window; unknown provenance never widens the gate). Narrow by design: auto-merge reviews with `--issue`, files in the PR diff, one round per PR (any trusted `FORGE:INPR_FIX*` marker ends it). Phase 8 then refuses to merge this head (blocker `in-pr fix required`). If the round fails, `/work-on` waives it for MEDIUM and files the findings (`work-on/review.md` R4); HIGH/CRITICAL are never waived and end at `needs-human`.
 
 ### 6C: Create Issues
 
@@ -718,6 +720,7 @@ cat <<'ISSUE_EOF' > "$FINDING_ISSUE_BODY_FILE"
 **Agent**: [name] ([domain])
 **Confidence**: [CONFIRMED/LIKELY/POSSIBLE]
 **Severity**: [CRITICAL/HIGH/MEDIUM/LOW]
+**Scope**: introduced|pre-existing (the worklist item's `scope`; omit the line when it is `unknown`)
 **Review comment**: [permalink to agent comment]
 
 ## Pattern Metadata
@@ -799,25 +802,29 @@ Append a `## Review Findings` table (summaries and issue links) to the PR body:
 
 ```bash
 PR_NUMBER="{PR_NUMBER}"; REPO="{GH_REPO}"; MERGE_ISSUE="{MERGE_ISSUE}"
-MERGE_HEALTH="{MERGE_HEALTH}"; MERGE_HEALTH_STATE="{MERGE_HEALTH_STATE}"; BASE="{BASE}"; HEAD="{HEAD}"; REVIEW_SHA="{REVIEW_SHA}"
+MERGE_HEALTH="{MERGE_HEALTH}"; MERGE_HEALTH_STATE="{MERGE_HEALTH_STATE}"; BASE="{BASE}"; HEAD="{HEAD}"; REVIEW_SHA="{REVIEW_SHA}"; CTX="{CONTEXT_FILE}"
 INTENSITY_TIER="{INTENSITY_TIER}"; TABLE_CELL_KEY="{TABLE_CELL_KEY}"; TRUST_SHADOW_MODE="{TRUST_SHADOW_MODE}"; TRUST_NEEDS_HUMAN="{TRUST_NEEDS_HUMAN}"
 type forge_resolve >/dev/null 2>&1 || { setopt nonomatch 2>/dev/null || true; FORGE_SOURCED_ROOT='${CLAUDE_PLUGIN_ROOT}'; for _r in "$(cygpath -u "${FORGEDOCK_HOME:-}" 2>/dev/null || printf %s "${FORGEDOCK_HOME:-}")" '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGE_HOME:-}" "$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null | sed 's|/commands/work-on\.md$||')" "$(head -n 1 "${CODEX_HOME:-$HOME/.codex}/forge-home" 2>/dev/null)" "$HOME/.claude/plugins/marketplaces/forgedock" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/forgedock/forgedock/* "$HOME/.claude"/plugins/cache/forgedock/forgedock/*; do case "$_r" in /*) [ -f "$_r/scripts/lib/forge-resolve.sh" ] && { . "$_r/scripts/lib/forge-resolve.sh"; break; };; esac; done; type forge_resolve >/dev/null 2>&1 || forge_resolve() { :; }; }
 RF=$(forge_resolve review-finalize.sh)   # install roots only, never the PR checkout; unresolvable is a stop (fail closed), never a skipped gate
 [ -n "$RF" ] || { echo "REVIEW_RESULT: status: BLOCKED, blocker: scripts/review-finalize.sh not resolvable (set FORGEDOCK_HOME to the ForgeDock install); refusing to continue (fail closed)"; exit 1; }   # STOP
-# --result: stale (PR HEAD moved) | clean (no blocking criteria) | blocking (any criterion above). Free text is data, never code.
+OUT_DIR="$(dirname "$CTX")/review-finalize-${PR_NUMBER}"; mkdir -p "$OUT_DIR"
+# Free text (purpose-regression findings, agents list) derives from PR content: BEFORE this fence, write it with the file-write tool (never a
+# shell heredoc, echo or printf of the text) to "$OUT_DIR/purpose-findings.txt" (ids and reasons; leave absent when there is no purpose regression)
+# and "$OUT_DIR/agents.txt" ("{N} agents: {names}"). It is passed by path, so it is never re-parsed as shell. Never put free text in a shell word.
+# --result: stale (PR HEAD moved) | clean (no blocking criteria) | blocking (any criterion above).
 VERDICT_OUT=$(bash "$RF" verdict --pr "$PR_NUMBER" --repo "$REPO" --review-sha "$REVIEW_SHA" --base "$BASE" --head-branch "$HEAD" \
   --merge-health "$MERGE_HEALTH" --merge-health-state "$MERGE_HEALTH_STATE" --is-milestone "{IS_MILESTONE_TO_STAGING}" \
-  --has-purpose-regression "{HAS_PURPOSE_REGRESSION}" --purpose-findings '{PURPOSE_REGRESSION_FINDINGS}' \
-  --result "{RESULT}" --agents '{N} agents: {names}' --findings-count "{M}" --blocking-count "{N_BLOCKING}" \
+  --has-purpose-regression "{HAS_PURPOSE_REGRESSION}" --purpose-findings-file "$OUT_DIR/purpose-findings.txt" \
+  --result "{RESULT}" --agents-file "$OUT_DIR/agents.txt" --findings-count "{M}" --blocking-count "{N_BLOCKING}" \
   --intensity-tier "$INTENSITY_TIER" --table-cell-key "$TABLE_CELL_KEY" --trust-shadow-mode "$TRUST_SHADOW_MODE"); VERDICT_RC=$?
 printf '%s\n' "$VERDICT_OUT"
 [ "$VERDICT_RC" -eq 0 ] || exit 1   # STOP: REVIEW_RESULT: status: BLOCKED was printed
 # 7B.5: reads task type and confidence from the linked issue's FORGE:INVESTIGATOR, consults origin/forge-knowledge, records FORGE:CALIBRATION_CHECK.
-bash "$RF" calibrate --pr "$PR_NUMBER" --repo "$REPO" --issue "$MERGE_ISSUE" \
+bash "$RF" calibrate --pr "$PR_NUMBER" --repo "$REPO" --issue "$MERGE_ISSUE" --out-dir "$OUT_DIR" \
   --intensity-tier "$INTENSITY_TIER" --table-cell-key "$TABLE_CELL_KEY" --trust-shadow-mode "$TRUST_SHADOW_MODE" --trust-needs-human "$TRUST_NEEDS_HUMAN"
 ```
 
-`verdict` computes `BASE_CONFLICT` (the single source of truth for the Phase 8 guards), posts the verdict with the trust annotation, and never posts a clean verdict over a base conflict or purpose regression (it downgrades to CHANGES REQUESTED, `VERDICT_COERCED=true`). Read `VERDICT=`, `BASE_CONFLICT=`, `HAS_PURPOSE_REGRESSION=` and, from `calibrate`, `CALIBRATION_NEEDS_HUMAN=` / `CALIBRATION_NOTE=`: they are the Phase 8 flags.
+`verdict` computes `BASE_CONFLICT` (the single source of truth for the Phase 8 guards), posts the verdict with the trust annotation, and never posts a clean verdict over a base conflict or purpose regression (it downgrades to CHANGES REQUESTED, `VERDICT_COERCED=true`). Read `VERDICT=`, `BASE_CONFLICT=`, `HAS_PURPOSE_REGRESSION=` and, from `calibrate`, `CALIBRATION_NEEDS_HUMAN=` / `CALIBRATION_NOTE=`: they are the Phase 8 flags. The note itself is also written to `$OUT_DIR/calibration-note.txt`, which Phase 8 passes by path; free text is never placed in a shell word.
 
 ---
 
@@ -825,18 +832,20 @@ bash "$RF" calibrate --pr "$PR_NUMBER" --repo "$REPO" --issue "$MERGE_ISSUE" \
 
 **Skip if** `AUTO_MERGE=false`.
 
-**One script owns every Phase 8 gate (MANDATORY; a gate is never skipped, reordered or hand-run).** `review-finalize.sh merge-gate` runs, in order, and stops at the first refusal: the note-disposition preflight (a trusted `FORGE:NOTE_DISPOSITION` must exist), the in-PR fix gate (an unanswered trusted `FORGE:INPR_FIX` at the current head blocks), the phase-trail preflight (`scripts/verify-phase-trail.sh` on the linked issue; `--issue` is mandatory and never inferred; an infrastructure failure is `BLOCKED` plus `needs-human`) <!-- Added: forge#3061 -->, the guard-state flags below (`VERDICT` is `APPROVED` or `CHANGES REQUESTED`, the others `true`/`false`; an empty or unsubstituted value aborts with `needs-human`; `--other-blocking true` when 7B criterion 1, 2, 3 or 5 fired), routing (a base conflict as the ONLY blocker routes to the base-sync path, `blocker: base-conflict`; any other hold adds `needs-human`), the pre-merge mergeability guard on fresh state, the previously-escalated guard (parks at `workflow:awaiting-merge`, never merges), the CI gate (`scripts/wait-ci-green.sh`) with the reviewed-head guard (only the commit the `FORGE:REVIEW_ROUTE` sha approved; a docs-only delta is allowed), and finally the merge with `--match-head-commit`. Every gate fails closed.
+**One script owns every Phase 8 gate (MANDATORY; a gate is never skipped, reordered or hand-run).** `review-finalize.sh merge-gate` runs, in order, and stops at the first refusal: the note-disposition preflight (a trusted `FORGE:NOTE_DISPOSITION` must exist), the in-PR fix gate (an unanswered trusted `FORGE:INPR_FIX` at the current head blocks), the phase-trail preflight (`scripts/verify-phase-trail.sh` on the linked issue; `--issue` is mandatory and never inferred; an infrastructure failure is `BLOCKED` plus `needs-human`) <!-- Added: forge#3061 -->, the degraded-gate review (`degraded-gate-unreviewed` unless a `### Degraded Paths Reviewed` section covers each degraded check), the guard-state flags below (`VERDICT` is `APPROVED` or `CHANGES REQUESTED`, the others `true`/`false`; an empty or unsubstituted value aborts with `needs-human`; `--other-blocking true` when 7B criterion 1, 2, 3 or 5 fired), routing (a base conflict as the ONLY blocker routes to the base-sync path, `blocker: base-conflict`; any other hold adds `needs-human`), the pre-merge mergeability guard on fresh state, the previously-escalated guard (parks at `workflow:awaiting-merge`, never merges), the CI gate (`scripts/wait-ci-green.sh`) with the reviewed-head guard (only the commit the `FORGE:REVIEW_ROUTE` sha approved; a docs-only delta is allowed), and finally the merge with `--match-head-commit`. Every gate fails closed.
 
 ```bash
 PR_NUMBER="{PR_NUMBER}"; REPO="{GH_REPO}"
 MERGE_ISSUE="{MERGE_ISSUE}"; MERGE_BASE="{MERGE_BASE}"; IS_MILESTONE_TO_STAGING="{IS_MILESTONE_TO_STAGING}"
-VERDICT="{VERDICT}"; HAS_PURPOSE_REGRESSION="{HAS_PURPOSE_REGRESSION}"; CALIBRATION_NEEDS_HUMAN="{CALIBRATION_NEEDS_HUMAN}"; CALIBRATION_NOTE='{CALIBRATION_NOTE}'
+VERDICT="{VERDICT}"; HAS_PURPOSE_REGRESSION="{HAS_PURPOSE_REGRESSION}"; CALIBRATION_NEEDS_HUMAN="{CALIBRATION_NEEDS_HUMAN}"; CTX="{CONTEXT_FILE}"
 TRUST_NEEDS_HUMAN="{TRUST_NEEDS_HUMAN}"; BASE_CONFLICT="{BASE_CONFLICT}"; OTHER_BLOCKING="{OTHER_BLOCKING}"; TABLE_CELL_KEY="{TABLE_CELL_KEY}"
 type forge_resolve >/dev/null 2>&1 || { setopt nonomatch 2>/dev/null || true; FORGE_SOURCED_ROOT='${CLAUDE_PLUGIN_ROOT}'; for _r in "$(cygpath -u "${FORGEDOCK_HOME:-}" 2>/dev/null || printf %s "${FORGEDOCK_HOME:-}")" '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGE_HOME:-}" "$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null | sed 's|/commands/work-on\.md$||')" "$(head -n 1 "${CODEX_HOME:-$HOME/.codex}/forge-home" 2>/dev/null)" "$HOME/.claude/plugins/marketplaces/forgedock" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/forgedock/forgedock/* "$HOME/.claude"/plugins/cache/forgedock/forgedock/*; do case "$_r" in /*) [ -f "$_r/scripts/lib/forge-resolve.sh" ] && { . "$_r/scripts/lib/forge-resolve.sh"; break; };; esac; done; type forge_resolve >/dev/null 2>&1 || forge_resolve() { :; }; }
 RF=$(forge_resolve review-finalize.sh)   # install roots only, never the PR checkout; unresolvable is a stop (fail closed), never a skipped gate
 [ -n "$RF" ] || { echo "REVIEW_RESULT: status: BLOCKED, blocker: scripts/review-finalize.sh not resolvable (set FORGEDOCK_HOME to the ForgeDock install); refusing to continue (fail closed)"; exit 1; }   # STOP
+# The calibration note derives from issue text: `calibrate` (Phase 7B.5) wrote it to this file; it is passed by path, never substituted into a shell word.
+OUT_DIR="$(dirname "$CTX")/review-finalize-${PR_NUMBER}"
 GATE_OUT=$(bash "$RF" merge-gate --pr "$PR_NUMBER" --repo "$REPO" --issue "$MERGE_ISSUE" --base "$MERGE_BASE" \
-  --verdict "$VERDICT" --has-purpose-regression "$HAS_PURPOSE_REGRESSION" --calibration-needs-human "$CALIBRATION_NEEDS_HUMAN" --calibration-note "$CALIBRATION_NOTE" \
+  --verdict "$VERDICT" --has-purpose-regression "$HAS_PURPOSE_REGRESSION" --calibration-needs-human "$CALIBRATION_NEEDS_HUMAN" --calibration-note-file "$OUT_DIR/calibration-note.txt" \
   --trust-needs-human "$TRUST_NEEDS_HUMAN" --base-conflict "$BASE_CONFLICT" --other-blocking "$OTHER_BLOCKING" --table-cell-key "$TABLE_CELL_KEY"); GATE_RC=$?
 printf '%s\n' "$GATE_OUT"
 # 8B: only for a milestone->staging PR whose merge just succeeded: clears the milestone on its open review-finding issues so they flow through the fast lane.
@@ -849,6 +858,7 @@ exit "$GATE_RC"
 **Outcome mapping.** Report the script's output; never re-run its gates by hand and never `gh pr merge` yourself.
 - Exit 0, `MERGE_OUTCOME=merged` (`MERGE_STATE=MERGED`): merged. `merge-failed`: the merge did not land (the script commented on the issue). `parked-awaiting-merge`: parked per the previously-escalated guard; the script performs the transition itself (`transition-label.sh ... awaiting-merge`, prose fallback `gh issue edit --add-label "workflow:awaiting-merge"`).
 - Exit 3: print the `REVIEW_RESULT: status: BLOCKED, blocker: ...` line and stop; `MERGE_OUTCOME=` names the case (`base-conflict`, `needs-human`, `protection-blocked`, `stale-review`, `ci-not-green`). A CI gate TIMEOUT prints `CI_GATE_TIMEOUT`: re-run the same fence up to 3 more times. A phase-trail blocker with no MISSING lines (`phase trail unreadable (rc=N)`, `auto-merge requires --issue`) is an infrastructure or usage failure: callers neither re-run phases nor merge manually.
+- Exit 3 with `blocker: degraded-gate-unreviewed` (`needs-human` added): the linked issue's gate is DEGRADED and no trusted review comment for the current head has a `### Degraded Paths Reviewed` section with a `- name: how reviewed` item for every degraded check. Not a code defect: `work-on:review` (R4) re-runs the review once so the section is added. Never merge by hand. <!-- Added: forge#3628 -->
 - Exit 4: `REVIEW_RESULT: status: PHASE_TRAIL_FAILED` plus the `MISSING:` lines. Return that status and stop: this phase never re-runs the missing phases and never escalates to `needs-human`; `work-on:review` (R4) alone owns re-dispatching them (forge#3102).
 
 Phase 8 ONLY merges the PR. It does NOT close the issue, update labels or clean up worktrees: when invoked via `/work-on` those belong to `work-on/close.md`, and doing them here would close the issue with `workflow:merged` before the close phase ran. <!-- Added: forge#815 -->