Orchestrata Ultimate › Plans › briefs › 2026-09-22-adr-0047-register-aware-adr-tooling

Brief: make the ADR tooling register-aware (execute ADR-0047)

Source: plans/briefs/2026-09-22-adr-0047-register-aware-adr-tooling.md at 8a2cb42ad · last changed 2026-09-22 · first committed 2026-09-22 · 105 lines.

Prose pending.

Plan text

Brief: make the ADR tooling register-aware (execute ADR-0047)

DESIGN_WAIVER: ADR-0047 (Accepted 2026-08-29). Scope is exactly that ADR's mandate: "ids match as zero-padded strings — ADR-0001 (factory register, docs/adr) and ADR-001 (project register, the wiki page) are different ids. register becomes a graph-node property; the gate matches (register, padded id); nothing renumbers."

GOAL

parse_adrs, ArchitectureWriter.upsert_architecture_decision, scripts/sync_architecture_to_graph.py --adrs and scripts/check_adr_graph_sync.py all key an ADR by (register, padded_id) so the two registers on the wiki page never collapse onto one integer.

FACTS (measured 2026-09-22)

• The wiki page has 83 ## ADR-…: headings: 58 four-digit (factory) and 25 three-digit (project). Numbers 1..25 are claimed by BOTH registers. parse_adrs returns 83 entries with only 58 distinct numbers.
• load_wiki_adrs / load_repo_adrs / load_graph_adrs in the gate all return dict[int, …], so the later heading silently wins.
• upsert_architecture_decision builds id = f"{project}:ADR-{int(n):04d}", so a project entry is written under the factory id. That is how the single node orchestrata-ultimate:ADR-0001 came to carry the project title 'Memgraph as Semantic Graph Backend', and why the sync now aborts with AdrImmutabilityError on the factory ADR-0001 before writing anything else (46 gate violations, all downstream of this).
• The graph the gate/sync use under the default test profile is 10.53.2.10 orchkg; it holds exactly one ArchitectureDecision node (the one above). The one-time re-key of that node is NOT this brief's job; Mohamed ruled it and the orchestrator executes it after this lands.

FILES

• src/orchestrata_ultimate/knowledge_graph/adr_parser.py
• src/orchestrata_ultimate/knowledge_graph/architecture_writer.py
• scripts/sync_architecture_to_graph.py
• scripts/check_adr_graph_sync.py
• tests/knowledge_graph/test_adr_parser.py
• tests/knowledge_graph/test_architecture_writer.py
• tests/scripts/test_sync_architecture_to_graph.py
• tests/scripts/test_check_adr_graph_sync.py
• Nothing else. Do not touch the wiki page, docs/adr, or any env file.

DESIGN (settled)

1. ParsedAdr gains two fields: register: str ("factory" when the heading id has 4 digits, "project" when it has 1–3 digits) and padded_id: str (the heading's digits verbatim, e.g. "0001" / "001"). number: int stays for callers that only need the integer. parse_adrs and parse_adr_file populate both; parse_adr_file (docs/adr files) is always factory.
2. upsert_architecture_decision takes padded_id: str and register: str (keyword, required alongside adr_number); the node id becomes f"{project}:ADR-{padded_id}"; register and padded_id are written as node properties; adr_number stays as today. Every existing caller is updated; the immutability check is unchanged.
3. sync_adrs passes register and padded_id through.
4. The gate keys every corpus by (register, padded_id): load_repo_adrs (factory only, from filenames/headings), load_wiki_adrs (both registers, from headings), load_graph_adrs (reads n.register, n.padded_id; a node lacking them is reported as a LEGACY_UNKEYED violation naming its id and title, never silently binned). AdrSyncRow carries register and padded_id; output lines print ADR-<padded_id> prefixed by the register when it is project. A wiki project entry with no docs mirror is NOT a violation (the wiki is that register's file of record).
5. Tests: extend the four test modules with real cases: a page holding ## ADR-001: and ## ADR-0001: with different titles parses to two entries with distinct (register, padded_id); the writer creates two distinct nodes for them on the real test graph and neither raises immutability; the gate on that fixture reports 0 violations; a legacy node without register surfaces as LEGACY_UNKEYED. Writer/gate tests use the real graph exactly as the existing tests in those modules do.

CONSTRAINTS

• No mocks/fakes/stubs/monkeypatch, no skip, no xfail.
• Read Python through scripts/serialize_codebase_ast.py only; edit with Edit/Write. Test runs: background, timeout 300, ORCHESTRATA_ENV_PROFILE=test, -p orchestrata_ultimate.core.threading.pytest_live_observer.
• Do NOT run scripts/sync_architecture_to_graph.py --adrs for real and do NOT write to orchestrata-ultimate:ADR-0001 on any graph; the orchestrator holds that ruling. --dry-run is fine.
• Commit with git -c user.name=Mohamed -c user.email=msamy@sufigeeks.org, no AI attribution lines (RUL-007 gate). Do not push.

DONE WHEN

• The four test modules pass (0 failed / 0 skipped / 0 xfailed) in one observed background run.
• uv run ruff check + uv run ruff format --check clean on all touched files; uv run pyright reports no new errors in src/ or scripts/ for them.
• scripts/check_adr_graph_sync.py run for real (read-only) reports the stale node as LEGACY_UNKEYED for ADR-0001 and otherwise only MISSING_FROM_GRAPH rows (the sync has not run yet) — no crash, no AMBIGUOUS_COLLISION on numbers 1..25.
• One commit on master containing the eight files and this brief unchanged.

VERIFY (report verbatim)

• The pytest summary line of the run over the four modules.
• The first 8 lines of the real check_adr_graph_sync.py output.
• The commit sha and git show --stat HEAD.

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks