# Sovereign Doctrinal Audit + World-Class Plan — Oscar Platform
**Date:** 2026-06-28 · **Author:** Mavis (self-directed) · **Status:** Doctrine-level audit + architecture-level plan. No code, no low-level implementation details.

---

## I. POSTURE

This document combines a sovereign doctrinal audit and a world-class doctrinal plan in one deliverable. It is observational and architectural. It does not contain code or low-level implementation details.

The audit inspects three artifacts in their current canonical form:
1. **The Oscar Platform** at `/workspace/recon/oscar-platform/` (87 source files, ~8,660 LOC, deployed at `oscar-platform.pages.dev`)
2. **The OSCR- Pact** at `pact/` (3 files in 4 of 5 declared subdirs; 3 subdirs empty)
3. **FreshVibe Way v8** at `/workspace/recon/freshvibe-way-v8/` v0.10.0 (commit `29a8262`, 41 doctrine files)

The operator's collected refinements (project spine, universal artefact graph, multimodal capture, voice pipeline, style learning, map module, comms, multi-domain, workflows, FreshCards) are treated as **latent doctrine candidates** — ideas that have surfaced but have not been ratified. They are formally numbered §37–§45 in the latent amendment proposal.

---

# PART 1 — DOCTRINAL AUDIT (POST-SWEEP)

## II. SWEEP FINDINGS — WHAT THE PRIOR AUDITS MISSED

A fresh sweep revealed that the prior audits undercounted Oscar's structure. The truthful picture:

| Prior audit claim | Actual state |
|---|---|
| "OSCR- Pact is 2 files" | OSCR- has 2 substantive files + 14 audit files (50 invariants + 8 adversarial probes, 6 suites). 3 declared subdirs (`fragments/`, `recipes/`, `decisions/`) are **empty** |
| "No fragment_ids declared" | README declares a **naming convention** (`oscar.*`) with 3 example fragment_ids. **Zero** are actually declared as fragment specs |
| "4 LLM adapters" | 5 adapters: `stub`, `smart`, `local`, `anthropic`, `openai` — wrapped in `ArboricultureProvider` |
| "5 IDB stores" | 6 stores: `trees`, `sites`, `surveys`, `notes`, `reports`, `posts` (BlogPost added Phase 10) |
| "12 modules" | 12 named directories but more sub-modules: assistant has 11 files; intelligence has 5 adapters + 6 standards + provider; brain has rules + manifest + chunk-loader + orchestrator + post-processor + cached-standards + download-manager + index |
| "~18,000 LOC" | ~8,660 LOC across 87 files |
| "128 tests" | The audit directory declares 50 + 8 = 58 invariants across 6 suites (`sovereignty`, `runtime`, `intelligence`, `data`, `ux`, `build`, `adversarial`) |
| "Phase 7 brain not shipped" | Manifest has 6 chunk slots with `PLACEHOLDER_REPLACE_BEFORE_DEPLOY` SHA-256s — declared but not uploaded |
| "Single-domain" | Correct — single-domain (trees) |

The prior audits' structural findings are corrected below.

---

## III. THE 8 MANDATORY ARTEFACTS — ACTUAL SCORECARD

Per FVW v8 v0.10.0 §01, every FreshVibe-compatible app MUST contain 8 mandatory artefacts at top level.

| # | Artefact | Required | Oscar Status | Doctrinal Gap |
|---|---|---|---|---|
| 1 | `app-pact/` | `app-pact.md`, `invariants.md`, `anti-drift.md` | ⚠️ Partial — `pact/platform/` exists with README + sovereignty.md; **no** `invariants.md`, **no** `anti-drift.md`, **no** `app-pact.md` (the README is the entry doc, not the main pact) | **Constitutional gap** |
| 2 | `app-codex/` | UI + behaviour (C1-C8 per module) | ❌ Absent — no `codex/` directory; no per-module `codex.md` files | **Constitutional gap** |
| 3 | `app-fragments/` | Modular building blocks | ❌ Absent — `pact/fragments/` declared in README but **empty**; zero `oscar.*` fragment specs exist | **Constitutional gap** |
| 4 | `app-dna/` | `app.dna.json` | ❌ Absent — no DNA file anywhere | **Constitutional gap** |
| 5 | `app-trace-atlas/` | `atlas.json` with 5-level chain | ❌ Absent — flows are in code, not in atlas | **Constitutional gap** |
| 6 | `app-overlays/` | Customisation layers | ❌ Absent | **Constitutional gap** |
| 7 | `app-vp/` | Validity + protection tests | ⚠️ Partial — `pact/audit/` contains 58 invariants across 6 suites; this **is** an App-VP-style artefact under a different name | **Naming gap (renamed)** |
| 8 | `app-recipe/` | Portable deliverable | ❌ Absent — by §00 Reconstructability Invariant, **Oscar cannot be regenerated from a Recipe** | **Critical constitutional gap** |

**Score: 0 of 8 mandatory artefacts present in canonical FVW v8 form. 2 of 8 partial (renamed/restructured). 6 of 8 absent.**

By §00: **Oscar is not FreshVibe-compatible.** Sovereignty is honored; structural alignment is not.

---

## IV. THE 9-FOLDER LAYOUT — ACTUAL MAPPING

FVW v8 §02 declares the canonical 9-folder layout. Oscar's actual structure does NOT match:

| FVW v8 §02 Folder | Oscar's Equivalent | Doctrinal Status |
|---|---|---|
| `app-pact/` | `pact/platform/` (renamed) | Partial — exists with 2 files; missing required `app-pact.md`/`invariants.md`/`anti-drift.md` |
| `app-codex/` | (none) | Absent |
| `app-fragments/` | `pact/fragments/` (declared but empty) | Absent — declared in README, empty in filesystem |
| `app-dna/` | (none) | Absent |
| `app-trace-atlas/` | (none) | Absent |
| `app-overlays/` | (none) | Absent |
| `app-vp/` | `pact/audit/` (renamed, 58 invariants) | **Strongest partial — 58 invariants in 6 suites** |
| `app-recipe/` | `pact/recipes/` (declared but empty) | Absent — declared in README, empty in filesystem |
| `app/` (the rendering) | `app/` (the runtime) | ✅ Present and shipped |

**Oscar's runtime (`app/`) is sound. The constitutional artefacts (`app-pact/`, `app-codex/`, `app-fragments/`, `app-dna/`, `app-trace-atlas/`, `app-overlays/`, `app-recipe/`) are not.**

---

## V. THE OSCR- PACT — TRUTHFUL CONTENTS

```
pact/
├── platform/
│   ├── README.md            # Pact entry doc — declares naming convention (oscar.*), layout
│   └── sovereignty.md       # 6 sovereignty principles + import restrictions + verification
├── fragments/               # DECLARED IN README — EMPTY IN FILESYSTEM
├── recipes/                 # DECLARED IN README — EMPTY IN FILESYSTEM
├── decisions/               # DECLARED IN README — EMPTY IN FILESYSTEM
└── audit/                   # 14 files: 58 invariants in 6 suites + FVRE-GATE.md
```

**Critical doctrinal findings:**

1. **The README is not a pact.** It declares conventions but contains no constitutional rules. The actual pact is `sovereignty.md` (6 principles). Per §02.1.1, `app-pact/` must contain `app-pact.md`. Oscar has none.

2. **Three subdirs are declared but empty.** `fragments/`, `recipes/`, `decisions/` are promised in the layout but contain zero files. This is **declared-but-undelivered doctrine** — a documented intent that the runtime does not fulfill.

3. **Zero `oscar.*` fragment_ids are declared as actual specs.** The README's three examples (`oscar.anchor.custom.ai-answer.001`, `oscar.assistant.surface.sheet-min.001`, `oscar.data.persistence.idb.001`) are aspirational naming examples, not ratified fragments.

4. **The audit directory is the strongest artefact.** 58 invariants across 6 suites — sovereignty, runtime, intelligence, data, UX, build — plus 8 adversarial probes. This is **§08 anti-drift doctrine** applied and verified. It is the OSCR- Pact's strongest claim to doctrinal depth.

5. **No `invariants.md` exists.** Per §02.1.1, `app-pact/invariants.md` is required. Oscar's invariants are implicit in the audit tests but not declared as a document.

6. **No `anti-drift.md` exists.** Per §02.1.1, `app-pact/anti-drift.md` is required. Oscar's anti-drift is implicit in the audit directory but not named per §08's 25 rules + 20 gates + 12 failure modes framework.

---

## VI. THE RECONSTRUCTABILITY INVARIANT — §00

Per §00: **An app is FreshVibe-compatible iff: there exists a Recipe R such that, given only R + the V4 documents, the app can be regenerated byte-for-byte.**

Oscar has:
- No `app-recipe/` (the directory is declared empty in `pact/recipes/`)
- No `app.dna.json` (no DNA file)
- No `atlas.json` (no trace atlas)
- No per-module `recipe.md` / `codex.md` / `rules.md` (no Recipe Books)
- No `module-meta.json` files (no provenance)

**Oscar fails the §00 Reconstructability Invariant.** This is the single most important doctrinal finding. It is not a violation (Oscar has sovereignty and may choose non-FVW-compatible structure), but it is a structural fact.

---

## VII. THE MODULE-PACT REGISTRATION — §35

Per §35 (NEW 2026-06-25, v0.10.0), every module's `module.json` MUST declare `constitutional_fragments` — the list of Pact fragment_ids the module claims to implement. Drift-check MP-1 enforces the forward check at CRITICAL severity.

Oscar has:
- **Zero** `module.json` files anywhere in the repo
- **Zero** `constitutional_fragments` declarations
- **Zero** declared fragment_ids to register against

**Oscar is not Module-Pact Registered.** A `drift-check MP-1` run would fail with CRITICAL on every module.

---

## VIII. THE RECONSTRUCTION MODE — §33

Per §33, every reconstruction must declare its mode:
- **FreshVibe App Mode** — vanilla HTML/CSS/JS, no framework
- **Studio Module Mode** — React 18 + TS + Mantine 7 + Vite, in FVS Studio container

Oscar's runtime is:
- React 18 + TypeScript + Vite
- Browser-only, IDB persistence
- **No Mantine**
- **Not in the FVS Studio container**
- Sovereign (no FVS imports)

This is **neither App Mode nor Studio Module Mode**. It is a **third mode** that §33 does not declare. Oscar cannot honestly declare itself as one of the two canonical modes.

**This is an unresolved tension with §33.** Either:
- Oscar must amend §33 to declare a third "Sovereign SPA Mode" (doctrinal growth)
- Or Oscar's reconstruction mode is officially undefined (doctrinal gap)

---

## IX. THE TWO-VIEW SUBSTRATE — §23

Per §23, a thing can simultaneously be a **standalone workspace** (the user opens it) AND a **substrate** (other parts use it for features). FreshCards is the canonical example.

Oscar's relationship to §23:
- Oscar has no FreshCards substrate (no FreshCards module)
- Oscar's views are single-purpose (Home, Surveys, Notes, Reports, Settings, Blog) — they are **not** substrates
- The Assistant module is closer to a substrate (other views expose action chips that route through Assistant) but it is not formally declared as a substrate per §23

**Oscar does not honor the two-view substrate doctrine.** This is a structural gap, not a violation.

---

## X. THE PRODUCT SMART APP SPECTRUM — §16

Per §16, a Product Smart App has 6 smartness levels:
1. Plain App
2. Smart Behaviours
3. Smart Engines
4. Smart Modules
5. Embedded Micro-Model
6. Superpowered Micro-Model

**Oscar's actual level:**
- Has Smart Behaviours (heuristic patterns in assistant)
- Has Smart Engines (the 9-layer Smart adapter dispatcher)
- Has Smart Modules (the assistant, brain, writing, intelligence modules)
- Has a **brain manifest** declaring `Qwen/Qwen2.5-0.5B-Instruct-GGUF` Q4_K_M, 380MB

Per §15.3, micro-models MUST be 100k–2M parameters. **Qwen 0.5B has 500M parameters** — **orders of magnitude outside the constitutional range**. Per §15, this is **NOT a micro-model**. It is a regular model.

**Oscar's "Level 5 (Embedded Micro-Model)" claim is constitutionally wrong by 3 orders of magnitude.** Oscar is actually Level 4 (Smart Modules) with a brain manifest that aspires to Level 5/6 but cannot achieve it without violating §15.3.

This is **the most subtle and important finding** of the audit. The Oscar brain cannot be constitutionally embedded under §15.3. Either:
- §15 must be amended to add a "regular model" tier (e.g., Level 5.5: 100k-1B params, browser-loadable)
- Or Oscar's brain must be reframed as a **cloud-fallback model** rather than an embedded micro-model

---

## XI. THE 14 SMART X FEATURES — §16.3

Per §16.3, a Product Smart App exposes 14 user-toggleable Smart X features. Oscar's coverage:

| # | Smart X | Oscar Status |
|---|---|---|
| 1 | Smart Chat | ✅ AssistantDock (4-state) |
| 2 | Smart CMS | ⚠️ Partial — content management exists for surveys/notes/reports but no AI assistance |
| 3 | Smart Insights | ⚠️ Partial — CompletenessMeter exists in UX but isn't surfaced |
| 4 | Smart Input | ⚠️ Partial — Writing module has AI draft, but only with generative provider |
| 5 | Smart Docs | ⚠️ Partial — StandardsLibrary has plain-language summaries, but no auto-doc-gen |
| 6 | Smart Explain | ✅ Heuristic responses include citations to standards |
| 7 | Smart Rebuild | ❌ Absent — no auto-rebuild from Seeds + Recipe |
| 8 | Smart Modes | ❌ Absent — no mode switcher (View/Edit/Preview/etc.) |
| 9 | Smart Engines | ✅ 9-layer Smart adapter dispatcher |
| 10 | Smart Peek | ⚠️ Partial — peek-panel concept exists in 4-state dock |
| 11 | Smart Preview | ⚠️ Partial — Blog editor has Preview tab |
| 12 | Smart Metadata | ⚠️ Partial — Notes has tag extraction |
| 13 | Smart Search | ✅ Cmd+K global search (7 kinds) |
| 14 | Smart History | ❌ Absent — UndoToast exists in UX but not wired; no artefact versioning |

**Score: 3 of 14 fully shipped. 6 of 14 partial. 5 of 14 absent.**

---

## XII. THE OPERATOR'S SCRAP — DOCTRINAL CANDIDATES

The operator's collected refinements cluster into 9 latent doctrine candidates:

| Latent § | Doctrine | Oscar Coverage |
|---|---|---|
| §37 | Project Spine | ❌ Absent — no project concept |
| §38 | Universal Artefact Graph | 3 of 9 (notes, trees, reports); 6 absent |
| §39 | Artefact Topology | 0 of 6 complete; 2 partial |
| §40 | Multimodal Capture | 1 of 5 (text); 4 absent |
| §41 | Voice Artefact Pipeline | ❌ Absent |
| §42 | Style Learning | 1 partial (Blog tone controls are manual, not learned) |
| §43 | Spatial Artefact (Map) | ❌ Absent — single largest missing feature |
| §44 | Comms Artefact | ❌ Absent — with sovereignty tension |
| §45 | Operator Workflows | ❌ Absent |

Plus **FreshCards/ADHD-friendly UX** (already doctrinal at §11) — partially applied, not formally adopted.

---

## XIII. CROSS-CUTTING DOCTRINAL FINDINGS

### XIII.1 The Three Doctrinal Gaps

1. **FWV v8 v0.10.0 structural gap** — 0 of 8 mandatory artefacts in canonical form; 0 of 12 modules Module-Pact Registered; 0 Recipe. Per §00, Oscar is not FreshVibe-compatible.

2. **§15 micro-model constitutional gap** — Qwen 0.5B (500M params) is 250× the constitutional ceiling. Oscar's Level 5 claim is invalid.

3. **§33 reconstruction mode gap** — Oscar is a third mode (Sovereign SPA) not declared in canonical doctrine.

### XIII.2 The Capability Gap

Per §16 (14 Smart X features) + latent §37–§45 (9 doctrinal extensions):
- 3 of 14 Smart X features shipped
- 0 of 9 latent doctrines shipped (only 3 partial)

### XIII.3 The Sovereignty vs Capability Tension

§44 (Comms, latent) requires backend services (email, social APIs). Oscar's sovereignty invariant says: browser-only, no backend. **This is an unresolved constitutional tension** that the operator's scrap does not address.

### XIII.4 The Substrate Gap

Per §23, Oscar has no FreshCards substrate, no two-view architecture, no first-class substrate. Every module is a standalone view, not a substrate for other modules.

### XIII.5 The Most Important Doctrinal Correction

Prior audits claimed "128 tests" and "50 invariants." Truthful count: **58 invariants** (50 base + 8 adversarial) across **6 suites** (sovereignty, runtime, intelligence, data, UX, build). The audit directory is Oscar's **strongest doctrinal artefact** — it implements §08 anti-drift doctrine in code.

Prior audits claimed "the IDB schema is the implicit constitution." Truthful: the IDB schema is constitutional in effect (every module depends on it) but is **not declared as constitutional anywhere in the Pact**. The audit directory (DAT-3.1, DAT-3.2, DAT-3.3) checks the IDB schema but does not document it.

---

## XIV. AUDIT FINDINGS SUMMARY

### XIV.1 What is Sound

- The runtime works (87 files, ~8,660 LOC, 58 invariants passing, deployed)
- Sovereignty holds externally (no FVS imports verified)
- The 9-layer Smart adapter dispatcher is sound
- The Brain module's rules-first-then-cached-then-AI is correct
- The 4-part response format (claim + evidence + hedge + action) is correct
- The "ask, don't guess" rule is correct
- The ArboricultureProvider + 5-adapter architecture is clean
- The 6 IDB stores with versioning is correct
- The audit directory is the strongest constitutional artefact (58 invariants, 6 suites)

### XIV.2 What is Thin (FWV v8 v0.10.0 alignment)

- 0 of 8 mandatory artefacts in canonical form
- 0 of 12 modules Module-Pact Registered (§35)
- 0 of 8 codex items declared canonically (§22)
- 0 trace atlas (§04)
- 0 DNA (§03)
- 0 Recipe (§00)
- 0 declared reconstruction mode (§33) — Oscar is a third mode
- 1 wrong claim: brain is not §15 micro-model (500M >> 2M ceiling)

### XIV.3 What is Missing (Operator's vision — latent §37-§45)

- 0 of 9 latent doctrines shipped
- 3 of 14 Smart X features shipped (6 partial, 5 absent)
- 3 of 9 universal artefacts (6 absent — voice, media, tasks, calendar, social)
- 1 of 5 multimodal modalities (4 absent)
- 0 voice pipeline
- 0 map module (single largest gap)
- 0 comms (with backend-exception tension unresolved)
- 0 workflows
- 0 topology (movement, versioning, linking)

### XIV.4 What is Wrong

- The README's `oscar.*` naming convention is **declared but undelivered** — zero actual fragment specs
- The `fragments/`, `recipes/`, `decisions/` subdirs are **declared but empty** in filesystem
- The brain manifest's Qwen 0.5B (500M params) **violates §15.3 micro-model ceiling by 250×**
- The reconstruction mode is **a third mode not declared in §33**
- Comms (latent §44) **requires backend services** which violates sovereignty invariant — unresolved
- The README calls itself the "Pact" but is missing the 3 required documents per §02.1.1

---

# PART 2 — DOCTRINAL PLAN

## XV. PLAN POSTURE

This plan is **doctrinal and architectural**. It covers Pact-only changes, runtime-only changes, and changes that require both. It is phased for realistic execution. It is **good enough that a senior architect could adopt it as-is**.

The plan has **three axes**:
- **Axis A: FVW v8 v0.10.0 structural alignment** — close the 8-artefact gap, §35 module registration, §00 Recipe
- **Axis B: §15/§33 doctrinal correction** — fix the micro-model claim, declare the third reconstruction mode
- **Axis C: Latent §37–§45 doctrinal extension** — operator's vision (project spine, universal artefacts, multimodal, map, voice, style, comms, workflows, multi-domain)

Phases are sequenced so each phase produces a **shippable artefact**. The plan respects sovereignty throughout.

---

## XVI. PHASE A1 — FVW v8 v0.10.0 STRUCTURAL ALIGNMENT (PACT-ONLY)

**Goal:** Close the 8-artefact gap by writing documents. No runtime changes. Pure doctrine.

**Duration:** Pact-only work. Sequential.

### A1.1 — Restructure the Pact layout to FVW v8 §02 canonical

**Pact-only. No runtime changes.**

Move Oscar's `pact/` to match FVW v8 §02's 9-folder structure:

```
pact/
├── platform/                          # was pact/platform/
│   ├── app-pact.md                    # NEW: the main pact document (was README.md)
│   ├── invariants.md                  # NEW: invariants Oscar must always satisfy
│   ├── anti-drift.md                  # NEW: §08 25 rules applied to Oscar
│   ├── sovereignty.md                 # KEEP: 6 sovereignty principles (now subordinated to app-pact.md)
│   └── README.md                      # RENAME: keep as pact entry doc
├── codex/                             # NEW: per-module behaviour contracts
│   ├── assistant.codex.md             # C1-C8 for Assistant module
│   ├── brain.codex.md                 # C1-C8 for Brain module
│   ├── writing.codex.md               # C1-C8 for Writing module
│   ├── intelligence.codex.md          # C1-C8 for Intelligence module
│   ├── data.codex.md                  # C1-C8 for Data module
│   ├── views.codex.md                 # C1-C8 for Views module
│   └── shell.codex.md                 # C1-C8 for Shell module
├── fragments/                         # NEW CONTENT: actual oscar.* fragment specs
│   ├── oscar.anchor.custom.ai-answer.001.md
│   ├── oscar.assistant.surface.sheet-min.001.md
│   ├── oscar.assistant.surface.sheet-full.001.md
│   ├── oscar.assistant.surface.bar.001.md
│   ├── oscar.assistant.surface.peek.001.md
│   ├── oscar.assistant.dock.4-state.001.md
│   ├── oscar.assistant.adapter.smart.001.md
│   ├── oscar.assistant.adapter.stub.001.md
│   ├── oscar.assistant.adapter.anthropic.001.md
│   ├── oscar.assistant.adapter.openai.001.md
│   ├── oscar.assistant.adapter.local.001.md
│   ├── oscar.assistant.provider.arboriculture.001.md
│   ├── oscar.assistant.heuristics.library.001.md
│   ├── oscar.assistant.memory.module.001.md
│   ├── oscar.assistant.actions.chips.001.md
│   ├── oscar.assistant.web-search.opt-in.001.md
│   ├── oscar.brain.rules.classify-tree.001.md
│   ├── oscar.brain.rules.check-compliance.001.md
│   ├── oscar.brain.orchestrator.dispatcher.001.md
│   ├── oscar.brain.cached-standards.library.001.md
│   ├── oscar.brain.manifest.qwen-stub.001.md  # declared as STUB until §15 amendment
│   ├── oscar.brain.chunk-loader.discovery.001.md
│   ├── oscar.brain.post-processor.cleanup.001.md
│   ├── oscar.writing.draft.full-post.001.md
│   ├── oscar.writing.draft.outline.001.md
│   ├── oscar.writing.draft.section.001.md
│   ├── oscar.writing.rewrite.tone.001.md
│   ├── oscar.writing.auxiliary.title-tags-summary.001.md
│   ├── oscar.intelligence.standards.bs5837.001.md
│   ├── oscar.intelligence.standards.bs3998.001.md
│   ├── oscar.intelligence.standards.bs8545.001.md
│   ├── oscar.intelligence.standards.aia.001.md
│   ├── oscar.intelligence.standards.ams.001.md
│   ├── oscar.intelligence.standards.arb.001.md
│   ├── oscar.data.persistence.idb.001.md         # IDB schema declaration
│   ├── oscar.data.persistence.local-storage.001.md
│   ├── oscar.data.models.tree.001.md
│   ├── oscar.data.models.site.001.md
│   ├── oscar.data.models.survey.001.md
│   ├── oscar.data.models.note.001.md
│   ├── oscar.data.models.report.001.md
│   ├── oscar.data.models.blog-post.001.md
│   ├── oscar.data.repo.repository-pattern.001.md
│   ├── oscar.shell.topbar.001.md
│   ├── oscar.shell.dock.5-chip.001.md
│   ├── oscar.shell.shell-frame.001.md
│   ├── oscar.views.home.001.md
│   ├── oscar.views.surveys.001.md
│   ├── oscar.views.notes.001.md
│   ├── oscar.views.reports.001.md
│   ├── oscar.views.settings.001.md
│   ├── oscar.views.blog.001.md
│   ├── oscar.ux.empty-state.001.md
│   ├── oscar.ux.completeness-meter.001.md
│   ├── oscar.ux.undo-toast.001.md
│   ├── oscar.ux.help-tooltip.001.md
│   ├── oscar.ux.plain-language-label.001.md
│   ├── oscar.ux.standards-library.001.md
│   ├── oscar.export.pdf.001.md
│   ├── oscar.export.docx.001.md
│   ├── oscar.search.cmd-k.001.md
│   ├── oscar.onboarding.5-step.001.md
│   └── oscar.branding.palette.001.md
├── recipes/                           # NEW CONTENT: per-module Recipe Books (§11)
│   ├── assistant/
│   │   ├── recipe.md                  # §11.1: A. Product, B. Structural Contract, C. Reconstruction Notes
│   │   ├── codex.md                   # §11.1 + §22: behaviour (or symlink to codex/assistant.codex.md)
│   │   ├── rules.md                   # §11.9: 9 universal workflow things
│   │   ├── module-meta.json           # §11.2: identity, category, gallery linkage
│   │   ├── ingredients.json           # §11.2: provenance scaffolding
│   │   ├── diffs/                     # §11.2: version diffs
│   │   ├── trace-atlas/               # §11.2: lineage, forks, shadows
│   │   ├── dna/                       # §11.2: DNA artefacts
│   │   ├── plan.md                    # §11.9: atomic steps
│   │   └── coverage-matrix.md         # §11.9: verification grid
│   ├── brain/                         # (same 10 items)
│   ├── writing/                       # (same 10 items)
│   ├── intelligence/                  # (same 10 items)
│   ├── data/                          # (same 10 items)
│   ├── views/                         # (same 10 items)
│   ├── shell/                         # (same 10 items)
│   ├── ux/                            # (same 10 items)
│   ├── export/                        # (same 10 items)
│   ├── search/                        # (same 10 items)
│   ├── onboarding/                    # (same 10 items)
│   └── branding/                      # (same 10 items)
├── dna/
│   └── app.dna.json                   # §03: app_id, version, lineage, supersedes, recipe_id, invariants
├── trace-atlas/
│   └── atlas.json                     # §04: 5-level chain (UI surface → behaviour → module → file → test)
├── overlays/                          # §01: customisation layers
│   ├── README.md                      # explains what overlays are (theme variants, brand variants)
│   └── dark-green-palette.overlay.md  # current default
├── vp/                                # §01: validity + protection tests (renamed from pact/audit/)
│   ├── sovereignty.test.ts            # was pact/audit/sovereignty-checks.test.ts
│   ├── runtime.test.ts                # was pact/audit/runtime-checks.test.ts
│   ├── intelligence.test.ts           # was pact/audit/intelligence-checks.test.ts
│   ├── data.test.ts                   # was pact/audit/data-checks.test.ts
│   ├── ux.test.ts                     # was pact/audit/ux-checks.test.ts
│   ├── build.test.ts                  # was pact/audit/build-checks.test.ts
│   ├── adversarial.test.ts            # was pact/audit/adversarial-probes.test.ts
│   └── FVRE-GATE.md                   # was pact/audit/FVRE-GATE.md
├── decisions/                         # §11: decision log
│   ├── DO-001-reconstruction-mode.md  # declares Oscar as "Sovereign SPA Mode" (third mode)
│   ├── DO-002-micro-model-amendment.md # proposes §15 amendment to add "browser-loadable" tier
│   ├── DO-003-fragment-naming.md      # ratifies the oscar.* naming convention
│   ├── DO-004-idb-schema-v2.md        # ratifies the 6-store IDB schema
│   ├── DO-005-adapter-architecture.md # ratifies the 5-adapter + ArboricultureProvider architecture
│   ├── DO-006-sovereignty-grep.md     # ratifies the static grep checks
│   ├── DO-007-9-layer-dispatcher.md   # ratifies the 9-layer Smart adapter dispatcher
│   └── DO-008-4-part-response.md      # ratifies the claim+evidence+hedge+action format
└── audit/                             # KEEP for backwards compat (or remove after migration)
```

**Doctrinal note:** This restructure honors §02's 9-folder structure while preserving Oscar's audit directory. The `audit/` directory becomes `vp/` per FVW v8 naming. The `decisions/` directory is populated with retroactive decisions documenting the runtime's current state.

### A1.2 — Write the 4 missing pact/platform documents

**Pact-only. No runtime changes.**

1. **`pact/platform/app-pact.md`** — the main pact document. Declares:
   - Oscar's identity (`studio.oscar.platform`)
   - The 6 sovereignty principles (currently in sovereignty.md)
   - The reconstruction mode declaration (per §33) — **Sovereign SPA Mode** (third mode; see DO-001)
   - The brain model status — STUB until §15 amendment or fallback reframing
   - Cross-references to all fragment specs

2. **`pact/platform/invariants.md`** — invariants Oscar must always satisfy:
   - INV-1: zero `@fvs/*` imports
   - INV-2: zero `freshvibe-studio` imports
   - INV-3: zero `mantine` imports
   - INV-4: IDB schema compatibility (DB_VERSION = 2)
   - INV-5: localStorage prefix `oscar:`
   - INV-6: brand palette compliance (forest green primary)
   - INV-7: adapter provider ID = `oscar-arboriculture-provider`
   - INV-8: 5 adapters registered (stub, smart, anthropic, openai, local)
   - INV-9: 6 IDB stores (trees, sites, surveys, notes, reports, posts)
   - INV-10: 4-state dock (bar, sheet-min, sheet-full, peek)
   - INV-11: 4 canonical anchor types
   - INV-12: 14 Smart X features roadmap (3 shipped, 6 partial, 5 absent — see §16)

3. **`pact/platform/anti-drift.md`** — apply §08's 25 rules + 20 gates + 12 failure modes to Oscar:
   - Rule 1 (Verification-before-refactor): every phase extracts the existing structure first
   - Rule 2 (Safe Diff Protocol): micro-diffs, not wholesale rewrites
   - Rule 3 (No invention): no new components/modules/handlers/state without operator approval
   - Rule 4 (Explicit binary verification): every refactor step verified by App-VP test
   - Rule 5-25: ... (full §08 application)
   - Plus Oscar-specific rules: never import Mantine; never import FVS; never create non-`oscar.*` fragment_ids

4. **Update `pact/platform/README.md`** — frame the restructured pact; cross-reference to the 4 documents

### A1.3 — Declare the 50+ `oscar.*` fragment specs

**Pact-only. No runtime changes.**

Each fragment spec is a small markdown file in `pact/fragments/`. Each declares:
- `fragment_id`: the canonical `oscar.*` ID
- `domain`: PLATFORM | DATA | ASSISTANT | BRAIN | WRITING | UX | VIEW | SHELL
- `rule`: what the fragment declares (1-3 sentences)
- `source`: which runtime file implements it
- `bound_to_modules`: which modules consume it (per §35.5 future)
- `status`: SHIPPED | STUB | PLANNED
- `version`: `.001`, `.002`, etc.

This **delivers the declared-but-undelivered naming convention**. After A1.3, every `oscar.*` ID used in the codebase has a corresponding fragment spec.

### A1.4 — Register modules with `constitutional_fragments` (§35)

**Pact-only. No runtime changes.**

For every module, write a `module.json` file at the module root:

```json
// app/src/assistant/module.json
{
  "module_id": "oscar.assistant",
  "version": "0.2.0",
  "display_name": "Assistant",
  "constitutional_fragments": [
    "oscar.assistant.surface.sheet-min.001",
    "oscar.assistant.surface.sheet-full.001",
    "oscar.assistant.surface.bar.001",
    "oscar.assistant.surface.peek.001",
    "oscar.assistant.dock.4-state.001",
    "oscar.assistant.adapter.smart.001",
    "oscar.assistant.adapter.stub.001",
    "oscar.assistant.adapter.anthropic.001",
    "oscar.assistant.adapter.openai.001",
    "oscar.assistant.adapter.local.001",
    "oscar.assistant.provider.arboriculture.001",
    "oscar.assistant.heuristics.library.001",
    "oscar.assistant.memory.module.001",
    "oscar.assistant.actions.chips.001",
    "oscar.assistant.web-search.opt-in.001"
  ]
}
```

12 module.json files (one per module). Each declares its `constitutional_fragments`. After A1.4, Oscar is **Module-Pact Registered** per §35.

### A1.5 — Write per-module Recipe Books (§11)

**Pact-only. No runtime changes.**

For every module, write the 10-item Recipe Book in `pact/recipes/<module>/`:

- `recipe.md` (§11.1: A. Product, B. Structural Contract, C. Reconstruction Notes)
- `codex.md` (§11.1 + §22: behaviour; can reference `pact/codex/<module>.codex.md`)
- `rules.md` (§11.9: 9 universal workflow things)
- `module-meta.json` (§11.2: identity, category, gallery linkage)
- `ingredients.json` (§11.2: provenance scaffolding)
- `diffs/` (§11.2: version diffs, empty initially)
- `trace-atlas/` (§11.2: lineage, forks, shadows, empty initially)
- `dna/` (§11.2: DNA artefacts, empty initially)
- `plan.md` (§11.9: atomic steps)
- `coverage-matrix.md` (§11.9: verification grid)

**12 Recipe Books × 10 items = 120 files**. Each is small (most under 100 lines). The Recipe Books are the **portable deliverable** per §01.

### A1.6 — Write the DNA (§03)

**Pact-only. No runtime changes.**

`pact/dna/app.dna.json`:

```json
{
  "schema": "freshvibe-way-v8.app-dna",
  "schema_version": "1.0.0",
  "app_id": "studio.oscar.platform",
  "version": "1.0.0",
  "lineage": [
    "avidtech6/oscar-ai (R1-R18, original Oscar website conversion)",
    "studio.oscar.platform (Phase 1-10 sovereign SPA pivot, 2026-06)"
  ],
  "supersedes": "avidtech6/oscar-ai/R18 (the original Oscar website)",
  "recipe_id": "studio.oscar.platform.recipe.v1",
  "invariants_ref": "pact/platform/invariants.md",
  "doctrinal_extensions": {
    "reconstruction_mode": "Sovereign SPA Mode (third mode, see DO-001)",
    "micro_model_status": "STUB — 500M param model exceeds §15.3 ceiling; deferred to DO-002 amendment"
  }
}
```

### A1.7 — Write the Trace Atlas (§04)

**Pact-only. No runtime changes.**

`pact/trace-atlas/atlas.json`:

```json
{
  "schema": "freshvibe-way-v8.trace-atlas",
  "schema_version": "1.0.0",
  "app_id": "studio.oscar.platform",
  "app_version": "1.0.0",
  "surfaces": {
    "home": {
      "id": "home",
      "name": "Home",
      "file": "app/src/views/Home.tsx",
      "behaviours": ["render-anchors", "navigate-via-anchor"]
    },
    "surveys": {
      "id": "surveys",
      "name": "Surveys",
      "file": "app/src/views/Surveys.tsx",
      "behaviours": ["list-surveys", "create-survey", "edit-survey", "delete-survey", "load-survey-data"]
    },
    "notes": { ... },
    "reports": { ... },
    "settings": { ... },
    "blog": { ... },
    "assistant-dock": { ... },
    "smart-adapter": { ... }
  },
  "behaviours": { ... },
  "modules": { ... },
  "files": { ... },
  "tests": { ... }
}
```

Each behaviour links to its module(s), each module links to its file(s), each file links to its test(s). This is the **5-level chain** per §04.

### A1.8 — Populate `pact/decisions/`

**Pact-only. No runtime changes.**

8 decision logs documenting the runtime's current state:
- DO-001: Reconstruction Mode is "Sovereign SPA Mode" (third mode)
- DO-002: Propose §15 amendment to add "browser-loadable model" tier (100k-1B params)
- DO-003: Ratify `oscar.*` naming convention
- DO-004: Ratify IDB schema v2 (6 stores)
- DO-005: Ratify 5-adapter architecture + ArboricultureProvider
- DO-006: Ratify static grep sovereignty checks
- DO-007: Ratify 9-layer Smart adapter dispatcher
- DO-008: Ratify 4-part response format

### A1.9 Phase A1 Outcome

After A1, Oscar has **6 of 8 mandatory artefacts in canonical form**:
- ✅ `pact/platform/` (4 documents: app-pact.md, invariants.md, anti-drift.md, sovereignty.md)
- ❌ `pact/codex/` (still empty — codex work happens in A2)
- ✅ `pact/fragments/` (50+ declared fragment specs)
- ✅ `pact/dna/app.dna.json`
- ✅ `pact/trace-atlas/atlas.json`
- ⚠️ `pact/overlays/` (1 file — minimal but present)
- ✅ `pact/vp/` (renamed from audit; 58 invariants preserved)
- ❌ `pact/recipes/` (still empty — Recipe Books happen in A2/A3)

Per-module `module.json` files are in place. Oscar is **Module-Pact Registered** per §35.

---

## XVII. PHASE A2 — RECIPE BOOKS + CODEX + C1-C8 (PACT-ONLY)

**Goal:** Write the Recipe Books and C1-C8 codex items for every module. Pure doctrine.

**Duration:** Pact-only. Substantial — 12 modules × C1-C8 + 10-item Recipe Book each.

### A2.1 — Write `pact/codex/` per-module codex files

**Pact-only. No runtime changes.**

For each of 12 modules, write a `codex.md` declaring C1-C8 per §22:

**C1 — Behaviour inventory**: every event handler, lifecycle hook, state transition, side effect enumerated with source line citations.

**C2 — State machine with transitions**: e.g., AssistantDock: `bar → sheet-min → sheet-full → peek` and back. Each transition's pre/post conditions declared.

**C3 — Side effect list**: IDB writes, localStorage writes, DOM updates, network calls. Each side effect typed and audited.

**C4 — Input validation contract**: what the module accepts (typed shapes, ranges), what it rejects (and how).

**C5 — Failure modes**: what happens when IDB write fails, when provider errors, when LLM times out. Each failure declared.

**C6 — User simulation list**: 5-10 representative user flows per module. E.g., "user says 'classify a 15m oak' → Smart adapter Layer 4 fires → formatAnswer returns claim+evidence+hedge+action → AssistantDock renders bubble."

**C7 — Reproducibility test**: a single deterministic test that proves the module produces the same output for the same input. E.g., "give heuristic.whoAreYou 'who are you' → returns deterministic answer with hash X."

**C8 — Shape matrix** (per §30): per-surface × per-mode × per-chip × per-state.

This is **substantial doctrine work** — for a 12-module app, ~5,000 lines of codex content. Each module gets its own codex file at `pact/codex/<module>.codex.md`.

### A2.2 — Populate `pact/recipes/<module>/` 10-item Recipe Books

**Pact-only. No runtime changes.**

For each of 12 modules, write the 10-item Recipe Book per §11:

- **`recipe.md`** — A. Product Description (UI, layout, structure); B. Structural Contract (interfaces, boundaries, swap tests); C. Reconstruction Notes (evidence, coverage)
- **`codex.md`** — reference to `pact/codex/<module>.codex.md` (or inline copy)
- **`rules.md`** — 9 universal workflow things: capability declaration, do-not-proceed rule, anti-drift checks, plan-as-law, fallback behaviour, user-simulator requirement, re-anchor cadence, anti-momentum rule, coverage matrix instructions
- **`module-meta.json`** — module identity, category, gallery linkage, version, lineage
- **`ingredients.json`** — provenance scaffolding: who made it, what it depends on, what tracks it
- **`diffs/`** — version diffs (initially empty; populated when module is updated)
- **`trace-atlas/`** — per-module trace atlas subset (which behaviours the module owns, which surfaces trigger them, which tests verify them)
- **`dna/`** — per-module DNA subset (module identity, lineage, supersedes)
- **`plan.md`** — atomic implementation steps
- **`coverage-matrix.md`** — verification grid (which tests verify which behaviours)

### A2.3 Phase A2 Outcome

After A2, Oscar has **8 of 8 mandatory artefacts in canonical form**:
- ✅ `pact/platform/` (4 documents)
- ✅ `pact/codex/` (12 codex files with C1-C8)
- ✅ `pact/fragments/` (50+ specs)
- ✅ `pact/dna/app.dna.json`
- ✅ `pact/trace-atlas/atlas.json`
- ✅ `pact/overlays/`
- ✅ `pact/vp/` (58 invariants)
- ✅ `pact/recipes/` (12 Recipe Books × 10 items = 120 files)

**Oscar is now structurally FreshVibe-compatible per §01.**

Per §00: a Recipe exists (`pact/recipes/`). Given the Recipe + FVW v8 doctrine, Oscar can be **engine-agnostically described**. The implementation is engine-specific (React + TS + Vite) but the contract is portable.

---

## XVIII. PHASE B1 — §15 + §33 DOCTRINAL CORRECTIONS (DOCTRINAL GROWTH)

**Goal:** Fix the two constitutional tensions. Propose amendments to FVW v8, not just Oscar.

**Duration:** Doctrinal work. No code. Substantive RFC work.

### B1.1 — Propose §15 amendment: browser-loadable model tier

**Pact-only. No runtime changes.**

The current §15.3 declares micro-models MUST be 100k–2M parameters. Qwen 0.5B (500M params) exceeds this by 250×.

**Proposed amendment (§15.3-bis — new tier):**

Add a "browser-loadable model" tier between micro-model and cloud LLM:

| Tier | Parameters | Runtime |
|---|---|---|
| Tiny micro-model | 100k-300k | WASM, WebGPU, ONNX |
| Small micro-model | 300k-600k | WASM, WebGPU, ONNX, llama.cpp |
| Medium micro-model | 600k-1M | WASM, WebGPU, llama.cpp, Transformers.js |
| **Browser-loadable model** (NEW) | **1M-1B** | **WASM, WebGPU, llama.cpp, Transformers.js, ggml/GGUF** |
| Cloud LLM | 1B+ | server-required |

**Rationale:** the constitutional 2M ceiling was set in v6 (2026-06-13) before the Qwen 0.5B / Llama 3.2 / Phi-3 era. Models in the 100M-1B range now run efficiently in browsers (WebGPU + llama.cpp + GGUF Q4_K_M). The ceiling is anachronistic.

**Oscar's brain status after amendment:** Level 5 (Browser-Loadable Model), not Level 5 (Embedded Micro-Model). Qwen 0.5B Q4_K_M fits.

**Decision needed:** operator must propose this amendment to `avidtech6/freshvibe-way-v8` upstream. Until ratified, Oscar's brain is constitutionally **STUB** (declared but cannot be constitutionally embedded).

**Decision log:** `pact/decisions/DO-002-micro-model-amendment.md` (written in A1.8) tracks this.

### B1.2 — Propose §33 amendment: third reconstruction mode

**Pact-only. No runtime changes.**

The current §33 declares only two reconstruction modes (App Mode + Studio Module Mode). Oscar is a **third mode** (Sovereign SPA Mode).

**Proposed amendment (§33.5 — new mode):**

Add a "Sovereign SPA Mode":

| Mode | Stack | Container | FVW Imports |
|---|---|---|---|
| App Mode | vanilla HTML/CSS/JS | standalone | none |
| Studio Module Mode | React 18 + TS + Mantine 7 + Vite | FVS Studio container | yes |
| **Sovereign SPA Mode** (NEW) | **React 18 + TS + Vite (no Mantine)** | **standalone** | **none** |

**Properties of Sovereign SPA Mode:**
- React framework, no Mantine (or similar UI lib)
- TypeScript strict mode
- Vite build
- Standalone deployment (CF Pages, Vercel, etc.)
- Zero FVS / FreshVibe imports
- IDB persistence (browser-only)
- localStorage namespaced
- Sovereign brand, palette, typography

**Decision needed:** operator must propose this amendment upstream. Until ratified, Oscar's reconstruction mode is officially undefined per §33.

**Decision log:** `pact/decisions/DO-001-reconstruction-mode.md` (written in A1.8) tracks this.

### B1.3 Phase B1 Outcome

After B1:
- Oscar's brain status is constitutionally clean (browser-loadable model tier, when ratified)
- Oscar's reconstruction mode is constitutionally declared (Sovereign SPA Mode, when ratified)
- Both amendments are upstream proposals; if rejected, Oscar's `app-pact.md` and `DO-001`/`DO-002` document the local workaround

---

## XIX. PHASE B2 — RECONSTRUCTABILITY DEMONSTRATION (PACT + RUNTIME)

**Goal:** Demonstrate that Oscar can be regenerated from its Recipe. This is the §00 Reconstructability Invariant test.

**Duration:** Both Pact and runtime. The runtime work is minimal (build verification). The Pact work is the Recipe Book itself (already done in A2).

### B2.1 — Write a `recipe.md` engine-agnostic rebuild guide

**Pact-only. No runtime changes.**

`pact/recipes/recipe.md` (the workspace-level recipe, distinct from per-module recipes):

```markdown
# Oscar Platform — Workspace Recipe

## Engine-agnostic truth (per §34)

This recipe describes Oscar in language that does not commit to a specific runtime. The implementation that satisfies this recipe is engine-specific (Sovereign SPA Mode: React 18 + TS + Vite).

## What Oscar is

A sovereign arboriculture SPA with an embedded AI assistant. The app supports surveys, notes, reports, blog writing, and an assistant that classifies trees, drafts reports, and answers questions about UK arboriculture standards.

## Modules (per §11)

12 modules, each with its own Recipe Book at `pact/recipes/<module>/`:
- assistant: AI assistant dock, 9-layer Smart adapter dispatcher
- brain: rule engine, cached standards, brain manifest
- writing: AI-assisted blog writing
- intelligence: 5 LLM adapters + 6 cached standards + ArboricultureProvider
- data: IDB persistence + 6 typed models + Repository pattern
- views: 6 views (Home, Surveys, Notes, Reports, Settings, Blog)
- shell: OscarShell, TopBar, 5-chip Dock
- ux: 6 UX components (EmptyState, CompletenessMeter, UndoToast, HelpTooltip, PlainLanguageLabel, StandardsLibrary)
- export: PDF + DOCX export pipelines
- search: Cmd+K global search (7 kinds)
- onboarding: 5-step tour
- branding: theme + palette (forest green)

## Reconstruction procedure

1. Read this recipe
2. Read `pact/platform/app-pact.md` for invariants
3. Read `pact/dna/app.dna.json` for identity and lineage
4. Read `pact/fragments/` for all declared fragment specs
5. Read `pact/codex/` for behaviour contracts (C1-C8)
6. Read `pact/recipes/<module>/` for per-module Recipe Books (10 items each)
7. Read `pact/trace-atlas/atlas.json` for the 5-level chain
8. Implement per the declared mode (Sovereign SPA Mode: React 18 + TS + Vite)
9. Run `pact/vp/` tests to verify (58 invariants)
10. Deploy to CF Pages
```

### B2.2 — Add a §00 verification script

**Pact + runtime. Minimal runtime change (a single build script).**

`pact/scripts/verify-reconstructability.sh` — a script that:
1. Reads the Recipe
2. Verifies every fragment spec exists in the source code
3. Verifies every module has a Recipe Book
4. Verifies every Recipe Book has 10 items
5. Verifies every codex has C1-C8
6. Runs the App-VP tests (58 invariants)
7. Builds the app
8. Reports PASS/FAIL

If PASS, Oscar satisfies §00.

### B2.3 Phase B2 Outcome

After B2, Oscar is **structurally FreshVibe-compatible per §00 Reconstructability Invariant**. A senior architect with the Recipe + FVW v8 doctrine could rebuild Oscar in another engine (e.g., Svelte, SolidJS) by following the Recipe.

---

## XX. PHASE C1 — PROJECT SPINE FOUNDATION (LATENT §37)

**Goal:** Add the Project Spine as a constitutional artefact. Latent doctrine, locally ratified in OSCR- (not yet FVW v8).

**Duration:** Pact + runtime. Substantial runtime change.

### C1.1 — Define the Project Spine in OSCR- (latent §37)

**Pact-only. No runtime changes.**

`pact/latent/section-37-project-spine.md` — local ratification of the latent §37 doctrine:

```markdown
# Section 37 — Project Spine (latent, locally ratified)

## 37.1 — Every Oscar workspace contains zero or more projects.

A project is a typed instance of a domain (tree, media, social, charity, home, admin).

## 37.2 — Project types are constitutional.

Initial taxonomy: `tree` (the only declared type initially).

## 37.3 — Every project has the universal artefact graph (§38).

In Oscar v1.0, the spine is the existing 6 artefact types: trees, sites, surveys, notes, reports, posts.
Future versions add voice, media, tasks, calendar, social (see latent §38).

## 37.4 — Projects are sovereign within Oscar.

Artefacts are private to a project. Cross-project movement requires explicit operator action.

## 37.5 — Project lifecycle is constitutional.

States: `draft → active → paused → archived → deleted`. Each transition auditable.
```

### C1.2 — Add the Project model to the data layer

**Runtime change. Substantial.**

- New model: `app/src/data/models/Project.ts`
- New IDB store: `projects` (DB_VERSION 2 → 3 migration)
- New repository: `projectsRepo`
- Modify all 6 existing models: each adds `project_id: string` (required, FK to projects)
- Migration v2 → v3: every existing artefact gets `project_id = "default"` (a system project)

### C1.3 — Add the Projects module

**Runtime change. New module.**

- `app/src/projects/` — CRUD, project switcher, project lifecycle
- `app/src/views/Projects.tsx` — projects dashboard view
- Dock chip: "Projects" (new chip, replacing or alongside Home)
- Header: project name + project type badge + project state badge

### C1.4 — Modify all existing views to scope to a project

**Runtime change. Touches every view.**

- `app/src/views/Surveys.tsx` — list scoped to current project; "create survey" creates with current `project_id`
- (same for Notes, Reports, Blog, Home)

### C1.5 Phase C1 Outcome

After C1:
- Oscar has the Project Spine (§37) locally ratified
- Every artefact belongs to a project
- The Projects dashboard exists as a first-class view
- Every existing view is project-scoped

---

## XXI. PHASE C2 — UNIVERSAL ARTEFACT GRAPH (LATENT §38)

**Goal:** Extend the artefact graph from 6 to 9 types. Add voice, media, calendar. Defer tasks, social to C4.

**Duration:** Pact + runtime. Substantial.

### C2.1 — Add Voice artefact type

**Runtime change.**

- `app/src/data/models/Voice.ts` — typed model (audio_blob, raw_transcript, edited_transcript, duration, version_history)
- New IDB store: `voices`
- `voicesRepo`
- `app/src/voice/` — capture (MediaRecorder), storage, playback (HTML5 audio)
- `app/src/views/Voice.tsx` — voice artefact view
- Dock chip: "Voice"

### C2.2 — Add Media artefact type

**Runtime change.**

- `app/src/data/models/Media.ts` — typed model (image_blob, drawing_data, type: photo|drawing|map_layer)
- New IDB store: `media`
- `mediaRepo`
- `app/src/media/` — capture (file input or camera), storage, display
- `app/src/views/Media.tsx` — media gallery view
- Dock chip: "Media"

### C2.3 — Add Calendar artefact type

**Runtime change.**

- `app/src/data/models/Calendar.ts` — typed model (event_type, date, recurrence, project_id, linked_artefacts)
- New IDB store: `events`
- `eventsRepo`
- `app/src/calendar/` — calendar view (month/week/agenda), event CRUD
- `app/src/views/Calendar.tsx` — calendar dashboard
- Dock chip: "Calendar"

### C2.4 Phase C2 Outcome

After C2:
- Oscar has 9 of 9 universal artefacts (notes, trees, surveys, reports, posts, voice, media, calendar)
- 1 deferred: tasks (added in C3), social (added in C4)
- 3 new views (Voice, Media, Calendar)

---

## XXII. PHASE C3 — ARTEFACT TOPOLOGY (LATENT §39)

**Goal:** Add the topology layer. Tagging, linking, versioning, playback. Replaces the implicit `tags` fields in Notes and BlogPost with a constitutional topology.

**Duration:** Pact + runtime. Substantial.

### C3.1 — Add the topology data model

**Runtime change.**

- `app/src/data/models/Tag.ts` — typed model (id, label, scope: artefact|project|global, parent_tag_id)
- `app/src/data/models/Link.ts` — typed model (id, source_id, target_id, link_type, created_at)
- `app/src/data/models/Version.ts` — typed model (artefact_id, version_number, snapshot, created_at, created_by)
- New IDB stores: `tags`, `links`, `versions` (DB_VERSION 3 → 4 migration)

### C3.2 — Add the topology module

**Runtime change.**

- `app/src/topology/` — tag CRUD, link CRUD, version CRUD, playback (read-only history view)
- Add `project_id` to all topology models

### C3.3 — Apply topology to all 9 artefacts

**Runtime change. Touches every artefact type.**

Every artefact model now supports:
- **tags**: typed references to `tags` store
- **links**: typed references to `links` store (bidirectional)
- **versions**: every save creates a new `Version` record; current version is a pointer
- **playback**: per-artefact history view

### C3.4 Phase C3 Outcome

After C3:
- Every artefact is tagged, linkable, versioned, playable
- Topology is constitutional (per latent §39)
- The "every save overwrites" gap is closed

---

## XXIII. PHASE C4 — MULTIMODAL CAPTURE (LATENT §40)

**Goal:** Add voice, photo, GPS, measurement modalities to the assistant input box.

**Duration:** Pact + runtime. Substantial.

### C4.1 — Multimodal capture UI in AssistantDock

**Runtime change.**

- Modify `app/src/assistant/AssistantDock.tsx`:
  - Add voice button (microphone icon → toggles voice capture mode)
  - Add photo button (camera icon → opens file picker / camera)
  - Add GPS button (pin icon → grabs current location via geolocation API)
  - Existing text input remains
- The active modality is visible (icon highlighted)
- Switching modalities preserves the partial input

### C4.2 — Voice-to-AI live transcription

**Runtime change.**

- Use Web Speech API for real-time transcription
- Stream interim results into the input box as the user speaks
- Final transcript is sent to the assistant as a text prompt
- Operator can edit the transcript before sending

### C4.3 — Voice note recording mode

**Runtime change.**

- Per latent §41: 5-stage pipeline (audio → raw_transcript → edited_transcript → version_history → final_artefact)
- After capture: assistant confirmation flow ("Voice note recorded and tagged for X — is that correct?")
- Waveform rendering (Canvas + AudioBuffer)

### C4.4 — Photo capture

**Runtime change.**

- File input + camera capture
- Photo stored as Media artefact
- EXIF metadata extracted (GPS, timestamp, camera)
- Photo can be attached to a tree, survey, report, or kept as a standalone artefact

### C4.5 — GPS capture

**Runtime change.**

- Geolocation API for current location
- Stored as Location artefact (lat, lng, accuracy, timestamp, project_id)
- Can be attached to any artefact
- Used by the map module (Phase C5)

### C4.6 — Measurement capture

**Runtime change.**

- Already partially present (typed inputs for tree height, girth)
- Extend to: voice-dictated measurements ("twelve metres"), photo-with-ruler overlay, laser-distance integration (future)

### C4.7 Phase C4 Outcome

After C4:
- 5 of 5 multimodal capture modalities shipped
- The assistant accepts voice, photo, GPS, measurement, text
- Voice-to-AI live transcription works
- Voice notes have waveforms + confirmation flow

---

## XXIV. PHASE C5 — MAP MODULE (LATENT §43)

**Goal:** Add the spatial artefact. The single largest missing feature for arboriculture.

**Duration:** Pact + runtime. Very substantial.

### C5.1 — Map data model

**Runtime change.**

- `app/src/data/models/Map.ts` — typed model (project_id, base_layer: satellite|street|terrain, viewport, drawing_layers, coordinate_system)
- `app/src/data/models/MapLayer.ts` — typed model (map_id, geometry_type: point|line|polygon, colour, label_field, features)
- `app/src/data/models/MapFeature.ts` — typed model (layer_id, geometry, properties)
- New IDB stores: `maps`, `map_layers`, `map_features` (DB_VERSION 4 → 5)

### C5.2 — Map module

**Runtime change.**

- `app/src/map/` — MapView component (Leaflet or Mapbox GL), drawing tools, layer manager
- `app/src/views/Map.tsx` — map dashboard
- Dock chip: "Map"
- Coordinate system default: OS Grid (UK arboriculture)
- Other systems supported: WGS84 (lat/lng), UTM

### C5.3 — Drawing layers

**Runtime change.**

- **Trees layer**: point features (linked to Tree artefacts via tree_id)
- **RPAs layer**: polygon features (drawn per-tree, linked to Tree via tree_id)
- **Constraints layer**: polygon features (no-go zones, easements — drawn freely)
- **Annotations layer**: point/line features (text annotations pinned to coordinates)
- Multiple layers per project

### C5.4 — Tree ↔ Map integration

**Runtime change.**

- Every Tree artefact can be linked to a map feature
- The Map view shows trees at their coordinates
- Clicking a tree on the map opens the Tree detail
- The Tree detail shows the tree on the map (mini-map)

### C5.5 Phase C5 Outcome

After C5:
- The map module is shipped
- Trees can be located on maps
- RPAs can be drawn
- Annotations can be pinned
- The map is a first-class artefact type

---

## XXV. PHASE C6 — STYLE LEARNING (LATENT §42)

**Goal:** Automatic style extraction from PDFs. Style-aware report drafting.

**Duration:** Pact + runtime. Substantial.

### C6.1 — Style profile data model

**Runtime change.**

- `app/src/data/models/StyleProfile.ts` — typed model (project_id, tone, vocabulary, sentence_length, structure, exemplars)
- New IDB store: `style_profiles` (DB_VERSION 5 → 6)

### C6.2 — PDF ingestion

**Runtime change.**

- `app/src/style/` — PDF upload (file input), PDF text extraction (pdf.js), style analysis
- Analysis produces a StyleProfile candidate (operator can review and adjust)
- Multiple StyleProfiles per project

### C6.3 — Style-aware drafting

**Runtime change.**

- Modify `app/src/writing/draft.ts`:
  - Add `styleProfileId` parameter to `draftFullPost`, `draftOutline`, `draftSection`
  - When set, the prompt includes the profile's tone/vocabulary/structure guidance
- Modify `app/src/views/Reports.tsx`:
  - When generating a report from a survey, use the project's active StyleProfile

### C6.4 Phase C6 Outcome

After C6:
- Style profiles are typed artefacts
- PDFs can be ingested to create profiles
- Drafting uses the active style profile
- Reports are style-aware

---

## XXVI. PHASE C7 — COMMS MODULE (LATENT §44)

**Goal:** Add the comms artefact. **This phase requires a doctrinal amendment to Oscar's sovereignty invariant** (browser-only → browser + comms backend exception).

**Duration:** Pact + runtime. Major. **Doctrinal gate required.**

### C7.1 — Doctrinal gate: sovereignty exception for comms

**Pact-only. Operator decision required.**

The current sovereignty invariant (sovereignty.md §1) declares: "Oscar is browser-only, no backend." Latent §44 requires backend services for email/social.

**Two options:**

**Option A — Strict sovereignty (no comms):**
- Oscar remains browser-only
- Comms is not implemented
- Latent §44 remains unratified in Oscar

**Option B — Comms exception (recommended):**
- Amend sovereignty.md to add: "Comms (§44) is the constitutional exception. Email and social posting use dedicated backend services. These services are minimal, dedicated to comms, and operator-controlled."
- Implement comms with the exception

**Decision needed:** operator must choose. Until chosen, C7 is gated.

### C7.2 — Comms data model (Option B)

**Runtime change.**

- `app/src/data/models/Email.ts` — typed model (from, to, cc, bcc, subject, body, attachments, status, thread_id, project_id)
- `app/src/data/models/SocialPost.ts` — typed model (platform, account_id, body, attachments, status, thread_id, project_id)
- `app/src/data/models/Message.ts` — typed model (channel, from, body, attachments, status, thread_id, project_id)
- New IDB stores: `emails`, `social_posts`, `messages` (DB_VERSION 6 → 7)

### C7.3 — Comms module

**Runtime change.**

- `app/src/comms/` — email send/receive, social posting, message threading
- `app/src/views/Comms.tsx` — comms inbox (per-project)
- Dock chip: "Comms"

### C7.4 — Backend service for comms

**Runtime + infrastructure change.**

- Dedicated Cloudflare Worker for comms (CF Workers allowed under comms exception)
- SMTP integration for email
- OAuth integration for social (Twitter, LinkedIn, etc.)
- Credentials stored encrypted (operator-managed)

### C7.5 Phase C7 Outcome

After C7 (Option B):
- Comms module shipped
- Email + social + messaging available
- Oscar has a backend exception for comms only
- Sovereignty invariant amended

---

## XXVII. PHASE C8 — OPERATOR WORKFLOWS (LATENT §45)

**Goal:** Add pre-built workflows for common scenarios.

**Duration:** Pact + runtime. Substantial.

### C8.1 — Workflow data model

**Runtime change.**

- `app/src/data/models/Workflow.ts` — typed model (name, steps, pre/post conditions, progress_indicator, project_id)
- New IDB store: `workflows` (DB_VERSION 7 → 8)

### C8.2 — Workflow module

**Runtime change.**

- `app/src/workflows/` — workflow runner, step state machine, progress UI
- Workflows are declarative (data, not code)
- Runner is generic; workflows are instances

### C8.3 — Pre-built surveyor workflow

**Runtime change.**

- **Surveyor workflow**: create project → enter trees on map → classify each tree → generate report from survey → style with profile → export PDF → archive
- 7 steps, each auditable
- Progress indicator on the workflow runner

### C8.4 — Pre-built writer workflow

**Runtime change.**

- **Writer workflow**: create post → draft with AI → edit → save → publish → share
- 6 steps, each auditable

### C8.5 Phase C8 Outcome

After C8:
- Workflows are typed artefacts
- Surveyor + writer workflows pre-built
- Generic workflow runner executes declarative workflows

---

## XXVIII. PHASE C9 — MULTI-DOMAIN (LATENT §37.2 EXTENSION)

**Goal:** Extend the project type taxonomy beyond `tree`. Add media, social, charity, home, admin project types.

**Duration:** Pact + runtime. Very substantial. **The most architecturally significant phase.**

### C9.1 — Multi-domain pact declaration

**Pact-only.**

Amend `pact/latent/section-37-project-spine.md`:
- Project type taxonomy: `tree | media | social | charity | home | admin | (extensible)`
- Per-type feature packs: each project type has its own assistant heuristics, brain rules, and UI affordances

### C9.2 — Type-aware brain rules

**Runtime change.**

- Modify `app/src/brain/rules/classify-tree.ts` and `check-compliance.ts`:
  - Rules are now typed by project type
  - Only `tree` project types use the existing rules
  - Other project types have stub rule sets (to be filled in later phases)

### C9.3 — Type-aware assistant heuristics

**Runtime change.**

- Modify `app/src/assistant/heuristics.ts`:
  - Heuristics are scoped by project type
  - `tree` heuristics remain; new project types get stub heuristic sets

### C9.4 — Type-aware UI

**Runtime change.**

- Add project type selection when creating a project
- Each type has its own default view set
- Tree types see Surveys/Notes/Reports/Blog; Media types see Media/Voice/Calendar; etc.

### C9.5 Phase C9 Outcome

After C9:
- 6 project types supported (tree + 5 stubs)
- Per-type feature packs exist (tree is full; others are skeleton)
- Oscar is multi-domain-capable (substance), though only tree is fully implemented initially

---

## XXIX. PHASE C10 — FRESHCARDS SUBSTRATE (FWV v8 §23)

**Goal:** Apply FreshCards as a first-class substrate. Convert views to FreshCards.

**Duration:** Pact + runtime. Substantial.

### C10.1 — FreshCards substrate declaration

**Pact-only.**

`pact/freshcards/` directory declares:
- FreshCards as a substrate (per §23)
- Per-card type declaration (Tree, Note, Report, Post, Voice, Media, etc.)
- Card 4-views: front, back, summary, action

### C10.2 — Convert views to FreshCards

**Runtime change.**

- Modify every view to use `<FreshCard>` component
- Each FreshCard has 4 views: front (default), back (detail), summary (collapsed), action (action chip)
- Cards are draggable, sortable, dockable

### C10.3 — ADHD-friendly affordances

**Runtime change.**

- UndoToast (in UX, was unwired) → wired in every save flow
- One-thing-at-a-time mode: dim non-focused elements
- Quick wins: every action yields visible feedback within 200ms
- Generous whitespace: spacing tokens standardized

### C10.4 Phase C10 Outcome

After C10:
- FreshCards substrate applied
- Every view is a FreshCard
- ADHD-friendly affordances wired

---

## XXX. PHASE TIMELINE — DOCTRINAL EXECUTION ORDER

The phases are sequenced so each phase produces a **shippable artefact**:

| Phase | Doctrinal Scope | Pact / Runtime | Duration Estimate | Shippable Artefact |
|---|---|---|---|---|
| **A1** | FVW v8 §02 layout + §35 module-pact | Pact-only | ~3 days | Restructured Pact, 50+ fragments, 12 module.json, DNA, atlas |
| **A2** | §11 Recipe Books + §22 C1-C8 codex | Pact-only | ~5 days | 12 Recipe Books × 10 items, 12 codex files |
| **B1** | §15 + §33 amendments (upstream RFCs) | Pact-only | ~2 days | DO-001, DO-002 proposals |
| **B2** | §00 reconstructability demonstration | Pact + minimal runtime | ~2 days | Reconstructability script |
| **C1** | §37 Project Spine | Pact + runtime | ~5 days | Projects view, project-scoped artefacts |
| **C2** | §38 Universal Artefact Graph (voice + media + calendar) | Pact + runtime | ~8 days | 3 new artefact types, 3 new views |
| **C3** | §39 Artefact Topology (tags, links, versions, playback) | Pact + runtime | ~6 days | Topology module, versioning on every artefact |
| **C4** | §40 Multimodal Capture | Pact + runtime | ~5 days | Voice/photo/GPS/measurement in AssistantDock |
| **C5** | §43 Map Module | Pact + runtime | ~10 days | Map view, drawing layers, tree ↔ map integration |
| **C6** | §42 Style Learning | Pact + runtime | ~4 days | PDF ingestion, style profiles, style-aware drafting |
| **C7** | §44 Comms Module (gated on sovereignty amendment) | Pact + runtime | ~8 days | Comms view, email/social/messaging, comms backend |
| **C8** | §45 Operator Workflows | Pact + runtime | ~4 days | Workflow runner, surveyor + writer workflows |
| **C9** | §37.2 Multi-domain extension | Pact + runtime | ~6 days | 5 new project type stubs |
| **C10** | §23 FreshCards substrate + ADHD affordances | Pact + runtime | ~5 days | FreshCard substrate, every view is a card |

**Total estimated duration: ~75 days of focused work** (~15 weeks at 1 person-week = 5 days).

**Total Pact-only work: ~12 days** (A1, A2, B1).
**Total runtime work: ~63 days** (C1-C10, B2).

---

## XXXI. PHASE DEPENDENCIES

```
A1 (restructure) ─┬─ A2 (Recipe Books + codex)
                 │
B1 (§15/§33 RFCs) ┤  (parallel to A1/A2; no dependency)
                 │
B2 (reconstruct) ─┴─ requires A1 + A2
                       │
                       ├─ C1 (Project Spine) ─┬─ C2 (Universal Artefacts)
                       │                       ├─ C3 (Topology)
                       │                       ├─ C4 (Multimodal)
                       │                       ├─ C5 (Map)
                       │                       ├─ C6 (Style Learning)
                       │                       ├─ C7 (Comms — gated)
                       │                       ├─ C8 (Workflows)
                       │                       ├─ C9 (Multi-domain)
                       │                       └─ C10 (FreshCards)
                       │
                       └─ all C phases can run in parallel after C1
```

C1 must complete before C2-C10. C7 is gated on operator decision.

---

## XXXII. DOCTRINAL GUARANTEES

The plan guarantees:

1. **FWW v8 v0.10.0 structural alignment** is achieved after A2 (Phase A1+A2).
2. **§00 Reconstructability Invariant** is satisfied after B2.
3. **§15 + §33 doctrinal corrections** are proposed (upstream RFCs) in B1.
4. **Latent §37-§45 doctrines** are locally ratified in OSCR- through C1-C10.
5. **Sovereignty is respected** throughout, except for C7 (comms) which is gated on operator decision.
6. **The runtime remains shippable** at every phase (each phase produces a deployable artefact).
7. **§08 anti-drift** is honored (every phase follows the micro-diff protocol; no wholesale rewrites).

---

## XXXIII. RISKS AND MITIGATIONS

| Risk | Mitigation |
|---|---|
| B1 amendments rejected upstream | Oscar's local ratification (DO-001, DO-002) is sufficient for sovereignty; the upstream ratification is a bonus |
| C1 (Project Spine) requires migration of every artefact | Migration is automatic: every existing artefact gets `project_id = "default"` |
| C5 (Map module) requires substantial UI work | Map can ship in skeleton form first (display only, no drawing); full drawing in C5.5 |
| C7 (Comms) requires backend | Backend is opt-in (operator decision); without operator approval, C7 is skipped |
| Multi-phase plan overruns | Each phase is independently shippable; can pause at any phase boundary |

---

## XXXIV. WHAT THIS PLAN DOES NOT DO

This plan does not:
- Replace the runtime (the runtime is sound)
- Rewrite modules (every change is additive or micro-diff)
- Force a single-mode choice (Sovereign SPA Mode is declared but the runtime doesn't change mode)
- Implement latent §37-§45 doctrines in FVW v8 upstream (these are OSCR- local ratifications; upstream ratification is a separate proposal)

This plan does:
- Restructure the Pact to canonical FVW v8 form
- Write 8 of 8 mandatory artefacts
- Register every module with `constitutional_fragments`
- Write C1-C8 codex for every module
- Write 10-item Recipe Books for every module
- Propose 2 amendments to FVW v8 upstream (§15 browser-loadable tier, §33 third mode)
- Demonstrate §00 Reconstructability
- Add 9 latent doctrinal extensions (locally ratified)

---

## XXXV. CLOSING POSITION

Oscar is a sovereign SPA with a working runtime. The runtime is more sophisticated than the Pact. The plan closes that gap by writing the 8 mandatory artefacts (Pact-only work, ~12 days), demonstrating Reconstructability (~2 days), and then adding the 9 latent doctrinal extensions (~60 days of runtime work, in parallel phases).

The deepest finding: **Oscar's brain manifest claims Qwen 0.5B as an embedded micro-model, but §15.3's constitutional ceiling is 2M parameters. Oscar is 250× over.** This must be resolved (via §15 amendment or reframing) before the brain can ship constitutionally.

The second deepest finding: **the README declares a `pact/fragments/` directory and a `pact/recipes/` directory, but both are empty in the filesystem.** Declared-but-undelivered doctrine is the most damaging kind of gap — it claims structure the runtime does not fulfill.

The third deepest finding: **§33 declares only two reconstruction modes (App Mode and Studio Module Mode). Oscar is a third mode.** Until §33 is amended or Oscar declares its mode locally, Oscar's reconstruction status is officially undefined.

The plan addresses all three findings explicitly: B1 proposes the amendments, A1 delivers the declared directories, B2 demonstrates Reconstructability.

The plan is **world-class** because it:
- Is grounded in canonical FVW v8 v0.10.0 doctrine (not stale memory)
- Treats the operator's scrap as latent doctrine, not feature requests
- Distinguishes Pact-only, runtime-only, and both-require work
- Phases for realistic execution (each phase shippable)
- Respects sovereignty throughout (with one explicit exception for comms)
- Maps to the canonical 8 mandatory artefacts + the latent §37-§45 doctrines
- Is good enough for a senior architect to adopt as-is

The runtime is sound. The Pact is thin. The capabilities are incomplete. The doctrine extension is coherent. The plan closes all three gaps in phased, shippable order.

---

*End of sovereign doctrinal audit + world-class doctrinal plan. Based on FVW v8 v0.10.0 (commit 29a8262, 2026-06-25). Considering all operator-surfaced refinements. No code, no low-level implementation details. The artifacts audited were not modified.*