Shay 10457bec69 docs(adr): propose ADRs 0092-0099 — scale-up slate through public showcase

Eight load-bearing ADRs closing the loop from contemplation Phase 5 through
a public showcase demo. Each one is small and evidence-bearing; together
they sequence the next arc without duplicating existing substrate.

- 0092 Reviewer Registry v1 — populates docs/reviewers.yaml schema;
  unblocks all reasoning-capable claims under ADR-0091.
- 0093 Domain Pack Contract v1 Implementation — wires ADR-0091's five
  follow-up items (parser, dry-run validator, chain registry, eval lane
  refs, reviewer resolution) so manifest fields actually gate status.
- 0094 Proposal Source Provenance — sealed ProposalSource type widening
  proposal schemas ahead of 0095.
- 0095 Miner-Sourced Teaching Proposals — closes the contemplation
  loop: articulation_quality / contradiction_detection / frontier_compare
  miners emit PackMutationProposal candidates routed through the single
  reviewed teaching path; identity-pack defense at construction, not
  review; replay-equivalence pre-gate.
- 0096 Fabrication-Control Eval Lane — first negative-control measure;
  three case classes (phantom endpoint, cross-pack non-bridge, sibling
  collapse) with frozen thresholds (fabrication_rate ≤ 0.01).
- 0097 Mathematics-Logic Reasoning-Capable Ratification — first
  domain claim under ADR-0091; chain corpus + eval lanes already
  exist, this is the formal contract ratification.
- 0098 Demo Composition Contract — DemoCommand protocol so demos can
  be composed without reimplementation; deterministic JSON, no global
  state mutation, declared output paths only.
- 0099 Public Showcase Demo — composes four scenes (determinism /
  honest unknown / reviewed learning / multi-hop+trace) under 30s;
  pure composition enforced by grep gate; JSON byte-equality CI-pinned.

Landing order: 0092 → 0094 → 0095 → 0093 → 0096 → 0097 → 0098 → 0099.

Deliberately not included: curriculum compiler, formation course
runner, calculator operators, response-mode taxonomy expansion,
learning-scale 10k harness. Each is deferred with a documented reason.

2026-05-21 17:34:09 -07:00

4.3 KiB

Raw Blame History

ADR-0092 — Reviewer Registry v1

Status: Proposed Date: 2026-05-21 Author: CORE agents + reviewers Depends on: ADR-0091

Context

ADR-0091 defines Domain Pack Contract v1. Its validation semantics require that every reviewers entry on a reasoning-capable pack resolve through docs/reviewers.yaml. The file exists but is currently empty:

reviewers: []

This means no pack can advance beyond grounded under the contract, no matter how complete its chains, evals, or gloss coverage. The empty registry is a hard block on every subsequent ADR that wants to ratify a domain claim.

The registry is also load-bearing for proposal review (teaching/review.py) and capability ledger evidence rows. Treating it as a free-form list will produce drift; treating it as schema-bearing data lets the validator refuse malformed entries before they reach the runtime.

Decision

Introduce Reviewer Registry v1 as a structured, validator-checked schema for docs/reviewers.yaml. The schema is small on purpose. It must be the minimum that satisfies ADR-0091 predicates without inviting identity inflation.

Schema

schema_version: 1
reviewers:
  - reviewer_id: shay-j
    display_name: "Joshua Shay"
    role: primary
    domains: ["*"]
    review_scope: ["pack", "proposal", "chain", "eval"]
    provenance: "adr-0092:bootstrap:2026-05-21"

Field	Required	Purpose
`schema_version`	yes	Version gate for registry parsing semantics.
`reviewer_id`	yes	Stable key referenced by pack manifests and proposals.
`display_name`	yes	Human-readable label for ledger and report rows.
`role`	yes	`primary` or `domain`. `primary` may review any pack; `domain` requires `domains` enumeration.
`domains`	yes	List of `domain_id` values from ADR-0091. `["*"]` for primary reviewers.
`review_scope`	yes	Subset of `{pack, proposal, chain, eval}`. Bounds what artifacts this reviewer may ratify.
`provenance`	yes	Review trail entry for the reviewer's addition itself.

Bootstrap entry

Registry ships with exactly one reviewer (shay-j) at v1 landing. Adding reviewers is a separate reviewed proposal flow. The bootstrap entry is self-sealed: its provenance references this ADR.

Validator rules

The capability validator (ADR-0091, follow-up #4) refuses ratification when:

docs/reviewers.yaml does not match schema_version: 1.
A pack manifest names a reviewer_id absent from the registry.
A reviewer's role: domain does not include the pack's domain_id.
A reviewer's review_scope does not cover the artifact being ratified.
Two reviewer entries share a reviewer_id.

No validator mutates the registry. Mutation remains a reviewed proposal.

Trust Boundary

docs/reviewers.yaml is parsed at validator startup and on every ledger report run. The parser rejects unknown top-level keys and unknown reviewer fields rather than ignoring them — schema drift is loud, not silent. Reviewer IDs are display-only; the registry never grants runtime permissions beyond the predicates ADR-0091 already enforces.

Invariant

reviewer_registry_schema_v1 — running core capability ledger against a registry that fails schema validation must exit non-zero and produce a typed error naming the failing field; no ledger row may be emitted under a malformed registry.

Lane

evals/reviewer_registry/ (new):

positive: valid v1 registry passes
negative: empty registry blocks all reasoning-capable claims
negative: malformed entry produces typed error
negative: domain reviewer claiming wildcard ["*"] rejected

Consequences

One real reviewer entered; subsequent reviewer additions are themselves reviewed proposals, preventing trust inflation.
ADR-0091 predicate #8 (reviewer resolution) becomes enforceable.
Identity, safety, ethics packs gain a checked author trail without altering their existing self-seal flow.

PR Checklist

Capability added: schema-checked reviewer registry; unblocks reasoning-capable claims.
Invariant proved: reviewer_registry_schema_v1.
Lane proving it: evals/reviewer_registry/.
Hidden normalization / stochastic fallback / approximate recall / unreviewed mutation: none.
Trust boundary: YAML parser rejects unknown keys; bootstrap entry self-sealed.

4.3 KiB Raw Blame History