@balpal4495/quorum 0.1.0

package/modules/CLAUDE.md

@@ -0,0 +1,64 @@
+# modules/ — Claude Instructions
+
+Supplements the root-level instructions. Read this when working inside the `modules/` folder.
+
+---
+
+## 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.
+
+The entry point for a host application is `setup.ts`. Everything else is internal.
+
+---
+
+## Key design decisions to preserve
+
+### Dependency injection throughout
+No module imports a specific LLM provider, vector store, or embedder. All external dependencies are passed in as function arguments or via a deps object. If you add a new capability, follow this pattern — do not hardcode providers.
+
+### council_brief is computed, not trusted
+In `jury/evaluate.ts`, the `council_brief` field in the LLM response is **always overridden** based on the numeric `confidence` value after parsing. The LLM is not trusted to compute this correctly. Do not remove this 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.
+
+### 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.
+
+### Query logging is best-effort
+`oracle/log.ts` writes to a JSONL file. The `query()` function wraps this in a try/catch that swallows errors silently. This is correct behaviour — a log write failure must never fail a query.
+
+---
+
+## When modifying oracle/query.ts
+
+The retrieval pipeline has two passes:
+1. **Vector search** — embed query, retrieve `limit × 3` candidates from the vector store
+2. **BM25 re-ranking** — score candidates, enrich query with domain terms from Pass 1, fuse ranks via RRF
+
+RRF constant is `k=60`. Score threshold default is `0.031`. Results below the threshold are dropped entirely — not returned as low-confidence results. If you change the threshold, update the default in `query.ts` and the `QueryOptions` type comment in `shared/types.ts`.
+
+---
+
+## When modifying council/deliberate.ts
+
+The pipeline order is fixed: `frameQuestion → fanOutAdvisors → fanOutReviewers → chairman → oracle.propose()`. Advisors and reviewers each run in parallel internally via `Promise.all`. Do not make the advisor and reviewer phases sequential — that defeats the independence of the panel.
+
+Anonymisation of advisor responses happens inside `fanOutReviewers()` before any reviewer sees them. It must stay there.
+
+---
+
+## Safe to change
+
+- `council/personas.ts` — add or adjust personas freely
+- `models` defaults in `setup.ts` — adjust model names as providers evolve
+- BM25 constants (`K1`, `B`) in `oracle/bm25.ts` — tunable, well-commented
+- `CANDIDATE_MULTIPLIER` and `RRF_K` in `oracle/query.ts` — tunable retrieval parameters
+
+## Do not change without strong reason
+
+- The `VectorStore` interface in `oracle/types.ts` — changing it breaks all adapters
+- The `ChronicleEntry` type in `shared/types.ts` — changing it breaks stored data
+- The Zod schemas in `jury/schema.ts` and `council/chairman.ts` — these are the output contracts
+- The `OracleClient` interface in `shared/types.ts` — Jury and Council depend on it

package/modules/README.md

@@ -0,0 +1,251 @@
+# Oracle · Jury · Council · Sentinel
+
+Four 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
+```
+
+---
+
+## Modules
+
+| Module | Responsibility | LLM? |
+|---|---|---|
+| **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 |
+| **Sentinel** | Chronicle coverage reporting, drift detection, and PR coverage maps | Optional |
+
+---
+
+## Chronicle
+
+Chronicle is the data that underpins the system. It is not a module — it lives at `.chronicle/` in your project root.
+
+```
+.chronicle/
+  committed/      ← approved entries as JSON (committed to git, source of truth)
+  proposals/      ← staged entries awaiting human approval (JSON, not indexed yet)
+  SUMMARY.md      ← auto-generated agent context, rebuilt on every commit
+```
+
+Every entry goes through `oracle.propose()` → human approval → `oracle.commit()`. There are no auto-commits.
+
+---
+
+## Dependencies
+
+**Required** (must be in your project):
+```
+zod
+```
+
+**Optional** — only needed if using the included default adapters:
+```
+vectordb              ← LanceDB adapter (oracle/adapters/lance-db.ts)
+@xenova/transformers  ← local ONNX embedder (oracle/adapters/xenova-embedder.ts)
+```
+
+You can substitute any vector store and embedder by implementing the `VectorStore` and `embedder` interfaces.
+
+---
+
+## TypeScript
+
+Requires TypeScript 4.7+ and `zod` v3.
+
+Recommended `tsconfig.json` settings:
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "moduleResolution": "node"
+  }
+}
+```
+
+---
+
+## Quick start
+
+```typescript
+import { createOracleClient, xenovaEmbed, createLanceDBStore } from "./modules/oracle"
+import { evaluate } from "./modules/jury"
+import { deliberate } from "./modules/council"
+
+// 1. Wire Oracle (no LLM required)
+const oracle = createOracleClient({
+  embedder: xenovaEmbed,
+  vectorStore: await createLanceDBStore(".chronicle"),
+})
+
+// 2. 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
+const juryOutput = await evaluate(
+  {
+    outcome: "Add JWT authentication to the API",
+    design: "RS256 tokens, 15-min expiry, refresh rotation in httpOnly cookies",
+    evidence,
+  },
+  { llm: yourLLMProvider, model: "gpt-4o-mini" },
+)
+
+// 4. Council validates adversarially
+const verdict = await deliberate(
+  {
+    outcome: "Add JWT authentication to the API",
+    design: "RS256 tokens, 15-min expiry, refresh rotation in httpOnly cookies",
+    evidence,
+    jury_output: juryOutput,
+  },
+  {
+    llm: yourLLMProvider,
+    oracle,
+    models: {
+      frame:    "gpt-4o-mini",
+      advisors: "gpt-4o-mini",
+      reviewers: "gpt-4o",
+      chairman: "gpt-4o",
+    },
+  },
+)
+
+// 5. Route on verdict
+if (verdict.satisfied) {
+  // → human gate → Executor
+} else if (verdict.recommendation === "redesign") {
+  // → return to Designer with verdict.verdict as feedback
+} else {
+  // → return to Detective with juryOutput.gaps
+}
+
+// 6. Human approves the proposed Chronicle entry
+// The Council automatically called oracle.propose() — you just need to commit:
+// await oracle.commit(proposalId)
+```
+
+---
+
+## LLM provider interface
+
+The `LLMProvider` type is a simple function. Wire it to any provider:
+
+```typescript
+import type { LLMProvider } from "./modules/shared/types"
+
+// OpenAI example
+const openaiProvider: LLMProvider = async (messages, model = "gpt-4o") => {
+  const res = await openai.chat.completions.create({ model, messages })
+  return res.choices[0].message.content ?? ""
+}
+
+// Anthropic example
+const anthropicProvider: LLMProvider = async (messages, model = "claude-3-5-sonnet-20241022") => {
+  const system = messages.find(m => m.role === "system")?.content ?? ""
+  const userMessages = messages.filter(m => m.role !== "system")
+  const res = await anthropic.messages.create({ model, system, messages: userMessages, max_tokens: 2048 })
+  return res.content[0].type === "text" ? res.content[0].text : ""
+}
+```
+
+---
+
+## Output routing
+
+### Jury
+
+| `recommendation` | Next step |
+|---|---|
+| `proceed` | Pass to Council |
+| `investigate-more` | Return to Detective with `gaps` |
+| `redesign` | Return to Designer |
+
+### Council
+
+| `satisfied` | `recommendation` | Next step |
+|---|---|---|
+| `true` | `proceed` | Human gate → Executor |
+| `false` | `redesign` | Return to Designer with `verdict` |
+| `false` | `investigate-more` | Return to Detective with `juryOutput.gaps` |
+
+---
+
+## Sentinel
+
+Sentinel is the health and visibility layer. It operates independently of the Oracle → Jury → Council pipeline and has no LLM dependency for its core functions.
+
+### Coverage
+
+Reports which source files have Chronicle entries and which are blind spots.
+
+```typescript
+import { coverage } from "./modules/sentinel"
+
+const report = await coverage(".chronicle", "src", {
+  excludeTestFiles: true, // default — __tests__/, *.test.ts, *.spec.ts are excluded
+})
+// report.percentage, report.uncoveredFiles, report.coverageByFile
+```
+
+### Drift detection
+
+For each Chronicle entry, asks the LLM whether the `key_insight` still accurately describes the current code. Advisory only — never modifies entries.
+
+```typescript
+import { detectDrift } from "./modules/sentinel"
+
+const report = await detectDrift(".chronicle", "src", llmProvider)
+// report.flags (potentially stale), report.confirmed, report.skipped
+```
+
+### Vitest assertions
+
+Drop into any Vitest suite to get coverage and drift as named tests.
+
+```typescript
+import { describe } from "vitest"
+import { sentinelAssertions } from "./modules/sentinel"
+
+const assertions = sentinelAssertions({
+  chronicleDir: ".chronicle",
+  codebasePath: "src",       // defaults to "." — scan from project root
+  llm: myLLMProvider,        // omit to skip drift tests
+  minCoveragePercent: 50,    // default 0 = advisory only, never fails CI
+})
+
+describe("sentinel", () => { assertions.forEach(a => a()) })
+```
+
+`minCoveragePercent: 0` (the default) means the coverage test is purely advisory — it logs gaps to the console but never fails the build. Raise it as the project matures.
+
+### PR coverage map
+
+`sentinel/review.ts` exports `reviewContext(changedFiles, chronicleDir, codebasePath)` — used by the `sentinel-pr.yml` GitHub Actions workflow to post a PR comment showing the full-project coverage table and a colour-coded Mermaid heatmap. Test files are excluded from the scan.
+
+---
+
+## Running tests
+
+Tests use [Vitest](https://vitest.dev/). Add to your project's test config or run directly:
+
+```bash
+npx vitest run modules/
+```
+
+---
+
+## What these modules do NOT include
+
+The following are application-specific and must be built in the host project:
+
+- **Detective** — investigation and task intake
+- **Designer** — solution proposal
+- **Executor** — task execution (existing tools/agents)
+- **Validator** — satisfaction evaluator on implementation
+- **Human gate UI** — approval interface for Chronicle proposals
+- **Workflow orchestration** — LangGraph, Inngest, or equivalent

package/modules/council/advisors.ts

@@ -0,0 +1,68 @@
+import type { LLMProvider, OracleResult } from "../shared/types"
+import type { AdvisorPersona } from "./personas"
+
+export interface AdvisorResponse {
+  persona: string
+  response: string
+}
+
+function formatEvidence(evidence: OracleResult[]): string {
+  if (evidence.length === 0) {
+    return "No Oracle entries are available. Reason from absence of evidence — name what is missing."
+  }
+  return evidence
+    .map(e =>
+      `[${e.id}] (${e.status})\n${e.key_insight}\nAreas: ${e.affected_areas.join(", ")}`,
+    )
+    .join("\n\n")
+}
+
+/**
+ * Run all advisors in parallel.
+ * Each advisor receives the framed question, the Oracle evidence pack,
+ * and their persona's system prompt fragment.
+ *
+ * Advisors MUST cite specific Oracle entry IDs — this is enforced in the prompt.
+ */
+export async function fanOutAdvisors(
+  framedQuestion: string,
+  evidence: OracleResult[],
+  personas: readonly AdvisorPersona[],
+  llm: LLMProvider,
+  model?: string,
+): Promise<AdvisorResponse[]> {
+  const evidenceText = formatEvidence(evidence)
+
+  return Promise.all(
+    personas.map(async (persona): Promise<AdvisorResponse> => {
+      const systemPrompt = [
+        `You are a Council advisor — ${persona.name}.`,
+        "",
+        persona.systemFragment,
+        "",
+        "Rules:",
+        "- Reason ONLY from the Oracle evidence provided. Do not use general knowledge.",
+        "- Cite specific Oracle entry IDs (e.g. [abc-123]) for every claim you make.",
+        "- If the evidence is insufficient to support a claim, say so explicitly.",
+        "- Keep your response focused and under 400 words.",
+      ].join("\n")
+
+      const userPrompt = [
+        framedQuestion,
+        "",
+        "## Oracle Evidence",
+        evidenceText,
+      ].join("\n")
+
+      const response = await llm(
+        [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userPrompt },
+        ],
+        model,
+      )
+
+      return { persona: persona.name, response }
+    }),
+  )
+}

package/modules/council/chairman.ts

@@ -0,0 +1,112 @@
+import { z } from "zod"
+import type { LLMProvider, OracleResult } from "../shared/types"
+import type { AdvisorResponse } from "./advisors"
+import type { ReviewerResponse } from "./reviewers"
+import type { CouncilOutput } from "./types"
+
+const ChairmanOutputSchema = z.object({
+  satisfied: z.boolean(),
+  verdict: z.string().min(1),
+  challenges: z.array(z.string()),
+  evidence_cited: z.array(z.string()),
+  recommendation: z.enum(["proceed", "redesign", "investigate-more"]),
+})
+
+function formatAdvisors(responses: AdvisorResponse[]): string {
+  return responses
+    .map(r => `## ${r.persona}\n${r.response}`)
+    .join("\n\n---\n\n")
+}
+
+function formatReviewers(responses: ReviewerResponse[]): string {
+  return responses
+    .map(r => `## ${r.reviewerId}\n${r.review}`)
+    .join("\n\n---\n\n")
+}
+
+function formatEvidence(evidence: OracleResult[]): string {
+  if (evidence.length === 0) return "No Oracle evidence."
+  return evidence
+    .map(
+      e =>
+        `[${e.id}] (${e.status}, confidence: ${e.confidence.toFixed(2)}) ${e.key_insight}`,
+    )
+    .join("\n")
+}
+
+const CHAIRMAN_SYSTEM_PROMPT = [
+  "You are the Council Chairman. You synthesise the final verdict from all advisor and reviewer inputs.",
+  "",
+  "Your verdict must:",
+  "1. Be grounded in Oracle evidence — cite specific entry IDs for every material conclusion",
+  "2. Summarise what was challenged and what held up under scrutiny",
+  "3. State a clear recommendation",
+  "4. List every Oracle entry ID that materially influenced the verdict in evidence_cited",
+  "",
+  "satisfied = true  → design holds up, can proceed to the human gate",
+  "satisfied = false → fundamental flaw, unresolved gap, or design needs rework",
+  "",
+  "Return ONLY valid JSON — no markdown fences, no explanation:",
+  JSON.stringify({
+    satisfied: "<boolean>",
+    verdict: "<string ≤400 words — clear synthesis>",
+    challenges: ["<string — each challenge raised>"],
+    evidence_cited: ["<Oracle entry ID>"],
+    recommendation: "proceed | redesign | investigate-more",
+  }),
+].join("\n")
+
+/**
+ * Chairman synthesises the verdict from all advisor and reviewer inputs.
+ * Every material conclusion must cite specific Oracle entry IDs.
+ *
+ * Throws if the LLM returns non-JSON or output fails schema validation.
+ */
+export async function chairman(
+  advisorResponses: AdvisorResponse[],
+  reviewerResponses: ReviewerResponse[],
+  evidence: OracleResult[],
+  llm: LLMProvider,
+  model?: string,
+): Promise<CouncilOutput> {
+  const userPrompt = [
+    "## Advisor Responses",
+    formatAdvisors(advisorResponses),
+    "",
+    "## Reviewer Critiques",
+    formatReviewers(reviewerResponses),
+    "",
+    "## Oracle Evidence",
+    formatEvidence(evidence),
+  ].join("\n")
+
+  const raw = await llm(
+    [
+      { role: "system", content: CHAIRMAN_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(
+      `Council chairman: LLM returned non-JSON. Raw (first 300 chars): ${raw.slice(0, 300)}`,
+    )
+  }
+
+  const result = ChairmanOutputSchema.safeParse(parsed)
+  if (!result.success) {
+    throw new Error(
+      `Council chairman: output failed schema validation. Issues: ${JSON.stringify(result.error.issues)}`,
+    )
+  }
+
+  return result.data
+}

package/modules/council/deliberate.ts

@@ -0,0 +1,106 @@
+import type { CouncilInput, CouncilOutput, CouncilDeps } from "./types"
+import { DEFAULT_PERSONAS } from "./personas"
+import { frameQuestion } from "./frame"
+import { fanOutAdvisors } from "./advisors"
+import { fanOutReviewers } from "./reviewers"
+import { chairman } from "./chairman"
+
+const DEFAULT_ADVISOR_COUNT = 5
+const DEFAULT_REVIEWER_COUNT = 5
+
+/**
+ * Run the Council deliberation pipeline.
+ *
+ * Pipeline:
+ *   1. frameQuestion     — reframe outcome + design into a deliberation brief
+ *   2. fanOutAdvisors    — N advisors reason in parallel from Oracle evidence
+ *   3. fanOutReviewers   — N reviewers critique anonymised advisor responses in parallel
+ *   4. chairman          — synthesises verdict, cites Oracle entry IDs
+ *   5. oracle.propose()  — proposes verdict to Chronicle (human approval required to commit)
+ *
+ * The council_brief from jury_output determines framing tone:
+ *   "challenge"      → find what is wrong (Jury confidence < 0.6)
+ *   "pressure-test"  → try to break what looks solid (Jury confidence ≥ 0.6)
+ *
+ * Routing on output:
+ *   satisfied: true                           → proceed to human gate → Executor
+ *   satisfied: false, recommendation: redesign         → return to Designer
+ *   satisfied: false, recommendation: investigate-more → return to Detective with gaps list
+ */
+export async function deliberate(
+  input: CouncilInput,
+  deps: CouncilDeps,
+): Promise<CouncilOutput> {
+  const {
+    llm,
+    oracle,
+    advisorCount = DEFAULT_ADVISOR_COUNT,
+    reviewerCount = DEFAULT_REVIEWER_COUNT,
+    models = {},
+  } = deps
+
+  // Select personas — cycle DEFAULT_PERSONAS if advisorCount > 5
+  const personas = Array.from(
+    { length: advisorCount },
+    (_, i) => DEFAULT_PERSONAS[i % DEFAULT_PERSONAS.length],
+  )
+
+  // 1. Frame the deliberation question
+  const framedQuestion = await frameQuestion(input, llm, models.frame)
+
+  // 2. Advisors reason in parallel
+  const advisorResponses = await fanOutAdvisors(
+    framedQuestion,
+    input.evidence,
+    personas,
+    llm,
+    models.advisors,
+  )
+
+  // 3. Reviewers critique in parallel (advisor responses anonymised inside fanOutReviewers)
+  const reviewerResponses = await fanOutReviewers(
+    advisorResponses,
+    input.evidence,
+    reviewerCount,
+    llm,
+    models.reviewers,
+  )
+
+  // 4. Chairman synthesises verdict
+  const verdict = await chairman(
+    advisorResponses,
+    reviewerResponses,
+    input.evidence,
+    llm,
+    models.chairman,
+  )
+
+  // 5. Propose verdict to Oracle — human must call oracle.commit() to index it
+  // Truncate to 200 chars so it passes propose()'s schema validation.
+  const firstSentence = verdict.verdict.split(/[.!?]/)[0]?.trim() ?? ""
+  const keyInsight = (firstSentence.length >= 20 ? firstSentence : verdict.verdict)
+    .slice(0, 200)
+
+  await oracle.propose({
+    key_insight: keyInsight,
+    affected_areas: extractAffectedAreas(input.outcome, input.design),
+    status: "open",
+    confidence: input.jury_output.confidence,
+    source_module: "council",
+    evidence_cited: verdict.evidence_cited,
+  })
+
+  return verdict
+}
+
+/**
+ * Extract candidate affected areas from the outcome and design text.
+ * Looks for capitalised noun phrases as a simple heuristic.
+ * The host application may override by post-processing CouncilOutput.
+ */
+function extractAffectedAreas(outcome: string, design: string): string[] {
+  const text = `${outcome} ${design}`
+  const phrases = text.match(/\b[A-Z][a-zA-Z]+(?:\s[A-Z][a-zA-Z]+)*\b/g) ?? []
+  const unique = [...new Set(phrases)]
+  return unique.length > 0 ? unique.slice(0, 5) : ["general"]
+}

package/modules/council/frame.ts

@@ -0,0 +1,54 @@
+import type { LLMProvider } from "../shared/types"
+import type { CouncilInput } from "./types"
+
+/**
+ * Reframe the outcome + design into a clear deliberation brief for the advisor panel.
+ * Tone and scope are set by the Jury's council_brief value.
+ */
+export async function frameQuestion(
+  input: CouncilInput,
+  llm: LLMProvider,
+  model?: string,
+): Promise<string> {
+  const { outcome, design, jury_output } = input
+
+  const briefInstruction =
+    jury_output.council_brief === "challenge"
+      ? `The Jury has LOW confidence (score: ${jury_output.confidence.toFixed(2)}). ` +
+        "Find what is WRONG with this design. Look for fundamental flaws, not just edge cases."
+      : `The Jury has HIGH confidence (score: ${jury_output.confidence.toFixed(2)}). ` +
+        "PRESSURE-TEST this design. Assume it is broadly correct — try to break it. " +
+        "Find edge cases, scaling failures, and hidden assumptions."
+
+  const systemPrompt = [
+    "You are the Council Framer. You write the deliberation brief that a panel of expert advisors will work from.",
+    "",
+    "Write a clear, precise brief that:",
+    "1. States what needs to be achieved (the outcome)",
+    "2. States what is being proposed (the design)",
+    "3. States the Jury's assessment and the gaps it identified",
+    "4. Sets the council directive — challenge or pressure-test",
+    "",
+    "Keep it under 300 words. Be direct. Advisors must know exactly what to evaluate.",
+  ].join("\n")
+
+  const userPrompt = [
+    `Outcome: ${outcome}`,
+    "",
+    `Design: ${design}`,
+    "",
+    `Jury assessment: ${jury_output.assessment}`,
+    `Jury confidence: ${jury_output.confidence.toFixed(2)}`,
+    `Jury gaps: ${jury_output.gaps.join("; ") || "none identified"}`,
+    "",
+    briefInstruction,
+  ].join("\n")
+
+  return llm(
+    [
+      { role: "system", content: systemPrompt },
+      { role: "user", content: userPrompt },
+    ],
+    model,
+  )
+}

package/modules/council/index.ts

@@ -0,0 +1,4 @@
+export { deliberate } from "./deliberate"
+export type { CouncilInput, CouncilOutput, CouncilDeps, CouncilModels } from "./types"
+export { DEFAULT_PERSONAS } from "./personas"
+export type { AdvisorPersona } from "./personas"