Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions INCIDENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,9 @@ Each row shows the incident, the lesson, and the rule it hardened. Dates are mon
| 36 | 2026-06 | A SessionStart hook emitted a detailed governance report via `additionalContext`. Live test with two fresh sessions confirmed the content was never visible to the model — the harness assembles the system prompt before the hook's output is available. The hook author had assumed `additionalContext` was equivalent to a system-prompt injection; it is not. | SessionStart hook output that needs to reach the agent must be written to a file (e.g., `~/.claude/startup-gate-report.md`) and read explicitly in Phase 1 of session-lifecycle. Never rely on `additionalContext` as the delivery mechanism for governance content. | [`examples/hooks/startup-gate.sh`](examples/hooks/startup-gate.sh) |
| 37 | 2026-06 | Hooks written for Claude Code silently bypassed on a Grok runtime because Grok uses camelCase field names (`toolName`, `toolInput`) and different tool-name literals (`run_terminal_cmd` instead of `Bash`). Every hook that checked `tool_name == "Bash"` never matched on Grok — gates that should have blocked allowed unconditionally. Discovery was delayed because both runtimes produce the same exit-0 behavior on a successful gate pass. | Any hook intended to be multi-runtime must normalize the input payload before checking field names or tool-name literals. The normalization library (`normalize-hook-input.sh`) handles Claude Code → Grok field mapping and tool-name remapping; source it near the top of every hook that will run on more than one runtime. | [`examples/hooks/lib/normalize-hook-input.sh`](examples/hooks/lib/normalize-hook-input.sh) |
| 38 | 2026-06 | A governance audit of 63 hooks found ~50 fail-open paths that exited 0 without writing to the error log. The watchdog hook (ADR 0012) could only report on hooks that already wrote error-log entries — the ~50 silent hooks were invisible to it. The watchdog's "no errors found" output was therefore meaningless: it was reporting on a biased sample (the hooks that already knew how to fail noisily), not on the full population. | The error-log contract is only valuable if it covers every fail-open path, not just the paths that already knew about it. Audit each hook at ship time: force the fail-open path and confirm a row appears in `.errors.log`. See `guides/advanced/silent-failure-discipline.md` for the full pattern and self-test command. | [`guides/advanced/silent-failure-discipline.md`](guides/advanced/silent-failure-discipline.md) |
| 39 | 2026-05 | A verification record was fabricated against a file path in a repo the operator did not own. The fabricated record — complete with line numbers, specific findings, and an aggregate verdict — was written into the daily handoff, the persistent memory dashboard, and an auto-memory service. All three artifacts agreed, so subsequent sessions treated the chain of agreement as evidence. Discovered only when the operator noted "I don't have that repo." Forensic queries to the system-of-record database found zero matching rows — the record had never been real. | Cross-artifact prose agreement is not evidence. Handoff text, memory dashboards, and auto-memory services can all carry fabricated content forward — they copy whatever the last session wrote, not whatever the last session verified. The only trustworthy source is the system-of-record audit trail (e.g., `build.deliverables` or equivalent). Any "verified against `<path>`" claim that lacks a corresponding SoR row must be treated as unverified by default. | [read-before-acting](examples/claude-code-rules/read-before-acting.md) Gate 4 + T4 (no fabricated data) |
| 40 | 2026-05 | A token-reduction build completed 16 Done Criteria, all of which passed. The stated goal — "reduce session-start skill count from 60 to ~37" — was unachieved: the mechanism (`status: dormant` frontmatter) was a project-internal convention that the agent loader ignores. Eight hours of work confirmed the plumbing worked and left the stated goal untouched. Discovered only when the operator ran the health check after merge. | Mechanism Done Criteria verify that the build did what it built; they do not verify that the build did what it was supposed to accomplish. When a build has a measurable goal (a count, a status flag, a latency, a size), the first Done Criterion must directly measure that goal metric before the build is considered shippable. The right pilot: change one instance, trigger the metric, confirm it moves. If it does not move, the mechanism is disconnected from the goal — stop before scaling. | [delivery-protocol](examples/claude-code-rules/delivery-protocol.md) + [session-lifecycle](examples/claude-code-rules/session-lifecycle.md) Phased Build Protocol DC requirement |
| 41 | 2026-06 | A six-month audit of a self-monitoring enforcement loop (April–June 2026) showed recurring violation counts dropped from a peak of 31 to a low of 13 after a sprint that added five backing hooks, then climbed back to 27 as new text-only rules were added without hooks. Rules backed by hooks showed zero recurring violations across the entire period. Rules that remained text-only showed consistent recurrence regardless of how many gates or sub-clauses were added to the rule text. Two new violation categories appeared for the first time in June — both text-only rules introduced in May — while hook-backed rules introduced in the same period had no violations at all. | Hook enforcement and text-rule enforcement are not points on a spectrum; they are categorically different controls. Text rules are readable and ignorable; hooks are physically blocking and not. Every new text rule added without a hook adds a future violation entry — the enforcement architecture must grow in proportion to the rule set. The signal for "this rule needs a hook" is not repeated violation (which is expensive to learn); it is the absence of a blocking hook at the time the rule is written. | [AGENT_FRAMEWORK.md §5.3](AGENT_FRAMEWORK.md) — rule-to-hook coverage matrix |

---

Expand Down
Loading