@balpal4495/quorum 0.1.0

package/.github/copilot-instructions.md

@@ -0,0 +1,94 @@
+# Project Guidelines
+
+## Architecture
+
+This project uses three portable reasoning modules: **Oracle**, **Jury**, and **Council**.
+They form the knowledge and validation layer for all agentic work in this codebase.
+
+```
+oracle.query()  →  jury.evaluate()  →  council.deliberate()  →  human gate  →  Executor
+```
+
+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? |
+|---|---|---|
+| `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 |
+
+---
+
+## Setup
+
+```typescript
+import { setup } from "./modules/setup"
+
+const { oracle, evaluate, deliberate } = 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.
+
+---
+
+## Build and test
+
+```bash
+npx vitest run modules/
+```

package/CLAUDE.md

@@ -0,0 +1,86 @@
+# Quorum — Claude Code Instructions
+
+## Project overview
+
+Quorum is a portable reasoning layer for agentic codebases. Three TypeScript modules form
+the knowledge and validation layer for all agentic work:
+
+```
+oracle.query()  →  jury.evaluate()  →  council.deliberate()  →  human gate  →  Executor
+```
+
+Full module rules and design decisions: [modules/CLAUDE.md](modules/CLAUDE.md)
+File ownership map: [modules/AGENTS.md](modules/AGENTS.md)
+
+---
+
+## Gemini CLI (optional assistant)
+
+Before attempting any Gemini call, check availability:
+
+```bash
+which gemini 2>/dev/null
+```
+
+If the command returns empty, skip this section entirely. The project is fully functional
+without Gemini. Never try to install it or ask the user to install it mid-task.
+
+**If Gemini is available**, use it as a large-context assistant — it can hold the entire
+codebase in a single context window where you work best on focused, precise tasks.
+
+**Call `gemini -p "..."` when:**
+- You need to survey many files at once before deciding where to look
+- You want to trace a pattern, type, or call across the whole codebase
+- You want a second opinion on an architecture decision before proposing it to the user
+
+**Important:** The Bash tool does not auto-source shell profiles. Always prefix Gemini
+calls with `source ~/.zshrc &&` so that `GEMINI_API_KEY` and `GEMINI_CLI_TRUST_WORKSPACE`
+are loaded from the user's profile before invoking the CLI.
+
+**Patterns:**
+
+```bash
+# Broad survey before narrowing
+source ~/.zshrc && gemini -p "What are all the public exports across modules/ and what does each do?"
+
+# Trace a pattern across many files
+source ~/.zshrc && find . -name "*.ts" | xargs cat | gemini -p "Find every place oracle.commit() is called"
+
+# Second opinion on a design
+source ~/.zshrc && gemini -p "I'm about to add streaming to oracle/query.ts. Given the full codebase, what should I watch out for?"
+```
+
+**Processing Gemini responses:**
+- You reason about Gemini's output — it assists, you decide
+- If Gemini contradicts what you know from reading the code, trust your direct reading
+- Never pass Gemini's response to the user unfiltered; synthesise it through your own judgment
+
+---
+
+## Chronicle — the persistent knowledge store
+
+Chronicle lives at `.chronicle/`. Every prior decision, investigation finding, and outcome
+is stored there.
+
+- **Query Oracle before proposing any solution.** Treat entries as ground truth for what has
+  been tried, what worked, and what failed.
+- **Never call `oracle.commit()` autonomously.** Use `oracle.propose()` to stage an entry.
+  A human must call `oracle.commit(proposalId)` to index it. There are no exceptions.
+
+---
+
+## Rules for AI agents
+
+- **Evidence first.** Query Oracle before proposing any design or implementation.
+- **No auto-commits.** Never call `oracle.commit()` without explicit human input.
+- **Cite entries.** Use entry IDs (e.g. `[abc-123]`) when referencing Chronicle findings.
+- **Respect refuted entries.** Surface the failure reason — don't ignore it.
+- **Fail loudly.** Jury and Council throw on bad LLM output. Do not swallow errors.
+
+---
+
+## Build and test
+
+```bash
+npx vitest run modules/
+```

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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 balpal4495
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# Quorum
+
+Quorum is a portable reasoning layer for agentic codebases.
+
+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.
+
+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.
+
+---
+
+## What's inside
+
+Four portable 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. |
+| **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
+```
+
+---
+
+## How it works
+
+**Flow — system components and connections:**
+
+```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])
+```
+
+**Sequence — one full decision cycle:**
+
+```mermaid
+sequenceDiagram
+    participant Agent as AI Agent
+    participant Oracle
+    participant Jury
+    participant Council
+    participant Human
+    participant Chronicle
+
+    Agent->>Oracle: query(text)
+    Oracle->>Chronicle: vector search
+    Chronicle-->>Oracle: ranked entries
+    Oracle-->>Agent: OracleResult[]
+
+    Agent->>Jury: evaluate(design, evidence)
+    Jury-->>Agent: score, flags, passed
+
+    Agent->>Council: deliberate(design, evaluations)
+    Council-->>Agent: satisfied, verdict, proposal
+
+    alt Council not satisfied
+        Note over Agent: revise design and retry
+    else Council satisfied
+        Agent->>Human: surface verdict and proposal
+        Human->>Oracle: commit(proposalId)
+        Oracle->>Chronicle: upsert entry
+        Oracle-->>Human: ChronicleEntry
+    end
+```
+
+---
+
+## How to use it
+
+Run this from any Node.js project root:
+
+```bash
+npx @balpal4495/quorum@latest init
+```
+
+Quorum scaffolds itself — copying modules into `quorum/`, merging AI instruction files (CLAUDE.md, AGENTS.md), and initialising Chronicle. Then run `npm install`.
+
+For manual control or AI-assisted setup, tell your AI: *"follow quorum/SETUP.md"*.
+
+See [SETUP.md](SETUP.md) for the full bootstrap sequence.
+
+---
+
+## Chronicle
+
+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.
+
+```
+.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
+```
+
+`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.
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---|---|
+| `zod` | Structured LLM output validation |
+| `vectordb` | LanceDB embedded vector store (swappable) |
+| `@xenova/transformers` | Local ONNX embedder — all-MiniLM-L6-v2 (swappable) |
+
+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.
+
+---
+
+## Designed to be dropped in — not installed
+
+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`.
+
+---
+
+## Sentinel
+
+Sentinel answers three questions Chronicle cannot answer about itself.
+
+**Coverage** — which files have no Chronicle entries? These are the blind spots where agents have no prior knowledge to draw on.
+
+**Drift** — do existing Chronicle entries still accurately describe the code? Insights become stale without anyone noticing.
+
+**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.
+
+### In CI — coverage and drift as Vitest assertions
+
+```typescript
+import { describe } from "vitest"
+import { sentinelAssertions } from "./modules/sentinel/assert"
+
+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
+})
+
+describe("sentinel", () => { assertions.forEach(a => a()) })
+```
+
+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.
+
+Test files (`__tests__/`, `*.test.ts`, `*.spec.ts`) are excluded from tracking by default — only source files count toward coverage.
+
+### In PRs — the coverage map
+
+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 — 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    |
+
+[mermaid heatmap — Chronicle root → all modules, nodes coloured red/yellow/green by risk,
+ changed modules labelled with file count]
+
+### Chronicle context for changed modules
+**oracle/**
+- `[30bdc1c1]` schema constraints not LLM self-evaluation — validated (0.88)
+```
+
+On a new project with no Chronicle entries, the comment instead shows a bootstrap prompt guiding the team toward their first `oracle.propose()` call.
+
+```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])
+```
+
+---
+
+## Module 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