@softspark/ai-toolkit 4.4.2 → 4.5.1

package/CHANGELOG.md

@@ -7,6 +7,39 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.5.1 - ShellCheck fix for loop-guard hook (2026-06-02)
+
+Patch release. Clears two ShellCheck `SC2034` warnings in `loop-guard.sh` that turned the `main` CI ShellCheck job red after v4.5.0. The publish workflow does not run ShellCheck, so v4.5.0 published despite the red CI; this patch makes `main` green again. No runtime behavior change.
+
+### Fixed
+- **`loop-guard.sh` ShellCheck** — `INPUT` now carries the `# shellcheck disable=SC2034` directive (it is consumed via the sourced `_hook-io.sh`, matching `guard-destructive.sh`), and `AI_TOOLKIT_HOOK_FORMAT` is `export`ed. `shellcheck --severity=warning app/hooks/*.sh` is clean.
+
+---
+
+## v4.5.0 - Unicode-safety scanner, loop guard, honest instincts (2026-06-02)
+
+Minor release. Hardens the security audit against invisible prompt injection, adds a repeated-action loop guard, fixes destructive-guard false positives, and turns the instinct system from a dormant promise into a working manual feature.
+
+### Added
+- **Unicode-safety scanner** — `scripts/audit_skills.py` now flags invisible/smuggled Unicode across shipped prompt text (skills, agents, rules, personas, mcp-templates): tag-block ASCII smuggling (`U+E0000–E007F`) and Trojan Source bidi controls as HIGH, zero-width/invisible format chars as WARN. Emoji ZWJ (`U+200D`) is allowlisted. Runs inside the existing `--ci` gate.
+- **`loop-guard.sh`** — advisory `PostToolUse` hook (`Bash|Edit|MultiEdit|Write`) that warns when the same action repeats within a short window, catching successful-but-identical loops the `/repeat` circuit breaker (failures-only) misses. Edits track content, so iterative editing of one file does not trip it. Tunable via `AI_TOOLKIT_LOOP_WINDOW`/`AI_TOOLKIT_LOOP_THRESHOLD`. Hook entries: 28 → 29.
+- **Per-hook opt-out** — `AI_TOOLKIT_DISABLED_HOOKS` (comma list) disables named profile-gated hooks via `_profile-check.sh`. Safety guards are intentionally excluded — remove them with `ai-toolkit remove-hook`.
+- **Editor hooks honesty** — the README platform matrix gained a **Hooks** column marking which editors get lifecycle hook enforcement; `validate.py` cross-checks the claim against the actual `generate_*_hooks.py` generators and fails on drift.
+- **`doctor` language-rules drift check** — warns when a local-install project gained a language (e.g. a new `Cargo.toml`) whose `<lang>-rules` were never injected.
+- **Live-app rubric verification** — `verification-before-completion` documents an optional weighted-rubric scoring pass for behavioral/visual work.
+
+### Changed
+- **Instincts load by default** — `session-start.sh` loads `.claude/instincts/*.md` whenever present (previously gated behind `AI_TOOLKIT_HOOK_VERBOSE=1`, so they never surfaced by default). `AI_TOOLKIT_HOOK_QUIET=1` suppresses; no instincts on disk means no output.
+- **memory-pack `strip_private.py`** — now redacts high-confidence secrets (API keys, tokens, private keys) to `[REDACTED:<label>]` in addition to stripping `<private>` blocks before SQLite storage.
+
+### Fixed
+- **`guard-destructive.sh` false positives** — `git push --force-with-lease`/`--force-if-includes` are no longer blocked, and a single non-chained `echo`/`printf`/`git commit`/`git tag` carrying a destructive token as data (e.g. a commit message mentioning `DROP TABLE`) passes. Chained commands (`&&`, `||`, `;`, `|`) and real executions (e.g. `psql -c "DROP TABLE"`) are still inspected and blocked.
+- **`instinct-review` documentation** — removed the false claim of an automatic session-end instinct extractor that never existed; the skill now documents the real manual authoring + curation flow.
+
+Test count: 1151 → 1179. No skill/agent count change.
+
+---
+
 ## v4.4.2 - Ecosystem sync: Claude Code 2.1.158 + Codex 0.134 hook events (2026-05-30)
 
 Patch release. Syncs the tool registry and `hook-creator` skill with newly detected upstream hook events and refreshes the ecosystem drift snapshot. No generated output or runtime behavior changes.

package/README.md

@@ -6,16 +6,17 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-107-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1151%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1179%20passing-success)](tests/)
 
-## What's New in v4.4.2
+## What's New in v4.5.1
 
-Patch release. Syncs the tool registry and `hook-creator` skill with newly detected upstream hook events and refreshes the ecosystem drift snapshot. No generated output or runtime behavior changes.
+v4.5.1 is a patch that clears a ShellCheck lint in the loop-guard hook. The v4.5.0 feature set: hardens the security audit against invisible prompt injection, adds a repeated-action loop guard, fixes destructive-guard false positives, and makes the instinct system actually work.
 
-- **Claude Code `MessageDisplay`**: the hook event added in Claude Code 2.1.152 is now tracked in the registry and documented in the `hook-creator` skill.
-- **Three more Claude Code events tracked**: `PostToolUseFailure`, `PostToolBatch`, and `UserPromptExpansion` were real but missing from the registry.
-- **Codex hook events**: recorded the four untracked Codex events (`PreCompact`, `PostCompact`, `SubagentStart`, `SubagentStop`); Codex exposes 10 lifecycle events total.
-- **Drift snapshot refreshed**: baselined Claude Code 2.1.158 and Codex 0.134; `ecosystem_doctor.py --check` is green.
+- **Unicode-safety scanner**: the skill/agent audit now flags invisible and smuggled Unicode (tag-block ASCII smuggling, Trojan Source bidi controls) across all shipped prompt text — a prompt-injection vector regex checks never caught. Runs in the `--ci` gate.
+- **Loop guard**: a new advisory `PostToolUse` hook warns when the same action repeats, catching stuck loops that the `/repeat` failure-counter circuit breaker misses.
+- **`git push --force-with-lease` unblocked**: the destructive-command guard no longer false-positives on safe force-pushes or on commit messages that merely mention `DROP TABLE`/`rm -rf`.
+- **Instincts load by default**: hand-authored `.claude/instincts/*.md` now load at session start (previously dormant behind a verbose flag). The skill docs were corrected to drop a never-implemented auto-extractor claim.
+- **Editor honesty + secret scrubbing**: the platform matrix marks which editors get hook enforcement, and memory-pack now redacts secrets before storing session observations.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -98,22 +99,22 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 
 ## Platform Support
 
-| Platform | Config Files | Scope |
-|----------|-------------|-------|
-| Claude Code | `~/.claude/` | global |
-| Cursor | `.cursor/rules/*.mdc` + `.cursor/mcp.json` + `.cursor/skills/*` | project (`~/.cursor/mcp.json` for MCP only) |
-| Windsurf | `~/.codeium/.../global_rules.md` + `~/.codeium/windsurf/skills/*` + `.windsurf/rules/*.md` | global + project |
-| Gemini CLI | `~/.gemini/GEMINI.md` | global |
-| GitHub Copilot | `.github/copilot-instructions.md` | project |
-| Cline | `~/.cline/rules/*.md` + `~/.cline/skills/*` + `.clinerules/*.md` | global + project |
-| Roo Code | `~/.roo/rules/*.md` + `.roomodes` + `.roo/rules/*.md` | global rules + project |
-| Aider | `~/.aider.conf.yml` + `.aider.conf.yml` + `CONVENTIONS.md` | global + project |
-| Augment | `~/.augment/rules/*.md` + `.augment/rules/ai-toolkit-*.md` | global + project |
-| Google Antigravity | `.agent/rules/*.md` + `.agent/workflows/*.md` | project |
-| Codex CLI | `AGENTS.md` + `.agents/rules/*.md` + `.agents/skills/*` + `.codex/hooks.json` | project + global plugin |
-| opencode | `AGENTS.md` + `.opencode/{agents,commands,plugins}/*` + `opencode.json` | project + global (`~/.config/opencode/`) |
-
-> Claude Code is always installed (primary platform). Other editors on demand with `--editors`. All platforms receive the same agent/skill catalog, guidelines, and registered custom rules.
+| Platform | Config Files | Hooks | Scope |
+|----------|-------------|:-----:|-------|
+| Claude Code | `~/.claude/` | ✅ | global |
+| Cursor | `.cursor/rules/*.mdc` + `.cursor/mcp.json` + `.cursor/skills/*` | ✅ | project (`~/.cursor/mcp.json` for MCP only) |
+| Windsurf | `~/.codeium/.../global_rules.md` + `~/.codeium/windsurf/skills/*` + `.windsurf/rules/*.md` | ✅ | global + project |
+| Gemini CLI | `~/.gemini/GEMINI.md` | ✅ | global |
+| GitHub Copilot | `.github/copilot-instructions.md` | — | project |
+| Cline | `~/.cline/rules/*.md` + `~/.cline/skills/*` + `.clinerules/*.md` | — | global + project |
+| Roo Code | `~/.roo/rules/*.md` + `.roomodes` + `.roo/rules/*.md` | — | global rules + project |
+| Aider | `~/.aider.conf.yml` + `.aider.conf.yml` + `CONVENTIONS.md` | — | global + project |
+| Augment | `~/.augment/rules/*.md` + `.augment/rules/ai-toolkit-*.md` | ✅ | global + project |
+| Google Antigravity | `.agent/rules/*.md` + `.agent/workflows/*.md` | — | project |
+| Codex CLI | `AGENTS.md` + `.agents/rules/*.md` + `.agents/skills/*` + `.codex/hooks.json` | ✅ | project + global plugin |
+| opencode | `AGENTS.md` + `.opencode/{agents,commands,plugins}/*` + `opencode.json` | ✅ | project + global (`~/.config/opencode/`) |
+
+> Claude Code is always installed (primary platform). Other editors on demand with `--editors`. Every platform receives the agent/skill catalog, guidelines, and registered custom rules as text. The **Hooks** column marks platforms that also get lifecycle hook enforcement — the machine-enforced constitution (guard-destructive, quality gates, search-first discipline). Platforms marked — receive those rules as guidance only, without blocking hooks.
 
 ---
 
@@ -125,7 +126,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | `skills/` (hybrid) | 30 | Slash commands with agent knowledge base |
 | `skills/` (knowledge) | 45 | Domain knowledge auto-loaded by agents (includes 13 `<lang>-rules` skills) |
 | `agents/` | 44 | Specialized agents across 10 categories |
-| `hooks/` | 28 entries / 14 events | Quality gates, path safety, prompt governance, session lifecycle |
+| `hooks/` | 29 entries / 14 events | Quality gates, path safety, prompt governance, loop guard, session lifecycle |
 | `plugins/` | 11 packs | Opt-in domain bundles (security, research, frontend, enterprise, 6 language packs) |
 | `constitution.md` | 6 articles | Machine-enforced safety rules |
 | `rules/` | auto-injected | Language-specific and custom rules injected into your configs |
@@ -141,14 +142,14 @@ ai-toolkit/
 │   ├── agents/          # 44 agent definitions
 │   ├── skills/          # 107 skills (task / hybrid / knowledge)
 │   ├── rules/           # Auto-injected into your CLAUDE.md
-│   ├── hooks/           # Hook scripts (28 entries, 14 lifecycle events)
+│   ├── hooks/           # Hook scripts (29 entries, 14 lifecycle events)
 │   ├── plugins/         # 11 experimental plugin packs (opt-in)
 │   ├── output-styles/   # System prompt output style overrides
 │   ├── constitution.md  # 6 immutable safety articles
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1151 tests)
+├── tests/               # Bats test suite (1179 tests)
 └── CHANGELOG.md
 ```
 
@@ -160,7 +161,7 @@ ai-toolkit/
 
 **Machine-enforced constitution** — 6-article safety constitution enforced via `PreToolUse` hooks that actually block `rm -rf`, `DROP TABLE`, and irreversible operations. Not just documentation.
 
-**28 lifecycle hooks** — Executable scripts across 14 events (SessionStart → SessionEnd, plus InstructionsLoaded + ConfigChange). Guards, governance, quality gates, session persistence, MCP health checks, revert protection, test-cohesion enforcement, search-first discipline. See [Hooks Catalog](kb/reference/hooks-catalog.md).
+**29 lifecycle hooks** — Executable scripts across 14 events (SessionStart → SessionEnd, plus InstructionsLoaded + ConfigChange). Guards, governance, quality gates, session persistence, MCP health checks, revert protection, test-cohesion enforcement, loop guard, search-first discipline. See [Hooks Catalog](kb/reference/hooks-catalog.md).
 
 **Security scanning** — `/skill-audit` for code-level risks, `/cve-scan` for dependency CVEs. Both CI-ready with exit codes.
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "4.4.2",
+  "version": "4.5.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -8,7 +8,7 @@ Universal multi-agent system for software development. Works across all reposito
 |-----------|-------|
 | Agents | See agents catalog |
 | Skills | See skills catalog |
-| Hooks | 14 events / 28 entries (SessionStart ×3, Notification ×1, PreToolUse ×5, UserPromptSubmit ×2, PostToolUse ×4, Stop ×4, TaskCompleted ×1, TeammateIdle ×1, SubagentStart ×1, SubagentStop ×1, PreCompact ×2, SessionEnd ×1, InstructionsLoaded ×1, ConfigChange ×1) |
+| Hooks | 14 events / 29 entries (SessionStart ×3, Notification ×1, PreToolUse ×5, UserPromptSubmit ×2, PostToolUse ×5, Stop ×4, TaskCompleted ×1, TeammateIdle ×1, SubagentStart ×1, SubagentStop ×1, PreCompact ×2, SessionEnd ×1, InstructionsLoaded ×1, ConfigChange ×1) |
 
 ---
 

package/app/hooks/_profile-check.sh

@@ -9,3 +9,20 @@
 
 PROFILE="${TOOLKIT_HOOK_PROFILE:-standard}"
 [ "$PROFILE" = "minimal" ] && exit 0
+
+# Per-hook soft opt-out: AI_TOOLKIT_DISABLED_HOOKS is a comma-separated list of
+# hook names (with or without the .sh suffix). A listed hook exits 0 (no-op).
+# Only hooks that source this file are covered — the safety guards
+# (guard-destructive/path/config) intentionally do not, and must be removed
+# deliberately with `ai-toolkit remove-hook` rather than silently env-disabled.
+if [ -n "${AI_TOOLKIT_DISABLED_HOOKS:-}" ]; then
+    _hook_name="$(basename "${BASH_SOURCE[1]:-$0}" .sh)"
+    IFS=',' read -ra _disabled_hooks <<< "$AI_TOOLKIT_DISABLED_HOOKS"
+    for _d in "${_disabled_hooks[@]}"; do
+        _d="${_d// /}"
+        _d="${_d%.sh}"
+        if [ -n "$_d" ] && [ "$_d" = "$_hook_name" ]; then
+            exit 0
+        fi
+    done
+fi

package/app/hooks/guard-destructive.sh

@@ -18,6 +18,24 @@ fi
 # Normalize command for matching: collapse whitespace, strip backslash escapes
 NORMALIZED=$(printf '%s' "$COMMAND" | tr -s '[:space:]' ' ' | sed 's/\\//g')
 
+# Benign data contexts: a single, non-chained command whose program only PRINTS
+# or RECORDS text (echo/printf) or writes a commit/tag message (git commit/tag)
+# cannot itself execute a destructive op — the dangerous tokens are data, not
+# actions. Skip matching so "git commit -m 'fix DROP TABLE race'" is not blocked.
+# Bail out of the allowlist when a command separator is present (&&, ||, ;, |) so
+# chained commands like `git commit -m x && rm -rf /tmp` are still inspected.
+if ! printf '%s' "$NORMALIZED" | grep -qE '(&&|\|\||;|\|)'; then
+    if printf '%s' "$NORMALIZED" | grep -qE '^[[:space:]]*(echo|printf|git[[:space:]]+(commit|tag))([[:space:]]|$)'; then
+        exit 0
+    fi
+fi
+
+# Safe git force variants (--force-with-lease / --force-if-includes) are the
+# recommended way to force-push without clobbering others' work. Strip them
+# before matching so they do not trip the broad --force patterns; a bare
+# --force or -f left behind still blocks.
+SAFE_STRIPPED=$(printf '%s' "$NORMALIZED" | sed -E 's/--force-with-lease(=[^ ]*)?//g; s/--force-if-includes//g')
+
 # Destructive patterns — word-boundary aware where possible
 DESTRUCTIVE_PATTERNS=(
     # rm variants (short flags, long flags, separated flags, sudo, xargs/find piped)
@@ -69,7 +87,7 @@ DESTRUCTIVE_PATTERNS=(
 # Build combined regex
 REGEX=$(IFS='|'; echo "${DESTRUCTIVE_PATTERNS[*]}")
 
-if echo "$NORMALIZED" | grep -qEi "($REGEX)"; then
+if echo "$SAFE_STRIPPED" | grep -qEi "($REGEX)"; then
     echo "WARNING: Potentially destructive command detected. Please verify." >&2
     exit 2
 fi

package/app/hooks/loop-guard.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# loop-guard.sh — Advisory detection of repeated identical actions (stuck loops).
+#
+# Fires on: PostToolUse (Bash|Edit|MultiEdit|Write)
+# Never blocks. Emits an advisory when the SAME tool action repeats at least
+# THRESHOLD times within a short window — catching successful-but-identical
+# loops that the /repeat circuit breaker (which only counts FAILURES) misses.
+# Skipped in minimal profile; honours AI_TOOLKIT_DISABLED_HOOKS.
+#
+# Tunables: AI_TOOLKIT_LOOP_WINDOW (default 6), AI_TOOLKIT_LOOP_THRESHOLD (3).
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
+
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
+INPUT=$(cat)
+TOOL_NAME=$(hook_tool_name)
+[ -z "$TOOL_NAME" ] && exit 0
+
+# Build an identity for the action. For Bash it is the command; for edits it is
+# file + new content, so normal iterative editing of one file does NOT trip the
+# guard — only re-applying an IDENTICAL change does.
+CMD=$(hook_command)
+if [ -n "$CMD" ]; then
+    IDENT="$CMD"
+else
+    FILE=$(hook_file_path)
+    [ -z "$FILE" ] && exit 0
+    IDENT="${FILE}::$(hook_new_content)"
+fi
+
+SID=$(hook_session_id)
+STATE_DIR="${HOME}/.softspark/ai-toolkit/sessions"
+mkdir -p "$STATE_DIR" 2>/dev/null || exit 0
+LOG="${STATE_DIR}/${SID}-actions.log"
+
+WINDOW="${AI_TOOLKIT_LOOP_WINDOW:-6}"
+THRESHOLD="${AI_TOOLKIT_LOOP_THRESHOLD:-3}"
+
+# Store only a short hash of "tool|identity" — never the raw payload.
+HASH=$(printf '%s|%s' "$TOOL_NAME" "$IDENT" | { shasum -a 256 2>/dev/null || sha256sum 2>/dev/null; } | cut -c1-16)
+[ -z "$HASH" ] && exit 0
+printf '%s\n' "$HASH" >> "$LOG" 2>/dev/null || exit 0
+
+# Keep only the last WINDOW entries so the file stays tiny.
+lines=$(wc -l < "$LOG" 2>/dev/null | tr -d ' ')
+if [ -n "$lines" ] && [ "$lines" -gt "$WINDOW" ]; then
+    tail -n "$WINDOW" "$LOG" > "${LOG}.tmp" 2>/dev/null && mv "${LOG}.tmp" "$LOG" 2>/dev/null
+fi
+
+COUNT=$(grep -cxF "$HASH" "$LOG" 2>/dev/null | tr -d ' ')
+[ -z "$COUNT" ] && COUNT=0
+if [ "$COUNT" -ge "$THRESHOLD" ]; then
+    export AI_TOOLKIT_HOOK_FORMAT=json
+    hook_emit_context "PostToolUse" \
+        "Loop guard: the same ${TOOL_NAME} action has repeated ${COUNT}x within the last ${WINDOW} steps. If you are not making progress, stop and reassess — try a different approach or ask the user — instead of retrying the identical action."
+fi
+exit 0

package/app/hooks/session-start.sh

@@ -58,9 +58,11 @@ if [ -f "$SESSION_FILE" ] && [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ] && [ "${AI
     printf '%s\n' "====================="
 fi
 
-# 3. Load active instincts (if any)
+# 3. Load active instincts (if any). These are explicit, hand-authored files, so
+# they load by default whenever present (unlike auto-saved session context above,
+# which stays verbose-gated). No instincts on disk => no output, no token cost.
 INSTINCTS_DIR=".claude/instincts"
-if [ -d "$INSTINCTS_DIR" ] && [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ] && [ "${AI_TOOLKIT_HOOK_VERBOSE:-0}" = "1" ] && ls "$INSTINCTS_DIR"/*.md >/dev/null 2>&1; then
+if [ -d "$INSTINCTS_DIR" ] && [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ] && ls "$INSTINCTS_DIR"/*.md >/dev/null 2>&1; then
     printf '%s\n' "=== Active Instincts ==="
     for f in "$INSTINCTS_DIR"/*.md; do
         printf '%s\n' "- $(head -1 "$f")"

package/app/hooks.json

@@ -139,6 +139,16 @@
                     }
                 ]
             },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "Bash|Edit|MultiEdit|Write",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/loop-guard.sh\""
+                    }
+                ]
+            },
             {
                 "_source": "ai-toolkit",
                 "matcher": "Edit|MultiEdit|Write",

package/app/plugins/memory-pack/README.md

@@ -5,13 +5,13 @@ Persistent session memory with SQLite storage and full-text search.
 ## Includes
 - Skills: `/mem-search` (FTS5 search across past sessions)
 - Hooks: `observation-capture.sh` (PostToolUse), `session-summary.sh` (Stop)
-- Scripts: `init_db.py` (database setup), `strip_private.py` (privacy filter)
+- Scripts: `init_db.py` (database setup), `strip_private.py` (privacy filter + secret redaction)
 
 ## How It Works
 1. **Capture**: Every tool use is recorded to `~/.softspark/ai-toolkit/memory.db` (PostToolUse hook)
 2. **Summarize**: Session summary generated on each Stop hook (tools used, observation count, time range)
 3. **Search**: `/mem-search <query>` runs FTS5 full-text search with progressive disclosure
-4. **Privacy**: Content between `<private>...</private>` tags is stripped before storage
+4. **Privacy**: `strip_private.py` runs before storage — it removes `<private>...</private>` blocks and redacts high-confidence secrets (API keys, tokens, private keys) to `[REDACTED:<label>]`
 
 ## Database Schema
 - `sessions` — one row per Claude Code session (id, project_dir, started_at, ended_at, summary)

package/app/plugins/memory-pack/scripts/strip_private.py

@@ -1,20 +1,47 @@
 #!/usr/bin/env python3
-"""Remove <private>...</private> blocks from stdin.
+"""Sanitize stdin before it is stored in the session memory database.
 
-Used by observation-capture.sh to sanitize content before storage.
-Handles multi-line private blocks and nested angle brackets.
+Two passes:
+1. Remove ``<private>...</private>`` blocks (explicit user opt-out).
+2. Redact high-confidence secrets (API keys, tokens, private keys) so a token
+   that scrolls through a tool output never lands in the SQLite memory store.
 
-Usage: echo "text <private>secret</private> more" | python3 strip_private.py
+Used by observation-capture.sh and session-summary.sh.
+
+Usage: echo "text <private>secret</private> sk-..." | python3 strip_private.py
 """
 from __future__ import annotations
 
 import re
 import sys
 
+# High-confidence, structural secret patterns only. These match a specific
+# token shape (not "password = ..." prose) so false positives stay near zero —
+# important because over-redaction silently corrupts stored observations.
+_SECRET_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"AKIA[0-9A-Z]{16}"), "aws-key"),
+    (re.compile(r"\bsk-[A-Za-z0-9]{20,}"), "api-key"),
+    (re.compile(r"\bgh[posru]_[A-Za-z0-9]{36,}"), "github-token"),
+    (re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{10,}"), "slack-token"),
+    (re.compile(r"\bAIza[0-9A-Za-z_\-]{35}"), "google-key"),
+    (re.compile(
+        r"-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----"
+        r"[\s\S]*?-----END (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----"
+    ), "private-key"),
+]
+
+
+def scrub_secrets(text: str) -> str:
+    """Replace recognised secret tokens with a labelled redaction marker."""
+    for pattern, label in _SECRET_PATTERNS:
+        text = pattern.sub(f"[REDACTED:{label}]", text)
+    return text
+
 
 def main() -> None:
     content = sys.stdin.read()
     cleaned = re.sub(r"<private>.*?</private>", "", content, flags=re.DOTALL)
+    cleaned = scrub_secrets(cleaned)
     sys.stdout.write(cleaned)
 
 

package/app/skills/instinct-review/SKILL.md

@@ -13,9 +13,9 @@ $ARGUMENTS
 
 ## What This Does
 
-Manages the instinct system that learns patterns from your sessions.
+Manages the instinct system: project-local behavioral notes that Claude loads at the start of a session.
 
-Instincts are stored in `.claude/instincts/` and loaded at session start.
+Instincts are markdown files in `.claude/instincts/`, loaded at session start by `session-start.sh` whenever any exist (set `AI_TOOLKIT_HOOK_QUIET=1` to suppress).
 
 ## Commands
 
@@ -48,10 +48,10 @@ Interactive review: shows each instinct and asks promote/remove/keep.
 
 ## How Instincts Work
 
-1. **Extraction**: At session end, the Stop hook extracts patterns from the session
-2. **Storage**: Saved as `.claude/instincts/<pattern-name>.md` with confidence score
-3. **Loading**: At session start, instincts are loaded and shown to Claude
-4. **Curation**: Use `/instinct-review` to promote good ones and remove bad ones
+1. **Authoring**: Instinct files are written by hand — one markdown file per pattern in `.claude/instincts/`. There is no automatic session-end extractor today (see [When NOT to Use](#when-not-to-use)).
+2. **Storage**: `.claude/instincts/<pattern-name>.md`, each carrying a confidence score (see format below).
+3. **Loading**: At session start, `session-start.sh` loads every instinct file into context whenever any exist. No instincts on disk means nothing is loaded; set `AI_TOOLKIT_HOOK_QUIET=1` to suppress.
+4. **Curation**: Use `/instinct-review` to list, promote, remove, or clear them.
 
 ## Instinct Format
 
@@ -88,14 +88,14 @@ Last seen: 2026-03-25
 ## Gotchas
 
 - Instincts live in **project-local** `.claude/instincts/`, not in `~/.softspark/ai-toolkit/`. Running this skill in a different project sees a different set — do not treat the list as global state.
-- The Stop hook that extracts instincts may write draft files even when no meaningful pattern was observed. A `.claude/instincts/` with 40 files is usually 35 noise + 5 signal — curate ruthlessly.
+- Every instinct file loads into session context by default (whenever the directory is non-empty), so each one costs startup tokens. This is why curation matters — prune aggressively and keep the set small.
 - Promoted instincts (confidence = 1.0) load into every session's context, costing tokens. Too many pinned instincts bloat startup. Keep ≤10 pinned.
-- Instinct files are plain markdown but the extraction format may evolve between ai-toolkit versions. A `--clear` after a version bump is often cleaner than trying to migrate old formats.
+- Instinct files are plain markdown following the format above. If you accumulate many, a `--clear` and re-author is often cleaner than migrating stale notes after a major toolkit bump.
 - The filename (`<pattern-name>.md`) is the identity used by `--promote` and `--remove`. Renaming files manually breaks those flags until the user reopens the review UI.
 
 ## When NOT to Use
 
-- To **extract** new instincts — extraction is automatic via the Stop hook
+- To **auto-extract** instincts from a session — not implemented. No Stop hook writes instinct files; author them by hand (or via a future extraction tool). This skill curates existing files, it does not generate them.
 - To search past session memory — use `/mem-search`
 - To edit global toolkit memory files — those live in `~/.claude/projects/*/memory/` and are managed by the auto-memory system, not this skill
-- To permanently disable the instinct system — edit `settings.json` to remove the Stop hook; `--clear` only wipes current state, extraction continues on the next session
+- To stop instincts from loading — delete the files with `--clear`, or set `AI_TOOLKIT_HOOK_QUIET=1` to suppress all session-start output. There is no extraction process to disable.

package/app/skills/skill-audit/SKILL.md

@@ -73,6 +73,16 @@ Scan skill and agent definitions for security risks before installation or after
 | `-----BEGIN.*PRIVATE KEY` | HIGH | Private key |
 | `ghp_[a-zA-Z0-9]{36}` | HIGH | GitHub PAT |
 
+### Unicode Safety
+
+Shipped prompt text (skills, agents, rules, personas, mcp-templates) is scanned for invisible/smuggled characters that a human reviewer cannot see. `U+200D` (ZWJ) is allowlisted so legitimate emoji sequences do not flag.
+
+| Pattern | Severity | Description |
+|---------|----------|-------------|
+| Tag block `U+E0000–U+E007F` | HIGH | ASCII smuggling / invisible prompt injection |
+| Bidi controls (LRE/RLE/PDF/LRO/RLO, LRI/RLI/FSI/PDI) | HIGH | Trojan Source text reordering |
+| Zero-width / invisible format chars (ZWSP, ZWNJ, WJ, BOM, soft hyphen, …) | WARN | Verify it is intentional |
+
 ## Output Format
 
 ```markdown

package/app/skills/verification-before-completion/SKILL.md

@@ -105,6 +105,25 @@ CORRECT:  Agent reports success → Check VCS diff → Verify changes → Report
 WRONG:    Trust agent report at face value
 ```
 
+## Live-App Rubric Verification (optional)
+
+When the success criterion is **behavioral or visual** (a UI flow, a generated app, a multi-step interaction), a pass/fail command is not enough — the proof is the running app, observed. Use a weighted rubric instead of a single assertion:
+
+1. **Define the rubric BEFORE building** — 3–6 criteria, each with a weight and an explicit pass bar. Example:
+
+   | Criterion | Weight | Pass bar |
+   |-----------|--------|----------|
+   | Core flow completes end-to-end | 0.40 | No error, reaches success state |
+   | Empty / loading / error states render | 0.25 | All three visible |
+   | Matches the requested layout | 0.20 | No major deviation |
+   | No console errors | 0.15 | Console clean |
+
+2. **Launch the app and observe** — actually run it and capture the behavior (screenshot, console, network). Do not infer from the source.
+3. **Score with a fresh evaluator** — have an independent agent grade the observed behavior against the rubric, not the implementer who wrote it (self-grading anchors high). Compute the weighted score.
+4. **Gate on the threshold** — below the bar (e.g. < 0.8) the claim is NOT verified: list the failing criteria as concrete defects and iterate. At or above the bar, state the score WITH the captured evidence.
+
+The rubric is the verification command for work that has no green/red exit code. The same Iron Law applies: observed evidence before the claim, every time.
+
 ## Constitutional Anchors
 
 This skill enforces **Constitution Art. VI.4 (Verify Before Claiming Done)**. The diff re-read is not optional: before any completion claim, confirm no orphaned references, no missing test coverage for changed paths, no stale docs. A task is not done while any of those exist.

package/kb/reference/hooks-catalog.md

@@ -3,7 +3,7 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.5.6"
+version: "1.5.7"
 created: "2026-03-27"
 last_updated: "2026-05-25"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
@@ -13,7 +13,7 @@ description: "Complete reference of all ai-toolkit hooks: events, scripts, insta
 
 ## Overview
 
-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/`.
+ai-toolkit provides 29 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
 
@@ -85,6 +85,10 @@ for debugging; `AI_TOOLKIT_HOOK_QUIET=1` keeps it silent explicitly.
 - `git push --force`
 - `chmod -R 777`
 
+**Exemptions (avoid false positives):**
+- `git push --force-with-lease` / `--force-if-includes` — the safe force-push variants are allowed.
+- A single, non-chained `echo`/`printf`/`git commit`/`git tag` carrying a destructive token as *data* (e.g. a commit message mentioning `DROP TABLE`) is allowed. Chained commands (`&&`, `;`, `|`) are still inspected in full.
+
 ### PreToolUse (file ops) — `guard-path.sh`
 
 | Field | Value |
@@ -403,6 +407,19 @@ First-match-wins per file. Built-in runners: `bats`, `pytest`, `vitest`, `jest`.
 
 **Overrides:** `CLAUDE_SKIP_COHESION=1` (one-off), `CLAUDE_HOOK_BOOTSTRAP=1` (when editing the hook itself). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
+### PostToolUse (loop guard) — `loop-guard.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `PostToolUse` |
+| Matcher | `Bash\|Edit\|MultiEdit\|Write` |
+| Script | `~/.softspark/ai-toolkit/hooks/loop-guard.sh` |
+| Fires | After every Bash command or file edit |
+
+**Action:** Advisory only, never blocks. Hashes a `tool|identity` signature of each action (command for Bash; file path + new content for edits) and keeps the last `AI_TOOLKIT_LOOP_WINDOW` (default 6) hashes per session. When the same signature repeats `AI_TOOLKIT_LOOP_THRESHOLD` times (default 3) it emits a `PostToolUse` `additionalContext` advisory telling Claude to reassess instead of retrying. Catches successful-but-identical loops that the `/repeat` circuit breaker (which only counts failures) does not. Edits track content, so normal iterative editing of one file does not trip it. Only short hashes are stored — never raw payloads.
+
+**Tunables:** `AI_TOOLKIT_LOOP_WINDOW`, `AI_TOOLKIT_LOOP_THRESHOLD`. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`; honours `AI_TOOLKIT_DISABLED_HOOKS`.
+
 ### PostToolUse (search-first tracker) — `search-tracker.sh`
 
 | Field | Value |
@@ -480,6 +497,8 @@ Set in `.claude/settings.local.json`:
 | `standard` | All hooks (default) |
 | `strict` | Standard + mypy --strict on task completion |
 
+**Disabling individual hooks:** set `AI_TOOLKIT_DISABLED_HOOKS` to a comma-separated list of hook names (with or without `.sh`), e.g. `{ "env": { "AI_TOOLKIT_DISABLED_HOOKS": "loop-guard,quality-check" } }`. Listed hooks become no-ops. This covers profile-gated hooks only; the safety guards (`guard-destructive`/`guard-path`/`guard-config`) intentionally cannot be env-disabled — remove them deliberately with `ai-toolkit remove-hook`.
+
 Non-blocking informational context is silent in plain-text mode by default while
 side effects and blocking decisions still run. Set `AI_TOOLKIT_HOOK_VERBOSE=1`
 only when debugging hook context locally. `AI_TOOLKIT_HOOK_QUIET=1` keeps hook
@@ -561,7 +580,7 @@ commands explicitly silent, and Codex-generated hooks plus Claude's bundled
 
 **Hook script not found:**
 ```bash
-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)
+ls ~/.softspark/ai-toolkit/hooks/     # should list 28 .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/llms-full.txt

@@ -8895,7 +8895,7 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.5.6"
+version: "1.5.7"
 created: "2026-03-27"
 last_updated: "2026-05-25"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
@@ -8905,7 +8905,7 @@ description: "Complete reference of all ai-toolkit hooks: events, scripts, insta
 
 ## Overview
 
-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/`.
+ai-toolkit provides 29 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
 
@@ -8977,6 +8977,10 @@ for debugging; `AI_TOOLKIT_HOOK_QUIET=1` keeps it silent explicitly.
 - `git push --force`
 - `chmod -R 777`
 
+**Exemptions (avoid false positives):**
+- `git push --force-with-lease` / `--force-if-includes` — the safe force-push variants are allowed.
+- A single, non-chained `echo`/`printf`/`git commit`/`git tag` carrying a destructive token as *data* (e.g. a commit message mentioning `DROP TABLE`) is allowed. Chained commands (`&&`, `;`, `|`) are still inspected in full.
+
 ### PreToolUse (file ops) — `guard-path.sh`
 
 | Field | Value |
@@ -9295,6 +9299,19 @@ First-match-wins per file. Built-in runners: `bats`, `pytest`, `vitest`, `jest`.
 
 **Overrides:** `CLAUDE_SKIP_COHESION=1` (one-off), `CLAUDE_HOOK_BOOTSTRAP=1` (when editing the hook itself). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
+### PostToolUse (loop guard) — `loop-guard.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `PostToolUse` |
+| Matcher | `Bash\|Edit\|MultiEdit\|Write` |
+| Script | `~/.softspark/ai-toolkit/hooks/loop-guard.sh` |
+| Fires | After every Bash command or file edit |
+
+**Action:** Advisory only, never blocks. Hashes a `tool|identity` signature of each action (command for Bash; file path + new content for edits) and keeps the last `AI_TOOLKIT_LOOP_WINDOW` (default 6) hashes per session. When the same signature repeats `AI_TOOLKIT_LOOP_THRESHOLD` times (default 3) it emits a `PostToolUse` `additionalContext` advisory telling Claude to reassess instead of retrying. Catches successful-but-identical loops that the `/repeat` circuit breaker (which only counts failures) does not. Edits track content, so normal iterative editing of one file does not trip it. Only short hashes are stored — never raw payloads.
+
+**Tunables:** `AI_TOOLKIT_LOOP_WINDOW`, `AI_TOOLKIT_LOOP_THRESHOLD`. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`; honours `AI_TOOLKIT_DISABLED_HOOKS`.
+
 ### PostToolUse (search-first tracker) — `search-tracker.sh`
 
 | Field | Value |
@@ -9372,6 +9389,8 @@ Set in `.claude/settings.local.json`:
 | `standard` | All hooks (default) |
 | `strict` | Standard + mypy --strict on task completion |
 
+**Disabling individual hooks:** set `AI_TOOLKIT_DISABLED_HOOKS` to a comma-separated list of hook names (with or without `.sh`), e.g. `{ "env": { "AI_TOOLKIT_DISABLED_HOOKS": "loop-guard,quality-check" } }`. Listed hooks become no-ops. This covers profile-gated hooks only; the safety guards (`guard-destructive`/`guard-path`/`guard-config`) intentionally cannot be env-disabled — remove them deliberately with `ai-toolkit remove-hook`.
+
 Non-blocking informational context is silent in plain-text mode by default while
 side effects and blocking decisions still run. Set `AI_TOOLKIT_HOOK_VERBOSE=1`
 only when debugging hook context locally. `AI_TOOLKIT_HOOK_QUIET=1` keeps hook
@@ -9453,7 +9472,7 @@ commands explicitly silent, and Codex-generated hooks plus Claude's bundled
 
 **Hook script not found:**
 ```bash
-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)
+ls ~/.softspark/ai-toolkit/hooks/     # should list 28 .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/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.4.2",
+  "version": "4.5.1",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.4.2",
+  "version": "4.5.1",
   "description": "AI coding toolkit: 107 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/audit_skills.py

@@ -2,7 +2,8 @@
 """Skill & Agent Security Auditor.
 
 Deterministic scanner for ai-toolkit skills and agents.
-Detects dangerous code patterns, hardcoded secrets, and permission issues.
+Detects dangerous code patterns, hardcoded secrets, permission issues, and
+invisible/smuggled Unicode in shipped prompt text.
 
 Stdlib-only. JSON output to stdout. Non-zero exit on HIGH findings.
 
@@ -22,6 +23,7 @@ from __future__ import annotations
 import json
 import re
 import sys
+import unicodedata
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
@@ -149,6 +151,73 @@ def scan_secrets(filepath: Path, findings: list[Finding]) -> None:
             findings.append(Finding(severity, rel, lineno, regex, desc))
 
 
+# ---------------------------------------------------------------------------
+# Unicode safety — invisible / smuggled characters in shipped prompt text.
+# Prompt files (skills, agents, rules, personas, mcp-templates) ARE the
+# product. A poisoned PR can carry instructions a human reviewer cannot see:
+# regex-over-decoded-text checks (above) never catch them.
+# ---------------------------------------------------------------------------
+
+# ASCII smuggling: U+E0000–U+E007F mirror ASCII inside Unicode "tag" chars.
+_UNICODE_TAG_BLOCK = range(0xE0000, 0xE0080)
+
+# Trojan Source bidi controls (CVE-2021-42574) — reorder rendered text vs. its
+# logical/source order, hiding instructions from a reviewer.
+_UNICODE_BIDI_HIGH = frozenset({
+    0x202A, 0x202B, 0x202C, 0x202D, 0x202E,  # LRE RLE PDF LRO RLO
+    0x2066, 0x2067, 0x2068, 0x2069,          # LRI RLI FSI PDI
+})
+
+# Invisible / zero-width formatting that can hide or splice text.
+# U+200D (ZERO WIDTH JOINER) is deliberately EXCLUDED — it is required by
+# legitimate emoji sequences and i18n text, so flagging it floods false
+# positives and trains maintainers to disable the gate.
+_UNICODE_INVISIBLE_WARN = frozenset({
+    0x200B, 0x200C, 0x200E, 0x200F, 0x2060, 0xFEFF, 0x00AD,
+    0x180E, 0x115F, 0x1160, 0x3164, 0xFFA0, 0x17B4, 0x17B5,
+})
+
+
+def _char_name(cp: int) -> str:
+    """Best-effort Unicode name for diagnostics."""
+    try:
+        return unicodedata.name(chr(cp))
+    except ValueError:
+        return f"U+{cp:04X}"
+
+
+def scan_unicode(filepath: Path, findings: list[Finding]) -> None:
+    """Flag invisible / smuggled Unicode in shipped prompt text."""
+    try:
+        text = filepath.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return
+    rel = str(filepath)
+    for lineno, line in enumerate(text.splitlines(), 1):
+        for ch in line:
+            cp = ord(ch)
+            if cp < 0x80:  # plain ASCII — fast path, always safe
+                continue
+            if cp in _UNICODE_TAG_BLOCK:
+                findings.append(Finding(
+                    "HIGH", rel, lineno, "unicode-tag-block",
+                    f"Unicode tag char {_char_name(cp)} (U+{cp:04X}) — "
+                    "ASCII smuggling / invisible prompt injection",
+                ))
+            elif cp in _UNICODE_BIDI_HIGH:
+                findings.append(Finding(
+                    "HIGH", rel, lineno, "unicode-bidi-control",
+                    f"Bidi control {_char_name(cp)} (U+{cp:04X}) — "
+                    "Trojan Source text reordering",
+                ))
+            elif cp in _UNICODE_INVISIBLE_WARN:
+                findings.append(Finding(
+                    "WARN", rel, lineno, "unicode-invisible",
+                    f"Invisible/zero-width char {_char_name(cp)} (U+{cp:04X}) — "
+                    "verify it is intentional",
+                ))
+
+
 # Description quality — per Anthropic docs (code.claude.com/docs/en/skills.md):
 # description + when_to_use combined ≤ 1536 chars; first sentence carries
 # the trigger keywords that let the LLM route to this skill.
@@ -373,15 +442,26 @@ def audit(toolkit_root: Path) -> list[Finding]:
                 scan_file_patterns(sh, BASH_WARN, "WARN", findings)
                 scan_secrets(sh, findings)
 
-            # Secrets in any text file
+            # Secrets + invisible Unicode in any text file
             for md in skill_dir.rglob("*.md"):
                 scan_secrets(md, findings)
+                scan_unicode(md, findings)
 
     # Scan agents
     if agents.is_dir():
         for agent_md in sorted(agents.glob("*.md")):
             check_agent(agent_md, findings)
             scan_secrets(agent_md, findings)
+            scan_unicode(agent_md, findings)
+
+    # Unicode safety across the rest of the shipped prompt surface.
+    for extra in ("rules", "personas", "mcp-templates"):
+        extra_dir = app / extra
+        if not extra_dir.is_dir():
+            continue
+        for f in sorted(extra_dir.rglob("*")):
+            if f.is_file() and f.suffix in (".md", ".json"):
+                scan_unicode(f, findings)
 
     # Sort: HIGH first, then WARN, then INFO
     order = {"HIGH": 0, "WARN": 1, "INFO": 2}

package/scripts/doctor.py

@@ -60,6 +60,7 @@ EXPECTED_HOOKS = [
     "config-desync-guard.sh",
     "instructions-audit.sh",
     "post-tool-use.sh",
+    "loop-guard.sh",
     "quality-check.sh",
     "quality-gate.sh",
     "revert-guard.sh",
@@ -549,6 +550,55 @@ def check_url_hooks(dr: DiagResult, fix_mode: bool) -> None:
                     print(f"    Could not re-fetch: {exc}")
 
 
+# ---------------------------------------------------------------------------
+# Check 10: Language Rules Drift (project-local)
+# ---------------------------------------------------------------------------
+
+def check_language_drift(dr: DiagResult) -> None:
+    """Warn when the current project gained a language but its rules were not injected.
+
+    Runs only inside a local-install project (cwd has .claude/CLAUDE.md with the
+    language-rules block). A new Cargo.toml / go.mod that appears after install
+    otherwise leaves the matching <lang>-rules unlinked with zero signal.
+    """
+    print()
+    print("## 10. Language Rules Drift")
+
+    claude_md = Path.cwd() / ".claude" / "CLAUDE.md"
+    if not claude_md.is_file():
+        dr.skip("not a local-install project (no .claude/CLAUDE.md)")
+        return
+    try:
+        content = claude_md.read_text(encoding="utf-8")
+    except OSError:
+        dr.skip("could not read .claude/CLAUDE.md")
+        return
+    if "TOOLKIT:language-rules" not in content:
+        dr.skip("no language-rules block in .claude/CLAUDE.md")
+        return
+
+    try:
+        from install_steps.detect_language import detect_languages
+    except Exception:
+        dr.skip("language detection unavailable")
+        return
+
+    missing = []
+    for module in detect_languages(Path.cwd(), toolkit_dir):
+        if not module.startswith("rules-"):
+            continue
+        skill = f"{module[len('rules-'):]}-rules"
+        if skill not in content:
+            missing.append(skill)
+
+    if not missing:
+        dr.ok("project language rules in sync")
+        return
+    for skill in missing:
+        lang = skill[: -len("-rules")]
+        dr.warn(f"{lang} detected but {skill} not injected — run: ai-toolkit install --local --lang {lang}")
+
+
 # ---------------------------------------------------------------------------
 # Main
 # ---------------------------------------------------------------------------
@@ -571,6 +621,7 @@ def main() -> None:
     check_benchmark_freshness(dr)
     check_stale_rules(dr, fix_mode)
     check_url_hooks(dr, fix_mode)
+    check_language_drift(dr)
 
     # Summary
     print("========================")

package/scripts/validate.py

@@ -785,6 +785,9 @@ def validate_metadata_contracts(
     # Cross-validate versions: package.json vs manifest.json vs plugin.json
     _validate_version_sync(tk_dir, vr)
 
+    # Cross-validate the README platform matrix's Hooks column against reality
+    _validate_editor_hooks_honesty(tk_dir, vr)
+
     print()
     return actual_tests
 
@@ -836,6 +839,87 @@ def _validate_version_sync(tk_dir: Path, vr: ValidationResult) -> None:
                     )
 
 
+# Editors that receive lifecycle hook enforcement without a generate_*_hooks.py
+# generator: Claude is native (app/hooks), opencode bridges via its plugin
+# (generate_opencode_plugin.py). Every other hook-enabled editor is derived
+# from the generate_<editor>_hooks.py set so this check stays honest as
+# generators come and go.
+_NATIVE_HOOK_EDITORS = {"claude", "opencode"}
+
+# README platform label (lowercased) -> canonical editor key.
+_README_PLATFORM_KEY = {
+    "claude code": "claude",
+    "cursor": "cursor",
+    "windsurf": "windsurf",
+    "gemini cli": "gemini",
+    "github copilot": "copilot",
+    "cline": "cline",
+    "roo code": "roo",
+    "aider": "aider",
+    "augment": "augment",
+    "google antigravity": "antigravity",
+    "codex cli": "codex",
+    "opencode": "opencode",
+}
+
+
+def _validate_editor_hooks_honesty(tk_dir: Path, vr: ValidationResult) -> None:
+    """Ensure the README platform matrix's Hooks column matches reality.
+
+    Guards against the overclaim that every editor gets hook enforcement when
+    only a subset does — the machine-enforced constitution needs generated
+    hooks, and rules-only editors receive guidance text without blocking hooks.
+    """
+    scripts_dir = tk_dir / "scripts"
+    readme = tk_dir / "README.md"
+    if not scripts_dir.is_dir() or not readme.is_file():
+        return  # installed copy without source — nothing to cross-check
+
+    # Actual hook-enabled editors: native set + generate_<editor>_hooks.py stems.
+    actual = set(_NATIVE_HOOK_EDITORS)
+    for gen in scripts_dir.glob("generate_*_hooks.py"):
+        stem = gen.name[len("generate_"):-len("_hooks.py")]
+        actual.add(stem)
+
+    content = readme.read_text(encoding="utf-8")
+    if "| Hooks |" not in content:
+        return  # matrix has no Hooks column to validate
+
+    claimed: set[str] = set()
+    parsed_any = False
+    for line in content.splitlines():
+        if not line.startswith("|"):
+            continue
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if len(cells) < 4:
+            continue
+        key = _README_PLATFORM_KEY.get(cells[0].lower())
+        if key is None:
+            continue  # header, separator, or unknown row
+        parsed_any = True
+        if "✅" in cells[2]:  # ✅
+            claimed.add(key)
+
+    if not parsed_any:
+        return
+
+    missing = actual - claimed       # has hooks but README omits the ✅
+    overclaimed = claimed - actual   # README claims ✅ but no generator exists
+    if missing:
+        vr.error(
+            "README Hooks column understates enforcement for: "
+            + ", ".join(sorted(missing))
+        )
+    if overclaimed:
+        vr.error(
+            "README Hooks column overclaims enforcement for: "
+            + ", ".join(sorted(overclaimed))
+            + " (no hook generator or native bridge found)"
+        )
+    if not missing and not overclaimed:
+        print(f"  OK: editor hooks honesty ({len(claimed)} hook-enabled editors)")
+
+
 ROMAN_NUMERALS = ["I", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX", "X"]