forgedock 1.35.0 → 1.37.0

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, hotspotGrowth, reproFailures, isBugIssue, parseReview, checkCompleteness, decide, closePlan, isInvestigation, formatShadowSummary, followupItems, inIssue, isTestPath, normalizeEvidencePath, mergeReviewRows, reviewSkeleton, missingIds, resolveEvidencePath, movingBaseDiff, scopeText, evidencePathLine, evidencePathOnly, explainFailures, missingTool, repoTracks, tmpdirInputs, isScopeCheck, isPureScopeCheck, dropScopeValidates, tagOutOfBand, outOfBandRequirements, isOutOfBand, followupMap, VERIFY_MODES, OUT_OF_BAND_RE } from "./conformance.mjs";
+import { validateContract, applyAmendments, precheck, hotspotGrowth, reproFailures, isBugIssue, parseReview, checkCompleteness, decide, closePlan, isInvestigation, formatShadowSummary, followupItems, inIssue, isTestPath, normalizeEvidencePath, mergeReviewRows, reviewSkeleton, missingIds, resolveEvidencePath, movingBaseDiff, scopeText, evidencePathLine, evidencePathOnly, explainFailures, missingTool, repoTracks, tmpdirInputs, isScopeCheck, isPureScopeCheck, dropScopeValidates, tagOutOfBand, outOfBandRequirements, isOutOfBand, followupMap, VERIFY_MODES, OUT_OF_BAND_RE, FOLLOWUP_CLASSES, followupClass, BUCKETS, bucketKind, bucketProblems, bucketTally, isE2eCommand, e2eVerified } 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.";
@@ -60,6 +60,21 @@ describe("amendments", () => {
   });
 });
 
+describe("#4655 multi-requirement amendment references", () => {
+  it("R1/R2, 'R1, R2' and an en-dash range split into one applied row per id", () => {
+    for (const requirement of ["R1/R2", "R1, R2", "R1\u2013R2", "R1 and R2"]) {
+      const a = applyAmendments(C, [{ kind: "defer", requirement, why: "w" }]);
+      assert.deepEqual(a.problems, [], requirement);
+      assert.deepEqual(a.toTrack.map((r) => r.id).sort(), ["R1", "R2"], requirement);
+      assert.deepEqual(a.applied.map((x) => x.target), ["R1", "R2"], requirement);
+    }
+  });
+  it("an unknown id inside a list is still a problem; scope-note stays an unknown kind", () => {
+    assert.match(applyAmendments(C, [{ kind: "defer", requirement: "R1/R9", why: "w" }]).problems[0], /unknown requirement R9/);
+    assert.match(applyAmendments(C, [{ kind: "scope-note", requirement: "R1", why: "w" }]).problems[0], /unknown kind 'scope-note'; valid kinds are/);
+  });
+});
+
 describe("#4574 amendment slips", () => {
   it("type for kind, amend-requirement and limitation apply as defer; an R# id fills requirement", () => {
     const a = applyAmendments(C, [{ kind: "amend-requirement", id: "R2", why: "stored hashed" }, { id: "A1", requirement: "R1", type: "limitation", why: "plugin limit" }]);
@@ -115,6 +130,11 @@ describe("precheck (deterministic, no reviewer)", () => {
     const failed = precheck({ contract: C2, result: { ...res, validation: [{ id: "V1", exit: 1 }, { id: "V2", ci: true }, { id: "V3", exit: 0 }] }, changedFiles: files, ciVerified: true });
     assert.deepEqual(failed.failures.map((f) => f.kind), ["validate_failed"]); assert.deepEqual(failed.ciCovered, ["V2"]);
   });
+  it("#4708 a validate row carried forward across a CI fix round counts as recorded; a row absent outside a CI-verified head still fails", () => {
+    const carried = precheck({ contract: C, result: { ...res, validation: [{ id: "V1", exit: 0, carried: true }] }, changedFiles: files });
+    assert.deepEqual(codes(carried), []);
+    assert.deepEqual(precheck({ contract: C, result: { ...res, validation: [] }, changedFiles: files }).failures.map((f) => f.kind), ["validate_missing"]);
+  });
   it("#4323 missingTool: commands, python and node modules; paths, relative and repo-tracked names are not the environment", () => {
     assert.deepEqual(missingTool({ rc: 127, output: "sh: 1: jq: not found" }), { tool: "jq", kind: "command" });
     assert.deepEqual(missingTool({ rc: 127, output: "" }, { command: "uv run pytest -q" }), { tool: "uv", kind: "command" });
@@ -670,3 +690,130 @@ describe("#4594 amend-requirement", () => {
     assert.match(explainFailures([{ code: "x", detail: "R1 partial" }], c)[0].detail, /amended to "regenerate and reveal/);
   });
 });
+
+describe("post-deploy check ids (#4626)", () => {
+  const pd = (extra = {}) => ({ ...C, requirements: [{ id: "R1", quote: Q1, disposition: "post-deploy", why: "needs prod", ...extra }, C.requirements[1]] });
+  it("validateContract: a post-deploy requirement needs a well-formed check id", () => {
+    assert.ok(validateContract(pd(), ISSUE).problems.some((p) => /post-deploy needs a check id/.test(p)));
+    assert.ok(validateContract(pd({ check: "Bad Id" }), ISSUE).problems.some((p) => /post-deploy needs a check id/.test(p)));
+    assert.ok(!validateContract(pd({ check: "login-smoke" }), ISSUE).problems.some((p) => /check id/.test(p)));
+  });
+  it("applyAmendments: a post-deploy amendment needs a check id", () => {
+    const bad = applyAmendments(C, [{ kind: "post-deploy", requirement: "R1", why: "w" }], ISSUE);
+    assert.ok(bad.problems.some((p) => /needs a check id/.test(p)));
+    const ok = applyAmendments(C, [{ kind: "post-deploy", requirement: "R1", why: "w", check: "login-smoke" }], ISSUE);
+    assert.equal(ok.contract.requirements[0].check, "login-smoke");
+  });
+  it("precheck: a check id on neither branch is unimplemented; null checkIds skips the rule", () => {
+    const res = { requirements: [{ id: "R1", status: "post-deploy" }, { id: "R2", status: "implemented" }], validation: [{ id: "V1", exit: 0 }] };
+    const c = pd({ check: "login-smoke" });
+    assert.ok(precheck({ contract: c, result: res, changedFiles: files, checkIds: new Set() }).failures.some((f) => f.kind === "check_unknown"));
+    assert.ok(!precheck({ contract: c, result: res, changedFiles: files, checkIds: new Set(["login-smoke"]) }).failures.some((f) => f.kind === "check_unknown"));
+    assert.ok(!precheck({ contract: c, result: res, changedFiles: files }).failures.some((f) => f.kind === "check_unknown"));
+  });
+  it("#4664 followupItems carries the follow-up class; validateContract rejects an unknown class", () => {
+    const cls = (r) => followupItems([{ id: "R1", quote: Q1, why: "w", ...r }])[0].class;
+    assert.equal(cls({ disposition: "defer" }), "engineering");
+    assert.equal(cls({ disposition: "post-deploy", check: "x" }), "post-deploy");
+    assert.equal(cls({ disposition: "defer", class: "external" }), "external");
+    assert.equal(cls({ disposition: "defer", class: "bogus" }), "engineering");
+    assert.deepEqual(FOLLOWUP_CLASSES, ["engineering", "post-deploy", "external", "ops"]);
+    assert.equal(followupClass({ disposition: "post-deploy" }), "post-deploy"); assert.equal(followupClass({ class: "ops" }), "ops");
+    const v = validateContract({ requirements: [{ id: "R1", quote: Q1, disposition: "defer", why: "w", class: "bogus" }], deliverables: [], preserve: [], validate: [{ id: "V1", command: "true" }] }, Q1);
+    assert.ok(v.problems.some((x) => /R1: class must be one of/.test(x)), v.problems.join(";"));
+  });
+  it("followupItems names the check in a post-deploy item", () => {
+    const [i] = followupItems([{ id: "R1", quote: Q1, disposition: "post-deploy", why: "w", check: "login-smoke" }]);
+    assert.match(i.why, /^post-deploy: \[check:login-smoke\] w$/);
+  });
+  it("#4724 a deferred row needs exactly one valid bucket; owner actions are never post-deploy; dates are absolute", () => {
+    const contract = (r) => ({ requirements: [{ id: "R1", quote: Q1, why: "w", ...r }], deliverables: [], preserve: [], validate: [{ id: "V1", command: "true" }] });
+    const probs = (r) => validateContract(contract(r), Q1).problems.filter((x) => /^R1: .*(bucket|never post-deploy|owner)/.test(x));
+    assert.deepEqual(BUCKETS, ["post-deploy", "verify-now", "date", "owner", "new-issue"]);
+    assert.equal(probs({ disposition: "defer" }).length, 1); // missing bucket
+    for (const bucket of ["post-deploy", "verify-now", "new-issue", "date:2026-12-01", "owner:rotate the key"]) assert.deepEqual(probs({ disposition: "defer", bucket }), [], bucket);
+    for (const bucket of ["date:5 weeks after deploy", "date:2026-02-30", "date", "owner:", "owner", "later", "post-deploy:x"]) assert.equal(probs({ disposition: "defer", bucket }).length, 1, bucket);
+    assert.match(probs({ disposition: "post-deploy", check: "a-smoke", bucket: "owner:spend" })[0], /never post-deploy/);
+    assert.equal(probs({ disposition: "deliver", bucket: "post-deploy" }).length, 1);
+    assert.deepEqual(probs({ disposition: "deliver" }), []);
+    assert.deepEqual(bucketProblems({ disposition: "defer", bucket: "owner:x", class: "post-deploy" }).length, 1);
+    assert.equal(bucketKind("date:2026-12-01"), "date"); assert.equal(bucketKind("nope"), null);
+  });
+  it("#4724 the bucket decides the follow-up class and tags the item for the script and the gate", () => {
+    const one = (r) => followupItems([{ id: "R1", quote: Q1, disposition: "defer", why: "w", ...r }], { now: Date.UTC(2026, 9, 27) })[0];
+    assert.equal(followupClass({ disposition: "defer", bucket: "owner:spend" }), "external");
+    assert.equal(followupClass({ disposition: "defer", bucket: "owner:spend", class: "ops" }), "ops");
+    assert.equal(followupClass({ disposition: "defer", bucket: "owner:x", class: "post-deploy" }), "external");
+    assert.equal(followupClass({ disposition: "defer", bucket: "new-issue", class: "post-deploy" }), "engineering");
+    for (const bucket of ["post-deploy", "verify-now", "date:2026-12-01"]) assert.equal(followupClass({ disposition: "defer", bucket }), "post-deploy");
+    assert.equal(one({ bucket: "owner:rotate the key" }).why, "owner: rotate the key. [bucket:owner] w");
+    assert.equal(one({ bucket: "verify-now" }).why, "post-deploy: [bucket:verify-now] w");
+    assert.equal(one({ bucket: "date:2026-12-01" }).why, "post-deploy: [bucket:date] due:2026-12-01 from:2026-10-27 w");
+    assert.equal(one({ bucket: "new-issue" }).why, "defer: [bucket:new-issue] w");
+    assert.equal(one({}).why, "defer: w"); // an unbucketed (older) row is unchanged
+  });
+  it("#4724 bucketTally counts deferred items per bucket kind; an amendment may carry the bucket", () => {
+    assert.deepEqual(bucketTally([{ bucket: "date:2026-12-01" }, { bucket: "date:2026-12-02" }, { bucket: "owner:x" }, {}]), { date: 2, owner: 1, none: 1 });
+    const c = { requirements: [{ id: "R1", quote: Q1, disposition: "deliver" }], deliverables: [], preserve: [], validate: [] };
+    const r = applyAmendments(c, [{ kind: "defer", requirement: "R1", why: "w", bucket: "verify-now" }]);
+    assert.equal(r.contract.requirements[0].bucket, "verify-now"); assert.equal(r.toTrack.length, 1);
+  });
+});
+
+describe("#4726 a [type:e2e] requirement needs a real end-to-end validate", () => {
+  const Q = "Users can sign up and sign in with an emailed code alone [type:e2e]";
+  const mk = (cmd, quote = Q, extra = {}) => {
+    const contract = { ...C, requirements: [{ id: "R1", quote, disposition: "deliver", ...extra }, C.requirements[1]], validate: [{ id: "V1", command: cmd }] };
+    return { contract, ctx: { ...ctx, contract } };
+  };
+  const rv = (contract) => ({ ...good, issue_coverage: [{ quote: contract.requirements[0].quote, status: "covered" }, ...good.issue_coverage.slice(1)] });
+  const run = (cmd, quote, extra, e2e) => { const m = mk(cmd, quote, extra); return decide(rv(m.contract), { ...m.ctx, issueText: `${ISSUE}\n${m.contract.requirements[0].quote}`, e2e }); };
+  it("e2e requirement verified only by a unit test fails conformance (the #36414 shape)", () => {
+    const d = run("pytest tests/test_email_code_auth.py");
+    assert.equal(d.state, "nonconforming");
+    assert.deepEqual(codes(d), ["conformance.e2e_unverified"]);
+  });
+  it("a Playwright, configured e2e check or e2e spec file validate passes", () => {
+    assert.equal(run("npx playwright test e2e/signup.spec.ts").state, "conforms");
+    assert.equal(run("make smoke-live", Q, {}, { checks: ["make smoke-live"] }).state, "conforms");
+    assert.equal(run("node --test tests/signup.js", Q, {}, { isSpec: (f) => f === "tests/signup.js" }).state, "conforms");
+  });
+  it("isE2eCommand and e2eVerified resolve a V-ref to its contract command", () => {
+    assert.equal(isE2eCommand("npx playwright test"), true);
+    assert.equal(isE2eCommand("pytest tests/test_x.py"), false);
+    const contract = { validate: [{ id: "V1", command: "pytest tests/a.py" }, { id: "V2", command: "npx cypress run" }] };
+    assert.equal(e2eVerified({ validated_by: "V1" }, contract), false);
+    assert.equal(e2eVerified({ validated_by: "V1, V2" }, contract), true);
+  });
+  it("[type:unit] and [type:api] requirements keep their evidence rules; not-applicable is untouched", () => {
+    assert.equal(run("pytest tests/test_x.py", "Users can sign up with an emailed code [type:unit]").state, "conforms");
+    assert.equal(run("pytest tests/test_x.py", "Users can sign up with an emailed code [type:api]").state, "conforms");
+    const na = { ...C.requirements[0], quote: Q, disposition: "not-applicable", evidence: "src/a.js:1" };
+    const contract = { ...C, requirements: [na, C.requirements[1]] };
+    const r = { ...good, issue_coverage: [{ quote: Q, status: "covered" }, ...good.issue_coverage.slice(1)], requirements: [{ id: "R1", status: "not-applicable" }, good.requirements[1]] };
+    assert.notEqual(decide(r, { ...ctx, contract, issueText: `${ISSUE}\n${Q}` }).failures.some((f) => f.code === "conformance.e2e_unverified"), true);
+  });
+});
+
+describe("decision amendments (#4695)", () => {
+  const withRow = { ...C, preserve: [...C.preserve, { id: "H1", what: "use A", source: "decision", decision: "d9-1" }] };
+  const amend = (extra, opts = { baseFiles: ["src/scrape.js", "src/search.js"] }) => applyAmendments(withRow, [{ kind: "decision", why: "w", decision: { choice: "use B", anchors: ["src/**"], ...extra } }], null, opts);
+  it("applies a decision whose anchors exist on the base and returns the record", () => {
+    const a = amend({});
+    assert.deepEqual(a.problems, []);
+    assert.equal(a.decisions[0].choice, "use B");
+    assert.ok(a.contract.preserve.some((p) => p.id === "H1"));
+  });
+  it("rejects an anchor that matches no base file", () => {
+    const a = amend({ anchors: ["nope/**"] });
+    assert.match(a.problems[0], /match no file on the base/);
+    assert.equal(a.decisions.length, 0);
+  });
+  it("supersedes drops the engine-authored preserve row; without it the row stays", () => {
+    assert.ok(!amend({ supersedes: "d9-1" }).contract.preserve.some((p) => p.id === "H1"));
+    assert.ok(amend({}).contract.preserve.some((p) => p.id === "H1"));
+  });
+  it("a decision without choice or anchors is an incomplete amendment", () => {
+    assert.match(amend({ choice: "" }).problems[0], /needs decision/);
+  });
+});

package/bin/lean/decisions.mjs

@@ -0,0 +1,181 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * #4695: anchored decisions. A settled choice carries the paths/globs (and optional symbols) it governs and an optional
+ * `supersedes` link. The record of truth is a `<!-- FORGE:DECISION {json} -->` issue comment (the JSON sits on the
+ * marker line; prose FORGE:DECISION comments carry none and are ignored); `~/.forge/decisions/<repo>.json` indexes it.
+ * Supersession appends a fresh record of the old decision (status superseded, superseded_by) on the old issue: the
+ * latest record per id wins, nothing is edited. When a lane's deliverables hit an anchor the decision becomes an
+ * engine-authored preserve row `{id:"H<n>", what, source:"decision"}` (same shape as #4694), capped at HISTORY_ROWS_MAX.
+ * Pure except the index read/write; no LLM, gh or git here.
+ */
+import * as nodeFs from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { noComments } from "./render.mjs";
+
+export const DECISION_MARKER = "FORGE:DECISION";
+/** Preserve rows the engine adds from history per lane; guards (#4694) share this cap. */
+export const HISTORY_ROWS_MAX = 5;
+const TEXT_MAX = 200;
+const ANCHORS_MAX = 10;
+const MARKER_RE = /^<!--\s*FORGE:DECISION\s+(\{.*\})\s*-->/;
+
+const one = (v, max = TEXT_MAX) => {
+  const t = typeof v === "string" ? noComments(v, " ").replace(/\s+/g, " ").trim() : "";
+  return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+};
+const strs = (v, max = ANCHORS_MAX, len = 200) => [...new Set((Array.isArray(v) ? v : []).map((x) => one(x, len)).filter(Boolean))].slice(0, max);
+const cleanAnchor = (a) => String(a).replace(/^\.\//, "").replace(/^\/+/, "");
+
+/** A bounded decision record from raw input, or null when it has no choice or no anchor. `issue` is the register issue. */
+export function normaliseDecision(raw, { issue = null, n = 1 } = {}) {
+  const r = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+  const choice = one(r.choice), anchors = strs(r.anchors).map(cleanAnchor);
+  if (!choice || !anchors.length) return null;
+  const iss = Number.isInteger(r.issue) ? r.issue : issue;
+  const status = r.status === "superseded" ? "superseded" : "active";
+  const rec = { v: 1, id: one(r.id, 60) || `d${iss ?? 0}-${n}`, choice, why: one(r.why), anchors, issue: iss, status };
+  const symbols = strs(r.symbols, ANCHORS_MAX, 80);
+  if (symbols.length) rec.symbols = symbols;
+  if (one(r.supersedes, 60)) rec.supersedes = one(r.supersedes, 60);
+  if (status === "superseded" && one(r.superseded_by, 60)) rec.superseded_by = one(r.superseded_by, 60);
+  return rec;
+}
+
+/** The marker (for post(): `<!-- FORGE:DECISION {json} -->`) and readable body of a decision record. */
+export function renderDecision(rec) {
+  const json = JSON.stringify(rec).replace(/>/g, "\\u003e").replace(/</g, "\\u003c"); // can never close the marker comment
+  const tail = [rec.supersedes ? `Supersedes \`${rec.supersedes}\`.` : "", rec.status === "superseded" ? `Superseded by \`${rec.superseded_by}\`.` : ""].filter(Boolean).join(" ");
+  return {
+    marker: `${DECISION_MARKER} ${json}`,
+    body: `## Decision \`${rec.id}\`${rec.status === "superseded" ? " (superseded)" : ""}\n**What**: ${rec.choice}\n**Why**: ${rec.why || "-"}\n**Governs**: ${rec.anchors.map((a) => `\`${a}\``).join(", ")}${tail ? `\n${tail}` : ""}`,
+  };
+}
+
+/** The record from a comment body whose first line is `<!-- FORGE:DECISION {json} -->`; null for prose or malformed. */
+export function parseDecisionComment(body, { issue = null } = {}) {
+  const m = MARKER_RE.exec(String(body ?? "").split("\n", 1)[0]);
+  if (!m) return null;
+  try {
+    const raw = JSON.parse(m[1]);
+    return normaliseDecision({ ...raw, issue: Number.isInteger(raw?.issue) ? raw.issue : issue });
+  } catch { return null; }
+}
+
+/** One record per id, the latest wins (input in posting order); ids ordered by first appearance. */
+export function foldDecisions(records) {
+  const by = new Map();
+  for (const r of records ?? []) if (r?.id) by.set(r.id, { ...(by.get(r.id) ?? {}), ...r });
+  return [...by.values()];
+}
+
+const globRe = (g) => new RegExp(`^${String(g).replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*\/?/g, "\u0000").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]").replace(/\u0000/g, ".*")}$`);
+/** True when `anchor` (a file, a `dir/` prefix or a glob) covers `path`. */
+export function anchorMatches(anchor, path) {
+  const a = cleanAnchor(anchor), p = cleanAnchor(path);
+  if (!a || !p) return false;
+  if (a.endsWith("/")) return p.startsWith(a);
+  return a === p || globRe(a).test(p) || p.startsWith(`${a}/`);
+}
+
+/** The anchors that match no file of `files`. */
+export const deadAnchors = (anchors, files) => (anchors ?? []).filter((a) => !(files ?? []).some((f) => anchorMatches(a, f)));
+
+/** Active decisions with at least one dead anchor on the base file list: [{decision, dead}]. Never applied. */
+export function staleDecisions(records, baseFiles) {
+  const out = [];
+  for (const d of foldDecisions(records)) {
+    if (d.status === "superseded") continue;
+    const dead = deadAnchors(d.anchors, baseFiles);
+    if (dead.length) out.push({ decision: d, dead });
+  }
+  return out;
+}
+
+/**
+ * Preserve rows for the active decisions an anchor of which covers a deliverable path: most specific anchor first, then
+ * newest issue, then id; at most `cap` rows, ids H<start>… Deterministic: the same inputs give the same rows.
+ */
+export function historyRows(records, deliverablePaths, { cap = HISTORY_ROWS_MAX, start = 1 } = {}) {
+  const paths = (deliverablePaths ?? []).filter(Boolean);
+  if (!paths.length || cap <= 0) return [];
+  const hits = [];
+  for (const d of foldDecisions(records)) {
+    if (d.status === "superseded") continue;
+    const spec = Math.max(-1, ...d.anchors.filter((a) => paths.some((p) => anchorMatches(a, p))).map((a) => cleanAnchor(a).length));
+    if (spec >= 0) hits.push({ d, spec });
+  }
+  hits.sort((x, y) => y.spec - x.spec || (y.d.issue ?? 0) - (x.d.issue ?? 0) || (x.d.id < y.d.id ? -1 : x.d.id > y.d.id ? 1 : 0));
+  return hits.slice(0, cap).map(({ d }, i) => ({
+    id: `H${start + i}`,
+    what: `${d.choice}${d.why ? ` (${d.why})` : ""} [decision ${d.id}${d.issue ? `, #${d.issue}` : ""}; to change it, amend {kind:"decision", decision:{choice, anchors, supersedes:"${d.id}"}, why}]`,
+    source: "decision",
+    decision: d.id,
+  }));
+}
+
+/** The contract with history rows appended to preserve; the same object when none apply (the hash stays byte-identical). */
+export function withDecisionRows(contract, records) {
+  const have = new Set((contract?.preserve ?? []).map((p) => p.id));
+  let start = 1;
+  while (have.has(`H${start}`)) start++;
+  const room = HISTORY_ROWS_MAX - (contract?.preserve ?? []).filter((p) => /^H\d+$/.test(String(p.id))).length;
+  const rows = historyRows(records, (contract?.deliverables ?? []).map((d) => d.path), { cap: room, start });
+  return rows.length ? { ...contract, preserve: [...(contract.preserve ?? []), ...rows] } : contract;
+}
+
+/** {old, next}: the old record marked superseded by the new id, the new one linked back with `supersedes`. */
+export function supersede(old, next) {
+  return { old: { ...old, status: "superseded", superseded_by: next.id }, next: { ...next, supersedes: old.id } };
+}
+
+export const decisionsDir = () => process.env.FORGEDOCK_DECISIONS_DIR || join(homedir(), ".forge", "decisions");
+export const indexFile = (repo) => join(decisionsDir(), `${String(repo ?? "repo").replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
+
+/** The indexed records (posting order); [] when the index is absent or unreadable. One file read. */
+export function readDecisionIndex(repo, { fs = nodeFs } = {}) {
+  try {
+    const j = JSON.parse(fs.readFileSync(indexFile(repo), "utf8"));
+    return (Array.isArray(j?.records) ? j.records : []).map((r) => normaliseDecision(r)).filter(Boolean);
+  } catch { return []; }
+}
+
+/** Replaces the index (written atomically); best effort, the register of record is GitHub. */
+export function writeDecisionIndex(repo, records, { fs = nodeFs } = {}) {
+  try {
+    const file = indexFile(repo);
+    fs.mkdirSync(decisionsDir(), { recursive: true });
+    fs.writeFileSync(`${file}.tmp`, JSON.stringify({ v: 1, records: foldDecisions(records) }));
+    fs.renameSync(`${file}.tmp`, file);
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * Posts the lane's decision records as FORGE:DECISION on `issue` and, for a `supersedes`, the old record marked
+ * superseded on its own issue (both records updated); then updates the index. `post(marker, body, onIssue)` posts a
+ * comment. Returns the records posted. Best effort per record: a failed post is skipped, never fails the lane.
+ */
+export async function recordDecisions(list, { issue, repo, post, fs = nodeFs }) {
+  const index = foldDecisions(readDecisionIndex(repo, { fs })), out = [];
+  let n = 0;
+  for (const raw of list ?? []) {
+    n++;
+    let next = normaliseDecision({ ...raw, id: undefined, issue }, { issue, n });
+    if (!next) continue;
+    const old = raw.supersedes ? index.find((d) => d.id === raw.supersedes) : null;
+    let oldRec = null;
+    if (old) ({ old: oldRec, next } = supersede(old, next));
+    else if (raw.supersedes) next = { ...next, supersedes: String(raw.supersedes) };
+    try {
+      const m = renderDecision(next);
+      await post(m.marker, m.body, issue);
+      if (oldRec?.issue) { const o = renderDecision(oldRec); await post(o.marker, o.body, oldRec.issue); }
+    } catch { continue; }
+    index.push(...[oldRec, next].filter(Boolean));
+    out.push(next);
+  }
+  if (out.length) writeDecisionIndex(repo, index, { fs });
+  return out;
+}

package/bin/lean/decisions.test.mjs

@@ -0,0 +1,71 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { normaliseDecision, renderDecision, parseDecisionComment, foldDecisions, anchorMatches, deadAnchors, staleDecisions, historyRows, withDecisionRows, supersede, readDecisionIndex, recordDecisions, HISTORY_ROWS_MAX } from "./decisions.mjs";
+
+const D = (o) => normaliseDecision({ choice: "use A not B", why: "B leaks", anchors: ["src/a/**"], ...o }, { issue: 10, n: 1 });
+
+describe("decisions (#4695)", () => {
+  it("round-trips through the marker line and ignores prose FORGE:DECISION comments", () => {
+    const d = D({ symbols: ["foo"], anchors: ["src/a/x.js", "lib/-->evil"] });
+    const m = renderDecision(d);
+    const body = `<!-- ${m.marker} -->\n${m.body}`;
+    assert.deepEqual(parseDecisionComment(body), d);
+    assert.equal(parseDecisionComment("<!-- FORGE:DECISION -->\n## Decision (batch 1)\n**What**: x"), null);
+    assert.equal(parseDecisionComment("<!-- FORGE:DECISION {nope} -->"), null);
+    assert.equal(normaliseDecision({ choice: "x", anchors: [] }), null);
+  });
+  it("matches files, directory prefixes and globs", () => {
+    assert.ok(anchorMatches("src/a.js", "src/a.js"));
+    assert.ok(anchorMatches("src/a/", "src/a/b/c.js"));
+    assert.ok(anchorMatches("src/**", "src/a/b.js"));
+    assert.ok(anchorMatches("src/*.js", "src/a.js"));
+    assert.ok(!anchorMatches("src/*.js", "src/a/b.js"));
+    assert.deepEqual(deadAnchors(["src/a.js", "gone/**"], ["src/a.js"]), ["gone/**"]);
+  });
+  it("history rows: only anchored deliverables, capped at 5, deterministic", () => {
+    const recs = Array.from({ length: 8 }, (_, i) => normaliseDecision({ id: `d${i}`, choice: `c${i}`, anchors: ["src/**"], issue: i + 1 }));
+    const a = historyRows(recs, ["src/x.js"]), b = historyRows([...recs].reverse(), ["src/x.js"]);
+    assert.equal(a.length, HISTORY_ROWS_MAX);
+    assert.deepEqual(a, b);
+    assert.deepEqual(a.map((r) => r.id), ["H1", "H2", "H3", "H4", "H5"]);
+    assert.equal(a[0].decision, "d7");
+    assert.ok(a.every((r) => r.source === "decision" && r.what.includes("supersedes")));
+    assert.deepEqual(historyRows(recs, ["docs/x.md"]), []);
+    assert.deepEqual(historyRows([], ["src/x.js"]), []);
+  });
+  it("withDecisionRows leaves a contract with no hit untouched (same object)", () => {
+    const c = { preserve: [{ id: "P1", what: "w" }], deliverables: [{ id: "D1", path: "docs/x.md" }] };
+    assert.equal(withDecisionRows(c, [D()]), c);
+    const c2 = withDecisionRows({ ...c, deliverables: [{ id: "D1", path: "src/a/x.js" }] }, [D()]);
+    assert.deepEqual(c2.preserve.map((p) => p.id), ["P1", "H1"]);
+  });
+  it("supersession links both records and the old one stops binding", () => {
+    const old = D({ id: "d10-1" }), next = D({ id: "d11-1", choice: "use B" });
+    const r = supersede(old, next);
+    assert.equal(r.old.status, "superseded");
+    assert.equal(r.old.superseded_by, "d11-1");
+    assert.equal(r.next.supersedes, "d10-1");
+    assert.deepEqual(historyRows([old, r.old], ["src/a/x.js"]), []);
+    assert.equal(foldDecisions([old, r.old]).length, 1);
+  });
+  it("lists stale decisions with dead anchors, never superseded ones", () => {
+    const live = D({ id: "a" }), dead = D({ id: "b", anchors: ["src/a/**", "old/x.js"] }), gone = D({ id: "c", anchors: ["old/y.js"], status: "superseded", superseded_by: "z" });
+    const s = staleDecisions([live, dead, gone], ["src/a/q.js"]);
+    assert.deepEqual(s.map((x) => [x.decision.id, x.dead]), [["b", ["old/x.js"]]]);
+  });
+  it("recordDecisions posts the new and the superseded old record and updates the index", async () => {
+    process.env.FORGEDOCK_DECISIONS_DIR = tmpDir("dec-");
+    const posts = [], post = async (marker, body, on) => { posts.push({ marker, on }); };
+    const first = await recordDecisions([{ choice: "use A", anchors: ["src/**"], why: "w" }], { issue: 10, repo: "o/r", post });
+    assert.equal(first[0].id, "d10-1");
+    const second = await recordDecisions([{ choice: "use B", anchors: ["src/**"], why: "w2", supersedes: "d10-1" }], { issue: 11, repo: "o/r", post });
+    assert.equal(second[0].supersedes, "d10-1");
+    assert.deepEqual(posts.map((p) => p.on), [10, 11, 10]);
+    const idx = foldDecisions(readDecisionIndex("o/r"));
+    assert.equal(idx.find((d) => d.id === "d10-1").status, "superseded");
+    assert.equal(idx.find((d) => d.id === "d11-1").supersedes, "d10-1");
+  });
+});

package/bin/lean/effects.mjs

@@ -18,8 +18,9 @@ import { gatherContextFacts } from "./context.mjs";
 import { makePitfallStore } from "./pitfalls.mjs";
 import { enumeratingTests, missingEntries } from "./enumerating.mjs";
 import { resolveBaseConflicts } from "./conflictres.mjs";
-import { sequenceCollisions, snapshotLane, verifyRenumber, renumberLane, resolveSequenceConflicts, generatorProblems } from "./sequence.mjs";
+import { sequenceCollisions, snapshotLane, verifyRenumber, renumberLane, resolveSequenceConflicts, generatorProblems, journalOrderProblems } from "./sequence.mjs";
 import { duplicateExports } from "./postmerge.mjs";
+import { englishCopies } from "./i18n.mjs";
 import { scopedChecks } from "./checks.mjs";
 import { makeSequenceLeaseIo } from "./seqlease.mjs";
 import { followupMap } from "./conformance.mjs";
@@ -29,9 +30,9 @@ import { detectApiShape } from "./apishape.mjs";
 const pexec = promisify(execFile);
 const script = (n) => fileURLToPath(new URL(`../../scripts/${n}`, import.meta.url));
 /** Argv-only child with stdin input; resolves stdout, rejects on a non-zero exit with stderr attached. */
-export function runWithInput(bin, args, input, timeout = 120000) {
+export function runWithInput(bin, args, input, timeout = 120000, env = undefined) {
   return new Promise((res, rej) => {
-    const child = execFile(bin, args, { timeout, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+    const child = execFile(bin, args, { timeout, maxBuffer: 10 * 1024 * 1024, ...(env ? { env } : {}) }, (err, stdout, stderr) => {
       if (err) { err.stdout = stdout; err.stderr = stderr; rej(err); } else res(String(stdout));
     });
     // A child that exits before reading stdin closes the pipe: EPIPE must reject via the exit callback, never crash the lane.
@@ -49,14 +50,25 @@ export function systemdRunAvailable() {
   }
   return systemdProbe;
 }
-const MEM_RE = /^\d+(\.\d+)?[KMGT]?$/i, CPU_RE = /^\d+%$/;
-/** Cap the whole lane process tree: spawn under `systemd-run --user --scope -p MemoryMax=.. -p CPUQuota=..`. Unset or invalid limits leave the spawn unchanged. */
-export function wrapLaneLimits(bin, args, limits) {
+const MEM_RE = /^\d+(\.\d+)?[KMGT]?$/i, CPU_RE = /^\d+%$/, TASKS_RE = /^\d+$/;
+/** #4690: default `TasksMax` of a lane scope; `tasks_max: 0|off` (or any non-count) turns the cap off. */
+export const DEFAULT_LANE_TASKS_MAX = 1024;
+let scopeSeq = 0;
+/**
+ * Cap the whole lane process tree: spawn under `systemd-run --user --scope --unit=.. -p TasksMax=.. [-p MemoryMax=..] [-p CPUQuota=..]`.
+ * #4690: `TasksMax` is on by default (one runaway lane cannot fork-bomb the host); unset limits use the default, invalid ones are dropped.
+ * Returns `unit` (the scope name) when wrapped, so the runner can read the scope's limit events.
+ */
+export function wrapLaneLimits(bin, args, limits, unit = `forgedock-lane-${process.pid}-${++scopeSeq}`) {
   const mem = limits?.memory_max && MEM_RE.test(String(limits.memory_max)) ? String(limits.memory_max) : null;
   const cpu = limits?.cpu_quota && CPU_RE.test(String(limits.cpu_quota)) ? String(limits.cpu_quota) : null;
-  if (!mem && !cpu) return { bin, args };
-  return { bin: "systemd-run", args: ["--user", "--scope", "-q", ...(mem ? ["-p", `MemoryMax=${mem}`] : []), ...(cpu ? ["-p", `CPUQuota=${cpu}`] : []), "--", bin, ...args] };
+  const raw = limits?.tasks_max === undefined || limits?.tasks_max === null || limits?.tasks_max === "" ? DEFAULT_LANE_TASKS_MAX : String(limits.tasks_max).trim();
+  const tasks = TASKS_RE.test(raw) && Number(raw) > 0 ? Number(raw) : null;
+  if (!mem && !cpu && !tasks) return { bin, args };
+  return { bin: "systemd-run", unit, args: ["--user", "--scope", "-q", `--unit=${unit}`, ...(tasks ? ["-p", `TasksMax=${tasks}`] : []), ...(mem ? ["-p", `MemoryMax=${mem}`] : []), ...(cpu ? ["-p", `CPUQuota=${cpu}`] : []), "--", bin, ...args] };
 }
+/** #4690: the one line a run logs when lanes get no scope (systemd-run --user --scope unavailable); null when they are capped. */
+export const laneCapNotice = (probe = systemdRunAvailable) => (probe() ? null : "lanes are uncapped: `systemd-run --user --scope` is unavailable here, so no TasksMax/MemoryMax/CPUQuota applies to lane process trees");
 
 /** #4211: a judgment call over data in the prompt only (the refactor:split grouping call): no tool can read a file. */
 export const noToolFlags = (caps) => (caps?.strictMcp ? ["--tools", ""]
@@ -80,7 +92,7 @@ export function makeLeanRunner({ runCli = runCliBackendAsync, probe = systemdRun
     const r = await runCli({ spec: { name: `core-${role}` }, userMessage: prompt, systemPrompt: resume ? "" : system,
       args: [String(issue)], cwd, bin, model, maxTurns: caps?.maxTurns ? maxTurns : null, env, sessionFlags: flags, extraArgs: resume ? ["--resume", resume] : [],
       logger: { log() {} },
-      idleMs, maxMs, stream: idleMs > 0, control, onSpawn, busy, busyMs, onIdleExtend, ...(contextMax > 0 ? { contextMax } : {}), ...(turnMax > 0 ? { turnMax } : {}), wrap: laneLimits && probe() ? (b, a) => wrapLaneLimits(b, a, laneLimits) : null });
+      idleMs, maxMs, stream: idleMs > 0, control, onSpawn, busy, busyMs, onIdleExtend, ...(contextMax > 0 ? { contextMax } : {}), ...(turnMax > 0 ? { turnMax } : {}), wrap: probe() ? (b, a) => wrapLaneLimits(b, a, laneLimits) : null });
     // #4395: a resumed session's first turn carries the prior history, so only a fresh session reports a baseline.
     return { text: r.text, sessionId: r.sessionId, usage: r.usage, costUsd: r.costUsd, durationMs: r.durationMs, turns: r.turns, model: r.cliModel ?? "default",
       baselineTokens: resume ? null : (r.baselineTokens ?? null), tools: toolStats(r.toolUses) }; // #4410: tool calls per turn, re-reads
@@ -327,11 +339,14 @@ export function makeLeanIo({ repo }) {
     async transitionLabel(issue, state) { await pexec("bash", [script("transition-label.sh"), String(issue), "-R", repo, state], { timeout: 60000 }); },
     /**
      * File (or append to) the parent's ONE batched follow-up issue (scripts/file-deferred-followups.sh: trusted lookup,
-     * append, create, claim marker, duplicate re-check). items: [{key, why}]. Returns {key: issueNumber}; throws on exit 3/4.
+     * append, create, claim marker, duplicate re-check; one issue per class, #4664). items: [{key, why, class?}]; the key is the
+     * item's identity (column 5, column 1 is `-`). milestone / defaultMilestone: the parent's and forge.yaml followups.default_milestone; lane: the release lane of the post-deploy rollup (#4724).
+     * Returns {key: issueNumber}; throws on exit 2/3/4.
      */
-    async fileFollowups({ parent, items }) {
-      const tsv = items.map((i) => `${i.key}\t${i.why}\t`).join("\n") + "\n";
-      const out = await runWithInput("bash", [script("file-deferred-followups.sh"), "--parent", String(parent), "--repo", repo], tsv, 180000);
+    async fileFollowups({ parent, items, milestone = null, defaultMilestone = null, lane = null }) {
+      const tsv = items.map((i) => `-\t${i.why}\t\t${i.class ?? ""}\t${i.key}`).join("\n") + "\n";
+      const env = { ...process.env, ...(milestone ? { FORGE_FOLLOWUP_MILESTONE: String(milestone) } : {}), ...(defaultMilestone ? { FORGE_FOLLOWUPS_DEFAULT_MILESTONE: String(defaultMilestone) } : {}), ...(lane ? { FORGE_RELEASE_LANE: String(lane) } : {}) }; // #4724: the post-deploy rollup is one per release lane
+      const out = await runWithInput("bash", [script("file-deferred-followups.sh"), "--parent", String(parent), "--repo", repo], tsv, 180000, env);
       return followupMap(out, items);
     },
     /**
@@ -380,10 +395,13 @@ export function makeLeanIo({ repo }) {
     conflictResolve: ({ cwd, files, cfg }) => resolveBaseConflicts({ git: (a) => run("git")(a, { cwd }), cwd, files, cfg }),
     sequenceLease: makeSequenceLeaseIo(),
     /** #4591: lane-added migrations the repo's generator did not produce (no journal entry or snapshot); [] on failure. */
-    migrationGenerator: ({ cwd, base }) => generatorProblems({ git: (a) => run("git")(a, { cwd }), base }),
+    /** #4661: plus journal `when` stamps not above the base max (newest-only migrators skip them). */
+    migrationGenerator: async ({ cwd, base }) => { const git = (a) => run("git")(a, { cwd }); return [...await generatorProblems({ git, base }), ...await journalOrderProblems({ git, base })]; },
     /** #4406: the lane's scoped checks after a base merge (bin/lean/checks.mjs; [] on failure), and same-app duplicate exports (bin/lean/postmerge.mjs). */
     postMergeChecks: async ({ cwd, base }) => { try { return scopedChecks({ repo: cwd, base }); } catch { return []; } },
     duplicateExports: ({ cwd, base }) => duplicateExports({ git: (a) => run("git")(a, { cwd }), cwd, base }),
+    /** #4596: keys added to a non-en locale catalog as English copies (bin/lean/i18n.mjs). */
+    englishCopies: ({ cwd, base }) => englishCopies({ git: (a) => run("git")(a, { cwd }), base }),
     /**
      * #4271: scripts/acceptance-red-green.sh for the frozen repro_test in cwd; {base, head} words, or null on any failure.
      * `env` (#4325): the lane env (run TMPDIR, toolchain), merged over process.env, so the command sees what the builder saw.