core/docs/analysis/close-flywheel-dedicated-regression-surface-ratification-2026-06-16.md

# Ratification: Create a Dedicated CLOSE Flywheel Regression Surface (Claim-B Level)

**Date:** 2026-06-16  
**Author:** Grok (following user brief)  
**Branch:** feat/create-dedicated-close-flywheel-regression-surface (freshly created from clean main)  
**Base:** Clean fetched main @b2b4d79b (includes post-#792 merge of prior integration work; working tree clean)  
**Brief reference:** "Title: Create a Dedicated CLOSE Flywheel Regression Surface (Claim-B Level)" (strict "ratify first" workflow; build on #792)

**Context:**
PR #791 hardened `evals/close_derived_climb` to full Claim B (lived `ChatRuntime.idle_tick()` + `IdleTickResult.derived_close_proposals_emitted`, `determine()` + `Determined(..., rule='direct')` semantic asserts on positives, `content_replay_checksum` over canonical closures with structure_key/Derivation/premise keys + proposal bodies; preserved 1/5/8 growth, wrong_total=0, determinism, SPECULATIVE/proposal_only, all invariants).

PR #792 (the immediate "Integrate..." follow-up) promoted the yardstick via docs recommendation in testing-lanes.md + Makefile comments + hermetic embedding into `evals/anti_regression/run_demo.py` (and its contract test) so `core demo anti-regression` now executes and reports the Claim-B signals. This made it "recurring" in documented determinism reruns and the anti-regression teaching demo flow.

This brief asks for the *next* step: elevate from "recommended invocation" to a **dedicated, clearly named, intentional regression surface** for the CLOSE flywheel at Claim-B level. It must be positioned for heavier determinism regressions and teaching/anti-regression verification (not fast local dev or CI), align with the project's Engineering Pillars (Mechanical Sympathy, Semantic Rigor, Third Door per Whitepaper.md), respect hermeticity/composable lanes, and stay strictly in scope.

The yardstick already exists and is proven (via `python -m evals.close_derived_climb`, the contract tests, and the #792 embedding). The task is naming, documenting, and surfacing it as a coherent target.

## Ratification Decision (chosen approach, justified before any implementation)

**Before any implementation code or edits to source/docs (other than creation of this artifact), the single correct path is:**

Introduce a **dedicated CLOSE Flywheel regression surface** via a minimal, composable, explicitly heavy "lane" construct that reifies the full Claim-B yardstick invocation as a first-class, intentional target. Concretely:

1. **Define the dedicated surface (clearly named invocation for heavier flows):**
   - Add a new explicit make target `test-close-flywheel` (plus .PHONY) in `Makefile`. The target runs the complete Claim-B yardstick:
     ```
     uv run python -m evals.close_derived_climb
     uv run python -m pytest tests/test_derived_close_proposals.py tests/test_architectural_invariants.py tests/test_anti_regression_demo.py -q
     ```
     (The inclusion of the anti test ensures the #792 hermetic embedding participates.)
   - Name it intentionally ("CLOSE Flywheel" / "test-close-flywheel"). Document in the target comment and help text its purpose as the high-signal Claim-B regression surface.
   - **Positioning:** Explicitly heavy / opt-in only. Do *not* wire it into `test-fast`, `test-slow`, `test-full`, any `-m` marker, `core test --suite`, CI workflows, or generic pytest collection. It lives alongside the existing lanes as a composable heavy-verification tool (for use after CLOSE-related changes in determinism reruns or teaching/anti-regression verification). This satisfies "not fast local or CI runs" and out-of-scope constraints while giving a "clearly named and documented way to invoke".

2. **Integrate into existing high-value flows (clean, hermetic, additive, building directly on #792):**
   - The #792 embedding of the yardstick execution inside `evals/anti_regression/run_demo.py` (the teaching anti-regression demo) + pinning in its test is the primary "high-value flow" integration point. It already pulls the full Claim-B (lived flag, semantic determine, content checksum) into the demo that exercises reviewed teaching gates.
   - Make small, purely additive, hermetic polish if needed to "cleanly embed" (e.g. enhance comments/labels in the embedding and RESULT output to explicitly reference "CLOSE Flywheel Regression Surface (Claim-B)" and the new make target; ensure the `close_derived_climb` report field and human output continue to surface the key signals; no behavior, dataclass, or logic changes).
   - Optionally add cross-references or a one-line hermetic mention in one related teaching verification path (e.g. a comment or docstring in `tests/test_reviewed_teaching_loop.py` or `docs/evals/anti_regression_demo.md` "How to reproduce" section) that operators running teaching anti-regression verification should also consider `make test-close-flywheel`. Keep strictly additive/hermetic — no new calls that could introduce side effects or non-determinism.
   - The surface "integrates" by *naming and elevating* the existing #792 embedding as part of the dedicated target (the anti test is part of what the make target runs).

3. **Update documentation (prominently and completely):**
   - In `docs/testing-lanes.md`: Elevate or replace the prior "# Recommended determinism / teaching regression invocation..." section with a new top-level or clearly headed section titled **"Dedicated CLOSE Flywheel Regression Surface (Claim-B Level)"** (or equivalent). Include:
     - Purpose: high-signal, intentional regression target for the full lived CLOSE flywheel (autonomous derived-fact growth + gated proposal emission) at Claim-B strength.
     - Invocation: `make test-close-flywheel` (primary named surface) or the equivalent `uv run python -m ...` commands.
     - Claim-B capabilities: exact list (real idle_tick + IdleTickResult.derived_close_proposals_emitted for proposal flag; explicit determine() asserts with rule='direct' for semantic_positives_determined_direct; content_replay_checksum on canonical closures + proposal bodies; retained wrong_total=0, 1/5/8 growth, determinism, etc.).
     - Expected runtime characteristics: heavyweight (~60s+ on 10-core mac, driven by multiple real ChatRuntime turns + climbs to fixed point; comparable to other proof-scale inner-loop fixtures); explicitly for heavier determinism regressions and teaching/anti-regression verification flows.
     - Hermeticity guarantees: fresh per-run ChatRuntime (no_load_state), internal TemporaryDirectory only for proposal sink during flag test, zero writes to engine_state/ / active teaching corpus / shared proposal sinks / evals reports; preserves all invariants (wrong_total=0, replayability, SPECULATIVE-only, proposal-only boundaries, INV-21/29/30/31, versor_condition, etc.).
     - Alignment with Engineering Pillars (Whitepaper.md §IV): Mechanical Sympathy (respects cost model by keeping it out of fast paths and default CI; explicit opt-in for heavy work), Semantic Rigor (precise named surface with non-negotiable Claim-B contract and capabilities; no fuzzy or approximate inclusion), Third Door (neither pollutes existing generic suites/CI nor adds new CLI commands/heavy infra; instead a minimal composable make lane + docs reification built from first principles of the project's lane model).
     - References: this ratification artifact, the #791 Claim-B hardening ratification, the #792 integration ratification, `evals/close_derived_climb/contract.md`, `docs/evals/anti_regression_demo.md`, `docs/runtime_contracts.md`, prior analysis docs on CLOSE, the anti-regression test, and the make target.
   - Update `Makefile` comments (already partially present from #792) to reference the new dedicated target and surface name.
   - Update supporting docs for accuracy and refs: `docs/evals/anti_regression_demo.md` (how-to and falsifiable claims sections to note the surface/make target and that the demo participates in it), `evals/close_derived_climb/contract.md` (add "Dedicated surface" note + link to testing-lanes section + this ratif), and any cross-refs in `docs/runtime_contracts.md` if the determination surface mention needs tightening. Keep changes minimal and reference-focused.
   - The surface name and description make the "what/why/how/hermeticity" first-class and auditable.

4. **Preserve all invariants and boundaries (non-negotiable):**
   - The make target and any doc updates are pure invocation + description. They call only already-shipped hermetic entrypoints (`python -m evals...` which asserts internally, and the anti demo which already embeds without mutation).
   - No edits to core/ (chat/runtime.py, generate/*, session/*, vault/*, etc.), no changes to proposal review/teaching logic, FrameVerdict, RuntimeConfig, closed-world reasoning, or any serving/ratification paths.
   - All prior guarantees (wrong_total=0 across scenarios, content/replay checksum stability, lived flag isolation only when flag enabled, semantic direct rule, proposal bodies with status="proposal_only" + requires_review + epistemic="speculative", no corpus mutation, byte-identical active state in anti demo, etc.) remain enforced by the yardstick and #792 embedding.
   - Hermeticity per testing-lanes.md rules is upheld (and documented as a property of the surface).

**Why this is the only correct path (and must not be broadened):**

- It directly satisfies the Objective ("clear, intentional, and high-signal regression surface" that "properly exercises the hardened Claim-B yardstick") and every Success Criterion while obeying every Constraint, Out-of-Scope item, and the Engineering Pillars.
- **Mechanical Sympathy:** Explicitly treats the yardstick as heavyweight real-runtime work (multiple ChatRuntime + idle_tick to fixed point + climbs). Does not fight the cost model by sneaking it into fast lanes, generic suites, or CI.
- **Semantic Rigor:** Gives the Claim-B behaviors a *precise name and contract* ("Dedicated CLOSE Flywheel Regression Surface (Claim-B Level)") with enumerated capabilities, runtime expectations, and hermeticity guarantees. No vague "also run this sometimes."
- **Third Door:** Rejects the two obvious doors (1. add to existing fast/full/slow or a generic "determinism" suite, which would violate positioning + out-of-scope + mechanical sympathy; 2. create new CLI command / heavy test infrastructure like a new core subcommand or pytest plugin or broad suite wiring). Instead: a minimal named make target (already the project's composable lane mechanism per testing-lanes + Makefile) + authoritative documentation. Composable, intentional, built from the project's own lane philosophy.
- Strictly inside Scope: defines the named surface (make target + docs section), integrates cleanly/additively into anti-regression (the high-value teaching path, building on #792 embedding), updates the required docs with all specified content (purpose, Claim-B list, runtime, hermeticity, pillar alignment, ratif/contract refs), preserves every invariant (no core/teaching/FrameVerdict changes).
- Avoids every Out-of-Scope item: no fast/generic suite inclusion, no "on every push/CI", no new CLI commands, no modification of proposal review/teaching logic/closed-world, no broad refactoring.
- Highest long-term value with lowest risk: the surface is discoverable and intentional exactly where heavy CLOSE flywheel verification belongs (post-change determinism reruns + teaching anti-regression flows). The #792 embedding already provides the "integrate into existing high-value flows"; this task names and elevates the whole thing.
- Any other path (new `core test --suite close-flywheel` entry in cli.py + test_cli_test_suites.py, adding the evals to an existing suite, creating a scripts/ wrapper as "heavy infra", modifying conftest markers, running inside test-full, or changes that touch teaching code) would either violate the "Creating new CLI commands or heavy test infrastructure", "not ... on every push/CI", "stay strictly within Scope", "Prioritize clarity... over maximal... inclusion", or "No changes to core... proposal review" constraints — or would dilute the intentionality that the brief demands.
- Ratifying this exact path first ensures implementation cannot drift; every edit will be traceable to "the dedicated surface is the make target + the named section in testing-lanes.md that exercises the full yardstick (including via the anti demo)".

**References (to be linked in PR):**
- This ratification: `docs/analysis/close-flywheel-dedicated-regression-surface-ratification-2026-06-16.md`
- #791 Claim-B hardening: `docs/analysis/close-derived-climb-yardstick-claim-b-ratification-2026-06-16.md`
- #792 integration: `docs/analysis/integrate-hardened-close-yardstick-determinism-teaching-regression-ratification-2026-06-16.md` + PR #792
- Yardstick: `evals/close_derived_climb/{contract.md, runner.py, __main__.py}`
- Lanes + hermeticity: `docs/testing-lanes.md` (will host the dedicated surface section) + `Makefile`
- Anti-regression (the integration flow): `evals/anti_regression/run_demo.py` + `tests/test_anti_regression_demo.py` + `docs/evals/anti_regression_demo.md`
- Pillars: `docs/Whitepaper.md` §"IV. The Three Engineering Pillars"
- Related: `docs/runtime_contracts.md`, inner-loop determinism discussion in testing-lanes.md, `tests/test_derived_close_proposals.py`, `tests/test_architectural_invariants.py`

**Ratification Status:** COMPLETE AND LOCKED. This artifact was written on the clean branch *before any search_replace, write (other than this ratif), or other implementation edit to Makefile, testing-lanes.md, anti_regression code/docs, contract.md, or any other file*. All prior steps were git + read-only exploration (list_dir, read_file, grep). 

Implementation will now proceed *strictly* to the four Scope bullets using exactly the approach above. After edits: full verification (re-run the yardstick, new make target, anti demo, derived contract tests, confirm green + invariants + hermeticity + pillar alignment), then PR with the mandated elements.

The surface will embody Mechanical Sympathy (heavy, explicit), Semantic Rigor (precisely named Claim-B contract), and Third Door (composable lane via existing mechanisms, not the obvious two paths).

(End of ratification. No implementation code has been written.)