@codyswann/lisa 3.11.4 → 3.11.7

package/rails/copy-overwrite/scripts/check-threshold-ratchet.mjs

@@ -24,6 +24,13 @@
  * itself an exception in the same change that weakens a gate. `key: "*"`
  * allows every key in the file.
  *
+ * One exception, and only one: a PROMOTION between deploy-chain branches
+ * (`--base` + `--head`, both named in `deploy.branches`, head upstream of
+ * base, head fully containing base). There the allow list is read from the
+ * head, because the change under review is the baseline plus history that has
+ * already passed this same gate. See `isPromotion` for why that is the only
+ * discriminator that holds.
+ *
  * Extraction lives in threshold-ratchet-families.mjs; comparison rules in
  * threshold-ratchet-compare.mjs. Zero dependencies.
  */
@@ -131,6 +138,148 @@ function resolvePlan(mode, root, baseRef, onlyFiles) {
   };
 }
 
+/**
+ * Strip a remote prefix so `origin/staging` and `staging` compare equal to a
+ * branch name declared in `.lisa.config.json`.
+ * @param {string} ref Git ref, possibly remote-qualified
+ * @returns {string} Bare branch name
+ */
+function bareBranch(ref) {
+  return ref.replace(/^refs\/heads\//u, "").replace(/^origin\//u, "");
+}
+
+/**
+ * The deploy chain, earliest environment first, from `deploy.branches`.
+ *
+ * Declaration order IS the chain order — that is already how Lisa reads it
+ * (dev → staging → production), and it is what makes "upstream of" decidable.
+ * @param {unknown} config Parsed `.lisa.config.json`
+ * @returns {string[]} Branch names in chain order
+ */
+function deployChain(config) {
+  const branches = config?.deploy?.branches;
+  if (!branches || typeof branches !== "object") return [];
+  return Object.values(branches).filter(b => typeof b === "string" && b !== "");
+}
+
+/**
+ * Whether this is a promotion of one deploy-chain branch into the next.
+ *
+ * A promotion carries approved history into a branch that is behind, so the
+ * exemptions it brings with it are not new — each one already faced this gate
+ * on the upstream branch. Reading the allow list from the baseline there
+ * reports every one of them as newly added, and the documented remedy is
+ * circular: recording them means adding `thresholdRatchet.allow` entries,
+ * which is itself the Tier 3 change being blocked. That deadlocked the whole
+ * promotion lane (#2531).
+ *
+ * The discriminator is branch IDENTITY, not ancestry. "The head contains the
+ * base" is true of any ordinary topic branch that is up to date with its base
+ * — and a repository with a strict up-to-date branch-protection rule REQUIRES
+ * that of every PR — so ancestry alone would hand self-approval to exactly the
+ * changes Tier 3 exists to stop. Being a deploy-chain branch cannot be
+ * arranged by a topic branch: those branches are protected, so everything on
+ * them arrived through a reviewed PR that passed this same ratchet.
+ *
+ * Ancestry is still required, as a second condition rather than the only one:
+ * a head that has diverged from its base is not "the baseline plus approved
+ * history", and the strict reading should stand.
+ *
+ * The chain is read from the BASELINE config, so a change cannot declare
+ * itself a promotion by adding `deploy.branches` entries in the same commit.
+ * @param {string} root Repo root
+ * @param {unknown} baselineConfig `.lisa.config.json` at the baseline
+ * @param {string | undefined} baseRef Ref being merged into
+ * @param {string | undefined} headRef Ref being merged from
+ * @returns {boolean} True when the allow list may be read from the head
+ */
+function isPromotion(root, baselineConfig, baseRef, headRef) {
+  if (!baseRef || !headRef) return false;
+  const chain = deployChain(baselineConfig);
+  const basePosition = chain.indexOf(bareBranch(baseRef));
+  const headPosition = chain.indexOf(bareBranch(headRef));
+  if (basePosition === -1 || headPosition === -1) return false;
+  if (headPosition >= basePosition) return false;
+  // Empty string on success, null when git exits non-zero or the ref is bogus.
+  if (git(["merge-base", "--is-ancestor", baseRef, headRef], root) !== null) {
+    return true;
+  }
+  // Both ARE deploy-chain branches, so this is a promotion that has diverged —
+  // typically a hotfix that landed on the base and was never synced down. The
+  // strict reading is correct here, but silence would leave an operator
+  // guessing why this promotion behaves differently from the last one.
+  process.stderr.write(
+    `threshold-ratchet: ${bareBranch(headRef)} does not contain ` +
+      `${bareBranch(baseRef)}, so this promotion is not the baseline plus ` +
+      `approved history and the allow list is read from the baseline. Sync ` +
+      `${bareBranch(baseRef)} down into ${bareBranch(headRef)} first.\n`
+  );
+  return false;
+}
+
+/**
+ * Resolve the allow list and say where it came from.
+ * @param {string} root Repo root
+ * @param {string} baselineRef Ref the comparison baselines against
+ * @param {"hook"|"staged"|"base"} mode Comparison mode
+ * @param {string | undefined} baseRef Base ref (base mode only)
+ * @param {string | undefined} headRef Head ref (base mode only)
+ * @returns {{ entries: object[], promotion: boolean, note: string | null }}
+ *   Entries, whether this is a promotion, and an audit line to print when the
+ *   entries came from anywhere but the baseline
+ */
+function resolveAllowList(root, baselineRef, mode, baseRef, headRef) {
+  const baselineConfig = parseJson(
+    git(["show", `${baselineRef}:.lisa.config.json`], root)
+  );
+  if (mode !== "base" || !isPromotion(root, baselineConfig, baseRef, headRef)) {
+    return {
+      entries: extractAllowEntries(baselineConfig),
+      promotion: false,
+      note: null,
+    };
+  }
+  return {
+    entries: extractAllowEntries(
+      parseJson(git(["show", "HEAD:.lisa.config.json"], root))
+    ),
+    promotion: true,
+    note:
+      `threshold-ratchet: promotion ${bareBranch(headRef)} → ` +
+      `${bareBranch(baseRef)}; both are deploy-chain branches declared at ` +
+      `${baselineRef} and the head fully contains the base, so the allow list ` +
+      `is read from the head. Exemptions below were approved upstream, not by ` +
+      `this change.`,
+  };
+}
+
+/**
+ * Split off the allow-entry additions a promotion is carrying forward.
+ *
+ * `applyAllowList` never drops an `allow-added` finding, from either side —
+ * an exception must not approve its own creation. That is right for an
+ * ordinary PR and wrong for a promotion, where the entry is not being created:
+ * it already exists on the upstream branch, where its creation faced this same
+ * unconditional block and needed a human to clear it. Without this the fix
+ * would be cosmetic — a promotion carrying an approved exemption also carries
+ * the `.lisa.config.json` diff that records it, so it would still be blocked
+ * by the finding for the record of its own approval.
+ *
+ * Only `allow-added` is carried. An actual threshold weakening in the same
+ * promotion still has to be covered by an allow entry.
+ * @param {Array<{ type: string }>} findings All findings from the change
+ * @param {boolean} promotion Whether the change is a recognised promotion
+ * @returns {{ carried: object[], rest: object[] }} Findings excused as already
+ *   approved upstream, and findings still subject to the allow list
+ */
+function partitionCarriedEntries(findings, promotion) {
+  if (!promotion) return { carried: [], rest: findings };
+  return {
+    carried: findings.filter(f => f.type === "allow-added"),
+    rest: findings.filter(f => f.type !== "allow-added"),
+  };
+}
+
 /**
  * Decide the exit code when the ratchet cannot determine what changed.
  *
@@ -161,9 +310,11 @@ function undeterminable(mode, reason) {
  * @param {"hook"|"staged"|"base"} mode Comparison mode
  * @param {string | undefined} [baseRef] Base ref (base mode only)
  * @param {string[] | undefined} [onlyFiles] Restrict to these paths (hook mode)
+ * @param {string | undefined} [headRef] Head ref (base mode only), used solely
+ *   to recognise a promotion between deploy-chain branches
  * @returns {number} Process exit code (2 for hook mode, 1 otherwise; 0 clean)
  */
-function run(mode, baseRef, onlyFiles) {
+function run(mode, baseRef, onlyFiles, headRef) {
   const root = git(["rev-parse", "--show-toplevel"])?.trim();
   if (!root) return undeterminable(mode, "not a git repository");
   const plan = resolvePlan(mode, root, baseRef, onlyFiles);
@@ -205,13 +356,21 @@ function run(mode, baseRef, onlyFiles) {
   );
   if (findings.length === 0) return 0;
 
-  const baselineConfig = parseJson(
-    git(["show", `${plan.baselineRef}:.lisa.config.json`], root)
-  );
-  const { blocked, allowed } = applyAllowList(
-    findings,
-    extractAllowEntries(baselineConfig)
+  const allow = resolveAllowList(
+    root,
+    plan.baselineRef,
+    mode,
+    baseRef,
+    headRef
   );
+  const split = partitionCarriedEntries(findings, allow.promotion);
+  const { blocked, allowed } = applyAllowList(split.rest, allow.entries);
+  if (allow.note) process.stdout.write(`${allow.note}\n`);
+  for (const finding of split.carried) {
+    process.stdout.write(
+      `threshold-ratchet: carried forward by this promotion, approved upstream — ${finding.message}\n`
+    );
+  }
   for (const finding of allowed) {
     process.stdout.write(
       `threshold-ratchet: allowed by .lisa.config.json exception — ${finding.message}\n`
@@ -257,11 +416,16 @@ function runHookMode() {
  */
 function main() {
   const args = process.argv.slice(2);
+  const headIndex = args.indexOf("--head");
+  const headRef = headIndex === -1 ? undefined : args[headIndex + 1];
   if (args[0] === "--staged") return run("staged");
-  if (args[0] === "--base") return run("base", args[1]);
+  // `--head` is optional and additive: a caller that omits it gets exactly the
+  // behavior that shipped before promotions were recognised, so an older
+  // workflow driving a newer script stays strict rather than silently relaxing.
+  if (args[0] === "--base") return run("base", args[1], undefined, headRef);
   if (args[0] === "--hook") return runHookMode();
   process.stderr.write(
-    "usage: threshold-ratchet.mjs --hook | --staged | --base <ref>\n"
+    "usage: threshold-ratchet.mjs --hook | --staged | --base <ref> [--head <ref>]\n"
   );
   return 0;
 }

package/scripts/check-required-check-promotions.mjs

@@ -69,6 +69,48 @@
  *     `measured_on_subject` separately makes that mechanically visible instead
  *     of a footnote in a report.
  *
+ *  6. **A worst case must come from a run that COMPLETED, and must be below the
+ *     budget it justifies** (#2528). Two clauses, one rule:
+ *
+ *     *Do not size a budget from the duration of a run that failed on time.*
+ *     This is the mirror of clause 3. #2509 says do not size from runs that
+ *     passed, because the sample excludes the failure mode; the mirror says do
+ *     not size from the DURATION of a run the budget terminated, because that
+ *     duration is the starvation, not the work. The failing-run version is
+ *     strictly worse: it does not merely omit information, it INVERTS the
+ *     ratio — the more contended the box was, the safer the resulting budget
+ *     looks. So `observed_on` must say `"pass"`, meaning the measured run
+ *     completed inside its budget. (That is a statement about TIME, not about
+ *     the check's verdict: a run that reproduces a real violation and exits 1
+ *     in 30s completed, and is `"pass"` here.)
+ *
+ *     *And an entry claiming a worst case at or above its own budget refuses
+ *     itself*, needing no knowledge of the test, the machine, or the workload.
+ *     #2523 cited 60,245ms while setting the budget to 60,000ms. The ratio in
+ *     clause 4 already rejects that arithmetically at 0.996x, but it reports a
+ *     THIN MARGIN when the defect is an IMPOSSIBLE CLAIM, and a message that
+ *     misnames the defect sends the reader off to re-measure when they should
+ *     be re-reading. The tell was on the face of the number: a test cannot run
+ *     60s against a 10s budget, so 60,245ms was wall clock spent waiting.
+ *     Re-measured in isolation at load 31 the same test takes 2,499ms — 24x,
+ *     not 0.996x, a 24-fold error in the unsafe direction.
+ *
+ *     The class is not specific to test timeouts. #2520 chased an actionlint
+ *     invocation reported as taking "25 minutes". It was not slow: a
+ *     3,490-line workflow returns in 0s while a 217-line one hangs, and the
+ *     minimal repro is 28 lines. It is a spin inside actionlint's shellcheck
+ *     integration — ~850% CPU across 37 threads, zero children — so it never
+ *     terminates. The 25 minutes was the observer's patience, not the
+ *     command's cost, and NO budget would have been generous enough. That is
+ *     what `observed_on` refuses: a number produced by a run that did not
+ *     finish is not a measurement of how long the work takes.
+ *
+ *     A missing `observed_on` is refused rather than grandfathered. Every
+ *     `proven` entry in the ledger when this clause shipped had already
+ *     recorded, in prose, that its worst case came from runs that completed, so
+ *     backfilling the field only restates what was already proved. Exempting
+ *     them would have exempted the only entries the clause could bind on.
+ *
  * ## The ratchet, and why incumbents are not simply exempted
  *
  * Contexts already required when this guard shipped may declare
@@ -315,9 +357,47 @@ function budgetProblems(budget) {
       },
     ];
   }
+  // A budgets[] entry publishes its OWN observed_worst_ms, so it can be a
+  // starved figure exactly as the block-level one can. Checking provenance
+  // first: a ratio computed from a duration that measures contention is
+  // arithmetic on the wrong number, so the reader needs the provenance before
+  // the margin.
+  const provenance = provenanceProblems(budget.observed_on);
+  if (provenance.length > 0) return provenance;
   return ratioProblems(budget.budget_ms, budget.observed_worst_ms);
 }
 
+/**
+ * Validate where an observed worst case was measured (#2528).
+ *
+ * `observed_on` records whether the run that produced `observed_worst_ms`
+ * COMPLETED within its budget (`"pass"`) or was terminated by it (`"fail"`).
+ * That is a claim about time, not about the check's verdict — a run that
+ * reproduces a real violation and exits 1 well inside its budget completed.
+ *
+ * @param {unknown} observedOn - the declared provenance.
+ * @returns {{ rule: string, detail: string }[]} problems, empty when sound.
+ */
+function provenanceProblems(observedOn) {
+  if (observedOn === "pass") return [];
+  if (observedOn === "fail") {
+    return [
+      {
+        rule: "headroom-measured-on-failing-run",
+        detail:
+          'observed_worst_ms was taken from a run the budget terminated ("observed_on": "fail"); that duration is the starvation, not the work, and the more contended the box was the safer the budget looks — re-measure on a run that completed, in isolation',
+      },
+    ];
+  }
+  return [
+    {
+      rule: "headroom-evidence-missing",
+      detail:
+        'headroom.observed_on must be "pass": the run that produced observed_worst_ms must have COMPLETED within its budget, because a duration reported alongside a timeout measures contention, not cost',
+    },
+  ];
+}
+
 /**
  * Compare an observed worst case against its budget.
  *
@@ -340,6 +420,17 @@ function ratioProblems(budgetMs, observedMs) {
       },
     ];
   }
+  // Checked before the ratio, and reported as its own defect: an entry whose
+  // worst case is not below the budget it justifies can never be valid, and
+  // "thin margin" would misname it. See clause 6 in the module preamble.
+  if (observedMs >= budgetMs) {
+    return [
+      {
+        rule: "headroom-worst-case-exceeds-budget",
+        detail: `observed worst ${observedMs}ms is not below the ${budgetMs}ms budget it justifies, so the entry disproves itself; a worst case at or above its own budget is usually elapsed time from a run the budget terminated, which measures contention rather than cost (#2528)`,
+      },
+    ];
+  }
   const ratio = budgetMs / observedMs;
   if (ratio < MIN_HEADROOM_RATIO) {
     return [
@@ -394,6 +485,8 @@ export function headroomProblems(headroom) {
     }
   }
   if (problems.length > 0) return problems;
+  problems.push(...provenanceProblems(headroom.observed_on));
+  if (problems.length > 0) return problems;
   problems.push(
     ...ratioProblems(headroom.budget_ms, headroom.observed_worst_ms)
   );

package/typescript/copy-overwrite/ast-grep/rule-tests/.gitkeep

@@ -1,8 +1,8 @@
 # Test cases for the ast-grep rules in ../rules/.
 #
-# These run. `ast-grep test` is wired to the `sg:test` package script and to
-# the AST Grep Scan job in Lisa's quality workflow, so a wrong assertion here
-# fails CI. The job counts the YAML files in this directory first: an empty
+# These run. The AST Grep Scan job in Lisa's quality workflow invokes the
+# `ast-grep` binary directly, so a wrong assertion here fails CI whether or not
+# this project has run `lisa apply` since the step shipped. The job counts the YAML files in this directory first: an empty
 # directory is reported as a skipped step with a warning, never as a pass,
 # because `ast-grep test` exits 0 when it finds nothing to run.
 #

package/typescript/copy-overwrite/scripts/check-threshold-ratchet.mjs

@@ -24,6 +24,13 @@
  * itself an exception in the same change that weakens a gate. `key: "*"`
  * allows every key in the file.
  *
+ * One exception, and only one: a PROMOTION between deploy-chain branches
+ * (`--base` + `--head`, both named in `deploy.branches`, head upstream of
+ * base, head fully containing base). There the allow list is read from the
+ * head, because the change under review is the baseline plus history that has
+ * already passed this same gate. See `isPromotion` for why that is the only
+ * discriminator that holds.
+ *
  * Extraction lives in threshold-ratchet-families.mjs; comparison rules in
  * threshold-ratchet-compare.mjs. Zero dependencies.
  */
@@ -131,6 +138,148 @@ function resolvePlan(mode, root, baseRef, onlyFiles) {
   };
 }
 
+/**
+ * Strip a remote prefix so `origin/staging` and `staging` compare equal to a
+ * branch name declared in `.lisa.config.json`.
+ * @param {string} ref Git ref, possibly remote-qualified
+ * @returns {string} Bare branch name
+ */
+function bareBranch(ref) {
+  return ref.replace(/^refs\/heads\//u, "").replace(/^origin\//u, "");
+}
+
+/**
+ * The deploy chain, earliest environment first, from `deploy.branches`.
+ *
+ * Declaration order IS the chain order — that is already how Lisa reads it
+ * (dev → staging → production), and it is what makes "upstream of" decidable.
+ * @param {unknown} config Parsed `.lisa.config.json`
+ * @returns {string[]} Branch names in chain order
+ */
+function deployChain(config) {
+  const branches = config?.deploy?.branches;
+  if (!branches || typeof branches !== "object") return [];
+  return Object.values(branches).filter(b => typeof b === "string" && b !== "");
+}
+
+/**
+ * Whether this is a promotion of one deploy-chain branch into the next.
+ *
+ * A promotion carries approved history into a branch that is behind, so the
+ * exemptions it brings with it are not new — each one already faced this gate
+ * on the upstream branch. Reading the allow list from the baseline there
+ * reports every one of them as newly added, and the documented remedy is
+ * circular: recording them means adding `thresholdRatchet.allow` entries,
+ * which is itself the Tier 3 change being blocked. That deadlocked the whole
+ * promotion lane (#2531).
+ *
+ * The discriminator is branch IDENTITY, not ancestry. "The head contains the
+ * base" is true of any ordinary topic branch that is up to date with its base
+ * — and a repository with a strict up-to-date branch-protection rule REQUIRES
+ * that of every PR — so ancestry alone would hand self-approval to exactly the
+ * changes Tier 3 exists to stop. Being a deploy-chain branch cannot be
+ * arranged by a topic branch: those branches are protected, so everything on
+ * them arrived through a reviewed PR that passed this same ratchet.
+ *
+ * Ancestry is still required, as a second condition rather than the only one:
+ * a head that has diverged from its base is not "the baseline plus approved
+ * history", and the strict reading should stand.
+ *
+ * The chain is read from the BASELINE config, so a change cannot declare
+ * itself a promotion by adding `deploy.branches` entries in the same commit.
+ * @param {string} root Repo root
+ * @param {unknown} baselineConfig `.lisa.config.json` at the baseline
+ * @param {string | undefined} baseRef Ref being merged into
+ * @param {string | undefined} headRef Ref being merged from
+ * @returns {boolean} True when the allow list may be read from the head
+ */
+function isPromotion(root, baselineConfig, baseRef, headRef) {
+  if (!baseRef || !headRef) return false;
+  const chain = deployChain(baselineConfig);
+  const basePosition = chain.indexOf(bareBranch(baseRef));
+  const headPosition = chain.indexOf(bareBranch(headRef));
+  if (basePosition === -1 || headPosition === -1) return false;
+  if (headPosition >= basePosition) return false;
+  // Empty string on success, null when git exits non-zero or the ref is bogus.
+  if (git(["merge-base", "--is-ancestor", baseRef, headRef], root) !== null) {
+    return true;
+  }
+  // Both ARE deploy-chain branches, so this is a promotion that has diverged —
+  // typically a hotfix that landed on the base and was never synced down. The
+  // strict reading is correct here, but silence would leave an operator
+  // guessing why this promotion behaves differently from the last one.
+  process.stderr.write(
+    `threshold-ratchet: ${bareBranch(headRef)} does not contain ` +
+      `${bareBranch(baseRef)}, so this promotion is not the baseline plus ` +
+      `approved history and the allow list is read from the baseline. Sync ` +
+      `${bareBranch(baseRef)} down into ${bareBranch(headRef)} first.\n`
+  );
+  return false;
+}
+
+/**
+ * Resolve the allow list and say where it came from.
+ * @param {string} root Repo root
+ * @param {string} baselineRef Ref the comparison baselines against
+ * @param {"hook"|"staged"|"base"} mode Comparison mode
+ * @param {string | undefined} baseRef Base ref (base mode only)
+ * @param {string | undefined} headRef Head ref (base mode only)
+ * @returns {{ entries: object[], promotion: boolean, note: string | null }}
+ *   Entries, whether this is a promotion, and an audit line to print when the
+ *   entries came from anywhere but the baseline
+ */
+function resolveAllowList(root, baselineRef, mode, baseRef, headRef) {
+  const baselineConfig = parseJson(
+    git(["show", `${baselineRef}:.lisa.config.json`], root)
+  );
+  if (mode !== "base" || !isPromotion(root, baselineConfig, baseRef, headRef)) {
+    return {
+      entries: extractAllowEntries(baselineConfig),
+      promotion: false,
+      note: null,
+    };
+  }
+  return {
+    entries: extractAllowEntries(
+      parseJson(git(["show", "HEAD:.lisa.config.json"], root))
+    ),
+    promotion: true,
+    note:
+      `threshold-ratchet: promotion ${bareBranch(headRef)} → ` +
+      `${bareBranch(baseRef)}; both are deploy-chain branches declared at ` +
+      `${baselineRef} and the head fully contains the base, so the allow list ` +
+      `is read from the head. Exemptions below were approved upstream, not by ` +
+      `this change.`,
+  };
+}
+
+/**
+ * Split off the allow-entry additions a promotion is carrying forward.
+ *
+ * `applyAllowList` never drops an `allow-added` finding, from either side —
+ * an exception must not approve its own creation. That is right for an
+ * ordinary PR and wrong for a promotion, where the entry is not being created:
+ * it already exists on the upstream branch, where its creation faced this same
+ * unconditional block and needed a human to clear it. Without this the fix
+ * would be cosmetic — a promotion carrying an approved exemption also carries
+ * the `.lisa.config.json` diff that records it, so it would still be blocked
+ * by the finding for the record of its own approval.
+ *
+ * Only `allow-added` is carried. An actual threshold weakening in the same
+ * promotion still has to be covered by an allow entry.
+ * @param {Array<{ type: string }>} findings All findings from the change
+ * @param {boolean} promotion Whether the change is a recognised promotion
+ * @returns {{ carried: object[], rest: object[] }} Findings excused as already
+ *   approved upstream, and findings still subject to the allow list
+ */
+function partitionCarriedEntries(findings, promotion) {
+  if (!promotion) return { carried: [], rest: findings };
+  return {
+    carried: findings.filter(f => f.type === "allow-added"),
+    rest: findings.filter(f => f.type !== "allow-added"),
+  };
+}
+
 /**
  * Decide the exit code when the ratchet cannot determine what changed.
  *
@@ -161,9 +310,11 @@ function undeterminable(mode, reason) {
  * @param {"hook"|"staged"|"base"} mode Comparison mode
  * @param {string | undefined} [baseRef] Base ref (base mode only)
  * @param {string[] | undefined} [onlyFiles] Restrict to these paths (hook mode)
+ * @param {string | undefined} [headRef] Head ref (base mode only), used solely
+ *   to recognise a promotion between deploy-chain branches
  * @returns {number} Process exit code (2 for hook mode, 1 otherwise; 0 clean)
  */
-function run(mode, baseRef, onlyFiles) {
+function run(mode, baseRef, onlyFiles, headRef) {
   const root = git(["rev-parse", "--show-toplevel"])?.trim();
   if (!root) return undeterminable(mode, "not a git repository");
   const plan = resolvePlan(mode, root, baseRef, onlyFiles);
@@ -205,13 +356,21 @@ function run(mode, baseRef, onlyFiles) {
   );
   if (findings.length === 0) return 0;
 
-  const baselineConfig = parseJson(
-    git(["show", `${plan.baselineRef}:.lisa.config.json`], root)
-  );
-  const { blocked, allowed } = applyAllowList(
-    findings,
-    extractAllowEntries(baselineConfig)
+  const allow = resolveAllowList(
+    root,
+    plan.baselineRef,
+    mode,
+    baseRef,
+    headRef
   );
+  const split = partitionCarriedEntries(findings, allow.promotion);
+  const { blocked, allowed } = applyAllowList(split.rest, allow.entries);
+  if (allow.note) process.stdout.write(`${allow.note}\n`);
+  for (const finding of split.carried) {
+    process.stdout.write(
+      `threshold-ratchet: carried forward by this promotion, approved upstream — ${finding.message}\n`
+    );
+  }
   for (const finding of allowed) {
     process.stdout.write(
       `threshold-ratchet: allowed by .lisa.config.json exception — ${finding.message}\n`
@@ -257,11 +416,16 @@ function runHookMode() {
  */
 function main() {
   const args = process.argv.slice(2);
+  const headIndex = args.indexOf("--head");
+  const headRef = headIndex === -1 ? undefined : args[headIndex + 1];
   if (args[0] === "--staged") return run("staged");
-  if (args[0] === "--base") return run("base", args[1]);
+  // `--head` is optional and additive: a caller that omits it gets exactly the
+  // behavior that shipped before promotions were recognised, so an older
+  // workflow driving a newer script stays strict rather than silently relaxing.
+  if (args[0] === "--base") return run("base", args[1], undefined, headRef);
   if (args[0] === "--hook") return runHookMode();
   process.stderr.write(
-    "usage: threshold-ratchet.mjs --hook | --staged | --base <ref>\n"
+    "usage: threshold-ratchet.mjs --hook | --staged | --base <ref> [--head <ref>]\n"
   );
   return 0;
 }