@balpal4495/quorum 0.1.9 → 0.1.10

package/README.md

@@ -1,327 +1,198 @@
 # Quorum
 
-**Quorum gives AI agents memory and judgment.**
+**Quorum gives your AI coding assistant memory and judgment.**
 
-Drop it into any Node.js project, wire up your LLM, and your agents can query what's been tried before, validate decisions against prior evidence, and write new knowledge back — with a human approving every write.
+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.
 
-```bash
-npx @balpal4495/quorum@latest init
-```
-
-That's it. Quorum copies itself into your project, merges instruction files for your AI, and creates the knowledge store directory. Run `npm install` and you're ready.
+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.
 
 ---
 
-## Why this exists
+## Get started in one command
+
+Run this from your project root:
 
-When AI agents work in a codebase over weeks or months, they lose context between sessions. They retry approaches that already failed. They contradict previous decisions. They have no memory of what the team has already learned.
+```bash
+npx @balpal4495/quorum@latest init
+```
 
-Quorum solves this with four modules:
+Then run `npm install`.
 
-| Module | What it does |
-|---|---|
-| **Oracle** | Stores and retrieves project knowledge — decisions, investigations, outcomes |
-| **Jury** | Scores a proposed design against that knowledge — gives you confidence before acting |
-| **Council** | A panel of advisors challenges the design and a Chairman gives a final verdict |
-| **Sentinel** | Shows you which parts of the codebase the AI knows nothing about — and flags stale knowledge |
+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/`.
 
 ---
 
-## How it works
+## Then just talk to your AI
 
-Every significant decision goes through a pipeline before execution:
+Once initialized, open your AI in agent mode and tell it:
 
-```
-oracle.query()  →  jury.evaluate()  →  council.deliberate()  →  human gate  →  Executor
-```
+> "Follow quorum/SETUP.md"
 
-1. **Query** — retrieve everything Chronicle knows about the problem
-2. **Evaluate** — Jury scores the proposed design against that evidence (0–1 confidence)
-3. **Deliberate** — Council advisors challenge it independently, reviewers anonymously critique, Chairman gives a verdict
-4. **Human gate** — if satisfied, a human approves the Chronicle entry; nothing is written automatically
-5. **Execute** — agent proceeds with a validated, documented decision
-
-```mermaid
-sequenceDiagram
-    participant Agent as AI Agent
-    participant Oracle
-    participant Jury
-    participant Council
-    participant Human
-    participant Chronicle
-
-    Agent->>Oracle: query(text)
-    Oracle->>Chronicle: vector + BM25 search
-    Chronicle-->>Agent: ranked evidence
-
-    Agent->>Jury: evaluate(design, evidence)
-    Jury-->>Agent: confidence score + gaps
-
-    Agent->>Council: deliberate(design, evidence, jury_output)
-    Council-->>Agent: verdict + proposal
-
-    alt Council satisfied
-        Agent->>Human: surface verdict for approval
-        Human->>Oracle: commit(proposalId)
-        Oracle->>Chronicle: index entry
-    else not satisfied
-        Note over Agent: revise and retry
-    end
-```
+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.
+
+**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
 
 ---
 
-## Real examples
+## What changes after setup
 
-### Example 1 — An agent remembers a past failure
+### Your AI now has a memory
 
-Your agent is about to propose JWT with symmetric signing. Oracle returns an entry:
+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.
 
-```
-[abc-123] Tried symmetric JWT (HS256) in March. Rejected — no way to rotate keys
-          without invalidating all active sessions. Use RS256 with short-lived tokens.
-          confidence: 0.91 · status: committed
-```
+> *"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."*
 
-Jury flags this as a conflict. The agent revises to RS256 before Council even sees it.
+### Your AI validates designs before acting
 
----
+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.
 
-### Example 2 — Validating a database migration plan
+> *"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."*
 
-An agent proposes adding a `NOT NULL` column to a 50M-row table.
+### You approve what gets remembered
+
+When a decision is made, your AI stages a Chronicle entry using `oracle.propose()`. You approve it with `oracle.commit(proposalId)`. Nothing is indexed without your explicit sign-off.
 
-```typescript
-const evidence = await oracle.query("schema migrations large tables")
-
-const jury = await evaluate({
-  outcome: "Add NOT NULL column users.verified",
-  design:  "ALTER TABLE, backfill with default false, then add constraint",
-  evidence,
-})
-// jury.confidence: 0.41 — gaps: ["no lock strategy", "no rollback plan"]
-
-const verdict = await deliberate({
-  outcome: "Add NOT NULL column users.verified",
-  design:  "ALTER TABLE, backfill with default false, then add constraint",
-  evidence,
-  jury_output: jury,
-})
-// verdict.satisfied: false
-// verdict.verdict: "No lock strategy specified. On a table this size, a naive ALTER TABLE
-//                   will take an exclusive lock for minutes. Use a shadow column pattern
-//                   or pg_repack."
+```
+.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
 ```
 
-The agent revises the plan. Chronicle records the reasoning once approved.
+Commit `.chronicle/committed/` to git. Future sessions — and your teammates' sessions — start with that context.
 
 ---
 
-### Example 3 — Onboarding a new AI to an established project
+## Real examples
 
-On day one, a fresh AI session queries Chronicle before touching anything:
+### An agent that remembers a past failure
+
+Your AI is about to propose symmetric JWT signing. Oracle returns:
 
-```typescript
-const evidence = await oracle.query("authentication, session handling, token strategy")
-// Returns 6 entries covering prior decisions, a failed experiment with Redis sessions,
-// the current RS256 approach, and a note about the upcoming OAuth migration.
+```
+[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
 ```
 
-The AI works with full context from the first message — no archaeology through git history.
+Jury flags it as a direct conflict. The agent revises before Council even sees it.
 
 ---
 
-## Quick start
+### Onboarding a new session to an established project
 
-```typescript
-import { setup } from "./quorum/modules/setup"
+Day one of a new Claude Code session. Before touching anything:
 
-const { oracle, evaluate, deliberate } = await setup({
-  llm: myLLMProvider,  // any function that calls your LLM — see wiring below
-})
-
-// Query what Chronicle knows
-const evidence = await oracle.query("authentication patterns in this codebase")
-
-// Evaluate a proposed design
-const jury = await evaluate({
-  outcome: "Add OAuth2 login via GitHub",
-  design:  "Use passport-github2, store sessions in Redis, 1-hour TTL",
-  evidence,
-})
-
-// Get a Council verdict
-const verdict = await deliberate({
-  outcome: "Add OAuth2 login via GitHub",
-  design:  "Use passport-github2, store sessions in Redis, 1-hour TTL",
-  evidence,
-  jury_output: jury,
-})
-
-if (verdict.satisfied) {
-  // → surface verdict.proposal to a human for approval
-  // → human calls oracle.commit(proposalId) to index it
-  // → Executor proceeds
-} else {
-  // verdict.verdict contains the specific objection
-  // verdict.recommendation is "redesign" or "investigate-more"
-}
 ```
+> query Chronicle for: authentication, session handling, token strategy
 
----
-
-## Wiring your LLM
-
-Quorum accepts any function with this signature — you're never locked in:
-
-```typescript
-import type { LLMProvider } from "./quorum/modules/shared/types"
+  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
 ```
 
-```typescript
-// Anthropic
-const llm: LLMProvider = async (messages, model = "claude-3-5-sonnet-20241022") => {
-  const system = messages.find(m => m.role === "system")?.content ?? ""
-  const user   = messages.filter(m => m.role !== "system")
-  const res = await anthropic.messages.create({ model, system, messages: user, max_tokens: 2048 })
-  return res.content[0].type === "text" ? res.content[0].text : ""
-}
-
-// OpenAI
-const llm: LLMProvider = async (messages, model = "gpt-4o") => {
-  const res = await openai.chat.completions.create({ model, messages })
-  return res.choices[0].message.content ?? ""
-}
-
-// Per-step model overrides (optional)
-const { oracle, evaluate, deliberate } = await setup({
-  llm,
-  models: {
-    jury: "gpt-4o-mini",
-    council: {
-      frame:    "gpt-4o-mini",
-      advisors: "gpt-4o-mini",
-      reviewers: "gpt-4o",
-      chairman: "gpt-4o",
-    },
-  },
-})
-```
-
-Oracle requires no LLM — only Jury, Council, and Sentinel drift checks need one.
+The AI works with full project context from the first message — no archaeology through git history.
 
 ---
 
-## Chronicle — the knowledge store
+### Validating a risky database change
 
-Chronicle lives at `.chronicle/` in your project root. It persists across sessions, machines, and contributors.
+An agent proposes adding a `NOT NULL` column to a 50M-row table. Jury returns:
 
 ```
-.chronicle/
-  committed/    ← approved entries as JSON (commit these to git)
-  proposals/    ← staged entries awaiting approval (commit these too — they're human-readable)
-  SUMMARY.md    ← auto-generated weekly context, rebuilt on every commit
+confidence: 0.41
+gaps: ["no lock strategy documented", "no rollback plan"]
+council_brief: challenge
 ```
 
-**The write path is always human-gated:**
+Council's Chairman gives a verdict:
 
 ```
-oracle.propose()   ← AI stages a candidate entry (no indexing yet)
-oracle.commit()    ← human approves — entry is indexed and searchable
+satisfied: false
+verdict: "On a table this size, a naive ALTER TABLE takes an exclusive lock for minutes.
+          Specify a shadow column pattern or pg_repack. No rollback plan documented."
 ```
 
-`deliberate()` automatically calls `oracle.propose()` at the end of every Council run. You only need to call `oracle.commit(proposalId)` when you're ready to approve it.
-
-There are no auto-commits. Ever.
+The agent revises the plan. You approve the Chronicle entry once it's solid. The reasoning is on record for the next time someone touches that table.
 
 ---
 
-## Sentinel — codebase coverage and drift
+## What's inside
 
-Sentinel answers three questions Chronicle can't answer about itself.
+Four portable TypeScript modules installed into `quorum/modules/`:
 
-### Which files does the AI know nothing about?
+| Module | What it does |
+|---|---|
+| **Oracle** | Query and write interface to Chronicle. No LLM required. |
+| **Jury** | Evaluates a proposed design against Chronicle evidence. Returns a confidence score. |
+| **Council** | A panel of advisors challenges the design independently, reviewers critique anonymously, a Chairman gives a final verdict. |
+| **Sentinel** | Shows which files the AI knows nothing about, flags stale knowledge, and posts a coverage map on every PR. |
 
-```typescript
-import { coverage } from "./quorum/modules/sentinel"
+The modules live in your repo — readable by any AI working in the codebase. Nothing is hidden in `node_modules`.
 
-const report = await coverage(".chronicle", "src")
-// report.percentage       — 34%
-// report.uncoveredFiles   — ["src/auth/session.ts", "src/payments/stripe.ts", ...]
-```
+---
 
-### Is the AI's knowledge stale?
+## Sentinel — coverage and drift
 
-```typescript
-import { detectDrift } from "./quorum/modules/sentinel"
+Sentinel surfaces two things Chronicle can't tell you about itself.
 
-const report = await detectDrift(".chronicle", "src", llm)
-// report.flags — entries where the key_insight may no longer match the code
-```
+**Coverage** — which parts of your codebase has the AI never documented?
 
-### Coverage as CI assertions
+**Drift** — do existing Chronicle entries still accurately describe the code, or have they gone stale?
 
-```typescript
-import { describe } from "vitest"
-import { sentinelAssertions } from "./quorum/modules/sentinel"
-
-describe("sentinel", () => {
-  sentinelAssertions({
-    chronicleDir: ".chronicle",
-    codebasePath: "src",
-    llm: myLLMProvider,       // omit to skip drift tests
-    minCoveragePercent: 50,   // 0 = advisory only (default — safe for new projects)
-  }).forEach(a => a())
-})
-```
+Add `sentinel-pr.yml` (included in `quorum/`) to your GitHub Actions and every PR 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.
 
-### PR coverage map
+---
 
-Add `.github/workflows/sentinel-pr.yml` (included in `quorum/`) to get a comment on every PR showing which modules are covered, which are blind spots, and which files the PR touches — as a table and a colour-coded Mermaid heatmap.
+## 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:
 
-## Modules at a glance
+```typescript
+import { setup } from "./quorum/modules/setup"
 
-| Module | Needs LLM | Entry point |
-|---|---|---|
-| Oracle | No | `oracle.query()` / `oracle.propose()` / `oracle.commit()` |
-| Jury | Yes | `evaluate(input, deps)` |
-| Council | Yes | `deliberate(input, deps)` |
-| Sentinel | Optional | `coverage()` / `detectDrift()` / `sentinelAssertions()` |
+const { oracle, evaluate, deliberate } = await setup({ llm: myLLMProvider })
 
-Full API reference: [modules/README.md](modules/README.md)
-Design decisions (what not to change): [modules/CLAUDE.md](modules/CLAUDE.md)
+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:
 
-## Dependencies
+```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 : ""
+}
 
-| Package | Why |
-|---|---|
-| `zod` | Validates all structured LLM output — required |
-| `vectordb` | LanceDB embedded vector store — default adapter, swappable |
-| `@xenova/transformers` | Local ONNX embedder (all-MiniLM-L6-v2) — default adapter, swappable |
+// OpenAI
+const llm = async (messages, model = "gpt-4o") => {
+  const res = await openai.chat.completions.create({ model, messages })
+  return res.choices[0].message.content ?? ""
+}
+```
 
-`vectordb` and `@xenova/transformers` are optional if you bring your own vector store and embedder. Implement the `VectorStore` interface in `oracle/types.ts` and pass your own `embedder` function to `setup()`.
+Full API reference: [modules/README.md](modules/README.md)
 
 ---
 
 ## Releases
 
-Quorum is published to npm as `@balpal4495/quorum`. New versions are released by pushing a semver tag:
-
-```bash
-git tag v0.2.0 && git push origin v0.2.0
-```
-
-GitHub Actions publishes to npm automatically via OIDC Trusted Publishing — no stored tokens.
+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.
 
 ---
 
 ## Docs
 
-- [modules/README.md](modules/README.md) — full API reference
-- [modules/AGENTS.md](modules/AGENTS.md) — file ownership and what each file owns
+- [SETUP.md](SETUP.md) — full bootstrap sequence (the file you point your AI at)
+- [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
-- [SETUP.md](SETUP.md) — manual bootstrap sequence (for AI-assisted setup)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@balpal4495/quorum",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Portable reasoning layer for agentic codebases — Oracle, Jury, Council, Sentinel",
   "type": "module",
   "license": "MIT",