@@ -0,0 +1,159 @@ |
| 1 | +# Sprint 16: Entrypoint Shell, Launcher Contract, and Explore Continuity |
| 2 | + |
| 3 | +## Prerequisites |
| 4 | + |
| 5 | +Sprint 15 |
| 6 | + |
| 7 | +## Goals |
| 8 | + |
| 9 | +Turn Sprint 15's ownership cleanup into a cleaner public runtime shape: reduce the remaining `Agent`-shaped bootstrap dependency, shrink `agent/loop.py` further toward a thin facade, and make explore mode feel like a maintained read-only runtime lane instead of a one-shot side path. |
| 10 | + |
| 11 | +Sprint 15 closed an important loop. Loader now has a shared runtime bootstrap seam, runtime-owned safeguards and deliberation helpers, compatibility-only `agent/reasoning.py` and `agent/safeguards.py`, no hidden `Agent._build_runtime_context()` helper, and a much smaller `agent/loop.py`. |
| 12 | + |
| 13 | +That leaves a tighter but more visible set of residual debts: |
| 14 | + |
| 15 | +- `conversation.py` and `explore.py` still start from an `Agent`-shaped bootstrap source at the public entrypoint layer |
| 16 | +- `agent/loop.py` still owns conversational fast-path behavior, decomposition orchestration, and too much session/UI-facing wiring for a runtime that otherwise lives under `src/loader/runtime/` |
| 17 | +- `agent/reasoning.py` and `agent/safeguards.py` are now compatibility-only, but Loader has not yet decided how narrow that compatibility surface should become |
| 18 | +- explore mode is structurally cleaner than it was, but it is still a one-shot lookup lane rather than a more intentional read-only workflow |
| 19 | + |
| 20 | +Sprint 16 is about finishing that next contraction without drifting into a brand-new roadmap: |
| 21 | + |
| 22 | +- the runtime gets a first-class launcher/entrypoint contract instead of depending on an `Agent`-shaped bootstrap source everywhere |
| 23 | +- `agent/loop.py` shrinks further toward a public facade over runtime-owned launch and orchestration helpers |
| 24 | +- compatibility exports remain explicit, tested, and intentionally narrow instead of becoming permanent soft ownership |
| 25 | +- explore mode gains a better continuity/inspection contract so it feels like a real product lane, not just a single-turn utility |
| 26 | + |
| 27 | +This sprint should feel like consolidating the public shell after Sprint 15, not reopening the old runtime ownership debates. |
| 28 | + |
| 29 | +The references for this sprint are: |
| 30 | + |
| 31 | +- `refs/claw-code/rust/crates/runtime/src/conversation.rs` |
| 32 | +- `refs/claw-code/rust/crates/runtime/src/runtime_context.rs` |
| 33 | +- `refs/claw-code/rust/crates/runtime/src/policy_engine.rs` |
| 34 | +- `refs/claw-code/rust/crates/runtime/src/prompt.rs` |
| 35 | +- `refs/claw-code/PARITY.md` |
| 36 | +- `.docs/audit.txt` |
| 37 | +- `.docs/audit_sprints/trunk_sitrep.md` |
| 38 | +- `.docs/sprints/sprint15.md` |
| 39 | +- `refs/oh-my-codex/src/ralplan/runtime.ts` |
| 40 | +- `refs/oh-my-codex/src/verification/verifier.ts` |
| 41 | + |
| 42 | +## Deliverables |
| 43 | + |
| 44 | +### 1. Introduce a first-class runtime launcher contract |
| 45 | + |
| 46 | +Sprint 15 made bootstrap shared. Sprint 16 should make the public launch path less `Agent`-shaped. |
| 47 | + |
| 48 | +Implementation targets: |
| 49 | + |
| 50 | +- introduce an explicit launcher/entrypoint seam under `src/loader/runtime/`, likely around: |
| 51 | + - creating a main-turn runtime |
| 52 | + - creating an explore runtime |
| 53 | + - carrying the minimum public bootstrap state needed by those runtimes |
| 54 | +- reduce direct dependence on `ConversationRuntime(self)` / `ExploreRuntime(self)` from `agent/loop.py` |
| 55 | +- make the launcher contract narrow and explicit: |
| 56 | + - project/session/prompt/capability state that truly belongs to launch-time setup |
| 57 | + - public callbacks that still genuinely need to stay at the `Agent` layer |
| 58 | +- avoid replacing one implicit wrapper with another vague wrapper; the goal is a visibly smaller ownership surface |
| 59 | + |
| 60 | +The goal is not to erase `Agent`. The goal is to make `Agent` a thin public shell over a runtime launcher contract instead of the default owner of launch-time state. |
| 61 | + |
| 62 | +### 2. Shrink `agent/loop.py` into a thinner facade |
| 63 | + |
| 64 | +Sprint 15 deleted dead code. Sprint 16 should move more of the still-live orchestration to clearer homes. |
| 65 | + |
| 66 | +Implementation targets: |
| 67 | + |
| 68 | +- move or re-home more of the still-live `agent/loop.py` behavior that has become runtime or launcher ownership in practice, especially: |
| 69 | + - conversational fast-path handling |
| 70 | + - decomposition orchestration |
| 71 | + - runtime/explore construction and launch wiring |
| 72 | + - session-facing setup that does not truly need to live on the agent object |
| 73 | +- keep `agent/loop.py` focused on: |
| 74 | + - public entrypoints |
| 75 | + - top-level session lifecycle |
| 76 | + - UI/event integration |
| 77 | + - explicit compatibility shims that still need to exist |
| 78 | +- continue deleting dead helper paths instead of letting the shell regrow around the new launcher seam |
| 79 | + |
| 80 | +This is the sprint where the public shell should become visibly easier to understand. |
| 81 | + |
| 82 | +### 3. Narrow the compatibility-export surface deliberately |
| 83 | + |
| 84 | +`agent/reasoning.py` and `agent/safeguards.py` are now compatibility layers. Sprint 16 should make that state intentional rather than indefinite. |
| 85 | + |
| 86 | +Implementation targets: |
| 87 | + |
| 88 | +- inventory the remaining compatibility-only exports under: |
| 89 | + - `src/loader/agent/reasoning.py` |
| 90 | + - `src/loader/agent/safeguards.py` |
| 91 | +- decide which exports still need to exist for test/import compatibility and which can be retired |
| 92 | +- keep internal Loader code importing canonical runtime modules instead of their compatibility mirrors |
| 93 | +- add direct tests that lock the intended compatibility contract: |
| 94 | + - which symbols are still re-exported |
| 95 | + - which internal hot paths must not import via compatibility modules anymore |
| 96 | + |
| 97 | +The goal is not immediate deletion of every compatibility export. The goal is to stop compatibility from behaving like shadow ownership. |
| 98 | + |
| 99 | +### 4. Give explore mode better continuity and inspection shape |
| 100 | + |
| 101 | +Explore is cleaner now, but still underpowered as a product lane. |
| 102 | + |
| 103 | +Implementation targets: |
| 104 | + |
| 105 | +- deepen the explore runtime without turning it into full workflow mode, likely around: |
| 106 | + - lightweight transcript continuity for follow-up explore questions |
| 107 | + - clearer inspection or status surfaces for recent explore activity |
| 108 | + - a stronger read-only session/state story |
| 109 | +- preserve the current constraints: |
| 110 | + - read-only registry |
| 111 | + - no DoD |
| 112 | + - no mutating workflow artifacts |
| 113 | + - explicit denial of write/destructive actions |
| 114 | +- add direct coverage so explore remains a maintained runtime lane rather than a product afterthought |
| 115 | + |
| 116 | +The goal is to make explore feel intentionally usable over multiple adjacent questions, not to turn it into a second main runtime. |
| 117 | + |
| 118 | +### 5. Keep the audit line active as a deletion-first check |
| 119 | + |
| 120 | +The useful part of `audit.txt` is still the bias toward deleting disguised ownership instead of endlessly wrapping it. |
| 121 | + |
| 122 | +Implementation targets: |
| 123 | + |
| 124 | +- use the audit's core complaint as a Sprint 16 check: |
| 125 | + - do not leave the launcher contract `Agent`-shaped by habit |
| 126 | + - do not regrow logic in `agent/loop.py` after moving it out |
| 127 | + - do not let compatibility exports become the internal default import path again |
| 128 | +- update `PARITY.md` and the sprint audit only after the launcher/entrypoint work is directly covered |
| 129 | + |
| 130 | +## Testing strategy |
| 131 | + |
| 132 | +- unit coverage for: |
| 133 | + - runtime launcher creation and bootstrap narrowing |
| 134 | + - conversational/decomposition orchestration after re-homing |
| 135 | + - compatibility-export boundaries |
| 136 | + - explore continuity state and inspection helpers |
| 137 | +- runtime coverage for: |
| 138 | + - main runtime launch through the new launcher contract |
| 139 | + - explore runtime launch and follow-up continuity |
| 140 | + - Sprint 00-15 parity scenarios staying green after the entrypoint-shell contraction |
| 141 | +- regression coverage for: |
| 142 | + - no return of hidden bootstrap helpers |
| 143 | + - no internal fallback to compatibility imports for runtime-owned helpers |
| 144 | + - no mutation leakage into explore continuity/session behavior |
| 145 | + |
| 146 | +## Definition of done |
| 147 | + |
| 148 | +- Loader has a first-class runtime launcher/entrypoint seam instead of relying on an `Agent`-shaped bootstrap source everywhere |
| 149 | +- `agent/loop.py` shrinks further toward a public facade over runtime-owned launch/orchestration helpers |
| 150 | +- compatibility exports under `agent/reasoning.py` and `agent/safeguards.py` are narrower, explicitly tested, and no longer used by internal hot paths |
| 151 | +- explore mode has a stronger continuity/inspection contract while staying read-only and workflow-light |
| 152 | +- the parity baseline remains green after the launcher/entrypoint changes |
| 153 | + |
| 154 | +## Explicitly out of scope |
| 155 | + |
| 156 | +- full claw-code policy-engine parity |
| 157 | +- multi-agent or team orchestration |
| 158 | +- AST-aware or LSP-aware semantic artifact diffs |
| 159 | +- a full visual explore/workflow UI |
