claude-config(audit-permission-grants): remediation prescribes a bare-name-on-PATH pattern that is unavailable on the measured platform

[kyle-sexton]

Problem

claude-config:audit-permission-grants prescribes a remediation that cannot be executed on the
platform the permission-rule-hygiene convention actually measures.

• plugins/claude-config/skills/audit-permission-grants/SKILL.md (Phase 2) tells the operator to
  "replace the fragile grant with the bare-name-on-PATH pattern from the convention".
• plugins/claude-config/skills/audit-permission-grants/reference/criteria.md (P1 Recommend)
  says "expose the helper as a bare command on PATH and allow the bare name narrowly."

docs/conventions/permission-rule-hygiene/README.md now carries a Known gap section (added in
#1277) recording the measured fact that a plugin's bin/ directory is not placed on the Bash
tool's PATH — harness-wide, not a packaging defect — and that the two obvious substitutes
(~/.local/bin shim, env.PATH in user settings) both rot on the version-numbered install path.

So on Windows / Git Bash the audit hands the operator a remediation with nothing to match. The
detector is right that the grant shape is an anti-pattern; the prescribed fix is unavailable.

Wanted

The audit's criteria and reporting should recognize this platform-specific unresolved state instead
of prescribing the unavailable bare-name pattern unconditionally — e.g. keep the finding, but state
the bundled-path invocation as the form that works today and point at the convention's Known gap
section for why the bare-name end state is not yet reachable.

Scope

plugins/claude-config/skills/audit-permission-grants/ — carries a claude-config plugin version
bump plus a CHANGELOG entry.

Origin

Codex review finding on #1277, judged VALID but out of that PR's scope: #1277 is docs-only under
docs/conventions/ and ships no plugin change. Filed here so the deferral carries a durable trigger.

Refs #843 — the upstream capability whose absence creates the mismatch.

[kyle-sexton]

This was generated by AI during triage.

Verified — the reported gap is real, but its premise is not yet true on main.

Role-label resolution note: .work-item-tracker.json has no config.role_labels entry; defaults (agent-ready / needs-human) are used, per the taxonomy's loud-warning requirement.

Confirmed:

• The audit-permission-grants skill's Phase 2 report recommendation and its P1 criteria entry do unconditionally prescribe "expose the helper as a bare command on PATH" with no platform caveat.
• PR docs(permission-rule-hygiene): record the undelivered plugin bin/-on-PATH capability #1277 (the origin of this issue) is still OPEN, not merged (mergedAt: null). Its target — a "Known gap" section in the permission-rule-hygiene convention doc — does not exist on main yet. Right now the convention doc still states the plugin bin/-on-PATH mechanism as the working post-migration pattern (citing the official plugins-reference "Executables" row) with no caveat.
• source-control:babysit-prs: plugin bin/ not on Bash-tool PATH — guarded wrapper bare names unresolvable (blocks narrow allow-rule match) #843 (the upstream capability issue this all traces to) is open and unresolved.

Brief (for whoever picks this up):

Update the audit-permission-grants skill's Phase 2 report language and its P1 criteria "Recommend" text so the remediation acknowledges the platform-specific unresolved state instead of prescribing the bare-name-on-PATH pattern unconditionally: keep the P1 finding (the grant shape is a real anti-pattern), state the bundled-path invocation as the form that works today, and point at the convention's Known gap section for why the bare-name end state isn't reachable yet. Bump the claude-config plugin version and add a CHANGELOG entry. No file paths/line numbers needed beyond the skill and criteria doc named above — durability over precision.

Routing — human-gated, not because of an open design decision, but a sequencing/capability blocker: this fix should land after PR #1277 merges (so the "Known gap" section it points to actually exists) — but the tracker's native blocked-by dependency edge only resolves issue-to-issue, not issue-to-PR:

failed to update ...#1398: resolving --add-blocked-by reference ".../issues/1277": GraphQL: Could not resolve to an Issue with the number of 1277. (repository.issue)

So the dependency can't be structurally enforced here — recording it as this comment instead of a status:ready + agent-ready label, to avoid an autonomous lane picking this up, greping for "Known gap," finding nothing, and either half-fixing it or scope-creeping into #1277's own work. Once #1277 merges, re-triage this to agent-ready + status:ready — at that point it's a small, fully delegable doc fix with no remaining open question.

[kyle-sexton]

This was generated by AI during triage.

Duplicate filed and closed: #1407 re-raises this same finding — both trace to the same Codex review thread on still-open PR #1277. Closed #1407 as a duplicate of this issue (--duplicate-of) rather than triaging it independently.

#1407 verified one additional prescription site this issue's brief did not yet name, plus three explicit decision points worth carrying into the eventual fix here:

• Third site — plugins/claude-config/skills/audit-permission-grants/scripts/permission-rule-check.sh's P1 remediation string ("Expose the guarded script as a bare PATH command and allow that...") also prescribes the bare-name-on-PATH fix unconditionally, alongside the SKILL.md Phase 2 report language and criteria.md's P1 "Recommend" entry already named above. A fix has to touch all three, not just the two docs.
• Does the finding stay P1 on a fixed path? criteria.md's own concession that the drop-category classification is a convention judgment call for this shape (not confirmed drop behavior) may mean P1 overstates it once the remediation is known to be unavailable.
• What does the report say when no remediation exists? The audit currently has no vocabulary for a platform-blocked finding — needs a distinct severity, an explicit "blocked upstream" disposition, or a per-platform note, worded so it doesn't read as a to-do the operator failed to do.
• Where does the platform fact live? docs(permission-rule-hygiene): record the undelivered plugin bin/-on-PATH capability #1277's "Known gap" section (once merged) should be the cited source of truth — the audit should point at it, not restate it.

Still routed human-gated, still blocked on #1277 merging first, per this issue's existing triage note.

[kyle-sexton]

Batch-4 filing note — two newly-filed rows share this remediation surface and will collide with any fix here in reference/criteria.md:

• fix(claude-config): audit-permission-grants' criteria.md is a stale pinned copy, and its remediation advice is wrong in four places downstream #2284 A10 — plugin bin/ is never mentioned anywhere in the skill. Important for whoever fixes this: the originating item framed bin/ as "what makes the skill's own bare-name-on-PATH advice achievable", and this repo's own convention says the opposite at docs/conventions/permission-rule-hygiene/README.md:177-179 ("Known gap — step 1's plugin bin/ delivery is unreliable, not absent"). Documenting bin/ as the answer without that caveat would re-open exactly this issue.
• fix(claude-config): audit-permission-grants' criteria.md is a stale pinned copy, and its remediation advice is wrong in four places downstream #2284 A7a residue — fix(claude-config): drop P2's unsupported no-expansion claim, refuse an unresolvable scan root, and key the postures report per project #2259 brought ${CLAUDE_SKILL_DIR} into P2, but P1's Recommend line (criteria.md:56-57) still prescribes only bare-name-on-PATH, and P1 is the check every interpreter-led fleet grant actually trips. The variable appears zero times in SKILL.md and zero times in the test suite.
• fix(claude-config): audit-permission-grants' criteria.md is a stale pinned copy, and its remediation advice is wrong in four places downstream #2284 A6 — the skill prescribes that the operative rule land in ~/.claude/settings.json and no code path in the detector ever reads ~/.claude/settings.json or $HOME.

Ledger: .work/handoff-inbox-batch-4/ledgers/I10-permission-grants-fleet.md § A6, A7a, A10.