chore: bump to v0.4.5 — L1 drift wiring fix

[jinhongkuan]

Summary

v0.4.5 fixes the L1 drift wiring bugs that made pending → reflected a no-op for freshly-ingested decisions. Live-verified against Accountable-App-3.0: 8/8 decisions reflected after bulk Slack ingest, vs the prior 27/27 stuck at pending.

Fixes

• Baseline hash stamped at ingest. `ingest_payload` now resolves HEAD from `repo_path` when no `commit_hash` is in the payload and computes a `content_hash` for every grounded region. Initial intent status is derived from the hash via `derive_status` instead of a hardcoded `"pending"`.
• Backfill sweep for legacy ledgers. `handle_link_commit` walks repo-scoped empty-hash regions before the main drift loop and hands them to `HashDriftAnalyzer`, which now self-heals a missing baseline by adopting the current git state as `reflected`. Pre-v0.4.5 ledgers heal opportunistically on the next `bicameral_status` / `link_commit` call — no forced migration.
• Intent status aggregation picks the loudest value across regions (`drifted > reflected > pending > ungrounded`) so a single drifted region always raises an alarm.

Also in this PR

• `docs(readme)`: restructured so Collaboration Modes and Tool Composition land above "How It Works", rewrote Tool Composition around a single running example (Sprint 14 checkout planning → discount rule → drift at PR review), added an ASCII header, dropped CodeGenome from the roadmap, removed the Roadmap section entirely.

Out of scope

CocoIndex-driven re-grounding on delta, AST (L2) and LLM-judge (L3) drift layers, and the single-token BM25 degeneracy guard (FC-1) are all tracked in separate plan files and are not in this PR.

Test plan

• `pytest tests/test_phase1_l1_wiring.py` — 4 new regression cases (ingest→reflected, edit→drifted, phantom range, legacy backfill) all pass
• `pytest tests/test_phase2_ledger.py tests/test_vocab_cache.py tests/test_coverage_loop.py tests/test_phase1_code_locator.py` — 52/52 passing, no regressions
• Live end-to-end: pipx-installed v0.4.5, ran `bicameral_ingest` inside Accountable-App-3.0 against Slack transcripts from `#accountable-tech` + `#accountable-strategy`, got 8/8 reflected / 0 pending (previously was 0/27 reflected)
• Phase 3 integration tests fail identically on `main` and this branch (pre-existing `TeamWriteAdapter._ensure_connected` issue, unrelated to this change)

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes – Version 0.4.5

• New Features

  • Added multi-region status aggregation for improved decision tracking across regions.
  • Introduced automatic baseline stamping at HEAD when commit hash is absent.

• Bug Fixes

  • Fixed self-healing logic for legacy regions with missing content hashes.
  • Improved hash handling during commit and ingest operations.

• Documentation

  • Enhanced collaboration modes guide (Solo vs Team behavior).
  • Expanded tool composition documentation with workflow examples and payloads.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bf7fe4aa-2c8b-4ea2-913a-86cebda28f28

📥 Commits

Reviewing files that changed from the base of the PR and between aae8809 and fe64e91.

📒 Files selected for processing (8)

• CHANGELOG.md
• README.md
• handlers/link_commit.py
• ledger/adapter.py
• ledger/drift.py
• ledger/queries.py
• pyproject.toml
• tests/test_phase1_l1_wiring.py

---

📝 Walkthrough

Walkthrough

Version 0.4.5 adds self-healing for legacy regions with missing content hashes, a new backfill mechanism in the ledger adapter, updated drift analysis to handle absent hashes, per-intent multi-region status aggregation, a new query to locate regions without hashes, and comprehensive regression tests covering the updated ingest and link-commit flows.

Changes

Cohort / File(s)	Summary
Release & Documentation CHANGELOG.md, README.md, pyproject.toml	Version bump to 0.4.5, release notes documenting behavior changes around content-hash handling and self-healing flows, updated README with new Collaboration Modes and Tool Composition sections.
Ledger Self-Healing & Status Aggregation ledger/adapter.py	New async method backfill_empty_hashes() queries regions with missing hashes, runs drift analysis, and persists backfilled hashes with updated intent statuses. Updated ingest_payload() to compute per-region statuses and aggregate them into a single intent status using priority rules (drifted > reflected > pending > ungrounded).
Drift Analysis Self-Healing ledger/drift.py	Added early return in HashDriftAnalyzer.analyze_region when stored_hash is absent: immediately returns reflected status with actual hash and high confidence, bypassing prior flow.
Ledger Query Utility ledger/queries.py	New async function get_regions_without_hash() retrieves code regions with unset or empty content_hash fields, optionally filtered by repository.
Handler Integration handlers/link_commit.py	Added try/except wrapped call to ctx.ledger.backfill_empty_hashes() at start of handle_link_commit, enabling pre-ingest self-healing of legacy regions without aborting on failure.
Regression Tests tests/test_phase1_l1_wiring.py	New pytest module with four end-to-end async tests covering: immediate reflected state on ingest of existing code, drift detection after code edit, phantom ranges never reporting as reflected, and legacy ledger self-healing via link-commit backfill.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant Handler as link_commit Handler
    participant Ledger as SurrealDB Ledger
    participant Analyzer as Drift Analyzer
    participant Query as Query Module

    Client->>Handler: link_commit(ctx, commit_hash)
    activate Handler
    
    alt Backfill phase (new)
        Handler->>Ledger: backfill_empty_hashes(repo_path)
        activate Ledger
        Ledger->>Query: get_regions_without_hash(repo)
        activate Query
        Query-->>Ledger: regions with empty hashes
        deactivate Query
        
        loop for each legacy region
            Ledger->>Analyzer: analyze_region(..., stored_hash="")
            activate Analyzer
            Analyzer-->>Ledger: DriftResult(status="reflected", content_hash=actual)
            deactivate Analyzer
            Ledger->>Ledger: update_region_hash(region_id, actual_hash)
            Ledger->>Ledger: update_intent_status(intent_id, aggregated_status)
        end
        Ledger-->>Handler: {healed_count, failed_count}
        deactivate Ledger
    end
    
    Handler->>Ledger: ingest_commit(payload, commit_hash)
    activate Ledger
    loop for each region in payload
        Ledger->>Analyzer: analyze_region(stored_hash, actual_hash)
        activate Analyzer
        Analyzer-->>Ledger: DriftResult with status
        deactivate Analyzer
        Ledger->>Ledger: persist region_hash & derive status
    end
    Ledger->>Ledger: _aggregate_intent_status(region_statuses)
    Ledger->>Ledger: update_intent_status(intent_id, aggregated_status)
    Ledger-->>Handler: ingestion result with region_ids
    deactivate Ledger
    
    Handler->>Handler: _reground_ungrounded(ctx)
    Handler-->>Client: LinkCommitResponse
    deactivate Handler

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly Related PRs

• refactor: port interfaces + source_span for drift pipeline #1: Modifies the same drift/ledger ingestion pipeline with changes to ledger.drift.analyze_region behavior, ledger/adapter.ingest_payload logic, and handler wiring that work together with this PR's status aggregation and backfill mechanisms.
• fix: ingest pipeline — input contracts, payload normalization, freshness guards #3: The new handle_link_commit backfill self-heal directly complements the upstream wiring that invokes handle_link_commit post-ingest or on status auto-sync, forming an integrated recovery flow.

Poem

🐰 Hashes once lost, now gently found,
Self-healing ledgers spinning 'round,
Intent statuses dance in harmony,
Drift and reflect, in symphony,
Legacy regions rise once more! ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/bump-v0.4.5

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}