feat: v0.5.1 — spec-gap wedge cuts + bicameral.history

[jinhongkuan]

Summary

• Surface cuts: removed 6 skill dirs and 5 MCP tool registrations (status, search, brief, scan_branch, doctor). Underlying handlers stay as internal plumbing called by preflight/ingest.
• Absorbed contracts: brief presentation rules folded into bicameral-ingest/SKILL.md step 5; guided-mode contract folded into bicameral-preflight/SKILL.md steps 6–7.
• New tool: bicameral.history — read-only ledger dump grouped by feature_group, in the balance-sheet shape (HistoryDecision with sources[], fulfillment, drift_evidence). 11 tests, all passing.
• Feature grouping: feature_group field added to ingest payload + decision table. agent_session source type added. Step 1.5 in ingest SKILL.md covers the stop-and-ask grouping contract.
• Test updates: stale post-v0.5.0 tests updated (intent_id → decision_id, compliant → verdict, schema v3 → v4, intent table → decision table).

Test plan

• test_v0420_history.py — 11 tests green
• test_phase3_integration.py — 7 tests green
• test_v048_ingest_brief_chain.py — 12 tests green
• test_resolve_compliance.py — 10 tests green
• test_compliance_check_schema.py — all green (updated)
• test_v0417_jargon_hygiene.py — green (bicameral-ingest exempted from BM25 term)

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes v0.5.1

• New Features

  • Added bicameral.history tool for viewing the complete decision ledger with optional filtering by feature name and historical snapshots via git references.

• Changes

  • Removed bicameral.status, bicameral.search, bicameral.brief, bicameral.scan_branch, and bicameral.doctor tools.
  • Added feature_group field to organize and track decisions by feature.
  • Extended source_type to include agent_session for decision origin tracking.

• Documentation

  • Updated guidance for ingest workflow and preflight checks.
  • Removed documentation for deprecated tools and features.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2d81c7c2-7de5-4b64-a418-da9b05e46360

📥 Commits

Reviewing files that changed from the base of the PR and between 630539f and c9a0c59.

📒 Files selected for processing (28)

• contracts.py
• handlers/brief.py
• handlers/doctor.py
• handlers/history.py
• handlers/ingest.py
• handlers/scan_branch.py
• ledger/adapter.py
• ledger/queries.py
• ledger/schema.py
• pyproject.toml
• server.py
• skills/bicameral-brief/SKILL.md
• skills/bicameral-doctor/SKILL.md
• skills/bicameral-guided/SKILL.md
• skills/bicameral-history/SKILL.md
• skills/bicameral-ingest/SKILL.md
• skills/bicameral-preflight/SKILL.md
• skills/bicameral-scan-branch/SKILL.md
• skills/bicameral-search/SKILL.md
• skills/bicameral-status/SKILL.md
• tests/test_compliance_check_schema.py
• tests/test_extract_headless.py
• tests/test_phase1_l1_wiring.py
• tests/test_v0411_latent_drift.py
• tests/test_v0417_jargon_hygiene.py
• tests/test_v0417_scan_branch.py
• tests/test_v0418_doctor.py
• tests/test_v0420_history.py

---

📝 Walkthrough

Walkthrough

This PR refactors the MCP tool architecture by removing five tools (scan_branch, doctor, status, search, brief) and introducing a new read-only bicameral.history tool. It extends ingest contracts and ledger storage to support a feature_group field for decision categorization, adds comprehensive history response contracts (HistorySource, HistoryDecision, HistoryFeature, HistoryResponse), and updates skill documentation accordingly.

Changes

Cohort / File(s)	Summary
Ingest Contracts & History Types contracts.py	Extended IngestMapping and IngestDecision with optional feature_group field; added agent_session to accepted source_type enums; introduced new history tool contracts: HistorySource, HistoryFulfillment, HistoryDecision (with statuses: reflected|drifted|ungrounded|superseded|discovered), HistoryFeature, and HistoryResponse.
Ledger Data Layer ledger/schema.py, ledger/queries.py, ledger/adapter.py	Added optional feature_group field to decision table schema; updated upsert_decision to accept and conditionally persist feature_group; updated ingest_payload in adapter to read and pass feature_group through decision creation.
Handler: History (New) handlers/history.py	Added new handle_history async function with decision enrichment, source reconstruction, status normalization, feature grouping (via feature_group/source_ref/default), feature filtering, and truncation (max 50 features); groups decisions by feature with priority for v0.5.1\+ feature_group field.
Handler: Ingest (Updated) handlers/ingest.py	Updated _normalize_payload to use fallback span text (d.source_excerpt or text); added conditional feature_group mapping output when present.
Removed Handlers handlers/doctor.py, handlers/scan_branch.py	Deleted handle_doctor (file vs branch vs empty scope detection with ledger summary); deleted handle_scan_branch (file-range scanning with deduplication and action hints).
Handler: Brief (Documentation Update) handlers/brief.py	Updated module docstring to reflect internal use by handle_ingest and handle_preflight, not direct MCP registration.
Server Tool Registration server.py	Removed MCP tool definitions and dispatch branches for bicameral.status, bicameral.search, bicameral.brief, bicameral.scan_branch, and bicameral.doctor; added new bicameral.history tool with parameters feature_filter, include_superseded, as_of.
Skill Documentation: Removals skills/bicameral-status/SKILL.md, skills/bicameral-search/SKILL.md, skills/bicameral-brief/SKILL.md, skills/bicameral-scan-branch/SKILL.md, skills/bicameral-doctor/SKILL.md, skills/bicameral-guided/SKILL.md	Deleted documentation for six deprecated/refactored skills and guided-mode behavior specifications.
Skill Documentation: New & Updated skills/bicameral-history/SKILL.md, skills/bicameral-ingest/SKILL.md, skills/bicameral-preflight/SKILL.md	Added comprehensive history skill documentation (trigger conditions, tool interface, presentation format, truncation); updated ingest to include feature-group assignment step and auto-brief presentation with buckets/formatting; updated preflight with mode-specific blocking-hint handling and ledger capture on resolution.
Package Version pyproject.toml	Bumped version from 0.5.0 to 0.5.1.
Tests: History (New) tests/test_v0420_history.py	Added comprehensive Phase 2 async test suite for handle_history with in-memory ledger, covering empty ledger, deduplication, grounding/ungrounded decisions, source-type preservation, feature grouping, truncation at 50 features, filtering, and response structure validation.
Tests: Removed tests/test_v0417_scan_branch.py, tests/test_v0418_doctor.py	Deleted full regression test suites for scan_branch (deduplication, status aggregation, range handling) and doctor (action-hint composition, control flow, scope detection).
Tests: Updated tests/test_compliance_check_schema.py, tests/test_extract_headless.py, tests/test_phase1_l1_wiring.py, tests/test_v0411_latent_drift.py, tests/test_v0417_jargon_hygiene.py	Updated schema version assertions (v3→v4); changed cache-key semantics (intent_id→decision_id); replaced compliant boolean with verdict enum; adjusted excerpt size thresholds; updated table/column queries to reference decision instead of intent; added allowlist for retrieval terms in ingest skill.

Sequence Diagram

sequenceDiagram
    participant Client as Client/Agent
    participant Server as Server
    participant Ledger as Ledger
    participant Handler as history Handler
    
    Client->>Server: call_tool("bicameral.history",<br/>feature_filter?, include_superseded?, as_of?)
    Server->>Handler: handle_history(ctx, feature_filter, include_superseded, as_of)
    
    Handler->>Ledger: _fetch_all_decisions_enriched()<br/>(with source_span reconstruction)
    Ledger-->>Handler: enriched decisions + sources + fulfillment
    
    Handler->>Handler: _normalize_source_type()<br/>for each decision
    Handler->>Handler: _decision_status_for_history()<br/>(map internal→history status)
    Handler->>Handler: _row_to_history_decision()<br/>convert to HistoryDecision objects
    
    Handler->>Handler: _feature_key_for_row()<br/>group by feature_group/source_ref/default
    Handler->>Handler: aggregate HistoryDecision[]<br/>into HistoryFeature containers
    
    Handler->>Handler: _priority_for_feature()<br/>sort (drifted/ungrounded first)
    Handler->>Handler: apply feature_filter<br/>(substring match, case-insensitive)
    Handler->>Handler: optionally exclude superseded
    Handler->>Handler: truncate to max 50 features<br/>(set truncated flag)
    
    Handler->>Handler: resolve_head(repo_path)→as_of
    Handler->>Server: return HistoryResponse<br/>(features[], truncated, total_features, as_of)
    Server-->>Client: HistoryResponse JSON

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• PR #35: Extends v0.5.0 decision-tier refactor—both PRs change contracts (IngestMapping/IngestDecision), ledger schema/queries for decision attributes, ingest adapter flow, and server tool wiring.
• PR #33: Both PRs touch ingest contracts and normalization pipeline—each adds a new field to IngestMapping/IngestDecision and updates handlers/ingest._normalize_payload to propagate it through decision persistence.
• PR #10: Both PRs modify ledger/adapter.py's ingest_payload behavior and decision/status persistence, extending ingest flow to carry new decision attributes.

Poem

🐰 Hops of joy, the ledger's bright,
Feature groups now organize our sight,
History flows from root to peak,
Old tools rest—new tools seek.
Fifty features dance in truncated grace, ✨
The decision ledger finds its place!

✨ 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 jin/v0.5.0-decision-tier

---

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.}