docs(proposals): document derived CLOSE proposal bridge

- docs/runtime_contracts.md: new subsection under idle passes describing eligibility,
  contract (proposal-only, review-gated, default-off, no corpus/COHERENT/serving change),
  and cross-ref to the analysis note.
- New dated analysis note with why (flywheel bridge after PR-1), architecture/boundaries,
  artifact schema, dedupe, tests, non-goals, and composition with PR-1/PR-3.
- Tiny high-level pointer not added (no suitable learning-loop section in README at this granularity).
This commit is contained in:
Shay 2026-06-16 15:20:08 -07:00
parent a3403b03ab
commit e1907ee921
2 changed files with 119 additions and 0 deletions

View file

@ -0,0 +1,88 @@
# PR-2: Derived CLOSE Facts → Review-Gated Proposal Bridge
**Date:** 2026-06-16
**Branch:** `feat/close-derived-proposal-bridge`
**Base:** `a1bdaa2c` (origin/main with PR #788 merged)
**Governing sequence:** PR-1 (substrate — relational transitive CLOSE) → **PR-2 (this: proposal bridge)** → PR-3 (yardstick measurement)
## What PR-2 adds
A deterministic, default-off proposal emitter that surfaces proof-gated derived CLOSE facts as reviewable proposal artifacts.
Eligible derived facts (after consolidation):
- `derived is True`
- `derivation is not None` with `verdict == "entailed"`
- `epistemic_status == "speculative"`
- `relation_predicate` ∈ {"member", "subset"} TRANSITIVE_PREDICATES (the four strict-order predicates)
Ineligible (skipped safely, never emitted):
- Direct (non-derived) facts
- Missing or non-entailed derivation
- Non-speculative standing
- Unsupported predicates (e.g. parent_of, sibling_of, left_of)
- Malformed records
Artifacts are written as JSON to `teaching/proposals/derived_close_facts/<dedupe_key>.json` with explicit fields:
- source: "derived_close_fact"
- predicate, subject, object, relation_arguments
- derivation: {rule, verdict, premise_structure_keys}
- epistemic_status, structure_key, dedupe_key
- status: "proposal_only", requires_review: true, mounted: false
Dedupe is stable across ticks and runs (predicate + args + derivation provenance + structure_key).
## Why (the flywheel bridge)
PR-1 (CLOSE relational transitive) lets the lived loop derive and remember more sound conclusions as SESSION/SPECULATIVE facts. Without a proposal path, those facts stay trapped in session memory and never reach the reviewed learning path.
PR-2 completes the "comprehend → realize → determine → CLOSE consolidate → propose" half of the flywheel while preserving the hard boundary: only human-reviewed mutation (via the existing HITL proposal review) can produce durable (COHERENT/ratified) knowledge. Derived CLOSE proposals are **proposal-only**.
## Architecture & boundaries (strictly observed)
- **After consolidation, before (or alongside) existing proposal review.** Runs in idle_tick only when `config.review_derived_close_proposals` (default False).
- **Read/write separation.** The emitter writes artifacts. Review consumption re-uses or parallels the existing read-only `core.proposal_review` machinery (no mutation of the review contract in this PR).
- **No side effects on serving/determine.** Emission never alters user-facing surface, determine answers, or any runtime field.
- **No learning/ratification.** Artifacts stay SPECULATIVE/proposal_only. No pack writes, no corpus mutation, no COHERENT promotion, no mounting.
- **Safe failure.** Malformed records and I/O errors are counted/skipped; the tick continues. No did_work / engine checkpoint is set by proposal emission (proposals live outside engine_state).
- **Determinism.** Collection sorts by (predicate, subject, object). Dedupe key is a content hash of the provenance tuple. Repeated identical state → zero new emissions.
## Tests & gates
- Flag-off: no emission, no behavior change.
- Emission for member/subset derived and for relational-transitive derived (less_than, before_event, etc.).
- Stable dedupe on second run.
- Skips for direct facts, malformed, unsupported predicates.
- No status upgrade (remain speculative, proposal_only).
- Re-run of PR-1 tests + architectural invariants remain green.
- wrong_total == 0 on touched surfaces.
## Documentation
- `docs/runtime_contracts.md` — new subsection under idle passes documenting the bridge, eligibility, and contract.
- This note.
- Tiny pointer in root README (if a learning-loop section existed; kept high-level).
## Commit shape
1. test(proposals): cover derived CLOSE proposal bridge (flag-off, emit for both is-a and relational, dedupe, skips, no mutation).
2. feat(proposals): emit review-gated proposals from derived CLOSE facts (emitter + idle_tick wiring behind the flag).
3. docs(proposals): document the bridge in contracts + this analysis note.
## Non-goals (explicit)
- No PR-3 yardstick / capability index lane.
- No FrameVerdict serving or default wiring.
- No determine() answer=False or semantic broadening.
- No corpus/pack mutation.
- No auto-ratify, no COHERENT, no mounting.
- No broad hygiene or unrelated test fixes.
- No change to existing comprehension-failure proposal review contract (additive only).
PR-2 is the minimal bridge that makes the richer derived facts from PR-1 visible to the review path without violating any red line or the SESSION vs. reviewed learning boundary.
Next (after merge): PR-3 yardstick to measure the autonomous CLOSE climb (answerable-set growth with wrong_total=0).
---
*This note + the contracts update close the documentation obligation for the design/capability change.*

View file

@ -180,6 +180,37 @@ Contract:
unchanged for existing callers. This is **not** a second idle loop and **not** the L10
always-on heartbeat — it only surfaces existing review obligations.
### Derived CLOSE proposal bridge (PR-2)
When `review_derived_close_proposals` is enabled, `ChatRuntime.idle_tick` (after the
consolidation pass) runs a deterministic scan over realized derived facts. A fact is
eligible only if:
- `derived is True`
- `derivation is not None` and `derivation.verdict == "entailed"`
- `epistemic_status == "speculative"`
- `relation_predicate` is `"member"`, `"subset"`, or one of the four
`TRANSITIVE_PREDICATES` (`less_than`, `greater_than`, `before_event`, `after_event`)
It emits reviewable proposal-only artifacts (source=`"derived_close_fact"`) carrying
predicate, arguments, derivation (rule/verdict/premise keys), epistemic status, and
structure/dedupe keys. Artifacts are written to `teaching/proposals/derived_close_facts/`
and deduplicated by a stable key (predicate + arguments + derivation + structure_key).
Contract:
- **Proposal-only, review-gated.** The artifacts are for human/HITL review. No corpus
mutation, no ratification, no COHERENT minted, no serving change, no determine change.
- **Skips safely.** Non-derived facts, malformed records, unsupported predicates, and
non-entailed derivations are counted and skipped (never crash, never emit).
- **Deterministic.** Emission order and dedupe are independent of recall order; repeated
ticks on the same state emit zero new proposals.
- **Default off.** Additive to the existing comprehension-failure proposal review. When
off, no derived-close proposals are emitted and `IdleTickResult` is unchanged.
See `docs/analysis/close-derived-proposal-bridge-2026-06-16.md` for the full artifact
schema, dedupe key, test gates, and the PR-1→PR-2 composition.
### Estimation surface (Step E — ESTIMATION)
When `estimation_enabled` and a turn is a **converse query** DETERMINE refused (told