Spec and plan the card harness

[robertblust]

The design we agreed, written up as a spec, plus the implementation plan. Supersedes the tier 4 paragraph of the shared design system spec, which was wrong in two directions.

What the earlier spec got wrong

It called the recipe local because "95 of its 148 lines differ for real reasons" — but og-recipe.mjs is machinery and a card list sharing a file. Diffed apart:

machinery   ~62 lines each, differing by 5 to 9 lines
            almost all of it comment prose — blust.ch's says "four
            multi-megabyte PDFs", guestgraph's says "both"
card list   genuinely different, as the spec said

It also called tier 4 "the smallest saving of the four". On the corrected measurement it is the largest cluster left in the family. Both errors came from the duplication sweep, wrong by construction three times now; these numbers were taken after it got tests.

The line count is the weaker argument

export-og.mjs has drifted into three variants, each carrying a capability the other two lost:

	companygraph	guestgraph	blust.ch
reduced-motion settling	✅	—	—
hash — render a named view	✅	—	—
recipe/renderer agreement guard	—	✅	—
per-card deviceScaleFactor	—	✅	—

The recipe tests drifted the same way — 29, 30 and 30 tests, and no one of them a superset of another. There is no copy here to consolidate onto. This is the shape of the defect that nearly shipped in the suite runner round, so "the package takes the union, never the intersection" is written in as a rule rather than left to judgement.

The design

No fences. A visitor never downloads any of these files, so the governing rule makes every piece an import. First tier where the answer is imports throughout.

Four modules under cards/ — recipe.mjs, check.mjs, export.mjs, recipe-tests.mjs — each taking the site's recipe module as input. Each site keeps og-recipe.mjs (its cards, frame, hide rules and REPO_ROOT) and three thin callers. REPO_ROOT stays site-side deliberately: that is the SITE_ROOT defect from the runner round, avoided by construction rather than by remembering.

No card's picture changes. The union makes settle: "reduced-motion" available everywhere but it applies only where a recipe asks, and blust.ch's does not. og:check is a fixed point across the whole change.

Self-review found three things

Fixed before this went out rather than discovered mid-implementation:

• cardFor is not a union item. Two sites export it, which is what made it look like one — it is defined once in each and called nowhere in either. Deleted rather than moved; the union rule protects capabilities a site would lose, and an export nothing imports is not one.
• Criterion 1 was unachievable as written. Dropping from from guestgraph's cards moves every guestgraph og.sha, because the recipe hashes every key of a card. Pictures identical, hashes not. Named as the one exception; the line holds everywhere else.
• SHARED_TEST_COUNT was inside the function that must not contain it, and its test counted occurrences of test( in the source — which a comment defeats, exactly how three tests in this family were defeated before. It counts registrations now.

The plan

Eight tasks: four package modules, a release, three site adoptions. Every task that adds a gate proves it red by mutation first. The union recipe suite ends at 32 tests on every site, up from 29, 30 and 30.

🤖 Generated with Claude Code