@balpal4495/quorum 0.1.0

package/modules/sentinel/drift.ts

@@ -0,0 +1,159 @@
+import { promises as fs } from "fs"
+import path from "path"
+import type { ChronicleEntry, DriftFlag, DriftReport, LLMProvider } from "../shared/types"
+
+const FILE_CONTENT_LIMIT = 3000
+
+async function readCommittedEntries(chronicleDir: string): Promise<ChronicleEntry[]> {
+  const committedDir = path.join(chronicleDir, "committed")
+  let files: string[]
+  try {
+    files = await fs.readdir(committedDir)
+  } catch {
+    return []
+  }
+  const entries: ChronicleEntry[] = []
+  for (const file of files) {
+    if (!file.endsWith(".json")) continue
+    try {
+      const raw = await fs.readFile(path.join(committedDir, file), "utf8")
+      entries.push(JSON.parse(raw) as ChronicleEntry)
+    } catch {
+      // skip malformed
+    }
+  }
+  return entries
+}
+
+async function resolveLocalFiles(areas: string[], codebasePath: string): Promise<string[]> {
+  const resolved: string[] = []
+  for (const area of areas) {
+    // Try as a direct relative path first
+    const candidate = path.join(codebasePath, area)
+    try {
+      await fs.access(candidate)
+      resolved.push(candidate)
+      continue
+    } catch {
+      // not a direct path — try substring search
+    }
+    // Walk up to two levels to find files whose relative path contains the area string
+    try {
+      const all = await fs.readdir(codebasePath, { recursive: true, encoding: "utf8" })
+      for (const f of all) {
+        const normalised = f.replace(/\\/g, "/")
+        if (normalised.includes(area.replace(/\\/g, "/")) && normalised.endsWith(".ts")) {
+          resolved.push(path.join(codebasePath, f))
+          break
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+  return [...new Set(resolved)]
+}
+
+async function evaluateDrift(
+  entry: ChronicleEntry,
+  files: Array<{ filePath: string; content: string }>,
+  llm: LLMProvider,
+): Promise<DriftFlag> {
+  const fileSection = files
+    .map(f => `### ${path.basename(f.filePath)}\n\`\`\`\n${f.content.slice(0, FILE_CONTENT_LIMIT)}\n\`\`\``)
+    .join("\n\n")
+
+  const response = await llm([
+    {
+      role: "system",
+      content:
+        "You are a code reviewer checking whether a documented insight still accurately describes the current source code. " +
+        "Reply with a JSON object only — no markdown, no explanation outside the object.",
+    },
+    {
+      role: "user",
+      content:
+        `Documented insight:\n"${entry.key_insight}"\n\n` +
+        `Current source:\n${fileSection}\n\n` +
+        `Does this insight still accurately describe the code above?\n` +
+        `{"stillValid": boolean, "confidence": number, "reasoning": "one sentence"}`,
+    },
+  ])
+
+  try {
+    const match = response.match(/\{[\s\S]*?\}/)
+    if (!match) throw new Error("no JSON")
+    const parsed = JSON.parse(match[0]) as { stillValid?: unknown; confidence?: unknown; reasoning?: unknown }
+    return {
+      entryId: entry.id,
+      keyInsight: entry.key_insight,
+      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,
+      reasoning: typeof parsed.reasoning === "string" ? parsed.reasoning : "no reasoning provided",
+    }
+  } catch {
+    // Parse failure → conservative: flag for human review
+    return {
+      entryId: entry.id,
+      keyInsight: entry.key_insight,
+      affectedFiles: files.map(f => f.filePath),
+      stillValid: false,
+      confidence: 0,
+      reasoning: "LLM response could not be parsed — manual review recommended",
+    }
+  }
+}
+
+/**
+ * For each Chronicle entry whose affected_areas resolves to at least one local
+ * source file, ask the LLM whether the key_insight still accurately describes
+ * the current code.
+ *
+ * Output is strictly advisory — entries are never updated autonomously.
+ * Entries where no affected_areas value resolves to a local file are skipped
+ * (e.g. entries about external tools, workflows, or conceptual areas).
+ */
+export async function detectDrift(
+  chronicleDir: string,
+  codebasePath: string,
+  llm: LLMProvider,
+): Promise<DriftReport> {
+  const entries = await readCommittedEntries(chronicleDir)
+
+  const flags: DriftFlag[] = []
+  const confirmed: DriftFlag[] = []
+  const skipped: string[] = []
+
+  for (const entry of entries) {
+    const localPaths = await resolveLocalFiles(entry.affected_areas, codebasePath)
+    if (localPaths.length === 0) {
+      skipped.push(entry.id)
+      continue
+    }
+
+    const files: Array<{ filePath: string; content: string }> = []
+    for (const p of localPaths) {
+      try {
+        const content = await fs.readFile(p, "utf8")
+        files.push({ filePath: p, content })
+      } catch {
+        // file unreadable — skip this path
+      }
+    }
+
+    if (files.length === 0) {
+      skipped.push(entry.id)
+      continue
+    }
+
+    const result = await evaluateDrift(entry, files, llm)
+    if (result.stillValid) {
+      confirmed.push(result)
+    } else {
+      flags.push(result)
+    }
+  }
+
+  return { checkedAt: new Date().toISOString(), flags, confirmed, skipped }
+}

package/modules/sentinel/index.ts

@@ -0,0 +1,6 @@
+export { coverage } from "./coverage"
+export { detectDrift } from "./drift"
+export { reviewContext } from "./review"
+export { sentinelAssertions } from "./assert"
+export type { CoverageReport, FileCoverage, DriftReport, DriftFlag } from "../shared/types"
+export type { SentinelAssertOptions } from "./assert"

package/modules/sentinel/review.ts

@@ -0,0 +1,207 @@
+import { promises as fs } from "fs"
+import path from "path"
+import type { ChronicleEntry } from "../shared/types"
+import { coverage as runCoverage } from "./coverage"
+
+function extractModule(filePath: string): string {
+  const normalised = filePath.replace(/\\/g, "/").replace(/^\/+/, "")
+  const stripped = normalised.replace(/^modules\//, "")
+  const parts = stripped.split("/")
+  return parts.length === 1 ? "(root)" : parts[0]
+}
+
+function mermaidSafe(str: string): string {
+  return str.replace(/[^a-zA-Z0-9_]/g, "_")
+}
+
+function riskClass(pct: number): "high" | "medium" | "good" {
+  if (pct === 0) return "high"
+  if (pct < 50) return "medium"
+  return "good"
+}
+
+function riskLabel(pct: number): string {
+  if (pct === 0) return "high"
+  if (pct < 50) return "medium"
+  return "low"
+}
+
+function isoWeekKey(date: Date): string {
+  const d = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()))
+  const day = d.getUTCDay() || 7
+  d.setUTCDate(d.getUTCDate() + 4 - day)
+  const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1))
+  const week = Math.ceil(((d.getTime() - yearStart.getTime()) / 86_400_000 + 1) / 7)
+  return `${d.getUTCFullYear()}-W${String(week).padStart(2, "0")}`
+}
+
+async function readCommittedEntries(chronicleDir: string): Promise<ChronicleEntry[]> {
+  const committedDir = path.join(chronicleDir, "committed")
+  let files: string[]
+  try {
+    files = await fs.readdir(committedDir)
+  } catch {
+    return []
+  }
+  const entries: ChronicleEntry[] = []
+  for (const file of files) {
+    if (!file.endsWith(".json")) continue
+    try {
+      const raw = await fs.readFile(path.join(committedDir, file), "utf8")
+      entries.push(JSON.parse(raw) as ChronicleEntry)
+    } catch {
+      // skip malformed
+    }
+  }
+  return entries
+}
+
+type ModuleStat = {
+  name: string
+  totalFiles: number
+  coveredFiles: number
+  entryIds: string[]
+  changedFiles: number
+  percentage: number
+}
+
+/**
+ * Generate a PR-level Chronicle coverage map as a markdown string ready to
+ * post as a PR comment.
+ *
+ * Produces three zones:
+ *   1. Coverage table — all modules with coverage %, entry count, file count,
+ *      PR delta, and risk. Changed modules are bolded.
+ *   2. Heatmap diagram — Chronicle → modules, nodes coloured by risk level,
+ *      labels show coverage % and change count in one visual.
+ *   3. Chronicle context — entries for touched modules only.
+ *
+ * Deterministic — no LLM required. Pass changedFiles from `git diff --name-only`.
+ */
+export async function reviewContext(
+  changedFiles: string[],
+  chronicleDir: string,
+  codebasePath: string,
+): Promise<string> {
+  const filtered = changedFiles.filter(f => f.trim().length > 0)
+  if (filtered.length === 0) return "<!-- sentinel: no changed files -->"
+
+  const [report, allEntries] = await Promise.all([
+    runCoverage(chronicleDir, codebasePath),
+    readCommittedEntries(chronicleDir),
+  ])
+
+  // Count changed files per module
+  const changedByModule = new Map<string, number>()
+  for (const file of filtered) {
+    const mod = extractModule(file)
+    changedByModule.set(mod, (changedByModule.get(mod) ?? 0) + 1)
+  }
+
+  // Build per-module stats from coverage report
+  const moduleStats = new Map<string, ModuleStat>()
+  for (const f of report.coverageByFile) {
+    const mod = extractModule(f.file)
+    const stat = moduleStats.get(mod) ?? {
+      name: mod, totalFiles: 0, coveredFiles: 0,
+      entryIds: [], changedFiles: changedByModule.get(mod) ?? 0, percentage: 0,
+    }
+    stat.totalFiles++
+    if (f.covered) {
+      stat.coveredFiles++
+      for (const id of f.entryIds) {
+        if (!stat.entryIds.includes(id)) stat.entryIds.push(id)
+      }
+    }
+    moduleStats.set(mod, stat)
+  }
+
+  // Include modules only referenced by changedFiles but not in codebase scan
+  for (const [mod, count] of changedByModule) {
+    if (!moduleStats.has(mod)) {
+      moduleStats.set(mod, {
+        name: mod, totalFiles: count, coveredFiles: 0,
+        entryIds: [], changedFiles: count, percentage: 0,
+      })
+    }
+  }
+
+  for (const stat of moduleStats.values()) {
+    stat.percentage = stat.totalFiles === 0
+      ? 0
+      : Math.round((stat.coveredFiles / stat.totalFiles) * 100)
+  }
+
+  const allModules = [...moduleStats.values()].sort((a, b) =>
+    a.name === "(root)" ? 1 : b.name === "(root)" ? -1 : a.name.localeCompare(b.name),
+  )
+  const touchedModules = allModules.filter(m => m.changedFiles > 0)
+
+  const lines: string[] = []
+  const week = isoWeekKey(new Date())
+  const chronicleIsEmpty = allEntries.length === 0
+
+  // ── Header ────────────────────────────────────────────────────────────────
+  lines.push(`## Sentinel — Chronicle Coverage Map — ${week}`)
+  lines.push("")
+
+  if (chronicleIsEmpty) {
+    lines.push(
+      "> **Chronicle has no entries yet.** Every module shows as uncovered because this project has no documented knowledge. " +
+      "The modules touched by this PR are a good starting point — run `oracle.propose()` after this lands to begin building Chronicle.",
+    )
+    lines.push("")
+  }
+
+  // ── Coverage table ────────────────────────────────────────────────────────
+  lines.push("| Module | Coverage | Entries | Files | PR Changes | Risk |")
+  lines.push("|--------|----------|---------|-------|------------|------|")
+  for (const stat of allModules) {
+    const name = stat.changedFiles > 0 ? `**${stat.name}/**` : `${stat.name}/`
+    const pct = `${stat.percentage}%`
+    const changed = stat.changedFiles > 0 ? `**${stat.changedFiles} files**` : "—"
+    lines.push(
+      `| ${name} | ${pct} | ${stat.entryIds.length} | ${stat.totalFiles} | ${changed} | ${riskLabel(stat.percentage)} |`,
+    )
+  }
+  lines.push("")
+
+  // ── Heatmap diagram ───────────────────────────────────────────────────────
+  lines.push("```mermaid")
+  lines.push("flowchart TD")
+  lines.push("    classDef high fill:#fca5a5,stroke:#dc2626")
+  lines.push("    classDef medium fill:#fde68a,stroke:#d97706")
+  lines.push("    classDef good fill:#bbf7d0,stroke:#16a34a")
+  lines.push("    Chronicle[(Chronicle)]")
+  for (const stat of allModules) {
+    const nodeId = mermaidSafe(stat.name)
+    const changed = stat.changedFiles > 0 ? ` — ${stat.changedFiles} changed` : ""
+    const label = `${stat.name} — ${stat.percentage}%${changed}`
+    const cls = riskClass(stat.percentage)
+    lines.push(`    Chronicle --> ${nodeId}["${label}"]:::${cls}`)
+  }
+  lines.push("```")
+  lines.push("")
+
+  // ── Chronicle context for touched modules ─────────────────────────────────
+  const touchedWithEntries = touchedModules.filter(m => m.entryIds.length > 0)
+  if (touchedWithEntries.length > 0) {
+    lines.push("### Chronicle context for changed modules")
+    lines.push("")
+    for (const stat of touchedWithEntries) {
+      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.status} — confidence ${entry.confidence.toFixed(2)}*`)
+      }
+      lines.push("")
+    }
+  }
+
+  // ── Footer ────────────────────────────────────────────────────────────────
+  lines.push("---")
+  lines.push("*Risk: high = 0% coverage, medium = 1-49%, low = 50%+*")
+
+  return lines.join("\n")
+}

package/modules/setup.ts

@@ -0,0 +1,153 @@
+import path from "path"
+import { promises as fs } from "fs"
+import { createOracleClient } from "./oracle/index"
+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 type { LLMProvider, OracleClient } from "./shared/types"
+import type { JuryInput, JuryOutput, JuryDeps } from "./jury/types"
+import type { CouncilInput, CouncilOutput, CouncilDeps, CouncilModels } from "./council/types"
+
+export interface SetupOptions {
+  /**
+   * Injectable LLM provider.
+   * All modules that need an LLM receive this function.
+   * Ignored by Oracle (which has no LLM dependency).
+   */
+  llm: LLMProvider
+
+  /**
+   * Root directory for Chronicle data.
+   * Default: ".chronicle" (relative to process.cwd())
+   */
+  chronicleDir?: string
+
+  /**
+   * Model overrides for each reasoning step.
+   * If omitted, the LLM provider's default model is used for all steps.
+   */
+  models?: {
+    jury?: string
+    council?: CouncilModels
+  }
+
+  /**
+   * Pre-warm the local ONNX embedder during setup so the first query
+   * is not slow. Set to false to skip (e.g. in test environments).
+   * Default: true
+   */
+  warmEmbedder?: boolean
+
+  /**
+   * Swap the default embedder (Xenova all-MiniLM-L6-v2) for your own.
+   * Must return a vector of consistent dimension.
+   */
+  embedder?: (text: string) => Promise<number[]>
+}
+
+export interface Modules {
+  /**
+   * Fully wired OracleClient.
+   * Use oracle.query() to retrieve evidence.
+   * Use oracle.propose() + oracle.commit() for the human-gated write path.
+   */
+  oracle: OracleClient
+
+  /**
+   * Evaluate a proposed design against Oracle evidence.
+   * Returns a confidence score and the Council brief for the next step.
+   */
+  evaluate: (input: Omit<JuryInput, never>) => Promise<JuryOutput>
+
+  /**
+   * Run the full Council deliberation pipeline.
+   * Proposes the verdict to Oracle automatically — a human must call
+   * oracle.commit(proposalId) to index it into Chronicle.
+   */
+  deliberate: (
+    input: Omit<CouncilInput, "jury_output"> & { jury_output: JuryOutput },
+  ) => Promise<CouncilOutput>
+}
+
+/**
+ * Wire up all three modules from a single call.
+ *
+ * @example
+ * import { setup } from "./modules/setup"
+ *
+ * const { oracle, evaluate, deliberate } = await setup({
+ *   llm: myLLMProvider,
+ * })
+ *
+ * const evidence  = await oracle.query("authentication patterns")
+ * const jury      = await evaluate({ outcome, design, evidence })
+ * const verdict   = await deliberate({ outcome, design, evidence, jury_output: jury })
+ *
+ * if (verdict.satisfied) {
+ *   // → human gate → Executor
+ * }
+ */
+export async function setup(options: SetupOptions): Promise<Modules> {
+  const {
+    llm,
+    chronicleDir = ".chronicle",
+    models = {},
+    warmEmbedder: shouldWarm = true,
+    embedder = xenovaEmbed,
+  } = options
+
+  // Ensure Chronicle directories exist before anything tries to write to them
+  await fs.mkdir(path.join(chronicleDir, "proposals"), { recursive: true })
+  await fs.mkdir(path.join(chronicleDir, "committed"), { recursive: true })
+
+  // Pre-warm the embedder if using the default (downloads model on first use)
+  if (shouldWarm && embedder === xenovaEmbed) {
+    await warmEmbedder()
+  }
+
+  const vectorStore = await createLanceDBStore(chronicleDir)
+
+  // Rebuild local index from committed entries if any are missing.
+  // This brings a fresh machine (or a post-git-pull state) up to date
+  // without requiring any manual step.
+  const committedDir = path.join(chronicleDir, "committed")
+  const committedFiles = (await fs.readdir(committedDir)).filter(f => f.endsWith(".json"))
+
+  if (committedFiles.length > 0) {
+    const existing = await vectorStore.getAll()
+    const existingIds = new Set(existing.map(e => e.id))
+    const missing = committedFiles.filter(f => !existingIds.has(f.replace(".json", "")))
+
+    if (missing.length > 0) {
+      console.log(`[Chronicle] Rebuilding index from ${missing.length} committed ${missing.length === 1 ? "entry" : "entries"}…`)
+      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 vector = await embedder(embeddingText)
+        await vectorStore.upsert(entry.id, vector, entry)
+      }
+    }
+  }
+
+  const oracle = createOracleClient({
+    embedder,
+    vectorStore,
+    chronicleDir,
+  })
+
+  return {
+    oracle,
+
+    evaluate: (input: JuryInput) =>
+      evaluate(input, { llm, model: models.jury }),
+
+    deliberate: (input: CouncilInput) =>
+      deliberate(input, {
+        llm,
+        oracle,
+        models: models.council,
+      }),
+  }
+}

package/modules/shared/types.ts

@@ -0,0 +1,148 @@
+/**
+ * Shared types used across Oracle, Jury, and Council modules.
+ * These are the only types that cross module boundaries.
+ */
+
+export type Message = {
+  role: "system" | "user" | "assistant"
+  content: string
+}
+
+/**
+ * Injectable LLM provider. Accepts a message array and optional model override.
+ * Returns the assistant response as a string.
+ *
+ * The modules never hardcode a provider — wire this at the application level.
+ */
+export type LLMProvider = (messages: Message[], model?: string) => Promise<string>
+
+/**
+ * Links a Chronicle entry to the unit of work that triggered it.
+ * Gives agents the "why now" context that key_insight alone cannot convey.
+ */
+export type WorkRef = {
+  type: "bug" | "story" | "epic" | "pr" | "spike"
+  /** Ticket number, PR reference, or branch name. e.g. "PROJ-123", "PR #4" */
+  ref?: string
+}
+
+/**
+ * A durable knowledge record stored in Chronicle.
+ * This is the canonical unit of institutional memory.
+ */
+export type ChronicleEntry = {
+  id: string
+  /** The core finding or decision, in one clear sentence. */
+  key_insight: string
+  /** Parts of the codebase or system this entry applies to. */
+  affected_areas: string[]
+  status: "validated" | "refuted" | "open"
+  /** 0–1. How strongly this was confirmed at write time. */
+  confidence: number
+  /** Which module produced this entry (detective, council, executor, etc.). */
+  source_module: string
+  /** IDs of Chronicle entries this decision was based on. */
+  evidence_cited: string[]
+  /** What actually happened when this was acted on. Added post-execution by Scribe. */
+  outcome?: string
+  /** The unit of work that triggered this entry. Used to build SUMMARY.md temporal context. */
+  work_ref?: WorkRef
+  timestamp: string
+}
+
+/**
+ * A Chronicle entry enriched with its retrieval score and relevance tier.
+ * Returned by Oracle.query().
+ *
+ * Tiers indicate relevance within the result set:
+ *   primary    — top ~30%: directly answers the query, should be foregrounded
+ *   supporting — middle ~40%: contextually relevant, useful but not central
+ *   background — bottom ~30%: loosely related, de-emphasise but do not hide
+ */
+export type OracleResult = ChronicleEntry & {
+  score: number
+  tier: "primary" | "supporting" | "background"
+}
+
+/**
+ * Returned by oracle.propose() when a high-similarity entry already exists.
+ * The human gate should surface this before approving the commit.
+ */
+export type SimilarityWarning = {
+  entry: ChronicleEntry
+  score: number
+  /** potential-duplicate: near-identical insight. potential-supersession: likely a correction. */
+  warning: "potential-duplicate" | "potential-supersession"
+}
+
+export type QueryOptions = {
+  statusFilter?: Array<"validated" | "refuted" | "open">
+  /** Maximum results to return. Default: 10. */
+  limit?: number
+  /**
+   * Minimum RRF score to include a result.
+   * Results below this threshold are dropped entirely — better to return nothing than noise.
+   * Default: 0.031.
+   */
+  scoreThreshold?: number
+}
+
+// ── Sentinel types ────────────────────────────────────────────────────────────
+
+/** Per-file result from sentinel.coverage(). */
+export type FileCoverage = {
+  file: string
+  covered: boolean
+  /** IDs of Chronicle entries that reference this file in affected_areas. */
+  entryIds: string[]
+}
+
+/** Returned by sentinel.coverage(). */
+export type CoverageReport = {
+  totalFiles: number
+  coveredFiles: number
+  uncoveredFiles: string[]
+  coverageByFile: FileCoverage[]
+  /** Integer 0–100. Treat as directional signal, not a precision metric. */
+  percentage: number
+}
+
+/**
+ * Advisory result for a single Chronicle entry from sentinel.detectDrift().
+ * Never auto-updates an entry — human reviews the flag and decides.
+ */
+export type DriftFlag = {
+  entryId: string
+  keyInsight: string
+  affectedFiles: string[]
+  stillValid: boolean
+  /** 0–1 confidence in the LLM's verdict. Low confidence = needs closer human review. */
+  confidence: number
+  reasoning: string
+}
+
+/** Returned by sentinel.detectDrift(). */
+export type DriftReport = {
+  checkedAt: string
+  /** Entries the LLM judged as no longer accurate — review and consider updating status. */
+  flags: DriftFlag[]
+  /** Entries the LLM judged as still current. */
+  confirmed: DriftFlag[]
+  /** Entry IDs skipped because no affected_areas value resolved to a local file. */
+  skipped: string[]
+}
+
+// ── Oracle client ─────────────────────────────────────────────────────────────
+
+/**
+ * The public interface any module uses to interact with Chronicle.
+ * Inject this into Jury and Council — do not couple them to Oracle internals.
+ */
+export interface OracleClient {
+  query: (text: string, options?: QueryOptions) => Promise<OracleResult[]>
+  propose: (
+    entry: Omit<ChronicleEntry, "id" | "timestamp">,
+  ) => Promise<{ proposalId: string; similarity?: SimilarityWarning }>
+  /** Called after human approval. Indexes the proposal into Chronicle. */
+  commit: (proposalId: string) => Promise<ChronicleEntry>
+}