Commit Response Template¶

Use when user asks to commit or for commit summary, and for task-scoped local commits approved by the user's answer or a local Git approval grant.

Required Commit Message Shape¶

Always use:

<type>(<scope>): <title>

Changes:
- <what changed, including the affected surface and resulting behavior>
- <what changed, including the affected surface and resulting behavior>

Impact:
- <concrete user, developer, runtime, compatibility, or maintenance effect>
- <concrete user, developer, runtime, compatibility, or maintenance effect>

Verification:
- <concise final check that materially validates the committed change, with its result>

Residual limits:
- <remaining risk, warning, deferred work, or "None known">

---

Co-authored-by: Codex <codex@openai.com>

Rules:

Creating a new commit does not authorize rewriting an existing commit. Never run git commit --amend, git rebase, git reset, squash, fixup, or an equivalent history rewrite unless the user explicitly requests that exact history operation. Never infer rewrite permission from a commit, cleanup, or commit-diet request.
First line: Conventional Commit.
<type> lowercase: feat, fix, docs, refactor, test, chore, ci, or perf.
Prefer specific lowercase <scope>: api, cli, config, tests, docs, ci, deps, packaging, models, data, or utils.
<title> imperative, concise, under 72 characters when practical.
Never hard-wrap commit messages. Keep each prose paragraph and each list item on one physical line regardless of length; preserve intentional breaks between the subject, section headings, separate list items, blank lines, and trailers. The title-length guideline does not impose a body line-width limit. Apply this rule to both the displayed draft and the exact message passed to Git.
Name behaviour in plain words in the title and body; never a skill's internal phase, step, or branch label the reader has not seen. Grep the draft for such labels before committing.
Body: always include four exact headings Changes:, Impact:, Verification:, and Residual limits: in that order.
Changes: must list every meaningful behavioral, interface, workflow, policy, test, documentation, packaging, or operational change included in commit. Name affected surface and describe resulting behavior; filename-only inventory is insufficient.
Impact: must state the concrete user, developer, runtime, compatibility, or maintenance effect for each change or tightly related group of changes. Generic impact claims such as "improves UX" or "makes things better" are insufficient.
Verification: includes only final checks that materially validate the committed surfaces or their acceptance contract, each with a concrete result. Consolidate closely related checks and report a required broad gate once using its final outcome. Do not list exploratory probes, failure-first reproductions, setup or environment diagnostics, repeated reruns, superseded failures, or unrelated repository-wide gates. State an exact not-run reason only for a material change-specific acceptance gate; never imply that an unexecuted check passed.
Residual limits: must list warnings, deferred work, and remaining uncertainty, or contain exactly - None known when no material limit remains.
Extensive means complete and auditable, not padded: omit pure lint/format churn, generated cache, typo-only edits, and verification chronology unless they are whole change; combine tightly related details without hiding distinct effects.
Keep --- before trailers. When Claude shaped the committed diff (code, review, diagnosis, or work Codex commits on Claude's behalf), put Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com> on the line before the Codex trailer. End with exactly:

Co-authored-by: Codex <codex@openai.com>

File-Free Commit Execution¶

As an application of the general approval contract, show the complete secret-free message in chat with the exact reviewed path list, then pass that same text as one message argument in one owning command that stages exactly those paths and commits them: rtk git add -- <paths> && rtk git commit --cleanup=verbatim -m <message>. Apply Authorized Workflow Execution: an authorized local commit uses existing runtime grants and does not require escalation merely because it writes .git. Use raw git when RTK is unavailable. Do not create a temporary or persistent commit-message file, ask for draft-file permissions, or schedule draft-file cleanup. Git's own internal commit files and local hooks remain normal Git behavior. Never shorten required detail to reduce the approval prompt.

When the checkout holds one, a Local Git approval grant covers ordinary finding-fix commits: the grant supplies consent once the owned plan and checks match, so do not open another authorization question. Without a grant, the contract's one Approve / Approve always / Deny question applies to a plain commit, unless a workflow step that defines the commit or an explicit same-turn request authorizes it. Staging and a task-owned merge commit never ask, grant or not. Reuse grouping preferences; default to one coherent commit when none is supplied. An explicit decide after verification, leave unstaged, denial or no-commit instruction still controls. Merge commits retain Local merge approval ownership and proof checks.

For code-remediate's explicit-request sequencing override only, record the explicit request and remaining report checkpoint in commit-plan.md. Run and record the owning workflow's applicable checks and prove ownership/destination, then execute and verify the requested local commit without waiting solely for final report validation. Code Remediate's explicit local snapshot exception permits failed checks, timeouts and known regressions when the user actually requested the bound commit; preserve those failures and unresolved work in Verification and Residual limits. Standing approval/default grouping alone does not activate this exception; runtime denial, hook failure, ownership/destination uncertainty and open security/critical findings still block the affected mutation. Resume the normal handoff validation and promotion afterward with the real hashes and disposition. Standing approval or a grouping preference alone does not invoke this override; unrelated workflows retain their own gates.

When conversational commit authorization is actually missing, follow User Questions: invoke a permitted native control, using the packaged ask_user form when sync is unavailable, prohibited for authorization, or cannot fit every mode; use async only after verifying its suitability and the native form is unavailable. Keep dependent work pending; use plain chat only after establishing that no permitted native control is suitable. Binary canonical options are Approve and Deny, supplied separately; apply User Questions' recommendation suffix and decision-key labeling before presentation. An existing commit-mode question retains all feasible choices in one supported control. Runtime permission controls retain their actual options. This does not add a confirmation after an explicit commit request.

Before the command, inspect git diff HEAD -- <paths> for exactly the reviewed paths and git status --porcelain=v1 -- <paths> so untracked new files are read too; record pre-commit HEAD. Reviewed paths are explicit repo-relative file paths, never ., a directory, or a glob. Then check git diff --cached --name-only: any staged entry outside the reviewed paths is user state and stops execution before the command; do not unstage, reset, or commit it. An explicit commit request needs no additional conversational confirmation; retain any runtime-required approval. A summary-only request never authorizes commit.
The chained command needs shell text. Construct each POSIX argv segment with shlex.join or equivalent literal quoting: single quotes with each embedded apostrophe encoded as '"'"', never three adjacent apostrophes. Before executing a constructed multiline shell command, validate its syntax without execution using the actual shell's parser (bash -n for Bash, zsh -n for Zsh; PowerShell's parser API for PowerShell). A parse check is read-only and does not require new consent. PowerShell single quotes double apostrophes, only when native argument passing preserves embedded quotes and newlines. Never use double-quoted shell interpolation, eval, command substitution, or expanding here-document to carry message text. Keep dollar signs, backticks, backslashes, quotes, blank lines, and Unicode literal; use LF line endings. Do not assume POSIX quoting works in PowerShell or that legacy Windows native argument passing is lossless. When the execution tool accepts only shell-free argv, or the observed shell has no success-only chaining operator (Windows PowerShell 5.1 has no &&), run rtk git add -- <paths> and then rtk git commit --cleanup=verbatim -m <message> as two argv calls with no other change. The same authorization and effective permissions cover both calls; a tool transport change alone does not require another approval.
Unsupported shell/native argument behavior, NUL characters, or command-size or encoding limits stop execution with the exact limitation. Do not silently fall back to a file, change the reviewed text, widen permissions, or introduce an interpreter wrapper to conceal the commit from approval. Use an available verified argv route before requesting approval; otherwise leave the commit pending for user direction.
Run with use_default or no sandbox override when the required repository and Git metadata paths are writable. Reuse any existing matching command allowance; do not request another approval or suppress an applicable saved allowance. If an actual missing capability requires runtime approval, request only that capability for the complete owning command under the shared approval contract. The short plain-English reason asks to stage the reviewed paths and create one local commit from them; it must not repeat the command, flags, message body, or full approval brief. The full message may appear in the runtime command approval and local process arguments; disclose that tradeoff, never include secrets. Do not promise network-free hooks without evidence; unexpected hook network needs retain their own approval boundary. This workflow does not promise a fixed number of host approval prompts.
After success, read committed UTF-8 message from raw Git output, not RTK summary: git --no-pager show -s --format=format:%B HEAD (the format: form adds no formatter newline). Compare it with text shown in chat after normalizing only one terminal LF on both sides; do not trim whitespace, collapse blank lines, or use shell capture that strips trailing newlines. For ordinary commits, read the committed file set with git --no-pager show --no-renames --name-only -z --format= HEAD and require it to equal the reviewed path list exactly as a set; --no-renames keeps a rename's old path and -z keeps non-ASCII paths unquoted. For merge commits, use the merge proof below instead of that default combined-diff path check. Verify new commit and post-commit index/worktree state before claiming success.
Classify a failure before stopping recovery. Inspect HEAD, the index, worktree, and merge state against the pre-command observations; a failed invocation may still have side effects. For a proven pre-execution syntax failure with unchanged state, correct the quoting, verify the same reviewed paths and message, validate syntax, and make one corrected attempt under existing authorization. No new commit consent or generic request to resume is needed. If staging succeeded but commit did not start, verify the index contains exactly the reviewed content and no unrelated changes, then run only the corrected commit segment under the same authorization. If a commit already exists, verify it under step 5 and do not create a duplicate commit.
On an actual user or runtime denial, uncertain execution, hook failure, concurrent changes, or mismatch, stop the affected mutation and first inspect state read-only; a mismatch includes a committed file set that differs from the reviewed paths. Do not amend, reset, unstage, blindly re-stage, or create a repair commit. A diagnosed configured-hook failure follows Hook Failure Recovery; denial, uncertain ownership/side effects and committed-content mismatch retain their stop. Ask only for a concrete missing decision after safe diagnosis, preserving the denial and recurrence rules.
Report observed state and continue independent authorized checks. When recovery succeeds, resume the active workflow from its first unmet checkpoint. Retain the reviewed message in the conversation, not a recovery draft file.

Hook Failure Recovery¶

A failing configured hook blocks the commit until repaired; it does not end already-authorized root-cause work. This applies both to an explicit pre-commit check and a hook invoked by Git. A tool permission denial is not a source-check failure. Read-only review may use the diagnosis and comparison steps below, but gains no source/config repair authority.

Preserve the exact command, exit status, diagnostic, hook/config revision, environment and source snapshot. Inspect HEAD, branch, index blobs/modes, worktree and operation state against pre-command evidence; hooks can edit files before failing. Resolve uncertain ownership or side effects before any mutation. Do not assign the problem to a maintainer merely because the failing file was unchanged or the dependency is installed.
Investigate the root cause before repair: record supporting evidence, a falsification check and a rejected alternative. Distinguish a source defect, declared dependency compatibility defect, missing prerequisite, command error and actual permission denial. For PR work, apply PR and target hook comparison. An accepted dependency version missing required exports is a compatibility defect to investigate, not proof that the environment alone is wrong.
Apply the smallest root fix within the existing authorized scope, including an authorized source or hook-configuration correction. Preserve the check's intended coverage and assertions. Never skip or disable the hook, suppress a real defect, weaken the gate, change dependency versions speculatively or rewrite history to obtain a commit. Read-only scope, another repository, dependency installation, protected-state changes and missing capabilities retain their own authority boundaries. When repair needs one of these, finish permitted diagnosis and ask only for that specific missing decision; continue unrelated authorized work. Retain recurrence and retry stops.
Rerun the same configured hook on the corrected source and the affected gates; a justified configuration repair must still exercise the original failing case. Retain before/after results, refresh invalidated source receipts and required fresh independent review, and prove the final reviewed source matches current bytes. A passing target check, parent inspection or snapshot exception never substitutes for the repaired PR hook passing.
Resume the original uncreated commit under existing commit authorization after rechecking destination, ownership, HEAD, operation state and index. An index containing only this unit's proven previously staged content may remain staged; compare its paths, blobs and modes with retained staging evidence, not path names alone. Accept a hook's own index change only when its exact effect and owned scope are established and reviewed. Preserve unrelated staged entries and stop before staging if any remain or attribution is uncertain. After a repair, show the refreshed exact owned paths and message, inspect the new diff, then stage only reviewed repaired content and commit through the ordinary owning command and post-commit proof. If staged content is already the exact refreshed reviewed content, run only the commit segment. A commit that already exists is verified, never replayed or amended; merge commits retain the separate parent/tree proof. Recovery does not grant a new commit unit or expand scope, and an explicit no-commit or wait still controls.

PR and target hook comparison¶

PR review and remediation require the configured pre-commit checks to pass on the PR. When a hook fails, also run the configured hook set on the exact collected target revision and retain per-hook PR/target results. Reuse still-current equivalent evidence when available. Use isolated disposable source copies or worktrees for checks that may autofix files; preserve the invoking checkout, target branch and source snapshots, record before/after changes, and never treat hook-modified review inputs as the original revision. Actual filesystem/network grants and dependency-installation boundaries still apply; an unavailable run remains unverified with its exact prerequisite.

Record both commit IDs, hook versions/configuration, checker environment, commands and equivalent file-selection rules. Run each revision's declared configuration; if the PR changes hooks, dependencies or selection, isolate those differences before claiming a source regression, with an additional controlled same-configuration comparison when feasible. Do not silently substitute target configuration for the required PR gate. Target pass plus PR fail is a regression signal requiring causal diagnosis. Both fail requires investigating the shared baseline/environment cause and any additional PR-specific failures; neither failure is waived. Target fail plus PR pass may show a fix, but does not establish its cause by itself. Incompatible environments, missing comparison inputs or non-equivalent selections keep causal attribution inconclusive; never label them a passing gate or confirmed PR regression.

Required User-Facing Commit Summary¶

Identify the local branch and absolute checkout path containing those commits, with a clickable checkout link. If a separate worktree was used, name the invoking checkout and its branch separately; scope clean, staged, unstaged and untracked claims to inspected Git status for that checkout. Distinguish local commits, remote publication and report promotion; one does not establish either of the others.

After creating or describing commits, report each commit separately with its hash and title, then concise bullets grouped by:

Behavior: what changed and user-visible or methodological impact.
Affected surfaces: principal components, workflows, or packages changed; do not dump unexplained filename list.
Verification: concise final change-specific tests, lint, build, package, or manifest checks and their results; omit exploratory, repeated, superseded, and unrelated checks.
Residual limits: skipped gates, warnings, deferred work, or remaining uncertainty; state none known when verified and no material limit remains.

For multiple commits, also state why the boundary exists. The user-facing summary may condense the commit body, but it must preserve every material behavior, impact, verification result, and residual limit. Never claim a check passed without concrete execution evidence.

Merge Commit Proof¶

Before committing, require a task-owned merge, as defined in Local merge approval, with no unmerged entries. Review every staged change against the recorded pre-merge HEAD, including clean merged-in target paths; the approved path set is the full first-parent change set, not only resolved conflicts. Unrelated staged entries stop the commit without unstaging or discarding them. Record the ordered intended parents from pre-merge HEAD and MERGE_HEAD. After that review of the staged index, and before the owning command, capture the reviewed index tree with git write-tree. The reviewed merge paths are already staged, so the owning command for a merge commit is rtk git commit --cleanup=verbatim -m <message> alone; never stage again after capturing the tree. Any later index change, such as re-staged worktree drift or a hook mutation, then fails the tree check below.

After committing, require git rev-list --parents -n 1 HEAD to match the recorded parents in order, git rev-parse HEAD^{tree} to equal the reviewed index tree, and git diff --no-renames --name-only -z <pre-merge-head> HEAD -- to equal the complete reviewed path set. Preserve existing message/trailer checks and branch receipts. A differing tree, parent or path set fails verification; no automatic amend, reset or history rewrite is authorized.

Apply Worktree lifecycle for remediation: prominently identify the current delivery checkout and branch, link its delivery evidence, and distinguish a historical temporary source from the current destination. Announce isolation before source work; return finished committed or uncommitted work to the invoking checkout unless explicitly worktree-only. Incomplete delivery stays explicit even when commits exist.

For a selected remediation commit mode, inspect source and delivery checkout status against the complete owned inventory before delivery and again before final output. All authorized task-owned edits, new files and deletions must be in the intended commits, with no task-owned staged, unstaged or untracked residue. Preserve unrelated baseline changes. Residue prevents task completion; diagnose unexpected hook/concurrent changes before any further mutation, retain real hashes and report exact remaining paths. Failed verification alone does not cancel an explicit local snapshot request.