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

ADR-0114: orchkg sees the component packages, and Spec and Requirement nodes are in scope

← ADR-0113 · ADR-0115 →

The record

Status: Accepted (ruling, Mohamed, 2026-10-19, verbatim: "all" — ratifying recommendation R5 option A of reports/project-analysis-2026-10-19.md) · Date: 2026-10-19

Context

orchkg was synced on 2026-10-19 from the monolith root only (root_path …/src/orchestrata_ultimate, synced 22 minutes before the prod deploy). Zero module paths start with packages or any orchestrata_<component> package name; the graph holds 0 Spec nodes and 0 Requirement nodes. The standing instruction is to answer project questions from that graph — an agent obeying it describes the star around core and cannot see the component DAG (finding F3). The repo holds 72 specs/*/spec.md files and 58 specs/*/checklists/requirements.md files; traceability lives there and in @traces (finding F5-adjacent: an empty label the schema promises is a false answer, not an absence of requirements).

One mechanism detail decides the shape: the AST walker skips nested distributions (DISTRIBUTION_MARKERS = pyproject.toml/setup.py/setup.cfg, src/orchestrata_ast/analyzer.py), and every component package is a distribution — so packages cannot be added as one root and yield any modules.

Decision (Mohamed, verbatim: "all" — R5 option A)

1. env/ast-roots.env gains one root per component package's src dir, appended after the existing set: packages/contracts/src, packages/governance/src, packages/kg/src, packages/kernel/src, packages/session/src, packages/volks/src, packages/gateway/src, packages/tools/src. Integration's src joins when it lands (ADR-0113). The snapshot (plans/ast-ultimate.json), the live sync, and the Prolog KB then cover the components; module ids carry their root-path prefix (packages.kernel.src.orchestrata_kernel.…), which the existing prefix rule already produces for every later root. The first root stays primary.
2. Spec and Requirement nodes are in scope for orchkg: Requirement nodes from the @traces decorators of both trees (existing scripts/sync_traces_to_graph.py, pointed at orchkg) and from specs/*/checklists/requirements.md; Spec nodes from specs/*/spec.md. The sync step verifies with count queries — both labels must return > 0 after the sync. A worker brief fills any tooling gap the existing scripts cannot cover; documenting the labels as out of scope is rejected.
3. The re-sync is a full project sync (sync_ast_to_graph.py full with the new root set), then the traces/specs sync, then verification queries for component paths and node counts.

Alternatives rejected

• Leave the graph on the monolith until cut-over (option B) — every agent keeps describing the architecture that is being replaced, and the graph cannot arbitrate between LEVEL0 and the mission memory.
• Silent empty Spec/Requirement counts — a false answer an agent would hand to the next session.

Consequences

orchkg describes both trees. Traceability queries (RUL-028) cover component code, and the graph can answer a question about orchestrata_contracts with modules rather than an absence. The null-module-count Project residue (finding F9) is a separate hygiene item, untouched by this ADR.

Provenance

Mohamed's in-session ruling 2026-10-19 ("all") on recommendation R5 of reports/project-analysis-2026-10-19.md (finding F3, §5 measurements). Root-declaration authority: env/ast-roots.env + src/orchestrata_ast/roots.py.

Related ADRs

• Also mentioned: ADR-0113

Rulings cited

• RUL-028: RUL-028 — Traceability is a query, never a file sweep

Specs cited

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