Skip to content

Commit 441fb0a

Browse files
randrand
committed
docs: add loop post-M7 adoption plan
1 parent 528f900 commit 441fb0a

1 file changed

Lines changed: 234 additions & 0 deletions

File tree

‎docs/process/loop-post-m7-adoption-plan.md‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# Loop Post-M7 Adoption Plan (dp-codex)
2+
3+
Date: 2026-02-20
4+
Planning task: `rlm-claude-code-8it.1`
5+
Execution epic: `rlm-tfib`
6+
7+
## 1. Objective
8+
9+
Update `rlm-claude-code` to fully leverage the current `loop` project **within current Python binding limits**.
10+
11+
"Fully leverage" in this plan means:
12+
- adopt all relevant post-M7 runtime/protocol fixes that are already available to this consumer,
13+
- remove known contract drifts (A1-A5) between `rlm-claude-code` and `loop`,
14+
- keep behavior pin-aware and evidence-driven,
15+
- preserve compatibility and rollback safety.
16+
17+
This does **not** mean a full Rust-orchestrator swap, because those surfaces are still not exposed in Python bindings.
18+
19+
## 2. Deep-Dive Baseline (Research Summary)
20+
21+
### 2.1 Consumer and upstream snapshots
22+
23+
- `rlm-claude-code` vendored `loop` SHA: `6779cdbc970c70f3ce82a998d6dcda59cd171560`
24+
- standalone `loop` working SHA (research baseline): `4bb2f7371e02b5b9c904fb67dcd61eda15725e6a`
25+
- `loop` execution tracker marks M0..M7 complete as of 2026-02-20.
26+
27+
### 2.2 Upstream policy constraints that govern this migration
28+
29+
From loop execution/contract docs:
30+
- compatibility for `rlm-claude-code` is release-blocking in affected windows,
31+
- compatibility claims are **pin-aware** (candidate SHA vs vendored SHA scope),
32+
- current migration scope is component delegation; full swap is explicitly deferred,
33+
- consumer invariants A1-A5 remain mandatory.
34+
35+
### 2.3 Observed integration state in rlm-claude-code
36+
37+
Current delegation is real and active in:
38+
- complexity classification (`PatternClassifier`),
39+
- memory (`MemoryStore`),
40+
- trajectory (`TrajectoryEvent`),
41+
- epistemic claim extraction,
42+
- optional smart-router delegation.
43+
44+
Core orchestration and REPL control remain Python-owned.
45+
46+
### 2.4 Concrete drift/gap inventory
47+
48+
1. REPL helper compatibility drift:
49+
- local REPL environment exposes `llm_batch` but not `llm_query_batched` alias.
50+
51+
2. Typed-submit protocol drift:
52+
- local flow is centered on `FINAL:` / `FINAL_VAR:` parsing;
53+
- no equivalent for upstream signature registration + `SUBMIT(...)` result path.
54+
55+
3. Binding-surface packaging/stub drift risk:
56+
- local `rlm_core` package layout/stubs differ from upstream Python package structure.
57+
58+
4. Validation drift risk:
59+
- no explicit A1-A5 compatibility gate suite in this repo today;
60+
- no local tuple evidence workflow that emits both candidate/pin scope metadata.
61+
62+
5. Vendored gap size is non-trivial:
63+
- `rlm-core/src`: `97 files changed, 8401 insertions, 1843 deletions` (no-index diff),
64+
- `rlm-core/python/rlm_repl`: `17 files changed, 422 insertions, 2 deletions`,
65+
- `rlm-core/python/rlm_core`: `6 files changed, 49 insertions`.
66+
67+
## 3. Migration Principles
68+
69+
1. Contract-first over code-first:
70+
- every change is tied to A1-A5 and consumer integration contract semantics.
71+
72+
2. Pin-aware truthfulness:
73+
- compatibility claims must always include both tuple SHAs and claim scope.
74+
75+
3. Delegation-first architecture:
76+
- harvest all available upstream value without pretending unavailable Python surfaces exist.
77+
78+
4. Backward-safe rollout:
79+
- preserve legacy execution path while introducing typed-submit path; remove only after evidence.
80+
81+
5. Measurable gates before closure:
82+
- no phase is complete without deterministic tests and reproducible artifacts.
83+
84+
## 4. Target End State
85+
86+
At completion of this epic:
87+
- vendored loop pin is intentionally upgraded to approved post-M7 tuple,
88+
- REPL/orchestrator compatibility with upstream helper/protocol behavior is restored,
89+
- local `rlm_core` wrappers/stubs are aligned with vendored runtime surface,
90+
- A1-A5 gates run in CI/local with tuple evidence output,
91+
- release/rollback runbook and cadence are documented and operational.
92+
93+
## 5. Phased Execution Plan
94+
95+
## Phase 0: Baseline and Gate Harness (`rlm-tfib.1`)
96+
97+
Deliverables:
98+
- Add local consumer contract baseline doc for A1-A5 interpretation in this repo.
99+
- Add compatibility harness command(s) that always emit:
100+
- loop candidate SHA,
101+
- `vendor/loop` SHA,
102+
- gate outcomes.
103+
- Define claim scope language: "verified for pinned vendor SHA" vs "verified for candidate tuple".
104+
105+
Exit criteria:
106+
- A1-A5 baseline is documented.
107+
- Harness run output is reproducible locally.
108+
109+
## Phase 1: Pin + Binding Surface Sync (`rlm-tfib.4`)
110+
111+
Deliverables:
112+
- Update `vendor/loop` submodule to approved post-M7 candidate.
113+
- Reconcile local `rlm_core` Python package wrapper/stubs to eliminate avoidable drift from vendored package shape.
114+
- Document any intentionally retained local deviations.
115+
116+
Exit criteria:
117+
- `import rlm_core` works with upgraded pin.
118+
- Local wrapper/stub surface is traceably aligned to vendored runtime package.
119+
120+
## Phase 2: REPL Protocol Parity (`rlm-tfib.3`)
121+
122+
Deliverables:
123+
- Add migration-window compatibility behavior for batched helper naming (`llm_batch` canonical + compatibility alias).
124+
- Introduce signature registration/clear flow and `SUBMIT(...)` handling in local orchestration boundary.
125+
- Extend parser behavior so typed-submit flow is first-class while keeping legacy `FINAL` fallback.
126+
127+
Exit criteria:
128+
- Typed-submit scenarios pass deterministic tests.
129+
- Legacy `FINAL` path still works.
130+
131+
## Phase 3: Deferred Bridge Alignment (`rlm-tfib.2`)
132+
133+
Deliverables:
134+
- Align pending-operation resolution semantics with upstream runtime behavior.
135+
- Handle `submit_result` validation outcomes with actionable user-visible errors.
136+
- Add structured telemetry/events for deferred and batch resolution lifecycle.
137+
138+
Exit criteria:
139+
- deferred and batch flows are deterministic in tests,
140+
- submit validation failures are surfaced clearly,
141+
- no regression in existing orchestration flows.
142+
143+
## Phase 4: A1-A5 Contract Suite + Tuple Evidence (`rlm-tfib.5`)
144+
145+
Deliverables:
146+
- Implement explicit A1-A5 tests:
147+
- A1 import/module usability,
148+
- A2 enum/constructor compatibility,
149+
- A3 memory behavior/locking assumptions,
150+
- A4 classifier/router delegation behavior,
151+
- A5 batched helper compatibility.
152+
- Add evidence pipeline commands that capture tuple metadata + gate result summary.
153+
154+
Exit criteria:
155+
- suite fails on contract drift,
156+
- artifacts are adequate for compatibility claim review.
157+
158+
## Phase 5: Rollout and Governance (`rlm-tfib.6`)
159+
160+
Deliverables:
161+
- Repo-specific rollout + rollback playbook for loop pin upgrades.
162+
- Required gate checklist for release.
163+
- Ongoing maintenance cadence ownership and schedule.
164+
165+
Exit criteria:
166+
- runbook is complete and executable,
167+
- rollback to prior tuple is documented and validated.
168+
169+
## 6. Beads Execution Backlog (Created)
170+
171+
- `rlm-tfib.1` Establish loop compatibility baseline and pin-aware gate harness
172+
- `rlm-tfib.4` Sync vendor/loop pin and refresh Python binding surface (depends on `.1`)
173+
- `rlm-tfib.3` Implement REPL protocol parity with loop post-M7
174+
- `rlm-tfib.2` Align orchestrator deferred execution bridge (depends on `.3`)
175+
- `rlm-tfib.5` Build A1-A5 contract suite and tuple evidence pipeline (depends on `.2`)
176+
- `rlm-tfib.6` Publish rollout/rollback/maintenance cadence (depends on `.5`)
177+
178+
Planning task:
179+
- `rlm-claude-code-8it.1` (this document + backlog creation)
180+
181+
## 7. Risks and Controls
182+
183+
1. Runtime breakage from pin jump
184+
- Control: staged rollout + A1-A5 gates + tuple-scoped claims.
185+
186+
2. Hidden protocol regressions (typed submit vs FINAL)
187+
- Control: dual-path tests and explicit fallback retention until evidence is stable.
188+
189+
3. SQLite behavior changes in memory layer
190+
- Control: dedicated A3 compatibility tests and WAL/locking focused regression checks.
191+
192+
4. Drift reappearing after initial migration
193+
- Control: recurring compatibility cadence and release checklist hard-gates.
194+
195+
## 8. dp-codex Execution Method
196+
197+
Plan preparation followed dp-codex conventions by:
198+
- claiming tracked work in beads,
199+
- creating a dedicated epic and phased child tasks with dependencies,
200+
- tying each phase to explicit acceptance criteria and gate expectations,
201+
- grounding scope in consumer contracts and tuple-based compatibility policy.
202+
203+
Note: `uv run dp ...` CLI was not available in this repository environment during planning, so beads-native decomposition and contract-based planning were used as the authoritative dp-codex workflow substrate.
204+
205+
## 9. Source Artifacts Used in This Deep Dive
206+
207+
`rlm-claude-code`:
208+
- `pyproject.toml`
209+
- `src/repl_environment.py`
210+
- `src/response_parser.py`
211+
- `src/orchestrator/core.py`
212+
- `src/memory_store.py`
213+
- `src/complexity_classifier.py`
214+
- `src/trajectory.py`
215+
- `src/smart_router.py`
216+
- `src/epistemic/claim_extractor.py`
217+
- `rlm_core/__init__.py`
218+
- `rlm_core/__init__.pyi`
219+
220+
`loop` / `rlm-core`:
221+
- `docs/execution-plan/STATUS.md`
222+
- `docs/execution-plan/DECISIONS.md`
223+
- `docs/execution-plan/contracts/CONSUMER-INTEGRATION.md`
224+
- `docs/migration-spec-rlm-claude-code.md`
225+
- `docs/internals/python-orchestrator-swap-analysis.md`
226+
- `rlm-core/src/pybind/mod.rs`
227+
- `rlm-core/src/repl.rs`
228+
- `rlm-core/src/adapters/claude_code/adapter.rs`
229+
- `rlm-core/src/orchestrator.rs`
230+
- `rlm-core/python/rlm_repl/main.py`
231+
- `rlm-core/python/rlm_repl/sandbox.py`
232+
- `rlm-core/python/rlm_repl/helpers.py`
233+
- `rlm-core/python/rlm_core/__init__.py`
234+
- `rlm-core/python/rlm_core/__init__.pyi`

0 commit comments

Comments
 (0)