@balpal4495/quorum 0.4.0 → 1.0.0

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.

package/modules/README.md

@@ -1,11 +1,12 @@
-# Oracle · Jury · Council · Sentinel
+# Advisor · Oracle · Jury · Council · Sentinel
 
-Four portable modules for the knowledge and reasoning layer of any agentic workflow.
+Five portable modules for the knowledge and reasoning layer of any agentic workflow.
 Drop the `modules/` folder into your project and wire up the dependencies.
 
 ```
-Oracle  →  Jury  →  Council  →  human gate  →  Executor
-Sentinel  →  coverage + drift + PR coverage map
+Advisor  →  plain-language questions answered from Chronicle
+Oracle   →  Jury  →  Council  →  human gate  →  Executor
+Sentinel →  coverage + drift + PR coverage map
 ```
 
 ---
@@ -14,6 +15,7 @@ Sentinel  →  coverage + drift + PR coverage map
 
 | Module | Responsibility | LLM? |
 |---|---|---|
+| **Advisor** | Ask a plain-language question — synthesises Chronicle evidence into a concise answer with an internal validation loop | Yes |
 | **Oracle** | Query and write interface to Chronicle (the persistent knowledge store) | No |
 | **Jury** | Evaluate a design against Oracle evidence — produces a confidence score | Yes |
 | **Council** | Adversarial validation via parallel advisor/reviewer fan-out — produces a verdict | Yes |
@@ -107,18 +109,34 @@ Recommended `tsconfig.json` settings:
 
 ## Quick start
 
+```typescript
+import { setup } from "./modules/setup"
+
+// The simplest entry point — wires all modules from one call
+const { oracle, evaluate, deliberate, ask } = await setup({ llm: myLLMProvider })
+
+// Ask a plain-language question (Advisor)
+const answer = await ask("what did the team decide about authentication?")
+// answer.what_we_know, .recommendation, .next_step, .risks, .blockers, .retries
+
+// Or run the full evaluation pipeline for a proposed design:
+const evidence = await oracle.query("authentication patterns in this codebase")
+```
+
+### Manual wiring (without setup())
+
 ```typescript
 import { createOracleClient, xenovaEmbed, createLanceDBStore } from "./modules/oracle"
 import { evaluate } from "./modules/jury"
 import { deliberate } from "./modules/council"
 
-// 1. Wire Oracle (no LLM required)
+// Wire Oracle manually
 const oracle = createOracleClient({
   embedder: xenovaEmbed,
   vectorStore: await createLanceDBStore(".chronicle"),
 })
 
-// 2. Retrieve evidence for the task at hand
+// Retrieve evidence for the task at hand
 const evidence = await oracle.query("authentication patterns in this codebase")
 
 // 3. Jury evaluates the design against the evidence
@@ -167,6 +185,47 @@ if (verdict.satisfied) {
 
 ---
 
+## Advisor
+
+The Advisor is the plain-language interface to Chronicle. Use it to answer questions rather than to evaluate designs. It is a **read-only** path — it never calls `oracle.propose()` or `oracle.commit()`.
+
+```typescript
+import { ask } from "./modules/advisor"
+
+const answer = await ask(
+  { question: "What did the team decide about session handling?", evidence },
+  { llm: myLLMProvider },
+)
+```
+
+Or via `setup()`, which queries Oracle automatically:
+
+```typescript
+const { ask } = await setup({ llm: myLLMProvider })
+const answer = await ask("What did the team decide about session handling?")
+```
+
+### Advisor output
+
+```typescript
+interface AdvisorOutput {
+  question: string
+  confidence: number        // 0–1 — how confident the answer is given the evidence
+  what_we_know: string      // plain-language summary of relevant Chronicle knowledge
+  risks: string[]           // real risks worth knowing
+  blockers: string[]        // hard blockers — must be resolved before acting (often empty)
+  recommendation: string    // one clear recommended action
+  next_step: string         // specific next step or quorum command
+  retries: number           // how many retry attempts were needed (0 = first try succeeded)
+}
+```
+
+### Validation loop
+
+Advisor validates its own answer before returning. If `confidence < 0.7` or `blockers.length > 0`, it retries the LLM call with the previous answer as context — up to 2 retries. After the retry budget is exhausted, the best answer is returned regardless. Throws on non-JSON or schema-invalid LLM output.
+
+---
+
 ## LLM provider interface
 
 The `LLMProvider` type is a simple function. Wire it to any provider:
@@ -284,14 +343,14 @@ const risk = classifyRisk(outcome, design, evidence)
 // risk.council_mode   — "jury-only" | "lite" | "full"
 ```
 
-| Risk | Triggers | Advisor + Reviewer count |
-|---|---|---|
-| Low | Nothing sensitive detected | 1 + 1 |
-| Medium | Cache, queues, deployments, rate limiting | 1 + 2 |
-| High | DB migrations, permissions, PII, secrets | 5 + 5 |
-| Critical | Auth, payments, crypto, data deletion | 5 + 5 |
+| Risk | Triggers | Council mode | Advisor + Reviewer |
+|---|---|---|---|
+| Low | Nothing sensitive detected | jury-only — skipped | 0 + 0 |
+| Medium | Cache, queues, deployments, rate limiting | lite | 1 + 2 |
+| High | DB migrations, permissions, PII, secrets | full | 5 + 5 |
+| Critical | Auth, payments, crypto, data deletion | full + human flag | 5 + 5 |
 
-Refuted entries in the evidence pack always elevate risk by at least one level.
+Refuted entries in the evidence pack always elevate risk by at least one level. `jury-only` means Council is not called at all — Jury alone is sufficient for low-risk designs.
 
 ### Council output routing
 

package/modules/advisor/ask.ts

@@ -0,0 +1,87 @@
+import { z } from "zod"
+import type { AdvisorInput, AdvisorOutput, AdvisorAnswer, AdvisorDeps } from "./types"
+import { SYSTEM_PROMPT, buildUserPrompt } from "./prompt"
+
+const SATISFACTION_THRESHOLD = 0.7
+const MAX_RETRIES = 2
+
+const AdvisorAnswerSchema = z.object({
+  confidence:     z.number().min(0).max(1),
+  what_we_know:   z.string().min(1),
+  risks:          z.array(z.string()),
+  blockers:       z.array(z.string()),
+  recommendation: z.string().min(1),
+  next_step:      z.string().min(1),
+})
+
+async function callLLM(
+  input: AdvisorInput,
+  deps: AdvisorDeps,
+  attempt: number,
+  previous: AdvisorAnswer | null,
+): Promise<AdvisorAnswer> {
+  const { llm, model } = deps
+
+  let userPrompt = buildUserPrompt(input.question, input.evidence)
+
+  if (attempt > 0 && previous) {
+    userPrompt += [
+      "",
+      `## Previous Answer (attempt ${attempt} — did not meet quality threshold)`,
+      `Confidence: ${previous.confidence.toFixed(2)} (need ≥ ${SATISFACTION_THRESHOLD})`,
+      previous.blockers.length > 0
+        ? `Unresolved blockers: ${previous.blockers.join("; ")}`
+        : "",
+      "Please produce a more specific and concrete answer.",
+    ].filter(Boolean).join("\n")
+  }
+
+  const raw = await llm(
+    [
+      { role: "system", content: SYSTEM_PROMPT },
+      { role: "user",   content: userPrompt },
+    ],
+    model,
+  )
+
+  let parsed: unknown
+  try {
+    const cleaned = raw.replace(/^```(?:json)?\s*/m, "").replace(/\s*```$/m, "").trim()
+    parsed = JSON.parse(cleaned)
+  } catch {
+    throw new Error(`Advisor: LLM returned non-JSON. Raw (first 300 chars): ${raw.slice(0, 300)}`)
+  }
+
+  const result = AdvisorAnswerSchema.safeParse(parsed)
+  if (!result.success) {
+    throw new Error(`Advisor: LLM output failed validation. Issues: ${JSON.stringify(result.error.issues)}`)
+  }
+
+  return result.data
+}
+
+/**
+ * Ask the Advisor a plain-language question.
+ *
+ * Internally calls the LLM and validates the answer against a satisfaction
+ * threshold (confidence ≥ 0.7, no blockers). Retries up to MAX_RETRIES times
+ * with the previous answer included as context. Returns the best answer found
+ * within the retry budget regardless of whether the threshold was met.
+ *
+ * Throws if the LLM returns non-JSON or output that fails schema validation.
+ */
+export async function ask(input: AdvisorInput, deps: AdvisorDeps): Promise<AdvisorOutput> {
+  let last: AdvisorAnswer | null = null
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    const answer = await callLLM(input, deps, attempt, last)
+    last = answer
+
+    const satisfied = answer.confidence >= SATISFACTION_THRESHOLD && answer.blockers.length === 0
+    if (satisfied || attempt === MAX_RETRIES) {
+      return { ...answer, question: input.question, retries: attempt }
+    }
+  }
+
+  return { ...last!, question: input.question, retries: MAX_RETRIES }
+}

package/modules/advisor/index.ts

@@ -0,0 +1,2 @@
+export { ask } from "./ask"
+export type { AdvisorInput, AdvisorOutput, AdvisorDeps } from "./types"

package/modules/advisor/prompt.ts

@@ -0,0 +1,50 @@
+import type { OracleResult } from "../shared/types"
+import { entryText } from "../shared/types"
+
+export 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, not a list of options unless genuinely necessary.
+- 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.
+- risks are real concerns worth knowing, not theoretical edge cases.
+
+Return ONLY valid JSON matching this schema (no markdown fences, no explanation):
+{
+  "confidence": <number 0–1 — how confident are you given the available evidence>,
+  "what_we_know": <string — what Chronicle knows about this topic. Plain English, 1–3 sentences.>,
+  "risks": [<string — each real risk, plain English, one per item. Empty array if none.>],
+  "blockers": [<string — hard blockers only. Empty array if none.>],
+  "recommendation": <string — one clear recommended action>,
+  "next_step": <string — the specific next thing to do, e.g. a quorum command or a decision>
+}`
+
+export function formatEvidence(evidence: OracleResult[]): string {
+  if (evidence.length === 0) {
+    return "Chronicle has no prior entries on this topic."
+  }
+  return evidence
+    .map(e => {
+      const text = entryText(e)
+      const statusTag =
+        e.status === "refuted"   ? " [REJECTED]"  :
+        e.status === "validated" ? " [VALIDATED]" : ""
+      return `[${e.id.slice(0, 8)}]${statusTag} ${text}\n  Areas: ${e.affected_areas.join(", ")}`
+    })
+    .join("\n\n")
+}
+
+export function buildUserPrompt(question: string, evidence: OracleResult[]): string {
+  return [
+    "## Question",
+    question,
+    "",
+    "## Chronicle Evidence",
+    formatEvidence(evidence),
+  ].join("\n")
+}

package/modules/advisor/types.ts

@@ -0,0 +1,26 @@
+import type { OracleResult, LLMProvider } from "../shared/types"
+
+export interface AdvisorInput {
+  question: string
+  evidence: OracleResult[]
+}
+
+export interface AdvisorAnswer {
+  confidence: number
+  what_we_know: string
+  risks: string[]
+  blockers: string[]
+  recommendation: string
+  next_step: string
+}
+
+export interface AdvisorOutput extends AdvisorAnswer {
+  question: string
+  /** Number of retries taken before the answer met the satisfaction threshold. */
+  retries: number
+}
+
+export interface AdvisorDeps {
+  llm: LLMProvider
+  model?: string
+}

package/modules/council/deliberate.ts

@@ -10,8 +10,6 @@ const DEFAULT_ADVISOR_COUNT = 5
 const DEFAULT_REVIEWER_COUNT = 5
 const LITE_ADVISOR_COUNT = 1
 const LITE_REVIEWER_COUNT = 2
-const JURY_ONLY_ADVISOR_COUNT = 1
-const JURY_ONLY_REVIEWER_COUNT = 1
 
 /**
  * Run the Council deliberation pipeline.
@@ -44,14 +42,26 @@ export async function deliberate(
 
   // Classify risk to determine Council mode and advisor/reviewer counts
   const risk = classifyRisk(input.outcome, input.design, input.evidence)
+
+  if (risk.council_mode === "jury-only") {
+    return {
+      satisfied: true,
+      verdict: "Skipped — low-risk design passed by Jury without Council review.",
+      blockers: [],
+      warnings: [],
+      challenges: [],
+      evidence_cited: [],
+      citation_validation: { valid_ids: [], hallucinated_ids: [] },
+      advisor_split: { proceed: 0, redesign: 0, "investigate-more": 0 },
+      recommendation: "proceed",
+    }
+  }
+
   let defaultAdvisors = DEFAULT_ADVISOR_COUNT
   let defaultReviewers = DEFAULT_REVIEWER_COUNT
   if (risk.council_mode === "lite") {
     defaultAdvisors = LITE_ADVISOR_COUNT
     defaultReviewers = LITE_REVIEWER_COUNT
-  } else if (risk.council_mode === "jury-only") {
-    defaultAdvisors = JURY_ONLY_ADVISOR_COUNT
-    defaultReviewers = JURY_ONLY_REVIEWER_COUNT
   }
   const advisorCount = deps.advisorCount ?? defaultAdvisors
   const reviewerCount = deps.reviewerCount ?? defaultReviewers

package/modules/council/types.ts

@@ -94,7 +94,7 @@ export type RiskLevel = "low" | "medium" | "high" | "critical"
 /**
  * Determines which Council mode to use.
  *   skip        → Oracle query only, no LLM validation
- *   jury-only   → Jury scores, no Council fan-out
+ *   jury-only   → Jury scores, Council skipped entirely (low-risk fast path)
  *   lite        → Jury + 1–2 reviewers (no full advisor fan-out)
  *   full        → Full Council (default 5 advisors + 5 reviewers + Chairman)
  */

package/modules/setup.ts

@@ -5,10 +5,12 @@ import { xenovaEmbed, warmEmbedder } from "./oracle/adapters/xenova-embedder"
 import { createLanceDBStore } from "./oracle/adapters/lance-db"
 import { evaluate } from "./jury/evaluate"
 import { deliberate } from "./council/deliberate"
+import { ask as advisorAsk } from "./advisor/ask"
 import type { LLMProvider, OracleClient } from "./shared/types"
 import { entryText } from "./shared/types"
 import type { JuryInput, JuryOutput, JuryDeps } from "./jury/types"
 import type { CouncilInput, CouncilOutput, CouncilDeps, CouncilModels } from "./council/types"
+import type { AdvisorOutput } from "./advisor/types"
 
 export interface SetupOptions {
   /**
@@ -69,6 +71,14 @@ export interface Modules {
   deliberate: (
     input: Omit<CouncilInput, "jury_output"> & { jury_output: JuryOutput },
   ) => Promise<CouncilOutput>
+
+  /**
+   * Ask the Advisor a plain-language question.
+   * Queries Oracle automatically, synthesises Chronicle evidence into a
+   * human-readable answer, and retries internally until the answer meets
+   * the confidence threshold (≥ 0.7, no blockers) or the retry budget runs out.
+   */
+  ask: (question: string) => Promise<AdvisorOutput>
 }
 
 /**
@@ -150,5 +160,10 @@ export async function setup(options: SetupOptions): Promise<Modules> {
         oracle,
         models: models.council,
       }),
+
+    ask: async (question: string) => {
+      const evidence = await oracle.query(question)
+      return advisorAsk({ question, evidence }, { llm })
+    },
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@balpal4495/quorum",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "description": "Portable reasoning layer for agentic codebases — Oracle, Jury, Council, Sentinel",
   "type": "module",
   "license": "MIT",