feat(hooks): add enchanter-hooks plugin — 11 advisory fail-open Claude Code hooks

A new vis package (enchanter-hooks) shipping 11 deterministic, fail-open, quiet hooks that
enforce the conduct substrate at lifecycle events in-context conduct can't self-time.
Distributed via the vis marketplace (/plugin install enchanter-hooks@vis) — hooks activate
natively, no settings.json editing.

Hooks (event -> F-code):
  compact-checkpoint           SessionStart(compact)    F03
  secret-scan                  PreToolUse(Write|Edit)   secret-exfil
  config-self-edit-guard       PreToolUse(Write|Edit)   self-modification
  substrate-engine-write-guard PreToolUse(Write|Edit)   F24
  artifact-authorship-guard    PreToolUse(Write|Edit)   authorship
  append-only-log-edit-guard   PreToolUse(Edit)         F14
  reversibility-guard          PreToolUse(Bash)         F26
  debug-hygiene                PostToolUse(Write|Edit)  code-hygiene
  post-write-validate          PostToolUse(Write|Edit)  F02/F14
  stale-pathref-guard          PostToolUse(Write|Edit)  F02/F27
  machine-path-leak-guard      PostToolUse(Write|Edit)  F02

Each clears a 5-part smart-test (deterministic, does-what-conduct-can't, advisory/fail-open,
non-redundant, quiet) and is verified incl. false-positive + fail-open audits. Built from an
open-web hook survey + a per-package mining sweep of the vis conduct substrate.

Also: register in marketplace.json (8 plugins), list in README, and add .gitattributes
forcing LF on *.sh so marketplace-cloned hooks don't break on Windows CRLF checkout.

Author: klaiderman

.claude-plugin/marketplace.json

@@ -2,7 +2,7 @@
   "name": "vis",
   "owner": { "name": "enchanter-ai" },
   "metadata": {
-    "description": "Behavioral substrate for the @enchanter-ai ecosystem — conduct-as-code, failure taxonomy, engines, recipes. Split into 7 focused plugins.",
+    "description": "Behavioral substrate for the @enchanter-ai ecosystem — conduct-as-code, failure taxonomy, engines, recipes. Split into 8 focused plugins.",
     "version": "0.6.0",
     "pluginRoot": "./packages"
   },
@@ -13,6 +13,7 @@
     { "name": "enchanter-web",           "source": "web",           "version": "0.6.0", "description": "Live web access conduct: cache, dedup, budget, cite hygiene." },
     { "name": "enchanter-memory",        "source": "memory",        "version": "0.6.0", "description": "Cross-session memory hygiene: working memory, decay, recall verification." },
     { "name": "enchanter-cost",          "source": "cost",          "version": "0.6.0", "description": "Session economics: cost-accounting, latency-budgeting, eval-harnesses recipe." },
-    { "name": "enchanter-safety",        "source": "safety",        "version": "0.6.0", "description": "Safety + compliance + security + operator-wiring: refusal-and-recovery, F15-F21 taxonomy, FedRAMP/ISO/SOC2/NIST evidence, pentest, synthetic-fire, OTLP/PagerDuty/Sentry wiring." }
+    { "name": "enchanter-safety",        "source": "safety",        "version": "0.6.0", "description": "Safety + compliance + security + operator-wiring: refusal-and-recovery, F15-F21 taxonomy, FedRAMP/ISO/SOC2/NIST evidence, pentest, synthetic-fire, OTLP/PagerDuty/Sentry wiring." },
+    { "name": "enchanter-hooks",         "source": "hooks",         "version": "0.6.0", "description": "Advisory Claude Code hooks (fail-open, deterministic, quiet) that enforce the conduct substrate at lifecycle events: post-compaction checkpoint (F03), pre-write secret scan, post-edit debug-artifact hygiene. Install activates hooks natively — no settings.json editing." }
   ]
 }

.gitattributes

@@ -0,0 +1,9 @@
+# Shell scripts must stay LF on every platform. They run via bash — including the
+# enchanter-hooks plugin scripts, which are distributed through the vis marketplace and
+# cloned into users' plugin caches (~/.claude/plugins/cache) on Windows too. A CRLF
+# checkout makes bash fail on the trailing \r, so force LF regardless of core.autocrlf.
+*.sh text eol=lf
+
+# Keep these LF as well for cross-platform consistency of the distributed package.
+*.json text eol=lf
+*.md text eol=lf

README.md

@@ -29,7 +29,7 @@ The behavioral substrate for building durable AI agents — conduct, engines, ta
 
 **In plain English:** Most agent stacks ship with prompts, tools, and hopes. The thing that actually keeps an agent from refactoring code you didn't ask it to touch, or pushing to main after you said not to, isn't another tool — it's a behavior rule that survives the long context. vis is the dependency-free pile of those rules, plus the math, taxonomy, and host recipes around them.
 
-**Technically:** 37 conduct modules across 7 packages (`core` / `skills` / `orchestration` / `safety` / `web` / `memory` / `cost`). 12 algorithmic engines with paper-backed derivations (Aho-Corasick pattern detection, Shannon entropy, Beta-Bernoulli trust scoring, Markov drift, Hunt-Szymanski LCS, Zhang-Shasha tree-edit, Tarjan SCC, Wald SPRT, Jaccard-cosine boundary segmentation, contextual LLM bandit, agentproof DFA, sycophancy calibration). 21 named failure codes (F01–F21) with testable counters, mapped to a 5-axis hybrid taxonomy (memory / reflection / planning / action / system) and 21 incident-response runbooks. 9 adoption recipes (Claude Code, OpenAI Agents SDK, Cursor, LangChain, Pydantic-AI, BAML, raw system-prompt, eval-harnesses, stupid-agent-review). Zero runtime dependencies — pure prose + math, loadable into any system that accepts text instructions.
+**Technically:** 37 conduct modules across 7 conduct packages (`core` / `skills` / `orchestration` / `safety` / `web` / `memory` / `cost`), plus a `hooks` package shipping 6 runtime advisory hooks (the **enchanter-hooks** plugin, installable via the vis marketplace). 12 algorithmic engines with paper-backed derivations (Aho-Corasick pattern detection, Shannon entropy, Beta-Bernoulli trust scoring, Markov drift, Hunt-Szymanski LCS, Zhang-Shasha tree-edit, Tarjan SCC, Wald SPRT, Jaccard-cosine boundary segmentation, contextual LLM bandit, agentproof DFA, sycophancy calibration). 21 named failure codes (F01–F21) with testable counters, mapped to a 5-axis hybrid taxonomy (memory / reflection / planning / action / system) and 21 incident-response runbooks. 9 adoption recipes (Claude Code, OpenAI Agents SDK, Cursor, LangChain, Pydantic-AI, BAML, raw system-prompt, eval-harnesses, stupid-agent-review). Zero runtime dependencies — pure prose + math, loadable into any system that accepts text instructions.
 
 ## Origin
 
@@ -132,9 +132,14 @@ vis/
 │   │                                  adaptive-adversary-baseline, provider-resilience
 │   ├── memory/                      ← memory hygiene
 │   │   └── conduct/                 ← memory-hygiene.md
-│   └── cost/                        ← cost + latency + eval harnesses
-│       ├── conduct/                 ← cost-accounting.md, latency-budgeting.md
-│       └── recipes/                 ← eval-harnesses.md
+│   ├── cost/                        ← cost + latency + eval harnesses
+│   │   ├── conduct/                 ← cost-accounting.md, latency-budgeting.md
+│   │   └── recipes/                 ← eval-harnesses.md
+│   └── hooks/                        ← runtime advisory hooks (the enchanter-hooks plugin)
+│       ├── hooks/hooks.json         ← 6 hooks: SessionStart(compact) / PreToolUse / PostToolUse
+│       ├── scripts/                 ← compact-checkpoint, secret-scan, config-self-edit-guard,
+│       │                              reversibility-guard, debug-hygiene, post-write-validate
+│       └── .claude-plugin/          ← plugin.json (installable via the vis marketplace)
 ├── docs/                            ← cross-cutting docs: architecture overview, ADRs
 │                                       (0001 four-layers, 0002 taxonomy expansion),
 │                                       CROSS_REPO_VERSIONING.md
@@ -143,7 +148,7 @@ vis/
 └── package.json                     ← changesets meta-package for cross-repo versioning
 ```
 
-Counts as of the latest tag: **37 conduct modules** across core / skills / orchestration / safety / web / memory / cost · **12 engines** in `orchestration/engines/` · **21 failure codes** split F01–F14 (core) and F15–F21 (safety) · **21 runbooks** mirroring the F-codes · **9 recipes** (8 in `skills/recipes/` + `cost/recipes/eval-harnesses.md`).
+Counts as of the latest tag: **37 conduct modules** across core / skills / orchestration / safety / web / memory / cost · **12 engines** in `orchestration/engines/` · **21 failure codes** split F01–F14 (core) and F15–F21 (safety) · **21 runbooks** mirroring the F-codes · **9 recipes** (8 in `skills/recipes/` + `cost/recipes/eval-harnesses.md`) · **6 runtime advisory hooks** in `hooks/` (the **enchanter-hooks** plugin).
 
 ---
 
@@ -213,7 +218,7 @@ In your project's `CLAUDE.md`:
 - @shared/vis/packages/core/conduct/failure-modes.md
 ```
 
-For runtime enforcement (not just description), wire hooks per [`packages/skills/recipes/claude-code.md`](packages/skills/recipes/claude-code.md) § Enforcement wiring. The framework now includes copy-paste shell skeletons in [`packages/core/conduct/hooks.md`](packages/core/conduct/hooks.md) § Starter patterns — PreToolUse deny, PostToolUse inject, Stop notify.
+For runtime enforcement (not just description), wire hooks per [`packages/skills/recipes/claude-code.md`](packages/skills/recipes/claude-code.md) § Enforcement wiring. The framework now includes copy-paste shell skeletons in [`packages/core/conduct/hooks.md`](packages/core/conduct/hooks.md) § Starter patterns — PreToolUse deny, PostToolUse inject, Stop notify. Or install them ready-made — `/plugin marketplace add enchanter-ai/vis` then `/plugin install enchanter-hooks@vis` — the **enchanter-hooks** plugin ships 6 advisory, fail-open hooks (post-compaction checkpoint, secret scan, config self-edit guard, reversibility guard, debug-hygiene, syntax validation) that activate without editing `settings.json`.
 
 ### OpenAI Agents SDK
 

packages/hooks/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "enchanter-hooks",
+  "version": "0.6.0",
+  "description": "vis-governed advisory Claude Code hooks: deterministic, fail-open enforcement of the conduct substrate at lifecycle events in-context conduct cannot self-time. v0.6 ships eleven quiet, conditional hooks (speak only when they have something to say) across SessionStart / PreToolUse / PostToolUse: post-compaction checkpoint (F03), secret scan, config self-edit guard, substrate-engine-write guard (F24), append-only-ledger guard (F14), artifact-authorship guard, bash reversibility guard (F26), debug-artifact hygiene, syntax validation (F02/F14), stale-pathref guard (F02/F27), and machine-path-leak guard. Every hook exits 0 and never blocks.",
+  "dependencies": ["enchanter-core"]
+}

packages/hooks/README.md

@@ -0,0 +1,62 @@
+# enchanter-hooks
+
+vis-governed **advisory** Claude Code hooks — deterministic, fail-open enforcement of the
+conduct substrate at lifecycle events that in-context conduct **cannot self-time**.
+
+Distributed the native way: `enchanter-hooks` is a Claude Code plugin in the `vis` marketplace.
+Installing it activates the hooks automatically — no `settings.json` editing.
+
+```
+/plugin marketplace add enchanter-ai/vis
+/plugin install enchanter-hooks@vis
+```
+
+## Design contract
+
+Every hook here obeys five rules (the "smart-test" — a hook that fails any is rejected, not shipped):
+
+1. **Deterministic trigger** — fires on an unambiguous event (tool call / lifecycle), never fuzzy intent.
+2. **Does what conduct can't** — earns its place by acting where in-context conduct structurally can't, or reliably misses.
+3. **Advisory / fail-open** — injects or warns, **never blocks**; every script exits 0 (and on a malformed payload, does nothing).
+4. **Not redundant** — doesn't re-implement Claude Code's built-in permission gating (or, where it complements it, adds a stated delta).
+5. **Quiet** — emits *nothing* unless it has something to say, so it never becomes ignored wallpaper.
+
+## Hooks (v0.6 — 11)
+
+| Hook | Event | F-code | What it does |
+|---|---|---|---|
+| `compact-checkpoint` | `SessionStart(compact)` | F03 | Re-injects a goal/state/invariants checkpoint right after a compaction (the one moment the model can't self-time). |
+| `secret-scan` | `PreToolUse(Write\|Edit)` | secret-exfil | Scans content about to be written for high-signal secret patterns; warns. |
+| `config-self-edit-guard` | `PreToolUse(Write\|Edit)` | self-modification | Warns on edits to the agent's own startup/hook/plugin config (`.claude/settings.json`, `hooks.json`, `.claude-plugin/`, `.mcp.json`). |
+| `substrate-engine-write-guard` | `PreToolUse(Write\|Edit)` | F24 | Warns on hand-writes to inference-engine state (`catalog.json`/`artifacts.jsonl`/briefings/`.lock`) — must go through the engine. |
+| `artifact-authorship-guard` | `PreToolUse(Write\|Edit)` | authorship | Warns when a public artifact (LICENSE/`.cff`/README/`.bib`) has author lines that don't credit "Enchanter Labs". Generic — no hardcoded names. |
+| `append-only-log-edit-guard` | `PreToolUse(Edit\|MultiEdit)` | F14 | Warns on an in-place Edit of an append-only ledger (`.jsonl`/`.ndjson`) — append a row instead. |
+| `reversibility-guard` | `PreToolUse(Bash)` | F26 | Advisory caution on hard-to-reverse commands (`rm -rf`, force-push, `--hard`, `mkfs`, `curl\|sh`, `DROP TABLE`). |
+| `debug-hygiene` | `PostToolUse(Write\|Edit)` | code-hygiene | Flags leftover debug artifacts (`console.log`/`debug`, `debugger`, `breakpoint()`, `pdb`/`pry`). |
+| `post-write-validate` | `PostToolUse(Write\|Edit)` | F02/F14 | Fast-parses the written file (`.py`/`.json`/`.sh`/`.toml`) and warns on a syntax error, same turn. |
+| `stale-pathref-guard` | `PostToolUse(Write\|Edit)` | F02/F27 | After writing a `.md`, checks its `@-imports` / local links actually resolve — the silent CLAUDE.md breakage. |
+| `machine-path-leak-guard` | `PostToolUse(Write\|Edit)` | F02 | Warns when a git-tracked file gains machine-absolute paths (`C:\git`, `/Users/<n>/`) — use repo-relative form. |
+
+Built in two passes: the first 6 from an open-web survey of agent-hook patterns; the last 5 from a
+per-package mining sweep of the vis conduct substrate (each candidate gate-tested, deduped, and
+verified against live repo evidence — e.g. `stale-pathref` against real `@-imports`, `authorship`
+against a live `CITATION.cff` slip).
+
+## Deferred (considered, did not clear the bar — or need a convention first)
+
+- `claude-format-to-nonclaude-target`, `scratch-in-prompts-folder-guard` — wixie-`prompts/`-specific, not general vis; belong in a wixie-local hook set.
+- `mcp-manifest-gate` — would warn on *every* MCP call until an `mcp-manifests/*.fingerprint.json` convention exists → wallpaper today. Revisit when that convention lands.
+- `finish-checklist` (Stop), `substrate-injection` / `build-premise` (UserPromptSubmit) — fire every turn or rely on fuzzy intent. `build-premise` is superseded by the F29 *conduct* gate in `doubt-engine.md`.
+- `backup-before-compact` — low value (transcripts are usually recoverable) + project-side file writes.
+- egress-fence, write-scope-audit, subagent-spawn/budget counters, `learnings.md`/`SKILL.md` schema lints — failed "quiet" in practice, or cited contract files that don't exist in this codebase.
+
+## Notes
+
+- Scripts are **self-contained** (no references outside the plugin root) so they survive the
+  plugin cache (`~/.claude/plugins/cache/`). Require `jq` + `bash`; `python3`/`python` for the
+  syntax validators (fail-open if absent).
+- `config-self-edit-guard`, `reversibility-guard`, and `substrate-engine-write-guard` are advisory
+  **complements** to permission gating, not replacements — the delta is the self-config/substrate
+  category and the reversibility framing.
+- The `vis-drift` SessionStart hook is **not** shipped here — it is project-local (reads the
+  consuming repo's `.vis-lock` against a sibling `../vis` checkout), which is not plugin-portable.

packages/hooks/hooks/hooks.json

@@ -0,0 +1,47 @@
+{
+  "description": "enchanter-hooks — vis advisory Claude Code hooks. Deterministic triggers, fail-open (every hook exits 0, never blocks), and quiet (each emits nothing unless it has something to say). Each maps to a vis F-code. Self-contained scripts (plugin-cache-safe) under scripts/, referenced via ${CLAUDE_PLUGIN_ROOT}.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [
+          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/compact-checkpoint.sh\"", "timeout": 5 }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/secret-scan.sh\"", "timeout": 5 },
+          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/config-self-edit-guard.sh\"", "timeout": 5 },
+          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/substrate-engine-write-guard.sh\"", "timeout": 5 },
+          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/artifact-authorship-guard.sh\"", "timeout": 5 }
+        ]
+      },
+      {
+        "matcher": "Edit|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/append-only-log-edit-guard.sh\"", "timeout": 5 }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/reversibility-guard.sh\"", "timeout": 5 }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/debug-hygiene.sh\"", "timeout": 5 },
+          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/post-write-validate.sh\"", "timeout": 5 },
+          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/stale-pathref-guard.sh\"", "timeout": 5 },
+          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/machine-path-leak-guard.sh\"", "timeout": 5 }
+        ]
+      }
+    ]
+  }
+}

packages/hooks/scripts/append-only-log-edit-guard.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# append-only-log-edit-guard.sh — PreToolUse(Edit|MultiEdit) advisory. Counter to F14 (append-only ledger).
+#
+# Warns when an in-place Edit targets an append-only ledger (*.jsonl / *.ndjson, or a named
+# artifacts/metrics/ledger/audit log). Such files take a NEW appended row — rewriting a prior row in
+# place corrupts their history. Advisory: stderr + exit 0. Quiet unless the path matches. Self-contained.
+set -uo pipefail
+
+[[ -n "${CLAUDE_SUBAGENT:-}" ]] && exit 0
+
+payload="$(cat 2>/dev/null || true)"
+tool="$(printf '%s' "$payload" | jq -r '.tool_name // empty' 2>/dev/null || true)"
+file="$(printf '%s' "$payload" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)"
+[[ -z "$file" ]] && exit 0
+case "$tool" in Edit|MultiEdit) ;; *) exit 0 ;; esac
+
+if printf '%s' "$file" | grep -Eq '\.(jsonl|ndjson)$|(artifacts|metrics|ledger|audit)\.jsonl$'; then
+  {
+    echo "[vis F14 · append-only] $(basename "$file") looks like an append-only ledger."
+    echo "An in-place Edit rewrites a prior row — append a NEW row instead, or you corrupt the ledger's history."
+  } >&2
+fi
+
+exit 0

packages/hooks/scripts/artifact-authorship-guard.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# artifact-authorship-guard.sh — PreToolUse(Write|Edit) advisory. Authorship contract.
+#
+# Warns when a PUBLIC artifact (LICENSE, *.cff / CITATION, README, *.bib) is written with an
+# author / copyright / alias line that does NOT credit "Enchanter Labs". GENERIC — it does not
+# hardcode any individual's name or email; it simply flags authorship lines missing the org credit.
+# Advisory: stderr + exit 0. Quiet unless an author line lacks the credit. Self-contained.
+set -uo pipefail
+
+[[ -n "${CLAUDE_SUBAGENT:-}" ]] && exit 0
+
+payload="$(cat 2>/dev/null || true)"
+file="$(printf '%s' "$payload" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)"
+content="$(printf '%s' "$payload" | jq -r '.tool_input.content // .tool_input.new_string // empty' 2>/dev/null || true)"
+[[ -z "$file" || -z "$content" ]] && exit 0
+
+case "$(basename "$file")" in
+  LICENSE|LICENSE.*|*.cff|CITATION.*|README.md|*.bib) ;;
+  *) exit 0 ;;
+esac
+
+authlines="$(printf '%s' "$content" | grep -niE 'author|copyright|alias|\(c\)' | head -10 || true)"
+[[ -z "$authlines" ]] && exit 0
+
+if ! printf '%s' "$content" | grep -qi 'Enchanter Labs'; then
+  {
+    echo "[vis · authorship] $(basename "$file") has author/copyright lines that don't credit 'Enchanter Labs':"
+    printf '%s\n' "$authlines" | head -4
+    echo "Public-artifact authorship must read 'Enchanter Labs', not a personal handle/email."
+  } >&2
+fi
+
+exit 0