@balpal4495/quorum 0.2.0 → 0.4.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 },
@@ -88,11 +105,14 @@ export async function deliberate(
     key_insight: keyInsight,
     affected_areas: extractAffectedAreas(input.outcome, input.design),
     alternatives_considered: verdict.challenges,
-    rejected_reason: verdict.satisfied ? [] : [verdict.verdict.slice(0, 200)],
+    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/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

@@ -2,6 +2,7 @@ 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
 
@@ -25,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"
@@ -41,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"
 }`
@@ -63,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",
@@ -71,6 +88,8 @@ export async function evaluate(
     "## Proposed Design",
     input.design,
     "",
+    preflightText,
+    "",
     "## Oracle Evidence",
     evidenceText,
   ].join("\n")
@@ -105,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/shared/types.ts

@@ -56,6 +56,14 @@ export type ChronicleEntry = {
   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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@balpal4495/quorum",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Portable reasoning layer for agentic codebases — Oracle, Jury, Council, Sentinel",
   "type": "module",
   "license": "MIT",
@@ -20,11 +20,11 @@
     "llm"
   ],
   "bin": {
-    "quorum": "bin/init.js"
+    "quorum": "bin/quorum.js"
   },
   "scripts": {
     "init": "node bin/init.js",
-    "test": "vitest run modules/",
+    "test": "vitest run modules/ evals/",
     "test:watch": "vitest modules/",
     "typecheck": "tsc --noEmit"
   },