@softspark/ai-toolkit 4.2.4 → 4.3.0

package/kb/reference/extension-api.md

@@ -2,11 +2,11 @@
 title: "Extension API Reference"
 category: reference
 service: ai-toolkit
-tags: [extension-api, inject-rule, inject-hook, mcp-templates, integration, editors]
-version: "1.4.0"
+tags: [extension-api, inject-rule, inject-hook, inject-mcp, mcp-templates, integration, editors]
+version: "1.5.0"
 created: "2026-04-07"
-last_updated: "2026-04-15"
-description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, remove-rule, remove-hook, and editor-aware MCP template management."
+last_updated: "2026-05-12"
+description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, inject-mcp, remove-* variants, and editor-aware MCP template management."
 ---
 
 # Extension API Reference
@@ -25,8 +25,10 @@ This design is intentional: ai-toolkit is a generic toolkit. Consumers (MCP serv
 | `remove-rule <name>` | `~/.claude/CLAUDE.md` | Strip markers by block name | Yes |
 | `inject-hook <file.json\|url> [name]` | `~/.claude/settings.json` | JSON `_source` tag per entry, URL cached + registered | Yes |
 | `remove-hook <name>` | `~/.claude/settings.json` | Strip all entries with matching `_source`, unregister URL source | Yes |
+| `inject-mcp <file.json\|url> [name] [--force]` | `~/.mcp.json` + every editor with `global_path` | JSON `_source` tag per server, URL cached + registered, full editor propagation | Yes |
+| `remove-mcp <name>` | `~/.mcp.json` + every editor with `global_path` | Strip all servers with matching `_source`, clean editor configs, unregister URL | Yes |
 | `add-rule <file.md\|url>` | `~/.softspark/ai-toolkit/rules/` | File copy + re-inject all rules on next `update` | Yes |
-| `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from template | Yes |
+| `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from built-in template | Yes |
 | `mcp install --editor <name...>` | Native editor MCP config | Render canonical template into editor format | Yes |
 
 ## inject-rule
@@ -115,6 +117,67 @@ npx @softspark/ai-toolkit remove-hook my-tool-hooks
 
 The argument is the source name (file stem used during `inject-hook`). If no entries with that source are present, the command exits 0 silently.
 
+## inject-mcp
+
+Injects an external MCP server template into `~/.mcp.json` (toolkit source-of-truth) and propagates it to every editor that exposes a `global_path` in `EDITOR_SPECS`. Symmetric with `inject-hook` -- accepts both local file paths and HTTPS URLs, with cache + auto-refresh on `ai-toolkit update`.
+
+```bash
+# From local file
+npx @softspark/ai-toolkit inject-mcp ./rag-mcp-template.json
+
+# From URL (cached locally, auto-refreshed on update)
+npx @softspark/ai-toolkit inject-mcp https://example.com/rag-mcp-template.json
+
+# With explicit source name (preferred when filename stem is generic)
+npx @softspark/ai-toolkit inject-mcp ./mcp/mcp-template.json --name rag-mcp
+
+# With explicit target dir
+npx @softspark/ai-toolkit inject-mcp ./template.json /custom/target --name my-rag
+
+# Force overwrite of servers with a different _source (collision resolution)
+npx @softspark/ai-toolkit inject-mcp ./conflict.json --force
+```
+
+**Flags:** `--name <name>` overrides the auto-derived source name (works for both local files and URLs). `--force` overwrites servers tagged with a different `_source`. Positional `template-name` is supported only for URL sources (legacy positional grammar inherited from `inject-hook`); for local files use `--name`.
+
+**Implementation:** `scripts/inject_mcp_cli.py`, `scripts/mcp_sources.py`, `scripts/url_fetch.py`.
+
+**Input format:** Same as built-in templates in `app/mcp-templates/`:
+```json
+{
+  "name": "rag-mcp",
+  "description": "Multi-tenant RAG over knowledge bases",
+  "mcpServers": {
+    "rag-mcp": {
+      "type": "http",
+      "url": "http://localhost:8081/mcp/sse?secret_key=${RAG_MCP_SECRET_KEY}"
+    }
+  }
+}
+```
+
+**Source name derivation:** `rag-mcp-template.json` → `"rag-mcp-template"`. For URLs: `https://example.com/rag-mcp-template.json` → `"rag-mcp-template"`. Every server in the `mcpServers` block is tagged with `"_source": "<source-name>"` inside `~/.mcp.json` only; native editor configs receive the same servers **without** the `_source` field (some clients reject unknown keys).
+
+**URL support:** When an HTTPS URL is provided, the JSON is fetched, validated, cached in `~/.softspark/ai-toolkit/mcp-templates/external/<name>.json`, and registered in `sources.json`. On every `ai-toolkit update`, URL-sourced templates are re-fetched and re-injected automatically. If the fetch fails during update, the cached version is used.
+
+**Editor propagation:** Every editor with a `global_path` in `EDITOR_SPECS` is updated -- Claude (`~/.claude.json`), Cursor (`~/.cursor/mcp.json`), GitHub Copilot (`~/.copilot/mcp-config.json`), Gemini CLI (`~/.gemini/settings.json`), Windsurf (`~/.codeium/windsurf/mcp_config.json`), Cline (`~/.cline/data/settings/cline_mcp_settings.json`), Augment (`~/.augment/settings.json`), Codex CLI (`~/.codex/config.toml`). Per-editor failures are non-fatal -- the command reports a warning and continues.
+
+**Idempotency:** Re-running with the same source overwrites entries for that source cleanly -- no duplicates accumulate.
+
+**Collisions:** If a server name in `~/.mcp.json` already exists under a *different* `_source` tag, the command exits with code 3 unless `--force` is passed. Entries tagged `"_source": "ai-toolkit"` are protected even with `--force` -- the built-in template namespace cannot be hijacked.
+
+**Safety:** Only HTTPS URLs are accepted. The source name `ai-toolkit` is reserved.
+
+## remove-mcp
+
+Strips all server entries from `~/.mcp.json` that carry a given `_source` tag, cleans the same server names from every editor `global_path`, and (if URL-sourced) unregisters from `sources.json` and removes the cached file.
+
+```bash
+npx @softspark/ai-toolkit remove-mcp rag-mcp-template
+```
+
+The argument is the source name (file stem used during `inject-mcp`). If no entries with that source are present, the command exits 0 silently. `ai-toolkit` source is reserved and cannot be removed via this command.
+
 ## mcp add / install
 
 Merges one or more MCP server templates from `app/mcp-templates/` into the project's `.mcp.json`.
@@ -153,6 +216,8 @@ When `install` runs with `--scope project`, ai-toolkit also updates `.mcp.json`
 │    remove-rule  <name>        → CLAUDE.md            │
 │    inject-hook  <file|url>    → settings.json        │
 │    remove-hook  <name>        → settings.json        │
+│    inject-mcp   <file|url>    → .mcp.json + editors  │
+│    remove-mcp   <name>        → .mcp.json + editors  │
 │    add-rule     <file|url>    → rules/ registry      │
 │    mcp add      <template>    → .mcp.json            │
 │    mcp install  <template>    → editor-native MCP    │
@@ -168,7 +233,7 @@ When `install` runs with `--scope project`, ai-toolkit also updates `.mcp.json`
    (consumer)       (consumer)      (consumer)
 ```
 
-## Example: Registering Rules and Hooks from an External Tool
+## Example: Registering Rules, Hooks, and MCP Servers from an External Tool
 
 An external tool's install script would call:
 
@@ -176,14 +241,14 @@ An external tool's install script would call:
 # Register rules into CLAUDE.md
 npx @softspark/ai-toolkit inject-rule ./rules/my-tool-rules.md
 
-# Register hooks into settings.json
+# Register hooks into settings.json (auto-propagates to Codex)
 npx @softspark/ai-toolkit inject-hook ./hooks/my-tool-hooks.json
 
-# Add an MCP server template
-npx @softspark/ai-toolkit mcp add github
+# Register MCP server template into .mcp.json + all editor MCP configs
+npx @softspark/ai-toolkit inject-mcp ./mcp-template.json
 
-# Render the same template into Cursor project config
-npx @softspark/ai-toolkit mcp install --editor cursor --scope project github --target .
+# Alternative: pull MCP template from a URL (auto-refreshed on update)
+npx @softspark/ai-toolkit inject-mcp https://example.com/mcp-template.json
 ```
 
 To uninstall:
@@ -191,6 +256,7 @@ To uninstall:
 ```bash
 npx @softspark/ai-toolkit remove-rule my-tool-rules
 npx @softspark/ai-toolkit remove-hook my-tool-hooks
+npx @softspark/ai-toolkit remove-mcp my-tool
 ```
 
 All operations are idempotent — safe to run on every install or update.

package/kb/reference/hooks-catalog.md

@@ -13,7 +13,7 @@ description: "Complete reference of all ai-toolkit hooks: events, scripts, insta
 
 ## Overview
 
-ai-toolkit provides 22 global hook entries across 12 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.softspark/ai-toolkit/hooks/`.
+ai-toolkit provides 28 global hook entries across 14 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.softspark/ai-toolkit/hooks/`.
 
 ## Supported Surface
 
@@ -327,6 +327,114 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
 **Action:** Captures an environment snapshot to `~/.softspark/ai-toolkit/sessions/current-context.json`. Records working directory, git branch, git status summary, Node.js version, Python version, and timestamp. Used by other hooks and tools to access session metadata without re-running discovery commands. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
+---
+
+## New Hooks (Constitution Art. VI Enforcement)
+
+These six hooks turn Constitution Article VI ("Repair Discipline") from prose into executable enforcement. Each one closes a specific gap that previously relied on agent goodwill.
+
+### PreToolUse (revert protection) — `revert-guard.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `PreToolUse` |
+| Matcher | `Bash` |
+| Script | `~/.softspark/ai-toolkit/hooks/revert-guard.sh` |
+| Fires | Before any Bash command |
+
+**Action:** Blocks (exit 2) `git checkout/restore -- <file>`, `git reset --hard`, or `git clean -fd` when the affected files were edited in the current session (per `session_state.py` log). Forces the agent to fix root causes instead of reverting work-in-progress (Art. VI.2). Branch switches (`git checkout main`) and reverts on untouched files pass through unchanged.
+
+**Override (one-off):** `CLAUDE_REVERT_OK=1`. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
+### PostToolUse (test cohesion) — `test-cohesion.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `PostToolUse` |
+| Matcher | `Edit\|MultiEdit\|Write` |
+| Script | `~/.softspark/ai-toolkit/hooks/test-cohesion.sh` |
+| Fires | After every file edit |
+
+**Action:** Runs the test commands mapped to the edited path via `test-cohesion-map.json`. Lookup order: project-local `.claude/test-cohesion-map.json`, then toolkit default `app/hooks/test-cohesion-map.json`. Blocks (exit 2) when the related test command fails. Runs **only** related tests, not the full suite (one of the user-stated requirements).
+
+Map schema:
+```json
+[
+  {
+    "match": "src/auth/*.py",
+    "tests": ["tests/test_auth.py"],
+    "runner": "pytest",
+    "command": null
+  }
+]
+```
+First-match-wins per file. Built-in runners: `bats`, `pytest`, `vitest`, `jest`. Use `"command"` for full overrides.
+
+**Overrides:** `CLAUDE_SKIP_COHESION=1` (one-off), `CLAUDE_HOOK_BOOTSTRAP=1` (when editing the hook itself). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
+### PostToolUse (search-first tracker) — `search-tracker.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `PostToolUse` |
+| Matcher | `mcp__rag-mcp__smart_query\|mcp__rag-mcp__hybrid_search_kb\|mcp__rag-mcp__crag_search\|mcp__rag-mcp__multi_hop_search\|mcp__rag-mcp__verify_answer\|WebSearch\|WebFetch` |
+| Script | `~/.softspark/ai-toolkit/hooks/search-tracker.sh` |
+| Fires | After any search-style tool call |
+
+**Action:** Clears `~/.softspark/ai-toolkit/state/search-required.flag`. Pairs with `user-prompt-submit.sh` (sets flag on long technical prompts only when a search provider is detected or strict mode is enabled) and `stop-search-check.sh` (blocks Stop if flag still set). Together they enforce the global CLAUDE.md GOLDEN RULE without breaking offline/no-RAG installs.
+
+Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
+### Stop (search-first enforcement) — `stop-search-check.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `Stop` |
+| Matcher | *(all)* |
+| Script | `~/.softspark/ai-toolkit/hooks/stop-search-check.sh` |
+| Fires | When Claude finishes a response |
+
+**Action:** If `search-required.flag` is still present (no search tool ran during this turn) and a search provider is still detectable, emits `{"decision":"block","reason":"..."}` to continue the conversation with a search-first reminder. If no RAG/Web provider is detected, it clears the stale flag and exits 0, so offline/no-MCP users are not blocked.
+
+**Overrides:** `CLAUDE_SKIP_SEARCH_FIRST=1`, `AI_TOOLKIT_SEARCH_FIRST=off`, or `AI_TOOLKIT_SEARCH_FIRST=strict` to force enforcement. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
+### InstructionsLoaded — `instructions-audit.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `InstructionsLoaded` |
+| Matcher | *(all)* |
+| Script | `~/.softspark/ai-toolkit/hooks/instructions-audit.sh` |
+| Fires | Whenever CLAUDE.md / `.claude/rules/*.md` is loaded into context |
+
+**Action:** Appends `<ts>\t<memory_type>\t<load_reason>\t<file_path>` to `~/.softspark/ai-toolkit/state/loaded-instructions.log`. Provides audit visibility: when a rule does NOT enter context (silently dropped, token budget, glob miss), the absence is observable. Auto-rotates at 2000 lines.
+
+Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
+### ConfigChange — `config-desync-guard.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `ConfigChange` |
+| Matcher | `user_settings` |
+| Script | `~/.softspark/ai-toolkit/hooks/config-desync-guard.sh` |
+| Fires | When `~/.claude/settings.json` changes |
+
+**Action:** Compares `_source: ai-toolkit` entries between `~/.claude/settings.json` (installed) and the toolkit source `app/hooks.json`. If they diverge (missing/stale entries), emits an advisory to stderr suggesting `ai-toolkit update` or `ai-toolkit doctor --fix`. Non-blocking by design — user's legitimate settings edits never get rejected.
+
+**Override (silence advisory):** `CLAUDE_SKIP_CONFIG_DESYNC=1`. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
+### Supporting Infrastructure
+
+| Component | Purpose |
+|-----------|---------|
+| `scripts/session_state.py` | Append-only edit log keyed by session_id. Cleared on SessionStart. Read by revert-guard, test-cohesion, quality-gate. |
+| `scripts/test_cohesion.py` | Resolves changed paths → test commands via cohesion map. First-match-wins. Stdlib-only. |
+| `app/hooks/test-cohesion-map.json` | Toolkit-default path → tests mapping (used when no project map exists). |
+| `app/hooks/_locate-toolkit.sh` | Shared bash helper that exports `$TOOLKIT_DIR` for hooks needing scripts/. |
+| `app/hooks/_hook-io.sh` | Shared bash helper that normalizes hook payloads across Claude, Augment, Gemini, Windsurf, and Cursor-style JSON. |
+| `app/hooks/_search-capability.sh` | Shared bash helper that enables search-first blocking only when RAG/Web is configured or strict mode is requested. |
+
 ## Runtime Profiles
 
 Set in `.claude/settings.local.json`:
@@ -346,42 +454,59 @@ Set in `.claude/settings.local.json`:
 ```
 ~/.softspark/ai-toolkit/
 ├── rules/          # Registered rules (add-rule.sh)
+├── state/          # Per-session runtime state (NEW)
+│   ├── session-edits.json         # Append-only edit log per session
+│   ├── search-required.flag       # Set by user-prompt-submit, cleared by search-tracker
+│   ├── loaded-instructions.log    # Audit trail of which rules entered context
+│   └── test-cohesion-last.log     # Last cohesion test command output
 └── hooks/          # Hook scripts (copied on install)
-    ├── _profile-check.sh    # Shared: profile skip logic (sourced by hooks)
+    ├── _profile-check.sh         # Shared: profile skip logic (sourced by hooks)
+    ├── _locate-toolkit.sh        # NEW: shared $TOOLKIT_DIR locator
+    ├── _hook-io.sh               # NEW: shared multi-editor payload/output adapter
+    ├── _search-capability.sh     # NEW: capability-aware search-first enforcement
     ├── session-start.sh
-    ├── session-context.sh   # NEW: capture session env snapshot
+    ├── session-context.sh
     ├── guard-destructive.sh
     ├── guard-path.sh
-    ├── guard-config.sh      # NEW: block config file edits
-    ├── mcp-health.sh        # NEW: check MCP runtime availability
-    ├── user-prompt-submit.sh
-    ├── post-tool-use.sh
-    ├── governance-capture.sh # NEW: log security-sensitive operations
+    ├── guard-config.sh
+    ├── revert-guard.sh           # NEW: block revert on session-edited files (Art. VI.2)
+    ├── mcp-health.sh
+    ├── user-prompt-submit.sh     # extended: arms search-required flag
+    ├── post-tool-use.sh          # extended: appends edits to session state
+    ├── governance-capture.sh
+    ├── test-cohesion.sh          # NEW: runs mapped tests after edits (Art. VI.3)
+    ├── test-cohesion-map.json    # NEW: path → tests mapping
+    ├── search-tracker.sh         # NEW: clears search-required flag
     ├── quality-check.sh
-    ├── quality-gate.sh
+    ├── quality-gate.sh           # extended: cohesion-tests session edits
+    ├── stop-search-check.sh      # NEW: enforces search-first on Stop
     ├── save-session.sh
     ├── subagent-start.sh
     ├── subagent-stop.sh
     ├── track-usage.sh
     ├── pre-compact.sh
-    ├── pre-compact-save.sh  # NEW: timestamped context snapshot
-    ├── commit-quality.sh    # NEW: advisory commit message check
+    ├── pre-compact-save.sh
+    ├── commit-quality.sh
+    ├── instructions-audit.sh     # NEW: logs CLAUDE.md / rules loads
+    ├── config-desync-guard.sh    # NEW: warns on settings ↔ source drift
     └── session-end.sh
 
 ~/.claude/settings.json
 └── hooks:          # Hook definitions referencing ~/.softspark/ai-toolkit/hooks/
-    ├── SessionStart     → session-start.sh, mcp-health.sh, session-context.sh
-    ├── Notification     → osascript (inline)
-    ├── PreToolUse       → guard-destructive.sh, guard-path.sh, guard-config.sh, commit-quality.sh
-    ├── UserPromptSubmit → user-prompt-submit.sh, track-usage.sh
-    ├── PostToolUse      → post-tool-use.sh, governance-capture.sh
-    ├── Stop             → quality-check.sh, save-session.sh, quality-gate.sh
-    ├── TaskCompleted    → quality-gate.sh
-    ├── TeammateIdle     → echo (inline)
-    ├── SubagentStart    → subagent-start.sh
-    ├── SubagentStop     → subagent-stop.sh
-    ├── PreCompact       → pre-compact.sh, pre-compact-save.sh
-    └── SessionEnd       → session-end.sh
+    ├── SessionStart       → session-start.sh, mcp-health.sh, session-context.sh
+    ├── Notification       → notify-waiting.sh
+    ├── PreToolUse         → guard-destructive.sh, guard-path.sh, guard-config.sh, commit-quality.sh, revert-guard.sh
+    ├── UserPromptSubmit   → user-prompt-submit.sh, track-usage.sh
+    ├── PostToolUse        → post-tool-use.sh, governance-capture.sh, test-cohesion.sh, search-tracker.sh
+    ├── Stop               → quality-check.sh, save-session.sh, quality-gate.sh, stop-search-check.sh
+    ├── TaskCompleted      → quality-gate.sh
+    ├── TeammateIdle       → echo (inline)
+    ├── SubagentStart      → subagent-start.sh
+    ├── SubagentStop       → subagent-stop.sh
+    ├── PreCompact         → pre-compact.sh, pre-compact-save.sh
+    ├── SessionEnd         → session-end.sh
+    ├── InstructionsLoaded → instructions-audit.sh
+    └── ConfigChange       → config-desync-guard.sh
 ```
 
 **Key design decisions:**
@@ -399,7 +524,7 @@ Set in `.claude/settings.local.json`:
 
 **Hook script not found:**
 ```bash
-ls ~/.softspark/ai-toolkit/hooks/     # should list 21 .sh files (plus _profile-check.sh helper)
+ls ~/.softspark/ai-toolkit/hooks/     # should list 27 .sh files (plus _profile-check.sh + _locate-toolkit.sh + _hook-io.sh + _search-capability.sh helpers + test-cohesion-map.json)
 ai-toolkit update            # re-copies scripts
 ```
 

package/kb/reference/mcp-templates.md

@@ -2,11 +2,11 @@
 title: "MCP Server Templates"
 category: reference
 service: ai-toolkit
-tags: [mcp, templates, servers, configuration, editors]
-version: "1.1.0"
+tags: [mcp, templates, servers, configuration, editors, inject-mcp, external-templates]
+version: "1.2.0"
 created: "2026-04-07"
-last_updated: "2026-04-12"
-description: "Reference for 26 MCP server templates plus native editor MCP installation support."
+last_updated: "2026-05-12"
+description: "Reference for 26 built-in MCP server templates, external template injection via inject-mcp, and native editor MCP installation support."
 ---
 
 # MCP Server Templates
@@ -15,6 +15,8 @@ description: "Reference for 26 MCP server templates plus native editor MCP insta
 
 ai-toolkit ships 26 ready-to-use MCP server configuration templates in `app/mcp-templates/`. Each template is a JSON file that defines the canonical `mcpServers` block for a specific service. Templates can be merged into the project's `.mcp.json` and rendered into editor-native MCP config files via the `ai-toolkit mcp` CLI subcommand.
 
+**External templates:** Tools outside the toolkit (MCP servers, plugins, custom integrations) can register their own MCP templates via `ai-toolkit inject-mcp <file|url>` -- the toolkit caches the template, tags every server with a `_source` field, and propagates the config to every editor that exposes a `global_path`. URL-sourced templates are auto-refreshed on every `ai-toolkit update`. See [PATH: kb/reference/extension-api.md] for the inject-mcp / remove-mcp reference.
+
 ## CLI
 
 ```bash

package/kb/reference/unique-features.md

@@ -21,11 +21,11 @@ Unlike other toolkits that put safety rules in documentation only, ai-toolkit en
 
 Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are copied to `~/.softspark/ai-toolkit/hooks/` on install and referenced from `~/.claude/settings.json`. Easy to read, debug, and extend.
 
-**12 lifecycle events / 22 global hook entries:**
+**14 lifecycle events / 28 global hook entries:**
 
 | Event | Script | Action |
 |-------|--------|--------|
-| SessionStart | `session-start.sh` | MANDATORY rules reminder + session context + instincts |
+| SessionStart | `session-start.sh` | MANDATORY rules reminder + session context + instincts + reset session-edit state |
 | SessionStart | `mcp-health.sh` | Check MCP server command availability (non-blocking warning) |
 | SessionStart | `session-context.sh` | Capture environment snapshot to `~/.softspark/ai-toolkit/sessions/current-context.json` |
 | Notification | `notify-waiting.sh` | Cross-platform desktop notification |
@@ -33,19 +33,25 @@ Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are
 | PreToolUse | `guard-path.sh` | Block wrong-user path hallucination |
 | PreToolUse | `guard-config.sh` | Block edits to linter/formatter config files unless explicitly requested |
 | PreToolUse | `commit-quality.sh` | Advisory validation of git commit messages |
-| UserPromptSubmit | `user-prompt-submit.sh` | Prompt governance reminder |
+| PreToolUse | `revert-guard.sh` | Block `git checkout/restore/reset --hard/clean` on files edited this session (Art. VI.2) |
+| UserPromptSubmit | `user-prompt-submit.sh` | Prompt governance reminder + arm search-first flag only when RAG/Web is available |
 | UserPromptSubmit | `track-usage.sh` | Record skill invocations to local stats |
-| PostToolUse | `post-tool-use.sh` | Lightweight validation reminders after edits |
+| PostToolUse | `post-tool-use.sh` | Lightweight validation reminders + append edit to session state |
 | PostToolUse | `governance-capture.sh` | Log security-sensitive operations to JSONL |
+| PostToolUse | `test-cohesion.sh` | Run cohesion-mapped tests after edits; block on failure (Art. VI.3) |
+| PostToolUse | `search-tracker.sh` | Clear search-first flag when smart_query/hybrid_search_kb/Web* runs |
 | Stop | `quality-check.sh` | Multi-language lint (ruff/tsc/phpstan/dart/go) |
 | Stop | `save-session.sh` | Persist session context for cross-session continuity |
-| Stop | `quality-gate.sh` | Block final response on lint/type errors |
+| Stop | `quality-gate.sh` | Block final response on lint/type errors + cohesion tests for session edits |
+| Stop | `stop-search-check.sh` | Continue conversation if search-first rule was skipped and a provider exists; no-op offline |
 | TaskCompleted | `quality-gate.sh` | Block task completion on lint/type errors |
 | SubagentStart | `subagent-start.sh` | Narrow-scope reminder for spawned subagents |
 | SubagentStop | `subagent-stop.sh` | Completion checklist for subagent handoff |
 | PreCompact | `pre-compact.sh` | Smart compaction: prioritized context |
 | PreCompact | `pre-compact-save.sh` | Save timestamped context backup |
 | SessionEnd | `session-end.sh` | Persist a session-end handoff note |
+| InstructionsLoaded | `instructions-audit.sh` | Append every CLAUDE.md / rules load to audit log (which rules actually entered context) |
+| ConfigChange | `config-desync-guard.sh` | Warn when `~/.claude/settings.json` drifts from `app/hooks.json` (advisory) |
 | TeammateIdle | *(inline)* | Completeness reminder |
 
 **5 skill-scoped hooks:**