msd-core/docs/adr/2264-golden-parity-redesign.md

ADR-2264: Redesign golden-install-parity — single-source manifest builder + split invariant

• Status: Proposed
• Date: 2026-07-14
• Issue: #2264 (epic); Phase 0 tracked by #2265
• Supersedes: nothing; amends the ADR-1239 Phase-B safety-net harness
• Relationship to prior work: Evolves tests/golden-install-parity.test.cjs (ADR-1239 Phase B). Related: #2086 (claude-local realpath normalization), #2095/#2100/#2117 (exclusion-set drift incidents), #1691 (scoped-CI drift guard).

Why this is still Proposed (audited 2026-07-17)

Audited 2026-07-17 against the live tree and GitHub. Phase 1 shipped cleanly and is genuinely done: buildParityManifest, buildInstallTree, and the four exclusion constants (VOLATILE_FILES, HOOK_CONFIG_FILES, HOOK_CONFIG_RELATIVE_PATHS, EXCLUDED_PREFIXES) live as the single source of truth in tests/helpers/install-shared.cjs (lines 104-234); scripts/gen-golden-install-parity-zcode.cjs now imports them instead of re-declaring them; the anti-divergence guard (tests/golden-parity-single-source.test.cjs) enforces no second copy; scripts/ci-test-scope.cjs (lines 121, 145, 175-176) selects the golden suite on the wider path set the Amendment describes; npm run gen:golden (package.json:93) exists; and all five issues (#2264-#2268) are closed as completed.

The blocker: Acceptance criteria 3 and 4 name mechanisms that were never built. AC3 requires "A simulated converter bug ... caught by the converted-artifact golden" and AC4 requires "A simulated verbatim-copy corruption ... caught by the copy-parity property test" — neither tests/fixtures/converted-artifacts/ nor any *copy-parity* test file exists anywhere in the tree (confirmed absent by direct filesystem check). The ADR's own same-day Amendment explains why (§3/§4 were found "unsound" in the Phase 2 spike) and states the old monolithic content-hash golden "is retained as-is" — but the Acceptance Criteria section itself was never edited to drop or reword AC1/AC3/AC4 to match the revised design. That leaves AC1 — the document's headline must-have, "editing the content of a verbatim/path-injected copied shipped file (e.g. a workflows/*.md) requires zero manual fixture regeneration" — literally unmet: tests/golden-install-parity.test.cjs still content-hashes every emitted file via the retained buildParityManifest (confirmed at install-shared.cjs:218, crypto.createHash('sha256')), and EXCLUDED_PREFIXES (install-shared.cjs:154) excludes only gsd-core/bin/lib/ — workflows/*.md is still fully inside the hashed manifest, so editing one still requires npm run gen:golden. The functional invariants AC3/AC4 care about are still covered, but only by the legacy hash golden this ADR set out to partly replace, not by the mechanisms the criteria name.

Unblock condition: Edit the Acceptance Criteria section (items 1, 3, 4) to match the shipped, amended design — replace "zero manual fixture regeneration" and the named converted-artifact/copy-parity mechanisms with the criteria the Amendment actually delivers (file-set snapshot catches structural drift; the retained content-hash golden catches converter and copy corruption; npm run gen:golden is the one-command fix for legitimate content changes) — then flip Status. No further code work is required; this is a documentation edit against already-shipped, already-closed work.

Context

tests/golden-install-parity.test.cjs snapshots the installer output for 18 runtime layouts. For each runtime it runs a real runMinimalInstall, walks every emitted file, normalizes volatile bits (temp root → <HOME>, package version → <VERSION>, macOS realpath /private → <HOME>), SHA-256s each file (16-char slice), and compares the entire path→hash map against a committed fixture under tests/fixtures/golden-install-parity/*.json (18 files, ~520 KB, ~7,500 hash lines).

It was created as a refactor fence: proof that moving installRuntimeArtifacts (ADR-1239) changed zero emitted bytes. That invariant is valuable and rarely triggered.

Four problems make it a recurring tax on ordinary code updates:

1. It conflates two invariants. ~95% of each manifest is "the installer copied a source file (workflows/*.md, agents/*.md, templates/config.json, bin/shared/*.json) to a destination." Those source files are already version-controlled. Storing a derived checksum of an already-tracked file adds ~zero review signal, yet every content edit to such a file trips the golden and forces a full 18-fixture regeneration. Only the ~5% of output that is transformed (per-runtime skill/command/agent projections produced by runtime-artifact-conversion: path rewrites, frontmatter edits, @-reference rewrites) is genuinely non-derivable from git and worth a content snapshot.

2. Regeneration runs through a hand-maintained duplicate. Local node --test is hook-blocked (.claude/hooks/block-local-node-test.sh), so regeneration goes through scripts/gen-golden-install-parity-zcode.cjs, which re-declares the exclusion set and re-implements buildParityManifest inline, kept in sync only by a comment: "Must match tests/golden-install-parity.test.cjs exactly." Its own comments record two prior drift incidents that shipped broken fixtures (#2100 missing settings.local.json; #2117 missing .kimi/config.toml).

3. The duplicate has drifted again — a live divergence. The test normalizes the macOS realpath form (fs.realpathSync(root) → collapse /private/var/...) added in #2086. The driver at scripts/gen-golden-install-parity-zcode.cjs:51 does not — it only collapses bare root and PKG_VERSION. Regenerating any realpath-embedding layout (e.g. claude-local) on macOS via the driver bakes a literal /private<HOME> into the hashed content, which fails golden-parity on the Linux benches — the exact #2086 bug, reintroduced in the copy that was never fixed.

4. The feedback loop is remote-only and the diff is unreviewable. The suite runs solely in the gsd-test docker lane (and scoped CI when src//bin//installer paths change, per scripts/ci-test-scope.cjs:117-145) — never in local npm test. The loop is: edit → push → remote matrix fails → regenerate via the duplicate → re-push → re-run. A one-line model-catalog.json change rewrites hundreds of hash lines across 18 fixtures, burying the real change.

Decision

Split the single monolithic content-hash manifest into three assertions with different change cadences, and collapse the manifest logic to a single source of truth so regeneration cannot drift.

1. Single-source manifest builder (Phase 1 — prerequisite refactor)

Lift buildParityManifest and the exclusion constants (VOLATILE_FILES, HOOK_CONFIG_FILES, HOOK_CONFIG_RELATIVE_PATHS, EXCLUDED_PREFIXES) out of the test into tests/helpers/install-shared.cjs (which already exports walk, RUNTIME_META, runMinimalInstall, BUILD_SCRIPT). The test and any generator import the one copy. Delete the inline re-implementation in scripts/gen-golden-install-parity-zcode.cjs. The #2086 realRoot divergence dies with the duplicate; the #2100/#2117 class of drift becomes structurally impossible. A guard test fails if a second inline copy of the exclusion set is reintroduced.

2. Emitted file-set snapshot — the tree shape (Phase 2a)

Per runtime, snapshot the sorted list of emitted relative paths (after the shared exclusions), with no content hashes → tests/fixtures/install-tree/<runtime>.json (a JSON array). This catches added / removed / renamed / moved files — the "installer stopped shipping X" or "installer emitted an unexpected Y" regression — and changes only when the file set changes, not when a file's content changes. The diff is proportional to the change (a few added/removed lines), not a rewrite of every hash.

3. Copy-parity property test — derive from source, store nothing (Phase 2b)

For every emitted file that is a copy (verbatim or copy-with-path-injection, e.g. copyWithPathReplacement), assert its normalized content is derivable from its git-tracked source — computed live at test time, no committed hash. The injected install path is the only variable and is already collapsed to <HOME> by normalization, so normalize(emitted) is the source content modulo a known, invertible substitution.

Spike/risk (resolve in Phase 2 before committing to "fixture-free"): validate that the path injection is cleanly invertible for every copied surface, so normalize(emitted) === reference(source) holds by pure derivation. Where a surface's injection is not cleanly invertible, that surface falls back to a small stored reference — but even then the reference is re-derived from source at test time, so a content edit to the source propagates automatically and needs no manual regeneration. This is the core win regardless of the spike outcome: content edits to copied files stop requiring hand-regenerated fixtures.

4. Converted-artifact golden — small and high-signal (Phase 2c)

Only the transformed outputs (per-runtime projections from runtime-artifact-conversion) keep a content-hash golden → tests/fixtures/converted-artifacts/<runtime>.json. This is the ~5% git cannot review (source is correct; the projection is derived and a converter bug corrupts it silently). The fixture is small and changes only when the converter logic or a converted source changes — exactly the changes that should require a human to bless. This gate stays a hard failure and is never auto-regenerated/auto-committed.

Phases

• Phase 0 — this ADR (#2265, docs-only PR on docs/2265-golden-parity-adr; PR Closes #2265, not the epic).
• Phase 1 — single-source manifest builder (#2266, refactor:). Extract the shared builder + exclusions; delete the duplicate driver's inline copies; add the no-second-copy guard test. Expected fixture diff: none (byte-identical), which is the safety proof. Resolves the #2086 realRoot divergence.
• Phase 2 — split invariant (#2267, refactor:/test:). Land the file-set snapshot (§2), the copy-parity property test + invertibility spike (§3), and the converted-artifact golden (§4). Migrate/replace the 18 monolithic fixtures once; delete the old per-file hash fixtures.
• Phase 3 — optional, CI-owned regen (#2268, stretch). On file-set or converted-golden drift, CI regenerates and posts the exact patch as a PR artifact/comment (jest --ci posture: fail on new snapshot, regenerate deliberately) — never silent auto-commit for the converted golden. Optionally adopt Node's first-party context.assert.snapshot + --test-update-snapshots for §4 to delete the bespoke UPDATE_GOLDEN env + hand-rolled read/write/compare code.

Acceptance criteria (must-haves)

1. Editing the content of a verbatim/path-injected copied shipped file (e.g. a workflows/*.md) requires zero manual fixture regeneration and the parity suite still passes. (Failing-first test: tweak a copied file, assert no fixture diff is needed.)
2. Adding/removing/renaming a shipped file is caught by the file-set snapshot with a diff proportional to the change.
3. A simulated converter bug (corrupt a transformed projection) is caught by the converted-artifact golden as a hard failure.
4. A simulated verbatim-copy corruption (installer truncates a copied file) is caught by the copy-parity property test.
5. The engine deep-refactor fence is preserved: the suite still proves byte-identical emitted output across all 18 runtimes.
6. Exactly one implementation of the manifest/exclusion logic exists; a guard test fails if a second copy is introduced.
7. macOS-generated fixtures match Linux-bench hashes (realRoot divergence resolved) — the #2086 class cannot reappear because there is one code path.

Consequences

• Positive: the dominant churn trigger (content edits to copied files) becomes fixture-free; fixtures shrink from ~520 KB to a few KB; diffs become reviewable; the duplicate-driver drift class (#2100/#2117/#2086-realRoot) is eliminated; the refactor fence and converter-bug detection are preserved and sharpened.
• Negative / risk: copy-parity depends on modeling each surface's path injection (§3 spike). If a surface's injection is not cleanly invertible, it retains a small re-derived reference (still no manual regen). One-time migration churn to replace the 18 fixtures.
• Neutral: Phase 3 (CI-owned regen / context.assert.snapshot) is optional polish; the churn win lands in Phase 2.

References

• tests/golden-install-parity.test.cjs — current harness
• scripts/gen-golden-install-parity-zcode.cjs — duplicate generator (to be deleted)
• tests/helpers/install-shared.cjs — shared install harness (target for the single-source builder)
• scripts/ci-test-scope.cjs:117-145 — scoped-CI selection of the golden test
• ADR-1239 (Phase B safety net); issues #2086, #2095, #2100, #2117, #1691
• Node.js test runner: context.assert.snapshot + --test-update-snapshots
• Jest --ci snapshot posture (fail on new snapshot, deliberate -u regeneration)

Amendment (2026-07-14): Phase 2 redesign — the copy/transform split was unsound

Implementing Phase 2 began with an empirical spike classifying every emitted install file. It overturned the §2–§4 premise:

• The copy/transform boundary is not clean. Nearly every emitted file passes through a deterministic rewrite (path-prefix canonicalization, {{GSD_VERSION}} stamping, hyphen-normalization) — even for claude, the reference host. Only ~36% of claude's files are byte-identical to source; ~64% are "transformed." A "content-hash only the transformed ~5%" golden (§4) was the wrong model.
• The §3 from-source copy-parity property test is unsound. Asserting emitted == transform(source) by calling the installer's own transform functions is largely tautological (it catches only non-determinism) — strictly weaker regression coverage than the current golden. Making it independent means reimplementing the transform in the test — the exact duplication this epic fights. It is also noisier than the golden it replaces: the harness's configDir == $HOME collapses path canonicalization differently than a real install, mis-classifying ~147 of claude's files as transforms.
• The real defect was stale fixtures, not platform divergence. The Phase-1 red (gsd-statusline.js + 3 claude-local files) was deterministic (macOS hash == Linux-bench hash for every entry); the fixtures were simply stale because golden-install-parity was not selected by CI when the emitting source (a hooks/ file) changed, so it merged undetected.

Revised Phase 2 (implemented in #2267):

1. File-set snapshot — tests/golden-install-tree.test.cjs + tests/fixtures/install-tree/*.json: a per-runtime sorted list of emitted paths (no hashes), reusing the single-source exclusions via buildInstallTree (= sorted keys of buildParityManifest). Cheap structural coverage; changes only when the file set changes, giving a clean reviewable diff instead of hash noise.

2. Anti-staleness CI selection — scripts/ci-test-scope.cjs gains a rule selecting golden-install-parity + the file-set snapshot whenever an installed-source path changes: the four gsd-core/ content subtrees (workflows, templates, references, contexts) + gsd-core/bin/shared/*.json, plus hooks/**, commands/**, agents/**, skills/**, and the shipped scripts/* files (scripts/changeset/, scripts/lib/, and three named generators) — not just src//installer paths. gsd-core/bin/** (tsc-compiled) is deliberately excluded (already covered by the installer rule). This makes the #2266 silent-staleness class impossible: a source edit that changes emitted output re-verifies the fixtures at PR time.

3. Regeneration convenience (Phase 3, #2268) — an npm run gen:golden one-command regenerator (both fixture sets, each now self-building hooks/dist) that the golden-parity/tree failure messages point at, so drift caught by (2) is a one-command fix. The full CI-auto-comment (auto-posting the fixture patch on drift, jest --ci posture) is deferred: it needs a write-token workflow running on PR code (an injection surface) that cannot be verified locally.

Deferred as an optional future refinement: the §3-style content-dedup of verbatim copies. The safe subset (structurally raw-copied non-.md/.js data files) is modest, and the broad form is unsound — a .md file that is byte-equal today transforms the moment a self-reference is added, producing false property-test failures. Since the anti-staleness rule already removes the root pain (silent stale merges) and the file-set snapshot adds structural coverage, the content-hash golden is retained as-is; churn on transformed output is legitimate (you should review transformed output when you change its source).