@balpal4495/quorum 0.4.0 → 1.0.0

package/CLAUDE.md

@@ -2,11 +2,12 @@
 
 ## Project overview
 
-Quorum is a portable reasoning layer for agentic codebases. Three TypeScript modules form
-the knowledge and validation layer for all agentic work:
+Quorum is a portable reasoning layer for agentic codebases. Five TypeScript modules:
 
 ```
-oracle.query()  →  jury.evaluate()  →  council.deliberate()  →  human gate  →  Executor
+Advisor  →  plain-language Chronicle queries
+Oracle   →  Jury  →  Council  →  human gate  →  Executor
+Sentinel →  coverage + drift
 ```
 
 Full module rules and design decisions: [modules/CLAUDE.md](modules/CLAUDE.md)
@@ -14,73 +15,132 @@ File ownership map: [modules/AGENTS.md](modules/AGENTS.md)
 
 ---
 
-## Gemini CLI (optional assistant)
+## Session protocol — run this every session
+
+This is not optional. Quorum is a self-improving system. It only improves if you use it.
 
-Before attempting any Gemini call, check availability:
+### On session start
+
+Run these before reading any code or proposing anything:
 
 ```bash
-which gemini 2>/dev/null
+node bin/quorum.js advisor brief
 ```
 
-If the command returns empty, skip this section entirely. The project is fully functional
-without Gemini. Never try to install it or ask the user to install it mid-task.
+This shows what's in Chronicle. Read it. It tells you what the team has already learned.
 
-**If Gemini is available**, use it as a large-context assistant — it can hold the entire
-codebase in a single context window where you work best on focused, precise tasks.
+Then query for the topic at hand:
 
-**Call `gemini -p "..."` when:**
-- You need to survey many files at once before deciding where to look
-- You want to trace a pattern, type, or call across the whole codebase
-- You want a second opinion on an architecture decision before proposing it to the user
+```bash
+node bin/quorum.js advisor query "topic of the work"
+```
 
-**Important:** The Bash tool does not auto-source shell profiles. Always prefix Gemini
-calls with `source ~/.zshrc &&` so that `GEMINI_API_KEY` and `GEMINI_CLI_TRUST_WORKSPACE`
-are loaded from the user's profile before invoking the CLI.
+If there are relevant entries, treat them as ground truth. If there are none, that's useful to know too — it means you're working in undocumented territory.
 
-**Patterns:**
+### During the session
 
-```bash
-# Broad survey before narrowing
-source ~/.zshrc && gemini -p "What are all the public exports across modules/ and what does each do?"
+Before making any architectural decision, ask explicitly:
 
-# Trace a pattern across many files
-source ~/.zshrc && find . -name "*.ts" | xargs cat | gemini -p "Find every place oracle.commit() is called"
+```bash
+node bin/quorum.js advisor query "the specific decision you're about to make"
+```
 
-# Second opinion on a design
-source ~/.zshrc && gemini -p "I'm about to add streaming to oracle/query.ts. Given the full codebase, what should I watch out for?"
+Examples:
+- `node bin/quorum.js advisor query "retry logic"`
+- `node bin/quorum.js advisor query "LLM validation"`
+- `node bin/quorum.js advisor query "CLI command structure"`
+
+If an entry is refuted, do not retry the approach. Surface the failure reason.
+
+### On session end
+
+For every significant decision made in the session, create a Chronicle proposal.
+
+What counts as Chronicle-worthy:
+- A new module or significant feature and its design rationale
+- An API or interface choice that will affect future sessions
+- A rejected approach and why it was rejected (important — prevents re-trying bad ideas)
+- A configuration or tooling decision that affects all future work
+- A failure or bug root cause that was non-obvious
+
+What does NOT need a Chronicle entry:
+- Routine code changes, style fixes, obvious bug fixes
+- Things already fully captured in git commit messages
+- Transient implementation details with no future impact
+
+**Template for a Chronicle proposal:**
+
+```javascript
+// Run with: node -e "..."
+const { randomUUID } = require('crypto')
+const { writeFileSync, mkdirSync } = require('fs')
+const path = require('path')
+
+mkdirSync('.chronicle/proposals', { recursive: true })
+
+const proposal = {
+  schema_version: 2,
+  topic: 'short label — module/area',
+  decision: 'One sentence: what was decided and why.',
+  key_insight: 'One sentence: what was decided and why.',   // same as decision
+  affected_areas: ['path/to/relevant/file.ts'],
+  scope: ['module-name', 'area-tag'],
+  alternatives_considered: ['Other approach that was considered'],
+  rejected_reason: ['Why the alternative was rejected'],
+  status: 'validated',      // or 'open' if still uncertain
+  confidence: 0.9,          // how certain you are this is right
+  source_module: 'council',
+  evidence_cited: [],
+  work_ref: { type: 'pr', ref: 'PR #N' },  // or spike/story
+}
+
+const id = randomUUID()
+writeFileSync(path.join('.chronicle', 'proposals', id + '.json'), JSON.stringify(proposal, null, 2), 'utf8')
+console.log('Proposed:', id.slice(0, 8), '—', proposal.topic)
 ```
 
-**Processing Gemini responses:**
-- You reason about Gemini's output — it assists, you decide
-- If Gemini contradicts what you know from reading the code, trust your direct reading
-- Never pass Gemini's response to the user unfiltered; synthesise it through your own judgment
+After creating proposals, tell the user: "I've staged N Chronicle entries — run `quorum commit --list` to review."
 
 ---
 
 ## Chronicle — the persistent knowledge store
 
-Chronicle lives at `.chronicle/`. Every prior decision, investigation finding, and outcome
-is stored there.
+Chronicle lives at `.chronicle/`. It is the team's accumulated learning — what has been tried, what worked, what failed, and why decisions were made.
 
-- **Query Oracle before proposing any solution.** Treat entries as ground truth for what has
-  been tried, what worked, and what failed.
-- **Never call `oracle.commit()` autonomously.** Use `oracle.propose()` to stage an entry.
-  A human must call `oracle.commit(proposalId)` to index it. There are no exceptions.
+**Rules:**
+- **Query first, always.** `node bin/quorum.js advisor query "topic"` before proposing any design.
+- **Never call `oracle.commit()` autonomously.** Use the proposal template above. A human must run `quorum commit <id>`.
+- **Cite entries by ID.** When referencing a Chronicle finding, use `[entry-id-prefix]`.
+- **Respect refuted entries.** If an entry is refuted, do not retry the approach without surfacing the failure reason to the user first.
 
 ---
 
-## Rules for AI agents
+## Gemini CLI (optional assistant)
+
+```bash
+which gemini 2>/dev/null
+```
 
-- **Evidence first.** Query Oracle before proposing any design or implementation.
-- **No auto-commits.** Never call `oracle.commit()` without explicit human input.
-- **Cite entries.** Use entry IDs (e.g. `[abc-123]`) when referencing Chronicle findings.
-- **Respect refuted entries.** Surface the failure reason — don't ignore it.
-- **Fail loudly.** Jury and Council throw on bad LLM output. Do not swallow errors.
+If empty, skip. Never install it or ask the user to install it mid-task.
+
+**Use Gemini when:**
+- You need to survey many files at once before deciding where to look
+- You want to trace a pattern across the whole codebase
+- You want a second opinion on an architecture decision before proposing it
+
+```bash
+source ~/.zshrc && gemini -p "What are all the public exports across modules/ and what does each do?"
+source ~/.zshrc && find . -name "*.ts" | xargs cat | gemini -p "Find every place oracle.commit() is called"
+```
+
+Reason about Gemini's output — it assists, you decide. Never pass it unfiltered to the user.
 
 ---
 
 ## Build and test
 
 ```bash
-npx vitest run modules/
+npx vitest run modules/ evals/
 ```
+
+All 141 tests must pass before any PR.