Optional per-commit validation hook (--verify) for staged snapshot

[wkentaro]

This was generated by AI.

Problem

git-hunk's whole purpose is producing a clean series of focused commits where each commit is independently valid. But nothing enforces that invariant — an agent can stage a partial hunk that leaves the file unparseable (e.g. a selection that drops a closing brace) and only find out later.

Proposal

Add an optional validation command that runs against the staged-tree snapshot and refuses the stage (non-zero exit) on failure:

git-hunk stage 66279ce -l ^115-119 --verify 'python -m py_compile path/to/file.py'

Behavior:

• Materialize the would-be-staged content (the same snapshot preview would emit), run the --verify command against it, and only commit the stage to the index if the command exits 0.
• On failure, leave the index untouched and report the command's output.

This bakes the "each commit builds" discipline into the tool instead of relying on the agent to remember to check.

Notes

• Depends conceptually on materializing the staged file state (see the preview issue); could share that machinery.
• Could later be promoted to a configurable default (e.g. a repo-level verify command) but a per-invocation flag is the minimal version.
• One of a set of agent-usability ideas from the same session.

[wkentaro]

This was generated by AI during triage.

Triage Notes — deferred, blocked by #57

This is a sound request, but it is not yet ready for an agent because it is built directly on machinery that does not exist yet.

What's established:

• --verify <cmd> should materialize the would-be-staged snapshot, run <cmd> against it, and commit the stage to the real index only if <cmd> exits 0; on failure, leave the index untouched and report output.
• This is the same "materialize staged content without touching the index" primitive that preview: emit resulting staged file content without touching the index #57 (preview) introduces. Optional per-commit validation hook (--verify) for staged snapshot #58 should reuse it, not reinvent it.

Why deferred: briefing #58 now would have to guess the shape of a primitive #57 is about to define. Sequence it after #57 lands, then reuse #57's materialize_staged_content.

Design questions to settle once #57 exists (the genuinely unresolved part):

• Where does <cmd> run? Against a temp worktree populated with the would-be-staged content of the affected file(s), so a relative path like python -m py_compile path/to/file.py resolves? Or is the snapshot handed to the command another way (stdin, a temp file path in an env var)? This is the core UX decision and affects how multi-file selections behave.
• Scope of the snapshot: just the affected file(s), or the whole tree with those files swapped to their staged-result content (so the validator can import siblings/run tests)?
• Which commands carry --verify — stage and commit, or also unstage/discard?

Recommend keeping in needs-triage until #57 is implemented, then a short grilling pass on the command-execution model promotes it to ready-for-agent.