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

ADR-0089: Bare toolchain names fail the gate in Prolog, and the C toolchain is one declared file

← ADR-0088 · ADR-0090 →

The record

Status: Accepted · Date: 2026-10-11

Context

Two failures, measured on 2026-10-11, have one cause: a program named by a bare word is resolved from PATH, and on this host PATH does not point where the code assumes.

• Interpreters. Session shells inherit the direnv environment of the primary checkout orchestrata-ultimate-architecture (branch architecture/domain-model, ~530 commits behind master), so its .venv/bin leads PATH. Run from a worktree, python -c 'import orchestrata_ultimate' imported the primary checkout's stale src/. Any subprocess.run(["python", ...]) therefore executed another checkout's code.
• Compilers. ~/.guix-profile/bin also precedes /usr/bin, so a bare gcc is Guix GCC 16.2.0. It fails the vendored janus-swi build against the system swipl headers, and Guix's C_INCLUDE_PATH leaks math.h ahead of the 3.14t headers. Two worktree provisions failed this way. Four places each chose a compiler of their own: .envrc exported the bare CC=gcc CXX=g++; deploy/install-orchestrata.sh defaulted to bare gcc and re-derived /usr/bin/gcc with a PATH-shadow probe; deploy/install-tools.sh hardcoded /usr/bin/gcc; scripts/worktree_toolchain.py pinned a hardcoded path only when it detected a shadow.

No mechanism could find these sites. The AST snapshot records each call's callee without its arguments, so the program a spawn runs was unrecoverable, and the Prolog gate (REQ-GATE-001) reads facts only from the snapshot.

Decision (Mohamed, verbatim)

"fix bare python make it prolog and atoms"

"make the gcc path a configuration and set it"

1. The snapshot records the facts; it classifies nothing. Every module in plans/ast-ultimate.json carries argv_literals: each literal program token at a spawn-shaped call, recorded verbatim with its file, line, callee text and form (argv / exec / shell). The snapshot declares the per-module captures it performed (captures). That identity is part of the warm-start cache, so a snapshot lacking a capture is fully re-parsed and never read as "captured, none found".
2. Prolog decides. code_facts.pl declares argv_literal/5 and snapshot_capture/1. gate_rules.pl names the toolchain programs as enumerated atoms (toolchain_program/2). The rule violation(bare_toolchain, File, Line, Detail) joins them with waived/2 and in_project/1. Severity is data in gate_severity.pl. A rule whose required capture the snapshot did not perform makes the gate INVALID, never PASS.
3. One compiler declaration. env/toolchain.env (tracked) holds CC and CXX as absolute paths (/usr/bin/gcc, /usr/bin/g++ on this host). Every consumer reads it: .envrc (dotenv, last), deploy/toolchain.sh (installers), and scripts/worktree_toolchain.py (worktree provisioning, janus and tree-sitter builds). Every consumer refuses a missing, bare-named or non-executable declaration rather than fall back to PATH. A host that needs another compiler edits that file.

Alternatives rejected

• Classify program names in the Python extractor. That hides policy in the fact layer; the codebase's rule is facts in code_facts.pl, policy in gate_rules.pl, severity in gate_severity.pl.
• A regex lint over source text. It re-parses files the snapshot already describes (REQ-GATE-009) and cannot see through a cmd = [...]; run(cmd) assignment.
• Keep the PATH-shadow probe. It decides per host and per shell what compiler to use, and it let an inherited bare CC=gcc through.
• Per-consumer defaults. That is the four-way divergence that produced the failures above.

Consequences

• An old snapshot (no captures) forces one full re-parse (93 s measured) on its next regeneration. The gate reads INVALID for it rather than PASS.
• Every existing bare toolchain spawn becomes a gate finding, and those findings are fixed or waived with a reason (# gate-ok: <reason>). If the count is large, the rule may land at warning and move to error once the tree is clean. That is a one-line change in gate_severity.pl, decided by Mohamed.
• Worktree provisioning, both installers and both native build scripts fail loudly on a bad declaration instead of building with the wrong compiler.

Provenance

• Directives: Mohamed, 2026-10-11 (quoted above).
• Evidence: worktree import of the primary checkout's src/ (2026-10-11); two failed provisions with Guix GCC 16.2.0; AST snapshot schema (ModuleInfo before this change carried no call arguments).
• Implementation: feat/bare-toolchain-gate (snapshot capture, Prolog facts and rule) and fix/bare-interpreter-gate (toolchain declaration), specified by the orchestrator and built by the Qwen executor under plans/briefs/qwen/.

Related ADRs

No other ADR is named in this record.

Rulings cited

None.

Specs cited

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