docs(hygiene): drop the hand-maintained integers from scanHeaderPosition's docstring

[os-steve]

Fixes #1351

Seventh application of the standing family ruling: delete the integers, keep the claim. Two sentences in one docstring — scanHeaderPosition in scripts/check-source-hygiene.mjs — swept together, as the card required. Six comment lines out, six in. No executable line changed.

Why this needed its own PR rather than a renumber

The twin sentence went stale again between being filed and being fixed. The card was written against a measurement of 3 of 8 headerless .mjs; PR #1354 normalised scripts/publish-marketplace.mjs's licence-header spelling that same morning, and the honest reading at the moment of this edit is 2 of 8. The prose said 3 of the 5. Two numbers, three readings inside one day, one sentence. That is the argument, not an anecdote.

Measurements — evidence the prose no longer depends on them

⚠️ Re-measured on origin/main @ 3b72afa (the base of this branch, re-fetched at start of work), using the gate's own rule reimplemented verbatim — COPYRIGHT_HEADER = /^\/\/ Copyright \(c\) \d{4} ObjectStack\./ from :346, applied the way scanHeaderPosition applies it at :425-433. Not a grep "Copyright" approximation.

.mjs under scripts/ — 8 total, 6 carry the header, 2 do not
  HEADER  shebang   scripts/check-lint-i18n-gate.mjs
  HEADER  shebang   scripts/check-source-hygiene.mjs
  HEADER  shebang   scripts/check-source-token-ratchet.mjs
  MISSING shebang   scripts/check-stackblitz-lock.mjs
  HEADER            scripts/lib/main-module.mjs
  HEADER            scripts/lib/source-hygiene-surface.mjs
  HEADER  shebang   scripts/publish-marketplace.mjs        (moved by #1354)
  MISSING           scripts/sync-docs-screenshots.mjs

.sh under the scanned trees          : 1, headerless   (scripts/wow1-live-schema.sh)
src/docs/*.md                        : 4, all headerless
.mjs under scripts/ with a shebang   : 5
.ts repo-wide with a shebang         : 0 of 338
.ts under SCANNED, no header         : 0 of 326  (the "universal in .ts" half holds)

⛔ These figures are reported as evidence, not as numbers to write back in.

The two edits

1. The "Why .ts only" paragraph (:404-407)

Was: "the header is universal in .ts and is not in the rest of the scanned trees — 3 of the 5 .mjs files under scripts/, the .sh script and the four src/docs/*.md pages have none."

Both integers are wrong, and — the trap this family has already paid for once — deleting them alone leaves a sentence that is false in the opposite direction: six of the eight .mjs do carry the header, so a bare "the .mjs files under scripts/ … have none" asserts something untrue. The head clause needed the same treatment: "the header … is not in the rest of the scanned trees" is itself a universal negative that the six headered .mjs falsify.

Now: "the header is universal in .ts and is not universal in the rest of the scanned trees — some of the .mjs under scripts/, plus the .sh and the src/docs/*.md pages, have none."

That is deliberately the wording PR #1349 landed for the twin sentence in test/source-hygiene-header-position.test.ts, so the gate and the suite that tests it stop disagreeing — which was the point of the card.

⭐ Note on the two integers that were currently accurate: the .sh script and the four src/docs/*.md pages both measure true today. four still goes, under the same ruling — a hand-maintained integer with no producer is the defect, not merely a wrong one — and losing it costs nothing, because "the src/docs/*.md pages" is true and stays true.

2. The shebang bullet (:392-394) — two defects, not one

Was: "No .ts file in this repo has a shebang today; the two .mjs gates in scripts/ do, and they carry the header on line 2, which is the shape this allows."

• the count is five, not two;
• and "they carry the header on line 2" is false of scripts/check-stackblitz-lock.mjs, which has a shebang and no licence header at all.

⚠️ Correcting two to five would have left the second defect standing and made it worse — the wrong number was the only thing keeping the universal claim narrow enough to be true.

Now: "No .ts file in this repo has a shebang today; some of the .mjs under scripts/ do, and where one of those carries the header it sits on line 2, which is the shape this allows." — no figure, and a conditional in place of the universal. Verified: of the five shebanged .mjs, the four that carry a header carry it on line 2; the fifth carries none, and is outside the conditional.

The load-bearing half was re-verified rather than assumed, since the allowance rests on it: no .ts file in this repo has a shebang (0 of 338). Unchanged, and no escalation needed.

What was deliberately not done

• ⛔ No renumbering to 2 of 8 or five.
• ⛔ No counting guard (ADR-0049 axis 3, as with the six landed siblings).
• ⛔ COPYRIGHT_HEADER, INDENTED_COPYRIGHT_HEADER, the scanned surface and the banner are untouched, as is every executable line.
• ⛔ scripts/publish-marketplace.mjs not touched — out of scope here, and already handled by fix(hygiene): spell the marketplace script's licence header the way the gate reads it #1354.

Verification

pnpm verify green, run on the tree that is byte-identical to this branch's head 09ebcd0 (git status --porcelain empty at that commit). Verdict lines as the gates printed them:

  ✓ Validation passed (1412ms)
✓ i18n lint gate: 0 `i18n/missing-*` issues
✓ source hygiene clean
✓ source token ratchet clean
 Test Files  142 passed (142)
      Tests  3004 passed | 1 skipped (3005)

typecheck, lint and build completed with no diagnostics; the whole chain exited 0 (captured before any pipe).

Changeset

.changeset/scan-header-position-docstring-integers.md, empty frontmatter — the sanctioned "releases nothing" declaration changeset-check.yml documents. Comment text only; nothing reaches HotCRM users.

Related

• source-hygiene-header-position.test.ts prose says "3 of 5 .mjs under scripts/" — it is 2 of 7, both integers were already wrong, and PR #1343 nudges it to 2 of 8 #1346 / PR docs(hygiene): drop the .mjs/.md counts from the header-position pin's prose (#1346) #1349 — the twin sentence, and the quantifier wording copied here
• publish-marketplace.mjs's licence header says "ObjectStack contributors." and fails COPYRIGHT_HEADER — invisible only because the check reads .ts only, and it is why "headerless .mjs" has two defensible counts #1352 / PR fix(hygiene): spell the marketplace script's licence header the way the gate reads it #1354 — the producer of one of these numbers; this card was serialised behind it
• scanHeaderPosition's "all 282 .ts files … 274 of them on line 1" is stale in both halves — it is 324 and 324, and the 8-file gap it was hedging against has closed #1315 — edited the bullet immediately above both of these and missed them
• docs: delete three hand-maintained integers from prose, keeping the claims they propped up #1338 — the family's landed ruling

🤖 Generated with Claude Code

https://claude.ai/code/session_01WMzCeNC4SZcPNBpE2zCVCg

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 27, 2026 9:00am