54e6bfc0d0
Implements the 4-phase documentation reorganization master plan. - Consolidation: Merged brief/, handoff/, planning/, and decisions/ into briefs/, handoffs/, plans/, and adr/ respectively (101 ADRs relocated) - Root Cleanup: Relocated HANDOFF-gpt55-*.md and key top-level docs (runtime_contracts.md, etc.) to canonical folders. Added superseded alerts. - Indices & Navigation: Created docs/README.md navigation document, docs/sessions/README.md index, docs/adr/README.md index - Note: Also includes prior commit adding ADR-0200+ corpus hygiene governance (ADR-0225, dependency map, backfilled cross-references)
71 lines
3.3 KiB
Markdown
71 lines
3.3 KiB
Markdown
# ADR-0152 — Learning-Arc Demo (`core demo learning-arc`)
|
|
|
|
**Status**: Accepted
|
|
**Implements**: W-019
|
|
**Depends on**: ADR-0150 (W-018 checkpoint contemplation), ADR-0151 (W-017 auto-proposal)
|
|
|
|
## Context
|
|
|
|
ADR-0055..0057 ships `core demo learning-loop`, which demonstrates the full cold-turn
|
|
→ discovery → operator-authored proposal → accept → grounded surface arc. In that
|
|
demo the operator supplies the connective, object, and evidence reference for the
|
|
proposed chain.
|
|
|
|
W-018 and W-017 together enable a new capability: the engine enriches discovery
|
|
candidates through autonomous contemplation at checkpoint and can generate proposal
|
|
structures without operator-crafted connective or object.
|
|
|
|
A new demo is needed to make this distinction observable and falsifiable.
|
|
|
|
## Decision
|
|
|
|
`core demo learning-arc` (`evals/learning_arc/run_demo.py`) scripts five scenes:
|
|
|
|
1. **S1 — Cold session**: `ChatRuntime(auto_contemplate=True, engine_state_path=tmpdir)`
|
|
turns with an ungrounded prompt. Checkpoint enriches the emitted candidate via
|
|
`contemplate()` and persists to `engine_state/discovery_candidates.jsonl`.
|
|
|
|
2. **S2 — Checkpoint enrichment**: Read the persisted candidate. Assert it carries
|
|
`polarity`, `claim_domain`, and `sub_questions` populated by `contemplate()`.
|
|
Assert the engine's `_decompose()` enumerated `(narrative, cause, reveals, meaning)`
|
|
as a candidate chain from existing corpus shapes.
|
|
|
|
3. **S3 — Engine-authored proposal**: Build the full chain candidate using the
|
|
engine-derived connective (`reveals`) and object (`meaning`) from `_decompose()`
|
|
output. Add the corpus evidence reference (`cause_creation_reveals_meaning`) that
|
|
the engine found as the shape template. `propose_from_candidate` with
|
|
`source.kind="contemplation"`. Replay gate runs.
|
|
|
|
4. **S4 — Operator ratifies**: `accept_proposal` against a transient corpus. Active
|
|
corpus is byte-identical before and after. Provenance: `adr-0057:discovery_promoted`.
|
|
|
|
5. **S5 — Session 2 grounded**: Same prompt against transient corpus →
|
|
`grounding_source == "teaching"`, surface contains subject / connective / object.
|
|
|
|
## The distinction from learning-loop
|
|
|
|
| | learning-loop | learning-arc |
|
|
|---|---|---|
|
|
| Connective source | operator | engine (_decompose) |
|
|
| Object source | operator | engine (_decompose) |
|
|
| Evidence ref | operator | engine (corpus shape match) |
|
|
| `source.kind` | `"operator"` | `"contemplation"` |
|
|
| Operator action | author + ratify | ratify only |
|
|
|
|
## Trust boundary
|
|
|
|
- Writes only to `tempfile.mkdtemp()` directories (engine state, proposal log, transient corpus)
|
|
- Active corpus on disk is byte-identical before and after (`active_corpus_byte_identical` asserted)
|
|
- No LLM calls, no stochastic sampling, no approximation
|
|
|
|
## Falsifiable claims
|
|
|
|
`test_learning_arc_demo.py` (11 tests) pins:
|
|
|
|
- `learning_arc_closed` — before grounding_source ≠ "teaching", after == "teaching"
|
|
- `active_corpus_byte_identical` — no corpus mutation
|
|
- `engine_chain_found` in S2 — decomposition found `(narrative, cause, reveals, meaning)`
|
|
- `source_kind == "contemplation"` in S3
|
|
- `replay_equivalent` in S3 — replay gate passed, no regression
|
|
- `transient_lines_after == transient_lines_before + 1` in S4
|
|
- `before["surface"] != after["surface"]` — measurable change on same prompt
|