@balpal4495/quorum 0.1.0

package/SETUP.md

@@ -0,0 +1,256 @@
+# 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 — copying modules, merging instruction files, updating `package.json`, `.gitignore`, and creating the Chronicle directory.
+
+After it completes, run `npm install` and wire `setup()` into your entry point (see Step 6 below).
+
+---
+
+## 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/modules/README.md` — module overview and quick-start
+- `quorum/modules/AGENTS.md` — file ownership and invariants
+- `quorum/.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 dependencies
+
+Open `package.json` at the project root. Add the following to `dependencies` if they are not already present:
+
+```json
+"zod": "^3.23.0",
+"vectordb": "^0.4.0",
+"@xenova/transformers": "^2.17.0"
+```
+
+Then run:
+
+```bash
+npm install
+```
+
+If the project uses `yarn` or `pnpm`, use the appropriate installer instead.
+
+> `zod` is required for all structured LLM output validation.
+> `vectordb` is the LanceDB adapter (swappable — see `quorum/modules/oracle/adapters/`).
+> `@xenova/transformers` is the local ONNX embedder (swappable — see `quorum/modules/oracle/adapters/xenova-embedder.ts`).
+
+---
+
+## Step 4 — Merge AI instruction files
+
+### 4a. `.github/copilot-instructions.md`
+
+**If it does not exist:**
+Copy `quorum/.github/copilot-instructions.md` to `.github/copilot-instructions.md`.
+
+**If it already exists:**
+Append the entire contents of `quorum/.github/copilot-instructions.md` to the existing file, preceded by this separator:
+
+```markdown
+---
+
+<!-- Quorum: appended by setup -->
+```
+
+Do not replace or overwrite existing content.
+
+### 4b. `AGENTS.md`
+
+**If it does not exist:**
+Create `AGENTS.md` at the project root with this content:
+
+```markdown
+# Agent Instructions
+
+See [quorum/modules/AGENTS.md](quorum/modules/AGENTS.md) for Quorum module internals.
+See [.github/copilot-instructions.md](.github/copilot-instructions.md) for workflow rules.
+```
+
+**If it already exists:**
+Append to it:
+
+```markdown
+
+## Quorum modules
+
+See [quorum/modules/AGENTS.md](quorum/modules/AGENTS.md) for Oracle, Jury, and Council internals.
+```
+
+### 4c. `CLAUDE.md`
+
+**If it does not exist:**
+Create `CLAUDE.md` at the project root with this content:
+
+```markdown
+# Claude Instructions
+
+See [quorum/modules/CLAUDE.md](quorum/modules/CLAUDE.md) for Quorum module internals.
+See [.github/copilot-instructions.md](.github/copilot-instructions.md) for workflow rules.
+```
+
+**If it already exists:**
+Append to it:
+
+```markdown
+
+## Quorum modules
+
+See [quorum/modules/CLAUDE.md](quorum/modules/CLAUDE.md) for Oracle, Jury, and Council internals.
+```
+
+---
+
+## Step 5 — Update .gitignore
+
+**If `.gitignore` does not exist**, create it.
+
+Add the following block if it is not already present:
+
+```gitignore
+# Quorum — Chronicle
+# entries/ is a LanceDB binary vector store — do not commit
+.chronicle/entries/
+
+# proposals/ contains pending human-approval writes — commit these
+# (remove the line above if you want to ignore the whole store)
+```
+
+---
+
+## Step 6 — Wire setup() into the project
+
+Find the application entry point (e.g. `index.ts`, `server.ts`, `app.ts`, or equivalent).
+
+Add the following import and call at startup, **before** any agent or workflow code runs:
+
+```typescript
+import { setup } from "./quorum/modules/setup"
+
+const { oracle, evaluate, deliberate } = await setup({
+  llm: yourLLMProvider, // replace with your project's LLM provider function
+})
+```
+
+`setup()` creates `.chronicle/` directories, warms the embedder, and wires all module dependencies.
+It must be called once before any `oracle.query()`, `evaluate()`, or `deliberate()` call.
+
+If no entry point exists yet, note that `setup()` must be called before first use — do not inline it.
+
+---
+
+## Step 7 — Verify Chronicle is created
+
+Run the project (or call `setup()` in isolation). Confirm that `.chronicle/proposals/` exists after startup.
+
+```bash
+ls .chronicle/
+# expected: proposals/
+# entries/ will appear after the first oracle.commit()
+```
+
+If the directory is not created, re-check that `setup()` is being awaited correctly.
+
+---
+
+## Step 8 — Run module tests
+
+Confirm the modules are working in this environment:
+
+```bash
+npx vitest run quorum/modules/
+```
+
+All tests should pass. If they fail due to missing dependencies, re-run Step 3.
+
+---
+
+## Step 9 — Report what was done
+
+Once all steps are complete, report:
+
+1. Which files were created vs appended
+2. Which dependencies were added (if any were already present, note that)
+3. Whether tests passed
+4. The path to `setup()` in the entry point, and the LLM provider that was wired (or a note if it was left as a placeholder)
+5. 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.
+
+If you do have it (or want to add it later), this enables Claude Code to delegate large-context
+analysis to Gemini — useful when a task requires surveying the whole codebase at once.
+
+**10a. Install Gemini CLI** (if not already installed — requires Node.js 18+):
+
+```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 so Gemini understands the codebase.
+Copy `quorum/modules/AGENTS.md` content as a starting point, or write a brief description of
+the project and the Quorum architecture. The `GEMINI.md` in the Quorum repo itself is a
+working example.
+
+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/modules/AGENTS.md` and `.github/copilot-instructions.md` apply to all subsequent work.
+
+Key reminders:
+- **Query Oracle before proposing anything.** `oracle.query("what you're about to do")` first.
+- **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.

package/bin/init.js

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+/**
+ * quorum init
+ *
+ * Drops Quorum into an existing Node.js project.
+ * Run from the target project root:
+ *
+ *   npx github:balpal4495/Quorum init
+ *
+ * Zero external dependencies — uses only Node.js built-ins.
+ * Requires Node.js 18+.
+ */
+
+import { promises as fs } from "fs"
+import path from "path"
+import { fileURLToPath } from "url"
+import { execSync } from "child_process"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const QUORUM_ROOT = path.resolve(__dirname, "..")
+const TARGET = process.cwd()
+
+// ── Deps Quorum requires in the host project ───────────────────────────────
+
+const DEPS = {
+  zod: "^3.23.0",
+}
+
+const OPTIONAL_DEPS = {
+  vectordb: "^0.4.0",
+  "@xenova/transformers": "^2.17.0",
+}
+
+// ── Logging ────────────────────────────────────────────────────────────────
+
+const c = {
+  bold:  (s) => `\x1b[1m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  blue:  (s) => `\x1b[34m${s}\x1b[0m`,
+  dim:   (s) => `\x1b[90m${s}\x1b[0m`,
+  yellow:(s) => `\x1b[33m${s}\x1b[0m`,
+  red:   (s) => `\x1b[31m${s}\x1b[0m`,
+}
+
+const log = {
+  section: (title) => console.log(`\n${c.bold(title)}`),
+  created: (file)  => console.log(`  ${c.green("+ created ")} ${file}`),
+  appended:(file)  => console.log(`  ${c.blue("~ appended")} ${file}`),
+  skipped: (file)  => console.log(`  ${c.dim("· skipped ")} ${file}`),
+  warn:    (msg)   => console.log(`  ${c.yellow("⚠ " + msg)}`),
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+async function exists(p) {
+  return fs.access(p).then(() => true).catch(() => false)
+}
+
+async function readJson(p) {
+  return JSON.parse(await fs.readFile(p, "utf8"))
+}
+
+function geminiAvailable() {
+  try {
+    execSync("which gemini", { stdio: "ignore" })
+    return true
+  } catch {
+    return false
+  }
+}
+
+// ── Steps ──────────────────────────────────────────────────────────────────
+
+async function guardAlreadyInitialized() {
+  if (await exists(path.join(TARGET, "quorum", "modules"))) {
+    console.log(c.yellow("\nQuorum is already initialized in this project."))
+    console.log("Remove quorum/ first if you want to reinitialize.\n")
+    process.exit(0)
+  }
+}
+
+async function copyModules() {
+  log.section("Copying modules")
+
+  const src  = path.join(QUORUM_ROOT, "modules")
+  const dest = path.join(TARGET, "quorum", "modules")
+  await fs.cp(src, dest, {
+    recursive: true,
+    filter: (src) =>
+      !src.includes("__tests__") &&
+      !src.includes(".test.ts") &&
+      !src.includes(".spec.ts"),
+  })
+  log.created("quorum/modules/")
+
+  await fs.copyFile(
+    path.join(QUORUM_ROOT, "SETUP.md"),
+    path.join(TARGET, "quorum", "SETUP.md"),
+  )
+  log.created("quorum/SETUP.md")
+}
+
+async function mergeCopilotInstructions() {
+  log.section("Merging AI instruction files")
+
+  const src     = path.join(QUORUM_ROOT, ".github", "copilot-instructions.md")
+  const dest    = path.join(TARGET, ".github", "copilot-instructions.md")
+  const content = await fs.readFile(src, "utf8")
+
+  await fs.mkdir(path.join(TARGET, ".github"), { recursive: true })
+
+  if (await exists(dest)) {
+    const existing = await fs.readFile(dest, "utf8")
+    if (existing.includes("<!-- quorum -->")) {
+      log.skipped(".github/copilot-instructions.md (already present)")
+      return
+    }
+    await fs.appendFile(dest, `\n\n---\n\n<!-- quorum -->\n${content}`, "utf8")
+    log.appended(".github/copilot-instructions.md")
+  } else {
+    await fs.writeFile(dest, content, "utf8")
+    log.created(".github/copilot-instructions.md")
+  }
+}
+
+async function mergeAgentsMd() {
+  const dest    = path.join(TARGET, "AGENTS.md")
+  const section = [
+    "",
+    "## Quorum modules",
+    "",
+    "See [quorum/modules/AGENTS.md](quorum/modules/AGENTS.md) for Oracle, Jury, and Council internals.",
+    "See [.github/copilot-instructions.md](.github/copilot-instructions.md) for workflow rules.",
+    "",
+  ].join("\n")
+
+  if (await exists(dest)) {
+    const existing = await fs.readFile(dest, "utf8")
+    if (existing.includes("quorum/modules/AGENTS.md")) {
+      log.skipped("AGENTS.md (already present)")
+      return
+    }
+    await fs.appendFile(dest, section, "utf8")
+    log.appended("AGENTS.md")
+  } else {
+    await fs.writeFile(dest, `# Agent Instructions\n${section}`, "utf8")
+    log.created("AGENTS.md")
+  }
+}
+
+async function mergeClaudeMd() {
+  const dest = path.join(TARGET, "CLAUDE.md")
+  const section = `
+## Quorum modules
+
+See [quorum/modules/CLAUDE.md](quorum/modules/CLAUDE.md) for Oracle, Jury, and Council internals.
+See [.github/copilot-instructions.md](.github/copilot-instructions.md) for workflow rules.
+
+## 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 for tasks that require
+surveying many files at once — it can hold the entire codebase in a single context window.
+
+\`\`\`bash
+# The Bash tool does not auto-source shell profiles — always prefix with source:
+source ~/.zshrc && gemini -p "Summarise the public API across all modules"
+source ~/.zshrc && gemini -p "I'm about to change X. What should I watch out for?"
+\`\`\`
+
+You reason about Gemini's output — it assists, you decide. Never pass its response to the
+user unfiltered. If Gemini contradicts what you know from reading the code, trust your reading.
+`
+
+  if (await exists(dest)) {
+    const existing = await fs.readFile(dest, "utf8")
+    if (existing.includes("quorum/modules/CLAUDE.md")) {
+      log.skipped("CLAUDE.md (already present)")
+      return
+    }
+    await fs.appendFile(dest, section, "utf8")
+    log.appended("CLAUDE.md")
+  } else {
+    await fs.writeFile(dest, `# Claude Instructions\n${section}`, "utf8")
+    log.created("CLAUDE.md")
+  }
+}
+
+async function mergeGeminiMd() {
+  const dest = path.join(TARGET, "GEMINI.md")
+
+  if (await exists(dest)) {
+    log.skipped("GEMINI.md (already present)")
+    return
+  }
+
+  if (!geminiAvailable()) {
+    log.skipped("GEMINI.md (Gemini CLI not detected — install it later to enable)")
+    return
+  }
+
+  const src = path.join(QUORUM_ROOT, "GEMINI.md")
+  if (await exists(src)) {
+    await fs.copyFile(src, dest)
+    log.created("GEMINI.md")
+  }
+}
+
+async function updatePackageJson() {
+  log.section("Updating package.json")
+
+  const pkgPath = path.join(TARGET, "package.json")
+  let pkg
+
+  if (await exists(pkgPath)) {
+    pkg = await readJson(pkgPath)
+  } else {
+    pkg = { name: path.basename(TARGET), version: "0.1.0", private: true }
+    log.warn("No package.json found — creating a minimal one")
+  }
+
+  pkg.dependencies         = pkg.dependencies         ?? {}
+  pkg.optionalDependencies = pkg.optionalDependencies ?? {}
+
+  const added = []
+
+  for (const [name, version] of Object.entries(DEPS)) {
+    if (!pkg.dependencies[name]) {
+      pkg.dependencies[name] = version
+      added.push(name)
+    }
+  }
+
+  for (const [name, version] of Object.entries(OPTIONAL_DEPS)) {
+    if (!pkg.optionalDependencies[name]) {
+      pkg.optionalDependencies[name] = version
+      added.push(`${name} (optional)`)
+    }
+  }
+
+  await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8")
+
+  if (added.length > 0) {
+    log.appended(`package.json — added: ${added.join(", ")}`)
+  } else {
+    log.skipped("package.json (all deps already present)")
+  }
+}
+
+async function updateGitignore() {
+  log.section("Updating .gitignore")
+
+  const dest  = path.join(TARGET, ".gitignore")
+  const block = [
+    "",
+    "# Quorum — Chronicle",
+    "# entries/ is a binary vector store — do not commit",
+    ".chronicle/entries/",
+    ".chronicle/query-log.jsonl",
+    "",
+  ].join("\n")
+
+  if (await exists(dest)) {
+    const existing = await fs.readFile(dest, "utf8")
+    if (existing.includes(".chronicle/entries/")) {
+      log.skipped(".gitignore (already present)")
+      return
+    }
+    await fs.appendFile(dest, block, "utf8")
+    log.appended(".gitignore")
+  } else {
+    await fs.writeFile(dest, block.trimStart(), "utf8")
+    log.created(".gitignore")
+  }
+}
+
+async function createChronicle() {
+  log.section("Creating Chronicle")
+
+  await fs.mkdir(path.join(TARGET, ".chronicle", "proposals"), { recursive: true })
+  log.created(".chronicle/proposals/")
+
+  await fs.mkdir(path.join(TARGET, ".chronicle", "committed"), { recursive: true })
+  log.created(".chronicle/committed/")
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log(c.bold("\nQuorum init"))
+  console.log(`Target: ${c.dim(TARGET)}\n`)
+
+  if (TARGET === QUORUM_ROOT) {
+    console.log(c.yellow("Run this from your project directory, not the Quorum repo itself."))
+    process.exit(1)
+  }
+
+  await guardAlreadyInitialized()
+  await copyModules()
+  await mergeCopilotInstructions()
+  await mergeAgentsMd()
+  await mergeClaudeMd()
+  await mergeGeminiMd()
+  await updatePackageJson()
+  await updateGitignore()
+  await createChronicle()
+
+  const hasGemini = geminiAvailable()
+
+  console.log(`\n${c.green("✓ Quorum initialized.")}`)
+  console.log("\nNext steps:")
+  console.log("  1. npm install")
+  console.log("  2. Wire setup() into your entry point:\n")
+  console.log(c.dim('     import { setup } from "./quorum/modules/setup"'))
+  console.log(c.dim('     const { oracle, evaluate, deliberate } = await setup({ llm: yourProvider })'))
+  console.log("\n  Or tell your AI: \"follow quorum/SETUP.md\"")
+
+  if (!hasGemini) {
+    console.log(`\n  ${c.dim("Optional: install Gemini CLI for large-context assistance")}`)
+    console.log(c.dim("  npm install -g @google/gemini-cli  +  set GEMINI_API_KEY"))
+    console.log(c.dim("  See quorum/SETUP.md Step 10 for details."))
+  } else {
+    console.log(`\n  ${c.green("✓ Gemini CLI detected")} — GEMINI.md written. Set GEMINI_API_KEY if not already set.`)
+  }
+
+  console.log("")
+}
+
+async function cli() {
+  const command = process.argv[2] ?? ""
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    console.log(`\n${c.bold("quorum")} — portable reasoning layer for agentic codebases\n`)
+    console.log("Usage:")
+    console.log(`  ${c.blue("npx @balpal4495/quorum init")}        Scaffold Quorum into a project (or meld into an existing one)`)
+    console.log(`  ${c.blue("npx quorum --version")}   Print version\n`)
+    return
+  }
+
+  if (command === "--version" || command === "-v" || command === "version") {
+    console.log("0.1.0")
+    return
+  }
+
+  if (command === "init") {
+    await main()
+    return
+  }
+
+  console.error(c.red(`\nUnknown command: ${command}`))
+  console.error("Run 'npx quorum help' for usage.")
+  process.exit(1)
+}
+
+cli().catch((err) => {
+  console.error(c.red("\nQuorum failed:"), err.message)
+  process.exit(1)
+})

package/modules/AGENTS.md

@@ -0,0 +1,66 @@
+# 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. |
+| `jury/evaluate.ts` | Four-dimension evaluation. **`council_brief` is always overridden from confidence here — do not remove this enforcement.** |
+
+### 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. Throws on bad output — do not add fallbacks. |
+| `council/deliberate.ts` | Full pipeline orchestration. Calls `oracle.propose()` at the end — never `oracle.commit()`. |
+
+---
+
+## 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
+
+- `oracle.commit()` is never called without explicit human input. `deliberate()` calls `propose()` only.
+- `jury/evaluate.ts` always computes `council_brief` from `confidence` after parsing — 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.
+- 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.