[hyperpolymath]

Summary

Adds docs/decisions/ADR-003-trust-tiers.adoc with status Proposed. It records the owner's 2026-10-07 rulings on the existing tier enum (Teranga / Shield / Ayo), which nothing enforces today:

• What a tier gates: a set of admission requirements plus a signing authority. The requirements are cumulative: Ayo, then Teranga (real FFI, adapter, tests, no stubs), then Shield (a clean Idris2 ABI and non-public exposure). Teranga and Shield index entries are signed by the owner key only.
• Where it is enforced: both a required CI check in this repo and the boj-server loader, which checks the signer against the declared tier and makes the hash mandatory.
• Re-audit: all 11 Teranga assignments stay. The 10 that fall short (9 manifest-only, plus orchestrator-lsp-mcp, which has no tests) are listed in a shrink-only exemption ratchet, declared before enforcement starts.

No manifest, code or workflow changes. The ADR becomes Accepted when the CI check lands.

How has this been verified?

• Teranga table: test -d <path>/{abi,ffi,adapter,tests} for every ledger row with "tier":"Teranga" (ledger from docs(split): Phase 0 survey and per-cartridge JSON Lines ledger #159).
• boj-server claims: read at 7dd5897d. tier is consumed only by router.ex L70–73 and catalogue.zig MenuTier. loader.zig loadCartridge takes an optional expected_hash and checks no signature.
• Existing schema CI: .github/workflows/cartridge-schema.yml exists.
• Render: asciidoctor --failure-level=WARN returned rc 0.

📌 New pins

Head 51c2d0ab2c2aab6d33ef83a0d7aea584a775d4e5. No action, lockfile or digest pins are added or changed.

Schema-validation note

• This PR adds or modifies one or more cartridge.json manifests.
• This PR does not touch any cartridge.json. The schema description change for tier is a follow-up in hyperpolymath/standards.

Refs

• docs(split): Phase 0 survey and per-cartridge JSON Lines ledger #159: Phase 0 survey and ledger (the re-audit baseline).
• [g] Implement the ~100 stub cartridges (truthfully, via the maker) boj-server#201: stub cartridges; overlaps building the 10.

🤖 Generated with Claude Code

https://claude.ai/code/session_019j8She9eTFx54r6aL6sCHP

[coderabbitai]

Caution

Review failed

Failed to post review comments.

GitHub was unavailable or timed out while CodeRabbit was posting the review. Please request a new review later if the pull request still needs one. This happened while posting 1 inline comment. Use @coderabbitai full review to retry the review.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 535919c4-2ac6-4c07-bd8f-0bd03ffba6ca

📥 Commits

Reviewing files that changed from the base of the PR and between 524e148 and 51c2d0a.

📒 Files selected for processing (1)

• docs/decisions/ADR-003-trust-tiers.adoc

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

⏰ Context from checks skipped due to timeout. (13)

• GitHub Check: analyze (actions, none)
• GitHub Check: analyze (javascript-typescript, none)
• GitHub Check: Active orchestration adapter
• GitHub Check: CodeFactor
• GitHub Check: governance / Trusted-base reduction policy
• GitHub Check: governance / Allowlist Preflight
• GitHub Check: governance / Language / package anti-pattern policy
• GitHub Check: governance / Workflow security linter
• GitHub Check: governance / Code quality + docs
• GitHub Check: governance / Debt ratchet
• GitHub Check: governance / Check Workflow Staleness
• GitHub Check: scan / gitleaks
• GitHub Check: Hypatia Neurosymbolic Analysis

📝 Summary

Summary by CodeRabbit

• Documentation
  • Added guidance defining three cumulative admission tiers, their signing requirements and loading behaviour.
  • Documented how CI and the loader enforce tier requirements, including current exemptions, assignments and follow-up work.

Walkthrough

ADR-003 defines cumulative admission requirements and signing rules for Ayo, Teranga, and Shield. It specifies CI and loader enforcement, records current assignments and exemptions, and lists follow-up work and rejected alternatives.

Changes

Trust-tier admission

Layer / File(s)	Summary
Tier requirements docs/decisions/ADR-003-trust-tiers.adoc	Defines cumulative Ayo, Teranga, and Shield requirements, signing authorities, and load timing.
CI and loader enforcement docs/decisions/ADR-003-trust-tiers.adoc	Specifies CI checks for declared-tier requirements and loader checks for signed-index entries, authorised signatures, and matching binary hashes.
Assignments and follow-up docs/decisions/ADR-003-trust-tiers.adoc	Records current assignments and exemptions, follow-up work, consequences, and alternatives considered.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Security Architecture Review

Security architecture risk: 🔵 Low · up to 51c2d

This proposed decision establishes security-relevant admission rules but changes no executable behavior. Risk is low because the authorization and recovery guarantees for temporary exemptions remain to be demonstrated before enforcement.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The intended security boundary covers cartridge admission into boj-server through the signed index and loader. The documentation-only change establishes no new executable reachability or privilege gain; tenant, environment and data-store exposure cannot be quantified from the available external implementation evidence.

Security Findings and Attack Paths

• observed — No verified Security finding is supplied. The exemption-addition authorization candidate remains deferred: the ADR prohibits additions without an owner ruling, but the enforcing implementation is unavailable. No attacker-controlled addition reaching an admission bypass has been demonstrated.

Trust Boundaries and Controls

• observed — The proposed trust transition binds the admitted tier and binary hash to a signer authorized for that tier. Unsigned entries, unauthorized signers and hash mismatches must be rejected. Signature verification establishes provenance; the separate CI path is responsible for admission requirements that the loader cannot retest.

Resilience and Maintainability Implications

• inferred — The ratchet specifies initialization, qualification-driven removal, stale-row rejection and owner authority for additions. Preservation of those guarantees under concurrent changes, interrupted updates, regression and rollback remains unproven. This is a future enforcement coverage gap, not a demonstrated weakening of current controls.

Hardening Proposals

• proposed — Before enforcement is activated, define how owner rulings authorize new or reintroduced exemptions and verify qualification/removal, concurrent edits, regression and rollback against an authorized baseline. Also define which CI and loader rollout states provide the complete admission guarantee.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: a proposed ADR that defines trust tiers as admission gates and signing requirements.
Description check	✅ Passed	The description follows the repository template. It includes a summary, schema-validation selection, verification details, and related references. It also states that no manifests, code, or workflows …
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit reads the tiers by moonlit light,
Ayo, Teranga, Shield set rules just right.
Signed hashes guard each entry in the queue,
CI checks what each tier must do.
Ten waits remain; the next steps start,
The rabbit hops with plans in heart.}

_{Comment @coderabbitai help to get the list of available commands.}

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR