# Assistant Module — Rules (per FVW v8 §11.9 — 9 Universal Things)

**Per FVW v8 v0.10.0 §11.9:** Every module's `rules.md` contains 9 universal workflow things. The doctrine defines; this module instantiates.

---

## 1. Capability Declaration

### Reconstruction Mode Declaration (per §33)

- **Mode:** Sovereign SPA Mode (third mode; per DO-001)
- **Target runtime:** React 18 + TypeScript + Vite
- **Module file extension:** .tsx + .ts
- **View fragment format:** React components
- **State management:** React hooks + module-level singletons
- **Theme tokens:** CSS custom properties

### Capability statement

I CAN:
- Run 9-layer Smart dispatcher (heuristic / web-search / data / history / classify / standard / how-to / off-topic / clarify)
- Render 4-state dock (bar / sheet-min / sheet-full / peek)
- Persist anchors in BackStack with 1000/999 invariant
- Execute action chips (navigate / open-item / compose / export)
- Search the web opt-in via DuckDuckGo
- Dispatch to 5 LLM adapters (stub / smart / anthropic / openai / local)

I CANNOT:
- Generate prose without a generative LLM (writing requires Local / Anthropic / OpenAI)
- Run without an active LLM provider (must select provider in Settings)
- Perform semantic search (Cmd+K is keyword-based)
- Audit commits without operator signoff

External validation required for:
- Any C8 Shape Matrix change (must update `vp/runtime.test.ts`)
- Any new assistant adapter (must register with `registerAdapter`)
- Any change to `askOscar` signature (breaking change)

---

## 2. Do-not-proceed rule

If ANY of the following fails, I MUST stop and write `blocker.md`:
- `vp/runtime.test.ts` fails (dock state machine broken)
- `vp/intelligence.test.ts` fails (Smart adapter broken)
- `vp/sovereignty.test.ts` fails (forbidden import introduced)
- `pact/recipes/assistant/coverage-matrix.md` has ✗ in any column

I MUST NOT skip, work around, or guess. After 3 failed fix attempts, write `stuck.md`.

---

## 3. Contract primacy

This module's contract is:
- `recipe.md` (3 sections: A. Product, B. Structural Contract incl. Reconstruction Mode Declaration, C. Reconstruction Notes)
- `codex.md` (C1-C9 contract items)

Scaffolding files (`module-meta.json`, `ingredients.json`, `diffs/`, `trace-atlas/`, `dna/`) are NOT the contract.

If the contract and source disagree, **fix the contract** (per §08 Rule 1).

---

## 4. Anti-drift enforcement (4 numbered checks)

### Check 1: Recipe → Source Check
Verify `recipe.md` Product Description matches:
- AssistantDock is the root component
- 4 states exist in `state-machine.ts`
- askOscar is the single entrypoint
- 5 adapters registered in `intelligence/adapters/`
- 25+ heuristics in `heuristics.ts`

### Check 2: Visual Diff Check
Compare current UI to reference (per §08 Rule 5):
- Bar: green dot, bottom-fixed
- SheetMin: lifted sheet with input
- SheetFull: bubbles left/right, action chips below
- Peek: panel peeking

### Check 3: Behavioural Check
Per §22 C6 user simulations (10 listed in codex.md), each must be runnable.

### Check 4: Contract Check
Per §35 Module-Pact Registration:
- `app/src/assistant/module.json` `constitutional_fragments` lists every fragment consumed
- All 50+ fragments exist in `pact/fragments/`
- Forward check (module → pact) passes per MP-1

---

## 5. Plan-as-law

See `pact/recipes/assistant/plan.md` (atomic steps; not yet written).

---

## 6. Fallback behaviour

When the smart adapter returns no match (Layer 9 clarifying), the assistant:
- Echoes the user's words
- Offers action chips (navigate / open-item / compose / export)
- Does NOT invent behaviour (per §08 Rule 3 no invention)

When the active provider is generative (anthropic / openai):
- `askOscar` blocks until response or timeout
- On timeout, returns friendly error
- On rate limit, returns retry message

When the active provider is local (Qwen 0.5B STUB):
- `LocalAdapter.complete()` returns PLACEHOLDER error
- Surfaces the §15.3 ceiling violation gracefully

---

## 7. User-simulator requirement

C6 user simulations (10 listed in codex) must be runnable as automated tests. The implementer MUST run all 10 simulations before declaring the assistant module complete.

---

## 8. Re-anchor cadence

Re-read the contract (recipe.md + codex.md) at every phase boundary:
- Beginning of every Pact-only change
- Beginning of every runtime change that touches this module
- After every App-VP test failure
- On operator directive

---

## 9. Coverage matrix

See `pact/recipes/assistant/coverage-matrix.md` (5 columns: source feature / source-line / recipe claim / impl status / test status). All cells MUST be ✓ or ✗. Empty cells = FAIL.

---

## END OF RULES.MD

*9 universal things per FVW v8 §11.9 instantiated for the Assistant module.*