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

ADR-0007: Traces are structurally validated, never model-declared

← ADR-0006 · ADR-0008 →

The record

• Status: Accepted
• Date: 2026-07-23
• Spec: SPEC-033 §3

Context

Generated code carries @traces(spec, req, design_node, adr), and the "completeness tripwire" holds that untraceable code is an orphan = an ungoverned path.

But the annotation is emitted by the model, and the existing validation (verification/traceability.py::validate_traces) computes set differences over requirement-ID strings: it checks that an ID the model wrote also appears in the spec. It never checks that the annotated unit implements that requirement, nor that the trace is attributed to the correct unit.

Consequences of that as-built design:

• An empty stub annotated @traces(reqs=["REQ-X"]) verifies.
• A trace attributed to the wrong function passes; misattribution is invisible.
• The tripwire fires only on code that forgot to lie.

A completeness detector whose input is a self-report is not a detector — the entity being governed authors the evidence that clears the gate.

Decision

A trace is valid only if both hold, checked structurally:

1. The traced unit's AST lies within the cited design node's contract (so an arbitrary node cannot be cited — signatures must match), and
2. the unit is reached by a test that asserts on it.

Presence of an annotation is necessary and not sufficient.

Alternatives rejected

• String/ID membership matching (status quo) — forgeable, as above.
• Model-reviewed trace correctness — replaces one model self-assessment with another.
• Requiring human review of every trace — does not scale, and is the load this system exists to reduce.

Consequences

• Depends on the AST≡design contract representation (SPEC-033 B2/B3) — a trace cannot be checked "within contract" before a contract format exists.
• This relocates the circularity rather than breaking it: validity now leans on test quality, and a weak-but-asserting test still satisfies clause 2. That residual is addressed by requirement-derived anchors (ADR-0012) and interpretation mutation — and is stated plainly rather than claimed away.
• Orphan detection becomes meaningful for absent traces; false traces are constrained (not eliminated) by clause 1.

Provenance

Round-1: all reviewers independently identified the circularity, code-verified against validate_traces. Round-2 accepted the structural definition; Round-3 Opus insisted the "breaks the circularity" phrasing be downgraded to "relocates" — reflected above.

Related ADRs

• Also mentioned: ADR-0012

Rulings cited

None.

Specs cited

• SPEC-033