@balpal4495/quorum 0.4.2 → 2.0.0

package/README.md

@@ -1,40 +1,200 @@
 # Quorum
 
-**Quorum gives your AI coding assistant memory and judgment.**
+**Git-backed memory and design review for AI coding agents.**
 
-When Claude Code, Copilot, or Cursor works in your codebase, it forgets everything between sessions. It retries approaches that already failed. It contradicts decisions made last week. It has no idea what the team has already learned.
+Your agent knows how to code. It does not know what your team decided last week.
 
-Quorum fixes this. It installs a persistent knowledge store into your project and gives your AI a structured workflow for querying it before proposing solutions, validating designs before acting, and writing new knowledge back — with you approving every write.
+Quorum gives Claude Code, Cursor, Codex, Copilot, and other coding agents a project memory they check before proposing changes — and only humans approve what gets remembered.
+
+```bash
+npx @balpal4495/quorum@latest init
+```
+
+This creates `.chronicle/`, adds agent instructions to `CLAUDE.md`, `AGENTS.md`, and `.github/copilot-instructions.md`, and gives every future AI session access to the project's approved memory.
+
+---
+
+## The problem
+
+AI coding agents forget:
+
+- decisions made in prior sessions
+- approaches that already failed and why
+- which parts of the codebase are risky
+- team-specific architecture rules
+- why something was rejected
+
+Every new session starts from zero. The same mistakes get proposed again. The same rejected patterns get rediscovered.
+
+---
+
+## What changes after Quorum
+
+**Without Quorum:**
+
+> "I'll replace sessions with HS256 JWTs."
+
+**With Quorum:**
+
+> "I checked Chronicle first. HS256 was rejected in March — key rotation would invalidate all active sessions. The validated approach is RS256 with short-lived access tokens and refresh rotation in httpOnly cookies."
+
+The agent didn't discover this through code archaeology. Chronicle told it. That knowledge was approved by a human and has been there for every session since.
+
+---
+
+## Three guarantees
+
+### 1. It remembers
+
+Every session starts from approved project knowledge, not a blank chat window. Decisions, rejected approaches, risky areas, and architectural rules — all available before the first line of code is written.
+
+### 2. It checks
+
+Risky proposals are compared against Chronicle evidence before they reach you. Refuted approaches are hard stops. Missing rollback plans and undocumented risks are surfaced before implementation.
+
+### 3. It learns under human control
+
+The agent can stage new lessons. Only you decide what becomes project memory. Nothing is indexed without your sign-off.
+
+---
+
+## Where Quorum fits
+
+Quorum does not replace your coding-agent workflow.
+
+Use Superpowers, Claude Code, Cursor rules, Codex instructions, or your own process for planning and implementation. Quorum adds the missing memory and evidence layer underneath them.
+
+```
+Agent workflow:
+  brainstorm → design → plan → implement → review → merge
+
+Quorum layer:
+  remember → check evidence → flag risk → stage learning → human approval
+```
+
+> **Your agent already has a workflow. Quorum gives it institutional memory.**
+
+### Using Quorum with Superpowers
+
+| Superpowers phase | Quorum hook |
+|---|---|
+| Brainstorming | `quorum advisor brief` and `quorum advisor query "topic"` before proposing options |
+| Writing the design | Chronicle entries as evidence for accepted and rejected approaches |
+| Planning | `quorum check` on the proposed design before implementation |
+| TDD / implementation | Stage meaningful decisions as Chronicle proposals |
+| Code review | Check whether the change contradicts validated entries |
+| Finish branch | `quorum commit --list`, approve learnings, then `quorum growth` |
+
+---
+
+## The Quorum loop
+
+```
+1. Start with memory
+   quorum advisor brief
+   quorum advisor query "authentication"
+
+2. Check the design
+   quorum check --outcome "migrate auth" --design "..."
+
+3. Stage what was learned
+   The agent proposes a Chronicle entry.
+
+4. Approve memory
+   quorum commit --list
+   quorum commit <id>
+
+5. Keep memory healthy
+   quorum growth
+   quorum evolve
+```
+
+Every PR merge posts a growth comment showing what Chronicle learned. `quorum evolve` periodically consolidates entries and resolves contradictions.
 
 ---
 
-## Get started in one command
+## What you can do
+
+| Job | Command |
+|---|---|
+| Ask what the project already knows | `quorum advisor "what did we decide about auth?"` |
+| Search memory without an LLM | `quorum advisor query "auth"` |
+| Start a session with full context | `quorum advisor brief` |
+| Check a design before coding | `quorum check --outcome ... --design ...` |
+| Approve what the agent should remember | `quorum commit <id>` |
+| See whether memory is growing | `quorum growth` |
+| Consolidate stale or duplicate entries | `quorum evolve` |
+| Find undocumented areas | `quorum sentinel coverage` |
+
+---
+
+## Start small, then add guardrails
+
+### Level 1 — Local memory
+Use `quorum advisor brief` and `quorum advisor query` at the start of AI sessions. No setup beyond `init`.
+
+### Level 2 — Human-approved learning
+Let the agent stage proposals. Approve them with `quorum commit`. Chronicle grows.
+
+### Level 3 — Design checks
+Run `quorum check` before risky changes. Auth, database, payments, PII, crypto — each gets a deterministic preflight and risk level.
+
+### Level 4 — Team memory in Git
+Commit `.chronicle/committed/` so every teammate and every new AI session starts with the same accumulated knowledge.
+
+### Level 5 — CI and PR visibility
+Enable the GitHub Actions workflows for automatic PR growth comments, coverage reports, and drift checks.
+
+---
 
-Run this from your project root:
+## Get started
 
 ```bash
 npx @balpal4495/quorum@latest init
+npm install
 ```
 
-Then run `npm install`.
+Then install the CLI globally for terminal access:
 
-That's the whole setup. Quorum copies its modules into `quorum/`, merges instruction files for your AI (`CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`), and creates the Chronicle knowledge store at `.chronicle/`.
+```bash
+npm install -g @balpal4495/quorum
+```
 
 ---
 
-## CLI commands
+## Command reference
 
-After `npm install -g @balpal4495/quorum` (or `npx @balpal4495/quorum`), you get:
+### `quorum advisor` — ask Chronicle a question
 
-| Command | What it does | LLM? |
-|---|---|---|
-| `quorum init` | Scaffold Quorum into a project | No |
-| `quorum status` | Chronicle health — pending proposals, committed entries, recent activity | No |
-| `quorum check --outcome X --design Y` | Deterministic preflight + risk classifier | No |
-| `quorum commit <id>` | Approve and index a pending proposal | No |
-| `quorum sentinel [coverage]` | Chronicle coverage of your source files | No |
+```bash
+quorum advisor "what did we decide about authentication?"
+quorum advisor query "session handling"   # keyword search, no LLM
+quorum advisor brief                      # full Chronicle summary, no LLM
+```
 
-### `quorum check` — instant risk triage before the full pipeline
+```
+Question: what did we decide about authentication?
+
+  What we know
+  The team settled on RS256 JWT after rejecting HS256 — key rotation without
+  invalidating active sessions was the blocker. Tokens are 15-min expiry with
+  refresh rotation in httpOnly cookies.
+
+  Recommendation
+  Follow the RS256 pattern. Entry [abc-123] is validated at 0.91 confidence.
+
+  Risks
+  · OAuth migration is planned for Q3 — coordinate before adding new auth surfaces
+
+  Next step
+  quorum advisor query "oauth migration" to check current status
+```
+
+No LLM required for `query` and `brief`. When an LLM is available, `advisor` synthesises and validates answers internally — retrying up to 2 times if confidence is below 0.7. When running inside Claude Code, Copilot, or Codex with no separate API key, it outputs Chronicle evidence and a synthesis request for the agent to answer inline.
+
+---
+
+### `quorum check` — instant risk triage
 
 ```bash
 quorum check \
@@ -57,117 +217,117 @@ Risk
   ⚠  Critical risk — human architecture review required before proceeding.
 ```
 
-Exit codes: `0` = low/medium, `1` = high, `2` = critical — pipe into CI scripts directly.
-Also accepts JSON on stdin: `echo '{"outcome":"…","design":"…"}' | quorum check --json`
+Exit codes: `0` = low/medium, `1` = high, `2` = critical — pipe directly into CI scripts.
+Accepts JSON on stdin: `echo '{"outcome":"…","design":"…"}' | quorum check --json`
 
-### `quorum status` — see what's pending and what's been learned
+---
 
-```bash
-quorum status
-```
+### `quorum commit` — the human gate
 
+```bash
+quorum commit --list                    # see all pending proposals
+quorum commit a1b2c3d4                  # approve and index (partial ID works)
+quorum commit a1b2c3d4 --dry-run        # preview without writing
 ```
-Chronicle status  .chronicle/
-
-     8  committed entries  (6 accepted, 1 refuted, 1 other)
-     2  pending proposals
 
-Pending proposals  (awaiting quorum commit <id>)
-  a1b2c3d4  JWT key rotation approach needs RS256 not HS256
-            oracle/propose.ts, modules/auth/
+Writes to `.chronicle/committed/`, updates `SUMMARY.md`, removes the proposal. Always works — no extra dependencies required. Install `@xenova/transformers` and `vectordb` to also embed entries for semantic search.
 
-Recent entries
-  e5f6a7b8  [accepted]  Shadow column migration avoids exclusive lock on 50M rows  2d ago
 ```
-
-### `quorum commit <id>` — the human gate from your terminal
-
-```bash
-quorum commit --list        # see pending proposals with full detail
-quorum commit a1b2c3d4      # approve and index (supports partial ID prefix)
-quorum commit a1b2c3d4 --dry-run  # preview without writing
+.chronicle/
+  proposals/    ← AI-staged entries waiting for your approval
+  committed/    ← approved entries, indexed and searchable
+  SUMMARY.md    ← auto-generated context for your AI to read
 ```
 
-Embeds the entry via the local ONNX model, upserts to LanceDB, writes to `.chronicle/committed/`, updates `SUMMARY.md`, and removes the proposal — the full oracle commit in one command. Requires `@xenova/transformers` and `vectordb` to be installed (both are optional deps from `quorum init`).
+---
 
-### `quorum sentinel coverage` — see where Chronicle goes dark
+### `quorum growth` — is Chronicle actually learning?
 
 ```bash
-quorum sentinel coverage --path modules
+quorum growth
+quorum growth --json   # machine-readable, for CI
 ```
 
 ```
-Chronicle coverage  modules/
-
-  ████░░░░░░░░░░░░░░░░  20%  (6/30 files)
-
-Covered
-  ✓  oracle/propose.ts  (3 entries)
-  ✓  oracle/query.ts    (1 entry)
-
-Uncovered  (no Chronicle entries reference these files)
-  ✗  council/chairman.ts
-  ✗  jury/evaluate.ts
-  …
+Chronicle growth
+
+  Status        THRIVING
+  Total entries 17
+  Last 7 days   6 commits
+  Last 30 days  17 commits
+  Last commit   0 days ago  2026-05-16
+  Pending       2 proposals awaiting quorum commit
+
+  Weekly commits
+    w/c 2026-05-11  ▪▪▪▪▪▪  6
+    w/c 2026-05-04  ▪▪▪▪▪▪▪▪▪▪▪  11
+
+  Recent learnings
+    bf448871  Low-risk designs skip Council entirely — Jury alone is sufficient…  2026-05-16
+    3efb1789  Advisor validates answers before returning — retries up to 2 times…  2026-05-16
+    090c7dc6  Advisor is a read-only path — never calls oracle.propose()…         2026-05-16
+    e57c30d5  Releases trigger from PR labels, not manual tag pushes…             2026-05-16
 ```
 
----
+Status levels: `EMPTY` → `STALLED` (14 days) → `SLOW` (7 days) → `HEALTHY` → `THRIVING` (3+ this week). When stalled, it tells you what to do.
 
-## Then just talk to your AI
+---
 
-Once initialized, open your AI in agent mode and tell it:
+### `quorum evolve` — Chronicle self-improvement
 
-> "Follow quorum/SETUP.md"
+```bash
+quorum evolve             # analyse and stage improvement proposals
+quorum evolve --dry-run   # preview without writing
+```
 
-Your AI reads the instruction files, wires the modules into your project's entry point, runs the tests, and reports what it did. From that point it operates under Quorum — querying Chronicle before every proposal, running designs through Jury and Council, and staging entries for your approval.
+```
+Quorum evolve  17 entries · via Anthropic
 
-**Works with:**
-- Claude Code (`claude` CLI or VS Code extension)
-- GitHub Copilot (agent mode)
-- Cursor
-- Any other AI that can read files and run terminal commands
+  ✓  Analysis complete
 
----
+  2 improvements found
 
-## What changes after setup
+  ✓  consolidate  10b848a2 + d93b6f40
+     Both entries describe Mermaid rendering failures — distinct symptoms, same root cause
+     → Mermaid diagrams have three known failure modes in GitHub PR descriptions…
 
-### Your AI now has a memory
+  ✓  promote      55278b3d → validated (0.88)
+     Confirmed by three subsequent entries referencing SUMMARY.md temporal context
 
-Before proposing anything, your AI queries Chronicle — the project's knowledge store. If a similar approach was tried and rejected, it knows. If a design decision was made last month, it knows.
+  2 proposals staged — run quorum commit --list to review
+```
 
-> *"I queried Chronicle before proposing the Redis session approach. Entry `[abc-123]` shows we rejected this in March — key rotation wasn't viable. I'm proposing JWT with RS256 instead."*
+Three improvement types:
 
-### Your AI validates designs before acting
+- **consolidate** — two entries covering the same ground → one sharper entry with `supersedes`
+- **resolve** — a validated entry contradicted by a newer one → mark it `refuted`
+- **promote** — an `open` entry confirmed by later entries → elevate to `validated`
 
-Every proposal goes through Jury (confidence scoring against evidence) and Council (adversarial panel review) before it reaches you. Low-confidence or contested ideas get challenged internally first.
+Every proposed improvement goes through the human gate (`quorum commit`). Nothing is auto-committed.
 
-> *"Jury scored this 0.41 — gaps in lock strategy and rollback plan. Council flagged the same issue. I've revised the migration plan to use a shadow column approach before bringing it to you."*
+---
 
-### You approve what gets remembered
+### Every merged PR shows what Chronicle learned
 
-When a decision is made, your AI stages a Chronicle entry using `oracle.propose()`. You approve it from the terminal:
+On every PR merge, Quorum automatically posts a growth comment:
 
-```bash
-quorum commit --list        # see what's pending
-quorum commit <id>          # approve and index
 ```
+## Quorum Chronicle — what this PR taught
 
-Nothing is indexed without your explicit sign-off.
-
-```
-.chronicle/
-  proposals/    ← AI-staged entries waiting for your approval
-  committed/    ← approved entries, indexed and searchable
-  SUMMARY.md    ← auto-generated weekly context for your AI to read
-```
+Chronicle grew from 14 → 17 entries
 
-Commit `.chronicle/committed/` to git. Future sessions — and your teammates' sessions — start with that context.
+Committed this PR:
+  ✅ [bf448871]  Low-risk designs skip Council entirely — jury-only, 0 LLM calls
+  ✅ [3efb1789]  Advisor validates answers before returning — retries up to 2 times
+  ✅ [090c7dc6]  Advisor is a read-only path — never calls oracle.propose()
 
-### Every merged PR can create a Chronicle proposal automatically
+2 proposals pending — run quorum commit --list to review.
 
-Quorum ships a GitHub Actions workflow (`chronicle-on-merge.yml`) that fires when any PR merges to main. It creates a Chronicle proposal capturing the decision, which files changed, and any explicitly deferred items from the PR description. The proposal sits in `proposals/` until you commit it — nothing is auto-indexed.
+---
+Run quorum growth for full Chronicle health · quorum evolve to consolidate entries
+```
 
-To enable this in your project, copy `.github/workflows/chronicle-on-merge.yml` and `scripts/chronicle-pr.js` from the [Quorum repo](https://github.com/balpal4495/Quorum) into your own repo.
+Enable by copying `.github/workflows/` from the [Quorum repo](https://github.com/balpal4495/Quorum). `sentinel-pr.yml` also posts a coverage table on every PR showing which files Chronicle knows about and which are blind spots.
 
 ---
 
@@ -175,15 +335,15 @@ To enable this in your project, copy `.github/workflows/chronicle-on-merge.yml`
 
 ### An agent that remembers a past failure
 
-Your AI is about to propose symmetric JWT signing. Oracle returns:
+Your AI is about to propose symmetric JWT signing. Chronicle returns:
 
 ```
 [abc-123] Tried HS256 JWT in March. Rejected — no way to rotate keys without
           invalidating all active sessions. Decision: RS256 with short-lived tokens.
-          status: committed · confidence: 0.91
+          status: validated · confidence: 0.91
 ```
 
-Jury flags it as a direct conflict. The agent revises before Council even sees it.
+Jury flags it as a direct conflict. The agent revises before it ever reaches you.
 
 ---
 
@@ -192,16 +352,16 @@ Jury flags it as a direct conflict. The agent revises before Council even sees i
 Day one of a new Claude Code session. Before touching anything:
 
 ```
-> query Chronicle for: authentication, session handling, token strategy
+quorum advisor query "authentication, session handling, token strategy"
 
   6 entries found:
-  - HS256 rejected (key rotation problem) → use RS256
-  - Redis sessions tried and removed (memory overhead at scale)
-  - Current approach: RS256 JWT, 15-min expiry, refresh rotation in httpOnly cookies
-  - Upcoming: OAuth migration planned for Q3
+  · HS256 rejected (key rotation problem) → use RS256
+  · Redis sessions tried and removed (memory overhead at scale)
+  · Current: RS256 JWT, 15-min expiry, refresh rotation in httpOnly cookies
+  · Upcoming: OAuth migration planned for Q3
 ```
 
-The AI works with full project context from the first message — no archaeology through git history.
+Full project context from the first message — no archaeology through git history.
 
 ---
 
@@ -215,24 +375,7 @@ gaps: ["no lock strategy documented", "no rollback plan"]
 council_brief: challenge
 ```
 
-Council's Chairman gives a structured verdict:
-
-```json
-{
-  "satisfied": false,
-  "blockers": [
-    {
-      "issue": "Naive ALTER TABLE takes an exclusive lock for minutes on a 50M-row table",
-      "evidence": ["db-017"],
-      "required_fix": "Use shadow column pattern or pg_repack. Add rollback path."
-    }
-  ],
-  "warnings": [],
-  "advisor_split": { "proceed": 0, "redesign": 4, "investigate-more": 1 }
-}
-```
-
-The agent revises the plan. You approve the Chronicle entry once it's solid. The reasoning — including alternatives considered and why they were rejected — is on record for the next time someone touches that table:
+Council gives a structured verdict with blockers. The agent revises. You approve the Chronicle entry once it's solid:
 
 ```json
 {
@@ -240,171 +383,122 @@ The agent revises the plan. You approve the Chronicle entry once it's solid. The
   "alternatives_considered": ["naive ALTER TABLE", "pg_repack"],
   "rejected_reason": ["ALTER TABLE takes exclusive lock for minutes on 50M rows"],
   "scope": ["database", "migrations"],
-  "affected_areas": ["db/migrations/", "src/models/user.ts"],
-  "validation_plan": ["Confirm 100% backfill before applying NOT NULL constraint", "Test rollback path on staging"],
+  "validation_plan": ["Confirm 100% backfill before applying NOT NULL constraint"],
   "review_after": "2026-08-01"
 }
 ```
 
+The next person touching that table has the full reasoning. They don't repeat the mistake.
+
 ---
 
-## What's inside
+## How it works under the hood
 
-Four portable TypeScript modules installed into `quorum/modules/`:
+You do not need to understand these internals to use Quorum. They are installed into `quorum/modules/` so any AI working in the codebase can inspect and use them directly.
 
-| Module | What it does |
-|---|---|
-| **Oracle** | Query and write interface to Chronicle. No LLM required. |
-| **Jury** | Evaluates a proposed design against Chronicle evidence. Returns a decomposed confidence score and hard-blocker gaps. |
-| **Council** | A panel of advisors challenges the design independently, reviewers critique anonymously, a Chairman gives a structured verdict with blockers and warnings. |
-| **Sentinel** | Shows which files the AI knows nothing about, flags stale knowledge, and posts a coverage map on every PR. |
+| Module | What it does | LLM |
+|---|---|---|
+| **Advisor** | Plain-language interface to Chronicle. Ask a question, get an answer synthesised from evidence, validated with an internal retry loop. | Auto |
+| **Oracle** | Query and write interface to Chronicle. Two-pass retrieval (vector + BM25). | No |
+| **Jury** | Evaluates a design against Chronicle evidence. Four-dimension confidence score, deterministic preflight, hard-blocker gaps. | Yes |
+| **Council** | Adversarial panel — advisors challenge independently, reviewers critique anonymously, Chairman gives a structured verdict. Risk-scaled fan-out. | Yes |
+| **Sentinel** | Coverage reporting (which files Chronicle knows about), drift detection (are entries still accurate), PR coverage maps. | Optional |
 
-The modules live in your repo — readable by any AI working in the codebase. Nothing is hidden in `node_modules`.
+### How Jury works
 
----
+Before calling the LLM, Jury runs a **deterministic preflight** — checks sensitive areas (auth, database migrations, crypto, payments, PII, secrets), rollback strategy, and refuted Chronicle conflicts. These are injected as hard ground truth.
 
-## How Jury works
+The LLM scores across four dimensions: evidence support, feasibility, risk, completeness. Confidence is the exact average — the LLM's stated value is discarded. Jury separates `blocking_gaps` (must resolve) from `gaps` (useful but not blocking).
 
-Before calling the LLM, Jury runs a **deterministic preflight** — no LLM required — that checks whether the design touches sensitive areas (auth, database migrations, crypto, payments, PII, secrets), mentions a rollback strategy, and whether any refuted Chronicle entries conflict with the design. These facts are injected into the Jury prompt as hard ground truth.
+### How Council works
 
-The LLM then scores the design across four dimensions:
+A risk classifier scales the panel before it runs:
 
-| Dimension | What it measures |
-|---|---|
-| Evidence support | Do validated Chronicle entries confirm this approach works here? |
-| Feasibility | Do Chronicle entries suggest this is achievable? |
-| Risk | How well does the design address known failure modes? |
-| Completeness | Does the design cover the full outcome? |
+| Risk | Triggers | Council mode | LLM calls |
+|---|---|---|---|
+| Low | Nothing sensitive | jury-only — Council skipped | 0 |
+| Medium | Cache, queues, deployments | lite — 1 advisor + 2 reviewers | 5 |
+| High | DB migrations, PII, permissions | full — 5 advisors + 5 reviewers | 12 |
+| Critical | Auth, payments, crypto, data deletion | full + human flag | 12 |
+
+Refuted entries always elevate risk by at least one level. Citation validation strips hallucinated Oracle IDs before any proposal is written.
+
+### LLM auto-detection
 
-Confidence is recomputed as the exact average of those four scores — the LLM's stated confidence is discarded. Jury also separates `blocking_gaps` (must resolve before proceeding) from `gaps` (useful but not critical).
+Quorum finds whichever LLM is available: `ANTHROPIC_API_KEY` → `OPENAI_API_KEY` → `GEMINI_API_KEY` → `OPENAI_BASE_URL` → Ollama at `localhost:11434` → authenticated `gemini` CLI. When running inside an AI agent with no separate key, commands output Chronicle evidence and a synthesis request — the agent answers inline.
 
 ---
 
-## How Council works
+## For custom agent pipelines
 
-Before running the full panel, a **risk classifier** reads the design text and Chronicle evidence and assigns a risk level:
+```typescript
+import { setup } from "@balpal4495/quorum"
 
-| Risk | Council mode | LLM calls |
-|---|---|---|
-| Low | 1 advisor + 1 reviewer | 4 |
-| Medium | 1 advisor + 2 reviewers | 5 |
-| High | 5 advisors + 5 reviewers | 12 |
-| Critical | 5 advisors + 5 reviewers (+ human architecture flag) | 12 |
+const { oracle, evaluate, deliberate, ask } = await setup({ llm: myLLMProvider })
 
-Auth, crypto, payments, and data deletion trigger Critical. Database migrations, PII, permissions trigger High. Cache, queues, deployments trigger Medium. Everything else is Low.
+// Ask a plain-language question
+const answer = await ask("what did the team decide about authentication?")
 
-The Chairman's verdict is **structured**:
+// Full evaluation pipeline
+const evidence = await oracle.query("authentication patterns")
+const jury     = await evaluate({ outcome, design, evidence })
+const verdict  = await deliberate({ outcome, design, evidence, jury_output: jury })
+```
 
-```json
-{
-  "blockers": [
-    {
-      "issue": "No rollback plan for destructive migration",
-      "evidence": ["db-017"],
-      "required_fix": "Add shadow-column migration and rollback path before execution"
-    }
-  ],
-  "warnings": [
-    {
-      "issue": "No integration test for token expiry edge case",
-      "suggested_fix": "Add test covering token rotation during concurrent requests"
-    }
-  ],
-  "advisor_split": { "proceed": 2, "redesign": 2, "investigate-more": 1 }
+```typescript
+// Wire any LLM provider
+const llm: LLMProvider = async (messages, model = "claude-3-5-sonnet-20241022") => {
+  const res = await anthropic.messages.create({ model, messages, max_tokens: 2048 })
+  return res.content[0].type === "text" ? res.content[0].text : ""
 }
 ```
 
-Blockers must be resolved before the human gate. Warnings can be ticketed. High `advisor_split` disagreement is surfaced explicitly — it means genuine uncertainty, not a safe proceed.
-
-Every Oracle ID cited in the verdict is also validated against the evidence pack that was actually sent. Hallucinated citations are flagged in `citation_validation.hallucinated_ids` and stripped from the Chronicle proposal.
+Full API reference: [modules/README.md](modules/README.md)
 
 ---
 
 ## Eval suite
 
-`evals/` contains canonical test cases — known-bad proposals that Council should block and known-good ones it should pass:
+`evals/` contains canonical test cases — known-bad proposals that should block, known-good ones that should pass:
 
-| Case | Expected outcome |
+| Case | Expected |
 |---|---|
 | Naive NOT NULL migration on large table | Block — no lock strategy |
-| HS256 JWT when RS256 was already chosen | Block — cites refuted entry auth-022 |
+| HS256 JWT when RS256 was already chosen | Block — cites refuted entry |
 | PII fields logged to stdout | Block — GDPR violation in evidence |
 | Payment charge without idempotency key | Block — duplicate charge risk |
-| Redis sessions (previously removed) | Block — memory overhead already documented |
-| Cache without stampede protection | Block — prior incident in Chronicle |
 | Safe internal rename | Proceed — low risk, no conflicts |
-| RS256 JWT (approved pattern) | Proceed — matches validated Chronicle entry |
+| RS256 JWT (approved pattern) | Proceed — matches validated entry |
 | Migration with rollback + shadow column | Proceed — addresses documented failure mode |
-| Novel WebSocket design, no evidence | Investigate-more — no Chronicle evidence either way |
-
-Deterministic assertions (preflight, risk classifier) run on every CI pass. LLM-dependent assertions (confidence bounds, Council recommendation) activate with `EVAL_LLM=1`.
 
 ```bash
 npx vitest run evals/
 ```
 
----
-
-## Sentinel — coverage and drift
-
-Sentinel surfaces two things Chronicle can't tell you about itself.
-
-**Coverage** — which parts of your codebase has the AI never documented?
-
-```bash
-quorum sentinel coverage --path src   # quick check from the terminal
-quorum sentinel coverage --json       # machine-readable, for scripts
-```
-
-**Drift** — do existing Chronicle entries still accurately describe the code, or have they gone stale? Drift detection requires an LLM; use `sentinelAssertions({ llm })` in your test suite (the CLI surfaces the message and directs you there).
-
-To get a coverage comment on every PR, copy `.github/workflows/sentinel-pr.yml` from the [Quorum repo](https://github.com/balpal4495/Quorum) into your project. Every PR then gets a comment showing a full-project coverage table and a colour-coded heatmap. Changed modules are highlighted. Reviewers see exactly where knowledge is solid and where it goes dark.
+Deterministic assertions run without any LLM. Set `EVAL_LLM=1` to also test Jury confidence and Council recommendations against a real LLM.
 
 ---
 
-## For custom agent pipelines
-
-If you're building your own agent workflow programmatically, the modules expose a clean TypeScript API. Wire your LLM provider and call directly:
-
-```typescript
-import { setup } from "./quorum/modules/setup"
-
-const { oracle, evaluate, deliberate } = await setup({ llm: myLLMProvider })
-
-const evidence = await oracle.query("authentication patterns")
-const jury     = await evaluate({ outcome, design, evidence })
-const verdict  = await deliberate({ outcome, design, evidence, jury_output: jury })
-```
-
-The `LLMProvider` type is a simple function — wire OpenAI, Anthropic, or anything else:
-
-```typescript
-// Anthropic
-const llm = async (messages, model = "claude-3-5-sonnet-20241022") => {
-  const res = await anthropic.messages.create({ model, messages, max_tokens: 2048 })
-  return res.content[0].type === "text" ? res.content[0].text : ""
-}
+## What Quorum is not
 
-// OpenAI
-const llm = async (messages, model = "gpt-4o") => {
-  const res = await openai.chat.completions.create({ model, messages })
-  return res.choices[0].message.content ?? ""
-}
-```
+Quorum is not a coding agent.  
+Quorum is not a replacement for TDD, code review, or planning.  
+Quorum is not a private SaaS memory store.  
+Quorum does not auto-approve what the AI learns.
 
-Full API reference: [modules/README.md](modules/README.md)
+It is a project-local memory, evidence, and review layer for agents you already use.
 
 ---
 
 ## Releases
 
-Quorum is published as `@balpal4495/quorum`. New versions release automatically when a semver tag is pushed — via GitHub Actions and OIDC Trusted Publishing, no stored tokens.
+Published as `@balpal4495/quorum`. Releases trigger automatically on PR merge via label (`release:patch`, `release:minor`, `release:major`) — GitHub Actions bumps the version, tags, and publishes via OIDC Trusted Publishing.
 
 ---
 
 ## Docs
 
-- [SETUP.md](SETUP.md) — full bootstrap sequence (the file you point your AI at)
+- [SETUP.md](SETUP.md) — full bootstrap sequence (point your AI at this)
 - [modules/README.md](modules/README.md) — TypeScript API reference
 - [modules/AGENTS.md](modules/AGENTS.md) — file ownership map
 - [modules/CLAUDE.md](modules/CLAUDE.md) — design decisions and invariants