gitleaks false positive on CLAUDE_SHIM=0 turns the hygiene lane red for every open PR

[kyle-sexton]

Context

The hygiene job's gitleaks step fails on pull requests that do not touch the flagged file,
which fails the ci-status rollup and blocks merge. Observed on #3588, whose diff is
documentation only.

The finding, reproduced locally with the CI-pinned gitleaks 8.30.1 and this repo's
.gitleaks.toml:

RuleID:      generic-api-key
Secret:      CLAUDE_SHIM=0
File:        plugins/claude-config/lib/resolve-convention-home.sh
Line:        248
Commit:      f7aec1549dec60407a24a7d8ea720696b7b099af
Fingerprint: f7aec1549dec60407a24a7d8ea720696b7b099af:plugins/claude-config/lib/resolve-convention-home.sh:generic-api-key:248

The source is an ordinary shell variable initialization:

AGENTS_STATE="none"; AGENTS_TOKEN=""
CLAUDE_STATE="none"; CLAUDE_TOKEN=""
CLAUDE_SHIM=0

generic-api-key fires because the preceding CLAUDE_TOKEN="" line supplies the keyword context
and CLAUDE_SHIM=0 is captured as the value. There is no secret here.

Why this reaches unrelated pull requests

The commit is not on main and not on the branch of the pull request that fails. It is reachable
from origin/chore/bespoke-conversion and origin/chore/retired-conventions-mechanism, both
pushed 2026-09-01T21:47Z. The CI checkout fetches all branches, and the gitleaks step's git scan
reaches the commit through those refs — the failing run reported 1,987 commits scanned where the
pull request head's own history is 1,976. A scan confined to the head resolves clean; adding
--log-opts=--all reproduces the finding exactly.

main's own last push run (2026-09-01T21:40Z) predates the offending push by seven minutes, which
is why main is still green while every pull request opened or pushed after it is red.

Proposed fix

.gitleaks.toml states the policy: "inherit the upstream default ruleset and add nothing
repo-specific. Managed consumers do not edit this file. Intentional findings use a
repository-owned .gitleaksignore or inline gitleaks:allow comment." So the config is not the
place to fix this. Two options, in order of preference:

1. On the branch that introduced the line, add an inline allow marker, or rename the variable so
   the keyword context no longer forms (for example CLAUDE_SHIM_PRESENT=0 reads the same and
   does not sit under a *_TOKEN line).
2. A .gitleaksignore fingerprint entry. Weaker: the fingerprint is commit-scoped, so a rebase of
   that branch invalidates it.

Worth considering separately: whether the gitleaks step should scan the pull request's own history
rather than every fetched ref. Scanning all refs means any branch in the repository can red-line
every open pull request, which is what happened here.

Acceptance criteria

• The hygiene job's gitleaks step passes on a pull request whose diff does not touch
  plugins/claude-config/lib/resolve-convention-home.sh.
• The fix does not add a repo-specific rule or allowlist to .gitleaks.toml.
• A decision is recorded on whether the scan should be scoped to the pull request's own
  commits.

References

• Failing run: https://github.com/melodic-software/claude-code-plugins/actions/runs/33567373731/job/100053589384
• .gitleaks.toml (root-canonical policy, [extend].useDefault)
• Observed while driving feat(conventions): absorb the context-engineering corpus and add the instruction exception register #3588 to green.

[kyle-sexton]

Correction: the rename I proposed does not work, and this blocks every open PR

Two updates after empirical testing against gitleaks 8.30.1 with this repo's .gitleaks.toml.

1. Scope is wider than first reported. This is not confined to #3588. PR #3611
(claude/html-effectiveness-discussion-avy6p6, unrelated — visualization doctrine), run at
23:40Z, fails hygiene with every other check green: the same signature. Any pull request whose
CI runs after the 21:47Z push of chore/bespoke-conversion / chore/retired-conventions-mechanism
is red on this check, because the scan reaches the offending commit through the fetched refs
rather than through the pull request's own history.

2. My proposed fix was wrong. I suggested renaming the variable
(CLAUDE_SHIM → CLAUDE_SHIM_PRESENT). Tested against the real rule, it still fires — the rule
captures the assignment regardless of the variable's name. Results, each a minimal file carrying
the surrounding lines verbatim:

Variant	Result
CLAUDE_SHIM=0 as written today	fires (generic-api-key)
CLAUDE_SHIM_PRESENT=0 (the rename I proposed)	still fires
blank line between it and the *_TOKEN lines	still fires
AGENTS_TOKEN="" / CLAUDE_TOKEN="" lines removed	clean
CLAUDE_SHIM=0 # gitleaks:allow	clean

So the keyword context comes from the *_TOKEN="" initializations above it, and it reaches
further than the adjacent line. Renaming the flag does nothing; only removing those _TOKEN
variables (a real code change) or marking the line suppresses it.

Revised recommendation. Add the inline marker on
plugins/claude-config/lib/resolve-convention-home.sh:248, on the branch that carries it:

CLAUDE_SHIM=0 # gitleaks:allow

This is the mechanism .gitleaks.toml itself sanctions ("intentional findings use a
repository-owned .gitleaksignore or inline gitleaks:allow comment"), and unlike a
.gitleaksignore fingerprint it survives rebases and the eventual squash onto main, where the
line gets a new commit SHA and a fingerprint entry would silently stop matching.

The line is on both chore/bespoke-conversion (#3601) and chore/retired-conventions-mechanism
(#3597), so whichever lands first should carry the marker.

Still worth deciding separately: whether the gitleaks step should scan the pull request's own
commits rather than every fetched ref. That scoping is what let one unmerged branch red-line the
whole queue, and it will happen again.

---

Generated by Claude Code

[kyle-sexton]

The inline marker is correct for the file but cannot clear CI, and a second copy has appeared

Two further findings, both verified against CI's pinned gitleaks 8.30.1 with this repo's config.

1. The marker does not clear the check. chore/bespoke-conversion and
chore/retired-conventions-mechanism now carry the inline marker on the CLAUDE_TOKEN line, and
I confirmed that placement does suppress the finding in the working file (the match region spans
both lines, so the marker need not sit on CLAUDE_SHIM=0 itself). But the CI step runs
scan-mode: git, which walks history — the original unmarked blob at f7aec154 still reports
from its own commit regardless of what a later commit on the same branch says. A file-level fix
cannot retract a finding already recorded against an earlier commit.

2. A second, unmarked copy now exists. chore/pilot-plugin-quality added
plugins/plugin-quality/lib/resolve-convention-home.sh at 23:06Z with the same pattern and no
marker, producing a second finding at line 249. Whoever owns that branch should add the marker
there too, otherwise each new commit to that file mints a fresh fingerprint that no ignore entry
covers and the check goes red again.

Fix applied. #3588 now carries a .gitleaksignore with both fingerprints — the mechanism
.gitleaks.toml explicitly points at, and the one that leaves the shared ruleset untouched:

f7aec1549dec60407a24a7d8ea720696b7b099af:plugins/claude-config/lib/resolve-convention-home.sh:generic-api-key:248
708739fb2ba1b0196e93f9c07d3293bddfeed2f0:plugins/plugin-quality/lib/resolve-convention-home.sh:generic-api-key:249

The all-refs scan goes from two findings to none across 2,008 commits. It landed on #3588 because
that is the pull request that needs to merge; once it reaches main, every other open pull
request inherits it.

Follow-up this issue should still carry:

• Remove each fingerprint entry once the branch it names squash-merges or is deleted (the commits
  become unreachable and the entry becomes dead config). The file states this condition inline.
• Add the inline marker to the plugin-quality copy, so new commits there do not mint new
  fingerprints.
• Decide whether the gitleaks step should scan the pull request's own commits rather than every
  fetched ref. That scoping is the root cause: one unmerged branch red-lined the entire queue, and
  the fingerprint entries are a floor under the symptom, not a fix for it.

---

Generated by Claude Code

[kyle-sexton]

Fix is on main; this issue stays open for the three follow-ups

.gitleaksignore reached main with both fingerprints (#3611 landed it, #3588 merged as
ae3aa802 carried the same two entries and the merged header). The hygiene lane is green again:
#3588 went from red to success on the merged head, and a local scan with CI's pinned gitleaks
8.30.1 reports no leaks across all refs.

.gitleaksignore is also recorded in scripts/affected-tests-no-suite.txt, paired with the
hygiene lane, so a future change to it fails the affected-tests contract loudly rather than
mapping to nothing.

Still open, and the reason this issue is not closed:

1. Stale entries. Each fingerprint names a commit on an unmerged branch (feat: convert source-control to the retirement manifest; rationale-line the rest (Phase 2c) #3601, feat: ship the retired-conventions mechanism (Phase 2b) #3597, and the
   plugin-quality copy). Once those squash-merge or are deleted, the commits become unreachable
   and the entries are dead config. The file states that removal condition inline.
2. The unmarked copy. plugins/plugin-quality/lib/resolve-convention-home.sh on
   chore/pilot-plugin-quality still lacks the inline marker. Every new commit touching that line
   mints a fresh fingerprint that no entry covers, which re-reds the lane. Adding the marker there
   is the one change that stops the recurrence.
3. Scan scoping. Whether the gitleaks step should scan the pull request's own commits rather
   than every fetched ref. This is the root cause: one unmerged branch red-lined the entire queue
   for roughly three hours, and fingerprint entries are a floor under the symptom, not a fix. If
   this is decided as "leave as is", that is a fine answer — but it should be recorded, because
   the next branch to trip a false positive will do the same thing.

---

Generated by Claude Code