docs(hygiene): match the header-position pin's head clause to the gate's

[os-steve]

Fixes #1357

One comment sentence in test/source-hygiene-header-position.test.ts. No executable line moves.

The two lines, side by side

This is the whole point of the card, so here is the claim rather than an assertion of it. The gate and the suite that tests it now state one fact in one shape:

scripts/check-source-hygiene.mjs   (landed by PR #1356, unchanged here)
 * 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.

test/source-hygiene-header-position.test.ts   (this PR)
    // #1094's own reproduce loop. The header is *not* universal in the rest of
    // the scanned trees today — some of the `.mjs` under scripts/, plus the
    // `.sh` and the `src/docs/*.md` pages — so widening this check would
    // demand headers in files nobody has decided about.

Before this PR the suite's half opened with a bare universal negative instead:

    // #1094's own reproduce loop. The rest of the scanned trees genuinely have
    // no header today — some of the `.mjs` under scripts/, plus the `.sh` and

Both quotes deliberately name the file and not the line. This family's own lesson is that a hand-maintained integer in prose goes stale, and these two lines moved twice in the day between the finding and this PR — the card recorded the sentence at ~:250 and it was at :249 at dispatch.

Why the head clause was wrong

Read on its own, "The rest of the scanned trees genuinely have no header today" is false. Measured with the gate's own COPYRIGHT_HEADER — /^\/\/ Copyright \(c\) \d{4} ObjectStack\./, applied the way scanHeaderPosition applies it — over SCANNED (src, test, e2e, scripts) on main @ 3e1b00b:

ext	files	carry the header
.ts	330	330
.mjs	8	6
.mts	1	1
.sh	1	0
.md	4	0

So 7 of the 14 non-.ts files in the scanned trees do carry it. (.mts is not .ts to this gate: isTs is f.endsWith('.ts') && !f.endsWith('.d.ts'), and "x.mts".endsWith(".ts") is false.)

There was a defensible reading under which the old sentence was fine — the em-dash clause does carry a quantifier, so it can be read as a restrictive appositive naming which files the head clause is about. That ambiguity was the entire finding, which is why it was graded marginal rather than as a defect. It is still worth one word: the audience for a gate's comments is the next agent to edit the gate, and an agent reads a bare universal negative as a fact it can reason from.

Why this wording and not a better one

The gate's docstring took exactly this repair in PR #1356, where the contrast was explicit and the bare universal negative unambiguously false. Copying it is the requirement, not a shortcut — a third phrasing would re-create "one fact, two shapes" under a new spelling, which is the entire reason the card exists.

Deliberately unchanged

• The em-dash clause. "the rest of the scanned trees" still ends the head clause immediately before the dash, so the appositive names the same noun phrase it always did. The .sh and src/docs/*.md halves are accurate and keep their wording; they read no more awkwardly after the change than before it.
• No integers in the source and no counting guard — the standing family ruling (docs: delete three hand-maintained integers from prose, keeping the claims they propped up #1338) applies unchanged. The measurement above lives in this PR and the changeset, where it is dated and re-runnable, not in the source where it would become the next instance of the defect this family removes.
• COPYRIGHT_HEADER, INDENTED_COPYRIGHT_HEADER, the scanned surface, every fixture, every assertion and the describe block: byte-identical. The diff is 5 comment lines out, 6 in, plus the changeset.
• scripts/check-stackblitz-lock.mjs and scripts/sync-docs-screenshots.mjs carrying no licence header is known and deliberate, and The copyright header is .ts-only in practice: 3 of 5 scripts/*.mjs, the .sh and src/docs/*.md have none, and one .mjs uses different wording #1138 was closed not_planned. Out of scope here and untouched.

Verification

pnpm verify green on the final commit of this branch, ab34da5 — run after the changeset was committed, so the union covers everything the PR ships:

✓ i18n lint gate: 0 `i18n/missing-*` issues
✓ source hygiene clean
✓ source token ratchet clean
  Test Files  145 passed (145)
       Tests  3030 passed | 1 skipped (3031)
os-verify-lock: VERDICT command-exit 0 · held the lock 212s (3m32s) · waited 0s

The token ratchet is unmoved by construction — it measures src/**/*.ts comment-stripped, and this change is a comment in test/.

pnpm changeset status --since=3e1b00b also passes locally: NO packages to be bumped at patch, minor or major.

Changeset

.changeset/header-position-twin-head-clause.md, empty frontmatter — the sanctioned "this PR releases nothing" declaration that .github/workflows/changeset-check.yml documents. This one genuinely is the prose-only case: the diff is one comment in test/ plus the changeset itself, and nothing under src/ is touched.

Generated by Claude Code

---

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 12:57pm