ceo-orchestration 1.0.0

package/.claude/adr/ADR-008-hook-adapter-layer.md

@@ -0,0 +1,169 @@
+# ADR-008: Hook Adapter Layer (neutral event/decision contract)
+
+## Status: ACCEPTED (2026-04-12)
+
+## Context
+
+PLAN-004 Phase 4 consensus finding C4 (VP Engineering R-ARCH1, AI-Security
+implicit): every hook currently depends on Claude Code's specific JSON
+payload shape (`_lib.payload.parse_stdin` returns a `HookPayload` that
+maps to Claude's fields). If the only adopter's IDE changes its contract
+or a second IDE (Gemini CLI, Codex CLI) must be supported, every hook
+needs a rewrite.
+
+VP Engineering P1 warned against premature abstraction: "Building an
+adapter for a hypothetical Gemini user spends complexity budget now."
+Consensus C4 reclassified Phase 4 as **refactor-only**: ship the
+contract + Claude adapter, behavior-identical; defer Gemini/Codex.
+
+## Decision Drivers
+
+- **Portability optionality.** A stable, IDE-agnostic contract lets a
+  non-Claude adapter plug in later without forking hooks.
+- **Zero behavioral regression.** 168 existing hook tests MUST continue
+  to pass without modification. The Claude adapter is a near-identity
+  map over the existing `_lib.payload` + stdout format.
+- **Incremental migration.** Hooks do NOT have to adopt the adapter
+  immediately. The contract is available; each hook migrates on its
+  own schedule.
+- **Stdlib-only.** No new deps. Dataclasses + json only.
+
+## Options Considered
+
+### Option A: Ship contract + Claude adapter, don't rewire hooks yet (chosen)
+
+- **Pros:** zero regression risk; adapter is purely additive; existing
+  hooks untouched; future hooks can adopt natively; Gemini/Codex can
+  plug in by adding one module.
+- **Cons:** `_lib.payload` + adapter coexist temporarily — some hooks
+  use old path, future hooks use new path. Sprint 5 can migrate each
+  hook behind its own PR.
+
+### Option B: Ship contract + rewire all 4 hooks in one commit
+
+- **Pros:** single-SoT sooner; no dual path.
+- **Cons:** ~400 LOC across 4 hooks; high regression risk; 168 tests
+  must all verify behavior preserved under a refactor that's hidden
+  inside decide() rewrites. Consensus C4 explicitly rejected this
+  scope for Sprint 4.
+
+### Option C: Defer HAL entirely to Sprint 5
+
+- **Pros:** zero cost now.
+- **Cons:** no contract forces itself on the ecosystem; future
+  adapters have nothing to align against; the neutral-event debate
+  happens in Sprint 5 instead of being settled.
+
+## Decision
+
+**Option A.**
+
+### The contract: `_lib/contract.py`
+
+- `NormalizedEvent` dataclass — neutral payload representation with
+  field names that already match Claude Code exactly (session_id,
+  tool_name, tool_input, tool_response, description, prompt,
+  subagent_type, file_path, old_string, new_string, replace_all,
+  command). Optional `parse_error` for fail-open propagation.
+- `Decision` dataclass — allow/block + reason + optional system_message
+  / message. Builder helpers: `allow()`, `block(reason)`,
+  `.with_reason()`, `.as_allow()`.
+- `KNOWN_ADAPTERS = ["claude"]`, `DEFAULT_ADAPTER = "claude"`.
+
+### The Claude adapter: `_lib/adapters/claude.py`
+
+- `read_event(stream=sys.stdin) -> NormalizedEvent` — wraps existing
+  `_lib.payload.parse_stdin`; preserves fail-open semantics.
+- `write_decision(decision: Decision) -> str` — serializes to Claude
+  Code's expected one-line JSON (decision + reason + optional
+  systemMessage + message), ensure_ascii=False.
+- `emit_decision(decision, stream=sys.stdout)` — convenience +\n.
+
+### What the contract does NOT ship (per C4)
+
+- Gemini CLI adapter (deferred to Sprint 5 — pending real user)
+- Codex CLI adapter (deferred indefinitely)
+- Hook rewiring (deferred to Sprint 5; each hook migrates independently)
+- `CEO_HOOK_ADAPTER` env-var selection (implemented as constant today;
+  env-var wiring lands when the second adapter does)
+
+> **Sprint 6 update (2026-04-13):** PLAN-006 reverses the "each hook
+> migrates independently" deferral and ships all 6 hook migrations in
+> Sprint 6 Phase 1. See **ADR-014 — Hook Adapter Migration Batch
+> Policy** for the batch-policy decision (1-per-commit, mixed-mode
+> support, byte-identity fixture gating). Gemini adapter ships as
+> **stub + fixture capture** in Sprint 6 Phase 2a; real parity
+> remains deferred to Sprint 7.
+
+### Future migration path (documented but not executed)
+
+When Sprint 5 migrates hook X to the adapter:
+
+```python
+# before
+from _lib import payload as _payload
+def main():
+    p = _payload.parse_stdin()
+    decision = decide(description=p.description, prompt=p.prompt, ...)
+    print(decision.to_json())
+
+# after
+from _lib.adapters import claude as claude_adapter
+from _lib import contract
+def main():
+    event = claude_adapter.read_event()
+    decision = decide_normalized(event)   # takes NormalizedEvent
+    claude_adapter.emit_decision(decision)
+```
+
+Observable output MUST remain byte-identical (verified against the
+hook's existing fixture suite).
+
+## Consequences
+
+### Positive
+
+- A second IDE can plug in by adding `_lib/adapters/<name>.py` with
+  `read_event` + `write_decision`. No hook changes required to gain
+  multi-IDE support (once hooks migrate).
+- The neutral contract is locked before a second consumer forces a
+  compromise. Dataclass field names mirror Claude Code so the adapter
+  is boring today; future adapters carry the translation burden.
+- 168 existing hook tests untouched. 21 new tests lock the contract.
+
+### Negative
+
+- Temporary duality: some hooks continue to import `_lib.payload`
+  directly (v1 path), while `contract.py` is available but unused.
+  Acceptable for one sprint; fully migrated in Sprint 5.
+- `HookPayload` and `NormalizedEvent` overlap in fields. Until
+  migration, there is duplication. `NormalizedEvent` is the canonical
+  forward path; `HookPayload` is internal to `_lib.payload`.
+
+### Neutral
+
+- Adapter package layout (`_lib/adapters/`) is new but lightweight
+  (2 files today, stdlib-only).
+
+## Blast Radius
+
+- `.claude/hooks/_lib/contract.py` (NEW, ~110 LOC)
+- `.claude/hooks/_lib/adapters/__init__.py` (NEW, package marker)
+- `.claude/hooks/_lib/adapters/claude.py` (NEW, ~90 LOC)
+- `.claude/hooks/tests/test_contract.py` (NEW, 21 tests)
+- Existing hooks (`check_agent_spawn.py`, `check_plan_edit.py`,
+  `check_bash_safety.py`, `audit_log.py`) — **UNCHANGED**
+
+**Reversibility:** HIGH — additive files only. Rollback = delete
+`contract.py`, `adapters/`, `test_contract.py`.
+
+## References
+
+- PLAN-004 §3 Phase 4
+- PLAN-004/debate/round-1/vp-engineering.md §R-ARCH1
+- PLAN-004/debate/round-1/consensus.md §C4
+- ADR-002 (hooks package layout — `_lib/` placement rule)
+
+## Enforcement commit
+
+`e83570766079` (retrofit — PLAN-050 Phase 2 / PLAN-045 F-06-03; this anchors the file's introduction commit, not a runtime-behavior commit. For ADRs whose decision was wired into hooks/scripts in a later commit, amend this line manually.)

package/.claude/adr/ADR-009-squad-contract.md

@@ -0,0 +1,167 @@
+# ADR-009: Squad bundle contract
+
+## Status: ACCEPTED (2026-04-12)
+
+## Context
+
+PLAN-004 Phase 8 consensus finding C3 + Growth P3: the framework ships
+one domain (fintech) today. Adding a second (lgpd-heavy-saas) requires
+a repeatable contract so future squads compose cleanly with the
+Compliance SPEC v1 and the manifest registry.
+
+Growth specialist argued for 2-3 more squads in 12 weeks (lgpd,
+trading-hft, payment-platforms). VP Engineering argued for an explicit
+squad.yaml manifest (P4). The squads need to be installable/removable
+atomically and must not leak across tier boundaries.
+
+## Decision Drivers
+
+- **Repeatable contract.** Every squad has the same 5-artifact shape so
+  adopters know what to expect and validators know what to check.
+- **Tier isolation.** Squads live under `.claude/skills/domains/<name>/`
+  and MUST NOT reference core/frontend skills as dependencies (only
+  core/frontend may be listed as foundational prerequisites in prose).
+- **Registry-friendly.** Squad skills are discoverable via
+  `registry.py` (Phase 2) like any other skill.
+- **Install-CLI stability.** `install.sh --profile core,<squad>`
+  continues to work as the single integration point.
+
+## Options Considered
+
+### Option A: 5-artifact minimum + free-form extras (chosen)
+
+Every squad ships exactly:
+
+1. `team-personas.md` — ≥ 5 personas (fictional composites per ADR-007 RC policy + Growth §personas red line)
+2. `skills/<skill-id>/SKILL.md` — ≥ 3 domain-specific skills with proper frontmatter (per skill-frontmatter.schema)
+3. `pitfalls.yaml` — ≥ 10 pitfalls in the catalog format
+4. `task-chains.yaml` — ≥ 2 domain workflows
+5. `examples/PLAN-EXAMPLE.md` — one complete example plan showing the squad in use
+
+Optional: `commands/`, `scripts/`, `frontend-team-personas.md`.
+
+- **Pros:** minimal, discoverable, matches existing fintech shape,
+  validates cleanly against `check-tier-boundaries.py` and
+  `registry.py`.
+- **Cons:** 5 artifacts is arbitrary minimum; a lighter squad with
+  2 skills would be rejected.
+
+### Option B: squad.yaml manifest (VP Eng P4 original)
+
+A single declarative manifest per squad listing all artifacts.
+
+- **Pros:** machine-readable composition, future-proof.
+- **Cons:** redundant with the filesystem layout + registry. The
+  manifest would just enumerate what registry.py already discovers.
+  Adds a second source of truth → drift risk.
+
+### Option C: No formal contract; each squad ships what it wants
+
+- **Pros:** zero friction to contribute.
+- **Cons:** adopters can't predict what a squad provides. Validation
+  impossible. Growth red line #9 (no skill bloat) becomes unenforceable.
+
+## Decision
+
+**Option A.**
+
+### Formal contract
+
+```
+.claude/skills/domains/<squad-id>/
+├── team-personas.md          (≥ 5 personas, fictional composites)
+├── skills/
+│   ├── <skill-1>/SKILL.md    (≥ 3 skills total)
+│   ├── <skill-2>/SKILL.md
+│   └── <skill-3>/SKILL.md
+├── pitfalls.yaml             (≥ 10 pitfalls)
+├── task-chains.yaml          (≥ 2 workflows)
+├── examples/
+│   └── PLAN-EXAMPLE.md       (one complete example plan)
+└── (optional)
+    ├── commands/
+    ├── scripts/
+    ├── frontend-team-personas.md
+    └── ORG_CHART.md
+```
+
+### Validation rules (enforced by CI)
+
+1. `check-tier-boundaries.py` MUST pass — domain does not leak into core/frontend (already enforced).
+2. `registry.py --validate` MUST pass — every archetype in
+   team-personas.md with a primary skill references an existing skill.
+3. **Minimum counts:**
+   - team-personas.md: ≥ 5 `### NN.` or `### <Name>` sections
+   - skills/: ≥ 3 subdirectories with SKILL.md
+   - pitfalls.yaml: ≥ 10 entries in `pitfalls:`
+   - task-chains.yaml: ≥ 2 entries in `task_chains:`
+   - examples/: ≥ 1 `.md` file
+
+Minimum-count checks are added to `validate-governance.sh` in Sprint 5
+(not blocking today — the lgpd-heavy-saas squad self-validates for now).
+
+### Installation
+
+```
+bash scripts/install.sh <target> --profile core,lgpd-heavy-saas
+```
+
+Copies only:
+- `.claude/skills/domains/lgpd-heavy-saas/` (entire subtree)
+- (does NOT add to pitfalls-catalog.yaml — the domain catalog is
+  loaded alongside, not merged)
+
+### Positioning invariants (per Growth red lines)
+
+- Squads MUST use fictional composite personas, never real-person names.
+- Squads MUST NOT advertise paid tiers.
+- Squads SHIP with at least one VETO holder (persona + scope stated in
+  team-personas.md header).
+
+### What a squad is NOT
+
+- A general-purpose skill bundle (core tier handles that)
+- A marketing label ("enterprise-ready squad" — avoid)
+- A wrapper for third-party tools (squads are skill sets, not SDKs)
+
+## Consequences
+
+### Positive
+
+- Every squad is predictable. Adopters know what they get.
+- `install.sh --profile core,<squad>` works uniformly.
+- Tier-boundary check remains meaningful.
+- Registry auto-discovers squad skills like core/frontend ones.
+- Growth red lines enforce positioning consistency.
+
+### Negative
+
+- Small squads (2-skill or 1-workflow) don't fit. Accepted: we want
+  rigor-heavy squads, not drive-by micro-bundles.
+- "≥ 5 personas" excludes minimal roster squads. Accepted: VETO
+  coverage (at least Compliance + Security + Domain expert + Eng +
+  QA) sets a floor for what a squad should provide.
+
+### Neutral
+
+- Squad installation remains a flag on install.sh; no new CLI.
+
+## Blast Radius
+
+- `.claude/skills/domains/lgpd-heavy-saas/` (NEW, 3 skills + personas + pitfalls + task-chains + example)
+- `scripts/install.sh` — **UNCHANGED** (already accepts arbitrary profile names; lgpd-heavy-saas installs by name with no code change)
+
+**Reversibility:** HIGH — delete the squad directory; no other file
+references it by hard-coded path.
+
+## References
+
+- PLAN-004 §3 Phase 8
+- PLAN-004/debate/round-1/vp-engineering.md §P4
+- PLAN-004/debate/round-1/growth-engineer.md §P3
+- PLAN-004/debate/round-1/consensus.md §C3
+- ADR-006 (registry — validates squad skills against archetypes)
+
+## Enforcement commit
+
+`c958c18c6a62` (retrofit — PLAN-050 Phase 2 / PLAN-045 F-06-03; this anchors the file's introduction commit, not a runtime-behavior commit. For ADRs whose decision was wired into hooks/scripts in a later commit, amend this line manually.)

package/.claude/adr/ADR-010-canonical-edit-sentinel.md

@@ -0,0 +1,181 @@
+# ADR-010: Canonical-edit sentinel for meta-agent drafts
+
+**Status:** ACCEPTED
+**Date:** 2026-04-13
+**Sprint:** 5 Phase 7
+**Related:** ADR-005 (event stream), ADR-009 (squad contract)
+
+## Context
+
+PLAN-005 Phase 7 (B.3) introduces the **Agent Architect** meta-agent —
+a slash command (`/architect <domain-brief>`) that drafts the 5-artifact
+bundle (team-personas, pitfalls, skill-selection, personas roster,
+rationale) for a candidate new squad based on a brief from the Owner.
+
+The meta-agent's drafts must NOT directly mutate canonical paths
+(`team.md`, `frontend-team.md`, `pitfalls-catalog.yaml`, `skills/**/SKILL.md`).
+Without a guardrail, a misaligned brief could rewrite the framework's
+governance contracts in a single session.
+
+## Decision drivers
+
+- **Drafts vs canonical.** The Architect emits files into a sandboxed
+  plan subdir (`.claude/plans/PLAN-NNN/architect/round-1/`). Adopters
+  review the drafts; only after Owner sign-off do contents migrate
+  to canonical paths.
+- **Sentinel signature.** Adopting a draft into canonical paths
+  requires an Owner-signed sentinel file
+  (`approved.md`) co-located in the bundle dir. The sentinel carries
+  a literal `Approved-By: @<owner> <commit-sha>` line.
+- **Mechanical enforcement.** A new PreToolUse hook
+  (`check_canonical_edit.py`) inspects Edit/Write/MultiEdit calls
+  against canonical paths; it BLOCKS unless the matching sentinel
+  exists with a valid signature.
+- **Recursion prevention.** The Architect MUST NOT spawn another
+  Architect within the same session; `check_agent_spawn.py` detects
+  the recursion via env var `CEO_ARCHITECT_ACTIVE`.
+
+## Decision
+
+Ship four pieces in Sprint 5 Phase 7:
+
+1. `/architect <domain-brief>` slash command + Agent-Architect SKILL.md
+2. `architect-bundle-validate.py` — validates draft bundle shape
+3. `check_canonical_edit.py` PreToolUse hook — sentinel enforcement
+4. `check_agent_spawn.py` extension — recursion guard
+
+### Sentinel format
+
+```markdown
+---
+plan: PLAN-NNN
+round: 1
+type: architect-sentinel
+---
+
+Approved-By: @<owner-handle> <commit-sha-of-bundle-PR>
+Approved-At: 2026-04-13T15:30:00Z
+Scope:
+  - .claude/skills/domains/<squad>/team-personas.md
+  - .claude/skills/domains/<squad>/pitfalls.yaml
+  - ...
+```
+
+The hook reads the sentinel, parses the `Scope:` block, and allows
+edits to those exact paths. Edits outside the declared scope are
+blocked even with a valid sentinel.
+
+### Canonical paths guarded (locked in v1)
+
+- `.claude/team.md`
+- `.claude/frontend-team.md`
+- `.claude/pitfalls-catalog.yaml`
+- `.claude/skills/**/SKILL.md`
+- `.claude/skills/domains/**/team-personas.md`
+- `.claude/skills/domains/**/pitfalls.yaml`
+- `.claude/skills/domains/**/skills/**/SKILL.md`
+
+`PROTOCOL.md`, `CLAUDE.md`, and `ADR-*.md` are NOT guarded. They are
+Owner-authored governance docs; bringing them under the sentinel adds
+blast radius without addressing a meta-agent attack vector (per Owner
+decision logged in PLAN-005 §9 Q3 default).
+
+### Amendment 2026-04-14 — Sprint 9 additions (PLAN-009 C1.0 / C1.1)
+
+Per PLAN-009 A22 and A14:
+
+- `.claude/**/conftest.py` added to the sentinel list. Rationale: the
+  Sprint 9 confidence-gate hook invokes `pytest --collect-only` during
+  claim verification, which imports `conftest.py`. An agent-tampered
+  conftest would execute under the gate's privileges before verification
+  completes. Blocking conftest edits behind the sentinel closes that
+  escalation path (defense-in-depth for A3 pytest-argv hardening).
+- `.claude/hooks/check_confidence_gate.py` added to the sentinel list
+  (the new Sprint 9 hook itself).
+- The existing `.claude/scripts/lessons.py`,
+  `.claude/scripts/prune-lessons.py`, `.claude/scripts/lesson-restore.py`,
+  and (Sprint 9 Phase 5) `.claude/scripts/lesson_ranker.py` are ALSO
+  explicitly covered here — edits to any of them must come through a
+  sentinel-approved Architect bundle.
+
+Full amended list (v1.1):
+
+- `.claude/team.md`
+- `.claude/frontend-team.md`
+- `.claude/pitfalls-catalog.yaml`
+- `.claude/skills/**/SKILL.md`
+- `.claude/skills/domains/**/team-personas.md`
+- `.claude/skills/domains/**/pitfalls.yaml`
+- `.claude/skills/domains/**/skills/**/SKILL.md`
+- `.claude/**/conftest.py` *(added Sprint 9)*
+- `.claude/hooks/check_confidence_gate.py` *(added Sprint 9)*
+- `.claude/scripts/lessons.py` *(explicit Sprint 9)*
+- `.claude/scripts/prune-lessons.py` *(explicit Sprint 9)*
+- `.claude/scripts/lesson-restore.py` *(explicit Sprint 9)*
+- `.claude/scripts/lesson_ranker.py` *(added Sprint 9 Phase 5)*
+
+### Recursion guard
+
+`check_agent_spawn.py` checks the env var `CEO_ARCHITECT_ACTIVE`:
+
+- The `/architect` command sets `CEO_ARCHITECT_ACTIVE=1` before
+  spawning the Architect.
+- If `check_agent_spawn.py` sees a spawn whose persona matches
+  `Agent Architect` AND `CEO_ARCHITECT_ACTIVE=1` is in the
+  environment, the spawn is BLOCKED with reason code
+  `architect_recursion`.
+
+### Sentinel-enforcement hook deferral path
+
+Per PLAN-005 §3 Phase 7, the sentinel-enforcement hook MAY slip to
+Sprint 6 if Phases 5+6 overran. Result for this Sprint 5: shipped
+in-sprint (no slip needed).
+
+## Consequences
+
+### Positive
+
+- Meta-agent drafts are sandboxed by design.
+- Adopting a draft into canonical paths leaves an Owner-signed audit
+  trail.
+- Recursion is impossible — no Architect-spawning-Architect loops.
+- Bundle validator catches malformed drafts before review wastes time.
+
+### Negative
+
+- Adds one PreToolUse hook to the dogfood `settings.json` (slight
+  CPU cost on every Edit/Write call). Mitigated by paths-filter:
+  the hook short-circuits `decision: allow` if the touched path is
+  not in the canonical guard list.
+- Sentinel discipline relies on the Owner reviewing the bundle. The
+  hook can only verify the signature, not the wisdom of the change.
+
+### Neutral
+
+- The sentinel format is a Markdown frontmatter convention; future
+  tooling MAY parse it but isn't required to.
+
+## Blast radius
+
+L2:
+- New `.claude/hooks/check_canonical_edit.py` (PreToolUse Edit/Write/MultiEdit)
+- New `.claude/hooks/tests/test_check_canonical_edit.py`
+- Extension to `check_agent_spawn.py` for recursion guard
+- New `.claude/scripts/architect-bundle-validate.py`
+- New `.claude/skills/core/agent-architect/SKILL.md`
+- New `.claude/commands/architect.md`
+- Settings.json wire-up (Edit matcher → check_canonical_edit.py)
+
+**Reversibility:** HIGH — the hook can be removed by deleting the
+settings.json stanza; the script + skill files are inert when not
+invoked.
+
+## References
+
+- PLAN-005 §3 Phase 7 + §9 Q3
+- ADR-005 (event stream — sentinel could emit `veto_triggered` events)
+- ADR-009 (squad contract — Architect helps draft new squads)
+
+## Enforcement commit
+
+`414cf213f904` (retrofit — PLAN-050 Phase 2 / PLAN-045 F-06-03; this anchors the file's introduction commit, not a runtime-behavior commit. For ADRs whose decision was wired into hooks/scripts in a later commit, amend this line manually.)

package/.claude/adr/ADR-011-event-stream-v2.1-injection-flag.md

@@ -0,0 +1,150 @@
+# ADR-011: Event stream v2.1 — `injection_flag` action
+
+**Status:** ACCEPTED
+**Date:** 2026-04-13
+**Sprint:** 5 Phase 5
+**Supersedes:** none
+**Extends:** ADR-005 (event stream v2)
+
+## Context
+
+PLAN-005 Phase 5 (B.4) introduces an advisory prompt-injection scanner
+(`scan-injection.py`) and an opt-in PreToolUse hook
+(`check_read_injection.py`) that flags files likely crafted to subvert
+an LLM's instructions when read.
+
+For the scanner to be useful operationally, its findings must be
+queryable: how often does Read content trigger the scanner, which
+families dominate, which sources, etc. ADR-005 locked the v2 audit
+event stream with 5 actions (`agent_spawn`, `debate_event`,
+`plan_transition`, `veto_triggered`, `benchmark_run`, `lesson_write`).
+We need a 7th.
+
+## Decision drivers
+
+- **Forward compat.** Adding a new `action` literal is the additive
+  evolution path explicitly preserved by ADR-005 §1.
+- **Advisory only.** This event documents observation, never
+  enforcement. The scanner cannot block; the hook cannot block.
+- **Aggregation-friendly.** Operators want family-level counts +
+  per-source breakdowns. The schema bakes both in.
+
+## Decision
+
+Introduce a **v2.1** action: `injection_flag`. The version bump is
+PATCH (consumers tolerating unknown actions are unaffected).
+
+### Schema
+
+```json
+{
+  "ts": "2026-04-13T12:34:56Z",
+  "event_schema": "v2",
+  "action": "injection_flag",
+  "source": "<file path or '<stdin>'>",
+  "family_counts": {
+    "direct_override": 2,
+    "role_injection": 1
+  },
+  "match_count": 3,
+  "bytes_scanned": 4096,
+  "truncated": false,
+  "triggered_by_tool": "Read",
+  "snippet_preview": "<redacted, ≤200 chars>",
+  "session_id": "<optional>",
+  "project": "<CLAUDE_PROJECT_DIR>",
+  "tokens_in": null,
+  "tokens_out": null,
+  "tokens_total": null
+}
+```
+
+### Field semantics
+
+| Field | Type | Notes |
+|---|---|---|
+| `source` | string | File path scanned, or sentinel `<stdin>` for CLI use |
+| `family_counts` | object | Map of pattern family → hit count |
+| `match_count` | integer | Total matches across all families |
+| `bytes_scanned` | integer | Bounded at 1 MiB by the scanner |
+| `truncated` | boolean | True if input exceeded the scan cap |
+| `triggered_by_tool` | string | Originating tool (`Read`, `Bash`, future) |
+| `snippet_preview` | string | Redacted snippet of the highest-confidence hit |
+
+### Pattern families (locked in v2.1)
+
+The scanner ships with 6 families. New families MAY be added in future
+PATCH versions; removals require a MINOR bump per SemVer policy
+(ADR-007).
+
+| Family | Examples |
+|---|---|
+| `direct_override` | "ignore previous instructions", "new system prompt:" |
+| `role_injection` | "I am the CEO", "<system>", "from now on you are" |
+| `instruction_disclosure` | "show your prompt", "what are your rules" |
+| `action_override` | "execute the following", "curl ... \| bash" |
+| `tool_smuggling` | `<tool_use>`, `"function_call":` |
+| `encoded_payload` | base64-ish blob ≥120 chars, hex blob ≥120 chars |
+
+### Producers
+
+| Producer | When |
+|---|---|
+| `check_read_injection.py` (PreToolUse Read hook) | On every Read of a non-skipped file with at least one match |
+| Future hooks may emit similarly | (e.g. WebFetch result scanning) |
+
+### Consumers
+
+`audit-query.py` `vetoes` and `metrics` sub-commands surface
+`injection_flag` aggregate counts. A future `injections` sub-command
+MAY ship in Sprint 6 if usage warrants per-source / per-family drill-down.
+
+## Consequences
+
+### Positive
+
+- Operators have a single audit channel for both real vetoes
+  (`veto_triggered`) and advisory observations (`injection_flag`),
+  queried via the same tooling.
+- Pattern family additions are PATCH-version events.
+- The advisory contract is enforced at the schema: there is no
+  `decision: block` field — the event records observation only.
+
+### Negative
+
+- `family_counts` is a free-form map, not enumerated. Consumers must
+  tolerate new families gracefully (the v2 forward-compat clause
+  already covers this).
+- The hook + audit emission means a noisy file produces an audit row
+  on every Read. Aggregation-friendly tooling absorbs this; raw-tail
+  monitors must filter.
+
+### Neutral
+
+- The hook is opt-in. The default `settings.json` does NOT wire it.
+  Adopters who care about prompt safety enable it explicitly.
+
+## Blast radius
+
+L1:
+- `_lib/audit_emit.py` — adds `emit_injection_flag()` + `injection_flag`
+  to `_KNOWN_ACTIONS`
+- `.claude/hooks/check_read_injection.py` (NEW)
+- `.claude/scripts/scan-injection.py` (NEW)
+- `AUDIT-LOG-SCHEMA.md` + `SPEC/v1/audit-log.schema.md` — append the row
+- Tests + fixtures (NEW)
+
+**Reversibility:** HIGH — the action literal can be removed in a future
+MAJOR; the hook is opt-in (deletion is invisible to non-adopters).
+
+## References
+
+- ADR-005 (event stream v2 contract)
+- ADR-007 (SemVer + RC policy — drives the v2.1 PATCH bump)
+- PLAN-005 §3 Phase 5
+- `scan-injection.py` for the scanner contract
+- `check_read_injection.py` for the hook wire-up instructions
+
+## Enforcement commit
+
+`d24cc8181058` (retrofit — PLAN-050 Phase 2 / PLAN-045 F-06-03; this anchors the file's introduction commit, not a runtime-behavior commit. For ADRs whose decision was wired into hooks/scripts in a later commit, amend this line manually.)