[kyle-sexton]

Refs: #9426

Summary

/guardrails:setup apply install-git-hooks scope=shared in a lefthook repository, or one with no hook manager yet, now commits one lefthook remotes: entry instead of copies under .githooks/guardrails/. Lefthook fetches plugins/guardrails/git-hooks/lefthook-remote.yml and its scripts from this repository's main branch and refetches them every 24h. Every consumer then runs the guardrails hooks as merged to main, with no refresh pull requests and no lint exclusions. This is the owner's decision. Husky and plain hooks keep the shared copies.

What a consumer commits in lefthook.yml (from install.mjs plan --scope remote):

remotes:
  - git_url: https://github.com/melodic-software/claude-code-plugins
    ref: main
    refetch_frequency: 24h
    configs:
      - plugins/guardrails/git-hooks/lefthook-remote.yml

Footprint. install.mjs is a shared copy: its canonical source is lib/git-hooks/install.mjs, registered in scripts/shared-copies.txt:496-505. Changing guardrails' copy therefore means changing the canonical and regenerating all 10 carriers. --check-bump then needs a fragment for each carrier, written with scripts/new-changelog-fragment.sh --carriers-of. The session-start drift notice runs that installer through lib/prerequisites.mjs, which is also shared (scripts/shared-copies.txt:234), so no guardrails-only module could quiet it. The new mode is opt-in through an entries.json remote block, so the other nine plugins behave exactly as before.

Ref: main (owner decision). Consumers track this repository's main, which changes only through reviewed pull requests under main's existing rulesets. lefthook-remote.test.sh runs end to end in PR CI: test-bash installs the pinned lefthook (2.2.2, SHA-256 checked, .github/scripts/pr-require-checks/install-lefthook.sh) on the leg that runs it, and GUARDRAILS_REQUIRE_LEFTHOOK=1 makes a missing lefthook fail instead of skip. There is no release branch and no move workflow.

Cache path. <git common dir>/info/lefthook-remotes/claude-code-plugins-main/ (lefthook's <repo name>-<ref>, RemoteDirectoryName in internal/git/remote.go).

#9426 coverage

• Delivered for lefthook consumers, because the remote removes the committed copies: items 1 (mode 100644), 2 (linted vendored copies), 3 (first-commit scan cost), 8 (on-disk mode), 9 (lint mirrors of the copies) and 10 (undetected drifted copies).
• Remaining for later work: items 1 to 3 for husky and plain-hook consumers, which keep the shared copies, and items 4 to 7 and 11 to 14 (entry-script defects that the remote does not change).

Fix

• lib/git-hooks/install.mjs and its 10 regenerated copies:
  • entries.json accepts an optional remote block (git_url, ref, config), and it is validated.
  • plan --scope remote writes nothing. It returns these decisions:
    • lefthook-config with the snippet above;
    • lefthook-install until every entry event's hook is lefthook's and the remote is fetched;
    • migrate (from: shared), naming .githooks/guardrails/ and the old guardrails-<entry> jobs;
    • remote-needs-lefthook for husky or plain hooks;
    • remote-source-dir when the consumer's lefthook config sets its own source_dir;
    • declined and the tool decisions, as before.
  • verify reports ok only when three things hold: the config has a remotes: entry with exactly the plugin's git_url, ref and config in block or flow YAML, TOML or JSON (another ref is missing with "set ref: main", and plan returns lefthook-config with foundRef), the event hook is lefthook's, and <git-path info>/lefthook-remotes/claude-code-plugins-main/<config> exists. Otherwise it reports missing with "run lefthook install".
  • copy --scope remote is a usage error.
• plugins/guardrails/git-hooks/lefthook-remote.yml holds the three jobs, named guardrails-remote-<entry>. entries.json gains the remote block.
• .lefthook/<event>/guardrails-<entry>.sh at the repository root: three one-line scripts, each running the plugin's own entry script. The scripts have to live there. When a remote config sets a top-level source_dir, it overrides the consumer's own source_dir and breaks the consumer's own script jobs (evidence below). With no source_dir, lefthook looks up a remote's scripts under the remote repository's root .lefthook/.
• skills/setup/SKILL.md: scope=shared runs plan --scope remote first. A clone-only opt-out skips the guardrails-remote-<name> job in the clone's lefthook local config, pointing at lefthook's docs for the syntax (tested with skip: true: lefthook prints "(skip) by condition"). reference/git-hook-decisions.md and the README also cover the new mode.
• Tests:
  • 8 cases in lib/git-hooks/install.test.mjs. The first 7 were checked against the old installer by restoring HEAD's install.mjs, and all 7 failed. The source_dir case fails there too, because the old installer has no --scope remote. Review added 7 more (another ref, another host or a comment, quoted and commands: job names, local copies in a remote plan, key order with flow-style YAML, TOML and JSON configs, and source_dir in TOML and JSON); each fails on the installer before its fix.
  • New plugins/guardrails/git-hooks/lefthook-remote.test.sh. It runs 11 static checks everywhere. When lefthook is on PATH it adds end-to-end cases against a file:// stand-in: the three entries block from the fetched copy, the cache is claude-code-plugins-main, and a new commit on main reaches the consumer on lefthook install.
  • One new case in scripts/plan-test-lanes.test.sh for the lefthook need.
• Fragments: guardrails minor, and the 9 other carriers patch.

Verification

Step 1 probe with lefthook 2.2.2 (lefthook version), run in throwaway repositories (obs-lefthook-remote-* beside the worktree). The stand-in is a local bare repository holding this branch's plugins/guardrails and .lefthook/. The consumer's lefthook.yml holds the exact snippet above, and git config url.file://<stand-in>.insteadOf https://github.com/melodic-software/claude-code-plugins points that URL at the stand-in. Findings:

Question	Evidence
Where lefthook stores a remote	Verbose install: git -C <repo>/.git/info/lefthook-remotes clone --quiet --origin origin --depth 1 --branch main <url> claude-code-plugins-main, then fetch --depth 1 origin -- main and checkout FETCH_HEAD. That is a shallow clone at <git common dir>/info/lefthook-remotes/<repo name>-<ref>/. A linked worktree uses the same one (git rev-parse --git-path info names the main .git/info).
How a remote job runs a remote script	A script: job whose file is in the remote. The probe printed pwd=<consumer root> src=<consumer>/.git/info/lefthook-remotes/.../probe.sh args=.git/COMMIT_EDITMSG, so the script runs from the fetched copy with the consumer as its working directory and git's arguments. A run: command also runs in the consumer root, but nothing gives it the remote's path.
source_dir in a remote	It merges over the consumer's: lefthook dump showed one top-level source_dir: plugins/guardrails/git-hooks/lefthook/, and the consumer's own script: mine.sh job failed with script does not exist: mine.sh. Without it, scripts resolve under the remote's root .lefthook/, and both the consumer's .lefthook/pre-commit/mine.sh and the remote's scripts ran.
The three entries from the fetched copy	commit-msg: an off-pattern subject blocked (Rewrite the subject to match the pattern..., rc=1) and ABC-1: initial passed. pre-commit: notes.md:2: secret or credential pattern: GitHub PAT, rc=1. pre-push (use_stdin: true, on a branch with no upstream, pushing main): readme.md:1: stale-path-verify: cited path(s) in readme.md were deleted from this repo, rc=1. Each entry found its libraries in the plugin layout and read the consumer's index, message and .claude/source-control.md.
Same job name in two configs	An old guardrails-commit-msg-convention run: job plus a remote job of that name merged into one job holding both run: and script:, which failed: either run, script, or group must be provided for a job. The remote jobs are therefore named guardrails-remote-<entry>. With different names, a half-migrated repository runs both.
Fetch failure, cache present	The hook printed Couldn't sync https://github.com/melodic-software/claude-code-plugins main. Will continue with fallback version: main. and ran the cached jobs; the commit went through.
First install offline	lefthook install printed Couldn't sync from ... Will continue anyway: exit status 128 and sync hooks: ✔️ but installed only prepare-commit-msg, so commits were unchecked. Restoring the network did not repair it; a second lefthook install did. verify now reports missing in this state.
ref and refetch	lefthook install always fetches, for a branch and for a force-moved tag alike. A hook run within 24h does not fetch. A hook run after the cache's .git mtimes were aged 25h did fetch, for the branch and the tag alike. The ref docs warn against dropping ref once used. Per the refetch_frequency docs, "Failure to fetch does not cause an error, but just a warning message."
Consumer source_dir	When a consumer sets source_dir: .hooks/, lefthook looks for the remote's scripts under .hooks/ in the fetched copy: guardrails-remote-pre-commit-content: script does not exist: guardrails-pre-commit-content.sh, and the commit fails. plan --scope remote now returns remote-source-dir for this case. None of standards' components/lefthook-*/lefthook.yml sets source_dir.
Pilot consumer (standards main at eaac7fa)	plan --scope remote returned lefthook-config, lefthook-install, and migrate (from: shared, the three .githooks/guardrails/ scripts, the three guardrails-<entry> jobs). After applying them (snippet added, .githooks/guardrails/ and the three jobs removed, the pre-commit exclude line dropped), lefthook install synced commit-msg, pre-commit, pre-push and verify printed ok three times. lefthook dump showed the remote jobs merged alongside standards' commands: and hook-level exclude. A non-conventional subject blocked; a conventional one committed, with editorconfig, typos, gitleaks and guardrails-remote-pre-commit-content passing.
Invalid remote YAML	Every commit in the consumer failed with Error: yaml: ... (rc=1), and lefthook install failed the same way before it refetched. To recover, run rm -rf "$(git rev-parse --git-path info)/lefthook-remotes/claude-code-plugins-main" && lefthook install once the fix is on main (also in the README) (the empty-cache reinstall above is the evidence).

Suites:

• node --test lib/git-hooks/install.test.mjs: 60 pass.
• bash plugins/guardrails/git-hooks/lefthook-remote.test.sh with GUARDRAILS_REQUIRE_LEFTHOOK=1 and lefthook 2.2.2: 19 pass. With lefthook stripped from PATH: a SKIP, or a FAIL when GUARDRAILS_REQUIRE_LEFTHOOK=1.
• plan-test-lanes.test.sh 43 pass. actionlint is clean on pr-require-checks.yml.
• Every plugins/*/git-hooks/*.test.sh and plugins/guardrails/hooks/git-hooks-notice.test.sh pass.
• scripts/sync-shared-copies.sh --check reports 520 copies match.
• --check-bump origin/main passes.
• scripts/check-changelog-fragments.sh --check passes.
• shellcheck and shfmt are clean on the new shell files.

Limitations:

• Each consumer clone holds a depth-1 checkout of this whole repository. Measured: 188M and 12,703 files, cloned in 6 s. Lefthook remotes have no sparse checkout. Linked worktrees share one copy.
• A broken lefthook-remote.yml on main would block every consumer's commits until it is fixed and refetched. Before merge, test-bash installs the pinned lefthook on the leg that runs lefthook-remote.test.sh (a new lefthook need in scripts/plan-test-lanes.sh) and sets GUARDRAILS_REQUIRE_LEFTHOOK=1, so that suite fails there instead of skipping.
• verify looks for lefthook 2.2.2's observed cache path, <repo name>-<ref>, and falls back to any <repo name>-* directory holding the config, so a lefthook release that renames it still verifies.
• A consumer with its own lefthook source_dir cannot use the remote (remote-source-dir).
• Every consumer runs main within 24h of a merge; a change to the hooks reaches them only through a reviewed pull request whose CI ran the end-to-end test.

Related

• guardrails: shared install-git-hooks copies fail consumer CI (mode 100644, linted vendored scripts) #9426
• chore(git-hooks): install the guardrails git hooks as shared lefthook jobs standards#852, which committed the shared copies this mode replaces and is a migration target.
• chore(git-hooks): install the guardrails git hooks as shared lefthook jobs #9462 (another session's PR, adding shared copies to this repository), also a migration target.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-24T01:39:45.389526Z	5529a1c	Draft marked ready

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5529a1c3bc

ℹ️ 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]

claude-security-review reviewed 4381c64bf6ffe19dbcc4419bab1a255edf2ee82a: 0 finding(s), 0 as inline comments.

Incremental security review of 4381c64 against 7132cf3: no security issues found.

The change is a single character class edit. In lefthookRemotes (lib/git-hooks/install.mjs:579) the remotes: block regex goes from [ \t-] to [ \t#-], so a column-0 comment no longer ends the block early. The edit is carried unchanged into the 10 generated copies, and lib/git-hooks/install.test.mjs gains one regression test.

• Commented-out entries stay inert. Line 586 strips whole-line comments (^[ \t]*#.*$) from each entry before git_url, ref and configs are read. The entry split (line 582) and indent detection (line 580) key on - at the start of a line, so a # - git_url: ... line neither starts an entry nor adds keys to the previous one. A comment cannot make verify report ok for a remote that is not configured.
• No wider trust boundary. The parser is read-only and feeds only the verify and plan decisions. It never executes or fetches anything from the parsed text. The regex is linear, so there is no ReDoS concern.
• Worst failure is benign. The old behavior hid later entries and could report missing. The new behavior is stricter about what counts as an entry.
• No manifest, workflow or instruction-surface changes in this increment, so no manifest <field> lines apply. The change touches no trust-gate path.

critical-findings: 0

[github-actions]

claude-review: 2 inline finding(s) on 5529a1c3bc9bbcde210dcadc740dbc26f4b9008a; the summary is in this lane's pull request comment.

claude-lane: claude-review

[github-actions]

claude-review reviewed 4381c64bf6ffe19dbcc4419bab1a255edf2ee82a: 0 finding(s), 0 as inline comments.

Incremental review of 4381c64 against 7132cf3: no findings.

The change widens the remotes: block regex in lefthookRemotes from [ \t-] to [ \t#-] at lib/git-hooks/install.mjs:579. A column-0 comment between two entries no longer ends the block and hides the entries after it. I read the function in the head file and traced the downstream steps:

• A column-0 comment line stays inside the block and is attached to the preceding entry's raw text. raw.replace(/^[ \t]*#.*$/gm, "") strips it before any key is read, so it cannot add a git_url, ref or configs value.
• The ^${indent}-[ \t]+ split cannot match a comment line, because the line starts with #. This holds when the indent is empty too.
• A trailing column-0 comment after the last entry is now consumed and then stripped. A following top-level key such as pre-commit: still ends the block, since it starts with none of space, tab, # or -.

The new test a column-0 comment between remotes entries hides no entry (lib/git-hooks/install.test.mjs:754) places a column-0 comment between a foreign entry and the plugin's entry. It asserts that verify reports ok and that plan returns no lefthook-config decision. Before the fix, the block stopped at the comment and the plugin's entry was invisible, so the test targets the bug. I did not run the test suite: the lane has no shell. The 60-pass claim in the PR body is author-claimed and unverified by me.

The same one-line change appears in the 10 carrier copies (actionlint, bash-format, biome-format, go-format, guardrails, instruction-placement, markdown-format, powershell-format, ruff-format, typos-format). Each hunk in the diff is identical to the canonical one, so the shared copies stay in step. I did not run sync-shared-copies.sh --check.

No plugin.json or marketplace.json change in this increment, so no manifest lines apply. No cost or trust-gate files are touched, so there is no hold.

[kyle-sexton]

Reply to the claude-security-review finding on 5529a1c (consumers run code from an unprotected mutable branch):

Finding	Classification	Evidence
Nothing restricts who can move or delete guardrails-release, so any account or contents: write workflow token can ship code to every migrated consumer within 24h	VALID; whether to merge before the protection lands is held for the owner (UNCERTAIN)	gh api repos/melodic-software/claude-code-plugins/rulesets lists rulesets only for the default branch and release/plugins. AGENTS.md says lanes "read untrusted issue and PR text while holding push credentials", so an attacker does not need a human account. The local security review found the tag-shadowing variant; a local probe with git 2.53 confirmed it, and the workflow now refuses to move the branch while such a tag exists.

The fix is a ruleset in github-iac (branch create, update and delete; tag creation; a dedicated App bypass), tracked in #9531. That is an org trust-boundary change, so this PR does not make it. The open question for the owner is whether this PR merges before #9531 lands or waits for it. The branch comes into existence when the guardrails release PR merges, and /guardrails:setup offers the remote from that release onward. This PR is not being merged until the owner answers.

[github-actions]

claude-review: 1 inline finding(s) on 70f2fd904d4b8d871ffee703f3688fba34066ea5; the summary is in this lane's pull request comment.

claude-lane: claude-review

[kyle-sexton]

Follow-up on the claude-security-review finding (consumers run code from an unprotected mutable branch), after the owner's decision:

Finding	Classification	Evidence
Nothing restricts who can move or delete guardrails-release	INCORRECT as of ab4c635 (the branch no longer exists in this design)	ab4c635 sets entries.json remote.ref to main and removes release-move-guardrails-ref.yml, move.sh and its test. Consumers now track main, which changes only through reviewed pull requests under main's existing rulesets. lefthook-remote.test.sh runs end to end in PR CI: test-bash installs the pinned lefthook and sets GUARDRAILS_REQUIRE_LEFTHOOK=1.

No branch is left to protect, so the follow-up #9531 is closed.

[github-actions]

claude-security-review: 1 inline finding(s) on ab4c635855894b3b3c4be382be917eedc0bf6808; the summary is in this lane's pull request comment.

claude-lane: claude-security-review

[github-actions]

claude-review: 1 inline finding(s) on 0267d3510d05f7e93a42cb5503216963e93a8a80; the summary is in this lane's pull request comment.

claude-lane: claude-review

[github-actions]

claude-security-review: 1 inline finding(s) on 7132cf3619ae1defcbf23bd86d8f981609d6c0d0; the summary is in this lane's pull request comment.

claude-lane: claude-security-review

[github-actions]

claude-review: 1 inline finding(s) on 7132cf3619ae1defcbf23bd86d8f981609d6c0d0; the summary is in this lane's pull request comment.

claude-lane: claude-review