forgedock 1.36.0 → 1.37.0

package/bin/lean/conformance.mjs

@@ -28,6 +28,7 @@ export const MIN_QUOTE_CHARS = 12;
 /** A contract larger than this cannot be posted whole in one comment (the comment cap is 60k). */
 export const MAX_CONTRACT_CHARS = 40000;
 import { CHECK_ID_RE } from "./postdeploy-check.mjs";
+import { normaliseDecision, deadAnchors } from "./decisions.mjs";
 const C = OUTCOME_CODES;
 
 export const norm = (s) => String(s ?? "").replace(/[`*_>]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
@@ -234,6 +235,8 @@ export function validateContract(c, issueText, { repro = false } = {}) {
     if (TRACKED.includes(r?.disposition) && blank(r?.why)) problems.push(`${id}: ${r.disposition} needs a why`);
     if (r?.disposition === "post-deploy" && !CHECK_ID_RE.test(String(r?.check ?? ""))) problems.push(`${id}: post-deploy needs a check id (\`check\`, e.g. "login-smoke") naming an entry of .forge/post-deploy-checks.json on the default branch`);
     if (r?.disposition === "not-applicable" && blank(r?.evidence)) problems.push(`${id}: not-applicable needs file:line evidence`);
+    for (const m of bucketProblems(r)) problems.push(`${id}: ${m}`);
+    if (r?.class != null && !FOLLOWUP_CLASSES.includes(r.class)) problems.push(`${id}: class must be one of ${FOLLOWUP_CLASSES.join("|")}`);
     if (r?.verify != null && !VERIFY_MODES.includes(r.verify)) problems.push(`${id}: verify must be one of ${VERIFY_MODES.join("|")}`);
     if (isOutOfBand(r) && r?.disposition !== "deliver") problems.push(`${id}: verify out_of_band applies only to a deliver requirement`);
     else if (isOutOfBand(r) && blank(r?.evidence)) problems.push(`${id}: verify out_of_band needs evidence naming the job or workflow that measures it (or set verify "in_lane" if this change can check it)`);
@@ -268,7 +271,8 @@ export function validateContract(c, issueText, { repro = false } = {}) {
 /** forge#4519: a shell pattern as in scripts/hotspots.sh `case` (`*` crosses `/`, `?` one character), anchored. */
 const shellGlobRe = (g) => new RegExp(`^${String(g).replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
 
-const AMEND_KINDS = ["add-deliverable", "add-requirement", ...TRACKED, "amend-requirement"];
+const AMEND_KINDS = ["add-deliverable", "add-requirement", ...TRACKED, "amend-requirement", "supersedes", "decision"];
+const GUARD_ID_RE = /^#?\d+$/;
 const AMEND_SLIPS = { "amend-requirement": "defer", limitation: "defer" };
 
 /** forge#4574: common builder slips: `type` for `kind`, amend-requirement/limitation as defer, an `R#` in `id` as the requirement. */
@@ -282,11 +286,26 @@ function normalizeAmendment(a) {
   return n;
 }
 
+const REF_SEP_RE = /\s*(?:[/,;&+]|\band\b)\s*/i, REF_RANGE_RE = /^R(\d+)\s*[-\u2013\u2014]\s*R?(\d+)$/i, REF_MAX = 50;
+
+/** forge#4655: a slash/comma-joined or ranged requirement reference (`R2/R3`, `R2, R3`, `R2–R3`) as its individual ids; a single id or anything else is returned as is. */
+function splitRequirementRefs(ref) {
+  if (typeof ref !== "string") return [ref];
+  const ids = [];
+  for (const part of ref.trim().split(REF_SEP_RE)) {
+    const m = REF_RANGE_RE.exec(part);
+    if (m && +m[1] <= +m[2] && +m[2] - +m[1] < REF_MAX) for (let i = +m[1]; i <= +m[2]; i++) ids.push(`R${i}`);
+    else ids.push(part);
+  }
+  return ids.length > 1 ? ids : [ref];
+}
+
 /** The rejection reason, naming the valid kinds or the missing field so the builder's correction round can fix it. */
 function amendmentProblem(a, tag) {
   const kind = a?.kind;
   const need = kind === "add-deliverable" ? "needs a path" : kind === "add-requirement" ? "needs requirement {id, quote}"
-    : TRACKED.includes(kind) ? "needs requirement: \"R#\"" : kind === "amend-requirement" ? "needs requirement: \"R#\" and text (the revised wording)" : null;
+    : kind === "supersedes" ? "needs guard: \"#N\" (the guarded issue)" : TRACKED.includes(kind) ? "needs requirement: \"R#\"" : kind === "amend-requirement" ? "needs requirement: \"R#\" and text (the revised wording)"
+      : kind === "decision" ? "needs decision {choice, anchors: [paths or globs], symbols?, supersedes?: decision id}" : null;
   const why = need ? `amendment kind '${kind}' ${need}` : `unknown kind '${kind ?? ""}'; valid kinds are ${AMEND_KINDS.join(", ")}`;
   return `unknown or incomplete amendment: ${why}: ${tag}`;
 }
@@ -296,14 +315,25 @@ function amendmentProblem(a, tag) {
  * defer|post-deploy {requirement: id}. Every amendment needs a why. Returns {contract, applied[], toTrack[], problems[]}.
  * `generatedPaths` (forge#4519, forge.yaml maintenance.generated_paths via scripts/hotspots.sh): an add-deliverable on a
  * matching path is refused; the repo's generator or bot owns that file.
+ * `decision` {decision:{choice, anchors, symbols?, supersedes?}} (#4695): every anchor must match a file of `baseFiles` (the
+ * base tree; null skips the check); `supersedes` names the decision whose engine-authored preserve row it replaces and
+ * drops that row; returns the records in `decisions`.
  */
-export function applyAmendments(frozen, amendments, issueText = null, { generatedPaths = [] } = {}) {
+export function applyAmendments(frozen, amendments, issueText = null, { generatedPaths = [], baseFiles = null } = {}) {
   const c = structuredClone(frozen);
   c.deliverables = c.deliverables ?? [];
-  const applied = [], toTrack = [], problems = [];
+  const applied = [], toTrack = [], problems = [], decisions = [];
   const genRes = (Array.isArray(generatedPaths) ? generatedPaths : []).filter((g) => typeof g === "string" && g).map(shellGlobRe);
+  const rows = [];
   for (const raw of Array.isArray(amendments) ? amendments : []) {
-    const a = normalizeAmendment(raw);
+    const n = normalizeAmendment(raw);
+    if (n && (TRACKED.includes(n.kind) || n.kind === "amend-requirement") && typeof n.requirement === "string") {
+      const ids = splitRequirementRefs(n.requirement);
+      if (ids.length > 1) { for (const id of ids) rows.push({ a: { ...n, requirement: id }, raw }); continue; }
+    }
+    rows.push({ a: n, raw });
+  }
+  for (const { a, raw } of rows) {
     const tag = JSON.stringify(raw ?? null).slice(0, 400);
     if (blank(a?.why)) { problems.push(`amendment without why: ${tag}`); continue; }
     if (a.kind === "add-deliverable" && !blank(a.path)) {
@@ -325,6 +355,12 @@ export function applyAmendments(frozen, amendments, issueText = null, { generate
       if (tagsOutOfBand(r)) r.verify = "out_of_band"; // #4404: same freeze-time tag as the planned requirements
       c.requirements.push(r);
       if (TRACKED.includes(r.disposition)) toTrack.push(r);
+    } else if (a.kind === "supersedes" && GUARD_ID_RE.test(String(a.guard ?? "").trim())) {
+      // #4693: retires one guard's guard_broken for this lane; the reviewer judges it, the engine tells the guarded issue after merge
+      const guard = `#${String(a.guard).trim().replace(/^#/, "")}`;
+      c.supersedes = [...(c.supersedes ?? []).filter((s) => s.guard !== guard), { guard, why: String(a.why).trim() }];
+      applied.push({ kind: a.kind, target: guard, why: String(a.why).trim() });
+      continue;
     } else if (a.kind === "amend-requirement" && !blank(a.requirement)) {
       // #4594: the requirement stays deliver and keeps its verbatim quote; the reviewer judges it against amendment.text
       const r = c.requirements.find((x) => x.id === a.requirement);
@@ -334,14 +370,24 @@ export function applyAmendments(frozen, amendments, issueText = null, { generate
       const r = c.requirements.find((x) => x.id === a.requirement);
       if (!r) { problems.push(`amendment names unknown requirement ${a.requirement}`); continue; }
       if (!TRACKED.includes(r.disposition)) {
+        if (a.bucket != null) r.bucket = a.bucket; // #4724
         if (a.kind === "post-deploy" && !CHECK_ID_RE.test(String(a.check ?? r.check ?? ""))) { problems.push(`amendment post-deploy ${a.requirement} needs a check id (check)`); continue; }
-        r.disposition = a.kind; r.why = a.why; r.amended = true; toTrack.push(r);
+        r.disposition = a.kind; r.why = a.why; r.amended = true; r.bucket ??= "post-deploy"; toTrack.push(r); // #4724: an amendment without a bucket defaults to post-deploy
         if (a.kind === "post-deploy") r.check = a.check ?? r.check; // #4626
       }
+    } else if (a.kind === "decision") {
+      const d = normaliseDecision({ ...a.decision, why: a.decision?.why ?? a.why });
+      if (!d) { problems.push(amendmentProblem(a, tag)); continue; }
+      const dead = Array.isArray(baseFiles) ? deadAnchors(d.anchors, baseFiles) : [];
+      if (dead.length) { problems.push(`decision anchor(s) ${dead.join(", ")} match no file on the base; anchor a path that exists there`); continue; }
+      if (!blank(a.decision?.supersedes)) c.preserve = (c.preserve ?? []).filter((p) => p.decision !== a.decision.supersedes && p.id !== a.decision.supersedes);
+      decisions.push(a.decision?.supersedes ? { ...d, supersedes: String(a.decision.supersedes) } : d);
+      applied.push({ kind: a.kind, target: d.choice.slice(0, 60), why: String(a.why).trim() });
+      continue;
     } else { problems.push(amendmentProblem(a, tag)); continue; }
     applied.push({ kind: a.kind, target: a.path ?? a.requirement?.id ?? a.requirement, why: String(a.why).trim() });
   }
-  return { contract: c, applied, toTrack, problems };
+  return { contract: c, applied, toTrack, problems, decisions };
 }
 
 const PY_MISSING_RE = /ModuleNotFoundError: No module named '([^']+)'|ImportError: No module named '?([\w.]+)'?/;
@@ -393,7 +439,7 @@ export function repoTracks(paths) {
  * `ciCovered` (#4527): the validate ids accepted only because the head is CI-verified (no local result, or a missing host
  * tool), for the trajectory; always an array.
  */
-export function precheck({ contract, result, changedFiles, ignore = [], ciVerified = false, hotspots = null, repro = null, validateRuns = null, repoHas = () => false, frozen = null, checkIds = null }) {
+export function precheck({ contract, result, changedFiles, ignore = [], ciVerified = false, hotspots = null, repro = null, validateRuns = null, repoHas = () => false, frozen = null, checkIds = null, guardFailures = null }) {
   const failures = [], superseded = [], ciCovered = [];
   // #4626: a post-deploy check id must be on the default branch or added by this PR (`checkIds`: ids of both checks files; null = not resolved)
   if (checkIds) for (const r of contract.requirements ?? []) {
@@ -435,6 +481,9 @@ export function precheck({ contract, result, changedFiles, ignore = [], ciVerifi
   }
   failures.push(...hotspotGrowth({ contract, result, hotspots, changedFiles }));
   if (repro) failures.push(...reproFailures(contract, repro));
+  // #4693: a broken guard fails unless the contract carries a supersedes amendment for it
+  const retired = new Set((contract.supersedes ?? []).map((s) => s.guard));
+  for (const f of guardFailures ?? []) if (!retired.has(f.guard)) failures.push(f);
   return { ok: failures.length === 0, failures, superseded, ciCovered };
 }
 
@@ -632,6 +681,26 @@ export function checkCompleteness(rv, { contract, changedFiles, issueText, pathE
   return { complete: p.length === 0, problems: p, missing: [...ids] };
 }
 
+
+/** #4726: a requirement quote that carries a `[type:e2e]` criterion. */
+const wantsE2e = (r) => /\[type:e2e\]/i.test(String(r?.quote ?? ""));
+const E2E_CMD_RE = /\b(?:playwright|cypress|e2e|live[- ]stack|wdio)\b/i;
+/**
+ * #4726: whether a validate command runs a real end-to-end check: an entry of `verify.e2e_checks`, a file of the e2e spec set
+ * (`e2e.isSpec`), or Playwright/Cypress/e2e/live-stack. A unit test file with stubbed I/O is not one.
+ */
+export function isE2eCommand(command, e2e = null) {
+  const cmd = String(command ?? "");
+  if ((e2e?.checks ?? []).some((c) => c && cmd.includes(c))) return true;
+  if (typeof e2e?.isSpec === "function" && cmd.split(/\s+/).some((t) => t && e2e.isSpec(t.replace(/^["']+|["']+$/g, "")))) return true;
+  return E2E_CMD_RE.test(cmd);
+}
+/** #4726: true when a V-ref named in the row's `validated_by` resolves to a contract validate command that is a real e2e check. */
+export function e2eVerified(row, contract, e2e = null) {
+  const by = String(row?.validated_by ?? "");
+  const refs = (contract?.validate ?? []).filter((v) => v?.id && new RegExp(`(?:^|[^A-Za-z0-9_])${v.id}(?![A-Za-z0-9_])`).test(by));
+  return refs.some((v) => isE2eCommand(v.command, e2e)) || (!refs.length && isE2eCommand(by, e2e));
+}
 /**
  * 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;
@@ -653,6 +722,8 @@ export function decide(raw, ctx) {
       if (row.instrumented !== true) f.push({ code: C.CONFORMANCE_UNIMPLEMENTED, detail: `${r.id} verified out of band${r.evidence ? ` by ${r.evidence}` : ""}: instrumentation missing${row.note ? `: ${row.note}` : ""}${row.evidence ? ` (${row.evidence})` : ""}` });
     } else if (r.disposition === "deliver" && row.status !== "implemented") {
       f.push({ code: ["deferred", "post-deploy"].includes(row.status) ? C.CONFORMANCE_UNTRACKED_DEFERRAL : C.CONFORMANCE_UNIMPLEMENTED, detail: `${r.amendment?.text ? `${r.id} amendment not accepted (amended to "${String(r.amendment.text).slice(0, 200)}"): ` : `${r.id} `}${row.status}${row.note ? `: ${row.note}` : ""}${row.evidence ? ` (${row.evidence})` : ""}` });
+    } else if (r.disposition === "deliver" && wantsE2e(r) && !e2eVerified(row, ctx.contract, ctx.e2e)) {
+      f.push({ code: C.CONFORMANCE_E2E_UNVERIFIED, detail: `${r.id} is a [type:e2e] criterion but ${row.validated_by || "its validated_by"} is not a real end-to-end check (the repo's e2e set, Playwright/browser/live stack); run one, or mark ${r.id} post-deploy with a tracked follow-up` });
     }
     if (TRACKED.includes(r.disposition) && row.deferral_ok === false) f.push({ code: C.CONFORMANCE_UNJUSTIFIED_DEFERRAL, detail: `${r.id} ${r.disposition} is not justified${row.note ? `: ${row.note}` : ""}; implement it` });
   }
@@ -752,11 +823,54 @@ export function formatShadowSummary(rows) {
   return `conformance: ${sh.length} shadow lane${sh.length === 1 ? "" : "s"}, would block ${would} (${pct(would)}), false-block ${falseB} (${pct(falseB)}: would-block on an incomplete/inconsistent/unparseable review); risk-path enforced: ${risk}`;
 }
 
-/** One line per requirement for the follow-up script: a stable key (id + quote) and a why. Tabs and newlines removed. */
-export function followupItems(reqs) {
+/** #4664: follow-up classes, one issue each per parent (scripts/file-deferred-followups.sh); post-deploy is one rollup per release lane (#4724). */
+export const FOLLOWUP_CLASSES = ["engineering", "post-deploy", "external", "ops"];
+/** #4724: the bucket every deferred row gets at contract time. `date:<YYYY-MM-DD>` and `owner:<action>` carry a value. */
+export const BUCKETS = Object.freeze(["post-deploy", "verify-now", "date", "owner", "new-issue"]);
+const DATE_BUCKET_RE = /^date:(\d{4})-(\d{2})-(\d{2})$/;
+/** The kind of a bucket (`date:2026-12-01` -> `date`), or null when absent or unknown. */
+export const bucketKind = (b) => { const k = String(b ?? "").split(":")[0]; return BUCKETS.includes(k) ? k : null; };
+/** #4724: problems with a deferred row's bucket (a defer or post-deploy row needs exactly one; owner actions are never post-deploy). */
+export function bucketProblems(r) {
+  const b = r?.bucket;
+  if (!TRACKED.includes(r?.disposition)) return b == null ? [] : ["bucket applies only to a defer or post-deploy requirement"];
+  if (b == null || b === "") return [`${r.disposition} needs a bucket (${BUCKETS.join("|")}; \`date:<YYYY-MM-DD>\`, \`owner:<action>\`)`];
+  const k = bucketKind(b), out = [];
+  if (!k || (k !== "date" && k !== "owner" && b !== k)) out.push(`bucket '${b}' must be post-deploy, verify-now, date:<YYYY-MM-DD>, owner:<action> or new-issue`);
+  else if (k === "date") {
+    const m = DATE_BUCKET_RE.exec(String(b)), d = m && new Date(Date.UTC(+m[1], +m[2] - 1, +m[3]));
+    if (!m || d.getUTCFullYear() !== +m[1] || d.getUTCMonth() !== +m[2] - 1 || d.getUTCDate() !== +m[3]) out.push(`bucket '${b}' must be an absolute date:<YYYY-MM-DD>, not a relative wait`);
+  } else if (k === "owner" && blank(String(b).slice(6))) out.push("bucket owner needs the action: owner:<action>");
+  if (r.disposition === "post-deploy" && (k === "owner" || k === "new-issue")) out.push(`a ${k} item is never post-deploy: use disposition defer`);
+  if (k === "owner" && r.class != null && r.class !== "external" && r.class !== "ops") out.push("an owner bucket belongs in class external or ops, never post-deploy");
+  return out;
+}
+/** The follow-up class of a requirement: owner -> external, new-issue -> engineering, other buckets post-deploy; else its `class`, else post-deploy for that disposition, else engineering. */
+export function followupClass(r) {
+  const k = bucketKind(r?.bucket);
+  if (k === "owner") return r?.class === "ops" ? "ops" : "external";
+  if (k === "new-issue") return r?.class && r.class !== "post-deploy" && FOLLOWUP_CLASSES.includes(r.class) ? r.class : "engineering";
+  if (k) return "post-deploy";
+  return FOLLOWUP_CLASSES.includes(r?.class) ? r.class : r?.disposition === "post-deploy" ? "post-deploy" : "engineering";
+}
+/** #4724: deferred items per bucket kind (`none` = no bucket), for the batch telemetry line. */
+export const bucketTally = (reqs) => (reqs ?? []).reduce((t, r) => { const k = bucketKind(r?.bucket) ?? "none"; t[k] = (t[k] ?? 0) + 1; return t; }, {});
+
+/**
+ * One line per requirement for the follow-up script: a stable key (id + quote), a why and a class. Tabs and newlines removed.
+ * #4724: a bucketed row's why carries `[bucket:<kind>]` (the script counts and routes on it) and a date bucket's `due:<date>`
+ * plus `from:<date>` (the contract-time anchor, `now` ms) that the gate re-anchors when the parent ships later.
+ */
+export function followupItems(reqs, { now = Date.now() } = {}) {
   const flat = (s) => String(s ?? "").replace(/[\t\r\n`]+/g, " ").replace(/\s+/g, " ").trim();
   const check = (r) => (r.disposition === "post-deploy" && r.check ? `[check:${flat(r.check)}] ` : ""); // #4626: the follow-up item names its check
-  return reqs.map((r) => ({ id: r.id, key: flat(`${r.id}: ${r.quote}`).slice(0, 240).trim(), why: flat(`${r.disposition}: ${check(r)}${r.why ?? ""}`).slice(0, 400).trim() }));
+  return reqs.map((r) => {
+    const k = bucketKind(r.bucket);
+    const tag = k ? `[bucket:${k}] ` : "";
+    const due = k === "date" ? `due:${String(r.bucket).slice(5)} from:${new Date(now).toISOString().slice(0, 10)} ` : "";
+    const head = k === "owner" ? `owner: ${flat(String(r.bucket).slice(6))}. ` : k && k !== "new-issue" ? "post-deploy: " : `${r.disposition}: `;
+    return { id: r.id, class: followupClass(r), key: flat(`${r.id}: ${r.quote}`).slice(0, 240).trim(), why: flat(`${head}${tag}${check(r)}${due}${r.why ?? ""}`).slice(0, 400).trim() };
+  });
 }
 
 /** #4388: the follow-up script's `key\tissue` lines as {[item.key]: issue}, matched on trimmed keys (the script trims what it echoes); unmatched items omitted. */

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" });
@@ -691,8 +711,109 @@ describe("post-deploy check ids (#4626)", () => {
     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;
+}