|
| 1 | +--- |
| 2 | +type: design |
| 3 | +title: "ADR-008 — The Adaptive, Observable Turn: toolset selection, wired recall, and the receipt ring" |
| 4 | +description: "Completes the ADR-007 Spine into a product turn: (1) ADAPTIVE TOOLING — a toolset decider picks WHICH ≤6 tools the turn advertises (coding/memory/core, deterministic keyword routing, null-floor on plain chat), so the banked '≤6 or the 12B stalls' constraint becomes 'the RIGHT 6 per turn'; (2) RECALL WIRED — the ADR-007 ranked-recall decider now injects matched facts as a system note in the gateway turn (SP_SPINE_RECALL=1, default-off) and emits a typed {recall} SSE event, gated LIVE for faithfulness (matched → fact stated; foreign → abstains, clean parametric answer); (3) THE RECEIPT RING — every spine decision (decide→execute→verify verdict) lands in an observable ring buffer served at /v1/spine and rendered as a panel pane: the operator can watch the organism decide. All default-off; null floor = wave-3 behavior." |
| 5 | +tags: [design, adr, spine, toolset, recall, receipts, observability, sse, gateway, faithfulness] |
| 6 | +timestamp: 2026-07-08T00:00:00Z |
| 7 | +resource: shannon-prime-lattice/papers/PPT-LAT-ADR-008-ADAPTIVE-TURN.md |
| 8 | +sp_status: "REALIZED: offline 12/12 (G-PK2-SPINE-2); live recall faithfulness gate G-PK2-RECALL-LIVE (see receipt)" |
| 9 | +sp_gate: "G-PK2-SPINE-2 (offline) + G-PK2-RECALL-LIVE (live, daemon+gateway)" |
| 10 | +sp_commit: "opens on harness 6cbfa61 (wave 3 spine)" |
| 11 | +sp_repro: "python tests/g_pk2_spine2_offline.py; live: run_console.bat + _pk2_recall_gateway.bat + python -u tests/g_pk2_recall_live.py" |
| 12 | +--- |
| 13 | + |
| 14 | +# ADR-008 — The Adaptive, Observable Turn |
| 15 | + |
| 16 | +**Status: REALIZED.** Builds on ADR-007 (the Harness Spine) and ADR-006 (verify law). |
| 17 | + |
| 18 | +## 1. Decision 1 — ADAPTIVE TOOLING (the toolset decider) |
| 19 | + |
| 20 | +The banked lesson says a 12B picks reliably from ≤6 tools and stalls exploring 14. Wave 2 fixed |
| 21 | +the COUNT; this fixes the CONTENT: a pre-turn `toolset_decider` (priority 10, deterministic |
| 22 | +keyword routing, no model call) classifies the user's message — coding words → the focused |
| 23 | +coding 6 (`read/write/edit_file/search/run_tests/run_command`), memory words → the memory set, |
| 24 | +anything else → **no decision** (the caller's default set = null floor). A wrong pick degrades |
| 25 | +to `load_tools` discovery, never to hard failure. Armed by `SP_SPINE_TOOLSET=1` in the gateway; |
| 26 | +the chosen tier is emitted as a typed `{"toolset": tier}` SSE event. |
| 27 | + |
| 28 | +## 2. Decision 2 — RECALL, WIRED AND GATED LIVE |
| 29 | + |
| 30 | +ADR-007 built the ranked-recall decider but left wiring opt-in pending a faithfulness gate. |
| 31 | +This ADR wires it (`SP_SPINE_RECALL=1`): matched facts are injected as a SYSTEM note |
| 32 | +("use them faithfully; never contradict") immediately before the user's message, and a typed |
| 33 | +`{"recall": facts}` event makes the injection observable. The live gate (G-PK2-RECALL-LIVE) |
| 34 | +checks the two faithfulness poles on the real 12B through the gateway: a matched query must |
| 35 | +fire the event AND state the fact; a foreign query must NOT fire and must answer cleanly from |
| 36 | +parametric knowledge (no hijack). This is the harness-side text-in-context complement to the |
| 37 | +engine's L5 path — when L5 is armed (`run_console_faithful.bat`), leave SP_SPINE_RECALL off |
| 38 | +(one recall authority at a time; composing both is future work with its own gate). |
| 39 | + |
| 40 | +## 3. Decision 3 — THE RECEIPT RING (observability) |
| 41 | + |
| 42 | +`run_spine` now appends every receipt to a bounded ring (200), served at **`/v1/spine`** and |
| 43 | +rendered as an operator-panel pane: decider → kind → verified|VERIFY_FAIL|unverified, result, |
| 44 | +latency. The ADR-006 law is only as good as its visibility — a VERIFY_FAIL that no one sees is |
| 45 | +a silent lie with extra steps. Now it's a red row on the panel. |
| 46 | + |
| 47 | +## 4. Surfaces |
| 48 | + |
| 49 | +`harness/control/spine.py` (+ring, +toolset_decider/toolset_for, +run_pre_turn), |
| 50 | +`harness/server/app.py` (pre-turn wiring, `{recall}`/`{toolset}` events, `/v1/spine`), |
| 51 | +`operator.html` (spine-receipts pane). Flags: `SP_SPINE_RECALL`, `SP_SPINE_TOOLSET` |
| 52 | +(both default-off). Launcher: engine `_pk2_recall_gateway.bat` (the armed gateway). |
| 53 | + |
| 54 | +## 5. Honest scope / next |
| 55 | + |
| 56 | +Toolset routing is keyword-coarse by design (deterministic, zero latency); a learned router is |
| 57 | +future work only if the coarse one measurably mispicks. The recall/L5 composition (both armed) |
| 58 | +is explicitly ungated. Next seams for deciders: task-loop step policy, NIGHTSHIFT admission, |
| 59 | +tool-argument validation. Next for the ring: persist to telemetry-okf (ADR-005 flywheel) so |
| 60 | +receipts survive restarts. |
0 commit comments