@balpal4495/quorum 0.4.0 → 1.0.0

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.
@@ -113,7 +117,7 @@ Append to it:
 
 ## Quorum modules
 
-See [quorum/modules/AGENTS.md](quorum/modules/AGENTS.md) for Oracle, Jury, and Council internals.
+See [quorum/modules/AGENTS.md](quorum/modules/AGENTS.md) for Advisor, Oracle, Jury, Council, and Sentinel internals.
 ```
 
 ### 4c. `CLAUDE.md`
@@ -135,7 +139,7 @@ Append to it:
 
 ## Quorum modules
 
-See [quorum/modules/CLAUDE.md](quorum/modules/CLAUDE.md) for Oracle, Jury, and Council internals.
+See [quorum/modules/CLAUDE.md](quorum/modules/CLAUDE.md) for Advisor, Oracle, Jury, Council, and Sentinel internals.
 ```
 
 ---
@@ -166,13 +170,15 @@ Add the following import and call at startup, **before** any agent or workflow c
 ```typescript
 import { setup } from "./quorum/modules/setup"
 
-const { oracle, evaluate, deliberate } = await setup({
+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.
-It must be called once before any `oracle.query()`, `evaluate()`, or `deliberate()` call.
+It 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. Use it to answer questions rather than to evaluate designs.
 
 If no entry point exists yet, note that `setup()` must be called before first use — do not inline it.
 
@@ -267,6 +273,7 @@ Gemini and use it for large-context tasks.
 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:
+- **Ask Advisor for context.** `quorum advisor "what has the team decided about X?"` before starting any meaningful work.
 - **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.
@@ -277,10 +284,17 @@ These commands are available globally after `npm install -g @balpal4495/quorum`:
 
 | 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 (Claude Code, Copilot, Codex, Gemini) with no separate key, they output Chronicle evidence and a synthesis request for the agent to answer inline.

package/bin/commands/advisor.js

@@ -0,0 +1,301 @@
+import { c } from "../shared/colors.js"
+import { findChronicleDir, readCommitted } from "../shared/chronicle.js"
+import { detectProvider } from "../shared/llm.js"
+
+const SATISFACTION_THRESHOLD = 0.7
+const MAX_RETRIES = 2
+
+// ── Evidence helpers ──────────────────────────────────────────────────────────
+
+function tokenize(text) {
+  return text.toLowerCase().split(/\W+/).filter(t => t.length > 2)
+}
+
+function scoreEntry(query, entry) {
+  const qTokens = new Set(tokenize(query))
+  const text = [
+    entry.key_insight ?? "",
+    entry.decision    ?? "",
+    ...(entry.affected_areas ?? []),
+    ...(entry.scope          ?? []),
+  ].join(" ")
+  const eTokens = tokenize(text)
+  const overlap = eTokens.filter(t => qTokens.has(t)).length
+  return overlap / Math.sqrt(qTokens.size * eTokens.length + 1)
+}
+
+function entryText(entry) {
+  return (entry.decision ?? entry.key_insight ?? "").trim()
+}
+
+function findRelevant(entries, query, limit = 6) {
+  return entries
+    .map(e => ({ entry: e, score: scoreEntry(query, e) }))
+    .filter(({ score }) => score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map(({ entry }) => entry)
+}
+
+function formatEvidenceForLLM(entries) {
+  if (entries.length === 0) return "Chronicle has no prior entries on this topic."
+  return entries.map(e => {
+    const statusTag =
+      e.status === "refuted"   ? " [REJECTED]"  :
+      e.status === "validated" ? " [VALIDATED]" : ""
+    return `[${(e.id ?? "").slice(0, 8)}]${statusTag} ${entryText(e)}\n  Areas: ${(e.affected_areas ?? []).join(", ")}`
+  }).join("\n\n")
+}
+
+// ── LLM + validation loop ─────────────────────────────────────────────────────
+
+const SYSTEM_PROMPT = `You are the Quorum Advisor — the plain-language interface to a team's collective knowledge.
+
+You receive a question from a developer or engineering manager, along with relevant Chronicle evidence.
+Synthesise that evidence into a clear, concise answer a human can act on.
+
+Rules:
+- Write for a human who does not know what "Chronicle entries" or "vector search" mean.
+- Be direct. One clear recommendation.
+- If Chronicle has relevant evidence, reference it plainly: "the team already decided X".
+- If Chronicle has no evidence, say so honestly — do not invent history.
+- Blockers are hard blockers only — things that MUST be resolved before moving forward.
+
+Return ONLY valid JSON matching this schema (no markdown fences, no explanation):
+{
+  "confidence": <number 0–1>,
+  "what_we_know": <string — what Chronicle knows, plain English, 1–3 sentences>,
+  "risks": [<string>],
+  "blockers": [<string — hard blockers only, empty array if none>],
+  "recommendation": <string — one clear action>,
+  "next_step": <string — specific next step or quorum command>
+}`
+
+async function callLLM(llm, question, evidence, attempt, previous) {
+  let userPrompt = `## Question\n${question}\n\n## Chronicle Evidence\n${formatEvidenceForLLM(evidence)}`
+
+  if (attempt > 0 && previous) {
+    const lines = [
+      "",
+      `## Previous Answer (attempt ${attempt} — quality threshold not met)`,
+      `Confidence: ${previous.confidence.toFixed(2)} (need ≥ ${SATISFACTION_THRESHOLD})`,
+    ]
+    if (previous.blockers?.length > 0) {
+      lines.push(`Unresolved blockers: ${previous.blockers.join("; ")}`)
+    }
+    lines.push("Please produce a more specific and concrete answer.")
+    userPrompt += lines.join("\n")
+  }
+
+  const raw = await llm([
+    { role: "system", content: SYSTEM_PROMPT },
+    { role: "user",   content: userPrompt },
+  ])
+
+  let parsed
+  try {
+    const cleaned = raw.replace(/^```(?:json)?\s*/m, "").replace(/\s*```$/m, "").trim()
+    parsed = JSON.parse(cleaned)
+  } catch {
+    throw new Error(`LLM returned non-JSON. Raw: ${raw.slice(0, 200)}`)
+  }
+
+  if (typeof parsed.confidence !== "number" || !parsed.what_we_know || !parsed.recommendation) {
+    throw new Error("LLM response missing required fields (confidence, what_we_know, recommendation)")
+  }
+
+  return parsed
+}
+
+async function runAdvisor(llm, question, evidence) {
+  let last = null
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    const answer = await callLLM(llm, question, evidence, attempt, last)
+    last = answer
+    const satisfied = answer.confidence >= SATISFACTION_THRESHOLD && (answer.blockers?.length ?? 0) === 0
+    if (satisfied || attempt === MAX_RETRIES) return { ...answer, retries: attempt }
+  }
+  return { ...last, retries: MAX_RETRIES }
+}
+
+// ── Output renderers ──────────────────────────────────────────────────────────
+
+function renderAsk(question, result) {
+  console.log(`\n${c.bold("Advisor")}\n`)
+  console.log(`  ${c.dim("Question:")} ${question}\n`)
+
+  console.log(`${c.bold("What we know")}`)
+  console.log(`  ${result.what_we_know}\n`)
+
+  if (result.blockers?.length > 0) {
+    console.log(`${c.bold(c.red("Blockers"))}`)
+    for (const b of result.blockers) console.log(`  ${c.red("✗")}  ${b}`)
+    console.log("")
+  }
+
+  if (result.risks?.length > 0) {
+    console.log(`${c.bold("Risks")}`)
+    for (const r of result.risks) console.log(`  ${c.yellow("⚠")}  ${r}`)
+    console.log("")
+  }
+
+  console.log(`${c.bold("Recommendation")}`)
+  console.log(`  ${result.recommendation}\n`)
+
+  console.log(`${c.bold("Next step")}`)
+  console.log(`  ${c.cyan(result.next_step)}\n`)
+
+  if (result.retries > 0) {
+    console.log(c.dim(`  (Refined over ${result.retries + 1} attempts)\n`))
+  }
+}
+
+function renderQuery(topic, entries) {
+  console.log(`\n${c.bold("Chronicle")}  ${c.dim(`query: "${topic}"`)}\n`)
+
+  if (entries.length === 0) {
+    console.log(`  ${c.dim("No matching entries found.")}\n`)
+    return
+  }
+
+  for (const e of entries) {
+    const statusColor =
+      e.status === "validated" ? c.green :
+      e.status === "refuted"   ? c.red   : c.dim
+    console.log(`  ${c.cyan((e.id ?? "").slice(0, 8))}  ${statusColor(`[${e.status}]`)}  ${entryText(e)}`)
+    if (e.affected_areas?.length) console.log(`           ${c.dim(e.affected_areas.join(", "))}`)
+    console.log("")
+  }
+}
+
+function renderBrief(allEntries) {
+  const validated = allEntries.filter(e => e.status === "validated")
+  const refuted   = allEntries.filter(e => e.status === "refuted")
+  const open      = allEntries.filter(e => e.status === "open")
+  const recent    = allEntries.slice(0, 5)
+
+  console.log(`\n${c.bold("Chronicle Brief")}\n`)
+  console.log(`  ${c.green(validated.length)}  validated   ${c.red(refuted.length)}  refuted   ${c.dim(open.length + "  open")}\n`)
+
+  if (recent.length > 0) {
+    console.log(`${c.bold("Recent entries")}`)
+    for (const e of recent) {
+      const statusColor =
+        e.status === "validated" ? c.green :
+        e.status === "refuted"   ? c.red   : c.dim
+      console.log(`  ${c.cyan((e.id ?? "").slice(0, 8))}  ${statusColor(e.status)}  ${entryText(e).slice(0, 70)}`)
+    }
+    console.log("")
+  }
+}
+
+// ── Subcommand handlers ───────────────────────────────────────────────────────
+
+async function cmdAsk(question, chronicleDir) {
+  const allEntries = await readCommitted(chronicleDir)
+  const evidence   = findRelevant(allEntries, question)
+  const provider   = await detectProvider()
+
+  if (!provider) {
+    renderPassthrough(question, evidence)
+    return
+  }
+
+  const { llm, name: llmName } = provider
+  process.stdout.write(c.dim(`\n  Thinking (${llmName})…`))
+  try {
+    const result = await runAdvisor(llm, question, evidence)
+    process.stdout.write("\r" + " ".repeat(50) + "\r")
+    renderAsk(question, result)
+  } catch (err) {
+    process.stdout.write("\r" + " ".repeat(50) + "\r")
+    console.error(`\n${c.red("Advisor failed:")} ${err.message}\n`)
+    process.exit(1)
+  }
+}
+
+function renderPassthrough(question, evidence) {
+  console.log(`\n${c.bold("Chronicle evidence")}  ${c.dim(`for: "${question}"`)}\n`)
+  if (evidence.length === 0) {
+    console.log(c.dim("  No relevant Chronicle entries found.\n"))
+  } else {
+    for (const e of evidence) {
+      console.log(`  ${c.cyan(e.id.slice(0, 8))}  ${c.bold(entryText(e))}`)
+      console.log(`  ${c.dim(`status: ${e.status} · confidence: ${e.confidence} · areas: ${(e.affected_areas ?? []).join(", ")}`)}`)
+      console.log("")
+    }
+  }
+  console.log(c.dim("─".repeat(60)))
+  console.log(`\n${c.bold("Synthesis request")}`)
+  console.log(`\n  ${question}`)
+  console.log(`\n${c.dim("  No LLM configured — answer from the Chronicle evidence above.")}`)
+  console.log(c.dim("  (Set ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, or run Ollama for auto-synthesis.)\n"))
+}
+
+async function cmdQuery(topic, chronicleDir) {
+  const allEntries = await readCommitted(chronicleDir)
+  const matches    = findRelevant(allEntries, topic, 8)
+  renderQuery(topic, matches)
+}
+
+async function cmdBrief(chronicleDir) {
+  const allEntries = await readCommitted(chronicleDir)
+  renderBrief(allEntries)
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+export async function run(argv) {
+  const [subOrQuestion, ...rest] = 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)
+  }
+
+  // `quorum advisor ask "..."` or `quorum advisor "..."` (default to ask)
+  if (subOrQuestion === "ask") {
+    const question = rest.join(" ").trim()
+    if (!question) return printUsage()
+    return cmdAsk(question, chronicleDir)
+  }
+
+  // `quorum advisor query "topic"` — Chronicle lookup, no LLM
+  if (subOrQuestion === "query") {
+    const topic = rest.join(" ").trim()
+    if (!topic) return printUsage()
+    return cmdQuery(topic, chronicleDir)
+  }
+
+  // `quorum advisor brief` — high-level Chronicle summary
+  if (subOrQuestion === "brief") {
+    return cmdBrief(chronicleDir)
+  }
+
+  // No subcommand — treat the whole argv as a question (default: ask)
+  const question = argv.join(" ").trim()
+  if (!question) return printUsage()
+  return cmdAsk(question, chronicleDir)
+}
+
+function printUsage() {
+  console.log(`
+${c.bold("quorum advisor")} — ask plain-language questions about your codebase
+
+${c.bold("Subcommands:")}
+  ${c.cyan("quorum advisor")} ${c.dim('"question"')}              Ask a question (default — uses LLM)
+  ${c.cyan("quorum advisor ask")} ${c.dim('"question"')}          Ask explicitly
+  ${c.cyan("quorum advisor query")} ${c.dim('"topic"')}           Search Chronicle entries (no LLM)
+  ${c.cyan("quorum advisor brief")}                  High-level Chronicle summary (no LLM)
+
+${c.bold("Examples:")}
+  quorum advisor "what happens if we change the auth system?"
+  quorum advisor ask "is it safe to add a NOT NULL column to users?"
+  quorum advisor query "authentication"
+  quorum advisor brief
+
+${c.dim("ask requires ANTHROPIC_API_KEY or OPENAI_API_KEY in your environment.")}
+`)
+  process.exit(1)
+}

package/bin/commands/commit.js

@@ -119,23 +119,15 @@ export async function run(argv) {
     return
   }
 
-  // ── Check optional dependencies ────────────────────────────────────────────
-  console.log(`\n${c.bold("Checking dependencies")}`)
+  // ── Check optional embedding dependencies ─────────────────────────────────
   const hasXenova  = await checkDep("@xenova/transformers")
   const hasLanceDB = await checkDep("vectordb")
+  const canEmbed   = hasXenova && hasLanceDB
 
-  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)
+  if (!canEmbed) {
+    console.log(`\n${c.dim("  Embedding deps not found — committing to JSON store only.")}`)
+    console.log(c.dim("  Install @xenova/transformers + vectordb to enable semantic search.\n"))
   }
-  console.log(`  ${c.green("✓")}  @xenova/transformers`)
-  console.log(`  ${c.green("✓")}  vectordb`)
 
   // ── Build entry ────────────────────────────────────────────────────────────
   const entry = {
@@ -144,46 +136,44 @@ export async function run(argv) {
     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" })
+  // ── Embed + index in vector store (optional) ───────────────────────────────
+  if (canEmbed) {
+    const spin = spinner("Embedding and indexing…")
+    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 })
+      const vector = Array.from(output.data)
+      spin.stop(`${c.green("✓")}  Embedded (${vector.length}-dim)`)
+
+      const storeSpin = spinner("Indexing in vector store…")
+      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.yellow("⚠")}  Vector store write failed — JSON commit will proceed`)
+        console.error(c.dim(`     ${err.message}`))
+      }
+    } catch (err) {
+      spin.stop(`${c.yellow("⚠")}  Embedding failed — JSON commit will proceed`)
+      console.error(c.dim(`     ${err.message}`))
     }
-    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 ───────────────────────────────────────────────────