Skip to content

docs(repo-hygiene): record CLAUDE_SKILL_DIR scope residual for clean context files - #2251

Merged
kyle-sexton merged 4 commits into
mainfrom
cursor/claude-skill-dir-scope-residual-63e1
Aug 12, 2026
Merged

kyle-sexton merged 4 commits into
mainfrom
cursor/claude-skill-dir-scope-residual-63e1

Conversation

@kyle-sexton

@kyle-sexton kyle-sexton commented Aug 11, 2026 •

Copy link
Copy Markdown
Member

No linked issue

Summary

Records the decide-lane DEFER verdict for #2237: keep /repo-hygiene:clean's six bundled context/*.md files on the interpreter-led ${CLAUDE_PLUGIN_ROOT} form; do not convert them to ${CLAUDE_SKILL_DIR} until substitution scope for on-demand context files is verified empirically.

  • Adds skills/clean/reference/invocation-forms.md documenting the accepted two-form split (SKILL.md paired on ${CLAUDE_SKILL_DIR} + allowed-tools; context/*.md deferred on ${CLAUDE_PLUGIN_ROOT}).
  • Points from SKILL.md to the new reference spoke.
  • Extends allowed-tools-pairing.test.sh with a comment and guard asserting context/*.md never adopt direct ${CLAUDE_SKILL_DIR}/scripts/… invocations.
  • CHANGELOG entry under [Unreleased].

docs/conventions/permission-rule-hygiene is not standards-managed (no sync manifest entry); the residual is recorded skill-locally per convention.

No changes to the six context/*.md invocation forms.

Test plan

  • bash plugins/repo-hygiene/scripts/allowed-tools-pairing.test.sh — all checks pass, including six new context-file guards

Related

Refs #2237

@cursor

cursor Bot commented Aug 11, 2026

Copy link
Copy Markdown

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

@claude

claude Bot commented Aug 11, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @kyle-sexton's task in 2m 15s —— View job


Code review

  • Gather context (CLAUDE.md, REVIEW.md, diff)
  • Understand the request
  • Review changed files
  • Post findings

This is a docs-only PR recording a DEFER decision for #2237 — no code behavior changes. Reviewed all 4 changed files against origin/main.

Verified independently:

  • The six context/*.md files listed in the new reference doc (action-router.md, clean-batch.md, git-branch-cleanup.md, git-tree-reset.md, git-tree-reset-batch.md, preflight.md) do exist and all still use the bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/… form — matches the "no changes to the six invocation forms" claim.
  • docs/conventions/permission-rule-hygiene/README.md exists and is a real doc.
  • reference/ is an established convention directory name across many other plugins in this repo (e.g. plugins/disk-hygiene/skills/clean/reference/), so the new spoke fits repo layout.
  • The new test guard's [[ "$f" == skills/*/context/* ]] glob check is syntactically correct bash and integrates cleanly into the existing per-file loop in allowed-tools-pairing.test.sh.
  • CHANGELOG [Unreleased] entry is the only one of its kind (no duplicate heading) and matches the file's existing style/verbosity.

Not independently verified (author-claimed only): I was unable to execute bash plugins/repo-hygiene/scripts/allowed-tools-pairing.test.sh myself — Bash tool invocations in this session required interactive approval that wasn't available, so the "all checks pass" test-plan result is the author's claim, not something I confirmed by running it. Static reading of the script and target files is consistent with it passing (context files contain no ${CLAUDE_SKILL_DIR}/scripts/ occurrences), but that's inference, not execution.

One finding posted inline (Nit, invocation-forms.md#L30-L33): the new doc frames whether ${CLAUDE_SKILL_DIR} substitution reaches bundled context/*.md as simply "unverified," but the existing docs/conventions/permission-rule-hygiene/README.md already describes the scope more broadly ("the skill's markdown content and ... Bash rules in allowed-tools") without carving out on-demand context files as a distinct case. DEFER is still a reasonable call pending empirical verification, but the doc would be stronger if it explicitly acknowledged that tension rather than presenting the narrower reading as uncontested.

No other correctness, error-handling, or maintainability issues found in this diff. Security scope not applicable — this PR touches no security-relevant code paths.

@claude

claude Bot commented Aug 11, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @kyle-sexton's task in 38s —— View job


Security Review

  • Gather context (diff, changed files)
  • Review changed files for security issues
  • Post findings

Scope: git diff origin/main...HEAD — 4 files, all documentation/test-guard changes (CHANGELOG.md, SKILL.md, new reference/invocation-forms.md, and an addition to allowed-tools-pairing.test.sh). No workflow files, no allowed-tools/permission grants, and no script logic changed — the PR only records a decision to not convert context/*.md invocation forms and adds a test assertion pinning that.

Findings: none.

  • No changes to allowed-tools frontmatter or permission grants — the PR explicitly defers/avoids that conversion.
  • The new test-script guard (allowed-tools-pairing.test.sh lines ~92–103) uses fixed-string grep -qF matching and a glob-based path check ([[ "$f" == skills/*/context/* ]]) against repo-local file paths discovered via find — no external/untrusted input, no eval, no injection surface.
  • No secrets, tokens, or credentials touched.
  • No .github/workflows files in this diff, so no trigger/permission/supply-chain concerns in this lane's scope (and per instructions, unpinned-action/trigger/permission-widening patterns are zizmor's lane, not re-reported here regardless).
  • The new markdown content (invocation-forms.md, SKILL.md addition) is prose documentation with no executable directives, links, or embedded commands that could act as an injection vector.

This PR is documentation-only in effect; there is nothing in the changed files that alters a trust boundary, execution path, or access-control surface.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9a829ef651

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@github-actions

Copy link
Copy Markdown
Contributor

Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count.

@cursor
cursor Bot force-pushed the cursor/claude-skill-dir-scope-residual-63e1 branch from 9a829ef to 6463f37 Compare August 12, 2026 01:03
@github-actions

github-actions Bot commented Aug 12, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Automated review did not complete — this is an infrastructure failure, not a review verdict.

Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."

Re-run the job to retry the review. A new push re-triggers this lane only if the caller's pull_request triggers include synchronize (the canonical caller omits it).
An automatic retry may already have run — it is skipped when a partial review could duplicate comments, or when the failure class needs an operator (auth).

@github-actions

github-actions Bot commented Aug 12, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Automated security review did not complete — this is an infrastructure failure, not a review verdict.

Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."

The check is green on purpose, and it is not evidence. It certifies that a security pass ran, and this one did not complete — but the cause is outside this PR's control, so merging is deliberately left unblocked rather than locking every merge for the length of the outage. Nothing was reviewed at this head. Where this check is required, it is satisfied without that evidence; a human should review security-sensitive changes here before merging.

Re-run the job to retry the review; a new push also retries it only if the caller's pull_request triggers include synchronize (the canonical security caller keeps it). An automatic retry may already have run — it is skipped when a partial review could duplicate comments, or when the failure class needs an operator.

Re-running does NOT help for every class:

  • rate-limit that persists across re-runs, or auth — the credential or usage budget needs an operator; retrying will not clear it.
  • a run that exhausted its turn budget ("subtype":"error_max_turns" above) will exhaust it again. As the PR author, split the change into smaller PRs; raising --max-turns is a change to the caller workflow, not something you can set on this PR.

cursoragent and others added 4 commits August 12, 2026 01:39
…context files

Document the accepted two-form invocation split (SKILL.md paired on
${CLAUDE_SKILL_DIR}; context/*.md deferred on ${CLAUDE_PLUGIN_ROOT}) per
decide-lane #2237 DEFER verdict. Extend allowed-tools-pairing.test.sh to guard
context files against premature ${CLAUDE_SKILL_DIR}/scripts/ conversion.

Relates #2237

Co-authored-by: Kyle Sexton <kyle-sexton@users.noreply.github.com>
Co-authored-by: Kyle Sexton <kyle-sexton@users.noreply.github.com>
…ission-rule doc tension

- Strengthen allowed-tools-pairing guard: every context/*.md script reference
  must retain bash ${CLAUDE_PLUGIN_ROOT}/skills/<skill>/scripts/…, not only
  exclude ${CLAUDE_SKILL_DIR}.
- Acknowledge tension with permission-rule-hygiene README's broader substitution
  phrasing in invocation-forms.md.

Co-authored-by: Kyle Sexton <kyle-sexton@users.noreply.github.com>
…nvocation-forms

Co-authored-by: Kyle Sexton <kyle-sexton@users.noreply.github.com>
@cursor
cursor Bot force-pushed the cursor/claude-skill-dir-scope-residual-63e1 branch from af1fac4 to dcc8909 Compare August 12, 2026 01:41
@kyle-sexton
kyle-sexton merged commit 5e15f57 into main Aug 12, 2026
1 check passed
@kyle-sexton
kyle-sexton deleted the cursor/claude-skill-dir-scope-residual-63e1 branch August 12, 2026 02:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants