@balpal4495/quorum 0.1.8 → 0.1.9

package/README.md

@@ -1,48 +1,45 @@
 # Quorum
 
-Quorum is a portable reasoning layer for agentic codebases.
+**Quorum gives AI agents memory and judgment.**
 
-Drop the `quorum/` folder into any Node.js project, tell your AI to follow `quorum/SETUP.md`, and it wires itself in — installing dependencies, merging instruction files, and initialising a persistent knowledge store called Chronicle.
+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.
 
-From that point, every AI agent working in the codebase queries Chronicle before proposing solutions, and every significant decision gets written back to it (with human approval). Over time it becomes the institutional memory of the project: what was tried, what worked, what failed, and why.
+```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.
 
 ---
 
-## What's inside
+## Why this exists
+
+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.
 
-Four portable TypeScript modules:
+Quorum solves this with four modules:
 
 | Module | What it does |
 |---|---|
-| **Oracle** | Query and write interface to Chronicle. No LLM required. |
-| **Jury** | Evaluates a proposed design against Oracle evidence. Returns a confidence score. |
-| **Council** | Adversarial validation via a parallel panel of advisors and reviewers. Returns a verdict. |
-| **Sentinel** | Chronicle coverage and drift detection. Surfaces gaps and stale knowledge as Vitest assertions. |
-
-```
-oracle.query()  →  jury.evaluate()  →  council.deliberate()  →  human gate  →  Executor
-sentinel.coverage() + sentinel.detectDrift()  →  advisory test output
-```
+| **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 |
 
 ---
 
 ## How it works
 
-**Flow — system components and connections:**
+Every significant decision goes through a pipeline before execution:
 
-```mermaid
-flowchart LR
-    Agent[AI Agent] -->|query| Oracle
-    Oracle -->|evidence| Jury
-    Jury -->|scores| Council
-    Council -->|verdict| Gate[Human Gate]
-    Oracle -. reads .-> Chronicle[(Chronicle)]
-    Gate -. approved commit .-> Chronicle
-    Chronicle -. coverage + drift .-> Sentinel
-    Sentinel -. advisory report .-> CI([CI / Developer])
+```
+oracle.query()  →  jury.evaluate()  →  council.deliberate()  →  human gate  →  Executor
 ```
 
-**Sequence — one full decision cycle:**
+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
@@ -54,149 +51,277 @@ sequenceDiagram
     participant Chronicle
 
     Agent->>Oracle: query(text)
-    Oracle->>Chronicle: vector search
-    Chronicle-->>Oracle: ranked entries
-    Oracle-->>Agent: OracleResult[]
+    Oracle->>Chronicle: vector + BM25 search
+    Chronicle-->>Agent: ranked evidence
 
     Agent->>Jury: evaluate(design, evidence)
-    Jury-->>Agent: score, flags, passed
+    Jury-->>Agent: confidence score + gaps
 
-    Agent->>Council: deliberate(design, evaluations)
-    Council-->>Agent: satisfied, verdict, proposal
+    Agent->>Council: deliberate(design, evidence, jury_output)
+    Council-->>Agent: verdict + proposal
 
-    alt Council not satisfied
-        Note over Agent: revise design and retry
-    else Council satisfied
-        Agent->>Human: surface verdict and proposal
+    alt Council satisfied
+        Agent->>Human: surface verdict for approval
         Human->>Oracle: commit(proposalId)
-        Oracle->>Chronicle: upsert entry
-        Oracle-->>Human: ChronicleEntry
+        Oracle->>Chronicle: index entry
+    else not satisfied
+        Note over Agent: revise and retry
     end
 ```
 
 ---
 
-## How to use it
+## Real examples
 
-Run this from any Node.js project root:
+### Example 1 — An agent remembers a past failure
 
-```bash
-npx @balpal4495/quorum@latest init
+Your agent is about to propose JWT with symmetric signing. Oracle returns an entry:
+
+```
+[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
 ```
 
-Quorum scaffolds itself — copying modules into `quorum/`, merging AI instruction files (CLAUDE.md, AGENTS.md), and initialising Chronicle. Then run `npm install`.
+Jury flags this as a conflict. The agent revises to RS256 before Council even sees it.
 
-For manual control or AI-assisted setup, tell your AI: *"follow quorum/SETUP.md"*.
+---
 
-See [SETUP.md](SETUP.md) for the full bootstrap sequence.
+### Example 2 — Validating a database migration plan
 
----
+An agent proposes adding a `NOT NULL` column to a 50M-row table.
 
-## Chronicle
+```typescript
+const evidence = await oracle.query("schema migrations large tables")
 
-Chronicle lives at `.chronicle/` and is the persistent knowledge store that underpins everything. Every Oracle entry goes through a human-gated write path — `oracle.propose()` stages it, a human calls `oracle.commit()` to index it. There are no auto-commits.
+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"]
 
-```
-.chronicle/
-  committed/    ← approved entries as JSON (committed to git, source of truth)
-  proposals/    ← staged entries awaiting human approval (JSON, not indexed yet)
-  SUMMARY.md    ← auto-generated agent context, rebuilt on every commit
+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."
 ```
 
-`SUMMARY.md` groups the last 12 weeks of entries by week and work context. It gives agents temporal sequence — what happened and in what order — which vector search alone cannot provide.
+The agent revises the plan. Chronicle records the reasoning once approved.
 
 ---
 
-## Dependencies
+### Example 3 — Onboarding a new AI to an established project
 
-| Package | Purpose |
-|---|---|
-| `zod` | Structured LLM output validation |
-| `vectordb` | LanceDB embedded vector store (swappable) |
-| `@xenova/transformers` | Local ONNX embedder — all-MiniLM-L6-v2 (swappable) |
+On day one, a fresh AI session queries Chronicle before touching anything:
+
+```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.
+```
 
-The LLM provider is injectable — Quorum defines a simple function interface and never hardcodes a provider. Wire OpenAI, Anthropic, or anything else at the application level.
+The AI works with full context from the first message — no archaeology through git history.
 
 ---
 
-## Designed to be dropped in — not installed
+## Quick start
 
-Quorum is intentionally a folder, not an npm package. The source lives in your repo, the modules are readable by any AI agent working in the codebase, and the instruction files (`AGENTS.md`, `CLAUDE.md`) travel with the code. Nothing is hidden inside `node_modules`.
+```typescript
+import { setup } from "./quorum/modules/setup"
 
----
+const { oracle, evaluate, deliberate } = await setup({
+  llm: myLLMProvider,  // any function that calls your LLM — see wiring below
+})
 
-## Sentinel
+// Query what Chronicle knows
+const evidence = await oracle.query("authentication patterns in this codebase")
 
-Sentinel answers three questions Chronicle cannot answer about itself.
+// 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,
+})
 
-**Coverage** — which files have no Chronicle entries? These are the blind spots where agents have no prior knowledge to draw on.
+// 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,
+})
 
-**Drift** — do existing Chronicle entries still accurately describe the code? Insights become stale without anyone noticing.
+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"
+}
+```
 
-**PR coverage map** — when a PR is opened, every module in the codebase is shown with its Chronicle coverage percentage, risk colour, and how many files the PR touches. Reviewers see exactly where the knowledge is solid and where it goes dark — as a table and a colour-coded heatmap, not a prose summary.
+---
 
-Sentinel is designed for both new and established projects. On a brand-new project with no Chronicle entries it surfaces a bootstrap prompt rather than a wall of red. As the project matures, coverage thresholds can be raised to enforce standards in CI.
+## Wiring your LLM
 
-### In CI — coverage and drift as Vitest assertions
+Quorum accepts any function with this signature — you're never locked in:
 
 ```typescript
-import { describe } from "vitest"
-import { sentinelAssertions } from "./modules/sentinel/assert"
+import type { LLMProvider } from "./quorum/modules/shared/types"
+```
 
-const assertions = sentinelAssertions({
-  chronicleDir: ".chronicle",
-  codebasePath: "src",          // path to your source tree — defaults to "."
-  llm: myLLMProvider,           // optional — drift tests skip gracefully when absent
-  minCoveragePercent: 50,       // optional — 0 (default) = advisory only, never fails CI
+```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.
+
+---
+
+## Chronicle — the knowledge store
+
+Chronicle lives at `.chronicle/` in your project root. It persists across sessions, machines, and contributors.
 
-describe("sentinel", () => { assertions.forEach(a => a()) })
+```
+.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
 ```
 
-Coverage tests are deterministic — no LLM required, always run. By default (`minCoveragePercent: 0`) gaps are logged but CI never fails, which is right for a new project. Raise the threshold as Chronicle matures. Drift tests are always advisory — they skip when no LLM is configured and never hard-block the build.
+**The write path is always human-gated:**
 
-Test files (`__tests__/`, `*.test.ts`, `*.spec.ts`) are excluded from tracking by default — only source files count toward coverage.
+```
+oracle.propose()   ← AI stages a candidate entry (no indexing yet)
+oracle.commit()    ← human approves — entry is indexed and searchable
+```
+
+`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.
+
+---
 
-### In PRs — the coverage map
+## Sentinel — codebase coverage and drift
 
-The `sentinel-pr.yml` workflow runs on every PR and posts a comment with a full-project coverage table and a colour-coded Mermaid heatmap. Changed modules are bolded. The comment updates in place on each push — one comment per PR, never a thread of duplicates.
+Sentinel answers three questions Chronicle can't answer about itself.
 
+### Which files does the AI know nothing about?
+
+```typescript
+import { coverage } from "./quorum/modules/sentinel"
+
+const report = await coverage(".chronicle", "src")
+// report.percentage       — 34%
+// report.uncoveredFiles   — ["src/auth/session.ts", "src/payments/stripe.ts", ...]
 ```
-## Sentinel — Chronicle Coverage Map — 2026-W20
 
-| Module   | Coverage | Entries | Files | PR Changes  | Risk   |
-|----------|----------|---------|-------|-------------|--------|
-| council/ | 0%       | 0       | 8     | —           | high   |
-| jury/    | 0%       | 0       | 4     | —           | high   |
-| oracle/  | 22%      | 4       | 9     | —           | medium |
-| scripts/ | 0%       | 0       | 1     | **1 files** | high   |
-| sentinel/| 0%       | 0       | 5     | **2 files** | high   |
-| shared/  | 100%     | 2       | 1     | —           | low    |
+### Is the AI's knowledge stale?
 
-[mermaid heatmap — Chronicle root → all modules, nodes coloured red/yellow/green by risk,
- changed modules labelled with file count]
+```typescript
+import { detectDrift } from "./quorum/modules/sentinel"
 
-### Chronicle context for changed modules
-**oracle/**
-- `[30bdc1c1]` schema constraints not LLM self-evaluation — validated (0.88)
+const report = await detectDrift(".chronicle", "src", llm)
+// report.flags — entries where the key_insight may no longer match the code
 ```
 
-On a new project with no Chronicle entries, the comment instead shows a bootstrap prompt guiding the team toward their first `oracle.propose()` call.
+### Coverage as CI assertions
 
-```mermaid
-flowchart LR
-    Chronicle[(Chronicle)] -->|committed entries| Sentinel
-    Codebase[Codebase] -->|source files, excl. tests| Sentinel
-    LLM[LLM Provider] -. drift eval .-> Sentinel
-    Sentinel --> Vitest([Vitest assertions])
-    Sentinel --> PRComment([PR coverage map])
+```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())
+})
 ```
 
+### 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.
+
+---
+
+## Modules at a glance
+
+| 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()` |
+
+Full API reference: [modules/README.md](modules/README.md)
+Design decisions (what not to change): [modules/CLAUDE.md](modules/CLAUDE.md)
+
+---
+
+## Dependencies
+
+| 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 |
+
+`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()`.
+
+---
+
+## 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.
+
 ---
 
-## Module docs
+## Docs
 
-- [modules/README.md](modules/README.md) — full API reference and quick-start
-- [modules/AGENTS.md](modules/AGENTS.md) — file ownership and invariants
-- [modules/CLAUDE.md](modules/CLAUDE.md) — design decisions and what not to change
-- [SETUP.md](SETUP.md) — bootstrap sequence for new projects
+- [modules/README.md](modules/README.md) — full API reference
+- [modules/AGENTS.md](modules/AGENTS.md) — file ownership and what each file owns
+- [modules/CLAUDE.md](modules/CLAUDE.md) — design decisions and invariants
+- [SETUP.md](SETUP.md) — manual bootstrap sequence (for AI-assisted setup)

package/bin/init.js

@@ -15,6 +15,10 @@ import { promises as fs } from "fs"
 import path from "path"
 import { fileURLToPath } from "url"
 import { execSync } from "child_process"
+import { createRequire } from "module"
+
+const _require = createRequire(import.meta.url)
+const PKG_VERSION = _require("../package.json").version
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const QUORUM_ROOT = path.resolve(__dirname, "..")
@@ -346,7 +350,7 @@ async function cli() {
   }
 
   if (command === "--version" || command === "-v" || command === "version") {
-    console.log("0.1.0")
+    console.log(PKG_VERSION)
     return
   }
 

package/package.json

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