Skip to content

Commit 76d4fe3

Browse files
randrand
committed
feat: complete loop post-M7 adoption plan phases
1 parent 10cb928 commit 76d4fe3

20 files changed

Lines changed: 1886 additions & 49 deletions

‎Makefile‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ CMDS := session-init complexity-check trajectory-save
1414
# Platforms to build for
1515
PLATFORMS := darwin/arm64 darwin/amd64 linux/amd64 linux/arm64 windows/amd64
1616

17-
.PHONY: all dev clean test lint help
17+
.PHONY: all dev clean test lint help rcc-contract-baseline rcc-contract-gate rcc-contract-test
1818

1919
# Default: build for current platform
2020
dev:
@@ -68,6 +68,9 @@ help:
6868
@echo " all - Build for all platforms"
6969
@echo " test - Run tests"
7070
@echo " lint - Run linter"
71+
@echo " rcc-contract-baseline - Generate A1-A5 compatibility artifact set"
72+
@echo " rcc-contract-gate - Run A1-A5 compatibility gate (strict)"
73+
@echo " rcc-contract-test - Run A1-A5 probe test suite"
7174
@echo " clean - Remove built binaries"
7275
@echo " install-tools - Install development tools"
7376
@echo ""
@@ -79,3 +82,17 @@ help:
7982
test-hooks: dev
8083
@echo "Testing session-init..."
8184
@echo '{"session_id":"test","source":"startup"}' | HOOK_DEBUG=1 ./bin/session-init || true
85+
86+
# Generate A1-A5 compatibility evidence artifact
87+
rcc-contract-baseline:
88+
@OUT_DIR="docs/process/evidence/$$(date -u +%F)/rcc-baseline"; \
89+
echo "Writing RCC baseline to $$OUT_DIR"; \
90+
UV_CACHE_DIR=.uv-cache uv run python scripts/rcc_contract_probe.py --output-dir "$$OUT_DIR"
91+
92+
# Strict A1-A5 compatibility gate (non-zero on any invariant failure)
93+
rcc-contract-gate:
94+
UV_CACHE_DIR=.uv-cache uv run python scripts/rcc_contract_probe.py --strict
95+
96+
# A1-A5 contract probe test suite
97+
rcc-contract-test:
98+
UV_CACHE_DIR=.uv-cache uv run --extra dev pytest -q tests/unit/test_rcc_contract_probe.py

‎docs/process/evidence/2026-02-20/rcc-baseline/rcc-contract-baseline.json‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
{
2+
"script": "scripts/rcc_contract_probe.py",
3+
"script_version": 1,
4+
"generated_utc": "2026-02-20T16:56:16.752398+00:00",
5+
"repo_root": "/Users/rand/src/rlm-claude-code",
6+
"python_version": "3.12.11",
7+
"platform": "macOS-26.3-arm64-arm-64bit",
8+
"loop_candidate_repo": "/Users/rand/src/loop",
9+
"loop_candidate_sha": "4bb2f7371e02b5b9c904fb67dcd61eda15725e6a",
10+
"vendor_loop_sha": "4bb2f7371e02b5b9c904fb67dcd61eda15725e6a",
11+
"all_passed": true,
12+
"claim_scope": "claim-ready-for-candidate-tuple",
13+
"invariants": [
14+
{
15+
"invariant": "A1",
16+
"title": "Python import path and module usability",
17+
"passed": true,
18+
"details": "Import path `rlm_core` is usable.",
19+
"observed": {
20+
"missing_exports": [],
21+
"version": "0.1.0",
22+
"features": [
23+
"python"
24+
]
25+
}
26+
},
27+
{
28+
"invariant": "A2",
29+
"title": "Trajectory enum/constructor compatibility",
30+
"passed": true,
31+
"details": "Trajectory enum variants and constructors used by this repo are compatible.",
32+
"observed": {
33+
"missing_variants": [],
34+
"missing_factories": [],
35+
"factory_errors": {}
36+
}
37+
},
38+
{
39+
"invariant": "A3",
40+
"title": "Memory-store behavior compatibility",
41+
"passed": true,
42+
"details": "Basic memory CRUD/search semantics are compatible.",
43+
"observed": {
44+
"db_path": "/var/folders/vx/_xxfn0z95bv7qmfgb3nx6z700000gn/T/rcc-memory-probe-5ptcu3kh/memory.db",
45+
"node_created": "5e853b5f-18bb-46c7-bf8f-3a13558d2ea7",
46+
"search_hits": 1,
47+
"deleted": true,
48+
"stats_total_nodes": 0,
49+
"stats_total_edges": 0
50+
}
51+
},
52+
{
53+
"invariant": "A4",
54+
"title": "Pattern-classifier and smart-router delegation",
55+
"passed": true,
56+
"details": "Classifier/router delegation paths are callable and structurally compatible.",
57+
"observed": {
58+
"activation_should_activate": true,
59+
"activation_reason": "Score 13 >= threshold 3 (signals: multi-file reference, cross-context reasoning, debugging, exhaustive search, security review, continuation)",
60+
"routing_reason": "Query type 'architecture' at depth 0 -> flagship tier (adjusted from flagship)",
61+
"routing_model": "claude-3-opus-20240229"
62+
}
63+
},
64+
{
65+
"invariant": "A5",
66+
"title": "REPL batched-query helper compatibility",
67+
"passed": true,
68+
"details": "Both REPL batched-query helpers are available.",
69+
"observed": {
70+
"llm_batch": true,
71+
"llm_query_batched": true
72+
}
73+
}
74+
]
75+
}

‎docs/process/evidence/2026-02-20/rcc-baseline/rcc-contract-baseline.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# RCC Contract Baseline
2+
3+
- Generated (UTC): `2026-02-20T16:56:16.752398+00:00`
4+
- Candidate loop SHA: `4bb2f7371e02b5b9c904fb67dcd61eda15725e6a`
5+
- Vendor loop SHA: `4bb2f7371e02b5b9c904fb67dcd61eda15725e6a`
6+
- All invariants passing: `True`
7+
- Claim scope: `claim-ready-for-candidate-tuple`
8+
9+
| Invariant | Pass | Details |
10+
|---|---|---|
11+
| A1 | PASS | Import path `rlm_core` is usable. |
12+
| A2 | PASS | Trajectory enum variants and constructors used by this repo are compatible. |
13+
| A3 | PASS | Basic memory CRUD/search semantics are compatible. |
14+
| A4 | PASS | Classifier/router delegation paths are callable and structurally compatible. |
15+
| A5 | PASS | Both REPL batched-query helpers are available. |
16+
17+
## Observed Data
18+
19+
```json
20+
{
21+
"script": "scripts/rcc_contract_probe.py",
22+
"script_version": 1,
23+
"generated_utc": "2026-02-20T16:56:16.752398+00:00",
24+
"repo_root": "/Users/rand/src/rlm-claude-code",
25+
"python_version": "3.12.11",
26+
"platform": "macOS-26.3-arm64-arm-64bit",
27+
"loop_candidate_repo": "/Users/rand/src/loop",
28+
"loop_candidate_sha": "4bb2f7371e02b5b9c904fb67dcd61eda15725e6a",
29+
"vendor_loop_sha": "4bb2f7371e02b5b9c904fb67dcd61eda15725e6a",
30+
"all_passed": true,
31+
"claim_scope": "claim-ready-for-candidate-tuple",
32+
"invariants": [
33+
{
34+
"invariant": "A1",
35+
"title": "Python import path and module usability",
36+
"passed": true,
37+
"details": "Import path `rlm_core` is usable.",
38+
"observed": {
39+
"missing_exports": [],
40+
"version": "0.1.0",
41+
"features": [
42+
"python"
43+
]
44+
}
45+
},
46+
{
47+
"invariant": "A2",
48+
"title": "Trajectory enum/constructor compatibility",
49+
"passed": true,
50+
"details": "Trajectory enum variants and constructors used by this repo are compatible.",
51+
"observed": {
52+
"missing_variants": [],
53+
"missing_factories": [],
54+
"factory_errors": {}
55+
}
56+
},
57+
{
58+
"invariant": "A3",
59+
"title": "Memory-store behavior compatibility",
60+
"passed": true,
61+
"details": "Basic memory CRUD/search semantics are compatible.",
62+
"observed": {
63+
"db_path": "/var/folders/vx/_xxfn0z95bv7qmfgb3nx6z700000gn/T/rcc-memory-probe-5ptcu3kh/memory.db",
64+
"node_created": "5e853b5f-18bb-46c7-bf8f-3a13558d2ea7",
65+
"search_hits": 1,
66+
"deleted": true,
67+
"stats_total_nodes": 0,
68+
"stats_total_edges": 0
69+
}
70+
},
71+
{
72+
"invariant": "A4",
73+
"title": "Pattern-classifier and smart-router delegation",
74+
"passed": true,
75+
"details": "Classifier/router delegation paths are callable and structurally compatible.",
76+
"observed": {
77+
"activation_should_activate": true,
78+
"activation_reason": "Score 13 >= threshold 3 (signals: multi-file reference, cross-context reasoning, debugging, exhaustive search, security review, continuation)",
79+
"routing_reason": "Query type 'architecture' at depth 0 -> flagship tier (adjusted from flagship)",
80+
"routing_model": "claude-3-opus-20240229"
81+
}
82+
},
83+
{
84+
"invariant": "A5",
85+
"title": "REPL batched-query helper compatibility",
86+
"passed": true,
87+
"details": "Both REPL batched-query helpers are available.",
88+
"observed": {
89+
"llm_batch": true,
90+
"llm_query_batched": true
91+
}
92+
}
93+
]
94+
}
95+
```

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,7 @@ Deliverables:
161161
- Repo-specific rollout + rollback playbook for loop pin upgrades.
162162
- Required gate checklist for release.
163163
- Ongoing maintenance cadence ownership and schedule.
164+
- Runbook location: `/Users/rand/src/rlm-claude-code/docs/process/loop-upgrade-runbook.md`.
164165

165166
Exit criteria:
166167
- runbook is complete and executable,

‎docs/process/loop-upgrade-runbook.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Loop Pin Upgrade Runbook
2+
3+
Date: 2026-02-20
4+
Owner epic: `rlm-tfib`
5+
Task: `rlm-tfib.6`
6+
7+
## Purpose
8+
9+
Define an executable rollout and rollback process for `vendor/loop` upgrades in
10+
`rlm-claude-code`, including required compatibility gates and maintenance
11+
cadence.
12+
13+
## Tuple Terms
14+
15+
- Candidate SHA: `git -C /Users/rand/src/loop rev-parse HEAD`
16+
- Vendored SHA: `git -C /Users/rand/src/rlm-claude-code/vendor/loop rev-parse HEAD`
17+
- Claim scope values:
18+
- `not-claim-ready`
19+
- `claim-ready-for-pinned-vendor-sha-only`
20+
- `claim-ready-for-candidate-tuple`
21+
22+
## Rollout Classes
23+
24+
1. Class A (low risk):
25+
- no pybind API surface changes used by `rlm-claude-code`
26+
- expected to pass A1-A5 unchanged
27+
28+
2. Class B (medium risk):
29+
- pybind/runtime behavior updates in delegated components (memory/router/trajectory/repl)
30+
- requires full A1-A5 + targeted unit slices
31+
32+
3. Class C (high risk):
33+
- contract-affecting changes in REPL protocol, pybind exports, or memory semantics
34+
- requires explicit migration notes + rollback rehearsal before merge
35+
36+
## Required Release Checklist
37+
38+
1. Confirm clean parent and submodule state before pin edits:
39+
```bash
40+
git status --short
41+
git submodule status vendor/loop
42+
git -C vendor/loop status --short
43+
```
44+
2. Update submodule pin intentionally:
45+
```bash
46+
git -C vendor/loop fetch --all --tags
47+
git -C vendor/loop checkout <candidate-sha>
48+
git add vendor/loop
49+
```
50+
3. Run compatibility evidence gates:
51+
```bash
52+
make rcc-contract-test
53+
make rcc-contract-gate
54+
```
55+
4. Run policy gates:
56+
```bash
57+
UV_CACHE_DIR=.uv-cache uv run dp review --json
58+
UV_CACHE_DIR=.uv-cache uv run dp verify --json
59+
UV_CACHE_DIR=.uv-cache uv run dp enforce pre-commit --policy dp-policy.json --json
60+
```
61+
5. Record tuple claim scope from probe output (`all_passed=... claim_scope=...`).
62+
63+
## Rollback Triggers
64+
65+
Rollback immediately when any of the following occur after pin movement:
66+
- `make rcc-contract-gate` fails.
67+
- `import rlm_core` fails or required exports in A1/A2 are missing.
68+
- deterministic unit slices covering REPL/orchestrator contract fail.
69+
- claim scope regresses to `not-claim-ready`.
70+
71+
## Rollback Procedure
72+
73+
1. Move submodule back to last known-good SHA:
74+
```bash
75+
git -C vendor/loop checkout <known-good-sha>
76+
git add vendor/loop
77+
```
78+
2. Re-run gates:
79+
```bash
80+
make rcc-contract-gate
81+
UV_CACHE_DIR=.uv-cache uv run dp review --json
82+
```
83+
3. Commit rollback with tuple metadata in message/body.
84+
85+
## Validated Known-Good Rollback Tuple
86+
87+
- Known-good vendored SHA: `6779cdbc970c70f3ce82a998d6dcda59cd171560`
88+
- Validation command run on 2026-02-20:
89+
```bash
90+
make rcc-contract-gate
91+
```
92+
- Evidence artifact:
93+
`/Users/rand/src/rlm-claude-code/docs/process/evidence/2026-02-20/rcc-baseline/rcc-contract-baseline.json`
94+
95+
## Maintenance Cadence
96+
97+
1. Weekly (owner: `rlm` maintainers):
98+
- check candidate loop SHA drift
99+
- log whether a pin update is needed
100+
101+
2. Monthly (owner: `rlm` maintainers):
102+
- run `make rcc-contract-test` + `make rcc-contract-gate`
103+
- confirm tuple claim scope status in evidence artifacts
104+
105+
3. Quarterly (owner: repo steward):
106+
- execute rollback drill to last known-good tuple on a branch
107+
- verify gate recovery and document results in `docs/process/evidence/<date>/`

0 commit comments

Comments
 (0)