ADR-006: colibri_code: none Semantics and the Executable-Meaning Contract

Status: Accepted Date: 2026-04-09 Round: R73 Supersedes: None Superseded by: None

Context

Every concept document (docs/concepts/α-system-core.md through docs/concepts/ξ-identity.md) carries a frontmatter key colibri_code. At R73, all 15 concepts have colibri_code: none. This is correct: src/ was deleted in R53 and Phase 0 has not started. Zero TypeScript files exist.

But in rounds R54 through R72, this key was used inconsistently. Some docs described features as if they existed. Some diagrams showed live code paths. Some promise.md and scenario.md files described the 7-state pipeline in the present tense, which reads as if it runs today.

The human’s R73 complaint — “по документации не чуствуется что это одна система” (“the docs don’t feel like one system”) — is partly this: docs that describe running behavior when nothing runs cause cognitive dissonance. They feel like marketing copy for a product that doesn’t exist.

This ADR fixes the semantics and sets a contract for how the frontmatter key is used.

Decision

colibri_code is a four-state enumeration. Every doc describing a runtime feature must carry it.

Value Meaning Verb tense in prose
none No source code exists. Feature is target design only. Future (“will”, “is designed to”, “once implemented”)
stub A code file exists but it is a no-op or placeholder. Conditional present (“stubs return constant”, “not yet scored”)
partial Implementation exists but does not meet the full spec. Present with qualification (“currently supports X; Y is in progress”)
complete Implementation meets the spec, tested, covered by writeback contract. Present indicative (“returns the root hash”, “validates the chain”)

At R73 (decision time)

Every one of the 15 concepts had colibri_code: none. There were zero stub, partial, or complete concepts.

At R75 Wave H.2 (first graduation wave, 2026-04-18)

7 concepts graduated from none to partial, matching the 7 shipped axes through Phase 0:

Letter Concept doc New value Graduation wave
α docs/2-plugin/middleware.md partial Wave A/B/C (P0.2.1–P0.2.4)
β docs/3-world/execution/task-pipeline.md partial Wave C/D/E (P0.3.1–P0.3.4)
γ docs/2-plugin/modes.md partial Wave A/E (P0.4.1–P0.4.2)
ε docs/3-world/execution/skill-registry.md partial Wave C/D/H (P0.6.1–P0.6.3)
ζ docs/3-world/execution/decision-trail.md partial Wave C/D/G (P0.7.1–P0.7.3)
η docs/3-world/physics/laws/proof-store.md partial Wave E/F (P0.8.1–P0.8.3)
ν docs/4-additions/index.md partial Wave F/G (P0.9.1–P0.9.3)

Wave H.2 also introduced a graduation: frontmatter field on every partial concept. This one-line string names the wave + tasks that moved the concept off none, so that future readers can trace the provenance without re-reading the wave memos.

At R75 Wave I (second graduation wave, 2026-04-18)

1 additional concept graduated from none to partial, closing Phase 0 at 28/28:

Letter Concept doc New value Graduation wave
δ docs/3-world/social/llm.md partial Wave I (P0.5.1 scoring + P0.5.2 fallback, library-only per ADR-005 §Decision)

After Wave I, 8 concepts are partial (α β γ δ ε ζ η ν) and 7 remain none (θ ι κ λ μ ξ π — all spec-only for later phases). None are promoted to complete because Phase 0 is a slice of each concept’s full phased spec — complete requires the full public API plus verification, which spans phases beyond Phase 0.

δ’s graduation is an interesting case under this ADR’s promotion rules: the Phase 0 δ surface is a pair of library stubs (scoring.ts returning a constant, fallback.ts with one member) with no MCP tool, so a strict reading of “50% of public API implemented” would keep it at stub. But ADR-005 §Decision explicitly required this exact shape as the Phase 0 δ — the interface is complete for the Phase 0 contract, even though Phase 1.5 will replace the formula. We promote to partial on that basis and record the reasoning here. A reader interpreting ADR-006 strictly in isolation would arrive at stub; a reader cross-referencing ADR-005 arrives at partial. The ADRs are co-authoritative.

Promotion rules

A concept may be promoted from none to stub only when:

  • A file exists under src/ that is recognizably part of that concept
  • The promotion is the output of a task with full writeback
  • The promotion commit is reviewed by PM at the wave gate

A concept may be promoted from stub to partial only when:

  • At least 50% of the spec’s public API is implemented
  • At least one Jest test file exercises the implementation
  • The promotion is the output of a task with full writeback

A concept may be promoted from partial to complete only when:

  • 100% of the spec’s public API is implemented
  • Test coverage meets the project standard (TBD; initially ≥80% line coverage)
  • All invariants in the contract file are verified
  • A verifier-mode T3 executor has signed off via a verification doc
  • The promotion is the output of a task with full writeback

Demotion rules

A concept may be demoted (e.g. complete → partial) only via Sigma’s Phase B authority during a round that removed functionality. Demotion requires an explicit thought_type="demotion" thought record explaining why.

Consequences

Positive

  • Honest present tense. When a doc says “Colibri does X”, readers can trust it. The frontmatter lets readers verify.
  • Review filter. A doc that changes prose from “will” to “does” must also change colibri_code. Sigma’s Phase B audit catches mismatches.
  • Memory discipline. MEMORY.md can’t drift to “R54 complete, system runs” when the concepts it names are all colibri_code: none. The conflict is visible.
  • Prompt clarity. Agent bootstrap prompts can auto-generate from the frontmatter: “the following concepts are none, do not treat them as running”. This kills the “presenting design as feature” class of hallucination.

Negative

  • Lint overhead. The colibri-docs-check skill must grow a linter that flags present-tense prose in colibri_code: none documents. Mitigation: start manual; automate when the pattern stabilizes.
  • Pedantry cost. Some prose reads less fluidly in future tense. Mitigation: targeted present tense is allowed in extractions and reference docs (which describe algorithms, not runtime state).

Neutral

  • The status field from older Greek frontmatter (Spec-ready, Spec-only, Partial) is deprecated in favor of colibri_code. During R73 both exist; status is removed in R74.

Implementation

Required fields for concept docs 

---
letter: α | β | γ | ...
concept: System Core | Task Pipeline | ...
axis: execution | intelligence | legitimacy | cross-cutting
colibri_code: none | stub | partial | complete
phase: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8
spec_source: <path to spec file>
---

Required fields for reference docs describing algorithms 

---
type: extraction
source_concept: <letter>
colibri_code: none
---

Reference docs may be present-tense (they describe algorithms), but they must carry colibri_code: none to make clear the algorithm is not yet implemented.

Check list for promotion (added to colibri-docs-check skill) 

[ ] A file under src/ matching the concept is present
[ ] The file exports the public API in the spec
[ ] A Jest test file exists for the concept
[ ] The concept doc has been updated with the new colibri_code value
[ ] The promotion thought_record exists with justification
[ ] PM has approved the promotion at wave gate

Tense rewriting guide

When a doc is at colibri_code: none:

Don’t write Write instead
“Colibri validates every decision” “Colibri will validate every decision”
“The task moves through 7 states” “Tasks are designed to move through 7 states”
“The Merkle root anchors the chain” “The Merkle root is intended to anchor the chain”
“Requests return within 50ms” “Requests are targeted to return within 50ms”

This is a small rewrite but a large honesty gain.

Alternatives Considered

Alternative A — Use a simple boolean implemented: true/false

Rejected. “Implemented” is a gradient, not a boolean. A stub is implemented in the sense that files exist but not in the sense that anything runs. The four-state enum captures the gradient.

Alternative B — Use the older status: Spec-ready | Spec-only | Partial | Complete

Rejected. “Spec-ready” means the spec is ready, not that the code is. That’s what made the old field ambiguous. The new colibri_code key names exactly what it measures: the code.

Alternative C — Delete the field entirely and rely on prose

Rejected. Prose does not grep. A greppable field lets Sigma audit every concept in one pass and produces an accurate status report.

Alternative D — Use status + colibri_code both

Rejected as R74 cleanup work. Two fields with overlapping meaning is worse than one, even if the overlap is partial. status is deprecated in R74.

Verification

This decision is verified at every round:

  • At Phase A, Sigma reads every concept doc’s frontmatter and confirms colibri_code is present
  • At Phase B, Sigma runs colibri-docs-check to verify no doc changed prose tense without matching frontmatter change
  • At Phase B of any promotion round, Sigma verifies the promotion rules were followed

Failure of any check blocks the seal.

References

  • docs/concepts/ — every concept doc must carry this frontmatter
  • docs/colibri-system.md §2 — “All 15 concepts have colibri_code: none”
  • .agents/skills/colibri-docs-check/SKILL.md — verification skill
  • .agents/skills/colibri-truthing/SKILL.md — factual verification skill

R73 unification corpus. Answers “how do we avoid presenting design as feature?” — via a greppable frontmatter field and a verb-tense contract.

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.