@balpal4495/quorum 2.0.0 → 3.0.0

package/bin/commands/migrate-v2.js

@@ -0,0 +1,136 @@
+import { promises as fs } from "fs"
+import path from "path"
+import { fileURLToPath } from "url"
+import { createRequire } from "module"
+import { c, log } from "../shared/colors.js"
+
+const _require = createRequire(import.meta.url)
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const QUORUM_ROOT = path.resolve(__dirname, "../..")
+
+async function exists(p) {
+  return fs.access(p).then(() => true).catch(() => false)
+}
+
+async function rmrf(p) {
+  await fs.rm(p, { recursive: true, force: true })
+}
+
+async function readJson(p) {
+  return JSON.parse(await fs.readFile(p, "utf8"))
+}
+
+async function detectV1Artifacts(target) {
+  const artifacts = []
+  const vendoredModules = path.join(target, "quorum", "modules")
+  const vendoredEvals   = path.join(target, "quorum", "evals")
+  if (await exists(vendoredModules)) artifacts.push({ path: vendoredModules, label: "quorum/modules/" })
+  if (await exists(vendoredEvals))   artifacts.push({ path: vendoredEvals,   label: "quorum/evals/" })
+  return artifacts
+}
+
+async function removeVendoredArtifacts(artifacts) {
+  for (const artifact of artifacts) {
+    await rmrf(artifact.path)
+    log.ok(`Removed ${artifact.label}`)
+  }
+}
+
+async function ensurePackageJsonDependency(target, version) {
+  const pkgPath = path.join(target, "package.json")
+  if (!await exists(pkgPath)) return
+  const pkg = await readJson(pkgPath)
+  const already = pkg.dependencies?.["@balpal4495/quorum"] || pkg.devDependencies?.["@balpal4495/quorum"]
+  if (already) {
+    log.skipped("package.json (@balpal4495/quorum already listed)")
+    return
+  }
+  pkg.devDependencies = pkg.devDependencies ?? {}
+  pkg.devDependencies["@balpal4495/quorum"] = `^${version}`
+  await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8")
+  log.appended(`package.json — added @balpal4495/quorum@^${version} to devDependencies`)
+}
+
+async function refreshHostDocs(target) {
+  // Replace quorum/CLAUDE.md with the host-facing template (not module internals)
+  const claudeSrc = path.join(QUORUM_ROOT, "bin", "templates", "CLAUDE.md")
+  const claudeDest = path.join(target, "quorum", "CLAUDE.md")
+  if (await exists(claudeSrc) && await exists(claudeDest)) {
+    const current = await fs.readFile(claudeDest, "utf8")
+    // Only replace if it looks like the old module-internal version
+    if (current.includes("Key design decisions to preserve") || current.includes("Dependency injection throughout")) {
+      await fs.copyFile(claudeSrc, claudeDest)
+      log.ok("quorum/CLAUDE.md — replaced module-internal doc with host-facing operational guide")
+    } else {
+      log.skipped("quorum/CLAUDE.md (does not look like v1 module-internal doc — leaving as-is)")
+    }
+  }
+}
+
+async function writeVersionFile(target, version) {
+  await fs.writeFile(path.join(target, ".quorum-version"), version + "\n", "utf8")
+  log.ok(`.quorum-version — written (${version})`)
+}
+
+export async function run(argv) {
+  const target = process.cwd()
+  const dryRun = argv.includes("--dry-run")
+  const pkg    = _require(path.join(QUORUM_ROOT, "package.json"))
+
+  console.log(c.bold("\nQuorum migrate-v2") + c.dim(`  v${pkg.version}`) + (dryRun ? c.yellow("  [dry-run]") : ""))
+  console.log(`Target: ${c.dim(target)}\n`)
+
+  // ── Detect v1 artifacts ──────────────────────────────────────────────────
+  log.section("Scanning for v1 artifacts")
+  const artifacts = await detectV1Artifacts(target)
+
+  if (artifacts.length === 0) {
+    console.log(c.dim("\n  No v1 vendored artifacts found (quorum/modules/, quorum/evals/)."))
+    console.log(c.dim("  This project may already be on v2, or was never on v1.\n"))
+
+    const hasVersionFile = await exists(path.join(target, ".quorum-version"))
+    if (!hasVersionFile) {
+      console.log(c.yellow("  No .quorum-version file found. Run 'quorum init' to initialize properly.\n"))
+    } else {
+      const currentVersion = (await fs.readFile(path.join(target, ".quorum-version"), "utf8")).trim()
+      console.log(c.green(`  .quorum-version: ${currentVersion}  ✓\n`))
+    }
+    return
+  }
+
+  console.log("")
+  for (const a of artifacts) {
+    console.log(`  ${c.yellow("⚠")}  Found: ${c.bold(a.label)}`)
+  }
+  console.log("")
+  console.log(c.dim("  These directories were copied by quorum init in v1 and are no longer needed."))
+  console.log(c.dim("  In v2, modules live in node_modules/@balpal4495/quorum."))
+
+  if (dryRun) {
+    console.log(c.yellow("\n  [dry-run] No changes made. Re-run without --dry-run to apply.\n"))
+    return
+  }
+
+  // ── Remove vendored artifacts ────────────────────────────────────────────
+  log.section("Removing v1 vendored artifacts")
+  await removeVendoredArtifacts(artifacts)
+
+  // ── Ensure package.json lists the dependency ─────────────────────────────
+  log.section("Updating package.json")
+  await ensurePackageJsonDependency(target, pkg.version)
+
+  // ── Refresh host-facing docs ─────────────────────────────────────────────
+  log.section("Refreshing host docs")
+  await refreshHostDocs(target)
+
+  // ── Write version marker ─────────────────────────────────────────────────
+  log.section("Version marker")
+  await writeVersionFile(target, pkg.version)
+
+  console.log(`\n${c.green("✓ Migration complete.")}\n`)
+  console.log("Next steps:")
+  console.log(c.dim("  1. npm install             — install @balpal4495/quorum as a package dep"))
+  console.log(c.dim("  2. quorum sync             — refresh instruction blocks"))
+  console.log(c.dim("  3. git rm -r quorum/modules quorum/evals 2>/dev/null  — remove from git index if tracked"))
+  console.log("")
+}

package/bin/commands/sentinel.js

@@ -141,7 +141,7 @@ export async function run(argv) {
   if (args.subcommand === "drift") {
     console.log(`\n${c.yellow("quorum sentinel drift")} requires an LLM provider and is not available as a standalone CLI command.`)
     console.log(c.dim("\nUse the sentinelAssertions() helper in your test suite instead:"))
-    console.log(c.dim("\n  import { sentinelAssertions } from \"./quorum/modules/sentinel\""))
+    console.log(c.dim("\n  import { sentinelAssertions } from \"@balpal4495/quorum\""))
     console.log(c.dim("  const assertions = sentinelAssertions({ llm: yourProvider })"))
     console.log(c.dim("  describe(\"sentinel\", () => { assertions.forEach(a => a()) })\n"))
     process.exit(0)

package/bin/commands/sync.js

@@ -0,0 +1,97 @@
+import { promises as fs } from "fs"
+import path from "path"
+import { fileURLToPath } from "url"
+import { c, log } from "../shared/colors.js"
+import { createRequire } from "module"
+
+const _require = createRequire(import.meta.url)
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const QUORUM_ROOT = path.resolve(__dirname, "../..")
+
+async function exists(p) {
+  return fs.access(p).then(() => true).catch(() => false)
+}
+
+async function syncFile(target, destRelative, freshContent) {
+  const dest = path.join(target, destRelative)
+  if (!await exists(dest)) {
+    log.skipped(`${destRelative} (not present — run quorum init first)`)
+    return false
+  }
+  const existing = await fs.readFile(dest, "utf8")
+  const startTag = "<!-- quorum:start -->"
+  const endTag   = "<!-- quorum:end -->"
+  const start = existing.indexOf(startTag)
+  const end   = existing.indexOf(endTag)
+  if (start === -1 || end === -1) {
+    log.skipped(`${destRelative} (no quorum marker block found)`)
+    return false
+  }
+  const fresh = `${startTag}\n${freshContent}\n${endTag}`
+  const updated = existing.slice(0, start) + fresh + existing.slice(end + endTag.length)
+  if (updated === existing) {
+    log.skipped(`${destRelative} (already up to date)`)
+    return false
+  }
+  await fs.writeFile(dest, updated, "utf8")
+  log.appended(`${destRelative} (marker block refreshed)`)
+  return true
+}
+
+async function syncCopilotInstructions(target) {
+  const src = path.join(QUORUM_ROOT, ".github", "copilot-instructions.md")
+  if (!await exists(src)) return
+  const content = await fs.readFile(src, "utf8")
+  await syncFile(target, ".github/copilot-instructions.md", content)
+}
+
+async function syncQuorumDocs(target) {
+  // Replace quorum/CLAUDE.md and quorum/AGENTS.md wholesale — no marker blocks
+  const claudeSrc  = path.join(QUORUM_ROOT, "bin", "templates", "CLAUDE.md")
+  const agentsSrc  = path.join(QUORUM_ROOT, "modules", "AGENTS.md")
+  const setupSrc   = path.join(QUORUM_ROOT, "SETUP.md")
+
+  for (const [src, destName] of [[claudeSrc, "quorum/CLAUDE.md"], [agentsSrc, "quorum/AGENTS.md"], [setupSrc, "quorum/SETUP.md"]]) {
+    const dest = path.join(target, destName)
+    if (!await exists(src)) continue
+    if (!await exists(dest)) { log.skipped(`${destName} (not present)`); continue }
+    const [fresh, current] = await Promise.all([fs.readFile(src, "utf8"), fs.readFile(dest, "utf8")])
+    if (fresh === current) { log.skipped(`${destName} (already up to date)`); continue }
+    await fs.writeFile(dest, fresh, "utf8")
+    log.appended(`${destName} (updated)`)
+  }
+}
+
+async function syncVersionFile(target) {
+  const pkg = _require(path.join(QUORUM_ROOT, "package.json"))
+  const dest = path.join(target, ".quorum-version")
+  const current = await exists(dest) ? (await fs.readFile(dest, "utf8")).trim() : null
+  if (current === pkg.version) {
+    log.skipped(`.quorum-version (already ${pkg.version})`)
+    return
+  }
+  await fs.writeFile(dest, pkg.version + "\n", "utf8")
+  log.appended(`.quorum-version — updated to ${pkg.version}`)
+}
+
+export async function run() {
+  const target = process.cwd()
+  const pkg = _require(path.join(QUORUM_ROOT, "package.json"))
+
+  console.log(c.bold("\nQuorum sync") + c.dim(`  v${pkg.version}`))
+  console.log(`Target: ${c.dim(target)}\n`)
+
+  if (!await exists(path.join(target, ".quorum-version"))) {
+    console.log(c.yellow("Quorum is not initialized here. Run 'quorum init' first.\n"))
+    process.exit(1)
+  }
+
+  log.section("Refreshing instruction files")
+  await syncCopilotInstructions(target)
+
+  log.section("Refreshing quorum docs")
+  await syncQuorumDocs(target)
+  await syncVersionFile(target)
+
+  console.log(`\n${c.green("✓ Sync complete.")}\n`)
+}

package/bin/quorum.js

@@ -30,6 +30,9 @@ ${c.bold("Usage:")}
   ${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 compass")} <subcommand>          Product-direction synthesis (brief, map, pathways, bets, score)
+  ${c.cyan("quorum sync")}                          Refresh Quorum instruction blocks after npm update
+  ${c.cyan("quorum migrate-v2")}                    Migrate from v1 vendored quorum/modules/ to npm package
   ${c.cyan("quorum --version")}                     Print version
 
 ${c.bold("quorum advisor")} subcommands:
@@ -52,6 +55,20 @@ ${c.bold("quorum sentinel")} subcommands:
   drift                     (requires LLM — use sentinelAssertions() instead)
   --json                    Machine-readable output
 
+${c.bold("quorum migrate-v2")} flags:
+  --dry-run       Preview what would be removed without writing
+
+${c.bold("quorum compass")} subcommands:
+  brief               Summarise product direction (LLM)
+  map                 Map behaviours from code + docs (no LLM)
+  pathways --goal X   Product pathways toward a goal (LLM)
+  bets                Strategic big bets (LLM)
+  score <idea>        Score a product idea (LLM)
+  spec <title>        Generate a product brief (LLM)
+  opportunities       List gaps from behaviour map (no LLM)
+  propose --from-last Stage a Chronicle entry from last artifact
+  outcome --entry-id X --result Y  Record a bet/pathway outcome
+
 ${c.bold("Exit codes")} (quorum check):
   0  low / medium risk
   1  high risk
@@ -120,6 +137,24 @@ async function cli() {
     return
   }
 
+  if (command === "sync") {
+    const { run } = await import(path.join(__dirname, "commands/sync.js"))
+    await run(rest)
+    return
+  }
+
+  if (command === "compass") {
+    const { run } = await import(path.join(__dirname, "commands/compass.js"))
+    await run(rest)
+    return
+  }
+
+  if (command === "migrate-v2") {
+    const { run } = await import(path.join(__dirname, "commands/migrate-v2.js"))
+    await run(rest)
+    return
+  }
+
   console.error(`${c.red(`Unknown command: ${command}`)}`)
   console.error(`Run ${c.bold("quorum help")} for usage.`)
   process.exit(1)

package/bin/templates/CLAUDE.md

@@ -0,0 +1,101 @@
+# Quorum — How to use this project's memory layer
+
+Quorum gives every AI session access to this project's approved decisions, rejected
+approaches, and institutional knowledge. It runs as a CLI tool backed by a local
+`.chronicle/` store.
+
+---
+
+## Start every session with memory
+
+Before proposing or planning anything, run:
+
+```bash
+quorum advisor brief
+```
+
+This shows the full Chronicle summary — what the team has already learned and approved.
+
+Then query for the specific area you are about to work in:
+
+```bash
+quorum advisor query "topic of the work"
+```
+
+If relevant entries exist, treat them as ground truth. **Refuted entries are hard stops** —
+do not retry a refuted approach without explicitly surfacing the failure reason to the user.
+
+---
+
+## Check designs before coding
+
+For any significant change, run a preflight check first:
+
+```bash
+quorum check \
+  --outcome "what you want to achieve" \
+  --design  "how you plan to do it"
+```
+
+Exit codes: `0` = low/medium risk — proceed. `1` = high risk — human review first.
+`2` = critical — stop and get explicit sign-off.
+
+Auth, payments, crypto, database migrations, PII, and data deletion always trigger
+elevated risk, regardless of how the design is framed.
+
+---
+
+## Propose what was learned
+
+When a significant decision is made or an approach is ruled out, stage a Chronicle
+proposal for human review:
+
+The Council stages proposals automatically after deliberation. You can also stage
+them manually by following the Chronicle proposal template in SETUP.md.
+
+```bash
+quorum commit --list        # see all pending proposals
+quorum commit <id>          # approve and index a proposal
+```
+
+**Never call `oracle.commit()` autonomously.** Only propose. A human must approve.
+
+---
+
+## Keep memory healthy
+
+```bash
+quorum growth               # is Chronicle actually growing?
+quorum evolve               # consolidate duplicate or stale entries (uses LLM)
+quorum sentinel coverage    # which source files have Chronicle entries?
+```
+
+---
+
+## Chronicle structure
+
+```
+.chronicle/
+  committed/      ← approved entries, indexed and searchable (commit to git)
+  proposals/      ← staged entries awaiting your approval (do not commit)
+  SUMMARY.md      ← auto-generated context, rebuilt on every commit
+```
+
+Commit `.chronicle/committed/` so every teammate and every new AI session starts with
+the same accumulated knowledge. Never commit `.chronicle/proposals/`.
+
+---
+
+## CLI quick reference
+
+```bash
+quorum advisor brief                          # full Chronicle summary, no LLM
+quorum advisor query "topic"                  # keyword search, no LLM
+quorum advisor "plain-language question"      # synthesised answer via LLM
+quorum check --outcome "..." --design "..."   # instant risk triage
+quorum commit --list                          # review pending proposals
+quorum commit <id>                            # approve a Chronicle entry
+quorum growth                                 # Chronicle learning health
+quorum evolve                                 # consolidate stale entries (LLM)
+quorum sync                                   # refresh Quorum instruction blocks after npm update
+```

package/modules/README.md

@@ -1,12 +1,12 @@
-# Advisor · Oracle · Jury · Council · Sentinel
+# Advisor · Oracle · Jury · Council · Sentinel · Compass
 
-Five portable modules for the knowledge and reasoning layer of any agentic workflow.
-Drop the `modules/` folder into your project and wire up the dependencies.
+Six portable modules for the knowledge, reasoning, and product-direction layer of any agentic workflow.
 
 ```
 Advisor  →  plain-language questions answered from Chronicle
 Oracle   →  Jury  →  Council  →  human gate  →  Executor
 Sentinel →  coverage + drift + PR coverage map
+Compass  →  product-direction synthesis (behaviours, pathways, bets, scoring)
 ```
 
 ---
@@ -20,6 +20,7 @@ Sentinel →  coverage + drift + PR coverage map
 | **Jury** | Evaluate a design against Oracle evidence — produces a confidence score | Yes |
 | **Council** | Adversarial validation via parallel advisor/reviewer fan-out — produces a verdict | Yes |
 | **Sentinel** | Chronicle coverage reporting, drift detection, and PR coverage maps | Optional |
+| **Compass** | Product-direction synthesis from Chronicle + codebase — behaviours, opportunities, pathways, bets, idea scoring | Optional |
 
 ---
 
@@ -91,6 +92,40 @@ You can substitute any vector store and embedder by implementing the `VectorStor
 
 ---
 
+## TypeScript runtime requirement
+
+Quorum ships TypeScript source (`.ts` files). Programmatic imports require a
+TS-aware runtime or bundler. Plain `node` will not work without a loader.
+
+**Supported runtimes:**
+
+```bash
+# tsx (recommended — zero config)
+npx tsx your-script.ts
+
+# ts-node
+npx ts-node --esm your-script.ts
+
+# Bun
+bun your-script.ts
+
+# Vitest / Jest with ts transform — works out of the box in test files
+```
+
+**Bundlers:** esbuild, Vite, Rollup, webpack — all supported with standard TS config.
+
+**Plain Node.js** (no TS runtime): use the CLI instead:
+
+```bash
+quorum advisor "question"
+quorum check --outcome "..." --design "..."
+```
+
+The CLI is always available after `npm install -g @balpal4495/quorum` and requires no
+TS loader. It is the recommended interface for most host-project use cases.
+
+---
+
 ## TypeScript
 
 Requires TypeScript 4.7+ and `zod` v3.
@@ -109,8 +144,10 @@ Recommended `tsconfig.json` settings:
 
 ## Quick start
 
+### npm users
+
 ```typescript
-import { setup } from "./modules/setup"
+import { setup } from "@balpal4495/quorum"
 
 // The simplest entry point — wires all modules from one call
 const { oracle, evaluate, deliberate, ask } = await setup({ llm: myLLMProvider })
@@ -123,12 +160,22 @@ const answer = await ask("what did the team decide about authentication?")
 const evidence = await oracle.query("authentication patterns in this codebase")
 ```
 
+### Quorum repo contributors
+
+Working directly inside the Quorum source tree? Import from the local path instead:
+
+```typescript
+import { setup } from "./modules/setup"
+
+const { oracle, evaluate, deliberate, ask } = await setup({ llm: myLLMProvider })
+```
+
 ### Manual wiring (without setup())
 
 ```typescript
-import { createOracleClient, xenovaEmbed, createLanceDBStore } from "./modules/oracle"
-import { evaluate } from "./modules/jury"
-import { deliberate } from "./modules/council"
+import { createOracleClient, xenovaEmbed, createLanceDBStore } from "@balpal4495/quorum/oracle"
+import { evaluate } from "@balpal4495/quorum/jury"
+import { deliberate } from "@balpal4495/quorum/council"
 
 // Wire Oracle manually
 const oracle = createOracleClient({
@@ -190,7 +237,7 @@ if (verdict.satisfied) {
 The Advisor is the plain-language interface to Chronicle. Use it to answer questions rather than to evaluate designs. It is a **read-only** path — it never calls `oracle.propose()` or `oracle.commit()`.
 
 ```typescript
-import { ask } from "./modules/advisor"
+import { ask } from "@balpal4495/quorum/advisor"
 
 const answer = await ask(
   { question: "What did the team decide about session handling?", evidence },
@@ -231,7 +278,7 @@ Advisor validates its own answer before returning. If `confidence < 0.7` or `blo
 The `LLMProvider` type is a simple function. Wire it to any provider:
 
 ```typescript
-import type { LLMProvider } from "./modules/shared/types"
+import type { LLMProvider } from "@balpal4495/quorum"
 
 // OpenAI example
 const openaiProvider: LLMProvider = async (messages, model = "gpt-4o") => {
@@ -276,7 +323,7 @@ interface JuryOutput {
 Before the LLM runs, Jury executes a deterministic preflight:
 
 ```typescript
-import { runPreflight } from "./modules/jury"
+import { runPreflight } from "@balpal4495/quorum/jury"
 
 const preflight = runPreflight(outcome, design, evidence)
 // preflight.touches_sensitive_area

package/modules/compass/behavior.ts

@@ -0,0 +1,161 @@
+import { randomUUID } from "crypto"
+import type {
+  ProductBehavior, ProductBehaviorGap, ProductBehaviorContradiction, BehaviorMap,
+  BehaviorMapInput, ProductSourceFinding, CompassEvidenceRef,
+} from "./types"
+
+// ── Deterministic behaviour mapping from source findings ─────────────────────
+
+export function mapBehaviorsFromFindings(
+  findings: ProductSourceFinding[],
+  input: BehaviorMapInput = {},
+): BehaviorMap {
+  const behaviors: ProductBehavior[] = []
+  const gaps: ProductBehaviorGap[] = []
+  const contradictions: ProductBehaviorContradiction[] = []
+
+  // Group CLI commands into behaviours
+  const cliFindings = findings.filter(f => f.kind === "cli")
+  for (const f of cliFindings) {
+    behaviors.push({
+      id: `behavior-cli-${f.id}`,
+      area: inferArea(f),
+      name: f.title,
+      description: f.summary,
+      current_behavior: f.summary,
+      evidence: [findingToRef(f)],
+      basis: ["implemented"],
+      confidence: f.confidence,
+    })
+  }
+
+  // Extract documented user flows from docs findings
+  const docsFindings = findings.filter(f => f.kind === "docs" && f.tags.includes("cli"))
+  for (const f of docsFindings) {
+    // Only add if not already covered by a CLI finding
+    const alreadyPresent = behaviors.some(b =>
+      b.current_behavior.toLowerCase().includes(extractCommand(f.summary).toLowerCase()) &&
+      extractCommand(f.summary).length > 3,
+    )
+    if (!alreadyPresent && extractCommand(f.summary)) {
+      behaviors.push({
+        id: `behavior-docs-${f.id}`,
+        area: inferArea(f),
+        name: `Documented: ${f.title}`,
+        description: f.summary,
+        current_behavior: f.summary,
+        evidence: [findingToRef(f)],
+        basis: ["documented"],
+        confidence: f.confidence * 0.9,
+      })
+    }
+  }
+
+  // Cross-reference: documented claims without implementation
+  const docsHeadings = findings.filter(f => f.kind === "docs" && !f.tags.includes("cli"))
+  const implementedAreas = new Set(behaviors.map(b => b.area))
+
+  // Detect gaps: central product promises with no CLI surface
+  const EXPECTED_AREAS = ["onboarding", "chronicle", "advisor", "review"]
+  for (const expected of EXPECTED_AREAS) {
+    const hasBehavior = behaviors.some(b => b.area === expected || b.name.toLowerCase().includes(expected))
+    if (!hasBehavior) {
+      const docRef = docsHeadings.find(f => f.summary.toLowerCase().includes(expected))
+      gaps.push({
+        id: `gap-${expected}`,
+        area: expected,
+        gap: `No first-class CLI command found for '${expected}'.`,
+        why_it_matters: `'${expected}' appears in product docs but has no dedicated CLI surface.`,
+        evidence: docRef ? [findingToRef(docRef)] : [],
+        confidence: 0.7,
+      })
+    }
+  }
+
+  // Gap: no product-direction module (Compass itself)
+  const hasCompass = behaviors.some(b => b.name.toLowerCase().includes("compass"))
+  if (!hasCompass) {
+    gaps.push({
+      id: "gap-product-direction",
+      area: "product direction",
+      gap: "No product behaviour mapping or direction module currently exists.",
+      why_it_matters: "Quorum helps agents avoid repeating engineering mistakes, but has no module to help avoid repeating product-direction mistakes.",
+      evidence: [],
+      confidence: 0.93,
+    })
+  }
+
+  // Filter by area if provided
+  const filteredBehaviors = input.area
+    ? behaviors.filter(b =>
+        b.area.toLowerCase().includes(input.area!.toLowerCase()) ||
+        b.name.toLowerCase().includes(input.area!.toLowerCase()),
+      )
+    : behaviors
+
+  const overallConfidence = filteredBehaviors.length === 0
+    ? 0.5
+    : filteredBehaviors.reduce((s, b) => s + b.confidence, 0) / filteredBehaviors.length
+
+  return {
+    generated_at: new Date().toISOString(),
+    area: input.area,
+    behaviors: filteredBehaviors,
+    gaps: input.area
+      ? gaps.filter(g => g.area.toLowerCase().includes(input.area!.toLowerCase()))
+      : gaps,
+    contradictions,
+    confidence: Math.round(overallConfidence * 100) / 100,
+  }
+}
+
+// ── Extract documented behaviors for LLM context ─────────────────────────────
+
+export function summarizeBehaviorMap(map: BehaviorMap): string {
+  const lines: string[] = []
+
+  if (map.behaviors.length > 0) {
+    lines.push("## Current behaviours")
+    for (const b of map.behaviors.slice(0, 20)) {
+      lines.push(`  ✓ ${b.current_behavior.slice(0, 100)}`)
+    }
+  }
+
+  if (map.gaps.length > 0) {
+    lines.push("\n## Gaps")
+    for (const g of map.gaps) {
+      lines.push(`  ? ${g.gap}`)
+    }
+  }
+
+  return lines.join("\n")
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function findingToRef(f: ProductSourceFinding): CompassEvidenceRef {
+  return {
+    id: f.id,
+    kind: f.kind,
+    source: f.source,
+    path: f.path,
+    summary: f.summary,
+    confidence: f.confidence,
+  }
+}
+
+function inferArea(f: ProductSourceFinding): string {
+  if (f.tags.includes("onboarding") || f.tags.includes("init")) return "onboarding"
+  if (f.tags.includes("chronicle") || f.tags.includes("commit") || f.tags.includes("proposal")) return "chronicle review"
+  if (f.tags.includes("advisor")) return "memory retrieval"
+  if (f.tags.includes("sentinel")) return "coverage"
+  if (f.tags.includes("compass")) return "product direction"
+  if (f.tags.includes("auth")) return "auth"
+  if (f.tags.includes("cli")) return "cli"
+  return "general"
+}
+
+function extractCommand(text: string): string {
+  const match = text.match(/`(quorum [^`]+)`/)
+  return match?.[1] ?? ""
+}