@balpal4495/quorum 3.3.0 → 3.3.1

package/.github/copilot-instructions.md

@@ -0,0 +1,117 @@
+# Project Guidelines
+
+## Architecture
+
+This project uses six portable reasoning modules: **Advisor**, **Oracle**, **Jury**, **Council**, **Sentinel**, and **Compass**.
+They form the knowledge, validation, and product-direction layer for all agentic work in this codebase.
+
+```
+Advisor  →  plain-language Chronicle queries
+Oracle   →  Jury  →  Council  →  human gate  →  Executor
+Sentinel →  coverage + drift
+Compass  →  product-direction synthesis (behaviours, pathways, bets, scoring)
+```
+
+Source: `modules/` — see [modules/README.md](modules/README.md) for full API reference.
+
+---
+
+## Chronicle — the persistent knowledge store
+
+Chronicle lives at `.chronicle/` and is the institutional memory of this codebase.
+Every prior decision, investigation finding, and outcome is stored there.
+
+**Always query Oracle before proposing a solution.** Treat existing entries as ground truth for what has been tried, what worked, and what failed.
+
+```typescript
+const evidence = await oracle.query("describe what you're about to do")
+// Use evidence to inform your proposal before proceeding
+```
+
+**Never call `oracle.commit()` without explicit human approval.**
+`oracle.propose()` writes a pending file. A human must call `oracle.commit(proposalId)` to index it.
+There are no auto-commits. Do not attempt to bypass this gate.
+
+---
+
+## Module responsibilities
+
+| Module | What it does | LLM? |
+|---|---|---|
+| `ask()` | Plain-language question answered from Chronicle — validates internally, retries up to 2× | Yes |
+| `oracle.query()` | Retrieves relevant Chronicle entries by semantic + BM25 search | No |
+| `oracle.propose()` | Stages a new entry for human review | No |
+| `oracle.commit()` | Indexes an approved entry — human-triggered only | No |
+| `jury.evaluate()` | Scores a design against evidence across 4 dimensions | Yes |
+| `council.deliberate()` | Adversarial validation via advisor/reviewer fan-out | Yes |
+| `sentinel` | Coverage reporting, drift detection, and PR coverage maps | Optional |
+| `compass` | Product-direction synthesis — behaviours, opportunities, pathways, bets, idea scoring | Optional |
+
+---
+
+## Setup
+
+```typescript
+import { setup } from "@balpal4495/quorum"
+
+const { oracle, evaluate, deliberate, ask, compass } = await setup({ llm: yourProvider })
+```
+
+`setup()` creates Chronicle directories, warms the embedder, and wires all dependencies.
+Call it once at application startup.
+
+---
+
+## Routing rules
+
+After `jury.evaluate()`:
+
+| `recommendation` | Action |
+|---|---|
+| `proceed` | Pass to `council.deliberate()` |
+| `investigate-more` | Return to Detective with `juryOutput.gaps` |
+| `redesign` | Return to Designer |
+
+After `council.deliberate()`:
+
+| `satisfied` | `recommendation` | Action |
+|---|---|---|
+| `true` | `proceed` | Human gate → Executor |
+| `false` | `redesign` | Return to Designer with `verdict` as feedback |
+| `false` | `investigate-more` | Return to Detective with `juryOutput.gaps` |
+
+---
+
+## Rules for AI agents
+
+- **Evidence first.** Query Oracle before proposing any design or implementation.
+- **No auto-commits.** Never call `oracle.commit()` autonomously. Only propose.
+- **Cite entries.** When referencing Chronicle findings, use the entry ID (e.g. `[abc-123]`).
+- **Respect refuted entries.** A `refuted` entry means this was tried and failed — surface the failure reason, don't ignore it.
+- **Fail loudly.** Jury and Council throw on bad LLM output. Do not swallow errors or default to passing scores.
+- **These modules are the portable core.** Detective, Designer, Executor, and Validator are application-specific — do not add them here.
+
+---
+
+## CLI quick reference
+
+```bash
+quorum advisor brief                        # full Chronicle summary, no LLM
+quorum advisor query "topic"                # keyword search, no LLM
+quorum advisor "plain-language question"    # synthesised answer via LLM
+quorum check --outcome "..." --design "..."  # instant risk triage
+quorum commit --list                        # review pending proposals
+quorum commit <id>                          # approve a Chronicle entry
+quorum compass map                          # map current product behaviours (no LLM)
+quorum compass brief                        # product-direction summary (LLM)
+quorum compass pathways --goal "..."        # generate product pathways (LLM)
+quorum compass score "idea"                 # score a product idea (LLM)
+```
+
+---
+
+## Build and test
+
+```bash
+npx vitest run modules/ evals/
+```

package/GEMINI.md

@@ -0,0 +1,73 @@
+# Quorum — Gemini Context
+
+> This file is optional. It is only active when Google Gemini CLI is installed and
+> `GEMINI_API_KEY` is set. Projects without Gemini CLI configured can ignore it.
+
+## Your role in this project
+
+You are a supporting AI in the Quorum codebase. Claude Code is the primary agent — it handles
+tool execution, file edits, complex reasoning, and final decisions.
+
+You are called in two modes:
+
+1. **Assistant mode** — Claude needs large-context analysis it can't efficiently do itself:
+   summarise many files, trace a pattern across the codebase, answer questions that require
+   holding the entire repo in memory at once.
+
+2. **Second-opinion mode** — Claude asks you to evaluate a design decision before proposing
+   it to the user.
+
+**When giving a second opinion: be direct and specific. Flag concerns by name. Do not hedge
+excessively. If something will break an invariant (see below), say so plainly.**
+
+---
+
+## Project overview
+
+Quorum is a portable reasoning layer for agentic codebases. Three TypeScript 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 + gaps. |
+| **Council** | Adversarial validation via parallel advisors and reviewers. Returns a verdict. |
+
+```
+oracle.query()  →  jury.evaluate()  →  council.deliberate()  →  human gate  →  Executor
+```
+
+Source lives in `modules/`. Detailed API: `modules/README.md`.
+
+---
+
+## Chronicle
+
+Chronicle lives at `.chronicle/` — the persistent institutional memory of the codebase.
+
+All writes go through a human-gated path:
+- `oracle.propose()` — stages a pending entry (AI agents may call this)
+- `oracle.commit(proposalId)` — indexes it (human-triggered only, **never AI-triggered**)
+
+---
+
+## Invariants — never suggest breaking these
+
+- `oracle.commit()` is **never** called without explicit human input.
+- In `jury/evaluate.ts`, `council_brief` is always overridden from the numeric `confidence`
+  value after parsing. The LLM is never trusted to compute it.
+- Both `jury/evaluate.ts` and `council/chairman.ts` throw on schema validation failure.
+  There are no fallbacks, defaults, or try/catch that swallows these errors.
+- All dependencies (LLM provider, vector store, embedder) are injected — never hardcoded
+  inside module logic. Do not suggest adding imports.
+- `deliberate()` calls `oracle.propose()` at the end of every run — never `oracle.commit()`.
+
+---
+
+## Key file locations
+
+| Path | What it contains |
+|---|---|
+| `modules/AGENTS.md` | File ownership map for Oracle, Jury, Council |
+| `modules/CLAUDE.md` | Design decisions and what not to change |
+| `modules/README.md` | Full API reference |
+| `.chronicle/` | LanceDB vector store, pending proposals, query log |

package/SETUP.md

@@ -0,0 +1,264 @@
+# Quorum — Bootstrap Setup
+
+You are reading this because Quorum is being set up in a codebase.
+
+---
+
+## Automated setup (preferred)
+
+If you have Node.js 18+ available, run this from the project root:
+
+```bash
+npx @balpal4495/quorum@latest init
+```
+
+This handles all steps below automatically — writing Quorum docs, merging instruction files,
+updating `package.json`, `.gitignore`, and creating the Chronicle directory.
+
+After it completes, run `npm install`. The CLI is immediately usable:
+
+```bash
+quorum advisor brief
+quorum advisor "what has the team decided about X?"
+quorum check --outcome '...' --design '...'
+```
+
+---
+
+## Manual setup (AI-assisted fallback)
+
+If the automated script is not available or fails, follow every step below in order.
+Do not skip steps. Do not ask for confirmation between steps — complete the full sequence and then report what was done.
+
+---
+
+## Step 1 — Read before touching anything
+
+Read these files in full before proceeding:
+
+- `quorum/AGENTS.md` — module file ownership and invariants
+- `quorum/CLAUDE.md` — design decisions and constraints
+- `.github/copilot-instructions.md` — workflow rules for AI agents
+
+These are your operating instructions for everything that follows.
+
+---
+
+## Step 2 — Audit the host project
+
+Check what already exists at the project root. Record what you find — you will need this in Step 4.
+
+```
+Does .github/copilot-instructions.md exist?        yes / no
+Does AGENTS.md exist at the project root?           yes / no
+Does CLAUDE.md exist at the project root?           yes / no
+Does package.json exist?                            yes / no
+Does .gitignore exist?                              yes / no
+Does .chronicle/ exist?                             yes / no
+```
+
+---
+
+## Step 3 — Install Quorum
+
+Open `package.json` at the project root. Add to `devDependencies` if not already present:
+
+```json
+"@balpal4495/quorum": "^2.0.0"
+```
+
+Then run:
+
+```bash
+npm install
+```
+
+If the project uses `yarn` or `pnpm`, use the appropriate installer instead.
+
+---
+
+## Step 4 — Merge AI instruction files
+
+### 4a. `.github/copilot-instructions.md`
+
+The automated init command handles this step automatically.
+
+**If completing manually:** fetch `.github/copilot-instructions.md` from the Quorum GitHub repo (`balpal4495/Quorum`) and write it to `.github/copilot-instructions.md` in the project root. If the file already exists and does not contain `<!-- quorum:start -->`, append:
+
+```markdown
+---
+
+<!-- quorum:start -->
+<content from Quorum repo>
+<!-- quorum:end -->
+```
+
+### 4b. `AGENTS.md`
+
+**If it does not exist:**
+
+```markdown
+# Agent Instructions
+
+<!-- quorum:start -->
+## Quorum
+
+See [quorum/AGENTS.md](quorum/AGENTS.md) for module file ownership and internals.
+See [.github/copilot-instructions.md](.github/copilot-instructions.md) for workflow rules.
+<!-- quorum:end -->
+```
+
+**If it already exists:** append the `<!-- quorum:start --> ... <!-- quorum:end -->` block above.
+
+### 4c. `CLAUDE.md`
+
+**If it does not exist:**
+
+```markdown
+# Claude Instructions
+
+<!-- quorum:start -->
+## Quorum
+
+See [quorum/CLAUDE.md](quorum/CLAUDE.md) for design decisions and invariants.
+See [.github/copilot-instructions.md](.github/copilot-instructions.md) for workflow rules.
+<!-- quorum:end -->
+```
+
+**If it already exists:** append the `<!-- quorum:start --> ... <!-- quorum:end -->` block above.
+
+---
+
+## Step 5 — Update .gitignore
+
+**If `.gitignore` does not exist**, create it.
+
+Add the following block if not already present:
+
+```gitignore
+# Quorum — Chronicle
+# entries/ is a LanceDB binary vector store — do not commit
+.chronicle/entries/
+.chronicle/query-log.jsonl
+```
+
+---
+
+## Step 6 — Wire setup() into the project (programmatic use only)
+
+Skip this step if you are using only the CLI (`quorum advisor`, `quorum check`, etc.).
+
+For programmatic use, find the application entry point (e.g. `index.ts`, `server.ts`, `app.ts`).
+
+```typescript
+import { setup } from "@balpal4495/quorum"
+
+const { oracle, evaluate, deliberate, ask } = await setup({
+  llm: yourLLMProvider, // replace with your project's LLM provider function
+})
+```
+
+`setup()` creates `.chronicle/` directories, warms the embedder, and wires all module dependencies.
+Must be called once before any `oracle.query()`, `evaluate()`, `deliberate()`, or `ask()` call.
+
+`ask(question)` is the plain-language interface — it queries Oracle automatically, synthesises Chronicle evidence into a concise answer, and retries internally until the answer meets a confidence threshold.
+
+**Approving Chronicle proposals:**
+
+```bash
+quorum commit --list         # see pending proposals
+quorum commit <id>           # approve and index a proposal
+quorum commit <id> --dry-run # preview without writing
+```
+
+---
+
+## Step 7 — Verify Chronicle is created
+
+Confirm `.chronicle/proposals/` and `.chronicle/committed/` exist:
+
+```bash
+ls .chronicle/
+# expected: committed/  proposals/
+```
+
+---
+
+## Step 8 — Verify the CLI works
+
+```bash
+quorum advisor brief
+quorum growth
+```
+
+Both commands run without any LLM. If they fail, check that `npm install` completed successfully.
+
+To run Quorum's eval suite (optional — tests Quorum's own correctness):
+
+```bash
+npx vitest run node_modules/@balpal4495/quorum/evals/
+```
+
+---
+
+## Step 9 — Report what was done
+
+Once all steps are complete, report:
+
+1. Which files were created vs appended
+2. Whether `npm install` succeeded
+3. The path to `setup()` in the entry point if wired (or note if CLI-only)
+4. Any step that could not be completed and why
+
+---
+
+## Optional: Step 10 — Gemini CLI integration
+
+Skip this step if you do not have Google Gemini CLI installed. Quorum is fully functional without it.
+
+**10a. Install Gemini CLI** (if not already installed):
+
+```bash
+npm install -g @google/gemini-cli
+```
+
+**10b. Get an API key** from Google AI Studio and add to your shell profile:
+
+```bash
+export GEMINI_API_KEY="your-key-here"
+export GEMINI_CLI_TRUST_WORKSPACE=true
+```
+
+**10c. Create `GEMINI.md`** at the project root. Use `quorum/AGENTS.md` content as a starting point, or write a brief description of the project and the Quorum architecture.
+
+Once the key is set and `gemini -p "hello"` responds, Claude Code will automatically detect Gemini and use it for large-context tasks.
+
+---
+
+## After setup
+
+You are now operating under Quorum. The rules in `quorum/AGENTS.md` and `.github/copilot-instructions.md` apply to all subsequent work.
+
+Key reminders:
+- **Ask Advisor for context.** `quorum advisor "what has the team decided about X?"` before starting any meaningful work.
+- **Never call `oracle.commit()` autonomously.** Only `oracle.propose()`. A human commits.
+- **Chronicle entries are ground truth.** Respect `refuted` entries — do not retry what has already failed.
+
+### CLI quick reference
+
+| Command | What it does |
+|---|---|
+| `quorum advisor "question"` | Ask a plain-language question — answer synthesised from Chronicle (needs LLM) |
+| `quorum advisor query "topic"` | Search Chronicle entries by keyword (no LLM) |
+| `quorum advisor brief` | High-level Chronicle summary (no LLM) |
+| `quorum status` | Chronicle health — pending proposals, committed entries |
+| `quorum check --outcome X --design Y` | Preflight + risk classifier (no LLM) |
+| `quorum commit --list` | List pending proposals |
+| `quorum commit <id>` | Approve and index a proposal |
+| `quorum sentinel coverage [--path <dir>]` | Chronicle coverage of source files |
+| `quorum growth` | Chronicle learning health — growth rate, last commit, pending proposals |
+| `quorum evolve` | Consolidate Chronicle — merges duplicates, resolves contradictions, promotes open entries |
+
+`quorum check` exit codes: `0` = low/medium risk · `1` = high · `2` = critical
+
+`quorum advisor ask` and `quorum evolve` auto-detect any available LLM: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENAI_BASE_URL`, Ollama at localhost:11434, or an authenticated `gemini` CLI. When running inside an AI agent with no separate key, they output Chronicle evidence and a synthesis request for the agent to answer inline.

package/dist/oracle/adapters/lance-db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lance-db.d.ts","sourceRoot":"","sources":["../../../modules/oracle/adapters/lance-db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAe9C,wBAAsB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA+CnF"}
+{"version":3,"file":"lance-db.d.ts","sourceRoot":"","sources":["../../../modules/oracle/adapters/lance-db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAa9C,wBAAsB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAsDnF"}

package/dist/oracle/adapters/lance-db.js

@@ -11,10 +11,15 @@
  * is nearly identical but table.query() replaces table.search() for non-vector queries.
  */
 import path from "path";
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const lancedb = require("vectordb");
 export async function createLanceDBStore(chronicleDir) {
+    // Dynamic import keeps this file valid ESM — `vectordb` is CJS-only and has
+    // no ESM export, so a top-level `require()` would throw in ESM scope.
+    const lancedbMod = await import("vectordb");
+    const lancedb = lancedbMod.default ?? lancedbMod;
     const tableDir = path.join(chronicleDir, "entries");
+    // Cast to any — `vectordb` is a CJS-only package whose TypeScript declarations
+    // are incomplete (e.g. `metric` option not typed in WriteOptions).
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const db = await lancedb.connect(tableDir);
     let table = null;
     async function getOrCreateTable(firstRow) {

package/dist/oracle/adapters/lance-db.js.map

@@ -1 +1 @@
-{"version":3,"file":"lance-db.js","sourceRoot":"","sources":["../../../modules/oracle/adapters/lance-db.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lance-db.js","sourceRoot":"","sources":["../../../modules/oracle/adapters/lance-db.ts"],"names":[],"mappings":"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"}

package/modules/AGENTS.md

@@ -0,0 +1,78 @@
+# modules/ — Agent Instructions
+
+Supplements the root `AGENTS.md` / `copilot-instructions.md` with module-specific internals.
+When working inside this folder, follow these rules in addition to the root guidelines.
+
+---
+
+## File ownership
+
+### Oracle
+| File | Owns |
+|---|---|
+| `oracle/query.ts` | Two-pass retrieval (vector → BM25 → RRF fusion). Score threshold. Query log. |
+| `oracle/bm25.ts` | BM25 scoring algorithm. Domain term extraction for query enrichment. |
+| `oracle/propose.ts` | `propose()` + `commit()`. The human-gated write path. Do not add auto-commit logic here. |
+| `oracle/log.ts` | Best-effort JSONL query log writer. Must never throw to callers. |
+| `oracle/adapters/lance-db.ts` | LanceDB `VectorStore` implementation. Swappable — do not couple oracle internals to this. |
+| `oracle/adapters/xenova-embedder.ts` | Local ONNX embedder. Swappable — do not couple oracle internals to this. |
+
+### Jury
+| File | Owns |
+|---|---|
+| `jury/schema.ts` | Zod schema for structured LLM output. Source of truth for `JuryOutput` shape including `confidence_breakdown` and `blocking_gaps`. |
+| `jury/evaluate.ts` | Four-dimension evaluation. **Confidence is always recomputed from the breakdown average here — do not remove this. `council_brief` is also overridden from confidence.** |
+| `jury/preflight.ts` | Deterministic preflight — no LLM. Detects sensitive areas, rollback mention, and Chronicle conflicts before the LLM runs. Safe to extend with new patterns. |
+
+### Council
+| File | Owns |
+|---|---|
+| `council/personas.ts` | Default advisor personas. Safe to extend. Do not remove existing personas without good reason. |
+| `council/frame.ts` | Sets deliberation tone from `council_brief`. Challenge vs pressure-test framing lives here. |
+| `council/advisors.ts` | Parallel advisor fan-out. Advisors must cite Oracle entry IDs — enforced in the prompt. |
+| `council/reviewers.ts` | Anonymisation of advisor responses + parallel reviewer fan-out. Anonymisation must happen before reviewers see responses. |
+| `council/chairman.ts` | Verdict synthesis + Zod validation. Produces structured `blockers`/`warnings`, validates citations, tracks `advisor_split`. Throws on bad output — do not add fallbacks. |
+| `council/risk.ts` | Deterministic risk classifier — no LLM. Assigns `low/medium/high/critical` and `council_mode` from design text and refuted evidence. Drives advisor/reviewer fan-out counts. |
+| `council/deliberate.ts` | Full pipeline orchestration. Calls `oracle.propose()` at the end — never `oracle.commit()`. Risk classifier runs first to set fan-out counts. |
+
+### Advisor
+| File | Owns |
+|---|---|
+| `advisor/ask.ts` | Main entry point. Queries Oracle, calls LLM, validates answer against satisfaction threshold (confidence ≥ 0.7, no blockers). Retries up to 2 times with previous answer as context. Throws on bad LLM output — do not add fallbacks. |
+| `advisor/prompt.ts` | SYSTEM_PROMPT, evidence formatter, user prompt builder. The plain-language framing lives here. |
+| `advisor/types.ts` | `AdvisorInput`, `AdvisorAnswer`, `AdvisorOutput`, `AdvisorDeps` types. |
+
+---
+
+## Extension points
+
+**Swap the vector store** — implement `VectorStore` from `oracle/types.ts` and pass it to `createOracleClient()` or `setup()`.
+
+**Swap the embedder** — pass `embedder: yourFn` to `setup()`. Must return a consistent-dimension float array.
+
+**Add advisor personas** — extend `DEFAULT_PERSONAS` in `council/personas.ts`, or pass a custom personas array directly to `fanOutAdvisors()`.
+
+**Use different models per step** — pass `models` to `setup()` or `council.deliberate()` deps. Cheaper models for advisors, stronger for chairman is the intended pattern.
+
+---
+
+## Invariants — do not break these
+
+- `advisor/ask.ts` never calls `oracle.propose()` or `oracle.commit()`. It is a read-only path.
+- `oracle.commit()` is never called without explicit human input. `deliberate()` calls `propose()` only.
+- `jury/evaluate.ts` recomputes `confidence` as the exact average of `confidence_breakdown` dimensions — the LLM value is discarded.
+- `jury/evaluate.ts` derives `council_brief` from the recomputed confidence — never trusts the LLM value.
+- `chairman.ts` and `jury/evaluate.ts` throw on schema validation failure. Do not add try/catch that swallows these errors.
+- `deliberate.ts` passes `citation_validation.valid_ids` (not raw `evidence_cited`) to `oracle.propose()` — hallucinated IDs are stripped.
+- Query logging in `oracle/log.ts` is always best-effort — callers must not fail because of a log write error.
+- `VectorStore` and `embedder` are always injected — never imported directly inside Oracle logic.
+
+---
+
+## Tests
+
+```bash
+npx vitest run modules/
+```
+
+Tests live in `__tests__/` inside each module folder. Use `vi.fn()` for LLM providers and vector stores — never call a real LLM in tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@balpal4495/quorum",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "description": "Git-backed memory and design review for AI coding agents",
   "type": "module",
   "license": "MIT",
@@ -26,7 +26,11 @@
   },
   "files": [
     "dist/**",
-    "bin/**"
+    "bin/**",
+    "SETUP.md",
+    "GEMINI.md",
+    ".github/copilot-instructions.md",
+    "modules/AGENTS.md"
   ],
   "exports": {
     ".": "./dist/setup.js",