lda-wf/docs/historical/superpowers/plans/2026-06-04-coderabbit-cleanup-followups.md

CodeRabbit Cleanup Follow-Ups Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Resolve non-blocking cleanup findings from the June 4 CodeRabbit review without mixing broad refactors into the focused correctness patch.

Architecture: Keep behavior unchanged unless a task explicitly says otherwise. Prefer documentation, small helpers, and narrowly scoped tests over cross-package refactors. Do not move modules or rename public APIs in this follow-up.

Tech Stack: Python 3.14, Pydantic v2, Typer, FastAPI JSON-RPC, pytest, ruff, basedpyright.

---

Scope

This plan intentionally excludes the already-fixed review items:

• CLI config exception tuple syntax in src/wf_cli/context.py
• CLI source-registry file JSON object validation and exception chaining
• RPC method module structure-test coverage
• stale long-lived API and CLI/API alignment doc statuses
• typed tmp_path annotations in tests/wf_config/test_config_models.py

---

Task 1: Document Source-Registry Mutation Asymmetry

Files:

• Modify: docs/superpowers/plans/2026-06-04-source-registry-mutations.md

• Step 1: Add rationale under shadow handling

Find the section mentioning:

A future `allow_shadow` flag can relax add; do not add it in this slice.

Append:

Rationale: `add` rejects config-shadowed ids to prevent silent no-ops: adding a
registry entry that cannot activate while config owns the same id. Existing
shadowed registry entries can still be updated, enabled, disabled, or removed so
operators can prepare store state for config removal or future `seed` ownership
policy.

• Step 2: Verify doc diff

Run:

git diff -- docs/superpowers/plans/2026-06-04-source-registry-mutations.md

Expected: only the rationale paragraph changed.

---

Task 2: Clarify RPC Target Selection Precedence

Files:

• Modify: docs/superpowers/plans/2026-06-03-workflow-config-and-rpc-cli-target.md

• Step 1: Add precedence table near the plan introduction

Add:

### Target Selection Precedence

1. `--url` CLI override selects an RPC HTTP target.
2. `--local` CLI override selects the in-process local target.
3. Config file `client.target` selects the configured target.
4. Missing target config defaults to local.

CLI overrides intentionally win over config so one-off diagnostics can point at
a different server without editing the config file.

• Step 2: Verify no code references are changed

Run:

git diff --stat

Expected: only the plan document is changed by this task.

---

Task 3: Extract Source-Registry RPC Availability Helper

Files:

• Modify: src/wf_transport_rpc_http/methods_source_registry.py

• Test: tests/wf_transport_rpc_http/test_source_registry_rpc.py

• Step 1: Add a helper

In src/wf_transport_rpc_http/methods_source_registry.py, add:

def _require_source_registry_admin(
    server: WorkflowServer,
    *,
    operation: str,
) -> WorkflowSourceRegistrySurface:
    admin = server.source_registry_admin
    if admin is None:
        raise WorkflowRpcError(
            data={
                "code": "source_registry_unavailable",
                "message": (
                    f"source registry admin {operation} are not available "
                    "for this server"
                ),
            }
        )
    return admin

Import WorkflowSourceRegistrySurface from wf_api if needed.

• Step 2: Replace repeated None checks

Use:

admin = _require_source_registry_admin(server, operation="reads")

for list/inspect, and:

admin = _require_source_registry_admin(server, operation="mutations")

for add/update/enable/disable/remove.

• Step 3: Run source-registry RPC tests

Run:

uv run pytest tests/wf_transport_rpc_http/test_source_registry_rpc.py -q

Expected: all tests pass.

---

Task 4: Clarify Chronological Event Ordering

Files:

• Modify: src/wf_api/admin.py

• Test: existing admin API tests if present

• Step 1: Add a comment above list_events

Add a short comment/docstring note near WorkflowAdminApi.list_events:

# Preserve provider order for events; event providers are expected to return
# chronological order and callers may rely on that ordering for diagnostics.

Do not sort event payloads in this task.

• Step 2: Run admin API tests

Run:

uv run pytest tests/wf_api -q

Expected: all wf_api tests pass.

---

Task 5: Record Shared ID Pattern Follow-Up

Files:

• Modify: docs/current_roadmap.md

• Step 1: Add a small platform cleanup bullet

Under the platform cleanup/architecture section, add:

- Cleanup candidate: consolidate store/source registry id validation patterns
  (`SOURCE_REGISTRY_ID_PATTERN`, `STORE_ID_PATTERN`) only after another package
  needs the same rule. Today they intentionally stay close to their stores.

• Step 2: Verify docs only

Run:

git diff -- docs/current_roadmap.md

Expected: only the cleanup bullet changed.

---

Final Verification

Run:

uv run pytest tests/wf_transport_rpc_http/test_source_registry_rpc.py tests/wf_api -q
uv run ruff check src/wf_transport_rpc_http/methods_source_registry.py src/wf_api/admin.py docs/superpowers/plans/2026-06-04-source-registry-mutations.md docs/superpowers/plans/2026-06-03-workflow-config-and-rpc-cli-target.md docs/current_roadmap.md
uv run basedpyright --level error src/wf_transport_rpc_http/methods_source_registry.py src/wf_api/admin.py
git diff --check

Expected: pytest exits 0, ruff exits 0, basedpyright exits 0, and git diff --check reports no whitespace errors.