docs(commits): add review-and-publish flow, tighten message conventions

Three additions to claude-rules/commits.md.

A new conventions section adds two rules. First, do not hard-wrap commit body lines. Let the renderer soft-wrap instead. Hard wraps shrink the visible width in web UIs and cause awkward mid-sentence breaks. Second, do not reference how the change was produced (code review, linting, test runs) in the message. The body is for the what and the why. The how belongs in the PR discussion.

A new Review and Publish section defines a two-step gate for every commit and PR. Step 1 runs /review-code against the change and blocks on Critical or Important findings unless the user overrides. Step 2 drafts the message to /tmp, opens it in the user's editor, runs the humanizer skill, and waits for explicit approval before committing or pushing. PRs also require a Linear cross-link line, a Linear comment with the PR URL after creation, and a status transition to Dev Review.

A short hook-level authorization note clarifies that the review-plus-approval flow is the authorization gate. Tools like git-commit-confirm should not add a second independent prompt once Step 2 has been approved.

1 files changed, 87 insertions, 0 deletions

diff --git a/claude-rules/commits.md b/claude-rules/commits.md
index 301c6ff..b8707c1 100644
--- a/claude-rules/commits.md
+++ b/claude-rules/commits.md
@@ -46,6 +46,93 @@ Conventional prefixes:
 Subject line ≤72 characters. Body explains the *why* when not obvious.
 Skip the body entirely when the subject line is self-explanatory.
 
+Do not hard-wrap body lines. Write each paragraph and each bullet as a
+single logical line and let the renderer (GitHub, Linear, `git log`) soft-
+wrap. Hard wraps shrink the visible render width in web UIs and cause
+awkward mid-sentence breaks. The subject-line limit still applies to line
+1. The same rule applies to PR bodies.
+
+Commit messages describe what changed and why, not the process that
+produced the change. Do not reference code review, linting, test runs, or
+other workflow steps in the body (e.g. "from local review," "review
+surfaced," "flagged by reviewer"). Reviewers and future archaeologists
+want the what and the why; how you got there belongs in the PR
+discussion, not the commit.
+
+## Review and Publish
+
+Commits and PRs are team-visible, permanent, and hard to amend once shared
+(especially after push or after a reviewer has replied). Before executing
+`git commit` or `gh pr create`, the change must pass a local code review
+*and* the message must be reviewed by the user. The flow has two steps, in
+order.
+
+### Step 1: local code review (mandatory)
+
+Run the `review-code` skill against the change:
+
+- Before a commit: `/review-code --staged`
+- Before a PR: `/review-code` (branch diff against `main` merge-base)
+- Before commenting on someone else's PR: `/review-code <PR#>`
+
+Surface **all** findings to the user: Critical, Important, and Minor.
+
+**Default block:** any Critical or Important finding stops the flow. Fix the
+issues and re-run `/review-code` until the diff is clean. Minor findings are
+shown but do not block.
+
+**Override:** the user can bypass the block with an explicit "proceed anyway"
+(or equivalent wording). Without the explicit override, do not proceed to
+Step 2.
+
+The `review-code` skill already has a Phase 0 eligibility gate that handles
+trivial and ineligible diffs (whitespace-only, revert with obvious
+justification, already-reviewed SHA). Trust that gate; there is no "trivial
+enough to skip review" exemption on top of it.
+
+### Step 2: draft, review, publish
+
+**For commit messages:**
+
+1. Write the proposed message to `/tmp/commit-<short-slug>.md`.
+2. Open it in the user's editor (e.g. `emacsclient -n /tmp/commit-<short-slug>.md`).
+3. Run the `humanizer` skill on the file. Always — commit messages get the same prose-review treatment as PR descriptions. After humanizing, re-scan the output and (a) rewrite dev-jargon fragments ("Empty X throws", "Hard throw not a clamp", "all green") as plain, brief, complete sentences a low- or mid-level engineer who is not a native English speaker can read without stumbling, and (b) replace semicolons with either a period or a comma. Few engineers use semicolons in prose. They make the writing feel unnecessarily literary.
+4. Stop and tell the user the draft is open for review. Wait for explicit approval.
+5. After approval, commit with `git commit -F /tmp/commit-<short-slug>.md`.
+
+**For PR descriptions:**
+
+1. Write the title as line 1 and the body below it to `/tmp/pr-<ticket-or-slug>.md`.
+2. The body must include a `Linear: [<TICKET-ID>](<linear-url>)` line so the
+   ticket and PR are cross-linked. If there is no ticket, state that
+   explicitly ("Linear: n/a") so reviewers know it was considered.
+3. Open it in the user's editor (e.g. `emacsclient -n /tmp/pr-<ticket-or-slug>.md`).
+4. Run the `humanizer` skill on the file. After humanizing, re-scan for dev-jargon fragments and rewrite them as plain, brief, complete sentences a low- or mid-level engineer who is not a native English speaker can read without stumbling. Replace semicolons with periods or commas. Few engineers use semicolons in prose.
+5. Stop and tell the user the draft is open for review. Wait for explicit approval.
+6. After approval, split the file on the first blank line and pass the title
+   and body to `gh pr create --title "..." --body "$(tail -n +3 <file>)"` (or
+   a heredoc) so formatting is preserved.
+7. After `gh pr create` returns a URL, post a comment on the linked Linear
+   ticket with the PR URL (use the Linear MCP `save_comment` tool, or open
+   the ticket manually if MCP is unavailable). This closes the ticket→PR
+   direction of the cross-link.
+8. Move the Linear ticket to the "Dev Review" status (use `save_issue` with
+   the Dev Review state ID, or the Linear UI). The ticket should not remain
+   "In Progress" once a PR is open against it.
+
+**Exception:** trivial one-liners the user dictated verbatim in the
+conversation (e.g. "commit this as `chore: bump version`") can skip the
+draft-file step in Step 2, but `/review-code --staged` in Step 1 still runs.
+
+### Hook-level authorization
+
+The Step 1 code review plus the Step 2 user approval together constitute the
+authorization gate for the publish action. No separate hook-level approval
+prompt is needed on `git commit`, `gh pr create`, `git push`, or their
+variants once Step 2 has been approved. If a hook is configured, rely on the
+flow above to be the source of truth; do not treat the hook as a second
+independent gate.
+
 ## Before Committing
 
 1. Check author identity: `git log -1 --format='%an <%ae>'` — should be the user.