commit · diff
git:20260822.f73c29d to git:20260823.6b8fa14
4 added, 2 removed. Audit A to A.
---
name: commit
description: Stage, commit, push, open a PR, and merge to main. Use ONLY on explicit commit intent — user says "commit", "ship it", "push this", "open a PR", "merge to main", "let's commit this", or prefixes with `/commit`. Do NOT auto-invoke on vague end-of-task phrases ("we're done", "wrap up") — those require explicit confirmation first. Runs the standard commit-PR-merge cycle; never force-pushes or skips hooks.
argument-hint: "[optional: commit message]"
allowed-tools: ["Bash", "Read", "Glob", "Agent", "Task"]
---
# Commit, PR, and Merge
Stage changes, verify quality gates, commit with a descriptive message, create a PR, and merge to main.
## Steps
### Step 0: Quality Gate (Pre-Commit)
**Run before branching.** For every changed `.qmd`, `.tex`, or `.R` file that has quality rubrics, run:
```bash
python3 scripts/quality_score.py <changed-file-paths>
```
- If any file scores below **80**, halt and report the findings. The user must either fix the issues or explicitly override with phrases like *"commit anyway"* or *"skip quality gate"*.
- If all files score 80+, continue.
Spawn the **verifier** agent (via the `Agent` tool with `subagent_type=verifier`) to run compilation/render checks on the changed files. Report pass/fail before committing.
### Step 0b: Consistency Gate (Pre-Commit)
- **Runs unconditionally.** The full backtest suite — all eight gates (surface-sync count claims like `"18 agents, 60 skills, 36 rules, 7 hooks"` and marked tables, skill integrity, model currency, links, spec conformance, staleness, repo hygiene, derived counts):
+ **Runs unconditionally.** The full backtest suite — all ten gates (surface-sync count claims like `"18 agents, 60 skills, 37 rules, 8 hooks"` and marked tables, skill integrity, model currency, links, spec conformance, staleness, repo hygiene, derived counts, ledger coverage, hook battery):
```bash
./scripts/backtest.sh
```
- **Exit 0:** all gates green — continue.
- **Nonzero:** at least one gate is red — print its output and halt. Fix, then re-run. Do NOT proceed past this gate on a red result, even with "commit anyway" — count drift alone produced PRs #70, #76, and #78.
### Step 0c: Passport Check (Pre-Commit)
- If the diff touches a manuscript (`.tex`/`.qmd`) that has a passport in `quality_reports/passports/`, or any `source_file` a passport lists, read that passport: a load-bearing claim with `status: FAIL` or `STALE` is a **must-fix** — halt, name the claim, and point at `/audit-reproducibility` (or the stale script) before committing. Skip silently when no passport exists.
+ If the diff touches a manuscript (`.tex`/`.qmd`) that has a passport in `quality_reports/passports/`, any `source_file` a passport lists, or any file a claim declares as a display (its `location:`, or an `appears_in` `path:`), read that passport: a load-bearing claim with `status: FAIL` or `STALE` is a **must-fix** — halt, name the claim, and point at `/audit-reproducibility` (or the stale script) before committing. A touched display triggers the check for the same reason a touched script does: editing one artifact's copy of a number desynchronizes it from that number's other displays — the supplement or deck holding the same value was not necessarily updated in the same commit. Skip silently when no passport exists.
### Step 1: Check current state
```bash
git status
git diff --stat
git log --oneline -5
```
### Step 2: Create a branch
```bash
git checkout -b <short-descriptive-branch-name>
```
### Step 3: Stage files
Add specific files (never use `git add -A`):
```bash
git add <file1> <file2> ...
```
Do NOT stage `.claude/settings.local.json` or any files containing secrets.
### Step 4: Commit with a descriptive message
If `$ARGUMENTS` is provided, use it as the commit message. Otherwise, analyze the staged changes and write a message that explains *why*, not just *what*.
+
+ **The subject line states what is TRUE AFTER the commit** — a plain sentence about behavior that a reader could go and test. *"Fixed review feedback"* and *"Updated the checker"* narrate your afternoon and tell a reader nothing; *"The parity gate refuses a fixture whose hash is unregistered"* is a claim they can check against the code. Process narration — which review round it came from, who asked, how many attempts it took — belongs in the body if it belongs anywhere. The body still carries the *why*; the subject carries the claim.
```bash
git commit -m "$(cat <<'EOF'
<commit message here>
EOF
)"
```
### Step 5: Push and create PR
```bash
git push -u origin <branch-name>
gh pr create --title "<short title>" --body "$(cat <<'EOF'
## Summary
<1-3 bullet points>
## Test plan
<checklist>
🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"
```
### Step 6: Merge and clean up
```bash
gh pr merge <pr-number> --merge --delete-branch
git checkout main
git pull
```
### Step 7: Report
Report the PR URL and what was merged.
## Important
- **Never skip Step 0.** Quality gates catch broken compilation, bad citations, and hardcoded paths before they reach `main`. If the user insists on skipping, record their override reason in the commit message.
- Always create a NEW branch — never commit directly to main.
- Exclude `settings.local.json` and sensitive files from staging.
- Use `--merge` (not `--squash` or `--rebase`) unless asked otherwise.
- If the commit message from `$ARGUMENTS` is provided, use it exactly.