@balpal4495/quorum 0.1.10 → 0.3.0

package/modules/council/deliberate.ts

@@ -4,9 +4,14 @@ import { frameQuestion } from "./frame"
 import { fanOutAdvisors } from "./advisors"
 import { fanOutReviewers } from "./reviewers"
 import { chairman } from "./chairman"
+import { classifyRisk } from "./risk"
 
 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.
@@ -34,11 +39,23 @@ export async function deliberate(
   const {
     llm,
     oracle,
-    advisorCount = DEFAULT_ADVISOR_COUNT,
-    reviewerCount = DEFAULT_REVIEWER_COUNT,
     models = {},
   } = deps
 
+  // Classify risk to determine Council mode and advisor/reviewer counts
+  const risk = classifyRisk(input.outcome, input.design, input.evidence)
+  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
+
   // Select personas — cycle DEFAULT_PERSONAS if advisorCount > 5
   const personas = Array.from(
     { length: advisorCount },
@@ -82,12 +99,20 @@ 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.blockers.map(b => b.issue).slice(0, 3),
     status: "open",
     confidence: input.jury_output.confidence,
     source_module: "council",
-    evidence_cited: verdict.evidence_cited,
+    evidence_cited: verdict.citation_validation.valid_ids,
+    scope: risk.reasons.slice(0, 3),
   })
 
   return verdict

package/modules/council/index.ts

@@ -1,4 +1,9 @@
 export { deliberate } from "./deliberate"
-export type { CouncilInput, CouncilOutput, CouncilDeps, CouncilModels } from "./types"
+export type {
+  CouncilInput, CouncilOutput, CouncilDeps, CouncilModels,
+  BlockerItem, WarningItem, CitationValidation, AdvisorSplit,
+  RiskLevel, CouncilMode, RiskAssessment,
+} from "./types"
 export { DEFAULT_PERSONAS } from "./personas"
 export type { AdvisorPersona } from "./personas"
+export { classifyRisk } from "./risk"

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/council/risk.ts

@@ -0,0 +1,89 @@
+import type { OracleResult } from "../shared/types"
+import type { RiskLevel, CouncilMode, RiskAssessment } from "./types"
+
+/**
+ * Patterns that trigger risk escalation.
+ * Each entry has a level (the minimum risk level it triggers) and a reason label.
+ */
+const RISK_RULES: Array<{ pattern: RegExp; level: RiskLevel; reason: string }> = [
+  // Critical — always run full Council + flag for human architecture review
+  { pattern: /\b(auth(?:entication|orization)?|jwt|token|session|password|oauth|credential|bearer)\b/i, level: "critical", reason: "authentication or authorisation logic" },
+  { pattern: /\b(payment|stripe|charge|billing|checkout|refund|subscription)\b/i, level: "critical", reason: "payment or billing logic" },
+  { pattern: /\b(encrypt|decrypt|private\s+key|certificate|tls|ssl|hmac|cipher)\b/i, level: "critical", reason: "cryptography or key management" },
+  { pattern: /\b(delete\s+all|drop\s+table|truncate|wipe|destroy.*data|hard\s+delete)\b/i, level: "critical", reason: "irreversible data deletion" },
+
+  // High — full Council
+  { pattern: /\b(migrat(?:ion|e)|alter\s+table|schema\s+change|not\s+null|backfill|pg_repack|shadow\s+column)\b/i, level: "high", reason: "database schema migration" },
+  { pattern: /\b(permission|role(?:s)?|acl|rbac|access\s+control|entitlement)\b/i, level: "high", reason: "permissions or access control" },
+  { pattern: /\b(pii|personal\s+data|gdpr|ccpa|email(?:\s+address)?|phone(?:\s+number)?|ssn|passport)\b/i, level: "high", reason: "PII or compliance-regulated data" },
+  { pattern: /\b(api\s+key|secret(?:s)?|private\s+key|credentials?)\b/i, level: "high", reason: "secrets or credentials handling" },
+
+  // Medium — Jury + lite Council
+  { pattern: /\b(cache|redis|memcached|invalidat(?:e|ion))\b/i, level: "medium", reason: "cache strategy" },
+  { pattern: /\b(rate\s*limit|throttl(?:e|ing)|quota)\b/i, level: "medium", reason: "rate limiting or throttling" },
+  { pattern: /\b(webhook|event|queue|pubsub|kafka|rabbitmq|sns|sqs)\b/i, level: "medium", reason: "async event or messaging" },
+  { pattern: /\b(deploy(?:ment)?|ci(?:\/cd)?|docker|kubernetes|infra(?:structure)?)\b/i, level: "medium", reason: "deployment or infrastructure" },
+]
+
+const RISK_ORDER: RiskLevel[] = ["low", "medium", "high", "critical"]
+
+function maxLevel(a: RiskLevel, b: RiskLevel): RiskLevel {
+  return RISK_ORDER.indexOf(a) >= RISK_ORDER.indexOf(b) ? a : b
+}
+
+function councilModeForLevel(level: RiskLevel): CouncilMode {
+  switch (level) {
+    case "low":      return "jury-only"
+    case "medium":   return "lite"
+    case "high":     return "full"
+    case "critical": return "full"
+  }
+}
+
+/**
+ * Classify the risk level of a proposed change from its text and evidence.
+ *
+ * Risk determines Council mode — avoid running full fan-out on low-risk changes:
+ *   low      → jury-only  (no advisor/reviewer fan-out)
+ *   medium   → lite       (Jury + 2 reviewers)
+ *   high     → full       (standard 5 advisors + 5 reviewers)
+ *   critical → full       (same as high, but Chronicle entry flags for human architecture review)
+ *
+ * Refuted Oracle entries also elevate risk — a known failure mode in the evidence pack
+ * means the design is repeating something that already went wrong.
+ */
+export function classifyRisk(
+  outcome: string,
+  design: string,
+  evidence: OracleResult[],
+): RiskAssessment {
+  const text = `${outcome} ${design}`
+  let level: RiskLevel = "low"
+  const reasons: string[] = []
+
+  for (const rule of RISK_RULES) {
+    if (rule.pattern.test(text)) {
+      const matched = maxLevel(level, rule.level)
+      if (matched !== level || !reasons.includes(rule.reason)) {
+        level = matched
+        reasons.push(rule.reason)
+      }
+    }
+  }
+
+  // Refuted entries in the evidence pack are a direct risk signal
+  const refutedCount = evidence.filter(e => e.status === "refuted").length
+  if (refutedCount > 0) {
+    const refutedRisk: RiskLevel = refutedCount >= 2 ? "high" : "medium"
+    if (RISK_ORDER.indexOf(refutedRisk) > RISK_ORDER.indexOf(level)) {
+      level = maxLevel(level, refutedRisk)
+    }
+    reasons.push(`${refutedCount} refuted Chronicle ${refutedCount === 1 ? "entry" : "entries"} in evidence pack`)
+  }
+
+  return {
+    level,
+    reasons: reasons.length > 0 ? reasons : ["no sensitive patterns detected"],
+    council_mode: councilModeForLevel(level),
+  }
+}

package/modules/council/types.ts

@@ -12,14 +12,57 @@ export interface CouncilInput {
   jury_output: JuryOutput
 }
 
+/** A finding that must be resolved before the design can proceed. */
+export interface BlockerItem {
+  issue: string
+  /** Oracle entry IDs that evidence this blocker. */
+  evidence: string[]
+  /** What must change in the design to resolve this. */
+  required_fix: string
+}
+
+/** A finding that should be addressed but does not block proceeding. */
+export interface WarningItem {
+  issue: string
+  suggested_fix?: string
+}
+
+/** Validates that cited Oracle IDs actually appeared in the evidence pack. */
+export interface CitationValidation {
+  /** IDs that were cited and exist in the evidence pack. */
+  valid_ids: string[]
+  /** IDs that were cited but were NOT in the evidence pack — likely hallucinated. */
+  hallucinated_ids: string[]
+}
+
+/** How advisors split on their recommendation. Signals disagreement level. */
+export interface AdvisorSplit {
+  proceed: number
+  redesign: number
+  "investigate-more": number
+}
+
 export interface CouncilOutput {
   satisfied: boolean
   /** Chairman synthesis — every material conclusion cites Oracle entry IDs. */
   verdict: string
-  /** What was challenged or could not be validated. */
+  /**
+   * Findings that MUST be resolved before the design proceeds.
+   * Each blocker names the issue, the Oracle evidence behind it, and the required fix.
+   */
+  blockers: BlockerItem[]
+  /**
+   * Findings that SHOULD be addressed but don't block execution.
+   */
+  warnings: WarningItem[]
+  /** Flat list of all issues raised — backwards compatible with existing consumers. */
   challenges: string[]
   /** Oracle entry IDs referenced in the verdict. */
   evidence_cited: string[]
+  /** Validation of whether cited IDs exist in the evidence pack. */
+  citation_validation: CitationValidation
+  /** How advisors split on recommendation — high disagreement = escalate. */
+  advisor_split: AdvisorSplit
   recommendation: "proceed" | "redesign" | "investigate-more"
 }
 
@@ -43,3 +86,22 @@ export interface CouncilDeps {
   reviewerCount?: number
   models?: CouncilModels
 }
+
+// ── Risk classifier types ─────────────────────────────────────────────────────
+
+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
+ *   lite        → Jury + 1–2 reviewers (no full advisor fan-out)
+ *   full        → Full Council (default 5 advisors + 5 reviewers + Chairman)
+ */
+export type CouncilMode = "skip" | "jury-only" | "lite" | "full"
+
+export interface RiskAssessment {
+  level: RiskLevel
+  reasons: string[]
+  council_mode: CouncilMode
+}

package/modules/jury/evaluate.ts

@@ -1,6 +1,8 @@
 import type { JuryInput, JuryOutput, JuryDeps } from "./types"
 import type { OracleResult } from "../shared/types"
+import { entryText } from "../shared/types"
 import { JuryOutputSchema } from "./schema"
+import { runPreflight, formatPreflight } from "./preflight"
 
 const CONFIDENCE_THRESHOLD = 0.6
 
@@ -12,8 +14,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)
@@ -24,14 +26,21 @@ function formatEvidence(evidence: OracleResult[]): string {
 
 const SYSTEM_PROMPT = `You are the Jury — an evidence-based evaluator for agentic development workflows.
 
-Your job is to evaluate a proposed design against Oracle evidence and produce a structured confidence score.
+Your job is to evaluate a proposed design against Oracle evidence and produce a calibrated confidence score.
 You do NOT make decisions. You assess and score. Your output determines the Council's brief.
 
-Score the design across these four dimensions (equally weighted to produce a final confidence in [0, 1]):
-1. Evidence support   — do validated Oracle entries confirm this approach works in this codebase?
-2. Feasibility        — do Oracle entries (or their absence) suggest this is achievable?
-3. Risk               — what do refuted entries reveal about failure modes? Has this been tried and failed?
-4. Completeness       — does the design address the full outcome, or only part of it?
+Score the design across four dimensions, each 0–1:
+1. evidence_support  — do validated Oracle entries confirm this approach works in this codebase?
+2. feasibility       — do Oracle entries (or their absence) suggest this is achievable?
+3. risk              — how well does the design address known failure modes? (1 = fully addressed, 0 = ignored)
+4. completeness      — does the design cover the full outcome, or only part of it?
+
+confidence = average of the four scores (you must compute this yourself — do not round or adjust it).
+
+Gaps fall into two categories:
+- gaps: any missing evidence that would improve confidence
+- blocking_gaps: a SUBSET of gaps that are hard blockers — must be resolved before proceeding
+  (examples: no rollback plan for a destructive change, no auth strategy for a security-sensitive feature)
 
 council_brief is determined by confidence only (do not invent a value):
   confidence < 0.6  → council_brief = "challenge"
@@ -40,8 +49,15 @@ council_brief is determined by confidence only (do not invent a value):
 Return ONLY valid JSON that matches this schema exactly — no markdown fences, no explanation:
 {
   "confidence": <number 0–1>,
+  "confidence_breakdown": {
+    "evidence_support": <number 0–1>,
+    "feasibility": <number 0–1>,
+    "risk": <number 0–1>,
+    "completeness": <number 0–1>
+  },
   "assessment": <string — what the evidence supports or contradicts>,
-  "gaps": [<string — each missing piece of evidence from Oracle>],
+  "gaps": [<string — each missing piece of evidence>],
+  "blocking_gaps": [<string — gaps that are hard blockers only>],
   "council_brief": "challenge" | "pressure-test",
   "recommendation": "proceed" | "investigate-more" | "redesign"
 }`
@@ -62,6 +78,8 @@ export async function evaluate(
 ): Promise<JuryOutput> {
   const { llm, model } = deps
   const evidenceText = formatEvidence(input.evidence)
+  const preflight = runPreflight(input.outcome, input.design, input.evidence)
+  const preflightText = formatPreflight(preflight)
 
   const userPrompt = [
     "## Outcome",
@@ -70,6 +88,8 @@ export async function evaluate(
     "## Proposed Design",
     input.design,
     "",
+    preflightText,
+    "",
     "## Oracle Evidence",
     evidenceText,
   ].join("\n")
@@ -104,7 +124,12 @@ export async function evaluate(
 
   const output = result.data
 
-  // Enforce council_brief from confidence — do not trust the LLM to compute this correctly
+  // Recompute confidence as the exact average of breakdown dimensions
+  // This makes confidence deterministic and calibrated regardless of what the LLM returned
+  const { evidence_support, feasibility, risk, completeness } = output.confidence_breakdown
+  output.confidence = Math.round(((evidence_support + feasibility + risk + completeness) / 4) * 100) / 100
+
+  // Enforce council_brief from recomputed confidence — do not trust the LLM to compute this correctly
   output.council_brief =
     output.confidence < CONFIDENCE_THRESHOLD ? "challenge" : "pressure-test"
 

package/modules/jury/index.ts

@@ -1,3 +1,5 @@
 export { evaluate } from "./evaluate"
-export type { JuryInput, JuryOutput, JuryDeps } from "./types"
+export type { JuryInput, JuryOutput, JuryDeps, ConfidenceBreakdown } from "./types"
 export { JuryOutputSchema } from "./schema"
+export { runPreflight, formatPreflight } from "./preflight"
+export type { PreflightResult } from "./preflight"

package/modules/jury/preflight.ts

@@ -0,0 +1,101 @@
+import type { OracleResult } from "../shared/types"
+import { entryText } from "../shared/types"
+
+/** Areas that warrant elevated scrutiny. */
+const SENSITIVE_PATTERNS: Record<string, RegExp> = {
+  auth:          /\b(auth(?:entication|orization)?|jwt|token|session|password|oauth|login|logout|credential|bearer)\b/i,
+  database:      /\b(migrat(?:ion|e)|alter\s+table|schema\s+change|postgres|mysql|sqlite|prisma|drizzle|knex|sequelize)\b/i,
+  crypto:        /\b(encrypt|decrypt|cipher|hash(?:ing)?|hmac|sign(?:ing)?|verify|private\s+key|certificate|tls|ssl)\b/i,
+  payments:      /\b(payment|stripe|charge|billing|invoice|subscription|price|checkout|refund)\b/i,
+  permissions:   /\b(permission|role(?:s)?|acl|access\s+control|rbac|authorization|entitlement)\b/i,
+  pii:           /\b(pii|personal\s+data|gdpr|ccpa|email(?:\s+address)?|phone(?:\s+number)?|postal\s+address|ssn|passport)\b/i,
+  data_deletion: /\b(delete(?:\s+all)?|drop\s+table|truncate|purge|wipe|destroy.*data|hard\s+delete)\b/i,
+  secrets:       /\b(api\s+key|secret(?:s)?|env(?:ironment)?\s+var(?:iable)?|\.env|private\s+key|credentials?)\b/i,
+}
+
+const ROLLBACK_PATTERNS = /\b(rollback|roll\s+back|revert|undo|restore|recovery|fallback|backward[- ]compat)\b/i
+const TEST_PATTERNS     = /\b(test(?:ing|s)?|spec(?:ification)?|unit\s+test|integration\s+test|coverage|vitest|jest|mocha)\b/i
+
+export interface PreflightResult {
+  touches_sensitive_area: boolean
+  /** Which sensitive area categories were detected. */
+  sensitive_areas: string[]
+  /** Whether the design mentions a rollback or recovery strategy. */
+  rollback_mentioned: boolean
+  /** Whether the design mentions testing. */
+  test_strategy_mentioned: boolean
+  /**
+   * IDs of refuted Chronicle entries that semantically overlap with the design text.
+   * These are potential conflicts — Jury should surface them.
+   */
+  chronicle_conflicts: string[]
+}
+
+/**
+ * Static preflight analysis — no LLM required.
+ *
+ * Runs deterministic checks on the outcome + design text and the evidence pack
+ * before any LLM call. Results are injected into the Jury prompt so the LLM
+ * reasons over concrete signals rather than discovering them itself.
+ */
+export function runPreflight(
+  outcome: string,
+  design: string,
+  evidence: OracleResult[],
+): PreflightResult {
+  const text = `${outcome} ${design}`
+
+  const sensitive_areas = Object.entries(SENSITIVE_PATTERNS)
+    .filter(([, pattern]) => pattern.test(text))
+    .map(([area]) => area)
+
+  // Refuted entries whose primary text shares at least one significant word with the design
+  const designWords = new Set(
+    text
+      .toLowerCase()
+      .split(/\W+/)
+      .filter(w => w.length > 4),
+  )
+
+  const chronicle_conflicts = evidence
+    .filter(e => {
+      if (e.status !== "refuted") return false
+      const entryWords = entryText(e)
+        .toLowerCase()
+        .split(/\W+/)
+        .filter(w => w.length > 4)
+      return entryWords.some(w => designWords.has(w))
+    })
+    .map(e => e.id)
+
+  return {
+    touches_sensitive_area: sensitive_areas.length > 0,
+    sensitive_areas,
+    rollback_mentioned: ROLLBACK_PATTERNS.test(text),
+    test_strategy_mentioned: TEST_PATTERNS.test(text),
+    chronicle_conflicts,
+  }
+}
+
+/** Format preflight result for injection into the Jury prompt. */
+export function formatPreflight(preflight: PreflightResult): string {
+  const lines: string[] = ["## Deterministic Preflight (machine-checked, not LLM-inferred)"]
+
+  if (preflight.touches_sensitive_area) {
+    lines.push(`⚠ Sensitive areas detected: ${preflight.sensitive_areas.join(", ")}`)
+  } else {
+    lines.push("✓ No sensitive areas detected")
+  }
+
+  lines.push(preflight.rollback_mentioned ? "✓ Rollback strategy mentioned" : "✗ No rollback strategy mentioned")
+  lines.push(preflight.test_strategy_mentioned ? "✓ Test strategy mentioned" : "✗ No test strategy mentioned")
+
+  if (preflight.chronicle_conflicts.length > 0) {
+    lines.push(`⚠ Refuted Chronicle entries potentially conflicting: ${preflight.chronicle_conflicts.join(", ")}`)
+    lines.push("  These entries were previously tried and failed — verify the design addresses the documented failure reason.")
+  } else {
+    lines.push("✓ No conflicting refuted Chronicle entries")
+  }
+
+  return lines.join("\n")
+}

package/modules/jury/schema.ts

@@ -1,13 +1,22 @@
 import { z } from "zod"
 
+const ConfidenceBreakdownSchema = z.object({
+  evidence_support: z.number().min(0).max(1),
+  feasibility: z.number().min(0).max(1),
+  risk: z.number().min(0).max(1),
+  completeness: z.number().min(0).max(1),
+})
+
 /**
  * Zod schema for the Jury's structured LLM output.
  * evaluate() validates all LLM responses against this before returning.
  */
 export const JuryOutputSchema = z.object({
   confidence: z.number().min(0).max(1),
+  confidence_breakdown: ConfidenceBreakdownSchema,
   assessment: z.string().min(1),
   gaps: z.array(z.string()),
+  blocking_gaps: z.array(z.string()),
   council_brief: z.enum(["challenge", "pressure-test"]),
   recommendation: z.enum(["proceed", "investigate-more", "redesign"]),
 })

package/modules/jury/types.ts

@@ -9,13 +9,32 @@ export interface JuryInput {
   evidence: OracleResult[]
 }
 
+/** Per-dimension breakdown of the 0–1 confidence score. */
+export interface ConfidenceBreakdown {
+  /** Do validated Oracle entries confirm this approach works here? */
+  evidence_support: number
+  /** Do Oracle entries suggest this is achievable in this codebase? */
+  feasibility: number
+  /** How well does the design address known failure modes? (1 = fully addressed) */
+  risk: number
+  /** Does the design cover the full outcome, or only part of it? */
+  completeness: number
+}
+
 export interface JuryOutput {
-  /** 0–1 confidence score. Drives the Council brief. */
+  /** 0–1 confidence score. Average of the four breakdown dimensions. */
   confidence: number
+  /** Per-dimension breakdown of the confidence score. */
+  confidence_breakdown: ConfidenceBreakdown
   /** What the evidence supports or contradicts. */
   assessment: string
   /** Evidence missing from Oracle that would improve confidence. */
   gaps: string[]
+  /**
+   * Gaps that are hard blockers — must be resolved before Council should proceed.
+   * Subset of gaps where the missing information is critical (auth, rollback, data safety).
+   */
+  blocking_gaps: string[]
   /**
    * Council brief derived from confidence:
    *   < 0.6  → "challenge"      (find what is wrong — broader scope)

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,