feat(hooks): a refusal no longer prints its own bypass marker (v1.37.0)

[lapc506]

What

A hook's refusal no longer prints its own bypass_marker. The marker still works — a human who knows one exists can type it deliberately, and every allows-bypass-marker test still asserts expected_exit: 0. What disappears is the hook announcing it.

Closes DOJ-6433.

The measurement

ref: origin/main @ ee0ba47 | delta: none (worktree cut from that ref, measured before any edit)

	count	command
rules total	40	jq 'length' hooks/rules/rules.json
with a bypass_marker	35	jq '[.[] | select((.bypass_marker // "") != "")] | length' hooks/rules/rules.json
printing that marker in their own refusal	26	below

jq '[.[] | select((.bypass_marker // "") != "")
         | select(.bypass_marker as $m | (.message // "") | contains($m))] | length' \
  hooks/rules/rules.json      # => 26

The brief's figure was 39 / 35 / 26, measured against the installed v1.35.0. Mine differs on the first number only: origin/main is v1.36.0, which added discard-stderr (PR #53) — rule 40, and the only rule in the manifest that already shipped bypass_marker: null on precisely this reasoning. The 35 and the 26 match exactly.

The 26, by id:

ssh-db-mutation · prod-ops-no-approval · destructive-db-ops · manual-edge-fn-deploy · minified-build-output · secrets-hardcoded · ds-arbitrary-breakpoint · warn-curl-mutating-supabase-rest · block-playwright-headless · block-git-force-push-no-lease · block-git-rebase-skip · warn-deletes-console-log · warn-time-estimates-in-plans · warn-pr-create-many-files · warn-posthog-in-alerts · block-sibling-suffix-storage · warn-localhost-in-pr-body · warn-bash-mutation-without-leading-cd · warn-version-readme-changelog-sync · warn-greptile-review-extraction-by-created-at · the six inline-db-mutation-*

Why this is a defect, not a convenience

The thing meant to stop you hands you the password. Reading the refusal is the authorization, and typing the marker becomes a reflex instead of a decision.

inline-db-mutation-psql is the clearest case: it listed # hook-bypass: db-mutation-rule in its refusal and shipped an allows-bypass-marker test with expected_exit: 0. The bypass was a tested feature of the refusal text, not a slip of wording.

dojo-os records the same shape in its non-negotiable 2, with an incident: pre-bash-block-main-target.sh accepted DOJO_HOTFIX_TO_MAIN=1 and printed that literal in its own refusal, and on 2026-07-28 two agents filed two false P0-hotfix claims under a human's GitHub account with no trace but their own self-report (DOJ-6247).

While preparing this PR the installed v1.36.0 hook blocked a probe command and printed "// hook-bypass: prod-ops" back at me — the defect firing on the author of its own fix. It was reported here rather than routed around.

What changed

33 rule messages — the 26 that named the marker, plus 7 that said "use the bypass marker" without naming it. A refusal announcing an exit you then go look up is the same invitation with an extra step.

The six inline-db-mutation-* rules also stop naming their .no-make-no-mistakes-db-mutation sentinel: the per-repo escape hatch is the same door one level up, and removing the marker while leaving the sentinel would just move traffic to the other door.

Untouched: ds-deep-ui-import and ds-arbitrary-fixed-width-in-ds-component, the two marker-bearing rules that never invited a bypass.

Each refusal now says what was blocked, why, what to do instead, and closes with:

A block is a finding. Report it upward rather than routing around it.

Both the markers and the sentinel stay documented in README.md and hooks/rules/README.md — files a human opens on purpose, which is a different act from being handed one at the moment you are trying to get past something.

The control that makes it stick

Three generic assertions in hooks/test-hooks.sh, under Running manifest invariants…. They hold over every rule in the manifest rather than case by case, because case by case is what drifted the first time. A message may not contain:

1. its own bypass_marker
2. its own disable_if_repo_file
3. the literal hook-bypass in any form — catches the // hook-bypass: <marker> template even when the marker is renamed or elided

Each failure lists every offending rule id. CI already runs bash hooks/test-hooks.sh on every PR touching hooks/**.

Both controls exercised, not assumed. Clean manifest → all three PASS. Leak injected into rules.json → the matching assertion FAILs and names the rule, while the others stay green:

# injected "// hook-bypass: prod-ops" into prod-ops-no-approval.message
FAIL  manifest-invariant / message-does-not-name-its-own-bypass-marker  --  prod-ops-no-approval
PASS  manifest-invariant / message-does-not-name-its-own-repo-escape-hatch
FAIL  manifest-invariant / message-does-not-contain-the-hook-bypass-literal  --  prod-ops-no-approval

# separately injected ".no-make-no-mistakes-db-mutation" into inline-db-mutation-psql.message
PASS  manifest-invariant / message-does-not-name-its-own-bypass-marker
FAIL  manifest-invariant / message-does-not-name-its-own-repo-escape-hatch  --  inline-db-mutation-psql
PASS  manifest-invariant / message-does-not-contain-the-hook-bypass-literal

Each assertion discriminates rather than all firing together — red-on-everything would not have measured anything.

Ordinary prose is deliberately untouched: ds-deep-ui-import still says deep imports "bypass the barrel", and discard-stderr still says outright that it has no bypass marker. Both keep passing.

What this does NOT enforce

The invariant is mechanical, so it only catches a message that names its marker or sentinel. A future rule could still write "use the bypass marker" without naming it and no assertion would fire — that is exactly the class removed by hand in the 7 rules above, and it stays a review question, not a gate. Saying so rather than implying the check is total.

Mechanics unchanged

• Rule count 40, before and after. No rule gained or lost a bypass_marker.
• All 34 allows-bypass-marker* tests still present, still expected_exit: 0, all passing.
• rules.json regenerated and verified to be a fixpoint of npm run build-rules (the CI staleness check).

Verification

check	result
bash hooks/test-hooks.sh	340 / 340 (baseline 337 / 337, measured on a detached worktree at origin/main @ ee0ba47; +3 invariants)
npm test (vitest)	60 / 60
bash hooks/test-sentinel-walkup.sh	5 / 5
npm run build-rules + fixpoint check	in sync

Version

1.36.0 → 1.37.0 across package.json, .claude-plugin/plugin.json, .claude-plugin/marketplace.json (both fields), the README.md version line, and a CHANGELOG.md entry — the same file set as PR #53.

One drive-by: the CHANGELOG link footer still pointed [Unreleased] at v1.35.0...HEAD and had no [1.36.0] line. Both fixed.

9 files, within the 15-file rule.

---

Created by Claude Code on behalf of @lapc506

[dojo-code-reviewer]

✅ Approved

Approved — 0 blockers, 1 P3. Confidence: 4.80/5.00.

Walkthrough

⚠️ GOVERNANCE WARNING: This PR targets main directly. Under GitFlow, changes are expected to target develop first (feature → develop → main). This is an informative-only warning; the merge verdict is based on code safety.

Walkthrough

This PR implements DOJ-6433 by removing the bypass markers and repo escape hatches from all 33 affected rule refusal messages. It also introduces manifest invariants in hooks/test-hooks.sh to mechanically enforce that no future rule messages contain their own bypass_marker, disable_if_repo_file, or the literal hook-bypass string.

Files Reviewed

• .claude-plugin/marketplace.json / .claude-plugin/plugin.json / package.json — Version bumps from 1.36.0 to 1.37.0
• CHANGELOG.md / README.md / hooks/rules/README.md — Documentation updates explaining the security reasoning and manifest invariants
• hooks/rules/rules.yaml / hooks/rules/rules.json — Rule message updates removing the bypass marker self-advertisements
• hooks/test-hooks.sh — Test suite updates with the three generic manifest invariant checks

Safety Rationale

The mechanics of the bypass markers and per-repo escape hatches themselves remain fully operational and verified by existing unit tests, meaning this is a safe, output-only message cleanup that prevents reflex bypasses without breaking compatibility.

Approved — 0 blockers, 1 P3.

🔵 P3 — Minor

• hooks/test-hooks.sh:115 — 🔵 P3 (minor) — A failure in the jq or paste command inside the pipeline (e.g., due to syntax errors or environment differences) will result in an empty stdout. Since set -e is not active, the script will silently assume offenders is empty and output a false positive PASS. Checking the exit status of the pipeline immediately after assignment prevents silent failures in test execution.

[pass 1]

---

Total findings: 1 business context (1 total)

[dojo-code-reviewer]

🔵 P3 (minor) — A failure in the jq or paste command inside the pipeline (e.g., due to syntax errors or environment differences) will result in an empty stdout. Since set -e is not active, the script will silently assume offenders is empty and output a false positive PASS. Checking the exit status of the pipeline immediately after assignment prevents silent failures in test execution.

[pass 1]