Reward Ledger Supabase Persistence and ledger Subcommands
Why
A single review run produces a reward_delta but without persistence there is no accumulated quality signal, no streak awareness, and no trend-over-time visibility. The reward ledger closes this gap: every review run is persisted to Supabase (ai_sync.review_runs, ai_sync.reward_ledger), accumulating coins, streaks, and violation frequency — all queryable for the house_rules auto-updater and for developer motivation.
A local JSON fallback (~/.specfact/ledger.json) ensures the feature works offline or when Supabase is unavailable.
What Changes
- NEW:
ai_sync.review_runs table — stores per-run metadata: session_id, issue_number, agent, changed_files, score, reward_delta, verdict, findings_json, house_rules_ver
- NEW:
ai_sync.reward_ledger table — accumulates coins, streaks, last delta/verdict per agent
- NEW:
LedgerClient — Supabase HTTP primary + ~/.specfact/ledger.json fallback; all public methods decorated with @require/@ensure + @beartype
- NEW:
specfact code review ledger update — reads ReviewReport JSON from stdin (piped from review run --json)
- NEW:
specfact code review ledger status — prints coins (2dp), streak_pass, streak_block, last verdict, top-3 violations
- NEW:
specfact code review ledger reset — resets local ledger (requires --confirm)
- NEW: Coin update formula:
coins += reward_delta / 10.0; streak bonuses: pass>=5 → +0.5, block>=3 → -1.0
- NEW: Supabase DDL migration file:
infra/supabase/review_ledger_ddl.sql
- NEW: Unit tests for
LedgerClient and ledger commands (TDD-first)
Capabilities
New Capabilities
reward-ledger: Supabase-persisted reward ledger with offline JSON fallback, coin accumulation, and streak trackingledger-commands: specfact code review ledger update|status|reset subcommands
Impact
- Depends on
code-review-01-module-scaffold (ReviewReport model)
- Requires Supabase
ai_sync schema access (service role key); degrades gracefully without it
- DDL must not conflict with existing
coding_run_logs / active_runs tables
specfact code review run --json | specfact code review ledger update is the canonical pipe- Documentation: Add ledger commands to
docs/modules/code-review.md; document offline fallback
OpenSpec Change Proposal: code-review-06-reward-ledger
Reward Ledger Supabase Persistence and ledger Subcommands
Why
A single review run produces a
reward_deltabut without persistence there is no accumulated quality signal, no streak awareness, and no trend-over-time visibility. The reward ledger closes this gap: every review run is persisted to Supabase (ai_sync.review_runs,ai_sync.reward_ledger), accumulating coins, streaks, and violation frequency — all queryable for the house_rules auto-updater and for developer motivation.A local JSON fallback (
~/.specfact/ledger.json) ensures the feature works offline or when Supabase is unavailable.What Changes
ai_sync.review_runstable — stores per-run metadata: session_id, issue_number, agent, changed_files, score, reward_delta, verdict, findings_json, house_rules_verai_sync.reward_ledgertable — accumulates coins, streaks, last delta/verdict per agentLedgerClient— Supabase HTTP primary +~/.specfact/ledger.jsonfallback; all public methods decorated with@require/@ensure+@beartypespecfact code review ledger update— readsReviewReportJSON from stdin (piped fromreview run --json)specfact code review ledger status— prints coins (2dp), streak_pass, streak_block, last verdict, top-3 violationsspecfact code review ledger reset— resets local ledger (requires--confirm)coins += reward_delta / 10.0; streak bonuses: pass>=5 → +0.5, block>=3 → -1.0infra/supabase/review_ledger_ddl.sqlLedgerClientand ledger commands (TDD-first)Capabilities
New Capabilities
reward-ledger: Supabase-persisted reward ledger with offline JSON fallback, coin accumulation, and streak trackingledger-commands:specfact code review ledger update|status|resetsubcommandsImpact
code-review-01-module-scaffold(ReviewReportmodel)ai_syncschema access (service role key); degrades gracefully without itcoding_run_logs/active_runstablesspecfact code review run --json | specfact code review ledger updateis the canonical pipedocs/modules/code-review.md; document offline fallbackOpenSpec Change Proposal:
code-review-06-reward-ledger