[jdx]

Summary

• classify every command exposed by the current builtin catalog: 236 command fields across 144 command-bearing modules
• wrap builtin commands at the generated Builtins.pkl boundary so overrides replace both the command and its safety claim
• classify fixers as writes and checks that populate caches, compile, or synchronize data as writes; other checks are reads
• fail builtin generation if any exposed check, check_list_files, check_diff, or fix command lacks an effect

Stack

Depends on #1166 (feat(step): add command effect safety). This is layer 4 of the agent-native hk stack.

Test evidence

• python3 -m py_compile scripts/gen_builtins.py
• mise exec ruff@0.15.20 -- ruff check scripts/gen_builtins.py
• mise exec ruff@0.15.20 -- ruff format --check scripts/gen_builtins.py
• mise run pkl:gen (includes 100% effect-coverage validation)
• mise run build
• mise run test:bats test/builtin_effects.bats
• mise run test:bats test/builtins_tests.bats was attempted locally; catalog loading and effect wrapping succeeded, while 27 tool executions failed because this host lacks configured Node, Ruby, or Java runtimes and one network-dependent zizmor check timed out. CI has the project toolchain and remains authoritative for the complete catalog.

Rollout notes

Builtin consumers receive explicit effects automatically. A user override such as replacing Builtins.trailing_whitespace.check_diff with a string becomes unknown rather than inheriting the builtin's read claim. No builtin is marked destructive because current builtin commands only inspect or update recreatable/project state.

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

---

Note

Medium Risk
Large mechanical change across 100+ builtin modules; misclassified read vs write could block or allow the wrong commands under safe mode, though generation enforces complete coverage.

Overview
Builtin commands now declare safety effects so hk can reason about read-only vs mutating steps (e.g. --safe, plan JSON).

Across the builtin catalog, check, check_list_files, check_diff, and fix are no longer bare strings or Command objects—they use Config.CommandSpec with effect = "read" for typical linters/format checks and effect = "write" for fixers and checks that compile, sync, or write caches (cargo, tsc, vale, rubocop, etc.). No builtins are marked destructive.

scripts/gen_builtins.py runs validate_effect_coverage() after generating Builtins.pkl, evaluating the catalog as JSON and erroring if any exposed command field lacks a valid effect. Deprecated builtin aliases now re-export the canonical builtin directly instead of re-importing the module path.

test/builtin_effects.bats asserts plan output includes per-step effects, safe mode runs a read builtin, and overriding a builtin command without CommandSpec surfaces an unknown effect instead of inheriting the builtin’s read claim.

^{Reviewed by Cursor Bugbot for commit c77afc6. 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: 4884ca5e-0d68-46bd-8361-46a126012c19

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 adds generated effect metadata to builtin commands and validates complete effect coverage during generation.

• Wraps builtin command fields with read/write effect declarations.
• Preserves effect handling across deprecated aliases and user command overrides.
• Adds integration coverage for plans, safe-mode execution, fix effects, and overridden commands.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
scripts/gen_builtins.py	Generates effect-wrapped builtin steps, validates command-effect coverage, and redirects deprecated aliases to wrapped canonical definitions; no eligible follow-up defect was established.
test/builtin_effects.bats	Verifies read/write plan metadata, safe execution of read commands, fix classification, and denial of an override whose effect becomes unknown.

_{Reviews (6): Last reviewed commit: "feat(builtins): classify command effects" | Re-trigger Greptile}

[greptile-apps]

Too many files changed for review (146 files, 100 file limit).

Bypass the limit by tagging @greptile-apps to review.

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
builtins	▁▁▁▁▁▁▁▁▁▁▁▁▁█	3,371,735 → 3,628,840	+7.63% ⚠️	2.85 → 2.67ms	-6.33%
check	—	—	—	19.56 → 20.08ms	+2.65%
usage	▁▁▁▁▁▁▁▁▁▁▁▁▁█	23,189,004 → 25,994,909	+12.10% ⚠️	5.00 → 5.25ms	+4.90%
validate	—	—	—	5.04 → 4.72ms	-6.28%

2 benchmark(s) above the 1% gate: builtins +7.63%, usage +12.10%

_{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.}

_{c77afc6e3737 vs 075e80902082 · measured on the runner, not pushed to the history.}

[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 f6ee638. Configure here.}