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.2 KiB

Raw Blame History

ADR-0094 — Proposal Source Provenance

Status: Proposed Date: 2026-05-21 Author: CORE agents + reviewers

Context

teaching/proposals/proposals.jsonl and the surrounding review flow (teaching/review.py, teaching/store.py, ADR-0057) currently assume proposals originate from a single source: an operator authoring through the existing teaching CLI. The schema has no typed source field.

Two near-term ADRs widen this:

ADR-0095 introduces miner-sourced proposals (contemplation Phase 5 loop closure).
A future ADR will introduce curriculum-sourced proposals (deferred per the rewrite blueprint).

Without a typed source field, downstream consumers (teaching/review.py, capability ledger evidence rows, audit telemetry) will branch on string prefixes informally. That is the same shape of mistake ADR-0067's explicit subject_pack_id / object_pack_id fields prevented for cross-pack chains.

Decision

Introduce a sealed ProposalSource type widening PackMutationProposal / TeachingProposal schemas. The widening is schema-only; no runtime behavior changes under this ADR.

Sealed type

@dataclass(frozen=True, slots=True)
class ProposalSource:
    kind: Literal["operator", "miner", "curriculum"]
    source_id: str  # "" for kind="operator"; miner_id or course_id otherwise
    emitted_at_revision: str  # git SHA at emission

    def serialize(self) -> str:
        # "operator", "miner:articulation_quality", "curriculum:math_logic_v1"
        return self.kind if not self.source_id else f"{self.kind}:{self.source_id}"

Schema migration

New field on PackMutationProposal and TeachingProposal: source: ProposalSource.
Default for existing operator-authored proposals: ProposalSource(kind="operator", source_id="", emitted_at_revision=<head>).
Migration is one-shot at ADR landing: a deterministic rewriter walks existing proposals.jsonl files, attaches the default operator source, and rewrites in sorted order. Migration is a reviewed proposal itself.

Consumer rules

teaching/review.py performs exhaustive match on source.kind. Any new kind requires a new ADR adding a branch.
Telemetry events (chat/telemetry.py) carry source.serialize() as a string field. Redact-by-default already covers proposal content; source is non-sensitive and emitted plainly.
Capability ledger evidence rows (ADR-0091) include source in their provenance trail.

What this ADR does not do

Does not introduce miner-sourced proposals (ADR-0095).
Does not introduce curriculum-sourced proposals.
Does not change review thresholds. Source affects audit, not gate.

Invariant

proposal_source_exhaustive_match — every code path that branches on proposal.source.kind uses Python match with explicit cases for each sealed-type value; the type checker refuses a non-exhaustive match. A proposal without source fails parsing.

Lane

evals/proposal_source_schema/ (new, small):

positive: round-trip serialization for each kind
negative: missing source field rejected at parse
negative: unknown kind rejected at parse
migration: existing proposals.jsonl rewritten deterministically; two runs produce identical bytes

Trust Boundary

source_id is a typed string but flows through user-adjacent surfaces (telemetry, ledger reports). It is sanitized via core/_safe_display.safe_display at all surface emission points, matching the discipline established in ADR-0051. The migration rewriter runs only when invoked explicitly; no implicit on-load mutation.

Consequences

ADR-0095 can introduce kind="miner" without secondary schema churn.
A future curriculum ADR can introduce kind="curriculum" the same way.
Existing operator review flow is unchanged; the new field is set to its operator default on every existing proposal.

PR Checklist

Capability added: typed provenance schema for proposals.
Invariant proved: proposal_source_exhaustive_match.
Lane proving it: evals/proposal_source_schema/.
Hidden normalization / stochastic fallback / approximate recall / unreviewed mutation: none. Migration is explicit and reviewed.
Trust boundary: source_id sanitized at every surface; no implicit on-load rewrites.

4.2 KiB Raw Blame History