@balpal4495/quorum 0.1.10 → 0.2.0

package/modules/council/advisors.ts

@@ -1,4 +1,5 @@
 import type { LLMProvider, OracleResult } from "../shared/types"
+import { entryText } from "../shared/types"
 import type { AdvisorPersona } from "./personas"
 
 export interface AdvisorResponse {
@@ -12,7 +13,9 @@ function formatEvidence(evidence: OracleResult[]): string {
   }
   return evidence
     .map(e =>
-      `[${e.id}] (${e.status})\n${e.key_insight}\nAreas: ${e.affected_areas.join(", ")}`,
+      `[${e.id}] (${e.status})
+${entryText(e)}
+Areas: ${e.affected_areas.join(", ")}${e.scope ? " | " + e.scope.join(", ") : ""}`,
     )
     .join("\n\n")
 }

package/modules/council/chairman.ts

@@ -1,5 +1,6 @@
 import { z } from "zod"
 import type { LLMProvider, OracleResult } from "../shared/types"
+import { entryText } from "../shared/types"
 import type { AdvisorResponse } from "./advisors"
 import type { ReviewerResponse } from "./reviewers"
 import type { CouncilOutput } from "./types"
@@ -29,7 +30,7 @@ function formatEvidence(evidence: OracleResult[]): string {
   return evidence
     .map(
       e =>
-        `[${e.id}] (${e.status}, confidence: ${e.confidence.toFixed(2)}) ${e.key_insight}`,
+        `[${e.id}] (${e.status}, confidence: ${e.confidence.toFixed(2)}) ${entryText(e)}`,
     )
     .join("\n")
 }

package/modules/council/deliberate.ts

@@ -82,8 +82,13 @@ export async function deliberate(
     .slice(0, 200)
 
   await oracle.propose({
+    schema_version: 2,
+    topic: input.outcome.slice(0, 80),
+    decision: keyInsight,
     key_insight: keyInsight,
     affected_areas: extractAffectedAreas(input.outcome, input.design),
+    alternatives_considered: verdict.challenges,
+    rejected_reason: verdict.satisfied ? [] : [verdict.verdict.slice(0, 200)],
     status: "open",
     confidence: input.jury_output.confidence,
     source_module: "council",

package/modules/council/reviewers.ts

@@ -1,4 +1,5 @@
 import type { LLMProvider, OracleResult } from "../shared/types"
+import { entryText } from "../shared/types"
 import type { AdvisorResponse } from "./advisors"
 
 export interface ReviewerResponse {
@@ -20,7 +21,7 @@ function anonymise(responses: AdvisorResponse[]): string {
 function formatEvidenceSummary(evidence: OracleResult[]): string {
   if (evidence.length === 0) return "No Oracle evidence available."
   return evidence
-    .map(e => `[${e.id}] (${e.status}) ${e.key_insight}`)
+    .map(e => `[${e.id}] (${e.status}) ${entryText(e)}`)
     .join("\n")
 }
 

package/modules/jury/evaluate.ts

@@ -1,5 +1,6 @@
 import type { JuryInput, JuryOutput, JuryDeps } from "./types"
 import type { OracleResult } from "../shared/types"
+import { entryText } from "../shared/types"
 import { JuryOutputSchema } from "./schema"
 
 const CONFIDENCE_THRESHOLD = 0.6
@@ -12,8 +13,8 @@ function formatEvidence(evidence: OracleResult[]): string {
     .map(e =>
       [
         `[${e.id}] status=${e.status}  confidence=${e.confidence.toFixed(2)}  score=${e.score.toFixed(3)}`,
-        `Insight: ${e.key_insight}`,
-        `Areas: ${e.affected_areas.join(", ")}`,
+        `Insight: ${entryText(e)}`,
+        `Areas: ${e.affected_areas.join(", ")}${e.scope ? " | " + e.scope.join(", ") : ""}`,
         e.outcome ? `Outcome: ${e.outcome}` : null,
       ]
         .filter(Boolean)

package/modules/oracle/propose.ts

@@ -4,6 +4,7 @@ import { randomUUID } from "crypto"
 import { exec } from "child_process"
 import { promisify } from "util"
 import type { ChronicleEntry, SimilarityWarning } from "../shared/types"
+import { entryText } from "../shared/types"
 import type { OracleDeps } from "./types"
 import { updateSummary } from "./summary"
 
@@ -27,6 +28,21 @@ function validateEntry(entry: Omit<ChronicleEntry, "id" | "timestamp">): void {
       `Distil to a single clear sentence.`,
     )
   }
+  if (entry.decision !== undefined) {
+    const d = entry.decision.trim()
+    if (d.length < INSIGHT_MIN_LENGTH) {
+      throw new Error(
+        `decision too short (${d.length} chars, min ${INSIGHT_MIN_LENGTH}). ` +
+        `Write a specific, complete sentence describing the decision.`,
+      )
+    }
+    if (d.length > INSIGHT_MAX_LENGTH) {
+      throw new Error(
+        `decision too long (${d.length} chars, max ${INSIGHT_MAX_LENGTH}). ` +
+        `Distil to a single clear sentence.`,
+      )
+    }
+  }
   if (!entry.affected_areas || entry.affected_areas.filter(a => a.trim()).length === 0) {
     throw new Error(`affected_areas must contain at least one non-empty entry.`)
   }
@@ -40,7 +56,7 @@ async function checkSimilarity(
   deps: OracleDeps,
 ): Promise<SimilarityWarning | undefined> {
   try {
-    const text = [entry.key_insight, ...entry.affected_areas].join(" ")
+    const text = [entryText(entry), ...entry.affected_areas, ...(entry.scope ?? [])].join(" ")
     const vector = await deps.embedder(text)
     const results = await deps.vectorStore.search(vector, 3)
     if (results.length === 0) return undefined
@@ -116,8 +132,8 @@ export async function commit(
     timestamp: new Date().toISOString(),
   }
 
-  // Embed the key insight (plus affected areas for richer retrieval)
-  const embeddingText = [entry.key_insight, ...entry.affected_areas].join(" ")
+  // Embed the primary text + areas + scope tags for richer retrieval
+  const embeddingText = [entryText(entry), ...entry.affected_areas, ...(entry.scope ?? [])].join(" ")
   const vector = await deps.embedder(embeddingText)
   await deps.vectorStore.upsert(entry.id, vector, entry)
 

package/modules/oracle/query.ts

@@ -1,4 +1,5 @@
 import type { ChronicleEntry, OracleResult, QueryOptions } from "../shared/types"
+import { entryText } from "../shared/types"
 import type { OracleDeps } from "./types"
 import { bm25Score, extractDomainTerms } from "./bm25"
 import { appendQueryLog } from "./log"
@@ -62,13 +63,13 @@ export async function query(
   // ── Pass 2: BM25 re-ranking with query enrichment ─────────────────────────
   const topInsights = candidates
     .slice(0, Math.min(5, candidates.length))
-    .map(c => c.entry.key_insight)
+    .map(c => entryText(c.entry))
   const domainTerms = extractDomainTerms(topInsights)
   const enrichedQuery =
     domainTerms.length > 0 ? `${text} ${domainTerms.join(" ")}` : text
 
   const documents = candidates.map(c =>
-    [c.entry.key_insight, ...c.entry.affected_areas].join(" "),
+    [entryText(c.entry), ...c.entry.affected_areas, ...(c.entry.scope ?? [])].join(" "),
   )
   const bm25Scores = bm25Score(enrichedQuery, documents)
 

package/modules/oracle/summary.ts

@@ -1,6 +1,7 @@
 import { promises as fs } from "fs"
 import path from "path"
 import type { ChronicleEntry } from "../shared/types"
+import { entryText } from "../shared/types"
 
 const SUMMARY_WEEKS = 12
 const DIRECTIVE =
@@ -29,7 +30,7 @@ function workRefLabel(entry: ChronicleEntry): string {
 function renderEntry(entry: ChronicleEntry): string {
   const areas = entry.affected_areas.join(", ")
   const id = entry.id.slice(0, 8)
-  return `- **[${id}]** ${areas} — \`${entry.status}\` (${entry.confidence.toFixed(2)}) — ${entry.key_insight}`
+  return `- **[${id}]** ${areas} — \`${entry.status}\` (${entry.confidence.toFixed(2)}) — ${entryText(entry)}`
 }
 
 /**

package/modules/sentinel/drift.ts

@@ -1,6 +1,7 @@
 import { promises as fs } from "fs"
 import path from "path"
 import type { ChronicleEntry, DriftFlag, DriftReport, LLMProvider } from "../shared/types"
+import { entryText } from "../shared/types"
 
 const FILE_CONTENT_LIMIT = 3000
 
@@ -73,7 +74,10 @@ async function evaluateDrift(
     {
       role: "user",
       content:
-        `Documented insight:\n"${entry.key_insight}"\n\n` +
+        `Documented insight:
+"${entryText(entry)}"
+
+` +
         `Current source:\n${fileSection}\n\n` +
         `Does this insight still accurately describe the code above?\n` +
         `{"stillValid": boolean, "confidence": number, "reasoning": "one sentence"}`,
@@ -86,7 +90,7 @@ async function evaluateDrift(
     const parsed = JSON.parse(match[0]) as { stillValid?: unknown; confidence?: unknown; reasoning?: unknown }
     return {
       entryId: entry.id,
-      keyInsight: entry.key_insight,
+      keyInsight: entryText(entry),
       affectedFiles: files.map(f => f.filePath),
       stillValid: Boolean(parsed.stillValid),
       confidence: typeof parsed.confidence === "number" ? Math.max(0, Math.min(1, parsed.confidence)) : 0.5,
@@ -96,7 +100,7 @@ async function evaluateDrift(
     // Parse failure → conservative: flag for human review
     return {
       entryId: entry.id,
-      keyInsight: entry.key_insight,
+      keyInsight: entryText(entry),
       affectedFiles: files.map(f => f.filePath),
       stillValid: false,
       confidence: 0,

package/modules/sentinel/review.ts

@@ -1,6 +1,7 @@
 import { promises as fs } from "fs"
 import path from "path"
 import type { ChronicleEntry } from "../shared/types"
+import { entryText } from "../shared/types"
 import { coverage as runCoverage } from "./coverage"
 
 function extractModule(filePath: string): string {
@@ -192,7 +193,7 @@ export async function reviewContext(
       lines.push(`**${stat.name}/**`)
       const relevant = allEntries.filter(e => stat.entryIds.includes(e.id))
       for (const entry of relevant) {
-        lines.push(`- \`[${entry.id.slice(0, 8)}]\` ${entry.key_insight}`)
+        lines.push(`- \`[${entry.id.slice(0, 8)}]\` ${entryText(entry)}`)
         lines.push(`  *${entry.status} — confidence ${entry.confidence.toFixed(2)}*`)
       }
       lines.push("")

package/modules/setup.ts

@@ -6,6 +6,7 @@ import { createLanceDBStore } from "./oracle/adapters/lance-db"
 import { evaluate } from "./jury/evaluate"
 import { deliberate } from "./council/deliberate"
 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"
 
@@ -124,7 +125,7 @@ export async function setup(options: SetupOptions): Promise<Modules> {
       for (const file of missing) {
         const raw = await fs.readFile(path.join(committedDir, file), "utf8")
         const entry = JSON.parse(raw) as import("./shared/types").ChronicleEntry
-        const embeddingText = [entry.key_insight, ...entry.affected_areas].join(" ")
+        const embeddingText = [entryText(entry), ...entry.affected_areas, ...(entry.scope ?? [])].join(" ")
         const vector = await embedder(embeddingText)
         await vectorStore.upsert(entry.id, vector, entry)
       }

package/modules/shared/types.ts

@@ -29,12 +29,19 @@ export type WorkRef = {
 /**
  * A durable knowledge record stored in Chronicle.
  * This is the canonical unit of institutional memory.
+ *
+ * Schema versions:
+ *   v1 (no schema_version field): key_insight is the primary text field.
+ *   v2 (schema_version: 2): decision is the primary text field; key_insight is a copy
+ *       of decision written for backwards compatibility. Always use entryText() to read.
  */
 export type ChronicleEntry = {
   id: string
-  /** The core finding or decision, in one clear sentence. */
+
+  // ── v1 fields (required — always present) ───────────────────────────────
+  /** The core finding or decision, in one clear sentence. v2: copy of decision. */
   key_insight: string
-  /** Parts of the codebase or system this entry applies to. */
+  /** File paths or system areas this entry applies to. Used by Sentinel for file matching. */
   affected_areas: string[]
   status: "validated" | "refuted" | "open"
   /** 0–1. How strongly this was confirmed at write time. */
@@ -48,6 +55,36 @@ export type ChronicleEntry = {
   /** The unit of work that triggered this entry. Used to build SUMMARY.md temporal context. */
   work_ref?: WorkRef
   timestamp: string
+
+  // ── v2 fields (optional — absent on legacy entries) ──────────────────────
+  /** 2 = decision record format. Absent = v1 legacy entry. */
+  schema_version?: 2
+  /** Short label for this decision. e.g. "auth/session strategy" */
+  topic?: string
+  /** The decision itself — the primary text field in v2. Use entryText() to read. */
+  decision?: string
+  /** Domain/category tags. Additive — does NOT replace affected_areas. e.g. ["auth", "sessions"] */
+  scope?: string[]
+  /** Approaches that were considered but not chosen. */
+  alternatives_considered?: string[]
+  /** Why the alternatives were rejected. */
+  rejected_reason?: string[]
+  /** ID of the Chronicle entry this supersedes. */
+  supersedes?: string | null
+  /** ID of the Chronicle entry that superseded this one. */
+  superseded_by?: string | null
+}
+
+/**
+ * Return the primary text for a Chronicle entry regardless of schema version.
+ * v2 entries use decision; v1 entries use key_insight.
+ * All callsites that render or embed entry text must use this function.
+ *
+ * Accepts any object with key_insight and optional decision — works for both
+ * full ChronicleEntry and Omit<ChronicleEntry, "id" | "timestamp"> from propose().
+ */
+export function entryText(entry: { key_insight: string; decision?: string }): string {
+  return entry.decision ?? entry.key_insight
 }
 
 /**

package/package.json

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