novahiz 0.3.7 → 0.4.0

package/README.md

@@ -1,392 +1,400 @@
-# Novahiz: Agent Governance Toolkit
-
-> **Zero-dependency enforcement layer for AI coding agents** — classifies prompts, assigns execution roadmaps, blocks unsafe edits until the right skills are loaded, and persists decisions across sessions — all deterministically, without model calls.
-
-17 categories, 96 skills, 11 gate rules, 7 MCP providers — all deterministic, all local, all JSON.
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                                                                     │
-│    USER PROMPT  ──▶  CLASSIFIER  ──▶  GATE  ──▶  SAFE OUTPUT      │
-│                                                                     │
-│    "Fix the      3 categories    2 missing     Edit blocked        │
-│     auth bug"    detected         skills        until skills       │
-│                                   required      loaded             │
-│                                                                     │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## How a session runs
-
-1. **Classify** — every prompt is scored against 17 categories (deterministic keyword matching, no model call). The result carries up to three categories, a primary one, a confidence, a **tier** (`trivial` / `lite` / `full`), and the skills the gate will expect.
-2. **Roadmap** — the primary category selects an ordered roadmap, and the plugin injects its checklist into the session: the agent walks plan → clarify → tasks → analyse → implement → converge instead of improvising an order.
-3. **Gate on every write** — `edit` / `write` / `patch` / `bash` / `shell` calls are checked against file class, active rules, roadmap skills and content (placeholder tokens): **allow** or **block**, locally, with no model call in the decision path.
-4. **Auto-repair, not a dead end** — a block names the exact missing skills and the retry rule: load each one, retry the same call once. A skill absent from the installed index is reported, never enforced. `NOVAHIZ_GATE=off` is the only escape hatch, and it is loud.
-5. **Verify and converge** — roadmaps end in `verify` steps that require proof; `novahiz-converge` grades the code against the original request and turns every remainder into a traceable ledger step.
-6. **Persist** — decisions, root causes and next steps survive the session through the memory layer (below), and `novahiz report` closes the loop with a session summary.
-
-```
- PROMPT ─▶ CLASSIFY ─▶ ROADMAP ─▶ work ─▶ GATE ─▶ allow ─▶ VERIFY ─▶ MEMORY
-               │                   ▲        │
-               └─ tier, skills ────│        └─ block: load named skills, retry once
-```
-
-**17 categories**, **96 skills**, **11 gate rules**, **7 MCP providers** — all deterministic, all local, all JSON.
-
----
-
-## Quick start
-
-### Option 1 — One-liner (recommended)
-
-```bash
-npm install -g novahiz
-novahiz-install --yes
-```
-
-`npm install -g novahiz` installs the CLI. On npm 11+, lifecycle scripts are gated behind an allow-scripts confirmation, so configuration is an explicit second step: `novahiz-install` asks which harnesses to configure (opencode and Claude Code when their config is present, Codex too; `--yes` accepts the detected defaults, `--harness claude` forces a list) — skills, plugin/agent, hooks, MCP servers, config. Then verify:
-
-```bash
-novahiz doctor   # health checks — 13 base, 17 with Claude Code, 19 with impeccable
-novahiz classify "fix the auth bug"
-```
-
-### Option 2 — From source
-
-```bash
-git clone https://github.com/novahiz/novahiz.git
-cd novahiz
-npm install            # `prepare` typechecks and builds dist/
-node ./install/install.mjs   # add --yes to accept the detected defaults
-
-# Verify
-node ./dist/cli.js doctor
-```
-
-> Requires **Node.js >= 22.18**. The installer auto-installs the CLI of each selected harness when it is entirely missing (`opencode-ai`, `@anthropic-ai/claude-code`, `@openai/codex`), non-blocking.
-
----
-
-## The Classifier
-
-Every user prompt passes through the classifier. It scores keywords against 17 categories and picks the top matches.
-
-```mermaid
-flowchart LR
-    A[User Prompt] --> B[Text Folding<br/>lowercase + strip accents]
-    B --> C{Keyword Scoring<br/>+1.0 per hit<br/>+1.5 multi-word bonus}
-    C --> D[Rank by Score + Priority]
-    D --> E[Top 3 Categories]
-    E --> F[Primary Category<br/>determines roadmap]
-    F --> G[Required Skills<br/>union of all categories]
-    F --> H[Enforced Skills<br/>primary only — gate blocks if missing]
-```
-
-**Example:**
-
-| Prompt | Top Category | Confidence | Skills Required |
-|--------|-------------|------------|-----------------|
-| "fix the auth bug" | `debug` | 0.60 | novahiz-plan, novahiz-analyse, novahiz-implement, novahiz-converge |
-| "add a landing page" | `design-ui` | 0.50 | novahiz-humanizer, ui-slop-remover |
-| "create supabase migration" | `database-supabase` | 0.60 | novahiz-supabase, novahiz-postgres, novahiz-plan, novahiz-implement |
-
----
-
-## The Gate
-
-The gate is the enforcement mechanism. It inspects every file edit and decides: **allow** or **block**.
-
-```mermaid
-flowchart TD
-    A[Tool Call: edit / write / patch] --> B[File Class Detection]
-    B --> C{Rule Matching}
-    
-    C --> D[R13: Design-ui prompt or style file?<br/>require humanizer + ui-slop + ui-craft]
-    C --> F[R3: Prompt was Supabase?<br/>require novahiz-supabase + postgres]
-    C --> G[R4: Prompt was browser?<br/>require novahiz-browser]
-    C --> H[R6: Workflow prompt?<br/>require plan/clarify/analyse/implement/converge]
-    
-    D --> I{Roadmap Enforcement}
-    F --> I
-    G --> I
-    H --> I
-    
-    I --> J{Placeholder Detection<br/>TODO / FIXME / placeholder tokens}
-    
-    J --> K["Check installed skills<br/>(missing → reported, not blocked)"]
-    J --> L["Check loaded skills<br/>(missing → BLOCKED)"]
-    
-    K --> M{All loaded?}
-    L --> M
-    
-    M -->|Yes| N[✅ Allow edit]
-    M -->|No| O[❌ Block edit<br/>list missing skills]
-```
-
-### File classes
-
-| Class | Extensions |
-|-------|-----------|
-| `code` | `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, `.rs`, `.java`, `.kt`, `.swift`, `.php`, `.dart`, `.rb` |
-| `design` | `.css`, `.scss`, `.html`, `.vue`, `.svelte`, `.astro` |
-| `text` | `.md`, `.txt`, `.rst` |
-| `config` | `.json`, `.yaml`, `.yml`, `.toml` |
-| `data` | `.csv`, `.sql`, `.db` |
-
-### Gate rules
-
-| Rule | Triggers on | Requires |
-|------|-------------|----------|
-| R3-supabase | A Supabase path or a Supabase prompt | novahiz-supabase, novahiz-postgres |
-| R4-playwright | A browser prompt category, or a browser test path (`**/*.spec.ts`, `**/e2e/**`, `**/playwright/**`, …) | novahiz-browser |
-| R6-Novahiz | A prompt in a workflow category | novahiz-plan, -clarify, -analyse, -implement, -converge |
-| R7-assessment | An assessment prompt | novahiz-assess-intake, -research, -define, -shape, -decide |
-| R8-docs | Edits under `novahiz-docs/**/*.md` | novahiz-docs |
-| R9-code-review | A review prompt or a code file under review | novahiz-code-review |
-| R10-security | An audit or security prompt | novahiz-security |
-| R11-accessibility | A design-ui or audit prompt | novahiz-wcag-audit |
-| R12-web-extract | A research prompt | novahiz-web-extract |
-| R13-design-craft | A design-ui prompt or a style file (css/scss/less/html) | novahiz-humanizer, ui-slop-remover, ui-craft-rules |
-| R14-impeccable | A design-ui prompt or a style file (css/scss/less/html) | impeccable |
-
-`novahiz-humanizer` and `ui-slop-remover` are required only on frontend design tasks (R13); `impeccable` loads the same way (R14) so the shape, critique, audit, harden and polish playbooks stay reachable, and the design-ui roadmap carries a deterministic `impeccable detect` verify step before ship. `novahiz init` and `novahiz doctor` report the impeccable `PRODUCT.md` / `DESIGN.md` context files as advisory rows.
-
-### Auto-repair
-
-A block is never a dead end. The refusal carries an AUTO-REPAIR recipe: load every skill it names with the skill loader, then retry the exact same call once — no alternate tool, no shell write, no editing around it. If the same skills are reported missing again, the load did not register: run `novahiz doctor`, report honestly, and stop. The only sanctioned bypass is `NOVAHIZ_GATE=off` (see Configuration), declared out loud.
-
-A required skill missing from the installed index is never enforced silently: the gate appends `required skill not in index, not enforced — run novahiz sync to realign` to its reasons instead of blocking forever. An unreadable index makes the gate stricter, never laxer.
-
----
-
-## Roadmaps
-
-Each category has an ordered execution roadmap. The gate enforces non-optional `skill` steps.
-
-### The six-stage pipeline
-
-Eight categories (`code`, `debug`, `browser`, `design-ui`, `database-supabase`, `planning`, `devops`, `data`) share one pipeline — and stages 1–4 write no application file, they produce a plan and decisions:
-
-| # | Stage | Skill | Produces |
-|---|-------|-------|----------|
-| 1 | Plan | `novahiz-plan` | direction, scope, dependency order, slicing strategy, risks |
-| 2 | Clarify | `novahiz-clarify` | the open questions, answered, and the decisions they freeze |
-| 3 | Tasks | `novahiz-task` | atomic tasks, each with acceptance criteria and proof |
-| 4 | Analyse | `novahiz-analyse` | the files and symbols that carry the logic, and the unknowns |
-| 5 | Implement | `novahiz-implement` | increments that leave the system working |
-| 6 | Converge | `novahiz-converge` | the gap between intent and code, as traceable remaining tasks |
-
-Clarify sends the work back to plan when an answer changes the architecture; converge sends it back to tasks when it finds a gap. `flutter` and `expo` keep the same six stages and insert their own quality skills around implement. The classifier's **tier** filters the rest: `trivial` runs almost nothing, `lite` keeps implement and converge, `full` walks the whole roadmap. Full reference: [docs/ROADMAPS.md](docs/ROADMAPS.md).
-
-```mermaid
-flowchart LR
-    subgraph "Feature (code)"
-        A1[advisory: Understand] --> A2[skill: Plan]
-        A2 --> A3[skill: Analyse]
-        A3 --> A4[skill: Implement]
-        A4 --> A5[skill: Converge]
-        A5 --> A6[verify: Verify]
-    end
-    
-    subgraph "Bugfix (debug)"
-        B1[advisory: Reproduce] --> B2[advisory: Isolate]
-        B2 --> B3[skill: Plan]
-        B3 --> B4[skill: Analyse]
-        B4 --> B5[skill: Implement]
-        B5 --> B6[skill: Converge]
-        B6 --> B7[advisory: Prevent]
-    end
-    
-    subgraph "Schema (database-supabase)"
-        C1[skill: Plan] --> C2[skill: Clarify]
-        C2 --> C3[skill: Inspect]
-        C3 --> C4[skill: Load supabase]
-        C4 --> C5[skill: Implement]
-        C5 --> C6[skill: Security]
-        C6 --> C7[skill: Converge]
-    end
-```
-
-| Step Kind | What it means | Gate behavior |
-|-----------|---------------|---------------|
-| `skill` | Load a skill before proceeding | **Blocks** if skill not loaded |
-| `edit` | Make code changes | Allowed |
-| `verify` | Check the work is correct | Advisory |
-| `advisory` | Informational | Never blocks |
-
----
-
-## Task Ledger
-
-For work that spans more than a few steps, the ledger keeps the plan in SQLite instead of in the conversation.
-
-```mermaid
-flowchart TD
-    A["task new 'Add CSV export'"] --> B[Create task + todos from roadmap]
-    B --> C[Dispatch work packets]
-    C --> D[Each packet = one todo<br/>exclusive file ownership]
-    D --> E[Agent works on todos]
-    E --> F{Review cadence<br/>every N edits}
-    F -->|N reached| G[Force review step<br/>reconcile plan]
-    F -->|N not reached| E
-    G --> E
-    E --> H[All todos done]
-    H --> I[Task complete]
-```
-
-- **Exclusive file ownership** — no two work packets can edit the same file
-- **Iteration budget** — each todo has a max (default: 12) before escalation
-- **Review cadence** — forced review every 3 edits or 2 completed todos
-- **Proof required** — verify steps require evidence before completion
-
----
-
-## Memory
-
-Session memory is a two-layer system: a bounded, machine-readable workspace, and a human-readable notebook that is dual-written.
-
-| Layer | Where | Behavior |
-|-------|-------|----------|
-| Session slots | `project-memory/` under the project root | `index.json` + fixed-size slots, compact → archive → rotate |
-| Notebook | `MEMORY.md` + Obsidian vault page | dual-write at task end; the vault folder comes from `_meta/routing.md` |
-
-### Session slots — `project-memory/`
-
-- Lives under the project root: `index.json` plus `slots/`, and `novahiz init` seeds it with a baseline slot.
-- Slots are fixed-size (**8000 chars / 200 lines**): a full slot is compacted, archived, and replaced — memory stays bounded no matter how long the project runs.
-- MCP tools operate it: `memory_init`, `memory_list`, `memory_get`, `memory_write` (appends and rotates), `memory_rebuild` (reindexes from the markdown).
-- This is where decisions, root causes and next steps go when a complex task ends.
-- `novahiz doctor` checks both the memory root and the memory tools.
-
-### Dual-write — `MEMORY.md` + vault
-
-The `novahiz-memory` skill writes the closing state of a task in two places at once:
-
-| Medium | Destination |
-|--------|-------------|
-| Project | `MEMORY.md` at the project root — what works now, what changed, what stays open |
-| Vault | an Obsidian page — folder chosen **only** by the `_meta/routing.md` routing table |
-
-Rules: mandatory frontmatter (title, category, tags, sources, created, updated, summary), `[[wikilinks]]` from the taxonomy, and enrich the existing page instead of creating a second one. Ambiguous routing → ask, never guess.
-
----
-
-## Installed skills
-
-Novahiz ships with 96 skills across all categories:
-
-| Category | Skills | Purpose |
-|----------|--------|---------|
-| `code` | novahiz-code-review, code-standards, openapi-mcp-server, ... | Code quality, patterns, architecture |
-| `debug` | novahiz-analyse, ... | Root cause analysis |
-| `review` | novahiz-code-review, novahiz-delta-review, ... | Structured review, blast radius |
-| `database-supabase` | novahiz-postgres, novahiz-supabase, ... | Schema, RLS, migrations, optimization |
-| `design-ui` | novahiz-humanizer, ui-slop-remover, ui-craft-rules, apple-ui-audit, ... | UI/UX, visual hierarchy, native feel |
-| `docs-writing` | ... | Prose, marketing copy, AI de-tell |
-| `browser` | novahiz-browser, browser-session, novahiz-web-extract, ... | Web automation, screenshots, extraction |
-| `audit` | novahiz-security, package-risk-audit, llm-threat-review, ... | Security, compliance, vulnerability |
-| `expo` | expo-overview, expo-router, expo-module, expo-dev-client, ... | Expo / React Native: routes, native modules, builds |
-| `devops` | eas-workflows, eas-app-stores, novahiz-release, ... | CI/CD, deploys, versioned releases |
-
-Run `npx novahiz skills --all` to see the full list.
-
----
-
-## Providers
-
-Novahiz auto-registers external MCP servers based on the prompt category:
-
-| Provider | Package | License | Categories |
-|----------|---------|---------|------------|
-| context7 | `@upstash/context7-mcp` | MIT | code |
-| narsil | `narsil-mcp` | MIT OR Apache-2.0 | code, review |
-| novahiz | local (`mcp/novahiz-tools`) | Apache-2.0 | code, planning |
-| playwright | `@playwright/mcp` | Apache-2.0 | browser, design-ui |
-| security | `security-mcp` | MIT | audit |
-| cron | `scheduler-mcp` (local venv clone) | MIT | devops |
-| dart | `dart mcp-server` (Dart SDK) | BSD-3-Clause | code, debug, design-ui, flutter |
-
-Skill packs (installed from official repos, never vendored): `flutter/agent-plugins` (25 skills), `dart-lang/skills` (15 skills), `expo/skills` (19 skills, the `expo-*` group only; `eas-*` paid services excluded), `pbakaus/impeccable` (1 skill, the upstream `impeccable` design skill). See [docs/PROVIDERS.md](docs/PROVIDERS.md).
-
-Upstream repositories and full provenance for MCP providers and opencode plugins: [docs/PROVIDERS.md](docs/PROVIDERS.md), [docs/HARNESSES.md](docs/HARNESSES.md), [NOTICE.md](NOTICE.md).
-
----
-
-## Configuration
-
-```bash
-# Disable the gate (escape hatch)
-NOVAHIZ_GATE=off npx opencode
-
-# Override home directory
-NOVAHIZ_HOME=/path/to/novahiz npx novahiz doctor
-
-# Force node version
-NOVAHIZ_NODE=/usr/local/bin/node npx novahiz doctor
-```
-
-See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for all options.
-
----
-
-## Commands
-
-| Command | Purpose |
-|---------|---------|
-| `novahiz init` | One-shot setup |
-| `novahiz doctor` | 13-check health diagnostic (14 with `--deep`; 17 with Claude Code, 19 with impeccable) |
-| `novahiz status` | Current classification + gate state |
-| `novahiz classify <text>` | Classify a prompt |
-| `novahiz gate` | Check if an edit is allowed |
-| `novahiz task new <title>` | Start a tracked task |
-| `novahiz task status` | Task progress |
-| `novahiz task done <id>` | Mark a todo complete |
-| `novahiz report` | Session report |
-| `novahiz skills` | List loaded or available skills |
-| `novahiz catalog <query>` | Search the skill catalog |
-| `novahiz roadmap` | Show execution roadmap |
-| `novahiz dispatch` | Generate work packets |
-| `novahiz sync` | Rebuild installed-skills index |
-| `novahiz clean` | Remove old logs |
-| `novahiz upgrade` | Pull latest + rebuild |
-| `novahiz version` | Print version |
-
-See [docs/CLI.md](docs/CLI.md) for full reference.
-
----
-
-## Documentation
-
-| File | Topic |
-|------|-------|
-| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design, components, data flow |
-| [docs/CLASSIFICATION.md](docs/CLASSIFICATION.md) | How the classifier works |
-| [docs/GATE.md](docs/GATE.md) | Gate rules, file classes, enforcement |
-| [docs/CATALOG.md](docs/CATALOG.md) | Categories, rules, providers, overrides |
-| [docs/PLUGIN.md](docs/PLUGIN.md) | opencode plugin lifecycle |
-| [docs/CLI.md](docs/CLI.md) | CLI command reference |
-| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Config files and env vars |
-| [docs/EXECUTION.md](docs/EXECUTION.md) | Task ledger, todos, dispatch |
-| [docs/PROVIDERS.md](docs/PROVIDERS.md) | MCP servers and skill packs |
-| [docs/INSTALL.md](docs/INSTALL.md) | Installation and setup |
-| [docs/ROADMAPS.md](docs/ROADMAPS.md) | Execution roadmaps |
-| [docs/RULES.md](docs/RULES.md) | Gate rules reference |
-| [docs/CONSTITUTION.md](docs/CONSTITUTION.md) | Project principles |
-| [docs/HARNESSES.md](docs/HARNESSES.md) | Harness adapter guide |
-| [docs/TOKENS.md](docs/TOKENS.md) | Token diagnostics |
-
----
-
-## Philosophy
-
-Novahiz treats skills like **locks** and the prompt like a **key**. The classifier determines which locks exist. The gate checks whether you have the right keys loaded. No key, no edit.
-
-Everything is local, deterministic, and JSON. No cloud calls. No model inference in the decision path. Same prompt + same config = same result, every time.
-
----
-
-## License
-
-Apache-2.0
+# Novahiz : la boîte à outils de gouvernance des agents
+
+> **Couche d'application sans dépendance pour les agents de code IA** — classe les prompts, attribue des roadmaps d'exécution, bloque les éditions non sûres tant que les bonnes skills ne sont pas chargées, et persiste les décisions d'une session à l'autre — tout cela de façon déterministe, sans appel de modèle.
+
+17 catégories, 96 skills, 11 gate rules, 7 MCP providers — tout déterministe, tout local, tout JSON.
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                                                                          │
+│   PROMPT UTIL.  ──▶  CLASSIF.  ──▶  GATE  ──▶  SORTIE SÛRE              │
+│                                                                          │
+│   « Corrige le    3 catégories   2 skills       Édition bloquée          │
+│     bug d'auth »  détectées      manquantes     tant que les            │
+│                   exigées        skills ne sont pas chargées            │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Comment se déroule une session
+
+1. **Classifier** — chaque prompt est noté contre 17 catégories (mots-clés déterministes, aucun appel de modèle). Le résultat porte jusqu'à trois catégories, une principale, un niveau de confiance, un **tier** (`trivial` / `lite` / `full`), et les skills que le gate attendra.
+2. **Roadmap** — la catégorie principale sélectionne une roadmap ordonnée, et le plugin injecte sa checklist dans la session : l'agent suit plan → clarify → tasks → analyse → implement → converge au lieu d'improviser un ordre.
+3. **Gate sur chaque écriture** — les appels `edit` / `write` / `patch` / `bash` / `shell` sont vérifiés selon la classe de fichier, les règles actives, les skills de roadmap et le contenu (tokens de placeholder) : **allow** ou **block**, en local, sans appel de modèle dans le chemin de décision.
+4. **Gate reload, pas une impasse** — un blocage nomme exactement les skills manquantes et la règle de retry : charger chacune, rejouer l'appel une seule fois. Une skill absente de l'index installé est signalée, jamais appliquée. `NOVAHIZ_GATE=off` est la seule soupape, et elle est bruyante.
+5. **Vérifier et converger** — les roadmaps se terminent par des étapes `verify` qui exigent une preuve ; `novahiz-converge` note le code face à la demande d'origine et transforme chaque reste en étape traçable du ledger.
+6. **Persister** — décisions, causes racines et prochaines étapes survivent à la session via la couche mémoire (ci-dessous), et `novahiz report` boucle la boucle avec un résumé de session.
+
+```
+ PROMPT ─▶ CLASSIFIER ─▶ ROADMAP ─▶ travail ─▶ GATE ─▶ allow ─▶ VERIFY ─▶ MEMORY
+                 │                     ▲         │
+                 └─ tier, skills ──────│         └─ block : charger les skills nommées, retry une fois
+```
+
+**17 catégories**, **96 skills**, **11 gate rules**, **7 MCP providers** — tout déterministe, tout local, tout JSON.
+
+---
+
+## Démarrage rapide
+
+### Option 1 — En une ligne (recommandé)
+
+```bash
+npm install -g novahiz
+novahiz-install --yes
+```
+
+`npm install -g novahiz` installe le CLI. Sur npm 11+, les scripts de lifecycle sont derrière une confirmation allow-scripts : la configuration est donc une seconde étape explicite. `novahiz-install` configure opencode, le seul harness supporté — skills, plugin/agent, commands, MCP servers, config ; `--yes` accepte la configuration détectée. Puis vérifiez :
+
+```bash
+novahiz doctor   # Santé : 15 checks (17 avec --deep)
+novahiz classify "fix the auth bug"
+```
+
+### Option 2 — Depuis les sources
+
+```bash
+git clone https://github.com/novahiz/novahiz.git
+cd novahiz
+npm install            # `prepare` typecheck et build dist/
+node ./install/install.mjs   # ajouter --yes pour accepter les valeurs détectées
+
+# Vérifier
+node ./dist/cli.js doctor
+```
+
+> Nécessite **Node.js >= 22.18**. L'installeur installe automatiquement le CLI d'opencode (`opencode-ai`) s'il est entièrement absent de la machine, sans bloquer.
+
+---
+
+## Le classifier
+
+Chaque prompt utilisateur passe par le classifier. Il note les mots-clés contre 17 catégories et retient les meilleurs matchs.
+
+```mermaid
+flowchart LR
+    A[Prompt utilisateur] --> B[Folding du texte<br/>minuscules + suppression des accents]
+    B --> C{Scoring mots-clés<br/>+1.0 par hit<br/>+1.5 bonus multi-mots}
+    C --> D[Classement par score + priorité]
+    D --> E[Top 3 des catégories]
+    E --> F[Catégorie principale<br/>détermine la roadmap]
+    F --> G[Skills requises<br/>union de toutes les catégories]
+    F --> H[Skills appliquées<br/>principale seulement — le gate bloque si absente]
+```
+
+**Exemple :**
+
+| Prompt | Catégorie principale | Confiance | Skills requises |
+|--------|----------------------|-----------|-----------------|
+| "fix the auth bug" | `debug` | 0.60 | novahiz-plan, novahiz-analyse, novahiz-implement, novahiz-converge |
+| "add a landing page" | `design-ui` | 0.50 | novahiz-humanizer, ui-slop-remover |
+| "create supabase migration" | `database-supabase` | 0.60 | novahiz-supabase, novahiz-postgres, novahiz-plan, novahiz-implement |
+
+---
+
+## Le gate
+
+Le gate est le mécanisme d'application. Il inspecte chaque édition de fichier et décide : **allow** ou **block**.
+
+```mermaid
+flowchart TD
+    A[Appel outil : edit / write / patch] --> B[Détection de la classe de fichier]
+    B --> C{Correspondance des règles}
+    
+    C --> D[R13 : prompt design-ui ou fichier style ?<br/>exiger humanizer + ui-slop + ui-craft]
+    C --> F[R3 : le prompt était Supabase ?<br/>exiger novahiz-supabase + postgres]
+    C --> G[R4 : le prompt était navigateur ?<br/>exiger novahiz-browser]
+    C --> H[R6 : prompt de workflow ?<br/>exiger plan/clarify/analyse/implement/converge]
+    
+    D --> I{Application de la roadmap}
+    F --> I
+    G --> I
+    H --> I
+    
+    I --> J{Détection de placeholder<br/>tokens TODO / FIXME / placeholder}
+    
+    J --> K["Vérif. des skills installées<br/>(manquante → signalée, non bloquée)"]
+    J --> L["Vérif. des skills chargées<br/>(manquante → BLOQUÉE)"]
+    
+    K --> M{Toutes chargées ?}
+    L --> M
+    
+    M -->|Oui| N[✅ Édition autorisée]
+    M -->|Non| O[❌ Édition bloquée<br/>liste des skills manquantes]
+```
+
+### Classes de fichiers
+
+| Classe | Extensions |
+|--------|-----------|
+| `code` | `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, `.rs`, `.java`, `.kt`, `.swift`, `.php`, `.dart`, `.rb` |
+| `design` | `.css`, `.scss`, `.html`, `.vue`, `.svelte`, `.astro` |
+| `text` | `.md`, `.txt`, `.rst` |
+| `config` | `.json`, `.yaml`, `.yml`, `.toml` |
+| `data` | `.csv`, `.sql`, `.db` |
+
+### Règles du gate
+
+| Règle | Se déclenche sur | Exige |
+|-------|------------------|-------|
+| R3-supabase | Un chemin Supabase ou un prompt Supabase | novahiz-supabase, novahiz-postgres |
+| R4-playwright | Une catégorie prompt navigateur, ou un chemin de test navigateur (`**/*.spec.ts`, `**/e2e/**`, `**/playwright/**`, …) | novahiz-browser |
+| R6-Novahiz | Un prompt dans une catégorie de workflow | novahiz-plan, -clarify, -analyse, -implement, -converge |
+| R7-assessment | Un prompt d'assessment | novahiz-assess-intake, -research, -define, -shape, -decide |
+| R8-docs | Une édition sous `novahiz-docs/**/*.md` | novahiz-docs |
+| R9-code-review | Un prompt de review ou un fichier de code en review | novahiz-code-review |
+| R10-security | Un prompt d'audit ou de sécurité | novahiz-security |
+| R11-accessibility | Un prompt design-ui ou audit | novahiz-wcag-audit |
+| R12-web-extract | Un prompt de recherche | novahiz-web-extract |
+| R13-design-craft | Un prompt design-ui ou un fichier style (css/scss/less/html) | novahiz-humanizer, ui-slop-remover, ui-craft-rules |
+| R14-impeccable | Un prompt design-ui ou un fichier style (css/scss/less/html) | impeccable |
+
+`novahiz-humanizer` et `ui-slop-remover` ne sont exigées que sur les tâches de design frontend (R13) ; `impeccable` se charge de la même façon (R14) pour garder les playbooks shape, critique, audit, harden et polish accessibles, et la roadmap design-ui porte une étape de vérification `impeccable detect` déterministe avant ship. `novahiz init` et `novahiz doctor` affichent les fichiers de contexte `PRODUCT.md` / `DESIGN.md` d'impeccable en lignes advisory.
+
+### Gate reload
+
+Un blocage n'est jamais une impasse. Le refus embarque une recette GATE RELOAD : charger chaque skill nommée via le loader, puis rejouer l'appel exact une fois — aucun outil alternatif, aucune écriture shell, aucun contournement d'édition. Si les mêmes skills sont de nouveau signalées manquantes, le chargement n'a pas été enregistré : exécuter `novahiz doctor`, signaler honnêtement, et s'arrêter. La seule dérogation sanctionnée est `NOVAHIZ_GATE=off` (voir Configuration), déclarée à voix haute.
+
+Une skill requise absente de l'index installé n'est jamais appliquée silencieusement : le gate ajoute `required skill not in index, not enforced — run novahiz sync to realign` à ses raisons au lieu de bloquer pour toujours. Un index illisible rend le gate plus strict, jamais plus laxiste.
+
+---
+
+## Roadmaps
+
+Chaque catégorie possède une roadmap d'exécution ordonnée. Le gate applique les étapes `skill` non optionnelles.
+
+### Le pipeline en six étapes
+
+Huit catégories (`code`, `debug`, `browser`, `design-ui`, `database-supabase`, `planning`, `devops`, `data`) partagent un pipeline — et les étapes 1 à 4 n'écrivent aucun fichier d'application : elles produisent un plan et des décisions :
+
+| # | Étape | Skill | Produit |
+|---|-------|-------|---------|
+| 1 | Plan | `novahiz-plan` | direction, périmètre, ordre des dépendances, stratégie de découpe, risques |
+| 2 | Clarify | `novahiz-clarify` | les questions ouvertes, répondues, et les décisions qu'elles figent |
+| 3 | Tasks | `novahiz-task` | des tâches atomiques, chacune avec critères d'acceptation et preuve |
+| 4 | Analyse | `novahiz-analyse` | les fichiers et symboles qui portent la logique, et les inconnues |
+| 5 | Implement | `novahiz-implement` | des incréments qui laissent le système fonctionnel |
+| 6 | Converge | `novahiz-converge` | l'écart entre intention et code, en tâches restantes traçables |
+
+Clarify renvoie le travail au plan quand une réponse change l'architecture ; converge le renvoie aux tâches quand il trouve un écart. `flutter` et `expo` gardent les six mêmes étapes et insèrent leurs skills qualité autour d'implement. Le **tier** du classifier filtre la suite : `trivial` n'exécute presque rien, `lite` garde implement et converge, `full` parcourt toute la roadmap. Référence complète : [docs/ROADMAPS.md](docs/ROADMAPS.md).
+
+```mermaid
+flowchart LR
+    subgraph "Fonctionnalité (code)"
+        A1[advisory: Comprendre] --> A2[skill: Plan]
+        A2 --> A3[skill: Analyse]
+        A3 --> A4[skill: Implement]
+        A4 --> A5[skill: Converge]
+        A5 --> A6[verify: Vérifier]
+    end
+    
+    subgraph "Correctif (debug)"
+        B1[advisory: Reproduire] --> B2[advisory: Isoler]
+        B2 --> B3[skill: Plan]
+        B3 --> B4[skill: Analyse]
+        B4 --> B5[skill: Implement]
+        B5 --> B6[skill: Converge]
+        B6 --> B7[advisory: Prévenir]
+    end
+    
+    subgraph "Schéma (database-supabase)"
+        C1[skill: Plan] --> C2[skill: Clarify]
+        C2 --> C3[skill: Inspecter]
+        C3 --> C4[skill: Charger supabase]
+        C4 --> C5[skill: Implement]
+        C5 --> C6[skill: Security]
+        C6 --> C7[skill: Converge]
+    end
+```
+
+| Type d'étape | Ce que ça veut dire | Comportement du gate |
+|--------------|---------------------|----------------------|
+| `skill` | Charger une skill avant de continuer | **Bloque** si la skill n'est pas chargée |
+| `edit` | Modifier le code | Autorisé |
+| `verify` | Vérifier que le travail est correct | Advisory |
+| `advisory` | Informatif | Ne bloque jamais |
+
+---
+
+## Ledger de tâches
+
+Pour un travail qui dépasse quelques étapes, le ledger conserve le plan dans SQLite plutôt que dans la conversation.
+
+```mermaid
+flowchart TD
+    A["task new 'Ajouter export CSV'"] --> B[Créer tâche + todos depuis la roadmap]
+    B --> C[Dispatch des work packets]
+    C --> D[Chaque packet = un todo<br/>propriété exclusive de fichiers]
+    D --> E[L'agent travaille les todos]
+    E --> F{Cadence de review<br/>tous les N éditions}
+    F -->|N atteint| G[Forcer une étape de review<br/>réconcilier le plan]
+    F -->|N pas atteint| E
+    G --> E
+    E --> H[Tous les todos faits]
+    H --> I[Tâche terminée]
+```
+
+- **Propriété exclusive des fichiers** — deux work packets ne peuvent pas éditer le même fichier
+- **Budget d'itération** — chaque todo a un max (par défaut : 12) avant escalade
+- **Cadence de review** — review forcée après 3 éditions de fichiers détenus par un todo ou 2 todos complétés (les éditions hors du projet de la tâche ou hors du périmètre d'un todo ne comptent pas)
+- **Preuve obligatoire** — les étapes verify exigent une évidence avant complétion
+- **Snapshots** — chaque écriture du ledger laisse un point de restauration ; `novahiz snap list / diff / restore` et les tools MCP `snap_log`, `snap_status`, `snap_diff`, `snap_restore` les lisent ou les rétablissent en place, sans jamais remplacer le fichier
+
+---
+
+## Mémoire
+
+La mémoire de session est un système à deux couches : un espace de travail borné et lisible par la machine, et un carnet lisible par l'humain écrit en double.
+
+| Couche | Où | Comportement |
+|--------|----|--------------|
+| Slots de session | `project-memory/` sous la racine du projet | `index.json` + slots de taille fixe, compact → archive → rotation |
+| Carnet | `MEMORY.md` + page Obsidian | double écriture en fin de tâche ; le dossier du vault vient de `_meta/routing.md` |
+
+### Slots de session — `project-memory/`
+
+- Vit sous la racine du projet : `index.json` plus `slots/`, et `novahiz init` le sème avec un slot de base. La racine est résolue une seule fois (`resolveMemoryDir`) : on peut passer la racine du projet **ou** le dossier mémoire lui-même, l'ancien layout (`index.json` + `slots/`) est accepté tel quel, un chemin hors du projet **dégrade** vers la mémoire du projet (`degraded: true`, jamais d'écriture hors workspace) — et chaque réponse `memory_*` écho le `root` réellement utilisé. Verrou pris trop longtemps → mise en file `.pending` rejouée au prochain appel ; slot illisible → exclu avec `warnings`. La mémoire ne bloque jamais la session.
+- Slots de taille fixe (**8000 caractères / 200 lignes**) : un slot plein est compacté, archivé, remplacé — mais jamais à l'aveugle : la copie complète part d'abord dans `slots/archive/<id>-precompact-<ts>.md` (réponse `archivedTo`) et les titres `## ` du fold sont démotés en puces pour que le reparse n'avale rien. La mémoire reste bornée **et** intacte quelle que soit la durée du projet.
+- Les outils MCP l'opèrent : `memory_init`, `memory_list`, `memory_get` (trace `last_read`, donnée d'entrée du decay), `memory_search` (shortlist via l'index SQLite FTS5 de `novahiz.sqlite` — index **dérivé**, `engine: "fts"`, repli automatique sur le scan fichiers en `engine: "files"` — puis classement IDF existant, scores 0..1 inchangés), `memory_write` (append et rotation), `memory_update`, `memory_archive`, `memory_rebuild` (réindexe depuis le markdown, hors archives, **et** régénère l'index FTS5).
+- Hygiène par la CLI, **dry-run par défaut** (`--apply` exécute, GC = archiver, jamais détruire) : `novahiz memory status | clean | prune` — verrous périmés, échecs `.pending`, fragments `.tmp`, doublons inter-slots (Resume + Détails identiques → le plus récent archivé), orphelins/fantômes, archives au-delà de `--retention` (déplacées vers `slots/archive/retention/`, contenu intact) et slots **jamais lus** depuis `--decay` jours ; `--days` compte la dernière *utilisation* (une lecture récente prolonge la vie). Le banc `npm run bench` mesure le chemin : fold sans cache → fold+cache → FTS+cache.
+- C'est ici que vont décisions, causes racines et prochaines étapes quand une tâche complexe se termine.
+- `novahiz doctor` vérifie à la fois la racine mémoire et les outils mémoire.
+
+### Double écriture — `MEMORY.md` + vault
+
+La skill `novahiz-memory` écrit l'état de clôture d'une tâche à deux endroits à la fois :
+
+| Support | Destination |
+|---------|-------------|
+| Projet | `MEMORY.md` à la racine — ce qui marche maintenant, ce qui a changé, ce qui reste ouvert |
+| Vault | une page Obsidian — dossier choisi **uniquement** par la table de routage `_meta/routing.md` |
+
+Règles : frontmatter obligatoire (title, category, tags, sources, created, updated, summary), `[[wikilinks]]` depuis la taxonomie, et enrichir la page existante au lieu d'en créer une seconde. Routage ambigu → demander, jamais deviner.
+
+---
+
+## Skills installées
+
+Novahiz livre 96 skills couvrant toutes les catégories :
+
+| Catégorie | Skills | Objectif |
+|-----------|--------|----------|
+| `code` | novahiz-code-review, code-standards, openapi-mcp-server, ... | Qualité du code, patterns, architecture |
+| `debug` | novahiz-analyse, ... | Analyse de cause racine |
+| `review` | novahiz-code-review, novahiz-delta-review, ... | Review structurée, rayon d'impact |
+| `database-supabase` | novahiz-postgres, novahiz-supabase, ... | Schéma, RLS, migrations, optimisation |
+| `design-ui` | novahiz-humanizer, ui-slop-remover, ui-craft-rules, apple-ui-audit, ... | UI/UX, hiérarchie visuelle, feel natif |
+| `docs-writing` | ... | Prose, copy marketing, dé-IA du texte |
+| `browser` | novahiz-browser, browser-session, novahiz-web-extract, ... | Automatisation web, captures, extraction |
+| `audit` | novahiz-security, package-risk-audit, llm-threat-review, ... | Sécurité, conformité, vulnérabilités |
+| `expo` | expo-overview, expo-router, expo-module, expo-dev-client, ... | Expo / React Native : routes, modules natifs, builds |
+| `devops` | eas-workflows, eas-app-stores, novahiz-release, ... | CI/CD, déploiements, releases versionnées |
+
+Lancer `npx novahiz skills --all` pour voir la liste complète.
+
+---
+
+## Providers
+
+Novahiz auto-enregistre les serveurs MCP externes selon la catégorie du prompt :
+
+| Provider | Package | Licence | Catégories |
+|----------|---------|---------|------------|
+| novahiz-docs | `mcp/novahiz-docs/index.mjs` (local) | Apache-2.0 | code |
+| novahiz-search | `mcp/lodestone/index.mjs` (local, zéro dépendance) | Apache-2.0 | code, review |
+| novahiz-core | local (`mcp/novahiz-tools`) | Apache-2.0 | code, planning |
+| novahiz-gate | local (`mcp/novahiz-gate`) | Apache-2.0 | code, planning |
+| novahiz-scan | `mcp/argus/src/cli.mjs` (local) | MIT | audit |
+| playwright | `@playwright/mcp` | Apache-2.0 | browser, design-ui |
+| novahiz-scheduler | `mcp/clepsydre/index.mjs` (local, zéro dépendance) | Apache-2.0 | devops |
+| dart | `dart mcp-server` (Dart SDK) | BSD-3-Clause | code, debug, design-ui, flutter |
+
+Packs de skills (installés depuis les dépôts officiels, jamais vendorés) : `flutter/agent-plugins` (25 skills), `dart-lang/skills` (15 skills), `expo/skills` (19 skills, le groupe `expo-*` seulement ; les services payants `eas-*` exclus), `pbakaus/impeccable` (1 skill, la skill design upstream `impeccable`). Voir [docs/PROVIDERS.md](docs/PROVIDERS.md).
+
+Dépôts upstream et provenance complète des providers MCP et plugins opencode : [docs/PROVIDERS.md](docs/PROVIDERS.md), [docs/HARNESSES.md](docs/HARNESSES.md), [NOTICE.md](NOTICE.md).
+
+> Note : les fichiers de `docs/` restent en anglais.
+
+---
+
+## Configuration
+
+```bash
+# Désactiver le gate (soupape d'urgence)
+NOVAHIZ_GATE=off npx opencode
+
+# Surcharger le répertoire home
+NOVAHIZ_HOME=/path/to/novahiz npx novahiz doctor
+
+# Forcer la version de node
+NOVAHIZ_NODE=/usr/local/bin/node npx novahiz doctor
+```
+
+Voir [docs/CONFIGURATION.md](docs/CONFIGURATION.md) pour toutes les options.
+
+---
+
+## Commandes
+
+| Commande | Objectif |
+|----------|----------|
+| `novahiz init` | Installation en une passe |
+| `novahiz doctor` | Diagnostic de santé 15-check (17 avec `--deep`) |
+| `novahiz status` | Classification + état du gate actuels |
+| `novahiz classify <text>` | Classer un prompt |
+| `novahiz gate` | Vérifier si une édition est autorisée |
+| `novahiz task new <title>` | Démarrer une tâche suivie |
+| `novahiz task status` | Avancement de la tâche |
+| `novahiz task done <id>` | Marquer un todo complété |
+| `novahiz snap <sub>` | Snapshots versionnés du ledger (`save` / `list` / `diff` / `restore`) |
+| `novahiz graph <sub>` | Graphe de code du workspace (`build` / `find` / `trace` / `api` / `map` / `fresh`) — le nôtre, en processus, sans binaire externe ([docs/GRAPH.md](docs/GRAPH.md)) |
+| `novahiz memory <sub>` | Hygiène de la mémoire projet (`status` / `clean` / `prune`) — dry-run par défaut, `--apply` pour exécuter ; `prune` archive, rien n'est supprimé |
+| `novahiz report` | Rapport de session |
+| `novahiz skills` | Lister les skills chargées ou disponibles |
+| `novahiz catalog <query>` | Chercher dans le catalogue de skills |
+| `novahiz roadmap` | Afficher la roadmap d'exécution |
+| `novahiz dispatch` | Générer des work packets |
+| `novahiz sync` | Reconstruire l'index des skills installées |
+| `novahiz clean` | Supprimer les vieux logs |
+| `novahiz upgrade` | Pull du dernier + rebuild |
+| `novahiz version` | Afficher la version |
+
+Voir [docs/CLI.md](docs/CLI.md) pour la référence complète.
+
+---
+
+## Documentation
+
+| Fichier | Sujet |
+|---------|-------|
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Design système, composants, flux de données |
+| [docs/CLASSIFICATION.md](docs/CLASSIFICATION.md) | Fonctionnement du classifier |
+| [docs/GATE.md](docs/GATE.md) | Règles du gate, classes de fichiers, application |
+| [docs/CATALOG.md](docs/CATALOG.md) | Catégories, règles, providers, overrides |
+| [docs/PLUGIN.md](docs/PLUGIN.md) | Cycle de vie du plugin opencode |
+| [docs/CLI.md](docs/CLI.md) | Référence des commandes CLI |
+| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Fichiers de config et variables d'env |
+| [docs/EXECUTION.md](docs/EXECUTION.md) | Ledger de tâches, todos, dispatch |
+| [docs/PROVIDERS.md](docs/PROVIDERS.md) | Serveurs MCP et packs de skills |
+| [docs/INSTALL.md](docs/INSTALL.md) | Installation et configuration |
+| [docs/ROADMAPS.md](docs/ROADMAPS.md) | Roadmaps d'exécution |
+| [docs/RULES.md](docs/RULES.md) | Référence des règles du gate |
+| [docs/CONSTITUTION.md](docs/CONSTITUTION.md) | Principes du projet |
+| [docs/HARNESSES.md](docs/HARNESSES.md) | Guide des adaptateurs de harness |
+| [docs/TOKENS.md](docs/TOKENS.md) | Diagnostics de tokens |
+
+---
+
+## Philosophie
+
+Novahiz traite les skills comme des **serrures** et le prompt comme une **clé**. Le classifier détermine quelles serrures existent. Le gate vérifie que vous avez les bonnes clés chargées. Pas de clé, pas d'édition.
+
+Tout est local, déterministe et JSON. Aucun appel cloud. Aucune inférence de modèle dans le chemin de décision. Même prompt + même config = même résultat, à chaque fois.
+
+---
+
+## Licence
+
+Apache-2.0