@balpal4495/quorum 0.4.0 → 1.0.0

package/bin/commands/evolve.js

@@ -0,0 +1,285 @@
+import { promises as fs } from "fs"
+import path from "path"
+import { randomUUID } from "crypto"
+import { c } from "../shared/colors.js"
+import { findChronicleDir, readCommitted, entryText } from "../shared/chronicle.js"
+import { detectProvider } from "../shared/llm.js"
+
+function parseArgs(argv) {
+  const args = { dryRun: false, json: false }
+  for (const arg of argv) {
+    if (arg === "--dry-run") args.dryRun = true
+    if (arg === "--json")    args.json   = true
+  }
+  return args
+}
+
+const SYSTEM_PROMPT = `You are a Chronicle Analyst for Quorum — a persistent knowledge store that gives AI coding assistants long-term memory across sessions.
+
+You will receive a list of committed Chronicle entries. Your task is to find quality improvements. Be conservative — it is correct to propose nothing when entries are all distinct and healthy. Never consolidate entries that are merely related; only merge when they are genuinely saying the same thing.
+
+Three types of improvement:
+
+CONSOLIDATE — two or more entries that cover the same ground, expressed redundantly or overlapping in scope. Propose merging into one sharper entry that supersedes them.
+
+RESOLVE_CONTRADICTION — a validated entry that a newer entry implicitly supersedes or contradicts. Propose marking the older entry as refuted.
+
+PROMOTE_OPEN — an entry with status "open" that other entries have since confirmed or validated. Propose elevating to "validated" with a justified confidence score.
+
+Return ONLY valid JSON — no prose, no markdown fences — with this exact shape:
+{
+  "actions": [
+    {
+      "type": "consolidate",
+      "entry_ids": ["full-uuid-1", "full-uuid-2"],
+      "synthesised": {
+        "topic": "short label",
+        "decision": "One precise sentence: what was decided and why.",
+        "key_insight": "same as decision",
+        "affected_areas": ["path/to/file.ts"],
+        "scope": ["tag1", "tag2"],
+        "alternatives_considered": [],
+        "rejected_reason": [],
+        "status": "validated",
+        "confidence": 0.9
+      },
+      "reason": "why these entries should be merged"
+    },
+    {
+      "type": "resolve_contradiction",
+      "stale_entry_id": "full-uuid",
+      "superseding_entry_id": "full-uuid",
+      "reason": "why the older entry is now superseded"
+    },
+    {
+      "type": "promote_open",
+      "entry_id": "full-uuid",
+      "new_confidence": 0.85,
+      "reason": "which other entries confirm this"
+    }
+  ],
+  "no_action_reason": "brief note on why the rest need no change, or empty string"
+}`
+
+function formatEntries(entries) {
+  return entries.map(e => {
+    const lines = [
+      `ID: ${e.id}`,
+      `Topic: ${e.topic ?? "(none)"}`,
+      `Status: ${e.status}`,
+      `Confidence: ${e.confidence}`,
+      `Decision: ${e.decision ?? e.key_insight}`,
+      `Affected areas: ${(e.affected_areas ?? []).join(", ")}`,
+      `Scope: ${(e.scope ?? []).join(", ")}`,
+    ]
+    if (e.alternatives_considered?.length) lines.push(`Alternatives considered: ${e.alternatives_considered.join("; ")}`)
+    if (e.rejected_reason?.length)         lines.push(`Rejected reason: ${e.rejected_reason.join("; ")}`)
+    if (e.supersedes)                       lines.push(`Supersedes: ${e.supersedes}`)
+    if (e.superseded_by)                    lines.push(`Superseded by: ${e.superseded_by}`)
+    return lines.join("\n")
+  }).join("\n\n---\n\n")
+}
+
+function validateAction(action) {
+  if (!action || typeof action.type !== "string") return false
+  if (action.type === "consolidate")
+    return Array.isArray(action.entry_ids) && action.entry_ids.length >= 2 && action.synthesised
+  if (action.type === "resolve_contradiction")
+    return typeof action.stale_entry_id === "string" && typeof action.superseding_entry_id === "string"
+  if (action.type === "promote_open")
+    return typeof action.entry_id === "string" && typeof action.new_confidence === "number"
+  return false
+}
+
+function spinner(msg) {
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+  let i = 0
+  const interval = setInterval(() => {
+    process.stdout.write(`\r  ${c.cyan(frames[i++ % frames.length])}  ${msg}`)
+  }, 80)
+  return { stop: (final) => { clearInterval(interval); process.stdout.write(`\r  ${final}\n`) } }
+}
+
+function renderEvolvePassthrough(entries) {
+  console.log(`\n${c.bold("Chronicle evolution analysis")}  ${c.dim(`${entries.length} entries`)}\n`)
+  console.log(c.dim("  No LLM configured — outputting Chronicle for agent analysis.\n"))
+  console.log(formatEntries(entries))
+  console.log(c.dim("─".repeat(60)))
+  console.log(`\n${c.bold("Analysis request")}\n`)
+  console.log("  Review the Chronicle entries above and identify quality improvements:")
+  console.log("  · consolidate — entries covering the same ground (merge into one stronger entry)")
+  console.log("  · resolve — a validated entry superseded or contradicted by a newer one")
+  console.log("  · promote — an 'open' entry confirmed by other entries (elevate to validated)")
+  console.log("")
+  console.log("  For each improvement, create a proposal using the template in CLAUDE.md:")
+  console.log(c.dim("  node -e \"const { randomUUID } = require('crypto'); ...\" (see CLAUDE.md)"))
+  console.log(c.dim("  Then run: quorum commit --list\n"))
+}
+
+export async function run(argv) {
+  const args = parseArgs(argv)
+
+  const chronicleDir = await findChronicleDir(process.cwd())
+  if (!chronicleDir) {
+    console.error(`\n${c.red("No .chronicle/ directory found.")} Run ${c.bold("quorum init")} first.\n`)
+    process.exit(1)
+  }
+
+  const entries = await readCommitted(chronicleDir)
+  if (entries.length === 0) {
+    console.log(`\n${c.dim("No committed entries — nothing to evolve.")}\n`)
+    return
+  }
+
+  const provider = await detectProvider()
+  if (!provider) {
+    renderEvolvePassthrough(entries)
+    return
+  }
+  const { llm, name: llmName } = provider
+
+  console.log(`\n${c.bold("Quorum evolve")}  ${c.dim(`${entries.length} entries · via ${llmName}`)}\n`)
+
+  const spin = spinner(`Analysing ${entries.length} Chronicle entries…`)
+
+  let raw
+  try {
+    raw = await llm([
+      { role: "system", content: SYSTEM_PROMPT },
+      {
+        role: "user",
+        content: `Here are the ${entries.length} committed Chronicle entries:\n\n${formatEntries(entries)}\n\nAnalyse and return your proposed improvements as JSON.`,
+      },
+    ])
+    spin.stop(`${c.green("✓")}  Analysis complete`)
+  } catch (err) {
+    spin.stop(`${c.red("✗")}  LLM call failed`)
+    console.error(c.dim(`     ${err.message}\n`))
+    process.exit(1)
+  }
+
+  let parsed
+  try {
+    const cleaned = raw.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "").trim()
+    parsed = JSON.parse(cleaned)
+  } catch {
+    console.error(`\n${c.red("Could not parse LLM response as JSON.")}\n`)
+    console.error(c.dim(raw.slice(0, 500)))
+    process.exit(1)
+  }
+
+  const actions = (parsed.actions ?? []).filter(validateAction)
+
+  if (args.json) {
+    console.log(JSON.stringify({ actions, no_action_reason: parsed.no_action_reason ?? "" }, null, 2))
+    return
+  }
+
+  if (actions.length === 0) {
+    console.log(`\n  ${c.green("✓")}  Chronicle is clean — no improvements identified.`)
+    if (parsed.no_action_reason) console.log(`\n  ${c.dim(parsed.no_action_reason)}`)
+    console.log("")
+    return
+  }
+
+  console.log(`\n  ${c.bold(String(actions.length))} improvement${actions.length === 1 ? "" : "s"} found\n`)
+
+  if (args.dryRun) {
+    for (const action of actions) {
+      if (action.type === "consolidate") {
+        console.log(`  ${c.cyan("consolidate")}  ${action.entry_ids.map(id => id.slice(0, 8)).join(" + ")}`)
+        console.log(`    ${c.dim(action.reason)}`)
+        console.log(`    ${c.dim("→")} ${action.synthesised.decision ?? action.synthesised.key_insight}`)
+      } else if (action.type === "resolve_contradiction") {
+        console.log(`  ${c.yellow("resolve")}      ${action.stale_entry_id.slice(0, 8)} → refuted  (superseded by ${action.superseding_entry_id.slice(0, 8)})`)
+        console.log(`    ${c.dim(action.reason)}`)
+      } else if (action.type === "promote_open") {
+        console.log(`  ${c.green("promote")}      ${action.entry_id.slice(0, 8)} → validated  (confidence ${action.new_confidence})`)
+        console.log(`    ${c.dim(action.reason)}`)
+      }
+      console.log("")
+    }
+    console.log(c.dim("  (Dry run — no proposals written.)\n"))
+    return
+  }
+
+  // Write proposals
+  const proposalsDir = path.join(chronicleDir, "proposals")
+  await fs.mkdir(proposalsDir, { recursive: true })
+
+  const entryMap = new Map(entries.map(e => [e.id, e]))
+  let stagedCount = 0
+
+  for (const action of actions) {
+    const proposalId = randomUUID()
+    let proposal
+
+    if (action.type === "consolidate") {
+      const sources = action.entry_ids.map(eid => entryMap.get(eid)).filter(Boolean)
+      const mergedAreas = [...new Set(sources.flatMap(e => e.affected_areas ?? []))]
+      const mergedScope = [...new Set(sources.flatMap(e => e.scope ?? []))]
+      proposal = {
+        schema_version: 2,
+        ...action.synthesised,
+        affected_areas: action.synthesised.affected_areas?.length ? action.synthesised.affected_areas : mergedAreas,
+        scope:          action.synthesised.scope?.length          ? action.synthesised.scope          : mergedScope,
+        key_insight:    action.synthesised.decision ?? action.synthesised.key_insight,
+        decision:       action.synthesised.decision ?? action.synthesised.key_insight,
+        supersedes:     action.entry_ids,
+        source_module:  "evolve",
+        evidence_cited: action.entry_ids,
+        _evolve_action: "consolidate",
+        _evolve_reason: action.reason,
+      }
+    } else if (action.type === "resolve_contradiction") {
+      const stale = entryMap.get(action.stale_entry_id)
+      proposal = {
+        schema_version: 2,
+        key_insight:    stale ? entryText(stale) : action.stale_entry_id,
+        decision:       stale ? entryText(stale) : action.stale_entry_id,
+        topic:          stale?.topic ?? "contradiction-resolution",
+        affected_areas: stale?.affected_areas ?? [],
+        scope:          [...(stale?.scope ?? []), "evolution"],
+        status:         "refuted",
+        confidence:     stale?.confidence ?? 0.5,
+        source_module:  "evolve",
+        evidence_cited: [action.superseding_entry_id],
+        supersedes:     action.stale_entry_id,
+        _evolve_action: "resolve_contradiction",
+        _evolve_reason: action.reason,
+      }
+    } else if (action.type === "promote_open") {
+      const original = entryMap.get(action.entry_id)
+      if (!original) continue
+      const { id: _id, timestamp: _ts, ...rest } = original
+      proposal = {
+        ...rest,
+        schema_version: 2,
+        status:         "validated",
+        confidence:     action.new_confidence,
+        supersedes:     action.entry_id,
+        source_module:  "evolve",
+        _evolve_action: "promote_open",
+        _evolve_reason: action.reason,
+      }
+    }
+
+    if (!proposal) continue
+    await fs.writeFile(path.join(proposalsDir, `${proposalId}.json`), JSON.stringify(proposal, null, 2))
+    stagedCount++
+
+    if (action.type === "consolidate") {
+      console.log(`  ${c.green("✓")}  ${c.cyan("consolidate")}  ${action.entry_ids.map(id => id.slice(0, 8)).join(" + ")}`)
+      console.log(`     ${c.dim(action.reason)}`)
+    } else if (action.type === "resolve_contradiction") {
+      console.log(`  ${c.green("✓")}  ${c.yellow("resolve")}      ${action.stale_entry_id.slice(0, 8)} → refuted`)
+      console.log(`     ${c.dim(action.reason)}`)
+    } else if (action.type === "promote_open") {
+      console.log(`  ${c.green("✓")}  ${c.green("promote")}      ${action.entry_id.slice(0, 8)} → validated (${action.new_confidence})`)
+      console.log(`     ${c.dim(action.reason)}`)
+    }
+    console.log("")
+  }
+
+  console.log(`  ${c.green(String(stagedCount))} proposal${stagedCount === 1 ? "" : "s"} staged — run ${c.bold("quorum commit --list")} to review\n`)
+}

package/bin/commands/growth.js

@@ -0,0 +1,139 @@
+import { c } from "../shared/colors.js"
+import { findChronicleDir, readCommitted, readProposals, entryText } from "../shared/chronicle.js"
+
+const STALLED_DAYS = 14
+const SLOW_DAYS    = 7
+
+function parseArgs(argv) {
+  const args = { json: false }
+  for (const arg of argv) {
+    if (arg === "--json") args.json = true
+  }
+  return args
+}
+
+function weekKey(timestamp) {
+  const d = new Date(timestamp)
+  const day = d.getUTCDay() || 7
+  const mon = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() - day + 1))
+  return mon.toISOString().slice(0, 10)
+}
+
+export async function run(argv) {
+  const args = parseArgs(argv)
+
+  const chronicleDir = await findChronicleDir(process.cwd())
+  if (!chronicleDir) {
+    console.error(`\n${c.red("No .chronicle/ directory found.")} Run ${c.bold("quorum init")} first.\n`)
+    process.exit(1)
+  }
+
+  const [entries, proposals] = await Promise.all([
+    readCommitted(chronicleDir),
+    readProposals(chronicleDir),
+  ])
+
+  const now      = Date.now()
+  const msPerDay = 86_400_000
+  const sorted   = [...entries].sort((a, b) => (a.timestamp ?? "").localeCompare(b.timestamp ?? ""))
+
+  const in7Days  = entries.filter(e => e.timestamp && (now - new Date(e.timestamp).getTime()) < 7  * msPerDay).length
+  const in30Days = entries.filter(e => e.timestamp && (now - new Date(e.timestamp).getTime()) < 30 * msPerDay).length
+
+  const newest    = sorted[sorted.length - 1]
+  const daysSince = newest?.timestamp
+    ? Math.floor((now - new Date(newest.timestamp).getTime()) / msPerDay)
+    : null
+
+  let status
+  if (entries.length === 0)                                   status = "empty"
+  else if (daysSince !== null && daysSince >= STALLED_DAYS)  status = "stalled"
+  else if (daysSince !== null && daysSince >= SLOW_DAYS)     status = "slow"
+  else if (in7Days >= 3)                                     status = "thriving"
+  else                                                        status = "healthy"
+
+  if (args.json) {
+    console.log(JSON.stringify({
+      status,
+      totalEntries: entries.length,
+      pendingProposals: proposals.length,
+      commitsLast7Days: in7Days,
+      commitsLast30Days: in30Days,
+      daysSinceLastCommit: daysSince,
+      newestEntryTimestamp: newest?.timestamp ?? null,
+    }, null, 2))
+    return
+  }
+
+  const statusLabel = {
+    empty:    c.red("EMPTY — Chronicle has no committed entries"),
+    stalled:  c.red(`STALLED — no commits in ${daysSince} days`),
+    slow:     c.yellow(`SLOW — no commits in ${daysSince} day${daysSince === 1 ? "" : "s"}`),
+    thriving: c.green("THRIVING"),
+    healthy:  c.green("HEALTHY"),
+  }[status]
+
+  console.log(`\n${c.bold("Chronicle growth")}\n`)
+  console.log(`  Status        ${statusLabel}`)
+  console.log(`  Total entries ${c.bold(String(entries.length))}`)
+  console.log(`  Last 7 days   ${in7Days === 0 ? c.yellow("0") : c.green(String(in7Days))} commit${in7Days === 1 ? "" : "s"}`)
+  console.log(`  Last 30 days  ${in30Days} commit${in30Days === 1 ? "" : "s"}`)
+
+  if (daysSince !== null) {
+    const col = daysSince >= STALLED_DAYS ? c.red : daysSince >= SLOW_DAYS ? c.yellow : c.green
+    console.log(`  Last commit   ${col(`${daysSince} day${daysSince === 1 ? "" : "s"} ago`)}  ${c.dim(newest.timestamp.slice(0, 10))}`)
+  }
+
+  console.log(`  Pending       ${proposals.length} proposal${proposals.length === 1 ? "" : "s"} awaiting ${c.bold("quorum commit")}`)
+
+  // Weekly sparkline (last 8 weeks)
+  if (entries.length > 0) {
+    const weeks = new Map()
+    for (const e of entries) {
+      if (!e.timestamp) continue
+      const k = weekKey(e.timestamp)
+      weeks.set(k, (weeks.get(k) ?? 0) + 1)
+    }
+    const weekKeys = [...weeks.keys()].sort().reverse().slice(0, 8)
+    if (weekKeys.length > 0) {
+      console.log(`\n  ${c.bold("Weekly commits")}`)
+      for (const wk of weekKeys) {
+        const n = weeks.get(wk)
+        const bar = "▪".repeat(n)
+        const col = n >= 3 ? c.green : n >= 1 ? c.cyan : c.dim
+        console.log(`    ${c.dim("w/c")} ${wk}  ${col(bar || "—")}  ${col(String(n))}`)
+      }
+    }
+  }
+
+  // Recent learnings
+  const recent = [...entries]
+    .filter(e => e.timestamp)
+    .sort((a, b) => b.timestamp.localeCompare(a.timestamp))
+    .slice(0, 7)
+  if (recent.length > 0) {
+    console.log(`\n  ${c.bold("Recent learnings")}`)
+    for (const e of recent) {
+      const text = entryText(e).slice(0, 72)
+      const trail = entryText(e).length > 72 ? "…" : ""
+      const date  = e.timestamp.slice(0, 10)
+      const col   = e.status === "refuted" ? c.red : e.status === "open" ? c.yellow : c.dim
+      console.log(`    ${c.dim(e.id.slice(0, 8))}  ${text}${trail}  ${col(date)}`)
+    }
+  }
+
+  // Actionable advice when not healthy
+  if (status === "stalled" || status === "slow" || status === "empty") {
+    console.log(`\n  ${c.yellow("Action needed:")}`)
+    if (proposals.length > 0) {
+      console.log(`    ${proposals.length} proposal${proposals.length === 1 ? " is" : "s are"} staged and ready to commit.`)
+      console.log(`    Run ${c.bold("quorum commit --list")} to review them.`)
+    } else {
+      console.log(`    No proposals are staged.`)
+      console.log(`    At the end of every session, create proposals for significant decisions.`)
+      console.log(`    ${c.dim("See CLAUDE.md for the proposal format and session protocol.")}`)
+    }
+  }
+
+  console.log("")
+}

package/bin/commands/init.js

@@ -55,6 +55,13 @@ async function copyModules(target) {
   log.created("quorum/SETUP.md")
 }
 
+async function copyEvals(target) {
+  const src  = path.join(QUORUM_ROOT, "evals")
+  const dest = path.join(target, "quorum", "evals")
+  await fs.cp(src, dest, { recursive: true })
+  log.created("quorum/evals/")
+}
+
 async function mergeCopilotInstructions(target) {
   log.section("Merging AI instruction files")
   const src     = path.join(QUORUM_ROOT, ".github", "copilot-instructions.md")
@@ -207,6 +214,7 @@ export async function run(PKG_VERSION) {
 
   await guardAlreadyInitialized(target)
   await copyModules(target)
+  await copyEvals(target)
   await mergeCopilotInstructions(target)
   await mergeAgentsMd(target)
   await mergeClaudeMd(target)

package/bin/commands/sentinel.js

@@ -1,4 +1,4 @@
-import { promises as fs, Dirent } from "fs"
+import { promises as fs } from "fs"
 import path from "path"
 import { c } from "../shared/colors.js"
 import { findChronicleDir, readCommitted } from "../shared/chronicle.js"

package/bin/init.js

@@ -5,7 +5,7 @@
  * Drops Quorum into an existing Node.js project.
  * Run from the target project root:
  *
- *   npx github:balpal4495/Quorum init
+ *   npx @balpal4495/quorum@latest init
  *
  * Zero external dependencies — uses only Node.js built-ins.
  * Requires Node.js 18+.
@@ -104,6 +104,13 @@ async function copyModules() {
   log.created("quorum/SETUP.md")
 }
 
+async function copyEvals() {
+  const src  = path.join(QUORUM_ROOT, "evals")
+  const dest = path.join(TARGET, "quorum", "evals")
+  await fs.cp(src, dest, { recursive: true })
+  log.created("quorum/evals/")
+}
+
 async function mergeCopilotInstructions() {
   log.section("Merging AI instruction files")
 
@@ -309,6 +316,7 @@ async function main() {
 
   await guardAlreadyInitialized()
   await copyModules()
+  await copyEvals()
   await mergeCopilotInstructions()
   await mergeAgentsMd()
   await mergeClaudeMd()

package/bin/quorum.js

@@ -20,13 +20,23 @@ function help() {
 ${c.bold("quorum")} ${c.dim(`v${PKG_VERSION}`)} — portable reasoning layer for agentic codebases
 
 ${c.bold("Usage:")}
+  ${c.cyan("quorum advisor")} ${c.dim('"question"')}             Ask a plain-language question (uses LLM)
+  ${c.cyan("quorum advisor query")} ${c.dim('"topic"')}          Search Chronicle entries (no LLM)
+  ${c.cyan("quorum advisor brief")}                 High-level Chronicle summary (no LLM)
   ${c.cyan("quorum init")}                          Scaffold Quorum into a project
   ${c.cyan("quorum status")}                        Show Chronicle health and pending proposals
   ${c.cyan("quorum check")} --outcome <x> --design <y>  Preflight + risk (no LLM)
   ${c.cyan("quorum commit")} <id>                   Approve and index a Chronicle proposal
   ${c.cyan("quorum sentinel")} [coverage]           Chronicle coverage of source files
+  ${c.cyan("quorum growth")}                        Chronicle learning health and growth rate
+  ${c.cyan("quorum evolve")}                        Consolidate and improve Chronicle entries (uses LLM)
   ${c.cyan("quorum --version")}                     Print version
 
+${c.bold("quorum advisor")} subcommands:
+  ask ${c.dim('"question"')}       Ask with LLM synthesis + validation loop
+  query ${c.dim('"topic"')}        Chronicle lookup (no LLM, instant)
+  brief                Chronicle summary (no LLM, instant)
+
 ${c.bold("quorum check")} flags:
   --outcome  -o   What you want to achieve
   --design   -d   How you plan to do it
@@ -62,6 +72,12 @@ async function cli() {
 
   const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
+  if (command === "advisor") {
+    const { run } = await import(path.join(__dirname, "commands/advisor.js"))
+    await run(rest)
+    return
+  }
+
   if (command === "init") {
     const { run } = await import(path.join(__dirname, "commands/init.js"))
     await run(PKG_VERSION)
@@ -92,6 +108,18 @@ async function cli() {
     return
   }
 
+  if (command === "growth") {
+    const { run } = await import(path.join(__dirname, "commands/growth.js"))
+    await run(rest)
+    return
+  }
+
+  if (command === "evolve") {
+    const { run } = await import(path.join(__dirname, "commands/evolve.js"))
+    await run(rest)
+    return
+  }
+
   console.error(`${c.red(`Unknown command: ${command}`)}`)
   console.error(`Run ${c.bold("quorum help")} for usage.`)
   process.exit(1)