[ptr727]

Summary

The Husky pre-commit hooks now hand the prose gate the paths the commit stages, rather than .. An unrelated untracked scratch file no longer refuses every commit (#1657, option 1 of the maintainer's answer).

Naming paths would have made the gate read a staged file inside a generated tree, which a . scan skips. So the gate gains --skip-generated. It drops a named file inside a generated_trees directory the same way a directory scan does. It reads the carried list and the repository's own .prose-gate.json additions. The pre-commit snippet passes the flag and drops its exclude: (^|/)reports/ copy of that list, and its README drops the sentence about mirroring it (#3443).

• .github/actions/prose-gate/prose_lint.py, prose-gate.json: --skip-generated, applied in discover() to a named file. Without the flag a named file is still read wherever it sits, so prose_lint.py reports/x.md by hand is unchanged.
• .husky/pre-commit, catalog/snippets/husky/pre-commit: git diff --cached --name-only --diff-filter=ACMRT -z, kept only where [ -f ] holds, so a submodule, a dangling symlink, or a staged-then-deleted path does not reach the gate's error-not-a-path refusal. The inner sh skips the gate on an empty list, since a gate given no path scans . with untracked files. It checks itself rather than relying on xargs -r, because GNU xargs runs once on empty input and BSD xargs does not. The list is read once on its own before the pipeline, so a failing git diff stops the hook rather than reading as an empty list. The catalog snippet calls uv run --no-project python "$hub_fetch_run" for the gate, the form the pre-commit snippet already uses, since xargs cannot call the run_py shell function. The working-tree content is still what is read, so a partially staged file is still judged on all of its edits.
• prose_lint.py repo_root(): git hands a hook in a linked worktree GIT_DIR, and under it git -C <dir> rev-parse --show-toplevel reports <dir> itself. So the first commit through the new hook, from a worktree, was refused as spanning several repositories. The lookup now drops the location variables checkout_provenance already drops (GIT_LOCATION). A . scan never met this, because the hook stands at the top level.
• scripts/README.md, catalog/snippets/pre-commit/README.md: the hook's scope and the generated-tree sentence now describe this.

Verification

• tests/test_prose_lint.py: three new cases in TestTheScanScopeIsTheScopeReported, on constructed data. A staged file at reports/run/audit.md reports its bait when named and passes under --skip-generated. A repository-declared generated_trees entry is honored while an authored file in the same run is still read. An untracked file is not read when the run names only the staged path. A test also pins one repository lookup per directory. Full suite under tests/requirements.txt: 3336 tests OK.
• tests/test_pre_commit_hook.py: the fixture moves to a shared HookCase. Five new cases drive the hub hook through real commits beside an untracked file holding a finding. A deletion-only commit skips the gate. An edit plus a staged report under reports/ passes, and a staged finding is refused without naming the untracked file. Those three fail against the hook that scanned .. A staged-then-removed path is dropped and a typechange is read, each failing once its filter is removed. The merge-commit cases still pass.
• Hub hook driven through constructed commits in a throwaway repository. An untracked scratch comment, a copy of reports/_template.md staged at reports/run/audit.md, a deletion-only commit, a staged-then-deleted path, and a dangling symlink each exit 0. An authored file with a duplicated word, its name holding a space, exits 1. So do a new comment line and a symlink replaced by a regular file holding a finding.
• The catalog Husky snippet driven the same way, with a local shim standing in for hub_fetch_run.py. An untracked note and a staged report pass, and an added comment is refused.
• shellcheck and shfmt clean on both hooks. ruff format, ruff check, mypy clean. repo_gate.py clean.

The hook comments are wanted, so this PR carries the comments label.

Local review

• The typechange gap is fixed: ACMR dropped a symlink replaced by a regular file, so T is kept. So is the per-path repository lookup, which now runs once per directory. The duplicated git-environment filter now shares one git_env() helper. And the Husky README's count of hub_fetch_run.py calls is dropped.
• Second pass: a staged-then-removed path and a typechange each now have a hook case. Each fails when the [ -f ] filter or the T filter is dropped. lookup_start() now holds where a git lookup starts, for repo_root() and main().
• Declined: moving the non-file filter and the empty-list skip into the gate. The gate's error-not-a-path refusal deliberately refuses rather than falling back to another scan, for every caller. The pre-commit framework already drops a non-file through its default types: [file].
• Declined: xargs may split a very large commit into several gate runs. The hook still fails when any batch fails, since xargs exits 123, and each batch's scope line names its gate commit. So a split never turns into a false pass.
• Third pass, edit budget spent. Declined: catalog/snippets/hub_fetch_run.py line 9's example prose_lint.py . --diff HEAD is a valid by-hand run of the fetcher, the form scripts/README.md documents. It makes no claim about what a hook passes, so it is left as written.
• Fix pass, after the hosted review: the inner sh takes a literal sh as $0. So an error such as a missing uv names the shell, not hub_fetch_run.py or the base. main()'s scan_root fallback now calls lookup_start() too.
• Last pass, edit budget spent. Declined: the standalone read of the staged list before the pipeline was called over-hardening, since git has loaded the index before it starts the hook. It stays. Without it a failed read silently skips the gate, and the hook is also run by hand, which its own comment allows for. The cost is one git diff --name-only.

Pre-existing findings, not filed

• catalog/snippets/husky/pre-commit: no test drives the catalog Husky snippet, only the hub's own hook (coverage, pre-existing). This change ran it by hand against constructed commits, as listed under Verification. Stand-ins replaced hub_fetch_run.py, dotnet and the formatters.
• catalog/snippets/husky/pre-commit, catalog/snippets/pre-commit/.pre-commit-config.yaml: a merge commit downstream still diffs against HEAD rather than MERGE_HEAD (correctness, pre-existing). It was closed unfixed under the backlog-scope decision, so it is not refiled here.

Dropped findings

• prose_lint.py discover(): its start computation, with a . fallback for a path that is neither file nor directory, could call lookup_start (consolidation, untouched text).

• prose_lint.py GIT_LOCATION: its list differs from spec/git_env.py's, which the fetched gate cannot import. The list predates this change, which only moves its comprehension into git_env() (consolidation, untouched text).

Deferred

• GOVERNANCE.md line 299 still implies a plain git hook scans the tree. That file is held by another lane, so the one-clause fix is Say in GOVERNANCE.md That the Husky Hook Also Passes the Staged Paths to the Prose Gate #3820.

Pre-existing findings, filed

• prose_lint.py tracked_paths, untracked_paths, shallow_checkout, git_bytes: an inherited GIT_DIR reroots a subdirectory run inside a linked-worktree hook (Keep an Inherited GIT_DIR From Rerooting the Prose Gate's Subdirectory Git Reads #3821).

Closes on promotion: #1657, #3443

🤖 Generated with Claude Code

[coderabbitai]

Important

• Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

• Source mode: Auto
• Repository: ptr727/ProjectTemplate
• Branch: burndown/1657-staged-prose-hook
• File: .coderabbit.yaml
• Commit: dfc5093
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: 40a8e0e3-5993-4d73-938a-9e8be8e65f4a

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[ptr727]

A recorded local strict-review pass covers head 96deead83ecdd4d10e527b6d2dd88bc9359820d8, the content this pull request carries at that commit against develop, and it recorded 3 findings.

[Copilot]

🟡 Changes recommended

The pre-commit hooks still have critical portability and fail-open issues: GNU-only xargs -r breaks on macOS, while staged-path enumeration failures can incorrectly allow commits to proceed.

4 open issues

• Fail closed when staged-path enumeration fails · New
• Avoid GNU-only xargs -r in the POSIX hook · New
• Fail closed when staged-path enumeration fails · New
• Avoid GNU-only xargs -r in the POSIX hook · New

What changed in this PR

This pull request scopes Husky prose checks to staged regular files, adds generated-tree filtering for named paths, and improves linked-worktree repository detection.

Changes:

• Adds --skip-generated support using repository-configured generated trees.
• Updates Husky and pre-commit integrations to process staged paths while excluding deleted and non-file paths.
• Expands tests and documentation for generated files, untracked files, deletions, type changes, and linked worktrees.
• Identifies critical portability and fail-closed issues in both Husky hooks involving xargs -r and staged-path enumeration failures.

File	Description
tests/​test_prose_lint.py	Tests generated-tree filtering, staged-path scope, and linked-worktree lookup behavior.
tests/​test_pre_commit_hook.py	Tests staged-path filtering and hook behavior through real commits.
scripts/​README.md	Documents staged-path scope and generated-tree handling.
catalog/​snippets/​pre-commit/​README.md	Updates pre-commit scope and generated-tree documentation.
catalog/​snippets/​pre-commit/​.pre-commit-config.yaml	Passes --skip-generated to the prose gate.
catalog/​snippets/​husky/​README.md	Documents staged-path processing for Husky hooks.
catalog/​snippets/​husky/​pre-commit	Filters staged paths and invokes the fetched prose gate.
.husky/​pre-commit	Filters staged paths and invokes the local prose gate.
.github/​actions/​prose-gate/​prose-gate.json	Declares the new --skip-generated option.
.github/​actions/​prose-gate/​prose_lint.py	Implements generated-tree filtering and linked-worktree-safe repository lookup.

_{Review effort: Lite}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.91%. Comparing base (b38e084) to head (dfc5093).
⚠️ Report is 76 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #3823      +/-   ##
===========================================
+ Coverage    81.60%   82.91%   +1.30%     
===========================================
  Files           26       29       +3     
  Lines         9070     9750     +680     
===========================================
+ Hits          7402     8084     +682     
+ Misses        1668     1666       -2     

Flag	Coverage Δ
python-3.13	82.91% <ø> (+1.30%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ptr727]

A recorded local strict-review pass covers head 02ed8f1b79420c5aa54ee32326ff5945e58f0a01, the content this pull request carries at that commit against develop, and it recorded 1 finding.

[ptr727]

A recorded local strict-review pass covers head dfc5093cb836d17e2e1f668ec7599fa107f0b436, the content this pull request carries at that commit against develop, and it recorded 2 findings.