docs(invariants): the sweep arithmetic, and why forge refs stay unfiltered

Two loose ends from the checks shipped today, both found by review rather than
by a failure.

`forgeTags` returns EVERY ref on purpose: PIN-DEAD has to resolve a pin written
as `config-audit/v5.0.0`, and filtering to `v*` would turn a live pin into a
false dead one. ktg-plugin-marketplace carries four such refs, so both new
checks see them. They parse to 0.0.0, so they can only read as behind a real
release, never as a newer tag one is lagging — and REMOTE-SYNC's unfiltered
side can only remove findings, never add one. Two tests pin that reasoning; the
remaining asymmetry is a coverage gap, not a false positive.

The API count went from two to three, so a full online sweep of 22 repos went
from 44 calls to 66. Nobody has measured 66, and the only knee ever measured is
the ~40 this same file now marks unusable. Written down beside the count,
because a downstream caller trusting a stale number is exactly how that line
failed twice.

213 tests (was 211).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWc4piM4QW6Jxfky2Rw4Z8

CLAUDE.md

@@ -115,7 +115,11 @@ would recreate, in data, exactly the drift this plugin exists to remove.
   for any reader, not only someone holding one. A sweep across every repo
   still does not belong here: it needs the listing fetched once, not once per
   invocation, which is a different shape of caller (org-ops), not a flag on
-  this engine.
+  this engine. **The arithmetic moved with the count**: a full online sweep of
+  22 repos is now 66 API calls, not 44. Nobody has measured 66, and the only
+  knee ever measured is the ~40 marked unusable below. A sweeping caller paces
+  or fetches once — this sentence exists so the number is not re-derived from a
+  stale "two calls", which is how that line failed twice.
   **The "13 calls in a loop" explanation was incomplete** (2026-08-04): the
   forge's nginx never sends `Retry-After` on its 429s (measured directly), so
   `fetchWithRetry` always falls back to exponential backoff — the
@@ -273,7 +277,7 @@ would recreate, in data, exactly the drift this plugin exists to remove.
 ## Commands
 
 ```bash
-npm test                                                  # 211 tests
+npm test                                                  # 213 tests
 node scripts/repo-standard-check.mjs --dir "$PWD"         # gate one repo
 node scripts/repo-standard-check.mjs --offline            # no network call
 node scripts/repo-standard-check.mjs --json               # machine output

scripts/repo-standard-check.test.mjs

@@ -2136,3 +2136,26 @@ test('several unpushed tags are reported in version order, in one finding', () =
   assert.equal(f.length, 1);
   assert.match(f[0].msg, /v0\.9\.0.*v0\.10\.0/);
 });
+
+test('a non-semver forge tag cannot manufacture a stale release', () => {
+  // `forgeTags` returns EVERY ref, deliberately: PIN-DEAD has to resolve a pin
+  // written as `config-audit/v5.0.0`, and filtering to `v*` would turn a live
+  // pin into a false dead one. ktg-plugin-marketplace carries four such refs
+  // (`config-audit-v4.0.0`, `config-audit/v5.0.0`, `config-audit/v5.1.0`,
+  // `pre-polyrepo-archive`), so RELEASE-CURRENT sees them too. They parse to
+  // 0.0.0 and can therefore only ever read as BEHIND a real release — never as
+  // a newer tag the release is lagging.
+  const f = checkReleaseCurrent({
+    forgeTagsSelf: ['v7.7.2', 'config-audit/v5.1.0', 'pre-polyrepo-archive'],
+    releases: ['v7.7.2'],
+  });
+  assert.equal(f[0].code, 'RELEASE-CURRENT');
+});
+
+test('unfiltered forge refs cannot manufacture an unpushed-tag ERROR either', () => {
+  // REMOTE-SYNC compares local `v*` tags against the unfiltered forge list, so
+  // the extra refs can only ever REMOVE findings. The asymmetry is a coverage
+  // gap — an unpushed non-`v` tag is invisible — never a false positive.
+  const f = checkRemoteSync({ tags: ['v7.7.2'], forgeTagsSelf: ['v7.7.2', 'pre-polyrepo-archive'] });
+  assert.equal(f[0].level, 'OK');
+});