@balpal4495/quorum 3.0.3 → 3.1.0

package/modules/sentinel/review.ts

@@ -1,208 +0,0 @@
-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 {
-  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)}]\` ${entryText(entry)}`)
-        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

@@ -1,202 +0,0 @@
-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 { 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"
-import { createCompass } from "./compass/create"
-import { defaultSources } from "./compass/sources/index"
-import type { Compass, CreateCompassOptions } from "./compass/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
-    compass?: {
-      brief?: string
-      pathways?: string
-      bets?: string
-      score?: string
-    }
-  }
-
-  /**
-   * Root directory for scanning source files (used by Compass).
-   * Default: process.cwd()
-   */
-  rootDir?: string
-
-  /**
-   * 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>
-
-  /**
-   * 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>
-
-  /**
-   * Product-direction module.
-   * Synthesises Chronicle memory and current codebase behaviour into
-   * pathways, bets, briefs, and opportunities.
-   * All writes go through oracle.propose() — never auto-committed.
-   */
-  compass: Compass
-}
-
-/**
- * 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",
-    rootDir = process.cwd(),
-    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 = [entryText(entry), ...entry.affected_areas, ...(entry.scope ?? [])].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,
-      }),
-
-    ask: async (question: string) => {
-      const evidence = await oracle.query(question)
-      return advisorAsk({ question, evidence }, { llm })
-    },
-
-    compass: createCompass({
-      oracle,
-      llm,
-      rootDir,
-      chronicleDir,
-      sources: defaultSources(),
-      models: models.compass,
-    }),
-  }
-}

package/modules/shared/types.ts

@@ -1,193 +0,0 @@
-/**
- * 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.
- *
- * 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
-
-  // ── v1 fields (required — always present) ───────────────────────────────
-  /** The core finding or decision, in one clear sentence. v2: copy of decision. */
-  key_insight: string
-  /** 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. */
-  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
-
-  // ── outcome tracking fields (optional — filled in post-execution) ────────────
-  /** Steps that must pass to confirm this decision was correct. */
-  validation_plan?: string[]
-  /** ISO date after which this entry should be re-evaluated for drift. */
-  review_after?: string
-  /** What actually happened after the decision was acted on in production. */
-  post_merge_result?: "successful" | "bug" | "partial" | "rolled-back"
-
-  // ── 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
-}
-
-/**
- * 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>
-}