feat(hook)!: make staging contextual

[jdx]

Summary

• stage fixes by default only for pre-commit
• leave manual hk fix and every other hook unstaged unless explicitly enabled
• preserve precedence: CLI, configured setting, hook, contextual default
• make step-level stage patterns filters rather than hidden staging switches
• preserve fail_on_fix as a forced no-staging mode

Stack

• Depends on feat(config)!: add shared top-level steps #1255, which depends on feat(builtins)!: expose configurable builtin factories #1253
• Part 3 of the hk v2 breaking-change rollout

Testing

• cargo test --no-default-features (287 passed)
• mise run test:bats test/stage_setting.bats
• mise run test:bats test/stage_default.bats
• cargo fmt
• git diff --check

AI-assisted — Tool: Codex; model: unavailable/unavailable; version: unavailable.

---

Note

Medium Risk
Changes default Git index behavior for hk fix and non–pre-commit hooks—a breaking v2 behavior shift that can surprise workflows relying on implicit staging, though overrides remain available.

Overview
Breaking change: auto-staging after fix commands is no longer universal. Only pre-commit turns staging on by default; hk fix, the implicit fix hook, and every other hook leave the index alone unless you opt in.

Hook-level should_stage now defaults with unwrap_or_else(|| self.name == "pre-commit") instead of always defaulting to true. Precedence is unchanged: CLI --stage / --no-stage, then global stage (HK_STAGE, git, config), then the hook’s stage, then that contextual default. fail_on_fix still forces no staging.

Step-level stage globs are filters only—they narrow which paths get git add when staging is enabled; they no longer imply staging on hooks where it’s off. When staging is on and no step patterns are set, hk still stages the files the step actually processed (not merely the step glob).

Docs (hooks.md, Config.pkl, settings.toml, env docs) and bats tests are updated; tests that expected hk fix to stage now pass --stage where staging is the assertion.

^{Reviewed by Cursor Bugbot for commit 52672e2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: c5a52fe3-eb9c-4f93-87f5-6648ef605c24

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR makes automatic fixer staging contextual: enabled by default for pre-commit and disabled for manual fixes and other hooks.

• Resolves staging through CLI, configured settings, hook configuration, and the contextual default.
• Treats step-level staging patterns as filters rather than staging switches.
• Updates documentation and integration tests for the new index behavior.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/hook.rs	Changes the final staging fallback to enable automatic staging only for the canonical pre-commit hook.
src/step/execution.rs	Applies step staging patterns only when hook-level staging is enabled while retaining default job-file filtering.
test/stage_default.bats	Covers contextual defaults, explicit hook overrides, step-level filters, and CLI disabling.
test/stage_setting.bats	Updates precedence coverage for pre-commit staging and unstaged manual fixes.
pkl/Config.pkl	Documents the contextual hook default and clarifies that step patterns only filter staged paths.

_{Reviews (22): Last reviewed commit: "test(hook): use canonical builtin factor..." | Re-trigger Greptile}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
builtins	████████████████▁	1,989,871 → 1,542,837	-22.47%	2.92 → 1.67ms	-42.87%
check	—	—	—	21.50 → 20.07ms	-6.68%
usage	▆▆▆▄▄▆▂█▁▁▁▅▅▅██▆	4,650,086 → 4,649,332	-0.02%	3.16 → 2.97ms	-6.06%
validate	—	—	—	5.48 → 5.48ms	+0.06%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

_{52672e28dc83 vs a15fcdfb197f · measured on the runner, not pushed to the history.}

[jdx]

Stack continuation: #1257 removes the deprecated v1 configuration interfaces and adds the v1-to-v2 migration guide.

AI-assisted — Tool: Codex; model: unavailable/unavailable; version: unavailable.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 179abde. Configure here.}