forgedock 1.7.1 → 1.8.1

package/bin/engine/admission.mjs

@@ -32,24 +32,82 @@
  * cascade until N tokens spent" — `max_generation` and `token_budget` below
  * are independent levers precisely so that shape of policy is expressible.
  *
- * Hard invariant (NOT configurable by design): safety exclusions — findings
- * whose `## Problem` section indicates security/billing/anti-bot/auth
- * concerns — are never batched and never auto-admitted by ANY policy,
- * including `all`. That exclusion lives upstream of this module (the P3
- * batching eligibility check in `phase-1-resolve.md` / the surface-area
- * batching check in `phase-4-execution.md`) and is intentionally absent
- * from the levers this module resolves.
+ * Billing findings are never batched. Security-relevant P3 findings may only
+ * batch with findings in the same coarse class, with a maximum of three
+ * members. The prose mirrors use `classifyBatchSafety` as their reference.
  */
 
 /** Sentinel string accepted anywhere an "int | unlimited" lever is read. */
 export const UNLIMITED = "unlimited";
 
+const BATCH_SAFETY_CLASSES = [
+  ["billing", /\bbilling\b/i],
+  ["auth", /\b(?:[A-Za-z0-9]*[A-Z][A-Za-z0-9]*[Aa][Uu][Tt][Hh][A-Za-z0-9]*|[Aa][Uu][Tt][Hh](?:[NnZz]?_|[A-Z]))\b|\b(?:authentication|authorization|authn|authz)\b/i],
+  ["injection", /\b(?:inject|injection|xss|csrf|ssrf|deserializ|rce)\w*/i],
+  ["access-control", /\b(?:bypass|escalat|privilege)\w*/i],
+  ["credential", /\b(?:credential|secret|token|password|pgpassword|htpasswd)\w*/i],
+  ["redaction", /\b(?:redact|sanitiz)\w*/i],
+  ["scheme", /\bscheme\b/i],
+  ["traversal", /\btraversal\b/i],
+  ["security", /\b(?:security|anti-bot)\b/i],
+];
+
+/**
+ * Return the batching safety class for title/Problem text. `null` is routine
+ * work; `billing` is an absolute exclusion; every other value is eligible only
+ * for a same-class, maximum-three-member security batch.
+ *
+ * `auth` deliberately matches camelCase/PascalCase and underscore identifiers
+ * (MaintenanceAuth, AdminAuth, authz_check) without matching authority_source.
+ * @param {string} text
+ * @returns {string|null}
+ */
+export function classifyBatchSafety(text) {
+  const findingText = text.replace(/^\*\*Agent\*\*:.*$/gim, "");
+  const explicitClass = findingText.match(/<!--\s*FORGE:CLASS:\s*([a-z0-9-]+)\s*-->/i)?.[1];
+  if (explicitClass) return explicitClass.toLowerCase();
+  return BATCH_SAFETY_CLASSES.find(([, pattern]) => pattern.test(findingText))?.[0] ?? null;
+}
+
+/**
+ * True only for the narrow automated-alert duplicate case. Human-authored
+ * reports and alerts without a stable generator/trigger identity always stay
+ * for investigation.
+ *
+ * @param {Object} canonical
+ * @param {Object} candidate
+ * @returns {boolean}
+ */
+export function canDeduplicateAutomatedAlert(canonical, candidate) {
+  const isAutomated = (issue) =>
+    issue?.authorType === "Bot" || /\[bot\]$/i.test(issue?.authorLogin || "");
+  const normalizeTitle = (title) => String(title || "").trim().replace(/\s+/g, " ").toLowerCase();
+  const hasIdentity = (value) => typeof value === "string" && value.trim() !== "";
+
+  return (
+    isAutomated(canonical) &&
+    isAutomated(candidate) &&
+    normalizeTitle(canonical.title) !== "" &&
+    normalizeTitle(canonical.title) === normalizeTitle(candidate.title) &&
+    hasIdentity(canonical.generator) &&
+    hasIdentity(candidate.generator) &&
+    canonical.generator === candidate.generator &&
+    hasIdentity(canonical.trigger) &&
+    hasIdentity(candidate.trigger) &&
+    canonical.trigger === candidate.trigger
+  );
+}
+
 /**
  * @typedef {Object} CascadePolicy
  * @property {number|typeof UNLIMITED} maxGeneration - Max cascade generation depth
  *   admitted. 1 = only original (non-review-finding-spawned) issues; a
  *   review-finding whose source is itself a review-finding is generation 2,
  *   and so on up the chain. `unlimited` removes the cap entirely.
+ * @property {number} batchMaxGeneration - Deepest review-finding generation that
+ *   may be absorbed into a P3 batch. This is deliberately always finite: batching
+ *   is a bounded aggregation exception to autonomous cascade admission, not an
+ *   alternate path to unlimited recursion.
  * @property {number|typeof UNLIMITED} tokenBudget - Per-batch token ceiling for
  *   Step 4C's review-finding cascade dispatch (mirrors, and by default reads
  *   through to, `pipeline.token_budget_per_batch`). `unlimited` removes the cap.
@@ -59,6 +117,10 @@ export const UNLIMITED = "unlimited";
  *   heuristic defers P3-and-below findings.
  * @property {boolean} p3SameFileDefer - Whether a P3 finding sharing a file with
  *   the active batch is deferred.
+ * @property {number|null} maxAmplification - Maximum findings spawned per merged
+ *   unit before same-lineage refinements are deferred. `null` disables the bound.
+ * @property {number} convergenceWindow - Merged-unit window used to warn when
+ *   amplification remains at or above 1.0.
  */
 
 /**
@@ -78,6 +140,7 @@ export const UNLIMITED = "unlimited";
 export const CASCADE_PRESETS = Object.freeze({
   all: Object.freeze({
     maxGeneration: UNLIMITED,
+    batchMaxGeneration: 2,
     tokenBudget: UNLIMITED,
     deferOnBatchGated: false,
     keywordHeuristic: false,
@@ -85,6 +148,7 @@ export const CASCADE_PRESETS = Object.freeze({
   }),
   balanced: Object.freeze({
     maxGeneration: 1,
+    batchMaxGeneration: 2,
     tokenBudget: 900000,
     deferOnBatchGated: true,
     keywordHeuristic: true,
@@ -92,6 +156,7 @@ export const CASCADE_PRESETS = Object.freeze({
   }),
   conservative: Object.freeze({
     maxGeneration: 1,
+    batchMaxGeneration: 2,
     tokenBudget: 450000,
     deferOnBatchGated: true,
     keywordHeuristic: true,
@@ -101,6 +166,19 @@ export const CASCADE_PRESETS = Object.freeze({
 
 export const DEFAULT_CASCADE_POLICY_NAME = "balanced";
 
+/** Parse an optional positive decimal used for an opt-in ratio ceiling. */
+export function parseOptionalPositiveNumber(raw) {
+  if (raw === undefined || raw === null || raw === "null" || raw === "" || raw === "off") {
+    return { value: null, warning: null };
+  }
+  const n = typeof raw === "number" ? raw : Number(String(raw).trim());
+  if (Number.isFinite(n) && n > 0) return { value: n, warning: null };
+  return {
+    value: null,
+    warning: `not a positive number or "off" ("${raw}") — disabling the bound`,
+  };
+}
+
 /**
  * Parse a raw config value that may be a positive integer, the literal
  * string "unlimited" (case-insensitive), or absent/invalid. Mirrors the
@@ -144,10 +222,13 @@ export function parseIntOrUnlimited(raw, fallback) {
  *   that resolves to `balanced` exactly like today's hardcoded behavior).
  * @param {string} [config.policy]
  * @param {number|string} [config.max_generation]
+ * @param {number|string} [config.batch_max_generation]
  * @param {number|string} [config.token_budget]
  * @param {boolean} [config.defer_on_batch_gated]
  * @param {boolean} [config.keyword_heuristic]
  * @param {boolean} [config.p3_same_file_defer]
+ * @param {number|string} [config.max_amplification]
+ * @param {number|string} [config.convergence_window]
  * @param {number|string} [legacyTokenBudgetPerBatch] - Deprecated-alias fallback:
  *   `pipeline.token_budget_per_batch`, read when `config.token_budget` is absent
  *   so existing configs keep working unchanged (see forge#1858).
@@ -173,6 +254,27 @@ export function resolveCascadePolicy(config = {}, legacyTokenBudgetPerBatch) {
   const maxGen = parseIntOrUnlimited(config.max_generation, preset.maxGeneration);
   if (maxGen.warning) warnings.push(`orchestration.cascade.max_generation ${maxGen.warning}`);
 
+  // Unlike explicit Phase 1 admission, automated batching must retain a finite
+  // recursion bound even under policy: all. Do not accept the unlimited sentinel.
+  const rawBatchMaxGeneration = config.batch_max_generation;
+  const parsedBatchMaxGeneration = Number(rawBatchMaxGeneration);
+  const batchMaxGeneration =
+    rawBatchMaxGeneration === undefined || rawBatchMaxGeneration === null || rawBatchMaxGeneration === ""
+      ? preset.batchMaxGeneration
+      : Number.isInteger(parsedBatchMaxGeneration) && parsedBatchMaxGeneration > 0
+        ? parsedBatchMaxGeneration
+        : preset.batchMaxGeneration;
+  if (
+    rawBatchMaxGeneration !== undefined &&
+    rawBatchMaxGeneration !== null &&
+    rawBatchMaxGeneration !== "" &&
+    !(Number.isInteger(parsedBatchMaxGeneration) && parsedBatchMaxGeneration > 0)
+  ) {
+    warnings.push(
+      `orchestration.cascade.batch_max_generation is not a positive integer ("${rawBatchMaxGeneration}") — falling back to default ${preset.batchMaxGeneration}`,
+    );
+  }
+
   // token_budget precedence: orchestration.cascade.token_budget (new home) >
   // pipeline.token_budget_per_batch (deprecated alias, forge#1858) > preset default.
   // The legacy fallback is validated through parseIntOrUnlimited itself before use —
@@ -195,6 +297,16 @@ export function resolveCascadePolicy(config = {}, legacyTokenBudgetPerBatch) {
     typeof config.keyword_heuristic === "boolean" ? config.keyword_heuristic : preset.keywordHeuristic;
   const p3SameFileDefer =
     typeof config.p3_same_file_defer === "boolean" ? config.p3_same_file_defer : preset.p3SameFileDefer;
+  const maxAmplification = parseOptionalPositiveNumber(config.max_amplification);
+  if (maxAmplification.warning) warnings.push(`orchestration.cascade.max_amplification ${maxAmplification.warning}`);
+  const convergenceWindow = parseIntOrUnlimited(config.convergence_window, 3);
+  if (convergenceWindow.warning || convergenceWindow.value === UNLIMITED) {
+    warnings.push(
+      convergenceWindow.warning
+        ? `orchestration.cascade.convergence_window ${convergenceWindow.warning}`
+        : 'orchestration.cascade.convergence_window cannot be "unlimited" — falling back to default 3',
+    );
+  }
 
   // Both-uncapped notice: neither generation depth nor token spend is bounded this
   // run. This is never a preset default (no preset in CASCADE_PRESETS sets both to
@@ -213,10 +325,13 @@ export function resolveCascadePolicy(config = {}, legacyTokenBudgetPerBatch) {
   return {
     policy: {
       maxGeneration: maxGen.value,
+      batchMaxGeneration,
       tokenBudget: tokenBudget.value,
       deferOnBatchGated,
       keywordHeuristic,
       p3SameFileDefer,
+      maxAmplification: maxAmplification.value,
+      convergenceWindow: convergenceWindow.value === UNLIMITED ? 3 : convergenceWindow.value,
     },
     policyName,
     bothUncapped,
@@ -237,6 +352,18 @@ export function admitsGeneration(generation, policy) {
   return generation <= policy.maxGeneration;
 }
 
+/**
+ * P3 batches may aggregate deferred findings only through this finite ceiling.
+ * The resulting batch must record its maximum member generation for auditability.
+ *
+ * @param {number} generation
+ * @param {CascadePolicy} policy
+ * @returns {boolean}
+ */
+export function admitsBatchGeneration(generation, policy) {
+  return generation <= policy.batchMaxGeneration;
+}
+
 /**
  * @param {number} projectedSpend - BATCH_TOKEN_SPEND if this unit were admitted.
  * @param {CascadePolicy} policy
@@ -247,6 +374,19 @@ export function admitsTokenSpend(projectedSpend, policy) {
   return projectedSpend <= policy.tokenBudget;
 }
 
+/**
+ * Compute the observable cascade amplification signal and opt-in bound state.
+ * The bound is deliberately not an admission decision: callers only apply it
+ * to same-lineage refinements, never to unrelated or high-value findings.
+ */
+export function evaluateAmplification(mergedUnits, findingsSpawned, policy) {
+  const ratio = mergedUnits > 0 ? findingsSpawned / mergedUnits : 0;
+  return {
+    ratio,
+    exceedsBound: policy.maxAmplification !== null && ratio > policy.maxAmplification,
+  };
+}
+
 /**
  * Evaluate the Step 4C rule chain for a single cascade-spawned finding.
  * Mirrors `commands/orchestrate/phase-4-execution.md` Step 4C's "Evaluation
@@ -292,3 +432,98 @@ export function evaluateCascadeFinding(finding, policy) {
   }
   return { admit: true, reason: null };
 }
+
+/**
+ * Deterministic P3 batching rules mirrored by the orchestration specs.
+ * Grouping order is deliberately strongest-context first: a finding can only
+ * belong to one group, so earlier rules claim it before broader rules run.
+ */
+export const P3_BATCHING_RULES = Object.freeze({
+  maxMembers: 8,
+  sameFileMinimum: 2,
+  sourcePrMinimum: 2,
+  defectClassMinimum: 2,
+  leafDirectoryMinimum: 3,
+});
+
+const HIGH_BLAST_RADIUS = /(?:^|\/)(?:\.env\.example|docker-compose[^/]*|compose[^/]*|index\.[^/]+|main\.[^/]+)$/i;
+
+function priorityOf(finding) {
+  const labels = (finding.labels || []).map((label) => typeof label === "string" ? label : label?.name);
+  return labels.find((label) => /^priority:P[0-3]$/.test(label))?.slice(-2) || labels.find((label) => /^P[0-3]$/.test(label)) || "P3";
+}
+
+/** Priority is urgency, not risk: only P0/P1 stay individual for latency. */
+export function batchExclusionReason(finding, dangerZones = []) {
+  if (["P0", "P1"].includes(priorityOf(finding))) return "urgency";
+  const file = finding.affectedFile || "";
+  if (/^infra\/migrations\/.*credit_balance/i.test(file) || /^services\/api\/app\/billing\//i.test(file)) return "domain";
+  if (dangerZones.some((zone) => file === zone || file.startsWith(`${zone}/`))) return "domain";
+  if (/\/migrations?\//i.test(file) || HIGH_BLAST_RADIUS.test(file)) return "high-blast-radius";
+  return classifyBatchSafety(`${finding.title || ""}\n${finding.body || ""}`) === "billing" ? "domain" : null;
+}
+
+function sourcePr(body = "") {
+  return body.match(/^\*\*Source\*\*: PR #(\d+)\b/m)?.[1] || null;
+}
+
+function defectClass(body = "") {
+  return body.match(/<!-- FORGE:CLASS: ([a-z0-9]+(?:-[a-z0-9]+)*) -->/)?.[1] || null;
+}
+
+function leafDirectory(file = "") {
+  const slash = file.lastIndexOf("/");
+  return slash > 0 ? file.slice(0, slash) : null;
+}
+
+/**
+ * Plan P3 batches from already safety-filtered, open, unbatched, undispatched
+ * findings. The caller executes these groups and preserves unclaimed findings
+ * for a later full-queue sweep.
+ */
+export function planP3BatchGroups(findings, rules = P3_BATCHING_RULES, { openBatches = [], dangerZones = [] } = {}) {
+  const remaining = new Map(
+    findings
+      .filter((finding) => finding?.number && finding.affectedFile && !batchExclusionReason(finding, dangerZones))
+      .map((finding) => [finding.number, finding]),
+  );
+  const groups = [];
+  const extensions = [];
+
+  for (const batch of openBatches) {
+    const key = batch.affectedFile || batch.key;
+    const headroom = rules.maxMembers - (batch.memberCount ?? batch.members?.length ?? 0);
+    if (!key || headroom <= 0) continue;
+    for (const member of batch.members || []) remaining.delete(typeof member === "object" ? member.number : member);
+    const members = [...remaining.values()].filter((finding) => finding.affectedFile === key).slice(0, headroom);
+    if (members.length) {
+      extensions.push({ batch: batch.number, key, members: members.map((finding) => finding.number) });
+      members.forEach((finding) => remaining.delete(finding.number));
+    }
+  }
+
+  const claim = (kind, key, minimum) => {
+    const byKey = new Map();
+    for (const finding of remaining.values()) {
+      const groupKey = key(finding);
+      if (!groupKey) continue;
+      const members = byKey.get(groupKey) || [];
+      members.push(finding);
+      byKey.set(groupKey, members);
+    }
+    for (const [groupKey, members] of [...byKey].sort(([a], [b]) => a.localeCompare(b))) {
+      while (members.length >= minimum) {
+        const chunk = members.splice(0, rules.maxMembers);
+        groups.push({ kind, key: groupKey, members: chunk.map((finding) => finding.number) });
+        chunk.forEach((finding) => remaining.delete(finding.number));
+      }
+    }
+  };
+
+  claim("same-file", (finding) => finding.affectedFile, rules.sameFileMinimum);
+  claim("source-pr", (finding) => sourcePr(finding.body), rules.sourcePrMinimum);
+  claim("defect-class", (finding) => defectClass(finding.body), rules.defectClassMinimum);
+  claim("leaf-directory", (finding) => leafDirectory(finding.affectedFile), rules.leafDirectoryMinimum);
+
+  return { groups, extensions, ungrouped: [...remaining.keys()] };
+}

package/bin/engine/admission.test.mjs

@@ -5,12 +5,73 @@ import {
   CASCADE_PRESETS,
   DEFAULT_CASCADE_POLICY_NAME,
   parseIntOrUnlimited,
+  parseOptionalPositiveNumber,
   resolveCascadePolicy,
   admitsGeneration,
+  admitsBatchGeneration,
   admitsTokenSpend,
   evaluateCascadeFinding,
+  classifyBatchSafety,
+  evaluateAmplification,
+  batchExclusionReason,
+  planP3BatchGroups,
+  canDeduplicateAutomatedAlert,
 } from "./admission.mjs";
 
+describe("classifyBatchSafety", () => {
+  it("classifies the six security findings that previously evaded batching exclusion", () => {
+    const fixtures = [
+      ["MaintenanceAuth alias bypasses write rate limit", "auth"],
+      ["nested bash -c double substitution permits command injection", "injection"],
+      ["CTA href needs scheme validation to reject javascript URIs", "scheme"],
+      ["Discord markdown code-fence injection from log samples", "injection"],
+      ["redact raw psql DETAIL and CONTEXT on migration failure", "redaction"],
+      ["PGPASSWORD interpolated into a SQL literal", "credential"],
+    ];
+    for (const [text, expected] of fixtures) {
+      assert.equal(classifyBatchSafety(text), expected, text);
+    }
+  });
+
+  it("keeps the documented false positives batchable while matching identifier auth", () => {
+    assert.equal(classifyBatchSafety("authority_source docstring fix"), null);
+    assert.equal(classifyBatchSafety("**Agent**: Security\n## Problem\nstale docstring count"), null);
+    assert.equal(classifyBatchSafety("AdminAuth and authz_check must reject bypasses"), "auth");
+    assert.equal(classifyBatchSafety("injection\n<!-- FORGE:CLASS: shell-hardening -->"), "shell-hardening");
+  });
+});
+
+describe("canDeduplicateAutomatedAlert", () => {
+  const canonical = {
+    authorType: "Bot",
+    authorLogin: "github-actions[bot]",
+    title: "Backup restore drill failed",
+    generator: "backup-restore-drill.yml",
+    trigger: "corrupt-backup-fixture-v1",
+  };
+
+  it("permits only byte-for-byte equivalent machine alerts after title normalization", () => {
+    assert.equal(
+      canDeduplicateAutomatedAlert(canonical, {
+        ...canonical,
+        authorLogin: "app[bot]",
+        title: "  backup   restore drill FAILED ",
+      }),
+      true,
+    );
+  });
+
+  it("rejects human reports and differing generators or triggers", () => {
+    assert.equal(
+      canDeduplicateAutomatedAlert(canonical, { ...canonical, authorType: "User", authorLogin: "person" }),
+      false,
+    );
+    assert.equal(canDeduplicateAutomatedAlert(canonical, { ...canonical, generator: "other.yml" }), false);
+    assert.equal(canDeduplicateAutomatedAlert(canonical, { ...canonical, trigger: "other-fixture" }), false);
+    assert.equal(canDeduplicateAutomatedAlert(canonical, { ...canonical, generator: undefined }), false);
+  });
+});
+
 describe("parseIntOrUnlimited", () => {
   it("parses a positive integer", () => {
     assert.deepEqual(parseIntOrUnlimited("3", 1), { value: 3, warning: null });
@@ -39,17 +100,36 @@ describe("parseIntOrUnlimited", () => {
   });
 });
 
+describe("parseOptionalPositiveNumber", () => {
+  it("defaults to disabled and accepts a positive decimal", () => {
+    assert.deepEqual(parseOptionalPositiveNumber(undefined), { value: null, warning: null });
+    assert.deepEqual(parseOptionalPositiveNumber("off"), { value: null, warning: null });
+    assert.deepEqual(parseOptionalPositiveNumber("1.5"), { value: 1.5, warning: null });
+  });
+
+  it("disables invalid values with a warning", () => {
+    const result = parseOptionalPositiveNumber("0");
+    assert.equal(result.value, null);
+    assert.match(result.warning, /disabling the bound/);
+  });
+});
+
 describe("resolveCascadePolicy — presets", () => {
   it("defaults to balanced when no config is given (no-op, matches pre-#2234 hardcoded behavior)", () => {
     const { policy, policyName, warnings } = resolveCascadePolicy();
     assert.equal(policyName, DEFAULT_CASCADE_POLICY_NAME);
-    assert.deepEqual(policy, CASCADE_PRESETS.balanced);
+    assert.deepEqual(policy, {
+      ...CASCADE_PRESETS.balanced,
+      maxAmplification: null,
+      convergenceWindow: 3,
+    });
     assert.deepEqual(warnings, []);
   });
 
   it("policy: all removes both caps and disables every heuristic", () => {
     const { policy, warnings } = resolveCascadePolicy({ policy: "all" });
     assert.equal(policy.maxGeneration, UNLIMITED);
+    assert.equal(policy.batchMaxGeneration, 2);
     assert.equal(policy.tokenBudget, UNLIMITED);
     assert.equal(policy.deferOnBatchGated, false);
     assert.equal(policy.keywordHeuristic, false);
@@ -65,6 +145,7 @@ describe("resolveCascadePolicy — presets", () => {
   it("policy: conservative keeps balanced's shape but lowers the token budget", () => {
     const { policy } = resolveCascadePolicy({ policy: "conservative" });
     assert.equal(policy.maxGeneration, 1);
+    assert.equal(policy.batchMaxGeneration, 2);
     assert.equal(policy.tokenBudget, 450000);
     assert.equal(policy.deferOnBatchGated, true);
   });
@@ -72,7 +153,11 @@ describe("resolveCascadePolicy — presets", () => {
   it("unrecognized policy name falls back to balanced with a warning", () => {
     const { policy, policyName, warnings } = resolveCascadePolicy({ policy: "yolo" });
     assert.equal(policyName, "balanced");
-    assert.deepEqual(policy, CASCADE_PRESETS.balanced);
+    assert.deepEqual(policy, {
+      ...CASCADE_PRESETS.balanced,
+      maxAmplification: null,
+      convergenceWindow: 3,
+    });
     assert.equal(warnings.length, 1);
     assert.match(warnings[0], /not one of/);
   });
@@ -87,6 +172,8 @@ describe("resolveCascadePolicy — granular overrides compose with a preset", ()
     assert.equal(policy.deferOnBatchGated, true);
     assert.equal(policy.keywordHeuristic, true);
     assert.equal(policy.p3SameFileDefer, true);
+    assert.equal(policy.maxAmplification, null);
+    assert.equal(policy.convergenceWindow, 3);
   });
 
   it("granular boolean overrides on top of the all preset", () => {
@@ -104,6 +191,32 @@ describe("resolveCascadePolicy — granular overrides compose with a preset", ()
     assert.equal(admitsGeneration(3, policy), true);
     assert.equal(admitsGeneration(4, policy), false);
   });
+
+  it("keeps batching finite even when explicit cascade admission is unlimited", () => {
+    const { policy } = resolveCascadePolicy({ policy: "all" });
+    assert.equal(admitsBatchGeneration(2, policy), true);
+    assert.equal(admitsBatchGeneration(3, policy), false);
+  });
+
+  it("allows a repository to set a different finite batching ceiling", () => {
+    const { policy } = resolveCascadePolicy({ batch_max_generation: 3 });
+    assert.equal(policy.batchMaxGeneration, 3);
+    assert.equal(admitsBatchGeneration(3, policy), true);
+    assert.equal(admitsBatchGeneration(4, policy), false);
+  });
+});
+
+describe("evaluateAmplification", () => {
+  it("reports the running ratio without bounding the default policy", () => {
+    const { policy } = resolveCascadePolicy();
+    assert.deepEqual(evaluateAmplification(2, 3, policy), { ratio: 1.5, exceedsBound: false });
+  });
+
+  it("flags an opt-in bound only after the ratio exceeds it", () => {
+    const { policy } = resolveCascadePolicy({ max_amplification: 1 });
+    assert.equal(evaluateAmplification(2, 2, policy).exceedsBound, false);
+    assert.equal(evaluateAmplification(2, 3, policy).exceedsBound, true);
+  });
 });
 
 describe("resolveCascadePolicy — token_budget deprecated-alias fallback", () => {
@@ -263,3 +376,71 @@ describe("evaluateCascadeFinding — Step 4C rule-chain parity", () => {
     assert.match(result.reason, /token budget exhausted/);
   });
 });
+
+describe("planP3BatchGroups — concern-level P3 batching", () => {
+  const finding = (number, affectedFile, body = "") => ({ number, affectedFile, body });
+
+  it("keeps same-file grouping ahead of every broader key", () => {
+    const plan = planP3BatchGroups([
+      finding(1, "infra/monitoring/a.yml", "**Source**: PR #42"),
+      finding(2, "infra/monitoring/a.yml", "**Source**: PR #42"),
+      finding(3, "infra/monitoring/b.yml", "**Source**: PR #42"),
+    ]);
+    assert.deepEqual(plan.groups, [
+      { kind: "same-file", key: "infra/monitoring/a.yml", members: [1, 2] },
+    ]);
+    assert.deepEqual(plan.ungrouped, [3]);
+  });
+
+  it("groups all remaining findings from one source PR cohort", () => {
+    const plan = planP3BatchGroups([
+      finding(1, "infra/monitoring/a.yml", "**Source**: PR #42"),
+      finding(2, "infra/monitoring/b.yml", "**Source**: PR #42"),
+      finding(3, "scripts/a.sh", "**Source**: PR #42"),
+      finding(4, "README.md", "**Source**: PR #42"),
+    ]);
+    assert.deepEqual(plan.groups, [
+      { kind: "source-pr", key: "42", members: [1, 2, 3, 4] },
+    ]);
+    assert.deepEqual(plan.ungrouped, []);
+  });
+
+  it("groups explicit defect classes across files", () => {
+    const plan = planP3BatchGroups([
+      finding(1, "infra/monitoring/a.yml", "<!-- FORGE:CLASS: fail-loud-check -->"),
+      finding(2, "scripts/check.sh", "<!-- FORGE:CLASS: fail-loud-check -->"),
+    ]);
+    assert.deepEqual(plan.groups, [
+      { kind: "defect-class", key: "fail-loud-check", members: [1, 2] },
+    ]);
+  });
+
+  it("lowers leaf-directory grouping to three and caps batches at eight", () => {
+    const three = planP3BatchGroups([
+      finding(1, "scripts/a.sh"), finding(2, "scripts/b.sh"), finding(3, "scripts/c.sh"),
+    ]);
+    assert.deepEqual(three.groups, [{ kind: "leaf-directory", key: "scripts", members: [1, 2, 3] }]);
+
+    const nine = planP3BatchGroups(Array.from({ length: 9 }, (_, index) => finding(index + 1, `scripts/${index}.sh`)));
+    assert.deepEqual(nine.groups, [{ kind: "leaf-directory", key: "scripts", members: [1, 2, 3, 4, 5, 6, 7, 8] }]);
+    assert.deepEqual(nine.ungrouped, [9]);
+  });
+
+  it("extends compatible open batches before creating another one", () => {
+    const plan = planP3BatchGroups(
+      [finding(1, "scripts/a.sh"), finding(2, "scripts/a.sh")],
+      undefined,
+      { openBatches: [{ number: 99, affectedFile: "scripts/a.sh", members: [1], memberCount: 7 }] },
+    );
+    assert.deepEqual(plan.extensions, [{ batch: 99, key: "scripts/a.sh", members: [2] }]);
+    assert.deepEqual(plan.groups, []);
+  });
+
+  it("uses urgency and path risk instead of excluding every P2 finding", () => {
+    assert.equal(batchExclusionReason({ labels: ["priority:P2"], affectedFile: "scripts/a.sh" }), null);
+    assert.equal(batchExclusionReason({ labels: ["priority:P1"], affectedFile: "scripts/a.sh" }), "urgency");
+    assert.equal(batchExclusionReason({ labels: ["priority:P2"], affectedFile: "infra/migrations/0333_credit_balance.sql" }), "domain");
+    assert.equal(batchExclusionReason({ labels: ["priority:P2"], affectedFile: "services/api/app/billing/charge.py" }), "domain");
+    assert.equal(batchExclusionReason({ labels: ["priority:P2"], affectedFile: ".env.example" }), "high-blast-radius");
+  });
+});