@balpal4495/quorum 0.4.2 → 2.0.0

package/bin/commands/init.js

@@ -10,12 +10,6 @@ const _require = createRequire(import.meta.url)
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const QUORUM_ROOT = path.resolve(__dirname, "../..")
 
-const DEPS = { zod: "^3.23.0" }
-const OPTIONAL_DEPS = {
-  vectordb: "^0.4.0",
-  "@xenova/transformers": "^2.17.0",
-}
-
 async function exists(p) {
   return fs.access(p).then(() => true).catch(() => false)
 }
@@ -29,25 +23,24 @@ function geminiAvailable() {
 }
 
 async function guardAlreadyInitialized(target) {
-  if (await exists(path.join(target, "quorum", "modules"))) {
+  if (await exists(path.join(target, ".quorum-version"))) {
     console.log(c.yellow("\nQuorum is already initialized in this project."))
-    console.log("Remove quorum/ first if you want to reinitialize.\n")
+    console.log("Run 'npm update @balpal4495/quorum' to upgrade to the latest version.\n")
     process.exit(0)
   }
 }
 
-async function copyModules(target) {
-  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/")
+async function writeQuorumDocs(target) {
+  log.section("Writing Quorum docs")
+  await fs.mkdir(path.join(target, "quorum"), { recursive: true })
+  for (const file of ["CLAUDE.md", "AGENTS.md"]) {
+    const src  = path.join(QUORUM_ROOT, "modules", file)
+    const dest = path.join(target, "quorum", file)
+    if (await exists(src)) {
+      await fs.copyFile(src, dest)
+      log.created(`quorum/${file}`)
+    }
+  }
   await fs.copyFile(
     path.join(QUORUM_ROOT, "SETUP.md"),
     path.join(target, "quorum", "SETUP.md"),
@@ -55,11 +48,9 @@ async function copyModules(target) {
   log.created("quorum/SETUP.md")
 }
 
-async function copyEvals(target) {
-  const src  = path.join(QUORUM_ROOT, "evals")
-  const dest = path.join(target, "quorum", "evals")
-  await fs.cp(src, dest, { recursive: true })
-  log.created("quorum/evals/")
+async function writeQuorumVersion(target, version) {
+  await fs.writeFile(path.join(target, ".quorum-version"), version + "\n", "utf8")
+  log.created(".quorum-version")
 }
 
 async function mergeCopilotInstructions(target) {
@@ -67,14 +58,15 @@ async function mergeCopilotInstructions(target) {
   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")
+  const block   = `<!-- quorum:start -->\n${content}\n<!-- quorum:end -->`
   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")
+    if (existing.includes("<!-- quorum:start -->")) { log.skipped(".github/copilot-instructions.md (already present)"); return }
+    await fs.appendFile(dest, `\n\n---\n\n${block}`, "utf8")
     log.appended(".github/copilot-instructions.md")
   } else {
-    await fs.writeFile(dest, content, "utf8")
+    await fs.writeFile(dest, block, "utf8")
     log.created(".github/copilot-instructions.md")
   }
 }
@@ -82,13 +74,18 @@ async function mergeCopilotInstructions(target) {
 async function mergeAgentsMd(target) {
   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.", "",
+    "",
+    "<!-- 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 -->",
+    "",
   ].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 }
+    if (existing.includes("<!-- quorum:start -->")) { log.skipped("AGENTS.md (already present)"); return }
     await fs.appendFile(dest, section, "utf8")
     log.appended("AGENTS.md")
   } else {
@@ -98,11 +95,12 @@ async function mergeAgentsMd(target) {
 }
 
 async function mergeClaudeMd(target) {
-  const dest = path.join(target, "CLAUDE.md")
+  const dest    = path.join(target, "CLAUDE.md")
   const section = `
-## Quorum modules
+<!-- quorum:start -->
+## Quorum
 
-See [quorum/modules/CLAUDE.md](quorum/modules/CLAUDE.md) for Oracle, Jury, and Council internals.
+See [quorum/CLAUDE.md](quorum/CLAUDE.md) for design decisions and invariants.
 See [.github/copilot-instructions.md](.github/copilot-instructions.md) for workflow rules.
 
 ## Gemini CLI (optional assistant)
@@ -127,10 +125,11 @@ 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.
+<!-- quorum:end -->
 `
   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 }
+    if (existing.includes("<!-- quorum:start -->")) { log.skipped("CLAUDE.md (already present)"); return }
     await fs.appendFile(dest, section, "utf8")
     log.appended("CLAUDE.md")
   } else {
@@ -147,7 +146,7 @@ async function mergeGeminiMd(target) {
   if (await exists(src)) { await fs.copyFile(src, dest); log.created("GEMINI.md") }
 }
 
-async function updatePackageJson(target) {
+async function updatePackageJson(target, version) {
   log.section("Updating package.json")
   const pkgPath = path.join(target, "package.json")
   let pkg
@@ -157,30 +156,27 @@ async function updatePackageJson(target) {
     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)`) }
+  pkg.devDependencies = pkg.devDependencies ?? {}
+  const quorumRange = `^${version}`
+  if (pkg.devDependencies["@balpal4495/quorum"] || pkg.dependencies?.["@balpal4495/quorum"]) {
+    log.skipped("package.json (@balpal4495/quorum already present)")
+    return
   }
+  pkg.devDependencies["@balpal4495/quorum"] = quorumRange
   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)")
-  }
+  log.appended(`package.json — added @balpal4495/quorum@${quorumRange} to devDependencies`)
 }
 
 async function updateGitignore(target) {
   log.section("Updating .gitignore")
   const dest  = path.join(target, ".gitignore")
   const block = [
-    "", "# Quorum — Chronicle",
+    "",
+    "# Quorum — Chronicle",
     "# entries/ is a binary vector store — do not commit",
-    ".chronicle/entries/", ".chronicle/query-log.jsonl", "",
+    ".chronicle/entries/",
+    ".chronicle/query-log.jsonl",
+    "",
   ].join("\n")
   if (await exists(dest)) {
     const existing = await fs.readFile(dest, "utf8")
@@ -195,7 +191,7 @@ async function updateGitignore(target) {
 
 async function createChronicle(target) {
   log.section("Creating Chronicle")
-  await fs.mkdir(path.join(target, ".chronicle", "proposals"),  { recursive: true })
+  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/")
@@ -213,30 +209,33 @@ export async function run(PKG_VERSION) {
   }
 
   await guardAlreadyInitialized(target)
-  await copyModules(target)
-  await copyEvals(target)
+  await writeQuorumDocs(target)
   await mergeCopilotInstructions(target)
   await mergeAgentsMd(target)
   await mergeClaudeMd(target)
   await mergeGeminiMd(target)
-  await updatePackageJson(target)
+  await updatePackageJson(target, PKG_VERSION)
   await updateGitignore(target)
   await createChronicle(target)
+  await writeQuorumVersion(target, PKG_VERSION)
 
   const hasGemini = geminiAvailable()
 
-  console.log(`\n${c.green("✓ Quorum initialized.")}`)
+  console.log(`\n${c.green("✓ Quorum initialized.")} ${c.dim(`(v${PKG_VERSION})`)}`)
   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("  2. Use the CLI:")
+  console.log(c.dim("     quorum advisor brief"))
+  console.log(c.dim('     quorum advisor "what has the team decided about X?"'))
+  console.log(c.dim("     quorum check --outcome '...' --design '...'"))
+  console.log("\n  For programmatic use:")
+  console.log(c.dim('     import { setup } from "@balpal4495/quorum"'))
   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.`)
   }

package/bin/commands/sentinel.js

@@ -1,4 +1,4 @@
-import { promises as fs, Dirent } from "fs"
+import { promises as fs } from "fs"
 import path from "path"
 import { c } from "../shared/colors.js"
 import { findChronicleDir, readCommitted } from "../shared/chronicle.js"

package/bin/quorum.js

@@ -20,13 +20,23 @@ function help() {
 ${c.bold("quorum")} ${c.dim(`v${PKG_VERSION}`)} — portable reasoning layer for agentic codebases
 
 ${c.bold("Usage:")}
+  ${c.cyan("quorum advisor")} ${c.dim('"question"')}             Ask a plain-language question (uses LLM)
+  ${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.cyan("quorum init")}                          Scaffold Quorum into a project
   ${c.cyan("quorum status")}                        Show Chronicle health and pending proposals
   ${c.cyan("quorum check")} --outcome <x> --design <y>  Preflight + risk (no LLM)
   ${c.cyan("quorum commit")} <id>                   Approve and index a Chronicle proposal
   ${c.cyan("quorum sentinel")} [coverage]           Chronicle coverage of source files
+  ${c.cyan("quorum growth")}                        Chronicle learning health and growth rate
+  ${c.cyan("quorum evolve")}                        Consolidate and improve Chronicle entries (uses LLM)
   ${c.cyan("quorum --version")}                     Print version
 
+${c.bold("quorum advisor")} subcommands:
+  ask ${c.dim('"question"')}       Ask with LLM synthesis + validation loop
+  query ${c.dim('"topic"')}        Chronicle lookup (no LLM, instant)
+  brief                Chronicle summary (no LLM, instant)
+
 ${c.bold("quorum check")} flags:
   --outcome  -o   What you want to achieve
   --design   -d   How you plan to do it
@@ -62,6 +72,12 @@ async function cli() {
 
   const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
+  if (command === "advisor") {
+    const { run } = await import(path.join(__dirname, "commands/advisor.js"))
+    await run(rest)
+    return
+  }
+
   if (command === "init") {
     const { run } = await import(path.join(__dirname, "commands/init.js"))
     await run(PKG_VERSION)
@@ -92,6 +108,18 @@ async function cli() {
     return
   }
 
+  if (command === "growth") {
+    const { run } = await import(path.join(__dirname, "commands/growth.js"))
+    await run(rest)
+    return
+  }
+
+  if (command === "evolve") {
+    const { run } = await import(path.join(__dirname, "commands/evolve.js"))
+    await run(rest)
+    return
+  }
+
   console.error(`${c.red(`Unknown command: ${command}`)}`)
   console.error(`Run ${c.bold("quorum help")} for usage.`)
   process.exit(1)

package/bin/shared/llm.js

@@ -0,0 +1,228 @@
+import { spawn, exec } from "child_process"
+import { promisify } from "util"
+import path from "path"
+
+const execAsync = promisify(exec)
+
+/**
+ * Auto-detect an available LLM provider from the environment.
+ *
+ * Priority:
+ *   1. ANTHROPIC_API_KEY            → Anthropic Claude
+ *   2. OPENAI_API_KEY               → OpenAI (or compatible via OPENAI_BASE_URL)
+ *   3. GEMINI_API_KEY               → Google Gemini (API)
+ *   4. OPENAI_BASE_URL (no key)     → OpenAI-compatible endpoint (Azure, Groq, Ollama, etc.)
+ *   5. OLLAMA_HOST env var          → Ollama (explicit host)
+ *   6. localhost:11434 probe        → Ollama (auto-detect)
+ *   7. gemini CLI in PATH           → Google Gemini (CLI subprocess)
+ *
+ * Returns { llm: LLMProvider, name: string } or null.
+ */
+export async function detectProvider() {
+  if (process.env.ANTHROPIC_API_KEY) {
+    return {
+      llm:  createAnthropicProvider(process.env.ANTHROPIC_API_KEY),
+      name: "Anthropic",
+    }
+  }
+
+  if (process.env.OPENAI_API_KEY) {
+    const base = (process.env.OPENAI_BASE_URL ?? "").replace(/\/$/, "")
+    const name = base
+      ? `OpenAI-compatible (${new URL(base).hostname})`
+      : "OpenAI"
+    return {
+      llm:  createOpenAICompatProvider(process.env.OPENAI_API_KEY, base || "https://api.openai.com/v1"),
+      name,
+    }
+  }
+
+  if (process.env.GEMINI_API_KEY) {
+    return {
+      llm:  createGeminiProvider(process.env.GEMINI_API_KEY),
+      name: "Gemini",
+    }
+  }
+
+  if (process.env.OPENAI_BASE_URL) {
+    const base = process.env.OPENAI_BASE_URL.replace(/\/$/, "")
+    return {
+      llm:  createOpenAICompatProvider("", base),
+      name: `OpenAI-compatible (${new URL(base).hostname})`,
+    }
+  }
+
+  const ollamaHost = process.env.OLLAMA_HOST || "http://localhost:11434"
+  const ollamaModel = await probeOllama(ollamaHost)
+  if (ollamaModel) {
+    return {
+      llm:  createOpenAICompatProvider("", `${ollamaHost}/v1`, ollamaModel),
+      name: `Ollama (${ollamaModel})`,
+    }
+  }
+
+  const geminiCLI = await probeGeminiCLI()
+  if (geminiCLI) {
+    return {
+      llm:  createGeminiCLIProvider(),
+      name: "Gemini CLI",
+    }
+  }
+
+  return null
+}
+
+/** Convenience wrapper — returns the provider function or null. */
+export async function detectLLM() {
+  return (await detectProvider())?.llm ?? null
+}
+
+/** Convenience wrapper — returns the provider name or null. */
+export async function detectLLMName() {
+  return (await detectProvider())?.name ?? null
+}
+
+// ── Probe Ollama ───────────────────────────────────────────────────────────────
+
+async function probeOllama(host) {
+  try {
+    const res = await fetch(`${host}/api/tags`, { signal: AbortSignal.timeout(1500) })
+    if (!res.ok) return null
+    const data = await res.json()
+    const model = process.env.OLLAMA_MODEL ?? data.models?.[0]?.name
+    return model ?? null
+  } catch {
+    return null
+  }
+}
+
+// ── Provider factories ─────────────────────────────────────────────────────────
+
+function createAnthropicProvider(apiKey) {
+  return async function llm(messages, model = "claude-3-5-sonnet-20241022") {
+    const systemMsg    = messages.find(m => m.role === "system")?.content
+    const userMessages = messages.filter(m => m.role !== "system")
+
+    const res = await fetch("https://api.anthropic.com/v1/messages", {
+      method:  "POST",
+      headers: {
+        "x-api-key":         apiKey,
+        "anthropic-version": "2023-06-01",
+        "content-type":      "application/json",
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: 2048,
+        ...(systemMsg ? { system: systemMsg } : {}),
+        messages: userMessages,
+      }),
+    })
+
+    if (!res.ok) throw new Error(`Anthropic API ${res.status}: ${(await res.text()).slice(0, 200)}`)
+    const data = await res.json()
+    return data.content?.[0]?.text ?? ""
+  }
+}
+
+/**
+ * OpenAI and OpenAI-compatible endpoints (Azure, Groq, Together, Ollama, etc.).
+ * Pass an empty apiKey for endpoints that don't require one.
+ * Pass a fixedModel to pin the model (e.g. for Ollama where the model comes from probe).
+ */
+function createOpenAICompatProvider(apiKey, baseUrl, fixedModel) {
+  return async function llm(messages, model = "gpt-4o") {
+    const headers = { "content-type": "application/json" }
+    if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`
+
+    const res = await fetch(`${baseUrl}/chat/completions`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        model:    fixedModel ?? model,
+        messages,
+        max_tokens: 2048,
+      }),
+    })
+
+    if (!res.ok) throw new Error(`API ${res.status}: ${(await res.text()).slice(0, 200)}`)
+    const data = await res.json()
+    return data.choices?.[0]?.message?.content ?? ""
+  }
+}
+
+function createGeminiProvider(apiKey) {
+  const defaultModel = process.env.GEMINI_MODEL ?? "gemini-2.0-flash"
+
+  return async function llm(messages, model = defaultModel) {
+    const systemMsg = messages.find(m => m.role === "system")?.content
+    const contents  = messages
+      .filter(m => m.role !== "system")
+      .map(m => ({
+        role:  m.role === "assistant" ? "model" : "user",
+        parts: [{ text: m.content }],
+      }))
+
+    const body = {
+      contents,
+      generationConfig: { maxOutputTokens: 2048 },
+    }
+    if (systemMsg) body.systemInstruction = { parts: [{ text: systemMsg }] }
+
+    const res = await fetch(
+      `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${apiKey}`,
+      { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) },
+    )
+
+    if (!res.ok) throw new Error(`Gemini API ${res.status}: ${(await res.text()).slice(0, 200)}`)
+    const data = await res.json()
+    return data.candidates?.[0]?.content?.parts?.[0]?.text ?? ""
+  }
+}
+
+async function probeGeminiCLI() {
+  try {
+    await execAsync("which gemini")
+  } catch {
+    return false
+  }
+
+  // Env vars that indicate Gemini CLI is authenticated
+  if (process.env.GOOGLE_GENAI_USE_VERTEXAI || process.env.GOOGLE_APPLICATION_CREDENTIALS) {
+    return true
+  }
+
+  // Settings file with a configured auth type
+  try {
+    const { homedir } = await import("os")
+    const { readFile } = await import("fs/promises")
+    const raw    = await readFile(path.join(homedir(), ".gemini", "settings.json"), "utf8")
+    const config = JSON.parse(raw)
+    return !!config.selectedAuthType
+  } catch {
+    return false
+  }
+}
+
+function createGeminiCLIProvider() {
+  return function llm(messages) {
+    return new Promise((resolve, reject) => {
+      const system      = messages.find(m => m.role === "system")?.content ?? ""
+      const userContent = messages.filter(m => m.role !== "system").map(m => m.content).join("\n\n")
+
+      // Pass system instruction via -p; pipe user content via stdin
+      const args = system ? ["-p", system] : []
+      const child = spawn("gemini", args, { stdio: ["pipe", "pipe", "pipe"] })
+
+      let out = "", err = ""
+      child.stdout.on("data", d => { out += d })
+      child.stderr.on("data", d => { err += d })
+      child.on("error", reject)
+      child.on("close", code => {
+        if (code === 0) resolve(out.trim())
+        else reject(new Error(`gemini CLI exited ${code}: ${err.slice(0, 200)}`))
+      })
+      child.stdin.write(userContent)
+      child.stdin.end()
+    })
+  }
+}

package/modules/AGENTS.md

@@ -35,6 +35,13 @@ When working inside this folder, follow these rules in addition to the root guid
 | `council/risk.ts` | Deterministic risk classifier — no LLM. Assigns `low/medium/high/critical` and `council_mode` from design text and refuted evidence. Drives advisor/reviewer fan-out counts. |
 | `council/deliberate.ts` | Full pipeline orchestration. Calls `oracle.propose()` at the end — never `oracle.commit()`. Risk classifier runs first to set fan-out counts. |
 
+### Advisor
+| File | Owns |
+|---|---|
+| `advisor/ask.ts` | Main entry point. Queries Oracle, calls LLM, validates answer against satisfaction threshold (confidence ≥ 0.7, no blockers). Retries up to 2 times with previous answer as context. Throws on bad LLM output — do not add fallbacks. |
+| `advisor/prompt.ts` | SYSTEM_PROMPT, evidence formatter, user prompt builder. The plain-language framing lives here. |
+| `advisor/types.ts` | `AdvisorInput`, `AdvisorAnswer`, `AdvisorOutput`, `AdvisorDeps` types. |
+
 ---
 
 ## Extension points
@@ -51,6 +58,7 @@ When working inside this folder, follow these rules in addition to the root guid
 
 ## Invariants — do not break these
 
+- `advisor/ask.ts` never calls `oracle.propose()` or `oracle.commit()`. It is a read-only path.
 - `oracle.commit()` is never called without explicit human input. `deliberate()` calls `propose()` only.
 - `jury/evaluate.ts` recomputes `confidence` as the exact average of `confidence_breakdown` dimensions — the LLM value is discarded.
 - `jury/evaluate.ts` derives `council_brief` from the recomputed confidence — never trusts the LLM value.

package/modules/CLAUDE.md

@@ -6,7 +6,7 @@ Supplements the root-level instructions. Read this when working inside the `modu
 
 ## What these modules are
 
-Three portable TypeScript modules — Oracle, Jury, Council — that form the knowledge and reasoning layer of an agentic workflow. They are designed to be dropped into any Node.js codebase.
+Five portable TypeScript modules — Advisor, Oracle, Jury, Council, Sentinel — that form the knowledge and reasoning layer of an agentic workflow. They are designed to be dropped into any Node.js codebase.
 
 The entry point for a host application is `setup.ts`. Everything else is internal.
 
@@ -21,7 +21,13 @@ No module imports a specific LLM provider, vector store, or embedder. All extern
 In `jury/evaluate.ts`, after parsing the LLM response, `confidence` is recomputed as the exact average of the four `confidence_breakdown` dimensions. The LLM's stated `confidence` value is discarded. `council_brief` is then derived from this recomputed value. Do not remove either override.
 
 ### Throw on bad LLM output — never default to passing
-Both `jury/evaluate.ts` and `council/chairman.ts` throw if the LLM returns non-JSON or output that fails Zod validation. This is intentional. A silently passing Jury score is worse than an error. Do not add fallbacks or defaults.
+`jury/evaluate.ts`, `council/chairman.ts`, and `advisor/ask.ts` all throw if the LLM returns non-JSON or output that fails schema validation. This is intentional. A silently passing score is worse than an error. Do not add fallbacks or defaults.
+
+### Advisor is a read-only path
+`advisor/ask.ts` queries Oracle and calls the LLM — it never calls `oracle.propose()` or `oracle.commit()`. It has no side effects on Chronicle. Do not add write calls to the Advisor path.
+
+### Advisor validation loop
+`advisor/ask.ts` retries the LLM call up to `MAX_RETRIES` (2) times when the answer does not meet the satisfaction threshold (confidence ≥ 0.7, no blockers). The previous answer is included as context in the retry prompt. After the retry budget is exhausted, the best answer is returned regardless. Do not increase `MAX_RETRIES` without considering LLM cost implications.
 
 ### oracle.commit() is a human gate
 `council/deliberate.ts` calls `oracle.propose()` at the end of every deliberation. It never calls `oracle.commit()`. If you see a code path that calls `oracle.commit()` without explicit human input, that is a bug.