core/docs/analysis/close-flywheel-proposal-review-visibility-ratification-2026-06-16.md

# Ratification: Strengthen Visibility and Measurement of the Proposal Review / Ratification Side of the CLOSE Flywheel

**Date:** 2026-06-16  
**Branch:** `feat/strengthen-close-flywheel-proposal-review-visibility` (fresh from `origin/main` at 9736dcc0 which includes #793)  
**Governing brief:** "Title: Strengthen Visibility and Measurement of the Proposal Review / Ratification Side of the CLOSE Flywheel" (the query for this session)  
**Preceding work (locked):** #791 (Claim-B hardening of `evals/close_derived_climb`), #792 (integration recommendation + embedding), #793 (Dedicated CLOSE Flywheel Regression Surface via `make test-close-flywheel` + dedicated section in testing-lanes.md + hermetic anti-regression participation).

## Context and the Gap

The CLOSE flywheel (comprehend → realize_derived → determine → CLOSE consolidate / idle_tick → proposal emission under `review_derived_close_proposals`) now has strong, Claim-B measurement on the *derivation and autonomous growth* half:

- Lived `ChatRuntime.idle_tick()` + `IdleTickResult.derived_close_proposals_emitted`
- `proposal_flag` + `only_with_flag` guarantee (proposals emitted **only** when the flag is on; zero without)
- `content_replay_checksum` over canonical closures (structure_key + Derivation with premise_structure_keys) + proposal bodies
- `semantic_positives_determined_direct` via explicit post-fixed-point `determine(..., rule='direct')` asserts
- `wrong_total=0`, strict/monotone growth, proposal_only + SPECULATIVE + requires_review posture on every emitted artifact, hermetic fresh_ctx runs

(See `evals/close_derived_climb/runner.py`, `evals/close_derived_climb/contract.md`, `tests/test_derived_close_proposals.py`, `docs/analysis/close-derived-climb-yardstick-claim-b-ratification-2026-06-16.md`, the dedicated surface ratification, and the bridge ADR doc `close-derived-proposal-bridge-2026-06-16.md`.)

The **review / ratification half** (the operator/HITL-gated path that takes a `status=proposal_only / epistemic_status=speculative / requires_review=true` artifact and moves it to accepted → corpus append or coherent promotion) has been the weaker half for observability:

- Emission artifacts (in `teaching/proposals/derived_close_facts/*.json` for the bridge, or via `ProposalLog` events for the older chain path) carry explicit review posture fields, but these are not aggregated or asserted as first-class signals in the main reporting surfaces.
- `DemoReport` (anti-regression) already captures per-scene `review_state` ("pending", "auto_rejected_on_regression", "rejected_pre_replay", "pending_awaiting_operator") and replay_evidence for the *teaching chain proposal* path (ADR-0057). It now also embeds the full climb yardstick. No combined review-outcome aggregates or CLOSE-specific review posture summary.
- `IdleTickResult` surfaces the *emission count* (`derived_close_proposals_emitted`) but not review/ratification outcomes (by design — review is HITL, not autonomous).
- `ProposalLog` (teaching/proposals.py) is an append-only event log with `record_transition(to="accepted|rejected|withdrawn")` and `accepted_corpus_append` events. These events exist and are exercised by the anti-regression scenes (S2 produces a rejected transition via the regression gate inside propose), but are not surfaced as structured counts or "ratification signals" in `DemoReport` or `core demo anti-regression --json`.
- The derived CLOSE artifacts are intentionally *parallel* to (or consumable by) the existing read-only proposal review reporter pattern (see historical `docs/analysis/proposal-review-reporter-2026-06-07.md` for the comprehension-failures precedent). No structured "how many of these specific proposals reached accepted/rejected, with what notes, producing what append events" measurement is present in the heavy verification lane.
- Vault promotion (SPECULATIVE → COHERENT via `apply_certified_promotion` or eligible promotion paths) is separate from teaching corpus extension; CLOSE derived facts can flow either as proposals or as consolidated determinations, but the "proposal review / ratification side" named in the brief is the gated proposal path.

The brief explicitly requires **measurement and visibility only** — no changes to review logic, policy, `accept_proposal`/`reject_proposal`/`review_correction`, `FrameVerdict`, closed-world reasoning, `teaching/*` mutation paths, or `RuntimeConfig` semantics.

## Ratification Decision (Chosen Approach)

**Introduce additive, structured proposal-review visibility exclusively through the already-established Dedicated CLOSE Flywheel Regression Surface (the anti-regression demo + embedded Claim-B climb yardstick + `make test-close-flywheel` lane).**

Concretely (post-ratif):

1. **Extend `evals/close_derived_climb` output (additively, in runner + contract)**:
   - From the already-captured `proposal_flag.proposals` list (the full emitted bodies), derive and surface a `review_posture` (or `proposal_review_posture`) sub-object:
     - `emitted_count`
     - `all_proposal_only: bool`
     - `all_requires_review: bool`
     - `all_speculative: bool`
     - `review_eligible: int` (same as emitted; documents the "born review-gated" invariant)
     - `none_promoted_or_accepted: bool` (structural guarantee of the yardstick — no review path is exercised inside the climb itself)
   - Retain `content_replay_checksum` (already covers proposal bodies). This makes the *review posture at emission time* a first-class, checksum-protected, wrong_total=0 Claim-B signal.
   - Update `contract.md`, runner docstring, and `__init__.py` summary only (no behavior change to emission or any runtime path).

2. **Extend `evals/anti_regression/run_demo.py` + `DemoReport` (additively, hermetic, building directly on the #792 embedding)**:
   - Add an optional `proposal_review_summary: dict | None = None` (and/or `close_proposal_review`) field to `DemoReport`.
   - In `run_demo`, after the three scenes + the existing `close_derived_climb = run_close_derived_climb()` call:
     - Aggregate from the existing `SceneResult` objects (they already carry `review_state`, `operator_note`, `replay_evidence`): counts by terminal review state, any "accepted_corpus_append" style signals if present in the temp log events for the demo's `ProposalLog`.
     - Merge / surface the climb's new `review_posture` (or the raw emitted proposals' review flags) as a `close_derived` subsection.
     - Optionally, for the demo's own ProposalLog (tmpdir-isolated), read the event stream post-scenes and count `transition` events by "to" state and `accepted_corpus_append` events. This gives a deterministic "ratification events observed during exercised gates" signal without ever calling the public `accept_proposal` on a path that would write the live active corpus (the demo's S3 is deliberately pending-only; any transition counts come from S2's internal auto-reject path or explicit log inspection).
   - In the verbose RESULT block and `as_dict()`, include the new summary so `--json` output and `core demo anti-regression` carry the signals.
   - The `all_gates_held` and `active_corpus_byte_identical` invariants remain unchanged and are still the primary success criteria.

3. **Light doc updates only (no code behavior)**:
   - `docs/testing-lanes.md`: Extend the "Dedicated CLOSE Flywheel Regression Surface (Claim-B Level)" section (the one added in #793) with a new subsection "Review / Ratification Posture and Events (the previously weaker half)" describing the new signals, their purpose (visibility into acceptance/rejection rates, review outcomes, promotion-adjacent events for the CLOSE-derived proposals), expected characteristics (still heavy, hermetic, proposal-only/SPECULATIVE guarantees are *asserted*, not bypassed), and the ratif link.
   - `docs/evals/anti_regression_demo.md`: Note that the demo now also participates in review/ratification visibility for the embedded CLOSE surface.
   - `evals/close_derived_climb/contract.md`: Add the new posture signals to the "What the yardstick measures" list + ratif reference.
   - `docs/runtime_contracts.md`: One-sentence tightening (if needed) that the determination + proposal emission contracts now have corresponding review-posture observability in the dedicated lane.
   - Cross-reference the new ratif artifact and the prior dedicated-surface ratif.

4. **No other changes**:
   - No modifications to `teaching/review.py`, `teaching/proposals.py` (beyond any trivial additive helper if a pure read function proves useful — but prefer direct inspection of public `ProposalLog.events()` / `find()` and the climb's already-returned dicts), `vault/store.py`, `generate/determine/derived_close_proposals.py`, `chat/runtime.py`, `IdleTickResult`, `accept_proposal`/`reject_proposal`, or any ratification/promotion policy.
   - The anti-regression scenes continue to leave passing proposals in "pending_awaiting_operator"; any new summary merely observes states and events that the existing gate machinery already produces.
   - `make test-close-flywheel` and the pytest contract pair (`test_anti_regression_demo.py` etc.) will transitively cover the new signals.
   - All existing hermeticity (temp dirs, no_load_state, fresh corpora, byte-identical active checks, no engine_state writes in the lane) is preserved.

**Primary surface:** the Dedicated CLOSE Flywheel Regression Surface (Claim-B) via `make test-close-flywheel` (or direct `uv run python -m evals.close_derived_climb` + the anti demo). This is explicitly positioned for heavier determinism + teaching/anti-regression verification, not fast local or CI — exactly as ratified in #793.

## Why This Is the Only Correct Path (Alignment with Scope, Constraints, and Engineering Pillars)

**Mechanical Sympathy (Whitepaper §IV):** The review/ratification half is inherently heavier and more HITL-dependent than pure autonomous derivation. We do not hide cost or make it "free" by adding always-on reporters, new CLI commands, or inclusion in `core test --suite smoke/fast` or CI. We extend the *explicitly heavy, opt-in, documented* lane (`make test-close-flywheel`) that already hosts the Claim-B derivation yardstick. Operators who care about the full flywheel (including the review posture of what the autonomous half emits) pay the cost intentionally. No new infrastructure.

**Semantic Rigor (Whitepaper §IV):** We give the review side *precise, named, contract-level signals* (`review_posture.all_requires_review`, `proposal_review_summary.by_state`, transition counts from the event log, "none promoted inside the yardstick" guarantees) rather than ad-hoc prints or sidecar files. The signals are derived from the same artifacts the bridge and ProposalLog already emit (status, epistemic_status, requires_review, transition events). The yardstick continues to fail loudly (wrong_total, posture violations, checksum drift) if the review-gated contract is violated at emission time. Documentation in testing-lanes.md + contract.md makes the contract legible.

**Third Door (Whitepaper §IV + the composable verification style in testing-lanes.md and the #793 ratification):** We do not invent a new `core close review-stats` command, a new pytest marker, a new `_TEST_SUITES` entry, or a broad `teaching/` refactor. We use the *existing composable lane mechanism* (the dedicated make target + the anti-regression demo as the canonical teaching-gate verification harness + the embedded climb) that was just ratified and documented days ago. This is the "third door": a small, load-bearing, additive extension inside the already-approved heavy surface. It is hermetic, additive, and discoverable by anyone following `make test-close-flywheel` or reading the dedicated section.

**Strict scope adherence and invariant preservation:**
- Only measurement/visibility (structured dicts in existing report shapes).
- Zero changes to proposal review logic, acceptance policy, FrameVerdict, closed-world, or any mutation path.
- All new data is either (a) already returned by public hermetic runners (climb proposals list) or (b) already written by the exercised gate code into temp ProposalLogs (events()).
- proposal_only / SPECULATIVE / requires_review boundaries are *asserted more visibly*, never relaxed or bypassed.
- wrong_total=0, determinism, replayability, content-addressing, and the "active corpus byte identical" contract of the anti demo remain the success criteria.
- The ratification artifact itself is written *before* any search_replace/write on source, tests, or other docs.

Alternative paths considered and rejected (as part of ratif reasoning):
- Adding a standalone `core proposal-review-stats` or new module under `core/`: violates "no new CLI", "no heavy infra", "Third Door / composable", and Mechanical Sympathy (would look like a fast-path tool).
- Instrumenting inside `accept_proposal` / `reject_proposal` or `review_correction`: changes (or appears to change) the review logic; broad touch on teaching/; out of scope.
- Running real accepts inside the anti demo that mutate the live teaching corpus: breaks the demo's hermetic "never writes active" contract and the "active_corpus_byte_identical" gate.
- Broadly enhancing IdleTickResult with review outcome counts: review is not part of the autonomous tick (by design and by INV-29/30); would be misleading and would require runtime changes.
- Updating the old comprehension-failure reporter in isolation: the brief is specifically about the *CLOSE* flywheel's proposal review side (the bridge + derived_close_facts path now exercised by the Claim-B yardstick).

The chosen path is the minimal, precise, pillar-aligned, scope-respecting, hermetic extension that makes the previously weaker half first-class *inside the surface that was just created for exactly this class of heavier CLOSE verification*.

## Verification Obligations (Post-Impl)

- `make test-close-flywheel` (or the two commands) must pass with the new signals present in JSON output and verbose text.
- `core demo anti-regression --json` must include the review summary/posture blocks; `all_gates_held` and `active_corpus_byte_identical` must remain true.
- `tests/test_anti_regression_demo.py` (and the other contract tests) remain green; the new fields are additive so existing assertions are unaffected or lightly extended only for presence/shape.
- Manual spot-check: emitted CLOSE proposals in the climb output continue to show `status: "proposal_only"`, `epistemic_status: "speculative"`, `requires_review: true`; the new posture object affirms the same.
- No diff in any production proposal review or promotion code paths (git diff limited to reporting/demo/docs + this ratif).
- All prior invariants (versor_condition, INV-21/22/23/24/29/30, wrong=0, SPECULATIVE default, proposal-only for derived CLOSE, etc.) continue to hold by construction.

## References

- Brief for this work + Required Workflow / Scope / Success Criteria / Constraints (this session's query).
- Dedicated CLOSE Flywheel Regression Surface ratification: `docs/analysis/close-flywheel-dedicated-regression-surface-ratification-2026-06-16.md`
- Claim-B yardstick hardening + integrate ratifs (2026-06-16).
- Bridge: `docs/analysis/close-derived-proposal-bridge-2026-06-16.md` (and the earlier proposal-review-reporter-2026-06-07.md for precedent style).
- `docs/testing-lanes.md` (Dedicated section + "How the surface builds on prior work").
- `evals/close_derived_climb/contract.md`, `evals/anti_regression/run_demo.py`, `chat/runtime.py:IdleTickResult`, `teaching/proposals.py:ProposalLog + ReviewState + accept/reject`, `vault/store.py` (promotion boundaries).
- Engineering Pillars: `docs/Whitepaper.md` §IV.
- Runtime contracts: `docs/runtime_contracts.md` (determination + proposal emission sections).

**Ratification Status:** COMPLETE AND LOCKED. This artifact was created via the `write` tool on the clean branch *before any search_replace, write (other than this file), or other implementation edit to Makefile, source, tests, evals runners, or any other documentation*. All preceding activity was git operations (fetch, checkout main, ff, branch creation, clean of stray artifacts) plus strictly read-only exploration (list_dir, read_file, grep with no edits). Implementation may now proceed exactly within the scope above. Any deviation requires a new ratification or explicit brief amendment.

---
*This ratification follows the project's ratify-first discipline for architectural and cross-cutting measurement changes on core flywheels. It prioritizes clarity, intentionality, long-term alignment with the Three Engineering Pillars, hermetic composable lanes, and preservation of every listed invariant over expedience or automatic inclusion.*