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

ADR-0126: The kg is branch-aware: each synced branch is its own project, serialized from a clean commit and checked after every sync

← ADR-0125 · ADR-0127 →

The record

Status: Proposed (the direction ruled by Mohamed 2026-10-22; the naming and mechanics proposed) · Date: 2026-10-22

Context

Measured 2026-10-22 on the prod kg (orchkg, main 10.53.1.123 and replica 10.53.1.128 agree):

• One project id, many trees. Every orchestrata checkout syncs into the single project orchestrata-ultimate: master and its worktrees, the components branch (wt-COMPONENTS), and any session's hooks or live sync. Nothing records which branch or commit the graph describes.
• The kg has lost modules. The project node says 5,252 modules, synced 2026-10-20 01:18 UTC (the wiki measured 5,232 that night). The kg now holds 4,195. The 1,064 missing ones (with all their classes and functions) form two contiguous ranges in sorted path order: claude/hooks/__init__.py → infra/rehearsal/enroll_orchgraph.py (114) and rtm/scripts/__init__.py → src/orchestrata_ultimate/plugin/registration.py (924). That pattern fits a batched rewrite that lost two batches. The weekly retention job last ran on 10-18, before the sync, so it is ruled out. The run that cleared the project is not yet identified.
• Snapshots depend on who runs them. env/ast-roots.env declares 23 roots, the eight packages/*/src included, on both master and components. Yet the 10-21 snapshot in wt-COMPONENTS has 3,334 modules from 6 roots and no packages: it was produced with a different root set in that session's environment. A full sync from it would have deleted the 1,771 package modules.
• Working trees are not commits. wt-COMPONENTS had 64 uncommitted changes and the master worktree 9; a snapshot taken there describes neither branch.
• codetools exists in the kg as a name-only project node with 0 modules; it has never been synced.

Decision (Mohamed, verbatim: "make the tree branch aware option b")

1. Branch-aware (ruled). The kg holds each synced branch as its own project, so syncing one branch never overwrites another.
2. The components branch is synced now (ruled, option B).
3. Naming (proposed). The default branch keeps the bare id (orchestrata-ultimate = master), so every existing consumer keeps working. Any other branch is <project>@<branch>, for example orchestrata-ultimate@components. Node ids already embed the project id, so branches never collide.
4. Source of a sync (proposed). A kg snapshot is serialized from a clean export of a commit (git archive <sha>), with the commit's own env/ast-roots.env, never from a working tree.
5. Every sync is checked (proposed). After a sync, the module paths in the kg are compared with the snapshot. Any missing module is re-synced (incremental --modules) and the comparison repeated until it is empty.

Alternatives rejected

• One project, the last writer wins. That is today's state, and it is how a sync from one tree can delete another tree's modules.
• A branch property on every node under one project id. Node ids would collide across branches (orchestrata-ultimate:module:<path> is the same on every branch), and every query would have to filter by branch.
• Option A, master only. Mohamed chose the components branch.

Consequences

• Mechanisms owed (worker briefs, RUL-041): the sync takes --branch and --commit and writes them on the Project node; it refuses a dirty tree; it runs the post-sync comparison itself and exits non-zero on a gap. Consumers (hooks, force-graph-query, context injection, volk work-context traversals) resolve the project id from the cwd's branch, falling back to the bare id.
• Until the sync writes branch and commit itself, the branch and commit of each sync are recorded in this ADR's Provenance and the design notes.
• The bare orchestrata-ultimate project stays partial (4,195 of about 5,220 modules) until master is re-synced from a clean export of origin/master.
• codetools is synced as its own project, by the same procedure.

Provenance

• Mohamed, 2026-10-22, verbatim: "check the knowledge graph, which i want to alias as kg for the future in all conversations, and see if the project is synced there and if not i want it synced"; "go with step 1"; "yes do that"; "make the tree branch aware option b".
• Evidence: graph_query.py cypher against KG_MAIN_URI and KG_REPLICA_URI; the comparison of the kg module list with plans/ast-ultimate.json in the master worktree (5,220 modules, 4,156 shared) and in wt-COMPONENTS (3,334 modules); systemctl --user list-timers (retention last ran 2026-10-18).
• First branch sync: components at d4b7e162a, exported clean to scratch with all 23 roots (5,251 Python files).

Related ADRs

No other ADR is named in this record.

Rulings cited

• RUL-041: RUL-041 — The host Claude writes no orchestrata code; it perfects the briefs, checks and workflow and measures the…

Specs cited

None (or no spec page exists for the ones named).