0002. Curated version snapshots for diagram history, not git-derived history

• Status: Accepted
• Date: 2026-09-10
• Deciders: Konrad engagement team
• Needs client validation: No — internal tooling choice
• Domain: tooling

Context

WS 2 runs three weeks of working sessions with lines of business whose explicit purpose is to change the architecture. At the executive readout we have to answer "what changed after the identity session, and why" — and the SOW names a "stakeholder alignment and feedback summary" as a deliverable. So revision history is not a developer convenience here; it is part of what we hand over.

Two things could serve as the history. Git already records every save. But git history is complete, not meaningful: it interleaves typo fixes and label nudges with real architectural turns, its unit is the commit rather than the review moment, and nowhere in it does the feedback that caused a change get recorded. Squash-merging or rebasing scrambles it further.

ADR-0001 already established typed JSON IR as the source of truth, which makes snapshotting cheap — a version is just a copy of one small file.

Decision

Keep a short, curated list of deliberate snapshots per diagram in diagrams/versions/<slug>/, cut explicitly with npm run version:cut, each carrying a label, a date, a note, and the feedback items that drove it. Git remains underneath as the complete audit trail; these snapshots are the narrative laid over it.

The build renders each version, generates an Archify Architecture Delta between consecutive versions, and produces a timeline page. A dock is injected into every rendered artifact so a reader can step through iterations in place.

Two guards keep the timeline honest: version:cut refuses to snapshot a diagram that does not validate, and refuses a snapshot identical to the previous version.

Alternatives considered

Option	Pros	Cons	Why not
Derive versions from git history	Zero new bookkeeping; complete by construction	Commits are not review moments; no feedback captured; noisy; rebase/squash destroys it; rendering every commit is slow	The unit of history we need is "what we showed the LOB leads", which git does not model
Git tags as version markers	Uses git, but curated	Still no place for feedback/notes; tags are repo-global for a per-diagram concern; needs checkouts to render	Half the bookkeeping of snapshots for less of the payoff
Keep only the current diagram, screenshot old ones by hand	No tooling	Not diffable, drifts immediately, no structural comparison	Fails the "what exactly changed" question outright
Full snapshots, no metadata	Simplest	The metadata is the deliverable	Loses the reason each revision exists

Consequences

Easier. "What changed between v2 and v3" is answered by a generated artifact with exact added/removed/changed/moved facts, not by memory. Because the compare receipt classifies each change as semantic, topology, or geometry, the timeline can state plainly whether a revision was structural or layout-only — a claim worth being able to make precisely in front of an executive. Feedback lives beside the change it caused, which is most of the alignment summary WS 2 owes.

Harder. Cutting a version is a deliberate act someone has to remember; forget it and the timeline is thinner than the real history. Mitigated by the timeline always showing a "working copy — uncut changes" row with its own delta, so drift is visible rather than silent.

Committed to. diagrams/versions/ is tracked, not generated — it is source. Version snapshots are immutable once cut; a mistake is corrected by cutting a new version or editing the metadata in history.json, never by rewriting a past snapshot.

Cost. A few KB of duplicated JSON per version, and a slower cold build. Incremental builds reuse immutable version renders, so the dev loop stays flat as versions accumulate.

Dependencies and open questions

• Deltas are architecture-only. Archify's compare supports the architecture type and no other. Workflow, sequence, dataflow, and lifecycle diagrams get the version picker and timeline, but no automatic "what changed" — the timeline says so rather than implying a delta exists. If those types need deltas later, that is a change to Archify, not to this repo.
• Whether Manulife wants the version history included in the final handoff, or only the accepted final state, is unconfirmed. Tracked in open-questions.md.