path: root/claude-rules/commits.md

# Commit Rules

Applies to: `**/*`

## Author Identity

All commits are authored as the user (repo owner / maintainer), never as
Claude, Claude Code, Anthropic, or any AI tool. Git uses the configured
`user.name` and `user.email` — do not modify git config to attribute
otherwise.

## No AI Attribution — Anywhere

Absolutely no AI/LLM/Claude/Anthropic attribution in:

- Commit messages (subject or body)
- PR descriptions and titles
- Issue comments and reviews
- Code comments
- Commit trailers
- Release notes, changelogs, and any public-facing artifact

This means:

- **No** `Co-Authored-By: Claude …` (or Claude Code, or any AI) trailers
- **No** "Generated with Claude Code" footers or equivalents
- **No** 🤖 emojis or similar markers implying AI authorship
- **No** references to "Claude", "Anthropic", "LLM", "AI tool" as a credited contributor
- **No** attribution added via template defaults — strip them before committing

If a tool, template, or default config inserts attribution, remove it. If
settings.json needs it, set `attribution.commit: ""` and `attribution.pr: ""`
to suppress the defaults.

## Commit Message Format

Commit messages follow the [Conventional Commits](https://www.conventionalcommits.org/) spec.

### Structure

    <type>[optional scope]: <description>

    [optional body]

    [optional footer(s)]

### Types

- `feat:` — new feature (correlates with MINOR in SemVer)
- `fix:` — bug fix (correlates with PATCH in SemVer)
- `refactor:` — code restructuring, no behavior change
- `perf:` — performance improvement
- `test:` — adding or updating tests
- `docs:` — documentation only
- `style:` — formatting, whitespace, missing semicolons (no code-behavior change)
- `build:` — build system or external dependencies
- `ci:` — CI configuration and scripts
- `chore:` — anything else: tooling, meta, housekeeping

The Conventional Commits spec doesn't mandate the type list. Add a new type only when the existing ones genuinely don't fit and the team will agree on what it means.

### Scope

A scope MAY follow the type, in parentheses, naming the affected area of the codebase: `feat(parser): add ability to parse arrays`. Use a single noun.

### Breaking changes

Either append `!` after the type or scope, or include a `BREAKING CHANGE:` footer (uppercase — required). Both at once is fine and adds detail. `!` alone is enough.

    feat!: drop support for Node 6

    BREAKING CHANGE: uses JavaScript features not available in Node 6.

### Subject line

Imperative mood. ≤72 characters. No trailing period. The full subject is `<type>[scope]: <description>` — the 72-char limit covers the whole thing.

### Body

Optional. Begins one blank line after the subject. Free-form, multiple paragraphs allowed. Don't 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 same soft-wrap rule applies to PR bodies.

Skip the body when the subject line covers the change.

### Footers

Optional. One blank line after the body. One per line. Format: `Token: value` or `Token #value` — the git trailer convention. The token uses `-` in place of whitespace (e.g. `Reviewed-by`, `Refs`, `Acked-by`). `BREAKING CHANGE:` is the one token allowed to contain a space, and `BREAKING-CHANGE:` is treated as a synonym.

### How to write the message

Write commit messages as if you're explaining the change to someone debugging a failure six months from now. Focus on what changed and why, not the play-by-play of how you typed it. Short imperative summaries like "Validate input before processing" age better than diary-style notes.

The body, when you need it, is where context belongs — the constraint, bug, or tradeoff that forced the change. Over time the body becomes a lightweight decision log, which is more valuable than perfectly formatted messages.

Commit messages describe what changed and why, not the process that produced the change. Don't 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.

### Examples

**Subject only:**

    docs: correct spelling of CHANGELOG

**With scope:**

    feat(lang): add Polish language

**With body and footer:**

    fix: prevent racing of requests

    Introduce a request id and a reference to the latest request. Dismiss incoming responses other than from the latest request.

    Remove timeouts which were used to mitigate the racing issue but are obsolete now.

    Refs: #123

**Breaking change with `!`:**

    feat(api)!: send an email to the customer when a product is shipped

**Breaking change in footer:**

    feat: allow provided config object to extend other configs

    BREAKING CHANGE: `extends` key in config file is now used for extending other config files.

## Voice and Focus

Applies to commit bodies, PR descriptions, and PR comments (review replies, follow-up notes, thread responses).

**Write as if to a colleague.** The reader is a teammate who'll see this in `git log`, a PR feed, or a Linear thread. "I" is allowed where natural. Don't sound abstract — name the file, the function, the constraint, the symptom. Press-release voice ("This change improves...") and committee voice ("It is recommended that...") both come out. The message has to read like one engineer talking to another, not like a generated artifact.

**No felt-experience narration.** Don't tell the reader how the change will feel or how often you'll use it. Phrases like "I'll feel this every time I commit", "this will be a relief", "I'm excited about" — these read as performance, not communication. State what changed and let the reader decide what to do with it.

**Don't noun-ify verbs.** "The ask", "a learn", "a reveal", "the spend", "a build" — use the real noun: "the request", "the lesson", "the finding", "the budget", "the system". Verb-as-noun reads as corporate-speak and makes the sentence feel performed.

**No sentence fragments in prose.** Every prose sentence needs a subject and a verb. "Two changes." or "Fix incoming." or "Body as decision log." read as bullet-list shorthand even when they're standing alone in a paragraph. Bullets and headings can be fragments — prose sentences cannot.

**"I" is the author, not the user.** First person is for what *I* did or decided in this commit ("I dropped the legacy fallback because..."). It's not for describing how the software or rule behaves for whoever uses it next. "The dialog only opens if I ask" is wrong when the rule is read by someone else — that "I" becomes ambiguous. Use third-person or passive for behavior: "opens on request", "opens when asked", "opens when the user invokes it". Code and systems are the actor; "I" stays for decisions.

**First person where it fits.** When the subject is you or a decision you made, use "I" ("I added X", "I kept the parameter as `Any` because..."). When the subject is a team decision or shared rationale, "we" fits. When another author's prior work is the subject, name them ("Kostya's PR #116 did X"). Third-person constructions like "This PR introduces X" or "This change restores Y" read as press-release self-narration. The commit *is* the change, so don't announce it. Code and systems can stay third-person when they're the actor ("the guard rejects...", "the serializer returns...") — first person is for describing what you did or decided, not for narrating how the code behaves.

**Brief. Terse is preferred.** A one-sentence body beats a paragraph saying the same thing. If the subject line covers it, skip the body entirely. Cut every clause that restates what the diff or the PR card already shows. Length is not a proxy for care. Rhetorical padding ("worth noting", "it's important to understand") always comes out; keep what a reader will actually use.

**Follow-up approvals stay terse.** A re-review that just confirms prior CHANGES_REQUESTED feedback got addressed should be `Approved.` and nothing more. The fixes are visible in the diff and in the prior review thread, so restating them adds noise. The first round of substantive review gets a real comment. Subsequent sign-offs after fixes do not. Counts as a trivial one-liner under the Step 2 exception, so the draft-file flow can be skipped.

**Kind.** PR comments and review replies are directed at a specific person. Acknowledge them when it fits ("thanks for the review") without pouring it on. When you disagree or push back, frame it as your read rather than a correction ("I think...", "my read was...", "did you mean X?"). Leave room for the other person to have seen something you didn't. A polite question beats a defensive explanation. Kindness is free and makes the next review cheaper.

Focus on what was wrong and what was corrected. Not the mechanics.
Readers skimming `git log` or a PR want the before-state, the
after-state, and the reason. They don't need a TypeScript-variance
lesson, a compiler-inference walkthrough, or a trip through an API's
internals. Keep the "why" to one sentence unless a subtle invariant
genuinely needs more.

Don't stack technical terms. A sentence that chains three or more type
signatures, API names, or compiler concepts reads as a jargon wall.
Break it into shorter sentences and translate to reader-facing
language. "The mock returns `Promise<Mission>`, so the resolver's
argument is `Mission`, not `unknown`" beats the full inference chain
that produces that signature. Keep the terms a reader will grep for,
drop the ones that name compiler internals.

## Content scope for public artifacts

PR descriptions, Linear ticket bodies, and PR review comments are
visible to the team and to anyone with read access to the repo or
project. Don't mention:

- Local file paths on the user's personal machine.
- Private repos by name (e.g. a personal notes repo, a career repo).
- Personal tooling or workflow the team doesn't share.
- Anything a teammate couldn't reproduce or act on from public sources.

Rule of thumb: if a teammate couldn't find the referenced thing without
the user's help, don't reference it.

**Personal-tooling files.** The rules and skills that drive my workflow are private. Treat the following as personal tooling and don't cite them as authority in any commit message, PR description, PR comment, Linear ticket, or other shared artifact:

- Anything in `~/code/rulesets/claude-rules/` (`commits.md`, `testing.md`, `verification.md`, `subagents.md`, and any others added later).
- Any `CLAUDE.md`, `AGENTS.md`, or similar project-level rules file.
- Anything under `~/.claude/`, project `.claude/`, or project `.ai/`.
- Any skill definition (`SKILL.md`) under `~/code/rulesets/`.

Don't write "per `testing.md`, integration tests must hit a real DB" or "the rule in `commits.md` says…". State the reason directly: "integration tests hit a real DB so the migration is exercised end-to-end." The personal rule doesn't matter to a teammate. The reason does.

Edge case: when one of these files *is* the change (a commit in the rulesets repo, an edit to a project's `CLAUDE.md`), describe what changed and why without invoking the wider personal-rules layer around it. The commit can absolutely say "tighten testing rule for legacy code". It shouldn't say "per the personal-rules layer this file is loaded into…".

Different artifact types carry different content. Don't duplicate.

**PR descriptions:** four sections, in order.

1. **Problem** — what's wrong, with enough detail that a teammate can
   recognize the same failure mode in their own work.
2. **Fix** — what changed.
3. **Why this fixes it** — causal link, one or two sentences.
4. **How it was tested** — skip for proposals, specs, or discussions;
   required for shipped fixes.

The PR is the technical artifact. It carries the detail.

If the project's publishing overlay defines a ticket system, see it for
ticket-body conventions (a ticket body is typically just the Problem and
Fix, with the causal why and test verification left to the PR).

**PR review comments** are conversational and don't follow this
structure — they follow the Voice and Focus rules above.

Verbose preambles, motivational language, and context unrelated to the
problem belong out. Same conciseness pressure as commit-message bodies.

## 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 three steps, in
order.

### Step 0: pre-flight reconcile (mandatory)

Before reviewing the diff, fetch from the remote and reconcile against the
upstream of the current branch. Reconciliation can change the working state
when a rebase brings in upstream commits that touch staged files, and that
would invalidate Step 1's review. Handling drift first means the review and
the commit message describe the post-reconcile state.

1. Fetch all remotes:

       git fetch --all --prune

2. If the current branch has no upstream (new branch, never pushed), skip
   to Step 1 — there's nothing to reconcile against, and the first push
   sets the upstream.

3. Otherwise, check divergence against `@{u}`:

       git rev-list --left-right --count @{u}...HEAD

   Output is `<behind>\t<ahead>`. Decide based on the pair:

   - **0 behind, anything ahead** — no-op. Continue to Step 1.
   - **Behind only, clean tree** — fast-forward: `git merge --ff-only @{u}`.
   - **Behind only, dirty tree** — surface to the user. Don't auto-stash or
     auto-merge. Offer to commit or stash first, or skip the reconcile and
     proceed knowing the push may need attention later.
   - **Diverged (behind AND ahead)** — surface to the user. Ask whether to
     rebase the local commits onto upstream (default for feature branches),
     merge the upstream branch in (rare; preserves both lines), or skip and
     proceed with the divergence. Don't auto-rebase.

4. **PR flow only.** Also fetch the base branch (usually `main`) and check
   whether the feature branch's base is behind. Surface this informationally;
   don't auto-rebase the feature branch without asking. The "X commits
   behind base" badge on the PR is a follow-up decision, not a reason to
   block publish.

The startup workflow's `git fetch --all --prune` doesn't substitute for
Step 0. Upstream can advance during a long session, especially across
machines or with teammates pushing in parallel. Run Step 0 every time the
publish flow starts.

### 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

**Voice patterns and the approval gate are two independent decisions.** Don't bundle them.

*Voice patterns are always personal for publish artifacts.* Commit messages, PR titles + bodies, and PR review comments all go out under the user's name, so they always run through `/voice personal` (the full pattern walk — general + Craig's-voice + the artifact-mechanics patterns: first-person rewrite, public-artifact scope flag, praise/correction asymmetry, finding stems), regardless of whether `.ai/` is tracked. These three are personal-voice artifacts by definition — the skill's personal mode exists for exactly them. Pattern #39 (public-artifact scope flag) matters *most* on team-visible artifacts, so it must never be skipped on a PR comment or PR body. There is no "general-voice mode" for publish artifacts.

*The approval gate is the only thing `.ai/`-tracking decides.* Before drafting, run this command:

```
git ls-files :/.ai/ 2>/dev/null | head -1
```

The `:/` pathspec anchors the search to the repo root, so the command works from any subdirectory. Without it, running from a subdir returns no matches even when `.ai/` is tracked at the repo root, which silently misclassifies the project.

- **No output** — `.ai/` is gitignored, missing, or empty (the user's personal repos). **Gate applies**: write to `/tmp`, run `/voice personal`, print inline, ask approve / request changes / open in editor, then publish only on explicit approval.
- **Any output** — one or more files under `.ai/` are tracked (a shared / team repo). **Gate skipped for velocity**: write to `/tmp`, run `/voice personal`, print inline, publish immediately.

Either way the draft runs through `/voice personal` first. The subflows below describe the full gated path. For the gate-skipped path, run the same `/voice personal` pass, then collapse the "Ask: approve, request changes, or open in editor" step — the draft prints inline and the publish step runs immediately afterward.

**For commit messages:**

1. Write the proposed message to `/tmp/commit-<short-slug>.md`.
2. Run `/voice personal` on the file. Always. The skill walks its full pattern list covering signs of AI writing, universal good-writing rules (Strunk & White, Orwell, Plain English, Garner), and Craig's voice patterns (first-person rewrite, semicolons → periods/commas, contractions, sentence-split on conjunctions, felt-experience cut, sentence-fragment rewrite, terse cut for rhetorical padding, no-emphasis-formatting, public-artifact scope flag, praise/correction asymmetry, finding stems). The commit subject line stays imperative per Conventional Commits — `/voice personal` rewrites the body, not the subject. Skip the pass for purely mechanical commits (a chore version bump, a typo fix) where the subject alone carries the message.
3. Print the final draft inline in the terminal. Every line, exactly as it'll be committed. No truncation, no summary. State that the skill ran (e.g. "/voice personal — full pattern walk"). If pattern #39 (public-artifact scope) flagged anything, surface those warnings; the user resolves them manually.
4. Ask: approve, request changes, or open in editor. Wait for an explicit answer. Do not open the file in `emacsclient` (or any editor) by default — print first, edit only if asked.
   - **Approve** → commit with `git commit -F /tmp/commit-<short-slug>.md`.
   - **Request changes** → make them, re-run `/voice personal`, re-print inline, ask again.
   - **Open in editor** → only if the user asks. `emacsclient -n /tmp/commit-<short-slug>.md`. After the editor closes, re-read the file, re-print the contents inline, and ask again.

**For PR descriptions:**

1. Write the title as line 1 and the body below it to `/tmp/pr-<slug>.md`. **Title format:** the conventional-commit subject (`refactor: remove dead if-count-is-not-None check in admin`). If the project defines a publishing overlay with a ticket system, follow it for the ticket suffix in the title and the cross-link line in the body (see the overlay).
2. Run `/voice personal` on the file. The PR title stays imperative per Conventional Commits — `/voice personal` rewrites the body, not the title.
3. Print the final draft inline in the terminal. Title on line 1, blank line, then body — exactly as it'll be posted. State that the skill ran. Surface any pattern #39 (public-artifact scope) warnings.
4. Ask: approve, request changes, or open in editor. Wait for an explicit answer. Do not open the file in `emacsclient` (or any editor) by default.
   - **Approve** → continue to step 5.
   - **Request changes** → make them, re-run `/voice personal`, re-print inline, ask again.
   - **Open in editor** → only if the user asks. `emacsclient -n /tmp/pr-<ticket-or-slug>.md`. After the editor closes, re-read the file, re-print inline, ask again.
5. 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. Add `--reviewer <user[,user...]>` in the same call when you already know who should review.
6. Request reviewers on the new PR if you didn't pass `--reviewer` at create time. Use `gh pr edit <N> --add-reviewer <user>`. If the repo has a `CODEOWNERS` file, GitHub auto-suggests based on touched paths. Still issue the explicit request so the reviewer gets notified. Pick reviewers per the team's convention for the area touched (often documented in the per-repo `CLAUDE.md`). For follow-up PRs, consider tagging the parent PR's author if their context would help. PRs without a human reviewer request stall — "checks passed" is not a substitute for review.
7. **Project publishing overlay (if present).** If the project defines a publishing overlay — a `publishing-<team>.md` rule loaded from its `.claude/rules/` — run its post-create steps now: ticket cross-linking, ticket-state moves, and any other tracker integration it specifies. A project with no overlay skips this; the PR is already open and reviewers are requested, which is the complete universal flow.

**For PR review comments and replies (review verdicts, threaded discussion, follow-up notes on someone else's PR or your own):**

Pick the shape first. Most reviews are Shape 1.

- **Shape 1 — Single review** (verdict + summary body + 0+ inline pins). The default for any post that carries a verdict (`APPROVE`, `REQUEST_CHANGES`, `COMMENT`), even when the verdict has no line-specific findings. One `gh api` call posts the summary, every inline pin, and the verdict together. review notification fires once for `APPROVE` or `REQUEST_CHANGES`.
- **Shape 2 — Issue-thread comment** (no verdict). General PR discussion, not a review. No inline pins. No review notification.
- **Shape 3 — Reply on an existing inline thread**. Responding to a specific prior reviewer comment. Threads under that comment. No review notification.

**Inline threshold for Shape 1.** Any finding that names a `path:line` belongs as an inline comment pinned to that line. Cross-cutting observations (verdict rationale, "third PR with the same pattern", overall test-coverage gaps that don't pin to one place) stay in the summary body. There's no "fold one inline into the summary" exception — a single line-specific finding still goes inline.

**Shape 1: Single review (bundled summary + inline)**

1. Identify findings, split into **inline-eligible** (each names a specific `path:line`) and **summary-only** (cross-cutting). Decide the verdict.

2. Write one concatenated draft to `/tmp/pr-<N>-review.md` with explicit separators:

   ```
   === SUMMARY ===
   <verdict summary body>

   === INLINE path=frontend/src/foo.tsx line=440 ===
   <inline body 1>

   === INLINE path=frontend/src/bar.tsx line=137 ===
   <inline body 2>
   ```

   The separator format is exactly `=== SUMMARY ===` and `=== INLINE path=<path> line=<n> ===`. The summary block is mandatory even for verdict-only reviews. Inline blocks are zero-or-more.

3. Run `/voice personal` on the file once. The skill walks its full pattern list across every block at the same time. The separators stay intact because they aren't prose.

4. Print the final draft inline in the terminal. Every block, exactly as it'll be posted, with its separator header. State that the skill ran (e.g. "/voice personal — full pattern walk across summary + 3 inline"). Surface any pattern #39 warnings.

5. Ask: approve, request changes, or open in editor. Wait for an explicit answer. Do not open the file in `emacsclient` (or any editor) by default.
   - **Approve** → continue to step 6.
   - **Request changes** → make them, re-run `/voice personal` on the whole file, re-print inline, ask again.
   - **Open in editor** → only if the user asks. `emacsclient -n /tmp/pr-<N>-review.md`. After the editor closes, re-read, re-print inline, ask again.

6. Split the file on the separator lines and post in **a single** `gh api` call:

   ```
   gh api repos/<owner>/<repo>/pulls/<N>/reviews \
     --hostname <ghe-host-or-omit> \
     -F event=REQUEST_CHANGES \
     -F body="<summary block>" \
     -F "comments[][path]=<path1>" \
     -F "comments[][line]=<line1>" \
     -F "comments[][body]=<inline 1>" \
     -F "comments[][path]=<path2>" \
     -F "comments[][line]=<line2>" \
     -F "comments[][body]=<inline 2>"
   ```

   `event` is one of `APPROVE`, `REQUEST_CHANGES`, `COMMENT`. The `comments[]` array can be empty for verdicts with zero line-specific findings — the call still uses the same endpoint. Pass `--hostname` for non-`github.com` hosts (a project's publishing overlay names its host when it's a GitHub Enterprise instance).

7. Verify the review landed. `gh api repos/<owner>/<repo>/pulls/<N>/reviews --hostname ...` returns the latest review with bundled inlines. Confirm `state` matches the verdict and the inline count matches what was posted.

8. **Project review-notification overlay (if present).** If the project defines a publishing overlay with a review-notification step (e.g. a Slack ping to the PR author), run it now — but only for `APPROVE` and `REQUEST_CHANGES` verdicts. The overlay owns the channel, the message format, the author-mention lookup, and the threading. A project with no overlay skips notification entirely. `COMMENT` verdicts and Shapes 2-3 below never notify, overlay or not.

**Shape 2: Issue-thread comment (no verdict)**

Use when the post is informal discussion that shouldn't appear as a review verdict (e.g. "I'd like to discuss the X approach before you continue").

1. Write the proposed comment to `/tmp/pr-<N>-comment.md`.
2. Run `/voice personal`.
3. Print inline, ask approve/changes/edit, gate as in Shape 1 step 5.
4. Post: `gh pr comment <N> --body-file /tmp/pr-<N>-comment.md`.
5. Verify: `gh api repos/<owner>/<repo>/issues/<N>/comments`.
6. No review notification.

**Shape 3: Reply on an existing inline thread**

Use when responding to a specific prior reviewer comment.

1. Find the parent comment ID: `gh api repos/<owner>/<repo>/pulls/<N>/comments`.
2. Write the reply to `/tmp/pr-<N>-reply-<comment-id>.md`.
3. Run `/voice personal`.
4. Print inline, ask approve/changes/edit, gate as in Shape 1 step 5.
5. Post: `gh api repos/<owner>/<repo>/pulls/<N>/comments -F in_reply_to=<comment-id> -F body="$(cat /tmp/pr-<N>-reply-<comment-id>.md)"`.
6. Verify in the same `comments` list.
7. No review notification.

**Approve does not authorize a merge.** Reviewing a PR never authorizes merging it. Anything in `## Merge Strategy` below applies only to merges *you* are about to perform on your own branches — and even then, the merge needs its own explicit user confirmation per the rules there. A project's publishing overlay may add a team merge practice (e.g. approve-then-author-merges, where the review notification hands the merge decision to the PR author); that's an overlay concern, not a global one.

**Exception:** trivial one-liners the user dictated verbatim in the
conversation (e.g. "commit this as `chore: bump version`", "reply just
'thanks for the review'") can skip the draft-file step in Step 2.
`/review-code` in Step 1 still runs when it applies; Phase 0 of that skill
handles trivial diffs, and acknowledgment-only replies don't need it at all.

**Single-skill gate.** Each of the three subflows above runs `/voice personal` before printing the draft — the full pattern walk covering AI-writing signs, universal good-writing rules, Craig's voice patterns, and the artifact-mechanics patterns (first-person rewrite, public-artifact scope flag, praise/correction asymmetry, finding stems). Publish artifacts (commits, PR titles + bodies, PR review comments) always use personal mode; the `.ai/`-tracking check at the top of Step 2 decides only whether the approval gate fires, not which patterns run. Running the skill is mandatory; the printed draft must have been through it. When the user asks mid-flow for "the voice pass" on an in-progress draft, that means re-run the full pattern walk — not a subset. Always state that the skill ran when announcing the printed draft (e.g. "/voice personal — full pattern walk"). Skipping the pass without flagging it is a defect. The terse/omit-needless-words cut (pattern #38) is the *last* thing the skill does before the draft is printed: read each sentence and cut it in half, keeping only what changes meaning. The draft the user first sees must already be terse — if they have to ask for an Orwell pass after seeing it, the pass was skipped.

**If `/voice` is unavailable.** The skill should be installed (it ships with rulesets), but a fresh or partial environment may not have it. Don't let that block the publish, and don't skip the discipline silently. Walk the same patterns inline — they're documented in the skill, and the publish flow already names which ones matter (first-person rewrite, semicolons → periods/commas, contractions, sentence-split, felt-experience cut, fragment rewrite, terse cut, the pattern #39 public-artifact scope flag, plus the AI-writing and good-writing passes). Then state that the skill was unavailable and the pass was applied by hand (e.g. "/voice unavailable — patterns walked inline"). The gate is the pattern walk, not the tooling; the skill is the convenient way to run it, not the only way. Flag the missing skill so it gets installed.

### 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.

## Merge Strategy

- *Squash-merge is the default* for feature branches. It avoids carrying
  WIP and fix-up commits into the target branch history and produces one
  logical change per merge.
- State the planned merge approach (squash, rebase, or merge commit) and
  the target branch *before* pushing or merging. Wait for explicit user
  confirmation before `git push`, `gh pr merge`, or any equivalent. The
  Review and Publish flow above approves the *content*; merge strategy is
  a separate decision that needs its own confirmation.
- *Pre-push reconcile.* Right before `git push`, do one more
  `git fetch <remote> <branch>` and verify the local branch is still
  ahead-only against its upstream. If something landed between Step 0 and
  push (review and draft together can take several minutes, and another
  machine or teammate may push in that window), surface and resolve before
  the push command runs. Catching drift here is cheaper than recovering
  from a failed non-fast-forward push under publish-step pressure.
- Override the squash default only when there's a concrete reason: a
  clean per-commit review history the user has explicitly asked for, a
  multi-commit semantic narrative the team values, etc. Squash is the
  safe default; document why when deviating.

## Before Committing

1. Check author identity: `git log -1 --format='%an <%ae>'` — should be the user.
2. Scan the message for AI-attribution language (including emojis and footers).
3. Review the diff — only intended changes staged; no unrelated files.
4. Confirm staged files belong in the repo: nothing that the project's policy keeps untracked (the personal-tooling set in gitignore-mode projects), and in repos with a canonical/mirror split, the edit is on the canonical side — a mirror-only edit gets reverted by the next sync.
5. Run tests and linters (see `verification.md`).

## If You Catch Yourself

Typing any of the following — stop, delete, rewrite:

- `Co-Authored-By: Claude`
- `🤖 Generated with …`
- "Created with Claude Code"
- "Assisted by AI"

Rewrite the commit as the user would write it: concise, focused on the
change, no mention of how the change was produced.