forgedock 1.26.0 → 1.28.0

package/bin/lean/conformance.mjs

@@ -12,10 +12,13 @@ import { OUTCOME_CODES } from "../engine/outcome-codes.mjs";
 export const DISPOSITIONS = Object.freeze(["deliver", "defer", "not-applicable", "post-deploy"]);
 /** Dispositions the engine files as a tracked follow-up issue before anything merges. */
 export const TRACKED = Object.freeze(["defer", "post-deploy"]);
+/** forge#4165: where a plan decision's justification comes from; audits filter on lint|precedent. */
+export const DECISION_SOURCES = Object.freeze(["doc", "lint", "precedent", "spec"]);
 const REQ_STATUS = ["implemented", "partial", "missing", "deferred", "post-deploy", "not-applicable"];
 const COVER_STATUS = ["covered", "narrowed", "missing"];
 const PRESERVE_STATUS = ["intact", "violated", "unverified"];
-const EVIDENCE_RE = /^([^\s:]+):(\d+)/;
+/** The first path:line anywhere in the evidence text (backticks, quotes and brackets around it are ignored). */
+const EVIDENCE_RE = /([^\s:`'"()[\]<>,;]+):(\d+)/;
 /** Test files in any common ecosystem: test dirs, *.test.* / *.spec.*, test_*.*, *_test.*, *Test(s).java|kt|cs|php|scala, *_spec.rb, tests.rs, conftest.py, snapshots. */
 const TEST_RE = /(^|\/)(test|tests|__tests__|spec|specs|testdata|__snapshots__)\/|\.(test|spec)\.[a-z0-9]+$|(^|\/)test_[^/]+\.[a-z0-9]+$|_test\.[a-z0-9]+$|Tests?\.(java|kt|kts|cs|php|scala|swift)$|_spec\.rb$|(^|\/)tests\.rs$|(^|\/)conftest\.py$|\.bats$|\.snap$/;
 /** Files any change may touch without being a deliverable: changelogs and dependency lockfiles. */
@@ -59,8 +62,16 @@ export function authorizationOf(contract, f) {
 }
 const blank = (s) => !String(s ?? "").trim() || /^none$/i.test(String(s).trim());
 
-/** Shape check of the builder's contract.json against the issue text. Returns {ok, problems[]}. */
-export function validateContract(c, issueText) {
+/** forge.yaml lean.repro_test (#4271): "prefer" (default) asks a bug lane for a red-green repro test; "off" is today's contract. */
+export const REPRO_MODES = Object.freeze(["off", "prefer"]);
+/** True when the issue carries a `bug` or `type:bug` label (names or {name} objects). */
+export const isBugIssue = (labels) => (Array.isArray(labels) ? labels : []).some((l) => ["bug", "type:bug"].includes(String(l?.name ?? l).trim().toLowerCase()));
+
+/**
+ * Shape check of the builder's contract.json against the issue text. Returns {ok, problems[]}. `repro` (#4271): a bug
+ * lane with lean.repro_test on also needs repro_test: {path, id?, command}, or "none" with a repro_test_reason.
+ */
+export function validateContract(c, issueText, { repro = false } = {}) {
   const problems = [];
   if (!c || typeof c !== "object" || Array.isArray(c)) return { ok: false, problems: ["contract.json is missing or not a JSON object"] };
   const reqs = Array.isArray(c.requirements) ? c.requirements : [];
@@ -79,8 +90,19 @@ export function validateContract(c, issueText) {
   if (reqs.some((r) => r?.disposition === "deliver") && !dels.length) problems.push("deliver requirements but no deliverables");
   for (const d of dels) if (!d?.id || !d?.path) problems.push(`deliverable without id or path: ${JSON.stringify(d).slice(0, 80)}`);
   for (const p of Array.isArray(c.preserve) ? c.preserve : []) if (!p?.id || blank(p?.what)) problems.push("preserve entry without id or what");
+  // forge#4165: decision provenance is optional (contracts frozen before it stay valid) and checked when present.
+  if (c.decisions != null && !Array.isArray(c.decisions)) problems.push("decisions must be an array");
+  for (const k of Array.isArray(c.decisions) ? c.decisions : []) {
+    if (!k?.id || blank(k?.choice)) problems.push(`decision without id or choice: ${JSON.stringify(k ?? null).slice(0, 80)}`);
+    else if (!DECISION_SOURCES.includes(k?.source)) problems.push(`${k.id}: decision source must be one of ${DECISION_SOURCES.join("|")}`);
+  }
   if (!Array.isArray(c.validate) || !c.validate.length) problems.push("the contract names no validate[] commands");
   else for (const v of c.validate) if (!v?.id || blank(v?.command)) problems.push("validate entry without id or command");
+  if (repro) {
+    const t = c.repro_test;
+    if (t === "none") { if (blank(c.repro_test_reason)) problems.push(`repro_test "none" needs a one-line repro_test_reason`); }
+    else if (!t || typeof t !== "object" || Array.isArray(t) || blank(t.path) || blank(t.command)) problems.push(`this is a bug: repro_test must be {"path","id","command"} (a test that fails on the base and passes after the fix) or "none" with a repro_test_reason`);
+  }
   if (JSON.stringify(c).length > MAX_CONTRACT_CHARS) problems.push(`the contract is over ${MAX_CONTRACT_CHARS} characters; keep quotes to the requirement sentence and descriptions short`);
   return { ok: problems.length === 0, problems };
 }
@@ -97,7 +119,11 @@ export function applyAmendments(frozen, amendments, issueText = null) {
     const tag = JSON.stringify(a ?? null).slice(0, 100);
     if (blank(a?.why)) { problems.push(`amendment without why: ${tag}`); continue; }
     if (a.kind === "add-deliverable" && !blank(a.path)) {
-      if (!c.deliverables.some((d) => d.path === a.path)) c.deliverables.push({ id: a.id ?? `A${c.deliverables.length + 1}`, path: a.path, change: a.why, amended: true });
+      const have = c.deliverables.find((d) => d.path === a.path);
+      // An existing deliverable keeps its id and gains the why, so an amendment naming a package on an already-listed
+      // package.json declares the edge (forge#4159); before, it was reported as applied but changed nothing.
+      if (have) { have.change = have.change ? `${have.change}; ${a.why}` : a.why; have.amended = true; }
+      else c.deliverables.push({ id: a.id ?? `A${c.deliverables.length + 1}`, path: a.path, change: a.why, amended: true });
     } else if (a.kind === "add-requirement" && a.requirement?.id && !blank(a.requirement?.quote)) {
       if (c.requirements.some((r) => r.id === a.requirement.id)) { problems.push(`add-requirement reuses id ${a.requirement.id}`); continue; }
       if (issueText != null && !inIssue(a.requirement.quote, issueText)) { problems.push(`add-requirement ${a.requirement.id}: quote is not verbatim from the issue`); continue; }
@@ -118,30 +144,69 @@ export function applyAmendments(frozen, amendments, issueText = null) {
 
 /**
  * Deterministic checks before any reviewer tokens are spent: unauthorized files, failed or missing validation,
- * requirements not implemented, and deferrals without a tracking issue. Returns {ok, failures[]}.
+ * requirements not implemented, deferrals without a tracking issue, and unexempted hotspot growth. Returns {ok, failures[]}; each failure carries a
+ * `kind` (scope_creep, validate_missing, validate_failed, requirement_unimplemented, untracked_deferral, hotspot_growth, repro_red_green) so callers can
+ * tell the builder's own failed checks apart from bookkeeping gaps. `ciVerified` (#4167): the current head passed the
+ * engine's CI verification, so a validate id left to CI is not missing; a recorded non-zero exit still fails. `repro` (#4271): the repro_test red-green words, checked when given.
  */
-export function precheck({ contract, result, changedFiles, ignore = [] }) {
+export function precheck({ contract, result, changedFiles, ignore = [], ciVerified = false, hotspots = null, repro = null }) {
   const failures = [];
   const creep = changedFiles.filter((f) => !ignore.some((p) => f.startsWith(p)) && !authorizationOf(contract, f));
-  if (creep.length) failures.push({ code: C.CONFORMANCE_SCOPE_CREEP, detail: `changed outside the contract's deliverables: ${creep.join(", ")}` });
+  if (creep.length) failures.push({ code: C.CONFORMANCE_SCOPE_CREEP, kind: "scope_creep", detail: `changed outside the contract's deliverables: ${creep.join(", ")}` });
   const runs = Array.isArray(result?.validation) ? result.validation : [];
   for (const v of contract.validate ?? []) {
     const r = runs.find((x) => x?.id === v.id);
-    if (!r) failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, detail: `validate ${v.id} (\`${v.command}\`) has no recorded result` });
-    else if (r.exit !== 0) failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, detail: `validate ${v.id} failed (exit ${r.exit})` });
+    // #4167: a head the engine verified on CI covers validate ids the builder left to CI (no result, or ci:true without an exit)
+    const leftToCi = !r || (r.ci === true && r.exit === undefined);
+    if (ciVerified && leftToCi) continue;
+    if (leftToCi) failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, kind: "validate_missing", detail: `validate ${v.id} (\`${v.command}\`) has no recorded result` });
+    else if (r.exit !== 0) failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, kind: "validate_failed", detail: `validate ${v.id} failed (exit ${r.exit})` });
   }
   const st = Array.isArray(result?.requirements) ? result.requirements : [];
   for (const r of contract.requirements ?? []) {
     const s = st.find((x) => x?.id === r.id)?.status;
     if (TRACKED.includes(r.disposition)) continue; // typed deferrals are judged by the reviewer, then filed before the PR
     if (r.disposition === "deliver") {
-      if (s === "deferred" || s === "post-deploy") failures.push({ code: C.CONFORMANCE_UNTRACKED_DEFERRAL, detail: `${r.id} was contracted as deliver but reported "${s}" without a typed amendment` });
-      else if (s !== "implemented") failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, detail: `${r.id} reported "${s ?? "no status"}"` });
+      if (s === "deferred" || s === "post-deploy") failures.push({ code: C.CONFORMANCE_UNTRACKED_DEFERRAL, kind: "untracked_deferral", detail: `${r.id} was contracted as deliver but reported "${s}" without a typed amendment` });
+      else if (s !== "implemented") failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, kind: "requirement_unimplemented", detail: `${r.id} reported "${s ?? "no status"}"` });
     }
   }
+  failures.push(...hotspotGrowth({ contract, result, hotspots, changedFiles }));
+  if (repro) failures.push(...reproFailures(contract, repro));
   return { ok: failures.length === 0, failures };
 }
 
+/**
+ * #4271: the frozen repro_test's red-green proof ({base, head} words from scripts/acceptance-red-green.sh). Anything but
+ * HEAD=RAN BASE=FAILED fails; code conformance.unimplemented, so it blocks in shadow too and goes back to the builder.
+ */
+export function reproFailures(contract, { base, head } = {}) {
+  if (head === "RAN" && base === "FAILED") return [];
+  const t = contract?.repro_test ?? {};
+  const name = [t.path, t.id].filter((x) => !blank(x)).join(" ") || "repro_test";
+  return [{ code: C.CONFORMANCE_UNIMPLEMENTED, kind: "repro_red_green",
+    detail: `repro test ${name} (\`${t.command ?? ""}\`) must fail on the base and pass on head; got BASE=${base ?? "UNRUNNABLE"} HEAD=${head ?? "UNRUNNABLE"}` }];
+}
+
+const EXEMPT_RE = /hotspot-exempt:\s*\S/i;
+/**
+ * forge#4195: a changed file already over `file_lines` (not generated, vendored or glob-excluded) that grew by more
+ * than `growth_lines` since the base, with no `hotspot-exempt: <reason>` in a covering deliverable's change or an
+ * add-deliverable amendment's why. `hotspots` is scripts/hotspots.sh --base output; null or disabled checks nothing.
+ */
+export function hotspotGrowth({ contract, result, hotspots, changedFiles = [] }) {
+  if (!hotspots || hotspots.enabled === false || !Array.isArray(hotspots.files)) return [];
+  const limit = Number(hotspots.growth_lines) || 0, max = Number(hotspots.file_lines) || 0;
+  const changed = new Set(changedFiles.map(cleanPath));
+  const amends = Array.isArray(result?.amendments) ? result.amendments : [];
+  const exempt = (f) => (contract?.deliverables ?? []).some((d) => pathCovers(d.path, f) && EXEMPT_RE.test(String(d.change ?? "")))
+    || amends.some((a) => a?.kind === "add-deliverable" && pathCovers(a.path, f) && EXEMPT_RE.test(String(a.why ?? "")));
+  return hotspots.files
+    .filter((h) => h?.over && !h.excluded && Number(h.growth) > limit && changed.has(cleanPath(h.path)) && !exempt(h.path))
+    .map((h) => ({ code: C.MAINTENANCE_HOTSPOT_GROWTH, kind: "hotspot_growth",
+      detail: `${h.path} grew by ${h.growth} lines (now ${h.lines}, limit +${limit} over ${max}) without hotspot-exempt` }));
+}
+
 /** The reviewer's JSON object (a json fence first, then the outermost braces), or null. */
 export function parseReview(text) {
   const s = String(text ?? "");
@@ -153,52 +218,114 @@ export function parseReview(text) {
   return null;
 }
 
+/**
+ * A basename or path suffix in reviewer evidence, resolved to the one repo path it names (changed files first, then
+ * `repoFiles`). An exact match, an ambiguous name or an unknown name is returned unchanged.
+ */
+export function normalizeEvidencePath(path, { changedFiles = [], repoFiles = [], listed = null } = {}) {
+  const p = cleanPath(path);
+  if (listed) repoFiles = listed;
+  if (!p) return p;
+  for (const pool of [changedFiles, repoFiles]) {
+    const files = [...pool];
+    if (files.includes(p)) return p;
+    const hits = [...new Set(files.filter((f) => String(f).endsWith(`/${p}`)))];
+    if (hits.length === 1) return hits[0];
+    if (hits.length > 1) return p;
+  }
+  return p;
+}
+/**
+ * #4160: an evidence path the reviewer gave as a bare or partial name (`route.ts`, `pdf/route.ts`) resolves to the one
+ * changed file it names. Returns the repo path, or null when it is not a unique match.
+ */
+export function resolveEvidencePath(p, changedFiles = []) {
+  const n = normalizeEvidencePath(p, { changedFiles });
+  return n && changedFiles.includes(n) ? n : null;
+}
+/** The path:line in an evidence string, with the path normalized; null when there is none. */
+function evidenceOf(text, ctx) {
+  const m = EVIDENCE_RE.exec(String(text ?? ""));
+  return m ? { path: normalizeEvidencePath(m[1], ctx), line: m[2] } : null;
+}
+const reviewedFiles = (changedFiles, ignore) => changedFiles.filter((x) => !ignore.some((pre) => x.startsWith(pre)));
+
+/**
+ * The rows the engine can fill itself, so bookkeeping is never "incomplete": a scope row per changed file from the
+ * contract's own authorization ("none" when unauthorized, still scope creep), a preserve row per id as "unverified"
+ * (still preserve_violated), and implemented evidence rewritten to `path:line` with the repo path. Returns a new object.
+ */
+export function fillEngineRows(rv, { contract, changedFiles = [], repoFiles = [], ignore = [] }) {
+  if (!rv || typeof rv !== "object") return rv;
+  const out = { ...rv };
+  const scope = Array.isArray(rv.scope) ? [...rv.scope] : [];
+  for (const f of reviewedFiles(changedFiles, ignore)) if (!scope.some((s) => s?.file === f)) scope.push({ file: f, authorized_by: authorizationOf(contract, f) ?? "none", note: "row filled by the engine", filled: true });
+  out.scope = scope;
+  const pres = Array.isArray(rv.preserve) ? [...rv.preserve] : [];
+  for (const c of contract.preserve ?? []) if (!pres.some((x) => x?.id === c.id)) pres.push({ id: c.id, status: "unverified", note: "no row from the reviewer", filled: true });
+  out.preserve = pres;
+  if (Array.isArray(rv.requirements)) {
+    out.requirements = rv.requirements.map((r) => {
+      if (r?.status !== "implemented") return r;
+      const e = evidenceOf(r.evidence, { changedFiles, repoFiles });
+      return e ? { ...r, evidence: `${e.path}:${e.line}` } : r;
+    });
+  }
+  return out;
+}
+
 /** Row completeness: every contract requirement, preserve item and changed file has a well-formed row. */
-export function checkCompleteness(rv, { contract, changedFiles, issueText, pathExists = () => false, ignore = [] }) {
-  const p = [];
+export function checkCompleteness(rv, { contract, changedFiles, issueText, pathExists = () => false, ignore = [], repoFiles = [] }) {
+  const p = [], ids = new Set();
+  const miss = (id, msg) => { p.push(msg); ids.add(id); };
   const arr = (k) => (Array.isArray(rv?.[k]) ? rv[k] : null);
-  if (!["CONFORMS", "NONCONFORMING"].includes(rv?.verdict)) p.push("verdict must be CONFORMS or NONCONFORMING");
+  if (!["CONFORMS", "NONCONFORMING"].includes(rv?.verdict)) miss("verdict", "verdict must be CONFORMS or NONCONFORMING");
   const cov = arr("issue_coverage");
-  if (!cov?.length) p.push("issue_coverage is missing or empty");
+  if (!cov?.length) miss("issue_coverage", "issue_coverage is missing or empty");
   for (const c of cov ?? []) {
-    if (!COVER_STATUS.includes(c?.status)) p.push(`issue_coverage status invalid: ${c?.status}`);
-    if (!inIssue(c?.quote, issueText)) p.push(`issue_coverage quote is not verbatim from the issue: "${String(c?.quote ?? "").slice(0, 60)}"`);
+    if (!COVER_STATUS.includes(c?.status)) miss("issue_coverage", `issue_coverage status invalid: ${c?.status}`);
+    if (!inIssue(c?.quote, issueText)) miss("issue_coverage", `issue_coverage quote is not verbatim from the issue: "${String(c?.quote ?? "").slice(0, 60)}"`);
   }
   const reqs = arr("requirements");
   if (!reqs) p.push("requirements rows are missing");
   for (const r of contract.requirements) {
     const rows = (reqs ?? []).filter((x) => x?.id === r.id);
-    if (rows.length !== 1) { p.push(`requirement ${r.id} needs exactly one row (has ${rows.length})`); continue; }
+    if (rows.length !== 1) { miss(r.id, `requirement ${r.id} needs exactly one row (has ${rows.length})`); continue; }
     const row = rows[0];
-    if (!REQ_STATUS.includes(row.status)) { p.push(`${r.id}: status invalid: ${row.status}`); continue; }
-    if (TRACKED.includes(r.disposition) && typeof row.deferral_ok !== "boolean") p.push(`${r.id}: a ${r.disposition} requirement needs deferral_ok true|false (is deferring it justified?)`);
+    if (!REQ_STATUS.includes(row.status)) { miss(r.id, `${r.id}: status invalid: ${row.status}`); continue; }
+    if (TRACKED.includes(r.disposition) && typeof row.deferral_ok !== "boolean") miss(r.id, `${r.id}: a ${r.disposition} requirement needs deferral_ok true|false (is deferring it justified?)`);
     if (row.status === "implemented") {
-      const m = EVIDENCE_RE.exec(String(row.evidence ?? ""));
-      if (!m) p.push(`${r.id}: implemented needs path:line evidence`);
-      else if (!changedFiles.includes(m[1]) && !pathExists(m[1])) p.push(`${r.id}: evidence path ${m[1]} does not exist`);
-      if (blank(row.validated_by)) p.push(`${r.id}: implemented needs validated_by (a validate id or test)`);
+      const e = evidenceOf(row.evidence, { changedFiles, repoFiles });
+      if (!e) miss(r.id, `${r.id}: implemented needs path:line evidence`);
+      else if (!changedFiles.includes(e.path) && !pathExists(e.path)) miss(r.id, `${r.id}: evidence path ${e.path} does not exist`);
+      if (blank(row.validated_by)) miss(r.id, `${r.id}: implemented needs validated_by (a validate id or test)`);
     }
   }
   const scope = arr("scope");
-  if (!scope) p.push("scope rows are missing");
-  for (const f of changedFiles.filter((x) => !ignore.some((pre) => x.startsWith(pre)))) if (!(scope ?? []).some((s) => s?.file === f)) p.push(`changed file ${f} has no scope row`);
+  if (!scope) miss("scope", "scope rows are missing");
+  // #4160: a file the contract authorizes (deliverable, test, incidental) is already settled by the deterministic precheck;
+  // a row is required only for the files it could not authorize (decide() fills those as "none"). A given row is still judged.
+  for (const f of reviewedFiles(changedFiles, ignore).filter((x) => !authorizationOf(contract, x))) if (!(scope ?? []).some((s) => s?.file === f)) miss(f, `changed file ${f} has no scope row`);
   const pres = arr("preserve") ?? [];
   for (const c of contract.preserve ?? []) {
     const row = pres.find((x) => x?.id === c.id);
-    if (!row || !PRESERVE_STATUS.includes(row.status)) p.push(`preserve ${c.id} needs a row with status ${PRESERVE_STATUS.join("|")}`);
+    if (!row || !PRESERVE_STATUS.includes(row.status)) miss(c.id, `preserve ${c.id} needs a row with status ${PRESERVE_STATUS.join("|")}`);
   }
-  if (rv && rv.regressions != null && !Array.isArray(rv.regressions)) p.push("regressions must be an array");
-  return { complete: p.length === 0, problems: p };
+  if (rv && rv.regressions != null && !Array.isArray(rv.regressions)) miss("regressions", "regressions must be an array");
+  if (!reqs) for (const r of contract.requirements) ids.add(r.id);
+  return { complete: p.length === 0, problems: p, missing: [...ids] };
 }
 
 /**
- * The engine's decision from the reviewer's rows. state: conforms | nonconforming | review.unparseable | review.incomplete.
- * failures[] are {code, detail}; `inconsistent` marks a CONFORMS verdict whose rows fail.
+ * The engine's decision from the reviewer's rows. state: conforms | nonconforming | review.unparseable | review.incomplete
+ * | review.inconsistent. failures[] are {code, detail}; `inconsistent` marks a CONFORMS verdict whose rows fail;
+ * `missing` lists the ids (or sections) a targeted re-ask must fill; `review` is the reply with the engine-filled rows.
  */
-export function decide(rv, ctx) {
-  if (!rv) return { state: "review.unparseable", failures: [{ code: C.REVIEW_NO_VERDICT, detail: "no JSON object in the reviewer reply" }] };
+export function decide(raw, ctx) {
+  if (!raw) return { state: "review.unparseable", failures: [{ code: C.REVIEW_NO_VERDICT, detail: "no JSON object in the reviewer reply" }] };
+  const rv = fillEngineRows(raw, ctx);
   const comp = checkCompleteness(rv, ctx);
-  if (!comp.complete) return { state: "review.incomplete", failures: comp.problems.map((d) => ({ code: C.REVIEW_INCOMPLETE, detail: d })) };
+  if (!comp.complete) return { state: "review.incomplete", failures: comp.problems.map((d) => ({ code: C.REVIEW_INCOMPLETE, detail: d })), missing: comp.missing, review: rv };
   const f = [];
   for (const c of rv.issue_coverage) if (c.status !== "covered") f.push({ code: C.CONFORMANCE_OMISSION, detail: `issue requirement ${c.status}: "${c.quote}"${c.note ? ` (${c.note})` : ""}` });
   for (const r of ctx.contract.requirements) {
@@ -216,10 +343,54 @@ export function decide(rv, ctx) {
   }
   for (const p of rv.preserve ?? []) if (p.status !== "intact") f.push({ code: C.CONFORMANCE_PRESERVE_VIOLATED, detail: `${p.id} ${p.status}${p.evidence ? ` (${p.evidence})` : ""}${p.note ? `: ${p.note}` : ""}` });
   for (const r of rv.regressions ?? []) f.push({ code: C.CONFORMANCE_REGRESSION, detail: `${r?.at ?? "?"}: ${r?.failure ?? ""}` });
-  if (f.length) return { state: "nonconforming", failures: f, inconsistent: rv.verdict === "CONFORMS" };
+  if (f.length) return { state: "nonconforming", failures: f, inconsistent: rv.verdict === "CONFORMS", review: rv };
   // A NONCONFORMING verdict with every row passing gives the builder nothing to fix: re-ask the reviewer.
-  if (rv.verdict !== "CONFORMS") return { state: "review.inconsistent", failures: [{ code: C.REVIEW_INCONSISTENT, detail: "verdict NONCONFORMING with no failing row" }] };
-  return { state: "conforms", failures: [] };
+  if (rv.verdict !== "CONFORMS") return { state: "review.inconsistent", failures: [{ code: C.REVIEW_INCONSISTENT, detail: "verdict NONCONFORMING with no failing row" }], missing: ["verdict"], review: rv };
+  return { state: "conforms", failures: [], review: rv };
+}
+
+/** The ids (or sections) a targeted re-ask must fill: requirement ids without a valid row, issue_coverage problems, ...; [] when complete. */
+export function missingIds(rv, ctx) {
+  if (!rv || typeof rv !== "object") return [];
+  return checkCompleteness(fillEngineRows(rv, ctx), ctx).missing;
+}
+
+/**
+ * The reviewer's first reply with the rows of a targeted re-ask applied: a repair row replaces the row with the same id
+ * (scope: file), issue_coverage is replaced when the repair sends any, verdict and summary follow the repair when valid.
+ */
+export function mergeReviewRows(first, repair) {
+  if (!first || typeof first !== "object") return repair ?? null;
+  if (!repair || typeof repair !== "object") return first;
+  const out = { ...first };
+  for (const [k, key] of [["requirements", "id"], ["preserve", "id"], ["scope", "file"]]) {
+    if (!Array.isArray(repair[k])) continue;
+    const rows = Array.isArray(first[k]) ? first[k].filter((x) => !x?.filled) : [];
+    for (const r of repair[k]) { const i = rows.findIndex((x) => x?.[key] === r?.[key]); if (i >= 0) rows[i] = r; else rows.push(r); }
+    out[k] = rows;
+  }
+  if (Array.isArray(repair.issue_coverage) && repair.issue_coverage.length) out.issue_coverage = repair.issue_coverage;
+  if (Array.isArray(repair.regressions)) out.regressions = [...(Array.isArray(first.regressions) ? first.regressions : []), ...repair.regressions];
+  if (["CONFORMS", "NONCONFORMING"].includes(repair.verdict)) { out.verdict = repair.verdict; if (repair.summary) out.summary = repair.summary; }
+  return out;
+}
+
+/**
+ * #4160: the rows the engine requires, pre-filled with every id so the reviewer fills statuses instead of composing rows:
+ * one requirement row per R id (status empty), one preserve row per P id ("unverified" until checked), one scope row per
+ * changed file pre-filled with the engine's authorization, and one issue_coverage row per contract quote (the reviewer adds
+ * any the contract missed). Called as (contract, changedFiles, ignore) or ({contract, changedFiles, ignore}).
+ */
+export function reviewSkeleton(contract, changedFiles = [], ignore = []) {
+  if (contract && !Array.isArray(contract.requirements) && "contract" in contract) ({ contract, changedFiles = [], ignore = [] } = contract);
+  const reqs = contract?.requirements ?? [];
+  return {
+    issue_coverage: reqs.map((r) => ({ quote: r.quote, contract_ids: [r.id], status: "" })),
+    requirements: reqs.map((r) => ({ id: r.id, status: "", evidence: "", validated_by: "", ...(TRACKED.includes(r.disposition) ? { deferral_ok: null } : {}), note: "" })),
+    scope: reviewedFiles(changedFiles, ignore).map((f) => ({ file: f, authorized_by: authorizationOf(contract ?? {}, f) ?? "none", note: "" })),
+    preserve: (contract?.preserve ?? []).map((x) => ({ id: x.id, status: "unverified", evidence: "" })),
+    regressions: [], verdict: "", summary: "",
+  };
 }
 
 /** Requirements the reviewer accepted as deferred or post-deploy that still need a tracking issue. */
@@ -236,3 +407,30 @@ export function followupItems(reqs) {
   const flat = (s) => String(s ?? "").replace(/[\t\r\n`]+/g, " ").replace(/\s+/g, " ").trim();
   return reqs.map((r) => ({ id: r.id, key: flat(`${r.id}: ${r.quote}`).slice(0, 240), why: flat(`${r.disposition}: ${r.why ?? ""}`).slice(0, 400) }));
 }
+
+/**
+ * forge#4159: package.json edges between workspace packages (scripts/structure-delta.sh `package_edges_added`) that
+ * the contract does not name. Named = a deliverable covering the edge's manifest whose `change` names the target
+ * package (an add-deliverable amendment counts: its change is the why). A null or `{}` delta names nothing to check.
+ */
+export function unnamedEdges(contract, delta) {
+  const edges = Array.isArray(delta?.package_edges_added) ? delta.package_edges_added : [];
+  const dels = contract?.deliverables ?? [];
+  return edges.filter((e) => e?.manifest && e?.to && !dels.some((d) => pathCovers(d.path, e.manifest) && String(d.change ?? "").includes(e.to)));
+}
+
+/**
+ * forge#4159: the one report-only line for the existing reviewer prompt, or "" when there is no import-pair growth
+ * and no boundary-config loosening. Never blocks; adds no reviewer run.
+ */
+export function structureNote(delta) {
+  const grow = (Array.isArray(delta?.import_pairs) ? delta.import_pairs : []).filter((p) => p?.files_added > 0);
+  const b = delta?.boundary_config_changed;
+  const loosened = Boolean(b?.loosens);
+  if (!grow.length && !loosened) return "";
+  const pairs = grow.map((p) => `${p.files_added} value import${p.files_added === 1 ? "" : "s"} ${p.from}→${p.to}`).join(", ");
+  const files = (Array.isArray(b?.files) ? b.files : []).join(", ");
+  const config = loosened ? `the repo's boundary config was loosened in this PR (${files})` : "the repo's boundary config allows it";
+  const s = grow.length ? `this PR adds ${pairs} (files); ${config}` : `this PR loosens the repo's boundary config (${files})`;
+  return `Structure (report only): ${s}; flag only if the contract or the architecture doc says otherwise.`.replace(/[\r\n]+/g, " ");
+}

package/bin/lean/conformance.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 { validateContract, applyAmendments, precheck, parseReview, checkCompleteness, decide, closePlan, followupItems, inIssue, isTestPath } from "./conformance.mjs";
+import { validateContract, applyAmendments, precheck, hotspotGrowth, reproFailures, isBugIssue, parseReview, checkCompleteness, decide, closePlan, followupItems, inIssue, isTestPath, normalizeEvidencePath, mergeReviewRows, reviewSkeleton, missingIds, resolveEvidencePath } from "./conformance.mjs";
 
 const ISSUE = "## Requirements\n1. The scrape route must release the spend reservation on 429.\n2. The search route must release the spend reservation on 429.\n\n- [ ] Billing pricing is unchanged.";
 const Q1 = "The scrape route must release the spend reservation on 429.";
@@ -95,10 +95,84 @@ describe("conformance review: the engine computes the verdict from complete rows
     assert.ok(d.failures.every((f) => f.code === "review.incomplete"));
   });
   it("no JSON is unparseable", () => { assert.equal(parseReview("LGTM"), null); assert.equal(decide(null, ctx).state, "review.unparseable"); });
-  it("incomplete: missing requirement row, missing scope row for a changed file, missing preserve row", () => {
-    assert.equal(decide({ ...good, requirements: good.requirements.slice(1) }, ctx).state, "review.incomplete");
-    assert.equal(decide({ ...good, scope: good.scope.slice(1) }, ctx).state, "review.incomplete");
-    assert.equal(decide({ ...good, preserve: [] }, ctx).state, "review.incomplete");
+  it("incomplete: a missing requirement row (only the reviewer can judge it), and missing lists that id for the re-ask", () => {
+    const d = decide({ ...good, requirements: good.requirements.slice(1) }, ctx);
+    assert.equal(d.state, "review.incomplete"); assert.deepEqual(d.missing, ["R1"]);
+  });
+  it("#4160 missing scope and preserve rows are filled by the engine: complete, with the honest verdict", () => {
+    assert.equal(decide({ ...good, scope: good.scope.slice(1) }, ctx).state, "conforms", "an authorized file needs no reviewer row");
+    const creep = decide({ ...good }, { ...ctx, changedFiles: [...files, "src/pricing.js"] });
+    assert.deepEqual(codes(creep), ["conformance.scope_creep"], "an unauthorized file without a row is still creep");
+    const noPres = decide({ ...good, preserve: [] }, ctx);
+    assert.deepEqual(codes(noPres), ["conformance.preserve_violated"], "a missing preserve row is unverified, not incomplete");
+    assert.match(noPres.failures[0].detail, /P1 unverified/);
+    assert.equal(decide({ ...good, scope: undefined, preserve: undefined }, ctx).state, "nonconforming");
+  });
+  it("#4160 basename and wrapped evidence are normalized to the repo path; an ambiguous or unknown name is still incomplete", () => {
+    assert.equal(decide(row("R1", { evidence: "scrape.js:7" }), ctx).state, "conforms");
+    assert.equal(decide(row("R1", { evidence: "see `src/scrape.js:7` (guard)" }), ctx).state, "conforms");
+    assert.equal(decide(row("R1", { evidence: "billing.js:1" }), { ...ctx, repoFiles: ["src/billing.js"], pathExists: (p) => p === "src/billing.js" }).state, "conforms");
+    assert.equal(decide(row("R1", { evidence: "nope.js:3" }), ctx).state, "review.incomplete");
+    assert.equal(normalizeEvidencePath("route.ts", { changedFiles: ["app/a/route.ts", "app/b/route.ts"] }), "route.ts", "ambiguous stays as is");
+    assert.equal(normalizeEvidencePath("b/route.ts", { changedFiles: ["app/a/route.ts", "app/b/route.ts"] }), "app/b/route.ts");
+    assert.equal(decide(row("R1", { evidence: "scrape.js:7" }), ctx).review.requirements[0].evidence, "src/scrape.js:7");
+  });
+  it("#4160 a targeted re-ask merges by id: the repair rows complete the first reply", () => {
+    const first = { ...good, requirements: [good.requirements[1]], preserve: [] };
+    const d1 = decide(first, ctx);
+    assert.equal(d1.state, "review.incomplete"); assert.deepEqual(d1.missing, ["R1"]);
+    const merged = mergeReviewRows(first, { requirements: [good.requirements[0]], preserve: good.preserve });
+    assert.equal(decide(merged, ctx).state, "conforms");
+    assert.equal(mergeReviewRows(first, null), first, "an unparseable repair keeps the first reply");
+    assert.equal(decide(mergeReviewRows({ ...good, verdict: "NONCONFORMING" }, { verdict: "CONFORMS" }), ctx).state, "conforms");
+  });
+  it("#4160 the skeleton has one row per requirement, preserve id and changed file, scope pre-filled by the engine", () => {
+    const s = reviewSkeleton(C, [...files, ".forge-lean/x", "src/pricing.js"], [".forge-lean/"]);
+    assert.deepEqual(s.requirements.map((r) => r.id), ["R1", "R2"]);
+    assert.deepEqual(s.preserve.map((r) => r.id), ["P1"]);
+    assert.deepEqual(s.scope.map((r) => [r.file, r.authorized_by]), [["src/scrape.js", "D1"], ["src/search.js", "D2"], ["test/leak.test.js", "test"], ["src/pricing.js", "none"]]);
+    assert.deepEqual(s.issue_coverage.map((r) => r.quote), [Q1, Q2]);
+    assert.ok(s.requirements.every((r) => r.status === ""), "requirement status is left for the reviewer");
+    assert.ok(s.preserve.every((r) => r.status === "unverified"), "preserve starts unverified");
+  });
+  it("#4160 missingIds lists only what a targeted re-ask must fill", () => {
+    assert.deepEqual(missingIds(good, ctx), []);
+    assert.deepEqual(missingIds({ ...good, requirements: [good.requirements[1]], preserve: [], scope: [] }, ctx), ["R1"], "engine-filled preserve/scope rows are not asked for");
+    assert.deepEqual(missingIds({ ...good, issue_coverage: [] }, ctx), ["issue_coverage"]);
+    assert.equal(normalizeEvidencePath("billing.js", { listed: new Set(["src/billing.js"]) }), "src/billing.js", "listed is the repo file list");
+  });
+  it("#4160 checkCompleteness on the raw reply still lists a missing scope row for an unauthorized changed file (decide fills it as creep)", () => {
+    const extra = { ...ctx, changedFiles: [...files, "src/billing.js"] };
+    assert.equal(checkCompleteness(good, extra).problems.includes("changed file src/billing.js has no scope row"), true);
+  });
+  it("#4160: a changed file the contract already authorizes (deliverable, test, incidental) needs no scope row", () => {
+    assert.equal(decide({ ...good, scope: [] }, ctx).state, "conforms");
+    assert.equal(checkCompleteness({ ...good, scope: [] }, { ...ctx, changedFiles: [...files, "CHANGELOG.md"] }).complete, true);
+  });
+  it("#4160: a scope row the reviewer gives for an authorized file is still judged (none on a deliverable is creep)", () => {
+    const s = good.scope.map((x) => (x.file === "src/scrape.js" ? { ...x, authorized_by: "none", note: "unrelated rewrite" } : x));
+    assert.equal(decide({ ...good, scope: s }, ctx).state, "nonconforming");
+  });
+  it("#4160: evidence given as a bare or partial file name resolves to the one changed file it names", () => {
+    assert.equal(resolveEvidencePath("scrape.js", files), "src/scrape.js");
+    assert.equal(resolveEvidencePath("./src/scrape.js", files), "src/scrape.js");
+    assert.equal(resolveEvidencePath("leak.test.js", files), "test/leak.test.js");
+    assert.equal(resolveEvidencePath("x.js", ["a/x.js", "b/x.js"]), null, "ambiguous");
+    assert.equal(resolveEvidencePath("nope.js", files), null);
+    assert.equal(decide(row("R1", { evidence: "scrape.js:4" }), ctx).state, "conforms");
+  });
+  it("#4160: reviewSkeleton (object form) lists every required row, scope rows pre-filled with the engine's authorization", () => {
+    const k = { ...C, requirements: [...C.requirements, { id: "R9", quote: "Billing pricing is unchanged.", disposition: "defer", why: "w" }] };
+    const sk = reviewSkeleton({ contract: k, changedFiles: [...files, "src/billing.js", ".forge-lean/x"], ignore: [".forge-lean/"] });
+    assert.deepEqual(sk.requirements.map((r) => r.id), k.requirements.map((r) => r.id));
+    assert.equal(sk.requirements.find((r) => r.id === "R9").deferral_ok, null);
+    assert.ok(!("deferral_ok" in sk.requirements[0]));
+    assert.deepEqual(sk.preserve.map((p) => p.id), (k.preserve ?? []).map((p) => p.id));
+    assert.deepEqual(sk.scope.map((s) => [s.file, s.authorized_by]), [...files.map((f) => [f, f.startsWith("test/") ? "test" : f === "src/scrape.js" ? "D1" : "D2"]), ["src/billing.js", "none"]]);
+    assert.deepEqual(sk.issue_coverage.map((c) => c.quote), k.requirements.map((r) => r.quote));
+    assert.ok(sk.issue_coverage.every((c) => inIssue(c.quote, ISSUE)), "seeded quotes pass the verbatim check");
+    assert.ok([...sk.requirements, ...sk.issue_coverage].every((r) => r.status === ""), "no requirement or coverage status is pre-judged");
+    assert.ok(sk.preserve.every((p) => p.status === "unverified"), "preserve starts unverified");
   });
   it("incomplete: implemented without path:line, with evidence in a nonexistent file, or without validation", () => {
     assert.equal(decide(row("R1", { evidence: "looks fine" }), ctx).state, "review.incomplete");
@@ -161,3 +235,67 @@ describe("close plan and follow-up items", () => {
     assert.equal(i.key, "R2: a b c"); assert.equal(i.why, "defer: x y"); assert.doesNotMatch(i.key + i.why, /[\t\n`]/);
   });
 });
+
+describe("hotspot growth precheck (forge#4195)", () => {
+  const H = (o = {}) => ({ path: "src/scrape.js", lines: 2600, commits_90d: 30, hotspot: 78000, over: true, excluded: false, base_lines: 2400, growth: 200, ...o });
+  const hs = (fs, o = {}) => ({ enabled: true, file_lines: 2000, growth_lines: 150, files: fs, ...o });
+  const result = { validation: [{ id: "V1", exit: 0 }], requirements: [{ id: "R1", status: "implemented" }, { id: "R2", status: "implemented" }] };
+  const run = (hotspots, contract = C, r = result) => precheck({ contract, result: r, changedFiles: files, hotspots });
+
+  it("an over-threshold file grown past growth_lines fails with maintenance.hotspot_growth", () => {
+    const pc = run(hs([H()]));
+    assert.equal(pc.ok, false);
+    assert.deepEqual(pc.failures.map((f) => [f.code, f.kind]), [["maintenance.hotspot_growth", "hotspot_growth"]]);
+    assert.match(pc.failures[0].detail, /^src\/scrape\.js grew by 200 lines \(now 2600, limit \+150 over 2000\) without hotspot-exempt$/);
+  });
+
+  it("within the limit, under the threshold, excluded, unchanged, disabled or no facts: no failure", () => {
+    for (const h of [hs([H({ growth: 150 })]), hs([H({ over: false, lines: 1900 })]), hs([H({ excluded: true })]), hs([H({ path: "src/other.js" })]),
+      hs([H()], { enabled: false }), hs([H({ growth: null })]), null, undefined, {}]) assert.equal(run(h).ok, true, JSON.stringify(h));
+    assert.deepEqual(precheck({ contract: C, result, changedFiles: files }), run(null), "callers without hotspots are unchanged");
+  });
+
+  it("hotspot-exempt: <reason> in a covering deliverable's change or an add-deliverable amendment's why exempts the file", () => {
+    const withChange = (change) => ({ ...C, deliverables: [{ id: "D1", path: "src/scrape.js", change }, C.deliverables[1]] });
+    assert.equal(run(hs([H()]), withChange("route fix; Hotspot-Exempt: the handler table must stay in one file")).ok, true);
+    assert.equal(run(hs([H()]), withChange("hotspot-exempt:   ")).ok, false, "an empty reason does not exempt");
+    assert.equal(run(hs([H()]), { ...C, deliverables: [{ id: "D1", path: "src/", change: "hotspot-exempt: generated routes" }, C.deliverables[1]] }).ok, true, "a covering directory deliverable");
+    const amended = { ...result, amendments: [{ kind: "add-deliverable", path: "src/scrape.js", why: "hotspot-exempt: one-off migration table" }] };
+    assert.equal(run(hs([H()]), C, amended).ok, true);
+    assert.equal(run(hs([H(), H({ path: "src/search.js" })]), withChange("hotspot-exempt: ok")).failures.length, 1, "the exemption covers only its own file");
+    assert.equal(hotspotGrowth({ contract: C, hotspots: hs([H()]), changedFiles: ["./src/scrape.js"] }).length, 1);
+  });
+});
+
+describe("repro_test on bug lanes (#4271)", () => {
+  const res = { requirements: [{ id: "R1", status: "implemented" }, { id: "R2", status: "implemented" }], validation: [{ id: "V1", exit: 0 }] };
+  const RT = { path: "test/leak.test.js", id: "releases on 429", command: "node --test test/leak.test.js" };
+  it("isBugIssue reads bug and type:bug labels, as names or {name}", () => {
+    assert.equal(isBugIssue([{ name: "bug" }]), true);
+    assert.equal(isBugIssue(["P2", "type:bug"]), true);
+    assert.equal(isBugIssue([{ name: "feature" }, "debug"]), false);
+    assert.equal(isBugIssue(null), false);
+  });
+  it("a testable bug needs repro_test {path, command}; a non-testable one records none with a reason", () => {
+    assert.deepEqual(validateContract({ ...C, repro_test: RT }, ISSUE, { repro: true }), { ok: true, problems: [] });
+    assert.deepEqual(validateContract({ ...C, repro_test: "none", repro_test_reason: "spec-only change" }, ISSUE, { repro: true }), { ok: true, problems: [] });
+    assert.match(validateContract(C, ISSUE, { repro: true }).problems.join(), /repro_test must be/);
+    assert.match(validateContract({ ...C, repro_test: { path: "test/x.js" } }, ISSUE, { repro: true }).problems.join(), /repro_test must be/);
+    assert.match(validateContract({ ...C, repro_test: "none" }, ISSUE, { repro: true }).problems.join(), /repro_test_reason/);
+  });
+  it("red on base and green on head passes; anything else fails the precheck as conformance.unimplemented", () => {
+    const k = { ...C, repro_test: RT };
+    assert.deepEqual(precheck({ contract: k, result: res, changedFiles: files, repro: { base: "FAILED", head: "RAN" } }), { ok: true, failures: [] });
+    for (const repro of [{ base: "RAN", head: "RAN" }, { base: "SKIPPED", head: "FAILED" }, { base: "UNRUNNABLE", head: "RAN" }, { base: "UNRUNNABLE", head: "UNRUNNABLE" }]) {
+      const pc = precheck({ contract: k, result: res, changedFiles: files, repro });
+      assert.deepEqual(pc.failures.map((f) => [f.code, f.kind]), [["conformance.unimplemented", "repro_red_green"]], JSON.stringify(repro));
+      assert.match(pc.failures[0].detail, new RegExp(`BASE=${repro.base} HEAD=${repro.head}`));
+    }
+    assert.match(reproFailures(k, {})[0].detail, /test\/leak\.test\.js releases on 429.*BASE=UNRUNNABLE HEAD=UNRUNNABLE/);
+  });
+  it("off (no repro option) is today's contract check and precheck exactly", () => {
+    assert.deepEqual(validateContract(C, ISSUE), validateContract(C, ISSUE, { repro: false }));
+    assert.deepEqual(validateContract(C, ISSUE), { ok: true, problems: [] });
+    assert.deepEqual(precheck({ contract: C, result: res, changedFiles: files }), precheck({ contract: C, result: res, changedFiles: files, repro: null }));
+  });
+});

package/bin/lean/credentials.mjs

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Credential lookup for sandbox providers (#4254): the env first, then the OS keychain under service `forgedock`
+ * (Linux `secret-tool`, macOS `security`). A value is returned to the caller only; it is never logged, and a failed
+ * lookup is `null`, never an error carrying the value or the keychain's output.
+ */
+import { execFileSync } from "node:child_process";
+
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** `security`/`secret-tool` lookup of `name` under service `forgedock`; null when absent, unsupported or failing. */
+export function defaultKeychain(name, platform = process.platform) {
+  const argv = platform === "darwin" ? ["security", ["find-generic-password", "-s", "forgedock", "-a", name, "-w"]]
+    : platform === "linux" ? ["secret-tool", ["lookup", "service", "forgedock", "account", name]] : null;
+  if (!argv) return null;
+  try {
+    const out = execFileSync(argv[0], argv[1], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 10000 });
+    return out.replace(/\r?\n$/, "") || null;
+  } catch { return null; }
+}
+
+/** `env[name]` when non-empty, else the keychain entry `name`, else null. */
+export function resolveCredential(name, { env = process.env, keychain = defaultKeychain, platform = process.platform } = {}) {
+  if (!name || !NAME_RE.test(String(name))) return null;
+  const v = env?.[name];
+  if (v !== undefined && v !== null && String(v) !== "") return String(v);
+  try { const k = keychain(String(name), platform); return k === undefined || k === null || String(k) === "" ? null : String(k); } catch { return null; }
+}