core/docs/adr/ADR-0095-miner-sourced-teaching-proposals.md

# ADR-0095 — Miner-Sourced Teaching Proposals

**Status:** Accepted
**Date:** 2026-05-21
**Accepted:** 2026-05-22
**Author:** CORE agents + reviewers
**Depends on:** ADR-0094

---

## Acceptance evidence

Accepted after miner-sourced proposals were wired through the reviewed teaching pipeline with a deterministic, SHA-pinned closure lane:

- `teaching/from_miner.py` converts contemplation miner outputs into `PackMutationProposal` / `TeachingProposal` records carrying `ProposalSource(kind="miner", source_id=<miner_id>, ...)`.
- `evals/miner_loop_closure/runner.py` and `evals/miner_loop_closure/contract.md` define the closure lane; `evals/miner_loop_closure/results/v1_dev.json` is the canonical report.
- `tests/test_miner_proposals.py` exercises miner-to-proposal conversion, source-tagging, replay determinism, and review-gate parity with operator-sourced proposals.
- `scripts/verify_lane_shas.py` pins `miner_loop_closure` at SHA `9f071733abe7dcacf759f928548ce738fb639af3fd6e4c621a651b306d7e77ce`; verified locally and by the `lane-shas` workflow on `main`.

---

## Context

Phase 5 of the contemplation arc landed three miners under
`core/contemplation/miners/`:

- `articulation_quality.py` (closed the articulation loop signal)
- `contradiction_detection.py`
- `frontier_compare.py`

Each miner emits observations. None of them currently produce
`PackMutationProposal` candidates. The loop is one-way: contemplation
sees the gap, but the only way to close it is for an operator to
read the miner output and manually file a proposal. That breaks the
"learn from reviewed correction" arc CLAUDE.md names as load-bearing:

> listen → comprehend → recall → think → articulate → learn from reviewed correction → replay deterministically

This ADR closes the loop without weakening the reviewed-teaching
discipline. The doctrine constraint is sharp: there must be exactly
one correction path, and miner-sourced proposals must traverse it.

---

## Decision

Introduce `teaching/proposals/from_miner.py` that translates miner
observations into `PackMutationProposal` candidates with
`source = ProposalSource(kind="miner", source_id=<miner_id>, …)` from
ADR-0094.

### Hard constraints

1. **Single review path.** Miner-sourced proposals enter
   `teaching/review.py` via the same entry point as operator proposals.
   No parallel reviewer, no auto-acceptance, no shortened review path.
2. **Default status `speculative`.** Miner-sourced proposals are never
   coherent at emission.
3. **Identity-pack defense.** Proposals touching identity-pack axes are
   rejected at proposal-construction time (before review), not at
   review time. This prevents the miner from ever filing an identity
   override candidate, even one that would fail review. ADR-0027's
   identity-override rejection rule extends upstream.
4. **Replay-equivalence pre-gate.** Before a miner-sourced proposal is
   review-eligible, replay the originating turn under the proposed
   mutation. If `trace_hash` changes on any non-target turn in the
   lane, the proposal is rejected at construction.
5. **Deterministic emission.** Same miner observations + same head SHA
   → byte-identical proposal stream. Proposal IDs are SHA-256 of
   `(miner_id, observation_canonical, emitted_at_revision)`.

### What miners do not gain

- Direct write access to packs.
- Ability to mark proposals coherent.
- Ability to mutate identity, safety, or ethics packs at all.

### Telemetry

Miner-sourced proposals emit a `"type": "proposal_emitted"` event to
the existing telemetry sink (ADR-0040), carrying the redacted
`source.serialize()` string and proposal ID. Content is redacted by
default per ADR-0040.

---

## Invariant

`miner_proposal_replay_equivalence` — for every miner-sourced proposal
that reaches review eligibility, replaying the originating lane with
the proposed mutation applied yields identical `trace_hash` on every
non-target turn. The lane gate refuses proposals that violate this.

`miner_proposal_single_review_path` — grep gate refuses any code path
that promotes a miner-sourced proposal to coherent outside
`teaching/review.py`.

---

## Lane

`evals/miner_loop_closure/` (new):

- positive: legitimate articulation gap → proposal emitted → reviewable
- negative: identity-override attempt via miner → rejected at construction
- negative: proposal that breaks replay-equivalence → rejected at construction
- negative: malformed miner observation → typed error, no proposal
- coincidence: random/noise observation → no proposal under threshold
- determinism: same observations across two runs → identical proposal stream

---

## Trust Boundary

Miners read turn telemetry only; they do not read user-controlled text
directly. The miner-to-proposal boundary sanitizes `source_id` via
`safe_pack_id` traversal rejection. The replay-equivalence gate is a
filesystem-only operation against the existing eval runners; no network
or shell.

---

## Consequences

- Phase 5 contemplation becomes a closed loop in code, not just in
  doctrine.
- The capability ledger gains a new evidence row class: "miner-sourced
  proposal accepted into coherent" — measurable, replayable.
- Learning-scale claims (the deferred 10k harness) become eventually
  defensible because every replayed proposal will have a real
  provenance, not a synthetic one.

---

## PR Checklist

- Capability added: closed contemplation loop through reviewed teaching.
- Invariants proved: `miner_proposal_replay_equivalence`, `miner_proposal_single_review_path`.
- Lane proving it: `evals/miner_loop_closure/`.
- Hidden normalization / stochastic fallback / approximate recall / unreviewed mutation: none. Single review path enforced by grep gate.
- Trust boundary: miner reads telemetry, never user text; identity-pack rejection at construction.