fix(guard): surface CRAFT_GUARD_ALLOW_DEV_EDIT in guard-bypass-marker confirms - #310
Merged
Merged
Conversation
… confirms (#309) The "Claude writes .claude/allow-once" one-shot flow documented in REFCARD-BRANCH-GUARD.md and branch-guard-smart-mode.md is circular for the one case where the approved action IS creating/editing that marker itself — every tool path (Write/Edit/Bash) intercepts it with its own [CONFIRM], and the one thing that actually resolves it non-interactively (issue #281's CRAFT_GUARD_ALLOW_DEV_EDIT env var) appeared in neither reference doc nor any runtime suggestion. Adds the env-var hint to the three guard-bypass-marker confirms only (edit_guard_bypass/write_guard_bypass/bash_guard_bypass) — not to write_new_code, where allow-once genuinely works as documented and the hint would be noise. Reconciles both reference docs with a caveat pointing to skills/dev/git/SKILL.md Operation 10, which already had this right.
…ounter Code review of PR #310 caught: the negative test guarding against CRAFT_GUARD_ALLOW_DEV_EDIT leaking into write_new_code's suggestions was reading stderr from a 2nd-encounter call, which renders "brief" verbosity — suggestions are omitted there regardless of content, so the assertion passed vacuously and would not have caught the very regression it was named for. Fixed to capture a single 1st-encounter ("full" verbosity, where Suggest: lines actually render) stderr and assert both the positive ("New code files" present) and negative (env var absent) conditions against it. Verified by planting the regression (temporarily adding the env-var hint to write_new_code's suggestions) and confirming the test now fails, then reverting and confirming it passes clean.
Data-Wise
added a commit
that referenced
this pull request
Jul 25, 2026
Full docs/website audit: docs-staleness-check.sh (nav/counts/coverage/ cross-doc freshness), validate-counts.sh, broken-link tests, mkdocs build --strict, and live-site version check all GREEN — no drift found there. The one real gap: both CHANGELOG.md and docs/CHANGELOG.md jumped straight from the header to [4.3.0], with no record of the two PRs merged to dev since that release (#310, #311). Added a mirrored [Unreleased] section to both files.
Data-Wise
added a commit
that referenced
this pull request
Jul 26, 2026
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
Closes #309. The
[CONFIRM]flow docs describe ("Claude writes.claude/allow-once") iscircular for the one case where the approved action is creating/editing that marker itself —
every tool path (Write/Edit/Bash) intercepts it with its own
[CONFIRM](
write_guard_bypass/edit_guard_bypass/bash_guard_bypass), and the one thing that actuallyresolves it non-interactively — issue #281's
CRAFT_GUARD_ALLOW_DEV_EDITenv var — appeared inneither reference doc (
REFCARD-BRANCH-GUARD.md,branch-guard-smart-mode.md) nor any runtime_confirm()suggestion string.to
write_new_code, whereallow-oncegenuinely resolves the block as documented and thehint would just be noise (the exact confusion branch-guard: docs prescribe allow-once but the runtime message doesn't, and every non-worktree remediation is unreachable for a non-interactive agent #309 reported, recreated in reverse).
skills/dev/git/SKILL.mdOperation10, which already had this right (added with branch-guard.sh: /craft:git:unprotect self-deadlocks in non-interactive sessions #281) — the gap was in the two reference docs
and the runtime message, not the skill.
Test plan
All tiers run in-tree (
~/.git-worktrees/craft/feature-issue-309), hook synced to~/.claude/hooks/viainstall-guards.shfirst (same as CI):tests/test_branch_guard.sh: 146/146 passed — includes 6 new tests pinning the env-var hintpresent in all 3 marker-specific confirms, absent from
write_new_code.tests/test_branch_guard_e2e.sh: 30/31 —e2e_perf_50_invocationsfails identically onunmodified
dev(wall-clock timing budget, pre-existing, reproduced to confirm baseline).tests/test_branch_guard_dogfood.py+test_integration_branch_guard.py: 28/28 passed.python3 -m pytest tests/): 2615 passed / 0 failed / 49 skipped / 1 xfailed(unrelated, tracked) / 1 xpassed (known perf microbenchmark flake, unrelated).
scripts/docs-staleness-check.sh: GREEN, 0 issues.🤖 Generated with Claude Code