feat(v1.8): AGENTS.md enforcement + empirical enforcement (#22)

* feat(v1.8): AGENTS.md enforcement + empirical enforcement

6 new hook ports, 2 guides, 1 smoke test, updated normalize lib.
Two Codex adversarial passes — 6 findings fixed before tag.

Hooks:
- agentsmd-bash-gate.sh (normalize + __NH_CONFLICT__ fail-closed + scoped allowlist)
- agentsmd-session-inject.sh
- three-failure-stop-gate.sh (normalize Grok payloads)
- claim-evidence-gate-dispatch.sh
- claim-evidence-gate.sh (bash floor, Gate 4)
- aof-eval-opportunity-counter.sh (env-var secret scrub + whitespace trim)

Guides:
- guides/advanced/when-to-write-a-hook.md (advisory exception + dedup question)
- guides/advanced/go-hook-dispatch-pattern.md

Tests:
- tests/smoke/hooks/grok-shape-normalize.sh (8/8 pass)

Docs:
- AGENT_FRAMEWORK.md v1.7 → v1.8, §5.3 matrix +5 rows
- CHANGELOG.md v1.8 section
- README.md + examples/hooks/README.md updated

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

* fix(v1.8): resolve 5 PRM-INFRA-001 Stage 1 findings before ship

HIGH agentsmd-bash-gate: remove broad case-arm allowlist (cat *AGENTS.md
bypass); replaced with anchored grep -qF on $AGENTS_PATH only.

HIGH three-failure-stop-gate: add no-op stubs for bc_record_exit/bc_write
when breadcrumb-lib.sh is absent — prevents exit-code corruption (127)
masking legitimate exit 2 blocks.

MED aof-eval-opportunity-counter: fix python3 silent-continue in
insert_opportunity (|| return on json-encode failure); use json.dumps
for tool_name and session_id to prevent JSON injection.

MED claim-evidence-gate: extract ALL backtick-quoted paths per hit, not
just the first — multi-path claims now check every cited path.

MED smoke test: add snake_case control payload to Test 6 to prevent
false-green from gate-blocks-everything scenario.

Smoke: 9/9 pass.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: m9751

AGENT_FRAMEWORK.md

@@ -1,4 +1,4 @@
-# Agent Operating Framework v1.7
+# Agent Operating Framework v1.8
 
 > A behavioral operating system for AI coding agents — born from production failures, not theory.
 >
@@ -304,7 +304,7 @@ See [`guides/enforcement-architecture.md`](guides/enforcement-architecture.md) f
 
 ### 5.3 Rule-to-Hook Coverage
 
-The escalation ladder above (memory → rule → hook) is aspirational — not every rule has a hook backing it, and the framework does not pretend otherwise. The matrix below is the accurate accounting of what ships in v1.6:
+The escalation ladder above (memory → rule → hook) is aspirational — not every rule has a hook backing it, and the framework does not pretend otherwise. The matrix below is the accurate accounting of what ships in v1.8:
 
 | Rule | Hook | Fail mode | Blast radius | Coverage |
 |---|---|---|---|---|
@@ -324,6 +324,16 @@ Five of six rules ship with hook backing as of v1.5. The single remaining adviso
 - If you adopt the framework expecting all rules to be system-enforced, this matrix is the reality check.
 - If you need stronger guarantees on the advisory rules, write your own `PreToolUse` hooks against your environment's specifics — the framework's hooks are reference implementations, not exhaustive coverage.
 
+**AGENTS.md enforcement hooks** (v1.8 — repo governance):
+- [`agentsmd-bash-gate.sh`](examples/hooks/agentsmd-bash-gate.sh) — blocks Bash commands that touch `~/repos/<name>/` unless AGENTS.md for that repo was Read this session *(fail-mode: closed, blast-radius: destructive)*
+- [`agentsmd-session-inject.sh`](examples/hooks/agentsmd-session-inject.sh) — SessionStart hook; when cwd is inside a repo, prints AGENTS.md to stdout as session context *(fail-mode: open, blast-radius: advisory)*
+
+**Empirical enforcement hooks** (v1.8 — claim and discipline gates):
+- [`three-failure-stop-gate.sh`](examples/hooks/three-failure-stop-gate.sh) — blocks the 4th `fix(...)` commit in 2 hours unless a `# halted-and-researched:` attestation is present; 6,262 fires / 13 blocks in production *(fail-mode: advisory — fail-open on repo-resolve failure)*
+- [`claim-evidence-gate-dispatch.sh`](examples/hooks/claim-evidence-gate-dispatch.sh) — cross-platform front door for Gate 4; probes native Go binary (two-probe trust check) before falling back to bash floor; live telemetry Mac 2026-06-27 PR #571 *(fail-mode: closed, blast-radius: security)*
+- [`claim-evidence-gate.sh`](examples/hooks/claim-evidence-gate.sh) — bash floor for Gate 4; blocks assertion language and path-cited claims without a session Read breadcrumb *(fail-mode: closed, blast-radius: security)*
+- [`aof-eval-opportunity-counter.sh`](examples/hooks/aof-eval-opportunity-counter.sh) — PostToolUse/SessionStart/UserPromptSubmit hook; POSTs to `eval.opportunities` for DPMO measurement; health signal = `eval.opportunities` rows (NOT `hook_events` fire_count); requires `AOF_EVAL_SUPABASE_URL` + `AOF_EVAL_SUPABASE_KEY` env vars *(fail-mode: open, blast-radius: telemetry)*
+
 **Meta-hooks** (not bound to a single rule):
 - [`deprecated-field-gate.sh`](examples/hooks/deprecated-field-gate.sh) — template for blocking writes that reference deprecated DB columns or API fields *(fail-mode: closed, blast-radius: destructive)*
 - [`empty-rule-body-gate.sh`](examples/hooks/empty-rule-body-gate.sh) — pre-merge CI check that rejects rule files with empty bodies (< 200 bytes) or missing `## Why` sections *(fail-mode: closed, blast-radius: security — protects framework integrity against false-positive "applied" claims)*
@@ -371,7 +381,7 @@ See [`guides/rule-consolidation.md`](guides/rule-consolidation.md) for a worked
 
 ---
 
-## Framework Structure (v1.5)
+## Framework Structure (v1.8)
 
 ```
 AGENT_FRAMEWORK.md          ← This file. The complete behavioral spec.
@@ -391,6 +401,8 @@ guides/
     hook-audit-methodology.md    ← 4-track audit pattern (v1.6)
     silent-failure-discipline.md ← Every fail-open path must log (v1.7)
     agents-md-standard.md   ← Three-level repo governance contract (v1.7)
+    when-to-write-a-hook.md ← Decision test for hook vs. rule (v1.8)
+    go-hook-dispatch-pattern.md  ← Go binary + bash floor dispatch pattern (v1.8)
 examples/
   claude-code-rules/        ← Sample rule files for Claude Code
   hooks/                    ← Reference hook implementations (Claude Code-specific)
@@ -406,6 +418,7 @@ Full per-release notes live in [CHANGELOG.md](CHANGELOG.md). The framework file
 
 Headline changes from recent versions:
 
+- **v1.8** — AGENTS.md enforcement + empirical enforcement release. 6 new hooks: `agentsmd-bash-gate.sh`, `agentsmd-session-inject.sh`, `three-failure-stop-gate.sh`, `claim-evidence-gate-dispatch.sh`, `claim-evidence-gate.sh`, `aof-eval-opportunity-counter.sh`. 2 new guides: `when-to-write-a-hook.md` and `go-hook-dispatch-pattern.md`. New smoke test: `tests/smoke/hooks/grok-shape-normalize.sh`. Updated `lib/normalize-hook-input.sh` with dual-shape conflict detection. §5.3 matrix extended with 5 new hook rows. CEG telemetry live Mac PR #571.
 - **v1.7** — Provable hooks release: `startup-gate.sh` (SessionStart governance check), `normalize-hook-input.sh` (cross-runtime payload normalization), `hook-telemetry-stop.sh` (session-end telemetry). New guides: `silent-failure-discipline.md` (ADR 0012 — every fail-open path must log) and `agents-md-standard.md` (three-level repo governance contract). Incidents #36–#38.
 - **v1.6** — Hook operations layer: `breadcrumb-lib.sh` shared session library, `CLAUDE_HOOKS_SAFE_MODE` emergency bypass pattern, `# fail-mode: silent-skip` taxonomy tier for watcher-class hooks. New guides: `hook-operations.md` (the three operational questions) and `hook-audit-methodology.md` (4-track audit pattern). §5.2 updated with bypass + breadcrumb protocol as standard requirements. AOF self-eval harness (`b3d8451`) on main.
 - **v1.5** — `secure-config-gate.sh`, `focus-breadcrumb.sh` + `focus-confirmation-gate.sh`, `dormant-code-gate.sh`. §5.3 coverage moves from 3-of-6 enforced to **5-of-6 enforced**. `no-local-infrastructure` rewritten as a hosting decision framework (advisory by design).

CHANGELOG.md

@@ -4,6 +4,74 @@ All notable changes to this framework follow [Keep a Changelog](https://keepacha
 
 ---
 
+## [1.8] — 2026-06
+
+### Background
+
+v1.7 answered: can you prove hooks work? v1.8 answers: do you ship the hooks that enforce the rules you already have written? Two rule gaps had hooks drafted in the private config but not ported to the public repo: AGENTS.md enforcement (repo governance) and empirical discipline gates (three-failure stop, claim-evidence). Both are now public.
+
+### What v1.8 covers ("AGENTS.md enforcement + empirical enforcement" release)
+
+Six new hook ports, two new guides, one new smoke test, and updated `lib/normalize-hook-input.sh` with dual-shape conflict detection.
+
+### Added
+
+- **`examples/hooks/agentsmd-bash-gate.sh`** — PreToolUse gate for Bash. Blocks commands that touch `~/repos/<name>/` unless AGENTS.md for that repo was Read this session. Complements `read-gate.sh` (which covers Edit/Write) with Bash-side coverage. Port hardening: added `source lib/normalize-hook-input.sh` and fixed the parser to read `tool_input.command` (not `input.command`) for correct Claude Code envelope handling.
+
+- **`examples/hooks/agentsmd-session-inject.sh`** — SessionStart advisory hook. When cwd is inside `~/repos/<name>/`, prints AGENTS.md to stdout so Claude loads it as session context before the first user prompt. Ports directly; no hardening needed.
+
+- **`examples/hooks/three-failure-stop-gate.sh`** — PreToolUse gate for Bash. Blocks the 4th `fix(...)` commit within 2 hours unless the commit body contains `# halted-and-researched: <one-line>`. State stored in `~/.claude/state/three-failure-stop/<repo>__<file>.log`. Production telemetry: 6,262 fires / 13 blocks. Fail-open on repo-resolve failure (advisory by design — false-positives more disruptive than false-negatives for this pattern).
+
+- **`examples/hooks/claim-evidence-gate-dispatch.sh`** — Cross-platform dispatch wrapper for Gate 4. Probes the native Go binary with a two-probe trust check (must allow a clean payload AND block a claim-shaped payload) before trusting it. Falls back to `claim-evidence-gate.sh` if the binary is missing, wrong architecture, or fails either probe. Fail-closed with no runnable gate at all. Telemetry breadcrumb fires at the dispatch layer (single choke point). CEG fire_count>0 on Mac confirmed 2026-06-27 (PR #571).
+
+- **`examples/hooks/claim-evidence-gate.sh`** — Bash floor for Gate 4. Blocks assertion language patterns and explicit path-cited claims without a session Read breadcrumb. Pattern list aligned one-for-one with the Go binary's `assertionPatterns` (softened per ADR 0064 — bare "confirmed"/"verified" removed after 58/59 audit showed false positives). Empty stdin fails closed. Self-exempts via path-allowlist (the file itself is allowlisted to prevent gate self-block during deployment).
+
+- **`examples/hooks/aof-eval-opportunity-counter.sh`** — Fires on PreToolUse, SessionStart, and UserPromptSubmit (three settings.json registrations). POSTs to `eval.opportunities` table for DPMO measurement. **Health signal: `eval.opportunities` row count.** `telemetry.hook_events` fire_count is expected to be 0 for this hook (it does not use `bc_write` / `hook-telemetry-stop`). Port hardening: replaced hardcoded Supabase URL + anon key with `AOF_EVAL_SUPABASE_URL` + `AOF_EVAL_SUPABASE_KEY` env vars; hook fails open if either is unset.
+
+- **`guides/advanced/when-to-write-a-hook.md`** — Decision test for hook vs. rule. Three questions: (1) has the rule been violated with real consequence? (2) can the hook detect the violation mechanically? (3) is the blast radius acceptable? Includes hook type table by blast radius, what belongs in a rule (not a hook), hook anatomy invariants, and a 4-step test matrix before shipping.
+
+- **`guides/advanced/go-hook-dispatch-pattern.md`** — Canonical pattern for shipping Go binary hooks with a bash fallback. Explains the 2026-06-13 incident (Mach-O binary failing open on Win11), the two-probe trust model, build-at-install-time pattern, gitignore for architecture-specific binaries, bash floor alignment requirements, and settings.json registration via dispatch wrapper only.
+
+- **`tests/smoke/hooks/grok-shape-normalize.sh`** — 6-case smoke test for `lib/normalize-hook-input.sh`. Tests: camelCase normalization, snake_case passthrough, dual-shape conflict sentinel (`__NH_CONFLICT__`), empty input, malformed JSON. Gate: all 6 PASS before tagging v1.8.
+
+- **`examples/hooks/lib/normalize-hook-input.sh`** — Updated from v1.7 with dual-shape conflict detection. When a payload carries a field in both camelCase and snake_case shapes, `nh_normalize` now emits `__NH_CONFLICT__` sentinel instead of normalizing. The dispatch wrapper and gate check for this sentinel and fail closed (block) — a dual-shape payload is unevaluable; scanning one branch while the runtime executes the other risks claim bypass.
+
+- **3 new sanitized incidents** in `INCIDENTS.md` (#39, #40, #41).
+
+### Changed
+
+- **`AGENT_FRAMEWORK.md`** — version bump to v1.8. §5.3 matrix extended with 5 new hook rows (AGENTS.md enforcement + empirical gates). Framework structure updated with two new advanced guides. Version history entry added.
+- **`README.md`** — v1.8 references, 41 incidents, 5 new hooks in hook table.
+- **`examples/hooks/README.md`** — 5 new inventory rows (one per new hook, plus counter).
+
+### What is NOT in v1.8 (deferred to v1.9)
+
+- **Go binary for claim-evidence-gate** — the dispatch wrapper + bash floor ship; the public Go source does not. The private Go binary is architecture-specific (Mach-O arm64) and requires build tooling. Public port deferred until a portable build pipeline exists for the AOF repo.
+- **FORGET mechanism** — carried from v1.7. Still the hard prerequisite for Phase D global deploy of the memory system.
+- **`distill-memory.py` regex fix** — resolved in private config (2026-06-27); not a public AOF artifact. Removed from deferred list.
+
+### Release checklist
+
+- [x] Port `agentsmd-bash-gate.sh` (with normalize-hook-input + tool_input.command fix)
+- [x] Port `agentsmd-session-inject.sh`
+- [x] Port `three-failure-stop-gate.sh`
+- [x] Port `claim-evidence-gate-dispatch.sh`
+- [x] Port `claim-evidence-gate.sh` (bash floor)
+- [x] Port `aof-eval-opportunity-counter.sh` (with secret scrub)
+- [x] Write `guides/advanced/when-to-write-a-hook.md`
+- [x] Write `guides/advanced/go-hook-dispatch-pattern.md`
+- [x] Write `tests/smoke/hooks/grok-shape-normalize.sh`
+- [x] Update `lib/normalize-hook-input.sh` (dual-shape conflict)
+- [x] Smoke test PASS (6/6)
+- [x] Edit `AGENT_FRAMEWORK.md` v1.7 → v1.8 + §5.3 matrix + structure
+- [x] Edit `README.md`
+- [x] Edit `examples/hooks/README.md`
+- [x] Insert CHANGELOG v1.8
+- [ ] `git tag v1.8 && git push --tags`
+- [ ] Create GitHub release
+
+---
+
 ## [1.7] — 2026-06
 
 ### Background

README.md

@@ -18,7 +18,7 @@ See [guides/getting-started.md](guides/getting-started.md) for the full adoption
 
 You've set up CLAUDE.md. You've built a few skills. You're using Projects Memory. But outputs are still inconsistent, the agent ignores rules under pressure, and you're manually reviewing everything.
 
-This framework is the next step. It adds rules with documented enforcement contracts (some advisory by design), circuit breakers (stop after 3 failures), and an escalation model (advice → law → barriers) that makes your CLAUDE.md actually stick. See the [rule-to-hook coverage matrix](AGENT_FRAMEWORK.md#53-rule-to-hook-coverage) for what is system-enforced versus advisory in v1.7 — five of six rules ship with hooks; one (`no-local-infrastructure`) is a decision framework that is advisory by design.
+This framework is the next step. It adds rules with documented enforcement contracts (some advisory by design), circuit breakers (stop after 3 failures), and an escalation model (advice → law → barriers) that makes your CLAUDE.md actually stick. See the [rule-to-hook coverage matrix](AGENT_FRAMEWORK.md#53-rule-to-hook-coverage) for what is system-enforced versus advisory in v1.8 — five of six rules ship with hooks; one (`no-local-infrastructure`) is a decision framework that is advisory by design.
 
 If you're just getting started with Claude Code, read the beginner guides first. If you've hit the wall where your CLAUDE.md "stops working," [start here](guides/from-beginner-to-framework.md).
 
@@ -49,7 +49,7 @@ Every rule exists because its absence caused a specific, documented failure. See
 ## Library Contents
 
 ### The Framework
-- **[AGENT_FRAMEWORK.md](AGENT_FRAMEWORK.md)** — The complete framework (v1.7). Use as your project's CLAUDE.md.
+- **[AGENT_FRAMEWORK.md](AGENT_FRAMEWORK.md)** — The complete framework (v1.8). Use as your project's CLAUDE.md.
 
 ### Guides
 - **[From Beginner to Framework](guides/from-beginner-to-framework.md)** — You've built CLAUDE.md and skills but outputs are inconsistent. Here's why and what to do next.
@@ -93,13 +93,19 @@ Shell scripts that enforce rules at the tool-call level — the third tier of th
 | [startup-gate.sh](examples/hooks/startup-gate.sh) | SessionStart advisory | Checks repo, AGENTS.md, active plan, and hook registration gap at session start; writes drift report |
 | [hook-telemetry-stop.sh](examples/hooks/hook-telemetry-stop.sh) | Stop advisory | Reads fire/block breadcrumbs at session end; bulk-INSERTs telemetry rows |
 | [lib/normalize-hook-input.sh](examples/hooks/lib/normalize-hook-input.sh) | Library (source only) | Normalizes hook payload field names and tool-name literals across Claude Code and Grok runtimes |
+| [agentsmd-bash-gate.sh](examples/hooks/agentsmd-bash-gate.sh) | PreToolUse hard block | Blocks Bash in `~/repos/<name>/` unless AGENTS.md for that repo was Read this session |
+| [agentsmd-session-inject.sh](examples/hooks/agentsmd-session-inject.sh) | SessionStart advisory | Injects AGENTS.md into session context when cwd is inside a repo |
+| [three-failure-stop-gate.sh](examples/hooks/three-failure-stop-gate.sh) | PreToolUse advisory block | Blocks 4th `fix(...)` commit in 2 hours without a halted-and-researched attestation |
+| [claim-evidence-gate-dispatch.sh](examples/hooks/claim-evidence-gate-dispatch.sh) | PreToolUse hard block | Cross-platform Gate 4 dispatcher; probes Go binary (two-probe trust check), falls back to bash floor |
+| [claim-evidence-gate.sh](examples/hooks/claim-evidence-gate.sh) | PreToolUse hard block | Bash floor for Gate 4; blocks assertion language and path-cited claims without a session Read |
+| [aof-eval-opportunity-counter.sh](examples/hooks/aof-eval-opportunity-counter.sh) | Multi-event advisory | DPMO counter; POSTs to `eval.opportunities` per tool call; health = row count |
 
 See [§5.3 Rule-to-Hook Coverage](AGENT_FRAMEWORK.md#53-rule-to-hook-coverage) for which rule each hook backs and the full enforced-vs-advisory accounting.
 
 See [examples/hooks/README.md](examples/hooks/README.md) for setup instructions and the breadcrumb pattern.
 
 ### Incident Log
-- **[INCIDENTS.md](INCIDENTS.md)** — 38 sanitized incidents linking real failures to the rules they produced. Month-precision dates.
+- **[INCIDENTS.md](INCIDENTS.md)** — 41 sanitized incidents linking real failures to the rules they produced. Month-precision dates.
 
 ## The Key Insight