@balpal4495/quorum 2.0.0 → 3.0.1

package/bin/commands/init.js

@@ -33,13 +33,19 @@ async function guardAlreadyInitialized(target) {
 async function writeQuorumDocs(target) {
   log.section("Writing Quorum docs")
   await fs.mkdir(path.join(target, "quorum"), { recursive: true })
-  for (const file of ["CLAUDE.md", "AGENTS.md"]) {
-    const src  = path.join(QUORUM_ROOT, "modules", file)
-    const dest = path.join(target, "quorum", file)
-    if (await exists(src)) {
-      await fs.copyFile(src, dest)
-      log.created(`quorum/${file}`)
-    }
+  // Host-facing CLAUDE.md — CLI-first operational guide, 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 fs.copyFile(claudeSrc, claudeDest)
+    log.created("quorum/CLAUDE.md")
+  }
+  // AGENTS.md — module file ownership map
+  const agentsSrc = path.join(QUORUM_ROOT, "modules", "AGENTS.md")
+  const agentsDest = path.join(target, "quorum", "AGENTS.md")
+  if (await exists(agentsSrc)) {
+    await fs.copyFile(agentsSrc, agentsDest)
+    log.created("quorum/AGENTS.md")
   }
   await fs.copyFile(
     path.join(QUORUM_ROOT, "SETUP.md"),

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