feat(design-sync): make design:pin a validated contract with the shared sync

[JG2547]

Rebased onto main after #223 merged. The pin-roll commit this branch opened with is dropped: #223 already rolled the citations to 08024a1, so replaying it would have reverted them. What remains is tooling only.

What this is

The shared design-system sync moves the submodule gitlink and knows nothing about the prose this repository keeps in step, so a bump alone leaves Build & Test red. It happened three times: #219 (ac0f1b1), main after #221 (793d3cf), and #223 (08024a1). #220 added a roller; this makes it safe for automation to call unattended and covers it with tests.

Contract

npm run design:pin                  roll to the current gitlink
npm run design:pin -- <40-hex sha>  roll to an explicit commit
npm run design:pin -- --check       report, write nothing, exit 1 if stale

The script name and one argument are the whole interface. 1132-Fixer/design-system#8 calls it that way; nothing in the shared repository hardcodes a path of ours.

Explicit, not broad

Citations are declared in PIN_SITES together with the prose that introduces them: the pinned to \<sha>\ note in AGENTS.md, and each Pinned design source: \design-system\ @ \<sha>\ line in DESIGN-SYNC.md. A bare 40-hex string anywhere else is not a pin and is never rewritten, so this repository's own commit references survive.

Fails instead of guessing

The SHA is not 40 lowercase hex; the SHA disagrees with the submodule's actual HEAD; a declared citation is missing, so a silent no-op would hide a shape change; citations disagree with each other; a pin is malformed in an otherwise-declared location; a design-system citation appears where PIN_SITES does not cover it.

That last check closes the drift hole. design-sync-pin-smoke.js now imports PIN_SITES and the scanner from the roller, so the gate and the tool that satisfies it cannot diverge.

The index trap, and why it matters

git ls-files -s design-system reads the superproject index. During the sync hook the index still records the previous commit, because the gitlink is staged in the next step; only the submodule working tree has moved. That is precisely how #223 was opened with its gitlink at 08024a1 and its citations at 793d3cf.

readGitlink now prefers git -C design-system rev-parse HEAD and falls back to the staged gitlink only when the submodule is not checked out. Reproduced in a checkout holding that exact state:

index gitlink : 793d3cf57e3ba87a1e8c32eb88c487dccd81eb9a
submodule HEAD: 08024a12c4560d695263dbc662ee4864e1593ca7
readGitlink   : 08024a12c4560d695263dbc662ee4864e1593ca7

Tests

tools/roll-design-pin-smoke.js, wired into npm test: a normal roll, multiple occurrences in one file, five invalid-SHA shapes, a missing citation in each document, mixed old pins, a malformed pin, protection of unrelated hashes, an undeclared citation location, idempotence, and index-versus-HEAD precedence. 30 checks, pure string transforms, no git or network.

Verification

npm test exits 0 on the rebased head. The diff against main is five files and touches no citation line: the pins on this branch are the 08024a1 values inherited from main.

Command line exercised end to end: a short SHA and a SHA disagreeing with the submodule are both refused with exit 1; reverting the pins makes --check exit 1 naming both files; rolling restores them byte-identically and the gate passes again.

Note on the earlier approval

@patricktobias86 approved be21867. The rebase replaced it with c60c07d, so that approval no longer applies to the current head and a fresh one is needed. Same content, minus the dropped pin commit.

Merge order: #223 (done), then this, then 1132-Fixer/design-system#8.