Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0098

ADR-0098: First-docs-capture rule — a graph ADR node whose body was never captured from docs/adr/ (it holds a wiki summary or is empty) is baselined once from its docs body; immutability binds from that first docs capture onward

← ADR-0097 · ADR-0099 →

The record

Status: Accepted (ruling, Mohamed, 2026-10-13, verbatim: "agreed on 0098, rerun the sync fix when hooks land") · Date: 2026-10-13 · Extends ADR-0096 (which authorised one re-baseline, ADR-0073) · Evidence: the body comparison added to check_adr_graph_sync.py under ADR-0096, run read-only against the live graph by the builder on 2026-10-13 (worktree adr-sync-fix, checkpoint 09e29ec7e)

Context

ADR-0096 authorised a single re-baseline because the audit of the 36 sync refusals found only ADR-0073 with a stale graph body. The audit answered the question it was asked: of the ids the sync refused to overwrite, which had drifted. It could not see ids the sync never tried to compare by body.

The body comparison the builder added to the check (docs body_sha versus graph for every factory id) reports 35 BODY_DRIFT rows over 122 ids, 70 docs ids compared, and they are not the 35 pointer ids of the audit:

• ADR-0034…0036, 0054…0058, 0062…0079: the graph holds the body captured from the wiki page (the one-paragraph summary) or an empty body with status Proposed; the wiki parser reads the - **Status:** bullet form as blank. The docs files hold the full bodies.
• ADR-0080…0085, 0087, 0089, 0096: all carry the empty-body hash c60b1f6ce4, i.e. the graph node was created from a wiki bullet entry with no body at all; the docs bodies for these were committed today (0080–0085, 0096) or on 10-12 (0087, 0089).
• ADR-0073 is in the list, as ADR-0096 expected.

Two mechanisms produced this: the wiki pass ran alone on the day many nodes were first written (the --repo-adrs pass did not run), and the wiki parser folds whatever prose it finds into decision. The immutability guard then did its job on the wrong baseline: it now protects wiki summaries and empty bodies as if they were the accepted decisions. Under ADR-0096 as written, the check cannot reach OK: --repo-adrs fixes the Proposed nodes but the Accepted ones with wiki bodies are refused, and ADR-0096 names only 0073.

Decision (proposed)

1. A docs body is the only body immutability protects. A graph ADR node whose stored body was captured from the wiki page or is empty has never held the accepted decision; baselining it from docs/adr/ is a first capture, not an edit. The guard binds from that first docs capture onward, and rebaselined_by/rebaselined_at record the event.
2. The set is computed, not listed. The re-baseline path accepts an id when (a) a docs file exists for it and (b) the graph body hash equals the empty-body hash or equals the hash of the wiki entry's parsed body, or the node carries no docs-capture marker; it refuses any id whose graph body already came from docs and differs (that is real drift and needs its own ADR). The 35 ids above are the result of that rule today; the report lists them with the reason per id.
3. One run, logged, under this ADR's authority. sync_architecture_to_graph.py --rebaseline-first-capture --authority ADR-0098 performs it once, logs a REBASELINED: line per id with the before/after hashes, and writes the docs-capture marker. ADR-0096's single-id path stays for named exceptions.
4. The wiki pass never writes a body for a docs-owned id again (ADR-0096 rule 1), and --repo-adrs runs in every sync, so the condition cannot recur; the check's body comparison is the proof and must print 0 BODY_DRIFT after the run.
5. ADR-0004 and ADR-0019 are unaffected (graph already holds their docs text; ADR-0096 rule 4 stands).

Alternatives rejected

• Thirty-five single-id authorities. Same outcome, thirty-five ADRs of noise; the condition is one mechanism, so one rule.
• Accept the wiki bodies as canonical. They are summaries; the decisions live in docs by ADR-0046/0047.
• Leave the check red. A check that is red by construction stops guarding; ADR-0096 made the body comparison the guard.

Consequences

• The sync-fix builder's brief gains rule 2–3 (computed set, one logged run) and its DONE WHEN "check prints OK" becomes reachable.
• @traces: REQ-106-006 (immutability) gains a sentence for first capture; the builder's choice of SPEC-106 is ratified.
• After the run, 122 ids compare clean by body; from then on any BODY_DRIFT is a genuine post-capture edit.

Provenance

Builder report of 2026-10-13 (check output: 35 BODY_DRIFT / 122 ids / 70 compared; id groups and the empty-body hash as quoted). Drafted by the coordinating session. Ruled Accepted by Mohamed on 2026-10-13 ("agreed on 0098, rerun the sync fix when hooks land"). The sync-fix builder's checkpoint d2d93ea53 already carries rebaseline_first_capture and the --rebaseline-first-capture --authority ADR-0098 path with tests (142 passed across 9 files), unexecuted; execution happens in the rerun after ADR-0097's hook fix is deployed.

Related ADRs

• Also mentioned: ADR-0096, ADR-0073, ADR-0034, ADR-0080, ADR-0004, ADR-0019, ADR-0046, ADR-0097

Rulings cited

None.

Specs cited

• SPEC-106