feat(merge): identity grouping — nest supersessions, split distinct tests (0046)

[siddhant573]

What

An optional tests.identity block in merge-rules turns a test-id collision from "pick one winner" into "group by identity".

tests:
  on_collision: error                 # unchanged fallback
  identity:
    keys: [external_id.commit_id, external_id.test_id]
    on_same: nest
    on_different: split

• Same identity → the latest run holds the canonical tests/<id>/ exactly as an uncontested test does; superseded runs are archived whole beneath it as 1/, 2/ … oldest first.
• Different identity → the copy gets its own sibling tests/<id>-1/, -2/.

Purely additive. Absent the block, output is unchanged — there is a regression test asserting exactly that.

merged/tests/
  login-flow/              result.yaml (latest) + steps/ logs/
    1/                     oldest superseded run, whole tree
    2/
  login-flow-1/            distinct test — result.yaml `test:` rewritten

Why

Producers derive test ids (a slug plus a path hash), so merging two runs of the same suite collides on every test. prefer_latest answers that by discarding artifacts and discard by dropping the test outright — neither preserves history, and neither can tell "the same test, run again" apart from "two different tests that happen to share a derived name". This realises the slice 0045 deferred as "cross-environment matrix identity".

Design notes

• Why a block, not a split action on the rule list. Grouping must ask "does this challenger belong to group 0, group 1, or neither?", which needs the whole key set as an up-front fact. Scraping it from "every rule whose action is split" would make identity an emergent property of an unrelated ordering — adding a guard rule would silently redefine sameness.
• Why not new on_collision values. error/prefer_first/prefer_latest/discard all answer which copy survives and never change the pack's shape. nest/split answer what shape the output takes.
• Guard rules still resolve first, so a must: same + error rule can never be downgraded into a split. discard tombstones the base id — split siblings included.
• Suffix reservation runs against every eligible pack's test ids, so a split never steals a name a pack legitimately owns (<id>-1 taken → allocates -2).
• Nested copies are inert by construction, not special-casing: totals walk top-level tests/*, the failure index reads tests/<id>/steps/, L1 checks enumerate <test>/steps/.
• Vendor-neutral per 0002 — keys are caller-supplied dot-paths; no producer field name enters src/ or the schemas.

Implementation

collide.ts generalises the union walk from one incumbent per test id to an ordered list of groups. A single-member group with folder === baseId is 0045's behaviour, so there is one code path rather than two. assemble.ts writes canonical + nested copies, rewrites test on split folders only (0031's directory equality), and pushes divergent environment down into every copy from its own source pack.

Also in this PR

• src/design-links.test.ts — 0046 initially shipped without governs/feature, which made it invisible to the design viewer everywhere except the decisions log; it was the only one of 46 decisions missing them. The new test catches the class. Note it revealed that a governs entry may be a conceptual area (repo in 0001/0025) rather than a path, so only path-shaped entries are filesystem-checked.
• CHANGELOG backfill for 0.1.6 — published to npm but never documented, leaving a hole between 0.1.5 and this release.

Verification

• npx vitest run → 194 passed / 20 files
• npm run build → clean
• Docs site rebuilt; 0046 now resolves against Contract.tsx's design/contract/03-commands.md token

Note for consumers

on_same: nest retains artifacts that prefer_latest discards today, so merged packs of re-runs grow with the number of runs kept. That is the intent of the feature, but it is a real change in output size for anyone who opts in.

🤖 Generated with Claude Code