[MumuTW]

Implements proposal 2 of #8584. Companion to #8585 (the one-off banking run) and #8589 (the --update gap fix) — but this is the one that makes the other two stop decaying.

The problem, restated in one line

The ratchet is only half automatic, and it is the wrong half.

direction	cost	who does it
raise a cap	a ten-second JSON edit, and the fastest way to unblock a red PR	anyone, under merge pressure
lower a cap	run --update, commit, get it reviewed	nobody — no workflow invokes it

Grep .github/workflows/ for --update: wiki-sync.yml (unrelated) and ci.yml's check-quality-ratchet.mjs --require-tighten (a different script, a different metric). Neither check:file-size --update nor check:complexity-ratchets --update is run by anything.

Measured on release/v3.8.49 at 4053e2314: 18 frozen files already at or under the 800-line new-file cap, worst at 132× (src/shared/validation/schemas.ts, 19 lines carrying a 2,523 cap); the complexity ceiling walked 1794 → 2169 across ~37 rebaseline notes with exactly one decrease (−1); "tighten via --update next cycle" written 31 times, honoured once in six weeks.

The consequence is not "caps drift up". It is that a cap outlives the code that earned it, so every completed decomposition silently becomes a growth allowance for whoever edits that file next.

What this adds

New job bank-ratchet-shrinks in nightly-release-green.yml — that workflow already measures the active release branch, so this reuses its lane, its branch resolution, and its injection guard.

resolve highest release/vX.Y.Z
  → check:file-size --update
  → check:complexity-ratchets --update
  → verify-ratchet-bank.mjs      ← aborts here if anything moved the wrong way
  → force-update one branch, open/refresh ONE PR

Schedule + dispatch only, deliberately not push. Banking has no latency requirement — a shrink banked within 8h is fine — while a per-merge run would rebuild the PR branch repeatedly during merge campaigns and pay for a full ESLint walk each time. Detection stays on push (release-green, unchanged); only banking is batched.

It never pushes to release/*. A human merges the PR, so a bad measurement cannot land unreviewed. That is also why it opens one force-updated PR rather than one per run.

The safety verifier is the actual argument

A bot that could raise a cap would be strictly worse than the status quo. So the job writes nothing unattended without scripts/quality/verify-ratchet-bank.mjs clearing it first. The verifier diffs the post---update tree against HEAD and aborts the job before a commit exists — opening no PR — unless every single change is one of:

• a frozen / testFrozen numeric entry lowered or removed
• complexity-baseline.json → count lowered
• quality-baseline.json → metrics.cognitiveComplexity.value lowered

Everything else fails: raising a number, adding an entry, changing cap/testCap, or deleting/rewriting a _rebaseline_* note. That last one matters more than it looks — the notes are the audit trail for why each ceiling exists, and they are stored inside the same frozen object as the file entries (which is why the gate prints 182 arquivos congelados for 127 real files). A naive "rewrite the JSON" bot would eat them.

Verified both directions against the real baselines

Forward — --update then verify, on the actual release tip:

[file-size] baseline ratcheado: 74 arquivo(s) encolheram
[test-file-size] baseline ratcheado: 17 arquivo(s) de teste encolheram
[verify-ratchet-bank] OK — 77 lowered, 14 removed, nothing raised.   exit=0

Negative control — hand-raise one entry and the cap, exactly what the verifier exists to stop:

[verify-ratchet-bank] UNSAFE — 2 problem(s); refusing to bank:
  ✗ file-size: "cap" changed — only the ratcheted values may move
  ✗ frozen: open-sse/handlers/chatCore.ts RAISED 5125 → 9999
  → the banking lane may only lower or remove.                       exit=1

The baseline edits were reverted — this PR contains no baseline changes and no product code changes. Banking the current 91 is #8585's job; this is the machinery that keeps doing it.

tests/unit/verify-ratchet-bank.test.ts — 22 tests, one per way the automation could go wrong (raise, add, delete a note, rewrite a note, move cap, move an unrelated metric while the tracked one legitimately dropped, …). All pass.

Notes for review

• docs/architecture/QUALITY_GATES.md shows ~29 deleted lines that are not mine. lint-staged runs prettier --write on *.md, and two pre-existing tables in that file were not prettier-clean at HEAD, so any commit touching the file reformats them. The change is whitespace-only. Say the word and I will add the file to .prettierignore instead (there is precedent — docs/reference/ENVIRONMENT.md is excluded for exactly this reason).
• This gets strictly more effective once fix(quality): let --update remove baseline entries that already fit the cap #8589 merges. --update currently cannot remove an entry whose value already equals the frozen value and sits under the cap; fix(quality): let --update remove baseline entries that already fit the cap #8589 adds that third bucket. The lane inherits whatever --update can do.
• --update is shrink-only by construction, independently of this PR: check-file-size.mjs writes only from improvements, and check-complexity-ratchets.mjs only when .improved. The verifier is defence in depth, not the only guard.
• Both --update invocations run under set +e on purpose: they exit non-zero while the branch is over baseline, which is precisely when there is nothing to bank. Their exit code is not the signal; the verifier is.

Closes the mechanism half of #8584. Proposal 3 (replacing the 93 dead #3501 references with a live decomposition tracker) is not in this PR.