ADR-113: Principles tier above initiative — fundamentals layer constraining the four-tier taxonomy

Status: Proposed Date: 2026-04-26 Related: ADR-083 (defense-in-depth-rule-promotion), ADR-088 (destroy-needs-silence-snapshot-deregister-wait), ADR-089 (host-teardown-protocol), ADR-090 (ai-as-scaffold-pipelines-as-runtime), ADR-098 (epics-and-decomposition), ADR-104 (dry-run-on-history-adaptive-gate), ADR-107 (gates-as-playbook-primitives), ADR-110 (observe-and-file-dominant-pattern)

Context

The board today carries a three-tier taxonomy (warp #299): initiative > epic > ticket. What is missing is a layer above initiative for the fundamental ideas that constrain everything below it — the operator's framing on 2026-04-26 was "the things, the ideas that live above it all". Those ideas exist in the system today but are scattered across four substrates that no warp item points to:

Memory files (feedback_*.md in user memory) carry operator preferences and structural rules — load-bearing but invisible to anyone without access to the operator's memory store.
ADRs (docs/decisions/*.md in dark-factory) capture architecture decisions, but each ADR re-derives the principles it implements rather than citing them.
CLAUDE.md sections (in every repo) carry operational rules — load-bearing inside a Claude Code session but invisible on the board.
Operator messages in flight conversations — the source of new principles, but with no structural landing pad.

The cost is concrete. New initiatives drift from established convention because the convention is not citable. Sub-agents reading warp items do not see the constraints the work must respect; the operator re-explains the same principles every time. ADRs get re-discussed because reviewers do not know which principles already settled the question. The 2026-04-26 saga in warp #321 included multiple iterations that re-discovered principles already established in memory and CLAUDE.md — invisible-principles produce visible-rework.

ADR-098 named the three-tier shape (initiative > epic > ticket) and the decomposition rules. This ADR adds the fourth tier above and establishes the contract that initiatives must cite the principles they are constrained by.

Decision

The board's taxonomy becomes four-tier:

principle  ──── stable rule that constrains everything below
   │
   ▼
initiative ──── strategic direction (months)
   │
   ▼
epic       ──── coherent body of work (weeks)
   │
   ▼
ticket     ──── single PR / single sub-agent turn (hours-days)

kind: principle becomes a first-class warp item. Schema additions over the existing item shape:

applies_to: [<pattern>, ...] — a free-form list of areas the principle constrains (["playbook authoring", "runtime extension", "observer steps"]). Sub-agent briefs use this to decide which principles to surface.
status: proposed | active | superseded — principles have lifecycle separate from tickets. A superseded principle records its replacement in superseded_by.
revision_history: [...] — every amendment recorded; principle bodies are not edited in place, they are revised through an explicit workflow (see r7 of warp #339).

Initiatives MUST cite their constraining principles in a constrained_by: [<principle-id>, ...] field; the warp validator rejects new initiatives that omit it. The validator is permissive about the choice of principles (any active principle is acceptable) but strict about the presence of the field — the goal is to make the citation habit structural, not to police the choice.

The 14 founding principles named in warp #339 are backfilled as kind: principle items in r3 of that epic, drawn from existing memory + ADRs + CLAUDE.md. They are listed here verbatim so this ADR records the founding set:

Structural beats prose — every rule that can be enforced by code rather than narrated should be (memory feedback_structural_over_prose.md).
The system runs without Claude — every gate and safety mechanism must work when the parent agent is not in the loop (ADR-107).
Playbooks are the primitive — every operation graduates to a YAML playbook; the runtime stays minimal (ADR-067, ADR-090).
Observers, not orchestrators — Claude's dominant role is observe-and-file, not execute (ADR-110).
Defense in depth — no single check is the only check; authoring + PR review + runtime + periodic (ADR-083).
Audit everything that mutates — every state-changing action signed, traceable, immutable-logged (ADR-088, ADR-089, ADR-112).
Re-creatable infrastructure — every host, service, dependency must be re-creatable from playbooks (ADR-090).
Adaptive gates earn their place — gates self-promote when they prove necessary; static gates ossify (ADR-083).
Cost is a structural constraint — every model call has a budget; cumulative usage tracked; running over fails closed (ADR-111).
Token-thrift on context — sub-agents default to the cheapest sufficient model; warp items are the durable record, conversation context is ephemeral (memory feedback_token_thrift_routine_agents_haiku.md).
First-real-fire is the gate — every playbook proves it works against a real target before shipping; untested assumptions are bugs.
Provenance via discovered_during — every agent-filed ticket carries the run_id that surfaced it; loss of provenance equals loss of postmortem-ability.
One PR per agent — sub-agents that try to ship multiple PRs stall at the watchdog (memory feedback_subagent_watchdog_600s.md).
Backups before destructive playbooks — silence then snapshot then wait then destroy (ADR-088, ADR-089, memory feedback_destroy_needs_silence_first.md).

The /board UI surfaces principles in a pinned section above the kanban; principle cards show their applies_to patterns and status. Sub-agent brief generation walks the constraining-principles list of the parent initiative and includes each principle body verbatim in the brief — the sub-agent does not need to re-derive the constraint.

The boundary against the existing substrates is explicit: a principle is the stable rule that lives above all decisions; an ADR is the decision implementing one or more principles in a specific architecture choice; a guideline is the how-to per module; a memory file is the operator's preference or shorthand. When a memory file or CLAUDE.md section describes what is actually a principle, r8 of warp #339 backfills it as kind: principle and deprecates the original location with a pointer.

Consequences

What becomes easier.

Sub-agents see the constraints. The brief that lands in a sub-agent's context window includes the constraining principles inline, so the sub-agent does not have to read CLAUDE.md plus memory plus the parent ADR plus a sibling ticket to figure out the rules.
Reviewers anchor to principles. gyrum-review-pr (and human review) can cite "this PR violates principle-3 — playbooks are the primitive" rather than re-arguing the principle from scratch every time.
Principle revisions get an explicit review process. Today an operator preference shifts in a chat message; tomorrow the system catches up. With principles as first-class items, a revision is a PR with a separate review template (r7 of warp #339), and the revision-history field records the change.
The board surfaces fundamentals. /board shows what the system thinks it stands for. New contributors (human or agent) see the rules without needing operator orientation.
Cross-references collapse. Today the same principle is cited (or re-derived) in five places; with one canonical principle item, ADRs and tickets cite the principle by id and the body lives once.

What becomes harder.

A fourth substrate to maintain alongside ADRs, CLAUDE.md, and memory files. Mitigation: the boundary above is explicit (principle = stable rule, ADR = decision, guideline = how-to, memory = preference); r8 of warp #339 actively migrates content out of the wrong substrate.
Risk of overlap or contradiction between substrates. Mitigation: when the same content lives in two places, the principle item is canonical and the other substrate links to it; the migration task in r8 enforces this.
Cost of citation. Every new initiative now requires constrained_by to be filled in; this is friction. Mitigation: the validator rejects empty constrained_by but accepts any active principle, so the friction is "name a principle" not "name the right principle".
Risk of principle proliferation. If every preference becomes a principle, the layer loses meaning. Mitigation: the proposed-status workflow has a 2-of-3-personas-plus-operator-sign-off bar (r7 of warp #339); promoting an idea to principle-tier is a deliberate act.

What we sign up to maintain.

The 14 founding principle items, backfilled with their existing source material cross-referenced.
The kind: principle schema, validator rules, and the constrained_by enforcement on initiatives.
The /board UI surface that pins principles above the kanban.
The sub-agent brief generation path that auto-includes constraining principles.
The principle-revision workflow (separate review template, operator sign-off, revision_history).
Periodic audit of the four substrates: principles in CLAUDE.md or memory get migrated; ADRs that pre-date this tier get back-annotated with the principles they implement.

Alternatives considered

Keep principles in CLAUDE.md only. Considered and rejected — CLAUDE.md is in-session context for Claude Code only. Sub-agent briefs do not auto-include the parent's CLAUDE.md (and even if they did, every repo has its own); reviewers do not read CLAUDE.md while reviewing; the board has no view onto it. The substrate is wrong for fleet-wide rules.
Keep principles in memory files. Rejected for the same reason — memory is per-operator, per-installation. Principles need to be visible to every sub-agent and every reviewer regardless of who is at the keyboard.
Express each principle as an ADR. Rejected on the substrate-purpose distinction. ADRs record decisions made at a moment in time with their context; principles are stable above any single decision and can outlast many ADRs. Conflating the two means an ADR's status (proposed / accepted / superseded) becomes the principle's status, and superseding a decision requires also re-arguing the underlying principle.
Add the citation field but not the items. Rejected — citing a principle that has no canonical body just means citing the cited memory file, which does not solve the discoverability problem. The first-class item is the point.
Defer until the board has 1000+ items. Rejected on the same grounds as ADR-098's tiering decision — the cost of restructuring the board grows non-linearly with item count, and every initiative filed without constrained_by between now and then would need backfilling.

Supersedes: none Superseded by: leave blank until a later ADR reverses this one

References

ADR-083 — defense-in-depth-rule-promotion (a candidate principle in its own right; also the engine that promotes findings to gates)
ADR-088 — destroy-needs-silence-snapshot-deregister-wait (implements principle 14)
ADR-089 — host-teardown-protocol (implements principle 14)
ADR-090 — ai-as-scaffold-pipelines-as-runtime (implements principles 3 + 7)
ADR-098 — epics-and-decomposition (the three-tier taxonomy this ADR adds the fourth tier above)
ADR-104 — dry-run-on-history-adaptive-gate (implements principles 5 + 8)
ADR-107 — gates-as-playbook-primitives (implements principle 2)
ADR-110 — observe-and-file-dominant-pattern (implements principle 4)
ADR-111 — broker-as-model-routing-layer (implements principle 9)
ADR-112 — executor-isolation (implements principles 5 + 6)
warp #339 — implementation epic (this ADR is r1)
warp #299 — three-tier taxonomy (the parent this ADR extends)
warp #321 — postmortem (the saga that demonstrated the cost of invisible principles)
warp #306 — discovered_during provenance (motivates principle 12)
warp #258 — token-thrift heuristic (motivates principle 10)
warp #317 — first-real-fire gate (motivates principle 11)
Memory: all feedback_*.md files — candidate principle sources for r8 backfill of warp #339

Amendment — 2026-04-29 (warp#698 / ADR-124)

A 15th founding principle joins the list: Pipeline tooling itself is block-composition, not monolithic Go — block names are abstract primitives, pipeline names are domain-specific, logic routing lives in the pipeline file. Filed as kind: principle warp#698 and ratified by ADR-124; reviewers cite it on PRs touching cmd/server/pipeline/**, pkg/pipeline/**, pkg/block/**, or any directory importing gyrum-pipelines/pkg/block.

Amendment — 2026-04-30 (warp#722 — directory reification)

The canonical browse-surface for live principles is docs/principles/. Each principle file in that directory is the markdown reification of a kind: principle warp item — the warp item carries the lifecycle (status, revision history, constrained-by citations); the file carries the citable text reviewers and sub-agents read. The README in that directory indexes the live set and documents the add-a-principle workflow. New principles land as docs/principles/<name>.md alongside the ADR that ratifies them; the warp item remains the source of truth for status changes.