novahiz 0.3.5 → 0.3.7

package/README.md

@@ -1,8 +1,8 @@
 # Novahiz: Agent Governance Toolkit
 
-> **Zero-dependency enforcement layer for AI coding agents** — classifies prompts, assigns execution roadmaps, blocks unsafe edits, and injects session-level skills, all deterministically without model calls.
+> **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, 95 skills, 11 gate rules, 7 MCP providers — all deterministic, all local, all JSON.
+17 categories, 96 skills, 11 gate rules, 7 MCP providers — all deterministic, all local, all JSON.
 
 ```
 ┌─────────────────────────────────────────────────────────────────────┐
@@ -18,41 +18,22 @@
 
 ---
 
-## What it does
+## 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.
 
 ```
-┌──────────────────────────────────────────────────────────────────────────┐
-│                        HOW Novahiz WORKS                            │
-│                                                                          │
-│  ┌──────────┐    ┌────────────┐    ┌──────────┐    ┌──────────────┐     │
-│  │  USER    │───▶│  CLASSIFY  │───▶│  INJECT  │───▶│    MODEL     │     │
-│  │  PROMPT  │    │            │    │ ENFORCE  │    │   RESPONSE   │     │
-│  └──────────┘    │ keywords   │    │ block +  │    └──────┬───────┘     │
-│                  │ priority   │    │ roadmap  │           │             │
-│                  │ roadmap    │    │ ledger   │           ▼             │
-│                  └────────────┘    └──────────┘    ┌──────────────┐     │
-│                       │                            │  TOOL CALL   │     │
-│                       │                            │ (edit/write) │     │
-│                       │                            └──────┬───────┘     │
-│                       │                                   │             │
-│                       │         ┌────────────┐            │             │
-│                       └────────▶│    GATE    │◀───────────┘             │
-│                                 │            │                          │
-│                                 │  file path │                          │
-│                                 │  skills    │                          │
-│                                 │  content   │                          │
-│                                 └─────┬──────┘                          │
-│                                       │                                 │
-│                                       ▼                                 │
-│                                 ┌──────────┐                           │
-│                                 │ allow /  │                           │
-│                                 │ BLOCK    │                           │
-│                                 └──────────┘                           │
-│                                                                          │
-└──────────────────────────────────────────────────────────────────────────┘
+ PROMPT ─▶ CLASSIFY ─▶ ROADMAP ─▶ work ─▶ GATE ─▶ allow ─▶ VERIFY ─▶ MEMORY
+               │                   ▲        │
+               └─ tier, skills ────│        └─ block: load named skills, retry once
 ```
 
-**17 categories**, **95 skills**, **11 gate rules**, **7 MCP providers** — all deterministic, all local, all JSON.
+**17 categories**, **96 skills**, **11 gate rules**, **7 MCP providers** — all deterministic, all local, all JSON.
 
 ---
 
@@ -61,14 +42,15 @@
 ### Option 1 — One-liner (recommended)
 
 ```bash
-npm install -g Novahiz
+npm install -g novahiz
+novahiz-install --yes
 ```
 
-This installs Novahiz globally and auto-configures opencode (skills, plugin, MCP servers, config). Then verify:
+`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
-npx Novahiz doctor   # 12 health checks
-npx Novahiz classify "fix the auth bug"
+novahiz doctor   # health checks — 13 base, 17 with Claude Code, 19 with impeccable
+novahiz classify "fix the auth bug"
 ```
 
 ### Option 2 — From source
@@ -76,14 +58,14 @@ npx Novahiz classify "fix the auth bug"
 ```bash
 git clone https://github.com/novahiz/novahiz.git
 cd novahiz
-npm install && npm run build
-node ./install/install.mjs
+npm install            # `prepare` typechecks and builds dist/
+node ./install/install.mjs   # add --yes to accept the detected defaults
 
 # Verify
-npx Novahiz doctor
+node ./dist/cli.js doctor
 ```
 
-> Requires **Node.js >= 22.18**. The installer auto-installs opencode if it's missing.
+> 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.
 
 ---
 
@@ -169,7 +151,13 @@ flowchart TD
 | 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 critique, audit and polish playbooks stay reachable.
+`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.
 
 ---
 
@@ -177,6 +165,21 @@ flowchart TD
 
 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)"
@@ -240,9 +243,39 @@ flowchart TD
 
 ---
 
+## 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 95 skills across all categories:
+Novahiz ships with 96 skills across all categories:
 
 | Category | Skills | Purpose |
 |----------|--------|---------|
@@ -255,8 +288,9 @@ Novahiz ships with 95 skills across all categories:
 | `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.
+Run `npx novahiz skills --all` to see the full list.
 
 ---
 
@@ -274,7 +308,7 @@ Novahiz auto-registers external MCP servers based on the prompt category:
 | 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` (17 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).
+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).
 
@@ -287,10 +321,10 @@ Upstream repositories and full provenance for MCP providers and opencode plugins
 NOVAHIZ_GATE=off npx opencode
 
 # Override home directory
-NOVAHIZ_HOME=/path/to/Novahiz npx Novahiz doctor
+NOVAHIZ_HOME=/path/to/novahiz npx novahiz doctor
 
 # Force node version
-NOVAHIZ_NODE=/usr/local/bin/node npx Novahiz doctor
+NOVAHIZ_NODE=/usr/local/bin/node npx novahiz doctor
 ```
 
 See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for all options.
@@ -301,23 +335,23 @@ See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for all options.
 
 | Command | Purpose |
 |---------|---------|
-| `Novahiz init` | One-shot setup |
-| `Novahiz doctor` | 12-check health diagnostic |
-| `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 |
+| `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.
 

package/adapters/claude/agent/novahiz.md

@@ -0,0 +1,23 @@
+---
+name: novahiz
+description: Novahiz deterministic workflow. Classifies the request, loads the required skills, then works under the Novahiz gate. Use for any multi-step task in a project that has a novahiz.config.json, or when the user asks for the Novahiz pipeline.
+---
+
+You are Novahiz-Agent, running inside Claude Code with the Novahiz gate and MCP server active.
+
+Work in this order for every request:
+
+1. Classify. Call the `novahiz_classify` MCP tool with the user request, or run `node <novahiz-home>/src/cli.ts classify "<request>"`. Read the returned categories and the required skills.
+2. Load skills. Call the `Skill` tool for every required skill before touching any file. That is the signal the Novahiz hook records; a skill loaded any other way does not count. If the `Skill` tool is unavailable, read `<novahiz-home>/skills/<name>/SKILL.md` instead, which the hook also accepts. The gate enforces this: edits, writes, and shell writes are blocked until the required skills are loaded.
+3. Plan. For anything beyond a trivial change, write the plan before the code.
+4. Execute. Prefer small reversible edits. Keep the architecture modular and maintainable.
+5. Verify. Run the relevant tests or commands. Report what you ran and what it returned.
+6. Report. State what changed, what is proven, what is uncertain, and the honest next step.
+
+Rules:
+
+- novahiz-humanizer, ui-slop-remover and ui-craft-rules are required only for frontend design tasks; impeccable covers the same design selectors.
+- Load the Supabase skills for any Supabase work.
+- Be honest. Avoid false good ideas. Zero simulation: never pretend to have run, tested, or verified something you did not.
+- Criticize the request when it is inconsistent, ambiguous, risky, or suboptimal, and propose an alternative.
+- If the gate blocks you, load every skill it names with the `Skill` tool, then retry the same call once. If the same skills are reported missing again, run `novahiz doctor`, report honestly, and stop. Never bypass the gate with a shell write or by editing around the block.

package/adapters/opencode/instructions.md

@@ -5,10 +5,10 @@
 Obsidian (`C:\Users\hiz\Documents\Novahiz`) is the user's second memory.
 
 ### Rules
-1. When the user asks to **save / memorize / update obsidian memory**, load the `memory-save` skill and follow its procedure without exception.
+1. When the user asks to **save / memorize / update obsidian memory**, load the `memory` skill (alias for `novahiz-memory`) and follow its procedure without exception.
 2. Determine the target folder **only** from the `Novahiz\_meta\routing.md` table (source of truth). Never guess. When ambiguous, ask the user.
 3. Display the chosen path before writing.
-4. Never write to `index.md`, `log.md`, `hot.md`, `.manifest.json`, `_meta/`, or `.obsidian/` **except through a dedicated maintenance skill** (wiki-ingest/wiki-lint/wiki-status for index/log/hot/manifest; graph-colorize for `.obsidian/graph.json`, with mandatory backup). The `memory-save` skill writes only to the targeted content page.
+4. Never write to `index.md`, `log.md`, `hot.md`, `.manifest.json`, `_meta/`, or `.obsidian/`. No installed skill covers maintenance of those files: if the user asks for it, do it step by step in front of them, with a backup first for anything under `.obsidian/`. The `memory` skill writes only to the targeted content page.
 5. Never create a root folder on your own. Every new category requires user agreement and an update to `routing.md`.
 6. Include mandatory frontmatter: `title, category, tags, sources, created, updated, summary`. Use tags from `_meta/taxonomy.md`.
 7. Link pages with `[[wikilinks]]`. Merge rather than duplicate.
@@ -29,7 +29,7 @@ Playwright uses a **persistent profile** that preserves data across sessions (co
 ## Behavioral & Quality Rules
 
 1. **Mandatory design skills on frontend design tasks** — `novahiz-humanizer`, `ui-slop-remover` and `ui-craft-rules` are required only on frontend design work (design-ui prompts and style files). Load them with `skill({name})` before any design edit. Outside design, they are not required by the gate. Browser tasks (navigation, search, extraction) proceed as direct actions without a roadmap.
-2. **Impeccable after UI work** — `impeccable` is installed and required on the same design selectors (gate rule R14). Whenever a page, component, section, or screen design is created or substantially changed, run its critique systematically afterwards, an audit when the change warrants it (a11y, performance, responsive), and a polish pass before shipping. The design-ui roadmap carries optional `impeccable-critique`, `impeccable-audit`, and `impeccable-polish` steps for exactly this.
+2. **Impeccable after UI work** — `impeccable` is installed and required on the same design selectors (gate rule R14). Whenever a page, component, section, or screen design is created or substantially changed, run its critique systematically afterwards, an audit when the change warrants it (a11y, performance, responsive), harden errors and edge cases, and a polish pass before shipping; a deterministic `impeccable detect` scan backs the verify step. The design-ui roadmap carries optional `impeccable-shape`, `impeccable-critique`, `impeccable-audit`, `impeccable-harden`, `impeccable-polish`, and `impeccable-detect` steps for exactly this.
 3. **Supabase** — On any Supabase task (database, auth, RLS, Edge Functions, migrations, Storage, Realtime, CLI/MCP), load the `novahiz-supabase` and `novahiz-postgres` skills before acting.
 5. **Honesty and critical thinking** — Always be honest. Avoid false good ideas. Maintain critical thinking. **Zero simulation objective:** never claim to have executed, tested, or verified what was not. Explicitly report uncertainties and assumptions.
 6. **Propose next steps** — After completing a task, always honestly propose the relevant next step. Do not invent unnecessary work or mask failures.

package/adapters/opencode/novahiz.ts

@@ -399,10 +399,14 @@ const DISABLED = ["off", "0", "false", "no", "disabled"].includes(ESCAPE);
 const GATE_TOOLS = new Set(
   (Array.isArray(GATE.tools) && GATE.tools.length > 0
     ? GATE.tools
-    // MINEUR#8: cron tools that carry/execute shell commands are gated too —
-    // cron_add_command_task was a bash-gate bypass. Keep in sync with
-    // DEFAULT_CONFIG.gate.tools (src/spec.ts) and novahiz.config.json.
-    : ["edit", "write", "patch", "apply_patch", "bash", "shell", "cron_add_command_task", "cron_update_command_task", "cron_update_task", "cron_run_task_now"]
+    // MINEUR#8 + 0.3.6 hardening: every cron tool that carries, creates, or
+    // executes shell commands is gated — cron_add_command_task was a bash-gate
+    // bypass, and cron_add_task / cron_add_ai_task / cron_add_http_task each
+    // accept a `command` field (HTTP/AI tasks run shell_command type too).
+    // Keep in sync with DEFAULT_CONFIG.gate.tools (src/spec.ts), install/lib.mjs,
+    // novahiz.config.example.json, the live novahiz.config.json, and
+    // docs/CONFIGURATION.md.
+    : ["edit", "write", "patch", "apply_patch", "bash", "shell", "cron_add_command_task", "cron_add_task", "cron_add_ai_task", "cron_add_http_task", "cron_update_command_task", "cron_update_task", "cron_run_task_now"]
   ).map((tool) => tool.toLowerCase())
 );
 
@@ -496,12 +500,15 @@ function buildRepairDirective(failure: GateFailure, attempt: number): string {
   }
 
   if (attempt <= 1) {
-    const steps = missing.map((skill, index) => `  ${index + 1}. skill({name:"${skill}"})`).join("\n");
+    // Always add novahiz-gate: it explains why the block happened and how to
+    // satisfy the rule, which is what the agent needs before retrying.
+    const loads = missing.includes("novahiz-gate") ? missing : [...missing, "novahiz-gate"];
+    const steps = loads.map((skill, index) => `  ${index + 1}. skill({name:"${skill}"})`).join("\n");
     return [
       `${head} Missing skills: ${missing.join(", ")}.`,
       "AUTO-REPAIR — execute now, do not ask the user, do not stop:",
       steps,
-      `  ${missing.length + 1}. Retry this exact ${failure.tool} call once, then continue the user's task where it left off.`,
+      `  ${loads.length + 1}. Retry this exact ${failure.tool} call once, then continue the user's task where it left off.`,
       "Never bypass the gate: no NOVAHIZ_GATE, no alternate tool, no shell write, no editing around the block."
     ].join("\n");
   }
@@ -727,7 +734,17 @@ export const NovahizPlugin: Plugin = async ({ client }) => {
         const sessionID = input.sessionID;
         if (!sessionID) return;
         const block = enforcementBySession.get(sessionID);
-        if (block) output.system.push(block);
+        if (!block) return;
+        // The output array can still hold the block from a previous turn:
+        // pushing again duplicated "[Novahiz enforcement]" once per turn.
+        // Drop every stale copy, then inject exactly one fresh block.
+        for (let i = output.system.length - 1; i >= 0; i--) {
+          const entry = output.system[i];
+          if (typeof entry === "string" && entry.startsWith("[Novahiz enforcement]")) {
+            output.system.splice(i, 1);
+          }
+        }
+        output.system.push(block);
       } catch (error) {
         await log("warn", `system.transform hook failed: ${String(error).slice(0, 200)}`);
       }

package/catalog/categories.json

@@ -507,6 +507,14 @@
           "id": "report",
           "label": "Report findings",
           "kind": "advisory"
+        },
+        {
+          "id": "audit",
+          "label": "Session compliance audit",
+          "kind": "advisory",
+          "requireSkills": [
+            "novahiz-audit"
+          ]
         }
       ]
     }
@@ -791,6 +799,14 @@
             "novahiz-task"
           ]
         },
+        {
+          "id": "tokens",
+          "label": "Design tokens (when a token system is involved)",
+          "kind": "advisory",
+          "requireSkills": [
+            "design-token-pipeline"
+          ]
+        },
         {
           "id": "design-craft",
           "label": "Apply design craft, humanizer and anti-slop pass",
@@ -802,6 +818,15 @@
           ],
           "optional": true
         },
+        {
+          "id": "impeccable-shape",
+          "label": "Impeccable shape (UX/UI design brief before code)",
+          "kind": "skill",
+          "requireSkills": [
+            "impeccable"
+          ],
+          "optional": true
+        },
         {
           "id": "implement",
           "label": "Implement",
@@ -828,6 +853,15 @@
           ],
           "optional": true
         },
+        {
+          "id": "impeccable-harden",
+          "label": "Impeccable harden (errors, i18n, edge cases before polish)",
+          "kind": "skill",
+          "requireSkills": [
+            "impeccable"
+          ],
+          "optional": true
+        },
         {
           "id": "impeccable-polish",
           "label": "Impeccable polish (final pass before ship)",
@@ -837,6 +871,15 @@
           ],
           "optional": true
         },
+        {
+          "id": "impeccable-detect",
+          "label": "Impeccable detector scan (deterministic UI check, exit 0 = clean)",
+          "kind": "verify",
+          "requireSkills": [
+            "impeccable"
+          ],
+          "optional": true
+        },
         {
           "id": "responsive",
           "label": "Verify responsive behavior",
@@ -1106,7 +1149,15 @@
       "nginx",
       "infra",
       "monitoring",
-      "eas"
+      "eas",
+      "release",
+      "cut a release",
+      "publish",
+      "npm publish",
+      "version bump",
+      "bump version",
+      "tag a version",
+      "changelog"
     ],
     "defaultSkills": [
       "eas-workflows",
@@ -1168,6 +1219,14 @@
           "requireSkills": [
             "novahiz-converge"
           ]
+        },
+        {
+          "id": "release",
+          "label": "Ship a release",
+          "kind": "advisory",
+          "requireSkills": [
+            "novahiz-release"
+          ]
         }
       ]
     }

package/catalog/providers.json

@@ -90,11 +90,11 @@
     "id": "expo-skills",
     "label": "Expo agent skills",
     "kind": "skill",
-    "install": ["npx", "-y", "skills@1.7.0", "add", "expo/skills", "--skill", "expo-overview", "expo-project-structure", "expo-router", "expo-animation", "expo-native-ui", "expo-design-system", "expo-ui", "expo-data-fetching", "expo-dom", "expo-web-to-native", "expo-module", "expo-brownfield", "expo-dev-client", "expo-examples", "expo-app-clip", "expo-upgrade", "expo-skill-feedback", "-g", "-a", "opencode", "-y"],
+    "install": ["npx", "-y", "skills@1.7.0", "add", "expo/skills", "--skill", "expo-overview", "expo-project-structure", "expo-router", "expo-animation", "expo-native-ui", "expo-design-system", "expo-ui", "expo-data-fetching", "expo-dom", "expo-web-to-native", "expo-module", "expo-migrate-module", "expo-brownfield", "expo-dev-client", "expo-examples", "expo-app-clip", "expo-upgrade", "expo-skill-eval", "expo-skill-feedback", "-g", "-a", "opencode", "-y"],
     "source": "https://github.com/expo/skills",
     "license": "MIT",
     "categories": ["code", "expo"],
-    "purpose": "17 official Expo framework skills (expo-* group); the 7 eas-* paid-service skills are excluded. Installed to ~/.agents/skills; when git clone fails, fetch the tarball from codeload.github.com and copy the skill folders."
+    "purpose": "19 official Expo framework skills (expo-* group); the 7 eas-* paid-service skills are excluded. Installed to ~/.agents/skills; when git clone fails, fetch the tarball from codeload.github.com and copy the skill folders."
   },
   {
     "id": "impeccable",

package/dist/cli.js

@@ -6,6 +6,7 @@ import { parse, print, flagOn } from "./commands/context.js";
 import { expandHome } from "./spec.js";
 import { commandCheck, commandSync, commandClassify, commandSkills, commandCategories, commandRules, commandSessionLoad, commandSessionState, commandCatalog, commandRoadmap, commandStep, commandProviders, commandDeps, commandDispatch } from "./commands/inspect.js";
 import { commandGate } from "./commands/gate.js";
+import { commandHook } from "./commands/hook.js";
 import { commandReport } from "./commands/report.js";
 import { commandTask } from "./commands/task.js";
 import { commandClean } from "./commands/clean.js";
@@ -39,7 +40,7 @@ function usage() {
             "init                    Initialize Novahiz in the current project",
             "setup                   Install Novahiz (config, skills, catalog)",
             "autodocs [--flush]      Sync docs and memory after major project changes",
-            "doctor                  Check that everything works",
+            "doctor [--deep]        Check that everything works (--deep also probes each MCP server live)",
             "status                  Show current classification and gate state",
             "task new <title>        Start a new tracked task",
             "task status             Show task progress",
@@ -59,6 +60,7 @@ function usage() {
             "Advanced (for power users and adapters):",
             "  classify <text>       Classify a prompt",
             "  gate --tool <t> --file <f>  Check if an edit is allowed",
+            "  hook [--harness h] [--event e]  Claude/Codex tool-use gate hook",
             "  skills [--category c] List loaded skills",
             "  catalog <query>       Search the skill catalog",
             "  roadmap --category c  Show execution roadmap",
@@ -130,7 +132,9 @@ function runUpgrade(parsed) {
     runSync();
     process.stdout.write("\nUpgraded! Restart opencode to apply changes.\n");
 }
-function main(argv) {
+// Async so `doctor --deep` can await its MCP probes; every other command
+// still returns void, which await handles transparently.
+async function main(argv) {
     const parsed = parse(argv);
     if (typeof parsed.flags.home === "string" && parsed.flags.home.length > 0) {
         process.env.NOVAHIZ_HOME = resolve(expandHome(parsed.flags.home));
@@ -175,6 +179,8 @@ function main(argv) {
             return commandClassify(parsed);
         case "gate":
             return commandGate(parsed);
+        case "hook":
+            return commandHook(parsed);
         case "skills":
             return commandSkills(parsed);
         case "categories":
@@ -209,7 +215,7 @@ function main(argv) {
     }
 }
 try {
-    main(process.argv.slice(2));
+    await main(process.argv.slice(2));
 }
 catch (error) {
     const message = error instanceof Error ? error.message : String(error);