Document Guard Fail-Mode Matrix (Fail-Open vs Fail-Closed)#2180
Merged
Trecek merged 2 commits intoMay 7, 2026
Merged
Conversation
github-merge-queue
Bot
removed this pull request from the merge queue due to a conflict with the base branch
Add Fail-Mode Contract section to guards/CLAUDE.md with a matrix table documenting the three fail-closed guards (skill_command_guard, open_kitchen_guard, skill_orchestration_guard) and their conditions. Mirror the same section into docs/safety/hooks.md between SessionStart and Drift detection sections. Add tests/docs/test_guard_fail_mode_docs.py verifying both doc files contain the fail-mode matrix and the old single-sentence description is removed from guards/CLAUDE.md. No guard code changes — docstrings already correctly document fail modes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…ard and design-principle assertions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Trecek
force-pushed
the
document-guard-fail-mode-matrix-fail-open-vs-fail-closed/2045
branch
from
599e22c to
a5d6d84
Compare
Trecek
deleted the
document-guard-fail-mode-matrix-fail-open-vs-fail-closed/2045
branch
Trecek
added a commit
that referenced
this pull request
May 8, 2026
## Summary Surface the actual fail-mode behavior of all guards into two documentation files (`hooks/guards/CLAUDE.md` and `docs/safety/hooks.md`) so agents can correctly predict whether an unrecognized session type or runtime error will be approved or denied — without reading guard source code. This is a documentation-only change: no guard code is modified. ## Requirements ### Required Changes #### 1. `src/autoskillit/hooks/guards/CLAUDE.md` Replace the single-sentence fail-mode description with the expanded fail-mode contract block (matrix table + design principle). #### 2. `docs/safety/hooks.md` Add a "Fail Modes" subsection after the hook descriptions section, with the same matrix and explanation. #### 3. Guard file docstrings (verification only) Verify each guard's module docstring already documents its own fail mode: - `skill_orchestration_guard.py:31` — "fail-closed to skill session" - `open_kitchen_guard.py:118` — "skill session, unset, or invalid — deny (fail-closed)" - `skill_command_guard.py:4` — "Unexpected errors: fail-closed (deny)" No changes needed to guard code — this is purely documentation. ## Acceptance Criteria - `guards/CLAUDE.md` contains the fail-mode matrix table - `docs/safety/hooks.md` contains a "Fail Modes" section - An agent reading ONLY `guards/CLAUDE.md` can correctly predict whether an unrecognized session type will be approved or denied by each guard - No code changes — this is purely documentation Closes #2045 ## Implementation Plan Plan file: `/home/talon/projects/autoskillit-runs/impl-20260507-111320-037598/.autoskillit/temp/make-plan/document_guard_fail_mode_matrix_plan_2026-05-07_111320.md` 🤖 Generated with [Claude Code](https://claude.com/claude-code) via AutoSkillit <!-- autoskillit:pipeline-signature steps=prepare_pr,run_arch_lenses,compose_pr,annotate_pr_diff,review_pr --> ## Token Usage Summary | Step | Model | count | uncached | output | cache_read | peak_ctx | turns | cache_write | time | |------|-------|-------|----------|--------|------------|----------|-------|-------------|------| | plan | claude-opus-4-6 | 1 | 77 | 7.6k | 947.9k | 56.8k | 56 | 47.0k | 7m 17s | | verify | claude-opus-4-6 | 1 | 31 | 4.8k | 451.4k | 44.1k | 48 | 34.7k | 3m 21s | | implement* | MiniMax-M2.7-highspeed | 1 | 391.7k | 5.4k | 789.7k | 48.4k | 60 | 34.7k | 2m 45s | | prepare_pr* | MiniMax-M2.7-highspeed | 1 | 66.5k | 4.2k | 205.4k | 29.8k | 22 | 15.2k | 1m 22s | | compose_pr* | MiniMax-M2.7-highspeed | 1 | 57.6k | 1.6k | 235.2k | 29.8k | 16 | 15.0k | 42s | | **Total** | | | 515.9k | 23.6k | 2.6M | 56.8k | | 146.6k | 15m 28s | \* *Step used a non-Anthropic provider; caching behavior may differ.* ## Token Efficiency | Step | LoC Changed | cache_read/LoC | cache_write/LoC | output/LoC | |------|-------------|----------------|-----------------|------------| | plan | 0 | — | — | — | | verify | 0 | — | — | — | | implement | 753 | 1048.8 | 46.1 | 7.2 | | prepare_pr | 0 | — | — | — | | compose_pr | 0 | — | — | — | | **Total** | **753** | 3492.1 | 194.7 | 31.4 | ## Model Usage Breakdown | Model | steps | uncached | output | cache_read | cache_write | time | |-------|-------|----------|--------|------------|-------------|------| | claude-opus-4-6 | 2 | 108 | 12.3k | 1.4M | 81.6k | 10m 38s | | MiniMax-M2.7-highspeed | 3 | 515.8k | 11.3k | 1.2M | 65.0k | 4m 49s | --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Surface the actual fail-mode behavior of all guards into two documentation files (
hooks/guards/CLAUDE.mdanddocs/safety/hooks.md) so agents can correctly predict whether an unrecognized session type or runtime error will be approved or denied — without reading guard source code. This is a documentation-only change: no guard code is modified.Requirements
Required Changes
1.
src/autoskillit/hooks/guards/CLAUDE.mdReplace the single-sentence fail-mode description with the expanded fail-mode contract block (matrix table + design principle).
2.
docs/safety/hooks.mdAdd a "Fail Modes" subsection after the hook descriptions section, with the same matrix and explanation.
3. Guard file docstrings (verification only)
Verify each guard's module docstring already documents its own fail mode:
skill_orchestration_guard.py:31— "fail-closed to skill session"open_kitchen_guard.py:118— "skill session, unset, or invalid — deny (fail-closed)"skill_command_guard.py:4— "Unexpected errors: fail-closed (deny)"No changes needed to guard code — this is purely documentation.
Acceptance Criteria
guards/CLAUDE.mdcontains the fail-mode matrix tabledocs/safety/hooks.mdcontains a "Fail Modes" sectionguards/CLAUDE.mdcan correctly predict whether an unrecognized session type will be approved or denied by each guardCloses #2045
Implementation Plan
Plan file:
/home/talon/projects/autoskillit-runs/impl-20260507-111320-037598/.autoskillit/temp/make-plan/document_guard_fail_mode_matrix_plan_2026-05-07_111320.md🤖 Generated with Claude Code via AutoSkillit
Token Usage Summary
* Step used a non-Anthropic provider; caching behavior may differ.
Token Efficiency
Model Usage Breakdown