Auto-commit at workflow gates

.claude/commands/next-step.md

@@ -125,9 +125,11 @@ Do **not** restate project conventions, coding style, build commands, or anythin
 
 **Issue-driven mode**: open the implementation prompt by noting the source issue inline — `Sourced from GitHub issue #NN ("<title>", <url>).` — then write the scoped prompt as usual. The issue reference lives in the prose, not a separate handoff field.
 
-End the implementation prompt with this standing instruction (verbatim):
+End the implementation prompt with these standing instructions (verbatim):
 
 > Before writing a plan, surface any remaining open questions and confirm scope with the user.
+>
+> When the work is done, commit your own changes locally (no push), following the commit conventions in CLAUDE.md. Commit only the files you changed — add them by path, never `git add -A`. If the tree holds changes you didn't make, surface them rather than committing them.
 
 Show the draft to the user for approval. Iterate if needed.
 

.claude/commands/pre-pr.md

@@ -6,10 +6,13 @@ This session is **fresh and separate** from the implementation session by design
 
 ```bash
 git diff main...HEAD --name-only
+git status --porcelain
 ```
 
 Capture the list of changed files. Use it as the scope for steps 3 and 4.
 
+Also record the `git status --porcelain` output as the **entry snapshot**. The tree should be clean here (the implementation session commits its own work). If it is already dirty, those are changes this session did not create — note them now; step 8 must not sweep them into the auto-commit.
+
 ## 2. Build & QA
 
 Run each CI job sequentially. **Capture only the last 40 lines + exit code, do not read the full output.** Stop on first failure.
@@ -104,11 +107,28 @@ Present a checklist summary:
 - [ ] Roadmap up to date
 - [ ] CI gaps surfaced: none / proposed (list them)
 - [ ] No upstream drift (or: /merge-main recommended)
+- [ ] Reconciliation edits committed
 ```
 
 Mark each item as pass ✓ or needs attention ✗ with details.
 
-## 8. Open PR (optional)
+## 8. Commit reconciliation edits
+
+Commit the documentation reconciliation edits this session made in steps 3–6 (architecture/feature docs, CLAUDE.md, README, the coding standard, and the roadmap). This is a local commit only — **no push**. Pushing happens, if at all, in step 9.
+
+First check the entry snapshot from step 1:
+
+- **If the tree was already dirty on entry** (changes this session did not create), **stop and surface** them: list those paths, state that the auto-commit is skipped so unrelated work isn't swept in, and let the user resolve it. The checklist above still stands on its own.
+- **Otherwise**, commit only the files this session edited. Add them by path — do not `git add -A`:
+
+```bash
+git add <files reconciled in steps 3–6>
+git commit -m '<message>'
+```
+
+Follow the repo's commit conventions from CLAUDE.md. Print a one-line summary of the commit (subject + files included). If nothing was reconciled (no edits this session), say so and skip the commit.
+
+## 9. Open PR (optional)
 
 After the checklist, offer to open the PR. This is human-gated — never open a PR without explicit confirmation.
 

.claude/commands/process-pr.md

@@ -132,7 +132,7 @@ gh pr comment NUMBER --body '...'
 
 ## 7. Commit and push
 
-Commit the code changes in logical groups, with messages referencing what each addressed. Follow the repo's commit conventions from CLAUDE.md, including the `Co-Authored-By` trailer.
+Commit the code changes in logical groups, with messages referencing what each addressed. Follow the repo's commit conventions from CLAUDE.md.
 
 ```bash
 git add -A

CLAUDE.md

@@ -93,6 +93,6 @@ This project uses CDD on itself. Every CDD session is a fresh context doing exac
 
 - **To start a new task** (handoff session): run `/next-step` from the main worktree to produce a handoff, then run `cdd-worktree <branch>` to spin up the implementation worktree (implementation session, opens in plan mode). `/next-step` has three front-ends: no argument picks the next roadmap item; a task prompt starts off-roadmap work (intent-driven); and `#NN` / a bare integer / the `issue`/`issues` keyword sources the task from a GitHub issue (issue-driven), naming the branch `gh_issue_NN_<slug>`.
 - **When main has advanced under a feature branch** (merge session): run `/merge-main` in a fresh context on the feature branch.
-- **Before opening a PR** (pre-PR session): run `/pre-pr` in a fresh context to verify the process doc and template are consistent and the roadmap reflects what landed; it ends with an opt-in step to open the PR (adding `Closes #NN` when the branch carries the `gh_issue_NN` token).
+- **Before opening a PR** (pre-PR session): run `/pre-pr` in a fresh context to verify the process doc and template are consistent and the roadmap reflects what landed; it auto-commits its own reconciliation edits (local, no push) and ends with an opt-in step to open the PR (adding `Closes #NN` when the branch carries the `gh_issue_NN` token).
 - **When a PR review leaves comments** (PR-review session): run `/process-pr` in a fresh context on the feature branch.
 - Keep the process doc, template, and roadmap consistent as part of every change. Process-first, then template.

doc/knowledge_base/claude-driven-development.md

@@ -158,6 +158,18 @@ Every bootstrapped or retrofitted project carries a one-line marker file, `.clau
 
 Its sole purpose is to anchor `/retrofit`'s upgrade mode: with the baseline hash, the old template a project started from can be recovered (`git show <hash>:template/<file>` in the CDD repo) and a three-way comparison can distinguish "the CDD template evolved" from "the project customized this file". Projects bootstrapped before the marker existed fall back to heuristic two-way diffing; the first upgrade writes the marker going forward.
 
+### 2.11 Commit conventions
+
+Several sessions auto-commit at their gate so that a session never leaves a dirty tree for the next one to inherit. Five rules keep this non-disruptive:
+
+1. **A gate commits only the changes it produced.** It adds the specific files the session edited — never `git add -A` over a tree it didn't author. If the working tree is already dirty on entry with changes the gate did not create, the gate **stops and surfaces** them and skips the auto-commit, rather than sweeping unrelated work into the commit.
+2. **Auto-commits are local — no push.** The sole exception is `/process-pr` (§3.7), which commits *and* pushes to the open PR branch; it is the one auto-push gate.
+3. **Messages follow the project's own commit conventions from `CLAUDE.md`**, including the `Co-Authored-By` trailer. The convention here is generic; each project defines its own message format.
+4. **Each gate surfaces a short summary of what it committed** in its output (the commit subject and the files included).
+5. **An auto-commit is not a checkpoint.** A local commit with no push is reversible — it adds no gate and removes none. It is not a seventh checkpoint (see §4); the human checkpoints are unchanged by it.
+
+Which sessions auto-commit: the implementation session (§3.3) and `/pre-pr` (§3.5) commit their own changes locally; `/process-pr` (§3.7) commits and pushes; `/merge-main` (§3.4) produces a merge commit and enforces a clean tree before merging. All four follow the rules above.
+
 ## 3. Lifecycle
 
 A task flows through CDD in up to five sessions, two of them optional side-loops (`/merge-main` before the PR, `/process-pr` after review). Each session type has a name, one command, and one job:
@@ -278,7 +290,7 @@ The session opens in plan mode, reads the handoff, and rebuilds its context from
 
 Plan mode is the load-bearing checkpoint here: the agent cannot modify files while in plan mode, so the human gets a guaranteed approval gate before any code is written.
 
-Once the plan is approved, the session implements the task, updates architecture and feature docs to reflect the change, updates the roadmap (ticking the completed checkbox; applying any add/modify/remove edits previously discussed and approved), and commits.
+Once the plan is approved, the session implements the task, updates architecture and feature docs to reflect the change, updates the roadmap (ticking the completed checkbox; applying any add/modify/remove edits previously discussed and approved), and commits its own changes locally (no push) per the commit conventions (§2.11) — stopping and surfacing rather than committing if the tree holds changes it didn't make. Because the implementation session has no command file, this commit is reinforced by a standing instruction in the handoff prompt that `/next-step` generates.
 
 ### 3.4 Merge session (optional): `/merge-main`
 
@@ -303,7 +315,7 @@ Doc reconciliation has three parts:
 
 `/pre-pr` also performs a conditional CI-improvement check: if the change introduces a category of work that the existing CI doesn't cover (new file type, new test category, a tool that should be linted but isn't), propose improvements to the human. On approval, apply them as part of the same PR; alternatively, the human may defer them as a new roadmap task. The default is silence. The agent should not propose CI improvements every run; only when the change genuinely surfaces a gap.
 
-Output is a pass/fail summary across all the gates. After the summary, `/pre-pr` offers an optional, human-gated step to open the PR — a general capability available to every task, not just issue-sourced ones. It asks a single yes/no question — no pre-shown title/body, no manual `gh` instructions. On approval it derives the title and body and runs `gh pr create`; if the branch name carries the `gh_issue_NN` token, the PR body gets a `Closes #NN` line so the issue auto-closes on merge. If §6 detected upstream drift, the step restates the `/merge-main` recommendation before offering. If the human declines, the step simply stops; the checklist stands on its own. The gate preserves the checkpoint model: `/pre-pr` never opens a PR without explicit confirmation.
+Output is a pass/fail summary across all the gates. After the summary, `/pre-pr` auto-commits the reconciliation edits it just made — the doc, CLAUDE.md, README, and roadmap changes from this session — locally and with no push, per the commit conventions (§2.11); if it entered an already-dirty tree it stops and surfaces that instead of committing. Pushing stays out of this commit: it happens only in the opt-in PR-open step below. That step is an optional, human-gated step to open the PR — a general capability available to every task, not just issue-sourced ones. It asks a single yes/no question — no pre-shown title/body, no manual `gh` instructions. On approval it derives the title and body and runs `gh pr create`; if the branch name carries the `gh_issue_NN` token, the PR body gets a `Closes #NN` line so the issue auto-closes on merge. If §6 detected upstream drift, the step restates the `/merge-main` recommendation before offering. If the human declines, the step simply stops; the checklist stands on its own. The gate preserves the checkpoint model: `/pre-pr` never opens a PR without explicit confirmation.
 
 ### 3.6 PR review and merge
 
@@ -313,7 +325,7 @@ The PR is opened either from the `/pre-pr` session's opt-in step (§3.5) or by t
 
 Run on the feature branch when a review has left comments that need addressing. A fresh session reads the open PR's review comments (inline review threads, review summary bodies, and general conversation comments), processes only the unresolved ones, and triages them: change-request, question, nit, or discussion. It presents the triage plan to the human, then implements the change-requests and nits, answers the questions, and pushes back — disagreeing and explaining in the reply — on any change-request it judges wrong or risky rather than implementing it blindly.
 
-Approving the triage plan is the session's single checkpoint: once the human approves it, the rest of the run — the edits, the in-thread replies, the commit, the push — executes without further confirmation gates. The rationale is described in Section 4. Review threads are never resolved by the command; resolving them is the human's call during re-review.
+Approving the triage plan is the session's single checkpoint: once the human approves it, the rest of the run — the edits, the in-thread replies, the commit, the push — executes without further confirmation gates. `/process-pr` is the one gate that pushes (the auto-push exception in §2.11): the PR branch is already open and under review, so the commit goes straight to it. The rationale is described in Section 4. Review threads are never resolved by the command; resolving them is the human's call during re-review.
 
 This loop can repeat across review rounds.
 
@@ -334,6 +346,8 @@ Six explicit checkpoints. The human is also free to interject at any other point
 
 These six are the gates. The agent should never proceed past a gate without explicit human confirmation.
 
+The auto-commits some sessions make at their gates (§2.11) do not change this count. A local commit with no push is reversible from git history, so it adds no checkpoint and removes none — it is not a seventh gate. The only gate that pushes is `/process-pr`, and its single up-front checkpoint is described in §4.1.
+
 ### 4.1 The `/process-pr` exception
 
 In `/process-pr` (Section 3.7) the gate sits up front rather than on each action: the human approves the triage plan (which comments will be addressed, and how) before any file is edited, and that single approval authorizes everything that follows — the edits, the in-thread replies, the commit, and the push. There is no second confirmation before the GitHub-side actions. This is a conscious trade-off, not an oversight: in a single-user, fast review-iteration loop the PR is already open, the human is actively reviewing it, and every change the command makes is visible in the PR diff and revertable from git history. Re-confirming each reply or push after the plan was already approved would defeat the purpose of a tight address-and-re-review cycle.

doc/knowledge_base/roadmap.md

@@ -105,6 +105,7 @@ Make the per-task session loop nicer to drive once a project is already on CDD.
 
 - [x] Extend `/next-step` with an optional intent prompt: with a task prompt it runs an intent-driven flow (skip candidate proposal, adaptive context load, overlap check, roadmap-belonging decision recorded for the implementation session); with no argument it keeps the roadmap-driven flow. One command, two front-ends. — process doc §3.1 + both `next-step.md` copies + both CLAUDE.md workflow bullets.
 - [x] Add a GitHub-issue front-end to `/next-step` (an issue number or the `issue`/`issues` keyword sources the task; branch named `gh_issue_NN_<slug>`), plus an opt-in "open the PR?" step in `/pre-pr` that adds `Closes #NN` on `gh_issue_NN` branches. — process doc §3.1/§3.5/§3.6 + both `next-step.md` + both `pre-pr.md` copies + both CLAUDE.md workflow bullets.
+- [x] Auto-commit at workflow gates: the implementation session and `/pre-pr` commit their own changes automatically (local, no push) in a non-disruptive way; `/process-pr` and `/merge-main` reviewed to fit one shared commit convention. — issue #20. Process doc §2.11 (new) + §3.3/§3.5/§3.7/§4 + both `pre-pr.md` and `next-step.md` copies + both CLAUDE.md `/pre-pr` bullets.
 
 **Milestone:** starting an off-roadmap task — typed or sourced from a GitHub issue — is a first-class, structured `/next-step` flow.
 

scripts/template-smoke-whitelist.txt

@@ -13,11 +13,13 @@
 <descriptive_slug>
 <exact checkbox line(s) from the roadmap being addressed>
 <file>
+<files reconciled in steps 3–6>
 <format check command>
 <integration test cmd>
 <lint command>
 <M>
 <mechanical | logical | structural>
+<message>
 <N>
 <n>
 <new convention / new utility / refactored interface>

template/.claude/commands/next-step.md

@@ -125,9 +125,11 @@ Do **not** restate project conventions, coding style, build commands, or anythin
 
 **Issue-driven mode**: open the implementation prompt by noting the source issue inline — `Sourced from GitHub issue #NN ("<title>", <url>).` — then write the scoped prompt as usual. The issue reference lives in the prose, not a separate handoff field.
 
-End the implementation prompt with this standing instruction (verbatim):
+End the implementation prompt with these standing instructions (verbatim):
 
 > Before writing a plan, surface any remaining open questions and confirm scope with the user.
+>
+> When the work is done, commit your own changes locally (no push), following the commit conventions in CLAUDE.md. Commit only the files you changed — add them by path, never `git add -A`. If the tree holds changes you didn't make, surface them rather than committing them.
 
 Show the draft to the user for approval. Iterate if needed.
 

template/.claude/commands/pre-pr.md

@@ -6,10 +6,13 @@ This session is **fresh and separate** from the implementation session by design
 
 ```bash
 git diff main...HEAD --name-only
+git status --porcelain
 ```
 
 Capture the list of changed files. Use it as the scope for steps 3 and 4.
 
+Also record the `git status --porcelain` output as the **entry snapshot**. The tree should be clean here (the implementation session commits its own work). If it is already dirty, those are changes this session did not create — note them now; step 8 must not sweep them into the auto-commit.
+
 ## 2. Build & QA
 
 Run each CI job sequentially. **Capture only the last 40 lines + exit code, do not read the full output.** Stop on first failure.
@@ -89,11 +92,28 @@ Present a checklist summary:
 - [ ] Roadmap up to date
 - [ ] CI gaps surfaced: none / proposed (list them)
 - [ ] No upstream drift (or: /merge-main recommended)
+- [ ] Reconciliation edits committed
 ```
 
 Mark each item as pass ✓ or needs attention ✗ with details.
 
-## 8. Open PR (optional)
+## 8. Commit reconciliation edits
+
+Commit the documentation reconciliation edits this session made in steps 3–6 (architecture/feature docs, CLAUDE.md, README, the coding standard, and the roadmap). This is a local commit only — **no push**. Pushing happens, if at all, in step 9.
+
+First check the entry snapshot from step 1:
+
+- **If the tree was already dirty on entry** (changes this session did not create), **stop and surface** them: list those paths, state that the auto-commit is skipped so unrelated work isn't swept in, and let the user resolve it. The checklist above still stands on its own.
+- **Otherwise**, commit only the files this session edited. Add them by path — do not `git add -A`:
+
+```bash
+git add <files reconciled in steps 3–6>
+git commit -m '<message>'
+```
+
+Follow the repo's commit conventions from CLAUDE.md. Print a one-line summary of the commit (subject + files included). If nothing was reconciled (no edits this session), say so and skip the commit.
+
+## 9. Open PR (optional)
 
 After the checklist, offer to open the PR. This is human-gated — never open a PR without explicit confirmation.
 

template/.claude/commands/process-pr.md

@@ -132,7 +132,7 @@ gh pr comment NUMBER --body '...'
 
 ## 7. Commit and push
 
-Commit the code changes in logical groups, with messages referencing what each addressed. Follow the repo's commit conventions from CLAUDE.md, including the `Co-Authored-By` trailer.
+Commit the code changes in logical groups, with messages referencing what each addressed. Follow the repo's commit conventions from CLAUDE.md.
 
 ```bash
 git add -A