docs: document .claude-no-enforce escape hatch #198

Merged

forgejo_admin merged 1 commit from 156-document-claude-no-enforce into main

2026-03-28 05:28:35 +00:00

forgejo_admin commented

2026-03-28 04:58:10 +00:00

Contributor

Summary

Documents the existing .claude-no-enforce repo-level opt-out from issue-driven development enforcement. This dotfile exists in check-issue.sh (line 74) but was undocumented in agent profiles. Adds a dedicated section to the Betty Sue agent profile covering mechanics, usage guidance, and lifecycle.

Changes

agents/betty-sue.md — Added .claude-no-enforce section between Code Tools and Constraints, documenting:
- How the hook detects the file (three locations: cwd, git_dir, repo_root)
- When to use it (frontend iteration, playground repos, supervised main-session work)
- When NOT to use it (production repos, agent work, tracked board items)
- Lifecycle guidance (gitignore it, session-scoped, not permanent)

Test Plan

Verified .claude-no-enforce works end-to-end:
- On a branch with no issue number, hook blocks with exit 2 (confirmed)
- After touch .claude-no-enforce, same invocation passes with exit 0 (confirmed)
No hook behavior changed — documentation only
No regressions in hook enforcement logic

Review Checklist

Passed automated review-fix loop
No secrets committed
No unnecessary file changes
Commit messages are descriptive

Closes #156
pal-e-agency — parent project
hooks/check-issue.sh line 74 — the implementation being documented
feedback_frontend_iteration — the principle behind this escape hatch

## Summary Documents the existing `.claude-no-enforce` repo-level opt-out from issue-driven development enforcement. This dotfile exists in `check-issue.sh` (line 74) but was undocumented in agent profiles. Adds a dedicated section to the Betty Sue agent profile covering mechanics, usage guidance, and lifecycle. ## Changes - `agents/betty-sue.md` — Added `.claude-no-enforce` section between Code Tools and Constraints, documenting: - How the hook detects the file (three locations: cwd, git_dir, repo_root) - When to use it (frontend iteration, playground repos, supervised main-session work) - When NOT to use it (production repos, agent work, tracked board items) - Lifecycle guidance (gitignore it, session-scoped, not permanent) ## Test Plan - [x] Verified `.claude-no-enforce` works end-to-end: - On a branch with no issue number, hook blocks with exit 2 (confirmed) - After `touch .claude-no-enforce`, same invocation passes with exit 0 (confirmed) - [x] No hook behavior changed — documentation only - [x] No regressions in hook enforcement logic ## Review Checklist - [x] Passed automated review-fix loop - [x] No secrets committed - [x] No unnecessary file changes - [x] Commit messages are descriptive ## Related Notes - Closes #156 - `pal-e-agency` — parent project - `hooks/check-issue.sh` line 74 — the implementation being documented - `feedback_frontend_iteration` — the principle behind this escape hatch

forgejo_admin added 1 commit

2026-03-28 04:58:10 +00:00

docs: document .claude-no-enforce escape hatch in betty-sue agent profile 5a9ec1226e

The check-issue.sh hook has a repo-level opt-out via .claude-no-enforce
that was undocumented. Add a dedicated section to agents/betty-sue.md
covering how it works, when to use it (frontend iteration), when not to
(production repos, agent work), and lifecycle guidance.

Closes #156

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

forgejo_admin commented

2026-03-28 04:59:04 +00:00

Author

Contributor

QA Review — PR #198

Diff Analysis

Single file changed: agents/betty-sue.md (+20 lines, 0 deletions). Documentation only — no hook behavior modified.

Accuracy Check

Hook mechanics: Correctly describes the three-location check ($cwd, $git_dir, $repo_root) matching check-issue.sh line 74.
Usage guidance: "When to use" and "When NOT to use" sections align with feedback_frontend_iteration memory and the issue's stated rationale.
Lifecycle advice: Gitignore + session-scoped guidance is sound — prevents accidental commits of the opt-out file.

Nits

Line 69 references convention-claude-no-enforce in pal-e-docs, which does not yet exist. Acceptable — the parent issue lists this as a separate deliverable ("Files to potentially create"), and pal-e-docs updates are outside this agent's boundary.

Scope Check

The issue has 4 acceptance criteria. This PR covers criterion 3 (agents/betty-sue.md in claude-custom updated). Criteria 1, 2, and 4 target pal-e-docs notes, which are outside the Dev agent's boundary. Betty Sue will need to handle those separately.

VERDICT: APPROVE

Clean documentation-only change. Accurately reflects existing hook behavior. No code changes, no risk. Forward reference to pal-e-docs convention note is the only loose end, correctly deferred.

## QA Review — PR #198 ### Diff Analysis Single file changed: `agents/betty-sue.md` (+20 lines, 0 deletions). Documentation only — no hook behavior modified. ### Accuracy Check - **Hook mechanics**: Correctly describes the three-location check (`$cwd`, `$git_dir`, `$repo_root`) matching `check-issue.sh` line 74. - **Usage guidance**: "When to use" and "When NOT to use" sections align with `feedback_frontend_iteration` memory and the issue's stated rationale. - **Lifecycle advice**: Gitignore + session-scoped guidance is sound — prevents accidental commits of the opt-out file. ### Nits - Line 69 references `convention-claude-no-enforce` in pal-e-docs, which does not yet exist. Acceptable — the parent issue lists this as a separate deliverable ("Files to potentially create"), and pal-e-docs updates are outside this agent's boundary. ### Scope Check The issue has 4 acceptance criteria. This PR covers criterion 3 (`agents/betty-sue.md` in claude-custom updated). Criteria 1, 2, and 4 target pal-e-docs notes, which are outside the Dev agent's boundary. Betty Sue will need to handle those separately. ### VERDICT: APPROVE Clean documentation-only change. Accurately reflects existing hook behavior. No code changes, no risk. Forward reference to pal-e-docs convention note is the only loose end, correctly deferred.

forgejo_admin commented

2026-03-28 05:00:28 +00:00

Author

Contributor

PR #198 Review

DOMAIN REVIEW

Tech stack: Markdown documentation in an agent profile (agents/betty-sue.md). Cross-referenced against a Bash hook (hooks/check-issue.sh).

Accuracy verification:

The documentation accurately reflects the implementation:

Three check locations ($cwd, $git_dir, $repo_root) -- confirmed at hooks/check-issue.sh line 74:

if [[ -f "$cwd/.claude-no-enforce" ]] || [[ -f "$git_dir/.claude-no-enforce" ]] || [[ -n "$repo_root" && -f "$repo_root/.claude-no-enforce" ]]; then

Line reference ("line 74") is accurate against current main.
Exit behavior ("enforcement is skipped entirely") correctly describes the exit 0 path.
.gitignore guidance is already implemented -- .claude-no-enforce is in the repo .gitignore at line 65.

Section placement: Inserted between "Code Tools" and "Constraints" sections. Semantically reasonable -- documents a hook mechanism adjacent to tool constraints.

BLOCKERS

None. This is a documentation-only change with no code modifications.

NITS

Line reference fragility: "See: hooks/check-issue.sh line 74" -- line numbers drift as the file changes. Consider referencing the section comment instead, e.g., "See: hooks/check-issue.sh (opt-out check near # Skip if repo opted-out)" or just the file without a line number. Low priority since this is an internal agent profile.
Cross-reference verifiability: "See: ... convention-claude-no-enforce in pal-e-docs" -- I cannot verify this note exists (pal-e-docs is outside my review boundary). If it does not exist yet, this is a dangling reference. The PR author should confirm it exists or note it as a planned follow-up.
Minor template variance: PR body uses "Related Notes" instead of the standard "Related" section header from the PR template. Non-blocking.

SOP COMPLIANCE

Branch named after issue (156-document-claude-no-enforce references #156)
PR body has Summary, Changes, Test Plan, Related sections
Related section references parent project (pal-e-agency)
No secrets committed
No unnecessary file changes (1 file, documentation only)
Commit message is descriptive (docs: document .claude-no-enforce escape hatch)
Closes #156 is declared

PROCESS OBSERVATIONS

Clean documentation PR. Low change-failure risk -- no behavioral changes, purely additive documentation of an existing mechanism. This is the kind of documentation debt paydown that improves operational clarity. The escape hatch was already functional but undiscoverable without reading hook source; this PR closes that gap.

VERDICT: APPROVED

## PR #198 Review ### DOMAIN REVIEW **Tech stack:** Markdown documentation in an agent profile (`agents/betty-sue.md`). Cross-referenced against a Bash hook (`hooks/check-issue.sh`). **Accuracy verification:** The documentation accurately reflects the implementation: - **Three check locations** (`$cwd`, `$git_dir`, `$repo_root`) -- confirmed at `hooks/check-issue.sh` line 74: ``` if [[ -f "$cwd/.claude-no-enforce" ]] || [[ -f "$git_dir/.claude-no-enforce" ]] || [[ -n "$repo_root" && -f "$repo_root/.claude-no-enforce" ]]; then ``` - **Line reference** ("line 74") is accurate against current `main`. - **Exit behavior** ("enforcement is skipped entirely") correctly describes the `exit 0` path. - **`.gitignore` guidance** is already implemented -- `.claude-no-enforce` is in the repo `.gitignore` at line 65. **Section placement:** Inserted between "Code Tools" and "Constraints" sections. Semantically reasonable -- documents a hook mechanism adjacent to tool constraints. ### BLOCKERS None. This is a documentation-only change with no code modifications. ### NITS 1. **Line reference fragility:** "See: `hooks/check-issue.sh` line 74" -- line numbers drift as the file changes. Consider referencing the section comment instead, e.g., "See: `hooks/check-issue.sh` (opt-out check near `# Skip if repo opted-out`)" or just the file without a line number. Low priority since this is an internal agent profile. 2. **Cross-reference verifiability:** "See: ... `convention-claude-no-enforce` in pal-e-docs" -- I cannot verify this note exists (pal-e-docs is outside my review boundary). If it does not exist yet, this is a dangling reference. The PR author should confirm it exists or note it as a planned follow-up. 3. **Minor template variance:** PR body uses "Related Notes" instead of the standard "Related" section header from the PR template. Non-blocking. ### SOP COMPLIANCE - [x] Branch named after issue (`156-document-claude-no-enforce` references #156) - [x] PR body has Summary, Changes, Test Plan, Related sections - [x] Related section references parent project (`pal-e-agency`) - [x] No secrets committed - [x] No unnecessary file changes (1 file, documentation only) - [x] Commit message is descriptive (`docs: document .claude-no-enforce escape hatch`) - [x] Closes #156 is declared ### PROCESS OBSERVATIONS Clean documentation PR. Low change-failure risk -- no behavioral changes, purely additive documentation of an existing mechanism. This is the kind of documentation debt paydown that improves operational clarity. The escape hatch was already functional but undiscoverable without reading hook source; this PR closes that gap. ### VERDICT: APPROVED