# Spec — Qwen Rule-Checker + Searchable SQLite Rulebook & Decision-Book

**Delegated to:** 🏗️ architect (infra) — database + local-LLM context substrate.
**Status:** spec for pickup. **Why now:** we have tons of documentation; it must become a queryable
substrate the local LLM can actually use, sentence-by-sentence, without blowing context.

## Framing: this is an ADDITION to the pixel (not a replacement)
The SQLite rulebook + decision-book is **one more input the local LLM reads alongside the pixel/
PMU maps and the reefs** — not a separate silo. The competence pixel already places work on the
lattice; this gives qwen the *named rules* and *prior decisions* to read **together with** that
placement, so it can say not just "this drifted" but "this breaks rule X, against decision Y." Two
tracks, both required: **(a)** stand up the SQLite substrate (rules + decisions, searchable), and
**(b)** teach qwen to read the pixel maps better *with that substrate in context*. And both must be
**maintained** — a living rulebook + decision-book that Claude keeps current as new rules are bitten
and new choices are made.

## The core inversion (the whole point)
qwen (local, qwen2.5:7b) is **better at recognizing rule-breaking than at producing rule-clean
prose.** So flip the division of labor:
- **qwen** reads a small artifact (a paragraph, a code hunk, a commit message) **plus the relevant
  rules + recent context**, and emits **which rules it breaks, quoting the rule and the offending
  span.** Recognition, not generation.
- **Claude** takes qwen's named violations and **solves** them. Generation/repair.
This is the optimal token split: qwen does cheap, local, high-recall detection; Claude spends
expensive tokens only on the fix. qwen monologues *everything we write or commit* and says
"breaks rule X, rule Y"; Claude resolves.

## Components

### 1. SQLite store (`data/substrate.sqlite`, local "sequel light")
- **`rules`** — one row per rule. Columns: `id`, `name`, `category` (hard | voice | format | pmu),
  `statement`, `rationale`, `incident` (what created it), `guard` (test/hook that enforces it),
  `priority` (int), `source` (file), `created_at`. Seed from `docs/voice/paradox-voice-rulebook.md`
  + the CLAUDE.md voice/PMU rules + the `feedback_*` memory entries + the anti-rules ledger.
- **`decisions`** — one row per choice we've made. Columns: `id`, `title`, `choice`, `why`,
  `alternatives_rejected`, `scope`, `priority`, `decided_at`, `supersedes`, `source`. Seed from the
  `project_*`/`feedback_*` memory + key commits.
- **FTS5** virtual tables over both so qwen's context can be retrieved by relevance to the passage.
- **Sortable by time AND by priority** (the operator's explicit requirement) — indexes on
  `created_at`/`decided_at` and `priority`.

### 2. Loader / curator (`scripts/substrate/build.mjs`)
- Parses the rulebook + CLAUDE.md + memory + anti-rules → `rules`. Parses memory/commits →
  `decisions`. **Claude-optimized** (curated, deduped, priority-ranked) but **qwen-readable**
  (plain statements). Idempotent; re-run to refresh. Each rule keeps its guard/incident so a
  violation can cite the precedent.

### 3. Context manager (`scripts/substrate/context.mjs`)
Given a passage + a task, assemble qwen's window: the small text slice + the **top-N relevant
rules** (FTS) + the **relevant recent commit messages** + the **relevant prior decisions**, sorted
by time/priority, capped to keep qwen's window small and accurate. This is the bridge between the
SQLite substrate and the reefs (where the reefs are; how the context comes in to get along with
them).

### 4. qwen rule-checker (`scripts/substrate/qwen-rulecheck.mjs`)
- Input: passage + assembled context. Prompt qwen to **read and report each rule it breaks** as
  structured output: `[{ruleId, ruleName, quote (the offending span), why}]`. NOT to rewrite.
- One pass per small slice (qwen handles one at a time reliably; batching/parallel is a follow-up,
  possibly a cloud-model job — out of scope for v1).
- Output feeds Claude, who repairs and re-submits until qwen reports zero violations + the grade is ≥95.

### 5. Integration points
- The **commit-panel stories** (qwen already monologues there) gain the rule-violation read.
- The **book-edit loop** + all outreach prose route through `qwen-rulecheck → Claude-fix`.
- Anything we write or commit can be checked: prose, code, commit messages.

## Acceptance
- `data/substrate.sqlite` has `rules` + `decisions` (FTS5), sortable by time + priority.
- `qwen-rulecheck.mjs <file>` returns the rules a passage breaks, quoting each.
- A passage that violates a known rule is correctly flagged with the rule quoted; a clean passage returns zero.
- Wired into the commit-panel + the writing loop.

## Track B + maintenance (both required)
- **Track B — read the pixel maps better:** with the substrate in context, improve qwen's read of
  the PMU/reef placement so a violation cites both the drift (where it landed) and the rule/decision
  it breaks. The substrate is an input to the pixel read, not a parallel system.
- **Maintenance loop:** rules + decisions are LIVING. When a new rule is bitten (a new signal-loss
  drift) or a new choice is made, Claude appends it (with incident + priority) and re-runs the
  loader. The substrate is only as good as it is current.

## Notes / open
- v1 = single qwen pass per slice (recognition). Parallel/batch = a later cloud-model option.
- The rulebook itself may become a standalone product; this substrate is its machine-usable form.
- Keep qwen STRICTLY off any blocking path (recognition is advisory; Claude/operator decide).