@balpal4495/quorum 3.0.4 → 3.1.1

package/.github/copilot-instructions.md

@@ -1,117 +0,0 @@
-# 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/CLAUDE.md

@@ -1,146 +0,0 @@
-# Quorum — Claude Code Instructions
-
-## Project overview
-
-Quorum is a portable reasoning layer for agentic codebases. Five TypeScript modules:
-
-```
-Advisor  →  plain-language Chronicle queries
-Oracle   →  Jury  →  Council  →  human gate  →  Executor
-Sentinel →  coverage + drift
-```
-
-Full module rules and design decisions: [modules/CLAUDE.md](modules/CLAUDE.md)
-File ownership map: [modules/AGENTS.md](modules/AGENTS.md)
-
----
-
-## Session protocol — run this every session
-
-This is not optional. Quorum is a self-improving system. It only improves if you use it.
-
-### On session start
-
-Run these before reading any code or proposing anything:
-
-```bash
-node bin/quorum.js advisor brief
-```
-
-This shows what's in Chronicle. Read it. It tells you what the team has already learned.
-
-Then query for the topic at hand:
-
-```bash
-node bin/quorum.js advisor query "topic of the work"
-```
-
-If there are relevant entries, treat them as ground truth. If there are none, that's useful to know too — it means you're working in undocumented territory.
-
-### During the session
-
-Before making any architectural decision, ask explicitly:
-
-```bash
-node bin/quorum.js advisor query "the specific decision you're about to make"
-```
-
-Examples:
-- `node bin/quorum.js advisor query "retry logic"`
-- `node bin/quorum.js advisor query "LLM validation"`
-- `node bin/quorum.js advisor query "CLI command structure"`
-
-If an entry is refuted, do not retry the approach. Surface the failure reason.
-
-### On session end
-
-For every significant decision made in the session, create a Chronicle proposal.
-
-What counts as Chronicle-worthy:
-- A new module or significant feature and its design rationale
-- An API or interface choice that will affect future sessions
-- A rejected approach and why it was rejected (important — prevents re-trying bad ideas)
-- A configuration or tooling decision that affects all future work
-- A failure or bug root cause that was non-obvious
-
-What does NOT need a Chronicle entry:
-- Routine code changes, style fixes, obvious bug fixes
-- Things already fully captured in git commit messages
-- Transient implementation details with no future impact
-
-**Template for a Chronicle proposal:**
-
-```javascript
-// Run with: node -e "..."
-const { randomUUID } = require('crypto')
-const { writeFileSync, mkdirSync } = require('fs')
-const path = require('path')
-
-mkdirSync('.chronicle/proposals', { recursive: true })
-
-const proposal = {
-  schema_version: 2,
-  topic: 'short label — module/area',
-  decision: 'One sentence: what was decided and why.',
-  key_insight: 'One sentence: what was decided and why.',   // same as decision
-  affected_areas: ['path/to/relevant/file.ts'],
-  scope: ['module-name', 'area-tag'],
-  alternatives_considered: ['Other approach that was considered'],
-  rejected_reason: ['Why the alternative was rejected'],
-  status: 'validated',      // or 'open' if still uncertain
-  confidence: 0.9,          // how certain you are this is right
-  source_module: 'council',
-  evidence_cited: [],
-  work_ref: { type: 'pr', ref: 'PR #N' },  // or spike/story
-}
-
-const id = randomUUID()
-writeFileSync(path.join('.chronicle', 'proposals', id + '.json'), JSON.stringify(proposal, null, 2), 'utf8')
-console.log('Proposed:', id.slice(0, 8), '—', proposal.topic)
-```
-
-After creating proposals, tell the user: "I've staged N Chronicle entries — run `quorum commit --list` to review."
-
----
-
-## Chronicle — the persistent knowledge store
-
-Chronicle lives at `.chronicle/`. It is the team's accumulated learning — what has been tried, what worked, what failed, and why decisions were made.
-
-**Rules:**
-- **Query first, always.** `node bin/quorum.js advisor query "topic"` before proposing any design.
-- **Never call `oracle.commit()` autonomously.** Use the proposal template above. A human must run `quorum commit <id>`.
-- **Cite entries by ID.** When referencing a Chronicle finding, use `[entry-id-prefix]`.
-- **Respect refuted entries.** If an entry is refuted, do not retry the approach without surfacing the failure reason to the user first.
-
----
-
-## Gemini CLI (optional assistant)
-
-```bash
-which gemini 2>/dev/null
-```
-
-If empty, skip. Never install it or ask the user to install it mid-task.
-
-**Use Gemini when:**
-- You need to survey many files at once before deciding where to look
-- You want to trace a pattern across the whole codebase
-- You want a second opinion on an architecture decision before proposing it
-
-```bash
-source ~/.zshrc && gemini -p "What are all the public exports across modules/ and what does each do?"
-source ~/.zshrc && find . -name "*.ts" | xargs cat | gemini -p "Find every place oracle.commit() is called"
-```
-
-Reason about Gemini's output — it assists, you decide. Never pass it unfiltered to the user.
-
----
-
-## Build and test
-
-```bash
-npx vitest run modules/ evals/
-```
-
-All 141 tests must pass before any PR.

package/GEMINI.md

@@ -1,73 +0,0 @@
-# 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

@@ -1,264 +0,0 @@
-# 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/evals/__tests__/eval.test.ts

@@ -1,31 +0,0 @@
-/**
- * Eval suite — runs all cases from evals/cases/ through deterministic checks.
- *
- * Deterministic assertions (preflight, risk classifier) run on every CI pass.
- * LLM-dependent assertions (jury confidence, council recommendation) are skipped
- * unless EVAL_LLM env var is set — they are too slow and costly for standard CI.
- *
- * To run with a real LLM locally:
- *   EVAL_LLM=1 OPENAI_API_KEY=sk-... npx vitest run evals/
- */
-import { describe, it, expect } from "vitest"
-import path from "path"
-import { loadCases, runCase } from "../runner"
-
-describe("eval suite — deterministic checks", async () => {
-  const cases = await loadCases(path.join(__dirname, "../cases"))
-
-  for (const evalCase of cases) {
-    it(`[${evalCase.id}] ${evalCase.description}`, async () => {
-      // No LLM — only runs deterministic assertions (preflight + risk classifier)
-      const result = await runCase(evalCase)
-
-      if (!result.passed) {
-        // Surface all failures clearly
-        throw new Error(
-          `Eval case "${evalCase.id}" failed:\n${result.failures.map(f => `  • ${f}`).join("\n")}`,
-        )
-      }
-    })
-  }
-})

package/evals/cases/auth_hs256_rejected.json

@@ -1,46 +0,0 @@
-{
-  "id": "auth_hs256_rejected",
-  "description": "Proposing HS256 JWT when RS256 was already chosen — should block",
-  "outcome": "Add JWT authentication to the API",
-  "design": "Use HS256 symmetric JWT tokens with a shared secret stored in environment variables",
-  "oracle_evidence": [
-    {
-      "id": "auth-022",
-      "key_insight": "HS256 JWT rejected — no way to rotate keys without invalidating all active sessions",
-      "decision": "HS256 JWT rejected — no way to rotate keys without invalidating all active sessions. Use RS256.",
-      "schema_version": 2,
-      "affected_areas": ["src/auth/", "src/middleware/"],
-      "scope": ["auth", "sessions"],
-      "status": "refuted",
-      "confidence": 0.91,
-      "source_module": "council",
-      "evidence_cited": [],
-      "timestamp": "2025-03-01T09:00:00Z"
-    },
-    {
-      "id": "auth-031",
-      "key_insight": "RS256 with short-lived tokens and refresh rotation in httpOnly cookies is the approved pattern",
-      "decision": "RS256 with 15-min access tokens and refresh rotation stored in httpOnly cookies is the approved auth pattern",
-      "schema_version": 2,
-      "affected_areas": ["src/auth/", "src/middleware/"],
-      "scope": ["auth", "sessions"],
-      "status": "validated",
-      "confidence": 0.88,
-      "source_module": "council",
-      "evidence_cited": ["auth-022"],
-      "timestamp": "2025-03-15T11:00:00Z"
-    }
-  ],
-  "expected": {
-    "jury_max_confidence": 0.45,
-    "council_recommendation": "redesign",
-    "must_flag": ["key rotation", "HS256"],
-    "must_cite": ["auth-022"],
-    "risk_level": "critical",
-    "preflight_expects": {
-      "touches_sensitive_area": true,
-      "sensitive_areas_include": ["auth"],
-      "chronicle_conflicts": ["auth-022"]
-    }
-  }
-}