@balpal4495/quorum 2.0.0 → 3.0.1

package/.github/copilot-instructions.md

@@ -2,11 +2,14 @@
 
 ## Architecture
 
-This project uses three portable reasoning modules: **Oracle**, **Jury**, and **Council**.
-They form the knowledge and validation layer for all agentic work in this codebase.
+This project uses six portable reasoning modules: **Advisor**, **Oracle**, **Jury**, **Council**, **Sentinel**, and **Compass**.
+They form the knowledge, validation, and product-direction layer for all agentic work in this codebase.
 
 ```
-oracle.query()  →  jury.evaluate()  →  council.deliberate()  →  human gate  →  Executor
+Advisor  →  plain-language Chronicle queries
+Oracle   →  Jury  →  Council  →  human gate  →  Executor
+Sentinel →  coverage + drift
+Compass  →  product-direction synthesis (behaviours, pathways, bets, scoring)
 ```
 
 Source: `modules/` — see [modules/README.md](modules/README.md) for full API reference.
@@ -35,20 +38,23 @@ There are no auto-commits. Do not attempt to bypass this gate.
 
 | Module | What it does | LLM? |
 |---|---|---|
+| `ask()` | Plain-language question answered from Chronicle — validates internally, retries up to 2× | Yes |
 | `oracle.query()` | Retrieves relevant Chronicle entries by semantic + BM25 search | No |
 | `oracle.propose()` | Stages a new entry for human review | No |
 | `oracle.commit()` | Indexes an approved entry — human-triggered only | No |
 | `jury.evaluate()` | Scores a design against evidence across 4 dimensions | Yes |
 | `council.deliberate()` | Adversarial validation via advisor/reviewer fan-out | Yes |
+| `sentinel` | Coverage reporting, drift detection, and PR coverage maps | Optional |
+| `compass` | Product-direction synthesis — behaviours, opportunities, pathways, bets, idea scoring | Optional |
 
 ---
 
 ## Setup
 
 ```typescript
-import { setup } from "./modules/setup"
+import { setup } from "@balpal4495/quorum"
 
-const { oracle, evaluate, deliberate } = await setup({ llm: yourProvider })
+const { oracle, evaluate, deliberate, ask, compass } = await setup({ llm: yourProvider })
 ```
 
 `setup()` creates Chronicle directories, warms the embedder, and wires all dependencies.
@@ -87,8 +93,25 @@ After `council.deliberate()`:
 
 ---
 
+## 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 compass map                          # map current product behaviours (no LLM)
+quorum compass brief                        # product-direction summary (LLM)
+quorum compass pathways --goal "..."        # generate product pathways (LLM)
+quorum compass score "idea"                 # score a product idea (LLM)
+```
+
+---
+
 ## Build and test
 
 ```bash
-npx vitest run modules/
+npx vitest run modules/ evals/
 ```

package/README.md

@@ -28,6 +28,23 @@ Every new session starts from zero. The same mistakes get proposed again. The sa
 
 ---
 
+## Why not just use agent instructions?
+
+Agent instructions tell the AI how to behave.
+Quorum tells the AI what the project has already learned.
+
+| | Agent instructions | Chronicle |
+|---|---|---|
+| Content | Rules and preferences | Decisions, rejections, outcomes |
+| Growth | Static — you write them | Grows — the agent stages, you approve |
+| Durability | Easy to overwrite or ignore | Git-backed, survives config changes |
+| Failed approaches | Not tracked | Hard stops on refuted patterns |
+| Human approval | Not required | Required for every indexed entry |
+
+Instructions are a starting point. Chronicle is accumulated project knowledge.
+
+---
+
 ## What changes after Quorum
 
 **Without Quorum:**
@@ -125,6 +142,10 @@ Every PR merge posts a growth comment showing what Chronicle learned. `quorum ev
 | See whether memory is growing | `quorum growth` |
 | Consolidate stale or duplicate entries | `quorum evolve` |
 | Find undocumented areas | `quorum sentinel coverage` |
+| Understand what the product currently does | `quorum compass map` |
+| Generate product pathways toward a goal | `quorum compass pathways --goal "..."` |
+| Score a product idea | `quorum compass score "add Slack integration"` |
+| Stage a direction decision for Chronicle | `quorum compass propose --from-last` |
 
 ---
 
@@ -154,12 +175,57 @@ npx @balpal4495/quorum@latest init
 npm install
 ```
 
-Then install the CLI globally for terminal access:
+Then run Quorum from your project:
+
+```bash
+npx quorum advisor brief
+npx quorum advisor "what has the team decided about auth?"
+npx quorum check --outcome "..." --design "..."
+```
+
+**Optional — install the CLI globally:**
 
 ```bash
 npm install -g @balpal4495/quorum
+quorum advisor brief
 ```
 
+> **v2 architecture:** Implementation lives in the npm package (`node_modules/@balpal4495/quorum`). Project memory lives in your repo (`.chronicle/`). Agent docs bridge the two (`quorum/CLAUDE.md`, `.github/copilot-instructions.md`). Nothing is copied into your project that you need to maintain.
+
+---
+
+## Upgrading from v1
+
+If your project has a `quorum/modules/` folder (the v1 vendored pattern), migrate in one step:
+
+```bash
+quorum migrate-v2
+```
+
+After any `npm update @balpal4495/quorum`, refresh agent instruction files:
+
+```bash
+quorum sync
+```
+
+---
+
+## Runtime model
+
+The CLI works in plain Node 18+.
+
+Programmatic imports are TypeScript-native and require a TS-aware runtime such as `tsx`, `ts-node`, Bun, or a bundler. Plain `node` will not resolve `.ts` files.
+
+```bash
+# recommended for scripts
+npx tsx your-script.ts
+
+# or Bun
+bun your-script.ts
+```
+
+For most host-project use cases the CLI is sufficient and requires no loader. See [modules/README.md](modules/README.md) for the full programmatic API.
+
 ---
 
 ## Command reference
@@ -394,7 +460,7 @@ The next person touching that table has the full reasoning. They don't repeat th
 
 ## How it works under the hood
 
-You do not need to understand these internals to use Quorum. They are installed into `quorum/modules/` so any AI working in the codebase can inspect and use them directly.
+You do not need to understand these internals to use Quorum. They live in `node_modules/@balpal4495/quorum` after install. The `quorum/` folder that `init` creates in your project contains agent-readable docs and Chronicle data — not module source.
 
 | Module | What it does | LLM |
 |---|---|---|
@@ -403,6 +469,7 @@ You do not need to understand these internals to use Quorum. They are installed
 | **Jury** | Evaluates a design against Chronicle evidence. Four-dimension confidence score, deterministic preflight, hard-blocker gaps. | Yes |
 | **Council** | Adversarial panel — advisors challenge independently, reviewers critique anonymously, Chairman gives a structured verdict. Risk-scaled fan-out. | Yes |
 | **Sentinel** | Coverage reporting (which files Chronicle knows about), drift detection (are entries still accurate), PR coverage maps. | Optional |
+| **Compass** | Product-direction layer — maps current behaviours from code and docs, identifies gaps and opportunities, generates pathways, strategic bets, and idea scores grounded in Chronicle evidence. All writes go through `oracle.propose()`. | Optional |
 
 ### How Jury works