@balpal4495/quorum 0.3.0 → 0.4.2

package/README.md

@@ -22,6 +22,97 @@ That's the whole setup. Quorum copies its modules into `quorum/`, merges instruc
 
 ---
 
+## CLI commands
+
+After `npm install -g @balpal4495/quorum` (or `npx @balpal4495/quorum`), you get:
+
+| Command | What it does | LLM? |
+|---|---|---|
+| `quorum init` | Scaffold Quorum into a project | No |
+| `quorum status` | Chronicle health — pending proposals, committed entries, recent activity | No |
+| `quorum check --outcome X --design Y` | Deterministic preflight + risk classifier | No |
+| `quorum commit <id>` | Approve and index a pending proposal | No |
+| `quorum sentinel [coverage]` | Chronicle coverage of your source files | No |
+
+### `quorum check` — instant risk triage before the full pipeline
+
+```bash
+quorum check \
+  --outcome "migrate auth from sessions to JWT" \
+  --design "replace session middleware with HS256 tokens on all routes"
+```
+
+```
+Preflight
+  ⚠  Sensitive areas: auth
+  ✗  No rollback strategy mentioned
+  ✗  No test strategy mentioned
+
+Risk
+  Level:        CRITICAL
+  Council mode: full
+  Reasons:
+    · authentication or authorisation logic
+
+  ⚠  Critical risk — human architecture review required before proceeding.
+```
+
+Exit codes: `0` = low/medium, `1` = high, `2` = critical — pipe into CI scripts directly.
+Also accepts JSON on stdin: `echo '{"outcome":"…","design":"…"}' | quorum check --json`
+
+### `quorum status` — see what's pending and what's been learned
+
+```bash
+quorum status
+```
+
+```
+Chronicle status  .chronicle/
+
+     8  committed entries  (6 accepted, 1 refuted, 1 other)
+     2  pending proposals
+
+Pending proposals  (awaiting quorum commit <id>)
+  a1b2c3d4  JWT key rotation approach needs RS256 not HS256
+            oracle/propose.ts, modules/auth/
+
+Recent entries
+  e5f6a7b8  [accepted]  Shadow column migration avoids exclusive lock on 50M rows  2d ago
+```
+
+### `quorum commit <id>` — the human gate from your terminal
+
+```bash
+quorum commit --list        # see pending proposals with full detail
+quorum commit a1b2c3d4      # approve and index (supports partial ID prefix)
+quorum commit a1b2c3d4 --dry-run  # preview without writing
+```
+
+Embeds the entry via the local ONNX model, upserts to LanceDB, writes to `.chronicle/committed/`, updates `SUMMARY.md`, and removes the proposal — the full oracle commit in one command. Requires `@xenova/transformers` and `vectordb` to be installed (both are optional deps from `quorum init`).
+
+### `quorum sentinel coverage` — see where Chronicle goes dark
+
+```bash
+quorum sentinel coverage --path modules
+```
+
+```
+Chronicle coverage  modules/
+
+  ████░░░░░░░░░░░░░░░░  20%  (6/30 files)
+
+Covered
+  ✓  oracle/propose.ts  (3 entries)
+  ✓  oracle/query.ts    (1 entry)
+
+Uncovered  (no Chronicle entries reference these files)
+  ✗  council/chairman.ts
+  ✗  jury/evaluate.ts
+  …
+```
+
+---
+
 ## Then just talk to your AI
 
 Once initialized, open your AI in agent mode and tell it:
@@ -54,7 +145,14 @@ Every proposal goes through Jury (confidence scoring against evidence) and Counc
 
 ### You approve what gets remembered
 
-When a decision is made, your AI stages a Chronicle entry using `oracle.propose()`. You approve it with `oracle.commit(proposalId)`. Nothing is indexed without your explicit sign-off.
+When a decision is made, your AI stages a Chronicle entry using `oracle.propose()`. You approve it from the terminal:
+
+```bash
+quorum commit --list        # see what's pending
+quorum commit <id>          # approve and index
+```
+
+Nothing is indexed without your explicit sign-off.
 
 ```
 .chronicle/
@@ -65,11 +163,11 @@ When a decision is made, your AI stages a Chronicle entry using `oracle.propose(
 
 Commit `.chronicle/committed/` to git. Future sessions — and your teammates' sessions — start with that context.
 
-### Every merged PR creates a Chronicle proposal automatically
+### Every merged PR can create a Chronicle proposal automatically
 
-A GitHub Actions workflow fires when any PR merges to main. It creates a Chronicle proposal capturing the decision, which files changed, and any explicitly deferred items from the PR description. The proposal sits in `proposals/` until you commit it — nothing is auto-indexed.
+Quorum ships a GitHub Actions workflow (`chronicle-on-merge.yml`) that fires when any PR merges to main. It creates a Chronicle proposal capturing the decision, which files changed, and any explicitly deferred items from the PR description. The proposal sits in `proposals/` until you commit it — nothing is auto-indexed.
 
-This means the gap between "PR merged" and "Chronicle knows about it" is now zero.
+To enable this in your project, copy `.github/workflows/chronicle-on-merge.yml` and `scripts/chronicle-pr.js` from the [Quorum repo](https://github.com/balpal4495/Quorum) into your own repo.
 
 ---
 
@@ -253,9 +351,14 @@ Sentinel surfaces two things Chronicle can't tell you about itself.
 
 **Coverage** — which parts of your codebase has the AI never documented?
 
-**Drift** — do existing Chronicle entries still accurately describe the code, or have they gone stale?
+```bash
+quorum sentinel coverage --path src   # quick check from the terminal
+quorum sentinel coverage --json       # machine-readable, for scripts
+```
+
+**Drift** — do existing Chronicle entries still accurately describe the code, or have they gone stale? Drift detection requires an LLM; use `sentinelAssertions({ llm })` in your test suite (the CLI surfaces the message and directs you there).
 
-Add `sentinel-pr.yml` (included in `quorum/`) to your GitHub Actions and every PR gets a comment showing a full-project coverage table and a colour-coded heatmap. Changed modules are highlighted. Reviewers see exactly where knowledge is solid and where it goes dark.
+To get a coverage comment on every PR, copy `.github/workflows/sentinel-pr.yml` from the [Quorum repo](https://github.com/balpal4495/Quorum) into your project. Every PR then gets a comment showing a full-project coverage table and a colour-coded heatmap. Changed modules are highlighted. Reviewers see exactly where knowledge is solid and where it goes dark.
 
 ---
 

package/SETUP.md

@@ -31,7 +31,7 @@ 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
+- `.github/copilot-instructions.md` — workflow rules for AI agents (installed at project root by init)
 
 These are your operating instructions for everything that follows.
 
@@ -80,16 +80,20 @@ If the project uses `yarn` or `pnpm`, use the appropriate installer instead.
 
 ### 4a. `.github/copilot-instructions.md`
 
-**If it does not exist:**
-Copy `quorum/.github/copilot-instructions.md` to `.github/copilot-instructions.md`.
+The automated init command (`npx @balpal4495/quorum@latest init`) handles this step automatically — it creates or appends to `.github/copilot-instructions.md` at the project root.
 
-**If it already exists:**
-Append the entire contents of `quorum/.github/copilot-instructions.md` to the existing file, preceded by this separator:
+**If you are completing this step manually:**
+
+Check whether `.github/copilot-instructions.md` already exists.
+
+**If it does not exist:** Fetch the Quorum copilot instructions from the Quorum GitHub repo (`balpal4495/Quorum`) at `.github/copilot-instructions.md` and write it to `.github/copilot-instructions.md` in the project root.
+
+**If it already exists and does not contain `<!-- quorum -->`:** Append the Quorum instructions to the existing file, preceded by:
 
 ```markdown
 ---
 
-<!-- Quorum: appended by setup -->
+<!-- quorum -->
 ```
 
 Do not replace or overwrite existing content.
@@ -176,6 +180,16 @@ It must be called once before any `oracle.query()`, `evaluate()`, or `deliberate
 
 If no entry point exists yet, note that `setup()` must be called before first use — do not inline it.
 
+**Approving Chronicle proposals:** after an agent calls `oracle.propose()`, approve and index the entry from the terminal:
+
+```bash
+quorum commit --list         # see pending proposals
+quorum commit <id>           # approve and index a proposal
+quorum commit <id> --dry-run # preview without writing
+```
+
+Requires `@xenova/transformers` and `vectordb` (both added in Step 3).
+
 ---
 
 ## Step 7 — Verify Chronicle is created
@@ -260,3 +274,17 @@ 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.
+
+### CLI quick reference
+
+These commands are available globally after `npm install -g @balpal4495/quorum`:
+
+| Command | What it does |
+|---|---|
+| `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 check` exit codes: `0` = low/medium risk · `1` = high · `2` = critical

package/bin/commands/check.js

@@ -0,0 +1,122 @@
+import { createInterface } from "readline"
+import { c } from "../shared/colors.js"
+import { runPreflight, classifyRisk } from "../shared/patterns.js"
+
+function parseArgs(argv) {
+  const args = { outcome: "", design: "", json: false }
+  for (let i = 0; i < argv.length; i++) {
+    if ((argv[i] === "--outcome" || argv[i] === "-o") && argv[i + 1]) { args.outcome = argv[++i]; continue }
+    if ((argv[i] === "--design"  || argv[i] === "-d") && argv[i + 1]) { args.design  = argv[++i]; continue }
+    if (argv[i] === "--json") { args.json = true; continue }
+  }
+  return args
+}
+
+async function readStdin() {
+  if (process.stdin.isTTY) return null
+  return new Promise((resolve) => {
+    let data = ""
+    const rl = createInterface({ input: process.stdin })
+    rl.on("line",  (line) => { data += line + "\n" })
+    rl.on("close", () => resolve(data.trim()))
+  })
+}
+
+function riskColor(level) {
+  switch (level) {
+    case "low":      return c.green(level.toUpperCase())
+    case "medium":   return c.yellow(level.toUpperCase())
+    case "high":     return c.red(level.toUpperCase())
+    case "critical": return `${c.bold(c.red("CRITICAL"))}`
+    default:         return level.toUpperCase()
+  }
+}
+
+function exitCodeForLevel(level) {
+  if (level === "critical") return 2
+  if (level === "high")     return 1
+  return 0
+}
+
+export async function run(argv) {
+  const args = parseArgs(argv)
+
+  // Accept JSON from stdin if no flags provided
+  if (!args.outcome && !args.design) {
+    const stdin = await readStdin()
+    if (stdin) {
+      try {
+        const parsed = JSON.parse(stdin)
+        args.outcome = parsed.outcome ?? ""
+        args.design  = parsed.design  ?? ""
+      } catch {
+        console.error(c.red("stdin: expected JSON with { outcome, design } or use --outcome / --design flags"))
+        process.exit(1)
+      }
+    }
+  }
+
+  if (!args.outcome && !args.design) {
+    console.error(`\n${c.bold("quorum check")} — run preflight and risk classifier (no LLM required)\n`)
+    console.error("Usage:")
+    console.error(`  quorum check --outcome "what you want to achieve" --design "how you plan to do it"`)
+    console.error(`  echo '{"outcome":"...","design":"..."}' | quorum check`)
+    console.error(`  quorum check --outcome "..." --design "..." --json\n`)
+    console.error("Exit codes:  0 = low/medium risk   1 = high risk   2 = critical risk\n")
+    process.exit(1)
+  }
+
+  const preflight = runPreflight(args.outcome, args.design)
+  const risk      = classifyRisk(args.outcome, args.design)
+
+  if (args.json) {
+    console.log(JSON.stringify({ preflight, risk }, null, 2))
+    process.exit(exitCodeForLevel(risk.level))
+  }
+
+  // ── Human-readable output ─────────────────────────────────────────────────
+  console.log(`\n${c.bold("Preflight")}`)
+
+  if (preflight.touches_sensitive_area) {
+    console.log(`  ${c.yellow("⚠")}  Sensitive areas: ${c.yellow(preflight.sensitive_areas.join(", "))}`)
+  } else {
+    console.log(`  ${c.green("✓")}  No sensitive areas detected`)
+  }
+
+  console.log(preflight.rollback_mentioned
+    ? `  ${c.green("✓")}  Rollback strategy mentioned`
+    : `  ${c.dim("✗")}  No rollback strategy mentioned`)
+
+  console.log(preflight.test_strategy_mentioned
+    ? `  ${c.green("✓")}  Test strategy mentioned`
+    : `  ${c.dim("✗")}  No test strategy mentioned`)
+
+  console.log(`\n${c.bold("Risk")}`)
+  console.log(`  Level:        ${riskColor(risk.level)}`)
+  console.log(`  Council mode: ${c.dim(risk.council_mode)}`)
+
+  if (risk.reasons.length > 0 && risk.reasons[0] !== "no sensitive patterns detected") {
+    console.log(`  Reasons:`)
+    for (const reason of risk.reasons) {
+      console.log(`    ${c.dim("·")} ${reason}`)
+    }
+  }
+
+  // ── Actionable guidance ───────────────────────────────────────────────────
+  if (risk.level === "critical") {
+    console.log(`\n  ${c.red("⚠  Critical risk — human architecture review required before proceeding.")}`)
+    console.log(`  ${c.dim("   Run the full Jury + Council pipeline and get explicit approval.")}`)
+  } else if (risk.level === "high") {
+    console.log(`\n  ${c.yellow("⚠  High risk — full Council deliberation recommended.")}`)
+    if (!preflight.rollback_mentioned) {
+      console.log(`  ${c.dim("   Add a rollback strategy before submitting for review.")}`)
+    }
+  } else if (risk.level === "medium") {
+    console.log(`\n  ${c.dim("   Medium risk — Jury + lite Council review.")}`)
+  } else {
+    console.log(`\n  ${c.dim("   Low risk — Jury-only review sufficient.")}`)
+  }
+
+  console.log("")
+  process.exit(exitCodeForLevel(risk.level))
+}

package/bin/commands/commit.js

@@ -0,0 +1,210 @@
+import { promises as fs } from "fs"
+import path from "path"
+import { randomUUID } from "crypto"
+import { exec } from "child_process"
+import { promisify } from "util"
+import { c } from "../shared/colors.js"
+import { findChronicleDir, entryText, updateSummary } from "../shared/chronicle.js"
+
+const execAsync = promisify(exec)
+
+function parseArgs(argv) {
+  const args = { id: null, dryRun: false, list: false }
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--dry-run") { args.dryRun = true; continue }
+    if (argv[i] === "--list")    { args.list   = true; continue }
+    if (!argv[i].startsWith("-")) args.id = argv[i]
+  }
+  return args
+}
+
+async function checkDep(name) {
+  try {
+    await import(name)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function spinner(msg) {
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+  let i = 0
+  const interval = setInterval(() => {
+    process.stdout.write(`\r  ${c.cyan(frames[i++ % frames.length])}  ${msg}`)
+  }, 80)
+  return { stop: (finalMsg) => { clearInterval(interval); process.stdout.write(`\r  ${finalMsg}\n`) } }
+}
+
+export async function run(argv) {
+  const args = parseArgs(argv)
+
+  const chronicleDir = await findChronicleDir(process.cwd())
+  if (!chronicleDir) {
+    console.error(`\n${c.red("No .chronicle/ directory found.")} Run ${c.bold("quorum init")} first.\n`)
+    process.exit(1)
+  }
+
+  // ── --list: show pending proposals ────────────────────────────────────────
+  if (args.list || (!args.id && argv.length === 0)) {
+    const proposalsDir = path.join(chronicleDir, "proposals")
+    let files
+    try { files = await fs.readdir(proposalsDir) } catch { files = [] }
+    const proposals = []
+    for (const f of files) {
+      if (!f.endsWith(".json")) continue
+      try {
+        const raw = await fs.readFile(path.join(proposalsDir, f), "utf8")
+        proposals.push({ id: f.replace(".json", ""), ...JSON.parse(raw) })
+      } catch { /* skip */ }
+    }
+    if (proposals.length === 0) {
+      console.log(`\n${c.dim("No pending proposals.")}\n`)
+      return
+    }
+    console.log(`\n${c.bold("Pending proposals")}\n`)
+    for (const p of proposals) {
+      console.log(`  ${c.cyan(p.id)}`)
+      console.log(`    ${c.bold("key_insight:")} ${entryText(p)}`)
+      console.log(`    ${c.bold("areas:")}       ${(p.affected_areas ?? []).join(", ")}`)
+      console.log(`    ${c.bold("confidence:")}  ${p.confidence}`)
+      if (p.status) console.log(`    ${c.bold("status:")}      ${p.status}`)
+      console.log("")
+    }
+    console.log(c.dim(`  quorum commit <id>  to approve and index a proposal`))
+    console.log("")
+    return
+  }
+
+  if (!args.id) {
+    console.error(`\n${c.bold("quorum commit")} — approve and index a Chronicle proposal\n`)
+    console.error("Usage:")
+    console.error(`  quorum commit <proposalId>       Commit and index the proposal`)
+    console.error(`  quorum commit <proposalId> --dry-run   Preview without writing`)
+    console.error(`  quorum commit --list                   List pending proposals\n`)
+    process.exit(1)
+  }
+
+  // ── Find proposal (supports partial ID prefix) ────────────────────────────
+  const proposalsDir = path.join(chronicleDir, "proposals")
+  let files
+  try { files = await fs.readdir(proposalsDir) } catch { files = [] }
+
+  const match = files.find(f => f === `${args.id}.json` || f.startsWith(args.id))
+  if (!match) {
+    console.error(`\n${c.red("Proposal not found:")} ${args.id}`)
+    console.error(c.dim(`  Run ${c.bold("quorum commit --list")} to see pending proposals.\n`))
+    process.exit(1)
+  }
+
+  const proposalId   = match.replace(".json", "")
+  const proposalPath = path.join(proposalsDir, match)
+
+  let raw
+  try { raw = await fs.readFile(proposalPath, "utf8") } catch {
+    console.error(`\n${c.red("Could not read proposal:")} ${proposalPath}\n`)
+    process.exit(1)
+  }
+  const partial = JSON.parse(raw)
+
+  // ── Dry run ────────────────────────────────────────────────────────────────
+  if (args.dryRun) {
+    console.log(`\n${c.bold("Dry run")} — would commit proposal ${c.cyan(proposalId.slice(0, 8))}\n`)
+    console.log(`  ${c.bold("key_insight:")} ${entryText(partial)}`)
+    console.log(`  ${c.bold("areas:")}       ${(partial.affected_areas ?? []).join(", ")}`)
+    console.log(`  ${c.bold("status:")}      ${partial.status}`)
+    console.log(`  ${c.bold("confidence:")}  ${partial.confidence}`)
+    if (partial.scope?.length) console.log(`  ${c.bold("scope:")}       ${partial.scope.join(", ")}`)
+    console.log(`\n  ${c.dim("(No changes made.)")}\n`)
+    return
+  }
+
+  // ── Check optional dependencies ────────────────────────────────────────────
+  console.log(`\n${c.bold("Checking dependencies")}`)
+  const hasXenova  = await checkDep("@xenova/transformers")
+  const hasLanceDB = await checkDep("vectordb")
+
+  if (!hasXenova) {
+    console.error(`\n  ${c.red("✗")}  @xenova/transformers not installed`)
+    console.error(c.dim("     Run: npm install @xenova/transformers\n"))
+    process.exit(1)
+  }
+  if (!hasLanceDB) {
+    console.error(`\n  ${c.red("✗")}  vectordb not installed`)
+    console.error(c.dim("     Run: npm install vectordb\n"))
+    process.exit(1)
+  }
+  console.log(`  ${c.green("✓")}  @xenova/transformers`)
+  console.log(`  ${c.green("✓")}  vectordb`)
+
+  // ── Build entry ────────────────────────────────────────────────────────────
+  const entry = {
+    ...partial,
+    id: randomUUID(),
+    timestamp: new Date().toISOString(),
+  }
+
+  // ── Embed ──────────────────────────────────────────────────────────────────
+  const spin = spinner("Loading embedder (first run may take 30s)…")
+  let vector
+  try {
+    const { pipeline } = (await import("@xenova/transformers")).default ?? await import("@xenova/transformers")
+    const embedder = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2")
+    const embeddingText = [
+      entryText(entry),
+      ...(entry.affected_areas ?? []),
+      ...(entry.scope ?? []),
+    ].join(" ")
+    const output = await embedder(embeddingText, { pooling: "mean", normalize: true })
+    vector = Array.from(output.data)
+    spin.stop(`${c.green("✓")}  Embedded (${vector.length}-dim)`)
+  } catch (err) {
+    spin.stop(`${c.red("✗")}  Embedding failed`)
+    console.error(c.red(`\n  ${err.message}\n`))
+    process.exit(1)
+  }
+
+  // ── Store in LanceDB ───────────────────────────────────────────────────────
+  const storeSpin = spinner("Indexing in Chronicle…")
+  try {
+    const lancedb = (await import("vectordb")).default ?? (await import("vectordb"))
+    const tableDir = path.join(chronicleDir, "entries")
+    const db = await lancedb.connect(tableDir)
+    const row = { id: entry.id, vector, payload: JSON.stringify(entry) }
+    const names = await db.tableNames()
+    if (names.includes("entries")) {
+      const table = await db.openTable("entries")
+      await table.delete(`id = '${entry.id.replace(/'/g, "''")}'`)
+      await table.add([row])
+    } else {
+      await db.createTable("entries", [row], { metric: "cosine" })
+    }
+    storeSpin.stop(`${c.green("✓")}  Indexed in vector store`)
+  } catch (err) {
+    storeSpin.stop(`${c.red("✗")}  Vector store write failed`)
+    console.error(c.red(`\n  ${err.message}\n`))
+    process.exit(1)
+  }
+
+  // ── Write committed file ───────────────────────────────────────────────────
+  const committedDir  = path.join(chronicleDir, "committed")
+  const committedPath = path.join(committedDir, `${entry.id}.json`)
+  await fs.mkdir(committedDir, { recursive: true })
+  await fs.writeFile(committedPath, JSON.stringify(entry, null, 2), "utf8")
+
+  // Git add — best-effort
+  try { await execAsync(`git add "${committedPath}"`) } catch { /* not in git, or git unavailable */ }
+
+  // Update SUMMARY.md — best-effort
+  try { await updateSummary(chronicleDir) } catch { /* never fail a commit */ }
+
+  // Remove proposal
+  await fs.unlink(proposalPath)
+
+  // ── Result ─────────────────────────────────────────────────────────────────
+  console.log(`\n${c.green("✓ Committed")}  ${c.dim(entry.id)}`)
+  console.log(`  ${c.bold("key_insight:")} ${entryText(entry)}`)
+  console.log(`  ${c.bold("areas:")}       ${(entry.affected_areas ?? []).join(", ")}`)
+  console.log(`  ${c.bold("status:")}      ${entry.status}`)
+  console.log("")
+}