docs: reconcile tracker truth and bootstrap coverage gate

Author: rand

.github/workflows/rlm-core-coverage.yml

@@ -0,0 +1,47 @@
+name: rlm-core coverage
+
+on:
+  pull_request:
+    paths:
+      - "rlm-core/**"
+      - "rlm-core-derive/**"
+      - "scripts/run_coverage.sh"
+      - "Makefile"
+      - ".github/workflows/rlm-core-coverage.yml"
+  push:
+    branches:
+      - main
+    paths:
+      - "rlm-core/**"
+      - "rlm-core-derive/**"
+      - "scripts/run_coverage.sh"
+      - "Makefile"
+      - ".github/workflows/rlm-core-coverage.yml"
+
+jobs:
+  coverage:
+    name: Coverage Gate
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install cargo-llvm-cov
+        uses: taiki-e/install-action@cargo-llvm-cov
+
+      - name: Run coverage gate
+        env:
+          COVERAGE_MIN_LINES: "80"
+        run: make coverage
+
+      - name: Upload coverage artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: rlm-core-coverage
+          path: coverage/
+          if-no-files-found: error

Makefile

@@ -1,6 +1,6 @@
 SHELL := /bin/bash
 
-.PHONY: check lint typecheck test review verify
+.PHONY: check lint typecheck test coverage review verify
 
 check: typecheck test
 
@@ -13,6 +13,9 @@ typecheck:
 test:
 	cd rlm-core && cargo test --quiet
 
+coverage:
+	./scripts/run_coverage.sh
+
 review: typecheck
 
 verify: check

README.md

@@ -162,6 +162,7 @@ rlm-core powers these projects:
 - [Documentation Portal](docs/README.md) - Role-based index and workflow-oriented navigation.
 - [User Guide](docs/user-guide/README.md) - New user to power-user guidance.
 - [Developer Guide](docs/developer-guide/README.md) - Setup, gates, and contribution workflow.
+- [API Docs Status](docs/developer-guide/api-docs-status.md) - What "documented" currently means, without fiction.
 - [Internals](docs/internals/README.md) - Architecture, OODA flow, and module map.
 - [Troubleshooting](docs/troubleshooting/README.md) - Incident triage and diagnostics checklists.
 

docs/developer-guide/README.md

@@ -7,6 +7,7 @@ This guide is for contributors changing code in Loop itself.
 1. [Setup](./setup.md)
 2. [Quality Gates](./quality-gates.md)
 3. [Contribution Workflow](./contribution-workflow.md)
+4. [API Docs Status](./api-docs-status.md)
 
 ## Development Contract
 

docs/developer-guide/api-docs-status.md

@@ -0,0 +1,38 @@
+# API Documentation Status
+
+This page is the source of truth for what "documented" means in this repository.
+
+## Current State (2026-02-20)
+
+- Module-level docs: complete baseline.
+- Workflow/docs/navigation guides: complete baseline.
+- Item-level rustdoc coverage for every public symbol: partial and incremental.
+
+That means the project is navigable and operable, but not every exported method has bespoke prose yet.
+No hand-waving, no cosplay as "finished."
+
+## Enforcement Contract
+
+Use these commands for docs quality checks:
+
+```bash
+cd /Users/rand/src/loop/rlm-core
+RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
+```
+
+Interpretation:
+- Build succeeds: no rustdoc warnings.
+- Build fails: fix docs or signatures before merge.
+
+## Policy
+
+1. Never claim "all public APIs documented" unless item-level rustdoc coverage is actually complete.
+2. Module-level docs are mandatory.
+3. Item-level docs are required for newly introduced public API in the same change set.
+4. Legacy public API doc depth is improved incrementally, prioritized by high-use surfaces.
+
+## Practical Rule of Thumb
+
+- If users copy/paste from it: document it now.
+- If only a debugger should ever see it: document it soon.
+- If nobody can explain it without opening three files: document it yesterday.

docs/developer-guide/quality-gates.md

@@ -1,6 +1,6 @@
 # Quality Gates
 
-Loop uses layered quality gates: local correctness, policy enforcement, and release-grade verification.
+Loop uses layered quality gates: local correctness, coverage proof, policy enforcement, and release-grade verification.
 
 ## Gate Layers
 
@@ -14,7 +14,22 @@ Runs:
 - Type checks
 - Tests
 
-### Layer 2: Governance review
+### Layer 2: Coverage proof (CI-backed, locally runnable when tooling is available)
+
+```bash
+make coverage
+```
+
+Runs:
+- `scripts/run_coverage.sh`
+- `cargo llvm-cov` line-coverage gate (`COVERAGE_MIN_LINES`, default `80`)
+- Artifact output: `coverage/lcov.info`, `coverage/summary.txt`
+
+Notes:
+- If `cargo-llvm-cov` is missing locally, the script exits with actionable install guidance.
+- GitHub Actions workflow `rlm-core-coverage.yml` is the canonical enforcement path.
+
+### Layer 3: Governance review
 
 ```bash
 ./scripts/dp review --json
@@ -25,7 +40,7 @@ Purpose:
 - Consistent, machine-readable status
 - Standardized workflow enforcement
 
-### Layer 3: Enforcement gates
+### Layer 4: Enforcement gates
 
 ```bash
 ./scripts/dp enforce pre-commit --policy dp-policy.json --json
@@ -55,7 +70,8 @@ No partial-pass narratives.
 
 1. During iteration: targeted tests.
 2. Before commit: `make check`.
-3. Before push: full `dp` enforcement chain.
+3. Before push: `make coverage` (or verify CI coverage gate pass when local tool install is blocked).
+4. Before push: full `dp` enforcement chain.
 
 ## Evidence Logging
 

docs/execution-plan/DECISIONS.md

@@ -264,6 +264,47 @@ Use this file for architecture and contract decisions that affect more than one
 - Preserves reproducibility by requiring clean-clone claim runs despite canonical local working-tree churn.
 - Impacted tasks/gates: loop-5va, Ops-Weekly, VG-LA-001, VG-LA-002, VG-CONTRACT-001.
 
+## D-019 Coverage Proof Uses Reproducible `llvm-cov` Gate With CI Canonical Evidence
+
+- Status: Accepted
+- Date: 2026-02-20
+- Context: Historical coverage closure claims were not backed by a reproducible, enforced coverage gate in this repository.
+- Decision:
+- Adopt `scripts/run_coverage.sh` + `make coverage` as the canonical coverage execution path.
+- Add CI workflow `.github/workflows/rlm-core-coverage.yml` as the canonical enforcement/evidence path.
+- Set line-coverage threshold policy to `>= 80%` (`COVERAGE_MIN_LINES`, default `80`).
+- Consequences:
+- Coverage evidence becomes repeatable and reviewable with concrete artifacts (`coverage/lcov.info`, `coverage/summary.txt`).
+- Local environments without `cargo-llvm-cov` can still proceed with explicit blocked evidence while CI remains authoritative.
+- Impacted tasks/gates: loop-k7d, VG-COVERAGE-001.
+
+## D-020 `rlm-claude-code` Migration Scope Is Component Delegation Until Binding Surface Expands
+
+- Status: Accepted
+- Date: 2026-02-20
+- Context: Early migration specs model full Python replacement, but Python bindings still do not expose orchestration/repl surfaces (`Orchestrator`, `ClaudeCodeAdapter`, `ReplPool`/`ReplHandle`).
+- Decision:
+- Treat component-level delegation as the supported migration end state for current scope.
+- Mark full replacement language in migration docs as archival target-state planning, not active backlog.
+- Consequences:
+- Removes ambiguity between executed migration reality and aspirational architecture.
+- Prevents false "partial implementation" interpretation for intentionally out-of-scope binding gaps.
+- Impacted tasks/gates: loop-cyl, loop-k7d, VG-CONTRACT-001, documentation reconciliation gates.
+
+## D-021 API Documentation Claims Must Distinguish Module-Level Baseline vs Item-Level Depth
+
+- Status: Accepted
+- Date: 2026-02-20
+- Context: Prior closure text implied complete public API docs while item-level rustdoc remained partial.
+- Decision:
+- Treat module-level docs as mandatory baseline.
+- Require item-level docs for newly introduced public API in the same change set.
+- Report legacy item-level rustdoc depth as incremental progress, not "fully complete."
+- Consequences:
+- Eliminates over-claims in project status reporting.
+- Preserves merge discipline for new API surfaces without blocking on historical backlog in a single tranche.
+- Impacted tasks/gates: loop-4w9 (historical interpretation), loop-k7d, docs/developer-guide/api-docs-status.md, doc review gates.
+
 ## Update Rule
 
 When adding a new decision:

docs/execution-plan/LANE-MAP.md

@@ -6,13 +6,13 @@ This map defines lane ownership and safe-mode activation rules.
 
 Default on this machine:
 
-- Lane A: active execution lane for M7 runtime closure (heavy work allowed via wrapper)
-- Lane B: read-only by default (docs/governance lane)
-- Lane C: cadence + consumer lane (heavy work only when Lane A is idle)
+- Lane A: complete M7 runtime closure lane (historical)
+- Lane B: complete M7 docs/governance lane (historical)
+- Lane C: cadence + consumer operations lane (active steady-state)
 
-Lane A is the default heavy lane for M7; Lane B and Lane C may run heavy commands only when orchestrator explicitly marks them active in `WORKBOARD.md`.
+Heavy commands run in Lane C steady-state cadence windows; any new implementation tranche requires explicit activation in `WORKBOARD.md`.
 
-## Lane A - M7 Core Runtime Closure (Active)
+## Lane A - M7 Core Runtime Closure (Complete)
 
 Scope:
 
@@ -37,7 +37,7 @@ Primary file areas:
 - `/Users/rand/src/loop/docs/spec/`
 - `/Users/rand/src/loop/docs/execution-plan/`
 
-## Lane B - M7 Docs/Governance Reconciliation (Standby)
+## Lane B - M7 Docs/Governance Reconciliation (Complete)
 
 Scope:
 
@@ -59,18 +59,17 @@ Start condition:
 - Lane A has completed implementation-heavy tasks or is blocked.
 - Orchestrator marks Lane B active in `WORKBOARD.md`.
 
-## Lane C - Consumer Cadence and Interop Follow-up (Conditional)
+## Lane C - Consumer Cadence and Interop Follow-up (Steady-State)
 
 Scope:
 
 - Ongoing Ops-Weekly compatibility cadence
-- `M7-T09` io-rflx adapter fixture + calibration task
 
 Task order:
 
 1. Ops-Weekly cadence runs (steady-state)
-2. `M7-T09` once `M7-T08` is done
-3. Resume cadence ownership after M7 closure
+2. Open and claim a new scoped issue when cadence discovers regressions/new scope
+3. Execute fix + evidence loop, then return to cadence ownership
 
 Primary file areas:
 

docs/execution-plan/README.md

@@ -15,16 +15,16 @@ Last reconciled: 2026-02-20 (live state source: `docs/execution-plan/STATUS.md`
 - Small-batch: execute one task card at a time, not one milestone at a time.
 - Reproducibility: every gate has a deterministic command and pass criteria.
 
-## Current Reality (Historical Snapshot: 2026-02-19 Post-M6 + M7 Planning)
+## Current Reality (Live Snapshot: 2026-02-20 Reconciliation)
 
 Use `docs/execution-plan/STATUS.md` for live status before acting on any item below.
 
-- M0-M6 remediation/governance milestones are complete with evidence.
-- SPEC-20..27 still contain implementation gaps or partial integrations requiring runtime closure.
-- Open gap IDs from traceability artifact: `G-001` (`LLM_BATCH` end-to-end runtime integration) and `G-002` (orchestrator fallback wiring).
-- `loop-agent` and `io-rflx` remain active integration targets; compatibility claims must follow D-017 clean-clone committed-tuple policy.
+- M0-M7 remediation/governance milestones are complete with evidence.
+- Historical M7 gaps (`G-001`, `G-002`) are closed by `M7-T01` and `M7-T02`.
+- Post-M7 critical refinement backlog (`loop-azq` + `loop-azq.1..9`) is implemented and closed.
+- No open implementation backlog currently exists in Beads (`open=0`, `in_progress=0`, `blocked=0`).
+- `loop-agent` and `io-rflx` remain active integration targets; claim-grade compatibility evidence follows D-017 clean-clone committed-tuple policy.
 - Safe mode remains mandatory due prior OOM history; heavy command concurrency stays at 1.
-- M7 is complete; post-M7 critical refinements are tracked in `loop-azq` and child tasks.
 
 ## File Map
 

docs/execution-plan/STATUS.md

@@ -38,7 +38,7 @@ Last updated: 2026-02-20
 | F10 | No executable performance gate harness for REPL startup/batch throughput | Resolved by M5-T01 (`run_m5_perf_harness.sh` + VG-PERF artifacts) | M5 |
 | F11 | Efficacy scenario suite lacked explicit mixed batch and fallback-non-submit coverage | Resolved by M5-T02 scenario matrix + targeted tests (`45 passed`) | M5 |
 | F12 | No baseline-vs-candidate performance/efficacy rollup report | Resolved by M5-T03 comparative analysis report with regression check | M5 |
-| F13 | Residual implementation gaps remained across SPEC-20..27 after M0-M6 closure | M7 task cards (`M7-T01`..`M7-T10`) are complete; post-M7 up-next critical refinements are explicitly tracked in `loop-azq` with reconciled spec metadata | M7/post-M7 |
+| F13 | Residual implementation gaps remained across SPEC-20..27 after M0-M6 closure | Resolved: M7 task cards (`M7-T01`..`M7-T10`) and post-M7 refinement backlog (`loop-azq` + children) are complete and closed | M7/post-M7 |
 
 ## Active Blockers
 
@@ -99,12 +99,13 @@ Last updated: 2026-02-20
 | R46 | Closed M7-T08 by enforcing SPEC-25 root prompt submit semantics, aligning helper-surface guidance with runtime helpers, and passing context/REPL/doc gates | `evidence/2026-02-20/milestone-M7/M7-T08-validation-summary.md` |
 | R47 | Closed M7-T09 by delivering `io_rflx_interop.v0` fixture/calibration artifacts, executable RFLX fixture gate coverage, and refreshed RFLX/contract/perf evidence | `evidence/2026-02-20/milestone-M7/M7-T09-validation-summary.md` |
 | R48 | Closed M7-T10 by reconciling SPEC-20..27 status/governance metadata, refreshing consumer claim evidence, and assigning post-M7 up-next critical gaps to `loop-azq` | `evidence/2026-02-20/milestone-M7/M7-T10-validation-summary.md` |
+| R49 | Closed post-M7 reconciliation drift by aligning execution-plan tracker docs with live Beads state (`loop-azq` closed, no active implementation backlog) | `loop-k7d` + updated tracker docs |
 
 ## Top Priority Queue (Next 9 Tasks)
 
 | Priority | Task ID | Description |
 |---|---|---|
-| P0 | loop-azq | Decompose and execute up-next critical post-M7 spec refinements backlog |
+| P0 | None (no open implementation backlog) | Create and claim a new issue from cadence findings or newly approved scope before editing |
 
 ## Consumer Readiness Snapshot