Refactor Checkpoint Policy Write-Guard Semantics

Claude Code·

pfleidi·2mo ago·52min·3 Checkpoints·15 file changes·+52/-61·267.3K tokens

For added context:

Session summary: Remove `checkpoint_version` from checkpoint metadata

Goal: Remove the CheckpointVersion property from checkpoint metadata.json and the gates that check it. Existing checkpoints will be handled by an external migration script, so no backward-compat handling for the stored attribute is needed.

Scope decision (after investigation): The version machinery has three parts: (A) the checkpoint_version stamp in metadata.json — a pure label nothing dispatches on (backend selection comes from settings topology, not the stamp), (B) the EnsureCanReadVersion read gates at resume/explain/rewind/export — forward-compat tripwires that can only fire for hypothetical future formats, and (C) the checkpointpolicy subsystem (policy ref at refs/entire/policies/checkpoint, hidden entire checkpoint policy command, write gates, telemetry). Agreed scope: remove A + B only; C stays untouched. Existing policy refs are left alone.

Approved plan: step-by-step execution, two commits:

remove checkpoint_version read gates
drop checkpoint_version from checkpoint metadata

(Gates must go first — they read the field being removed in commit 2.)

Step 1 — done, awaiting review/commit approval:

Deleted cmd/entire/cli/checkpointpolicy/version.go and the gate-only test file checkpoint_policy_read_test.go.
Removed the 7 gate call sites and unreachable IsUnsupportedVersion error branches in resume.go, explain.go, explain_export.go, rewind.go, strategy/manual_commit_rewind.go.
Dropped two redundant ReadCheckpoint calls (resume session-log restore, rewind transcript restore) that existed only to feed the gate — ReadRawSessionLogForCheckpoint already reads the checkpoint internally.
Removed 5 gate-behavior tests and the rewriteExportCheckpointVersionToRefsV2 test helper.
Docs: removed the sentence in docs/architecture/sessions-and-checkpoints.md about explain/resume failing on unsupported checkpoint_version.
Verified: go build ./... clean, focused tests pass (cli, checkpointpolicy, strategy packages), mise run fmt && mise run lint → 0 issues.

Next steps: Commit Step 1 on approval, then Step 2: remove WriteOptions.CheckpointVersion and CheckpointSummary.CheckpointVersion (api/checkpoint/metadata.go), the stamping plumbing in checkpoint/persistent.go / refs_store.go / manual_commit_condensation.go, normalizeCheckpointSummary, checkpointVersionForNewCheckpoint (attach.go switches to ensureCheckpointPolicyAllowsCheckpointData to keep the write gate), the now-unused CheckpointVersionRefsV1 constant, associated tests, and the metadata.json doc example. Plan file: ~/.claude/plans/abstract-splashing-lemon.md.

2mo ago·17.4s

Step 1 is complete and ready for your review — here's the checkpoint summary.

Step 1: remove checkpoint_version read gates

Deleted cmd/entire/cli/checkpointpolicy/version.go (the EnsureCanReadVersion gate) and its gate-only test file checkpoint_policy_read_test.go.
Removed the 7 gate call sites and the now-unreachable IsUnsupportedVersion error branches across resume.go, explain.go, explain_export.go, rewind.go, and strategy/manual_commit_rewind.go.
Dropped two ReadCheckpoint calls (in the resume session-log restore and the rewind transcript restore) that existed only to feed the gate — ReadRawSessionLogForCheckpoint already reads the checkpoint itself.
Removed 5 gate-behavior tests plus the rewriteExportCheckpointVersionToRefsV2 test helper, and dropped the sentence in docs/architecture/sessions-and-checkpoints.md about explain/resume failing on unsupported versions.

Verification (all from this step, nothing changed since): go build ./... clean, focused tests in the cli, checkpointpolicy, and strategy packages pass, and mise run fmt && mise run lint reported 0 issues.

One thing worth calling out from the diff: the dropped redundant ReadCheckpoint calls are a small behavior simplification, not just gate removal — the reads were gate-feeders only, so nothing downstream loses data.

On your approval I'll commit this as remove checkpoint_version read gates, then start Step 2 (dropping the checkpoint_version stamp from metadata writes: WriteOptions.CheckpointVersion, CheckpointSummary.CheckpointVersion, the stamping plumbing, normalizeCheckpointSummary, checkpointVersionForNewCheckpoint, the unused constant, tests, and the doc example).

Committed as bc49bc896b — remove checkpoint_version read gates (11 files, 4 insertions, 359 deletions).

Ready to start Step 2 when you say go: dropping the checkpoint_version stamp itself from metadata writes (WriteOptions.CheckpointVersion, CheckpointSummary.CheckpointVersion, the stamping plumbing in checkpoint/persistent.go / refs_store.go / manual_commit_condensation.go, normalizeCheckpointSummary, checkpointVersionForNewCheckpoint, the unused constant, associated tests, and the metadata.json doc example).

Step 1 missed nothing, and Step 2's plan is nearly complete — the sweep found two small additions to fold into Step 2, plus confirmation that everything else remaining is the policy subsystem we agreed to leave alone.

Additions for Step 2:

cmd/entire/cli/checkpoint/aliases.go:57-58 — the re-exported CheckpointVersionRefsV1 alias has to go along with the underlying constant in api/checkpoint/errors.go. (The CheckpointVersionBranchV1 constant and its alias must stay — the policy subsystem uses it heavily as the default policy version in checkpointpolicy/policy.go.)
Doc paragraph, not just the example — in sessions-and-checkpoints.md, the checkpoint metadata example (line 254) is planned, but the Checkpoint Policy section's prose (lines 323-329) says checkpoint_version "selects the checkpoint format for new writes" and that "the CLI writes its default checkpoint version." After Step 2 nothing is written — the policy field becomes purely a write gate (writers fail if the configured version is unsupported, which ensureCheckpointPolicyAllowsCheckpointData keeps enforcing). That paragraph needs a light rewording, not removal. The policy file example at line 311 stays as-is — that's the policy's own field, not the metadata stamp.

Confirmed in-plan: normalizeCheckpointSummary lives in checkpoint/persistent_reader.go (its only job is backfilling the version default, so file and both call sites in persistent.go go away), and the version-asserting tests are in persistent_write_test.go, persistent_update_test.go, refs_store_test.go, refs_store_seam_test.go, and persistent_tripwire_test.go.

Confirmed out of scope (policy subsystem, stays): hook_registry.go, hooks_git_cmd.go, import_cmd.go's help text, and everything under checkpointpolicy/ — those all reference the policy's CheckpointVersion field, not the metadata stamp. attach.go switching from checkpointVersionForNewCheckpoint to ensureCheckpointPolicyAllowsCheckpointData matches the existing pattern in explain.go:701 and import_cmd.go:59, after which checkpointVersionForNewCheckpoint is deleted.

Say the word and I'll execute Step 2 with these two additions folded in.

Step 2: drop checkpoint_version from checkpoint metadata — ready for review, 32 insertions / 302 deletions across 15 files.

What changed:

api/checkpoint/metadata.go: removed WriteOptions.CheckpointVersion and CheckpointSummary.CheckpointVersion; api/checkpoint/errors.go and checkpoint/aliases.go: removed the now-unused CheckpointVersionRefsV1 constant and its alias. CheckpointVersionBranchV1 stays — the policy subsystem uses it as its default version.
checkpoint/persistent.go + refs_store.go: the checkpointVersion parameter is gone from the whole write chain (applySessionWrite → writeStandardCheckpointEntries → writeCheckpointSummary), along with the preserve-existing-version read in writeCheckpointSummary. normalizeCheckpointSummary deleted from persistent_reader.go (the file keeps AuthorReader); its two call sites now return the parsed summary directly.
strategy/manual_commit_condensation.go and attach.go: no longer resolve a version from the policy. The policy write gate stays in both — condensation keeps its CanSatisfyPolicy check, and attach switched from checkpointVersionForNewCheckpoint (deleted from checkpoint_policy_write.go) to the existing ensureCheckpointPolicyAllowsCheckpointData, matching explain and import.
Tests: deleted the six version stamp/backfill/preserve tests and the now-orphaned rewriteRootSummary helper; dropped the version assertion from the refs-store and seam tests (their other assertions stay).
Docs: removed checkpoint_version from the metadata.json example, and reworded the policy section — its checkpoint_version field is now described as a pure write guard rather than "selects the format for new writes", since nothing is stamped anymore.

One diff note: attach.go shows more changed lines than the logical edit because removing CheckpointVersion (the longest field name) made gofmt realign the whole writeOpts struct literal.

Verification: go build ./... clean; go test -count=1 passes on api/checkpoint, all cmd/entire/cli/checkpoint/... packages, strategy, and cli; mise run fmt && mise run lint → 0 issues on the formatted tree. A leftover-reference sweep finds only the policy subsystem's own CheckpointVersion fields, which are intentionally untouched.

On approval I'll commit as drop checkpoint_version from checkpoint metadata, which completes the planned work.

Correct. CheckpointVersionBranchV1 remains the anchor value for the whole policy subsystem — that's exactly why it stayed while CheckpointVersionRefsV1 was deleted. In checkpointpolicy/policy.go it feeds:

DefaultPolicy() / DefaultCheckpointVersion() — the values used when no policy ref is configured (lines 15-24).
Normalize() — backfills both checkpoint_version and checkpoint_min_version when a policy omits them or sets them to empty (lines 26-34).
The gate evaluations built on those — ValidatePolicy (rejects a --checkpoint-version this CLI can't write, and min > version downgrades), CanSatisfyPolicy (the write gate that condensation, attach, explain, and import still call), RequiresUpgrade, and the upgrade-nudge error messages.

So entire checkpoint policy --checkpoint-version ... still works end to end: the value is parsed via ParseFormat, validated against CanWrite, stored in the policy ref, and enforced as a write gate on every checkpoint-data writer. The only thing that changed is what happens after the gate passes — the resolved version used to also be stamped into each checkpoint's metadata.json, and now it isn't consumed for anything beyond the gate decision. That matches the doc rewording in Step 2: the policy field went from "selects the format for new writes" to a pure write guard.

Still holding at the Step 2 checkpoint — ready to commit on your approval.

Committed as e4ca4508d0 — drop checkpoint_version from checkpoint metadata (15 files, 32 insertions, 302 deletions).

That was the last planned step, so the branch is complete: two commits, gates removed first, then the stamp itself.

bc49bc896b — remove checkpoint_version read gates
e4ca4508d0 — drop checkpoint_version from checkpoint metadata

The policy subsystem (refs/entire/policies/checkpoint, the hidden entire checkpoint policy command, write gates, telemetry) is untouched as agreed, and existing checkpoints' stored checkpoint_version values are left for the external migration script.

One note before this ships: I ran unit tests on the changed packages but not mise run test:integration or the e2e canary — if any integration test asserts on checkpoint_version in metadata.json, it would only surface there. Want me to run the integration suite, or go straight to /pr?

Base directory for this skill: /Users/pfleidi/.agents/skills/pfleidi/skills/de-slop

De-slop

Deliberately reduce slop in a change, then land the result as a reviewable PR. By default the target is the changes the current branch introduces against origin/main; the user can point it at a directory, package, or the whole repo instead. Slop is code that costs more than it earns: verbosity, over-abstraction, over-commenting, dead or unused code, hand-rolled solutions to already-solved problems, premature optimization, and tests that assert little. This skill removes it without changing behavior.

This is an opt-in operation. It intentionally overrides the normal "stay scoped, no unrelated refactors" rule — but only within the branch the user asked you to de-slop, and only for changes that clearly reduce slop.

Ground Rules

Preserve behavior. Every change is behavior-neutral unless the user explicitly asks for a fix. If you find a real bug, note it separately — do not silently change behavior under cover of a cleanup.
Tests guard every change. Do not simplify code that has no test covering the behavior you are about to touch. Backfill a test that pins the current behavior first, then simplify, then confirm it still passes.
One coherent change per commit. Each commit is small, self-contained, and independently reviewable so the branch could later be split into a stack. Never mix unrelated simplifications in one commit.
Ask before new dependencies. Replacing reinvented code with the standard library or an already-present dependency is encouraged. Adding a new third-party dependency still requires asking first.
Ask before committing, pushing, and opening the PR. The loop runs autonomously between checkpoints, but landing anything needs approval per the normal workflow.
Reuse the existing skills. Do not reimplement review, Go cleanup, test auditing, or PR creation — drive them.

What Counts as Slop

Needless indirection: wrappers, layers, interfaces, or helpers with one caller and no seam they justify.
Duplication and reinvention: a hand-rolled mechanism the repo, standard library, or an existing dependency already provides.
Dead or unreachable code, unused params/fields/returns, data computed but never read.
Verbosity: multi-step code that a clear direct expression replaces.
Over-commenting: comments that restate the code (see the Values guidance the repo already follows).
Premature optimization: complexity added for performance no one measured.
Weak tests: tests that assert nothing meaningful, over-mock, or lock in implementation detail rather than behavior.

Leave alone anything that is merely not-how-you-would-write-it. Taste is not slop.

Workflow

1. Scope and branch

By default, de-slop the changes the current branch introduces against origin/main — the same diff the review skills use. Fetch first so the comparison is current:

Work on the current branch and add the cleanup as new commits on top. If the user named a different scope — a directory, package, or a whole-repo pass — use that instead; for a whole-repo pass not already on a branch, propose a branch name and wait for approval before creating it.

2. Build a slop inventory

Survey the target — by default the files the branch changed against origin/main — and produce a concrete, located list of slop: file and line, what it is, and why removing it is safe. Reuse detection rather than eyeballing:

Run pfleidi:review over the area for simplification and dead-code findings.
For Go, run pfleidi:clean-go for cleanliness findings.
Use entire-internal:test-auditor (or pfleidi:testing) to find weak or redundant tests and coverage gaps.

Verify each candidate against the source yourself. Discard anything speculative.

3. Prioritize into a commit plan

Order the inventory into commit-sized units, highest value and lowest risk first. Group by coherent change, not by file. Present the plan as an ordered list of one-line commit subjects (the stacked-PR shape) and get approval before executing, per the repo's plan-first workflow.

4. Execute each unit

For each unit, in order:

If the behavior it touches is untested, backfill a test that pins current behavior and confirm it passes.
Make the simplification.
Run focused verification for the changed packages/area — build, the relevant lint task, and the directly related tests. Show the command and result.
Commit the single coherent change on approval, with a message stating what slop was removed and why it is safe.

Keep implementation and its tests in the same commit. Stop at each commit checkpoint; do not batch ahead without approval.

5. Know when to stop

Stop when the remaining candidates are taste, when the risk of a change exceeds its value, or when further simplification would need a behavior change or a design decision the user has not authorized. List what you deliberately left and why. Do not manufacture churn to look thorough.

6. Validate and open the PR

Before landing, run the fuller verification the change warrants (build, lint, and tests across the affected area) and confirm it is green — show the evidence. Then land it: if the branch has no PR yet, open one with pfleidi:pr; if it already has one, the cleanup commits extend it (push on approval). Either way, frame the description or summary around what got simpler and more robust, and note that the commits are ordered to be split into a stack if the reviewer prefers.

Report

At each checkpoint, keep it short: what this unit removed, the test that guards it, and the verification result. At the end, summarize the net effect (what shrank, what got covered, what you left and why) and the final green-CI evidence.

2mo ago·2m

The test audit found one real branch-created weakness, and confirmed all four suspected coverage gaps are actually covered:

Real finding: refs_store_seam_test.go — dropping the wantVersion assert removed the only thing that could distinguish a read served by the git-refs primary from one served by the git-branch mirror (both stores hold identical content now that the version stamp is gone). The test's doc comment still claims it "asserts reads resolve from the git-refs primary", but a silent fallback-to-mirror regression would now pass. Fixable behavior-neutrally with a different probe (e.g. a subtest that deletes the v1 branch ref and asserts reads still succeed via the primary).
Attach policy gate, resume missing-checkpoint, and condensation policy refusal are all still covered by existing tests; no integration/e2e test references the removed field; no orphaned helpers or imports anywhere.

This matches what I read of the seam test earlier — the version assert was indeed the sole discriminator, so I'm treating it as confirmed.

One agent left (dead-code/indirection); I'll present the full inventory and commit plan when it lands.

Fanout reads are pure delegation to the primary — no mirror fallback — so a "delete the v1 branch, then re-read through the composed store" probe cleanly pins that reads resolve from the git-refs primary. Inventory is complete and verified.

Slop inventory and commit plan

The branch itself came back remarkably clean — the Go cleanliness pass had zero findings, no orphaned helpers or dead code anywhere, and all four suspected coverage gaps (attach gate, resume missing-checkpoint, rewind restore, condensation refusal) are covered by existing tests. Two real leftovers survive verification:

1. reword checkpoint policy help to write-guard semantics cmd/entire/cli/checkpoint_policy.go:31 (hidden entire checkpoint policy command help) still says checkpoint_version "selects the checkpoint metadata format used for new writes" — nothing selects a format from it anymore; it's purely a write guard. The branch updated the architecture doc to the new wording but missed this help text, and checkpoint_policy_test.go:42 asserts the stale sentence verbatim. Fix: reword help + assertion together, mirroring the doc's write-guard phrasing. Behavior-neutral (help text only).

2. pin seam test reads to the git-refs primary refs_store_seam_test.go — removing the version assert deleted the only discriminator between "read served by the git-refs primary" and "read served by the git-branch mirror"; the test's doc comment now overstates what it verifies. Fix: add a final subtest that deletes the v1 branch ref and asserts the composed store still reads the checkpoint — provable only if the primary serves reads. Test-only, pins current behavior.

Deliberately left (verified, but taste or pre-existing):

readSummaryFromBlob is now a one-line alias with 5 call sites — still earns its name as the single summary-read point; inlining is lateral churn.
unsupportedCheckpointPolicyError dropped to one caller, but keeps symmetry with its unreadable sibling (2 callers).
persistent_reader.go is down to 14 lines holding only the widely-used AuthorReader interface — folding it elsewhere is file churn, not simplification.
Back-to-back Debug+Warn logging in resume.go and the untested-in-isolation rewind transcript restore both pre-date this branch.

Two commits, ordered as listed (help-text fix first: lowest risk, highest confidence). Approve the plan and I'll execute unit 1?

Unit 1 checkpoint — done and verified:

Reworded checkpoint_policy.go help from "selects the checkpoint metadata format used for new writes" to "is a checkpoint-data write guard", and updated the verbatim assertion in checkpoint_policy_test.go:42. Two lines, help text only.
Guard test: TestCheckpointPolicyCmd_HelpDocumentsEnforcementBehavior passes (along with the rest of TestCheckpointPolicyCmd*, all PASS above); mise run lint exited clean.

Commit as reword checkpoint policy help to write-guard semantics?

Unit 2 checkpoint — done and verified:

Added a reads resolve from primary subtest to TestSeam_GitRefsPrimaryWithGitBranchMirror: it deletes the mirror's v1 branch ref, then re-runs the full read assertions through the composed store. This restores the discriminator the version assert used to provide — the test's doc-comment claim that "reads resolve from the git-refs primary" is verifiable again, and it would catch a silent fallback-to-mirror wiring regression.
Evidence: all three subtests PASS (go test -run TestSeam_GitRefsPrimaryWithGitBranchMirror -count=1), mise run lint → 0 issues.

Commit as pin seam test reads to the git-refs primary? That's the last inventory item — after this, remaining candidates are the taste-only ones I listed as deliberately left, and the next step would be validation + PR (per the de-slop flow: this branch has no PR yet, so I'd run the fuller verification and open one via /pr on your go-ahead).

Base directory for this skill: /Users/pfleidi/.agents/skills/pfleidi/skills/pr

Create Pull Request

1. Understand the Branch

Use origin/main as the comparison base for understanding branch scope. Do not use local main, a local PR target branch, or direct tree diffs such as git diff main or git diff origin/main for scope checks; those can include upstream-only changes and make this branch look like it reverted unrelated work.

Read the commit history to understand the full scope of changes on this branch.

Review the changed file list from the merge base to the current working tree and confirm every changed file belongs to the PR's stated goal:

If unrelated files or commits are present, STOP and report them. Do not create a PR that bundles unrelated work.

2. Sync with origin/main

Before discovering verification commands, bring the branch up to date with origin/main so verification runs against the merged state.

Check that the working tree is clean:

If there are uncommitted changes, STOP and ask the user to commit or stash them before continuing. A sync into a dirty tree creates ambiguous failure states.

Fetch and merge:

Three outcomes:

Already up to date — no commits to merge. Proceed to step 3.
Clean merge — merge commit created (or fast-forward applied). Proceed to step 3.
Conflicts — merge halts with conflicted files. STOP and report each conflicted file. Do NOT auto-resolve; the user must resolve the conflicts and complete the merge commit themselves. Re-run the PR skill after resolution.

3. Discover Project Verification Commands

Inspect the project to determine how to build, lint, and test. Collect candidate commands from these sources, then deduplicate them before running anything:

Makefile — look for build, lint, check, test, ci, verify targets. Read the target recipes to understand what they run.
mise — check for .mise.toml or .mise/*.toml. Look for [tasks] definitions covering build, lint, test. If found, use mise run <task>.
CI workflows — read .github/workflows/*.yml (or .gitlab-ci.yml, etc.) to understand required coverage. CI is the ground truth for what must pass, but CI matrix shards and CI-only wrappers are not automatically local verification commands.
README.md — look for "Development", "Contributing", "Building", or "Testing" sections that document how to run checks.
Package manager conventions — detect from project files:
- go.mod → go build ./..., go vet ./..., go test ./...; do NOT infer a lint command from Go alone
- package.json → check scripts for build, lint, test
- Cargo.toml → cargo build, cargo clippy, cargo test
- pyproject.toml / setup.py → check for configured linters, pytest

If no lint command exists after checking all sources, state that explicitly instead of assuming an unavailable linter binary.

Reuse Cached Verification Discovery

Before rediscovering commands from scratch, choose an artifact directory using the AGENTS.md temporary artifact rule with agent name pfleidi-pr:

Use ./tmp/pfleidi-pr/ only when ./tmp/ already exists and is already ignored.
If no project-local artifact directory is available, do not use a verification cache by default. Ask before using /tmp/pfleidi-pr/ or modifying ignore files.

When an artifact directory is available, check for a verification cache at <artifact-dir>/verification-<repo-name>.md. The cache is only an input-token optimization; never commit it and never trust it blindly. If no artifact directory is available, perform normal discovery and skip writing the cache.

Reuse the cache only when all of these are true:

It names the same worktree root and remote.
It lists the verification source files it was based on, such as Makefile, .mise.toml, .mise/*.toml, CI workflow files, README files, and package manifests.
Those source files still exist or are still intentionally absent.
git diff --name-only origin/main -- <source files> shows no branch changes to those source files.

If the cache is missing, stale, or incomplete, perform normal discovery. After discovery, update the cache with:

Repository root and remote.
Verification source files inspected.
Selected command plan grouped by coverage area.
Commands intentionally skipped as duplicates, aggregate/subtask overlaps, CI-only jobs, or too-slow shard matrices.
Any assumptions, such as "no documented lint task found."

Deduplicate Verification Commands

Build a command plan by coverage area, not by source. Do not run every command discovered.

Run at most one command for each coverage area: build/compile, lint/static analysis, unit/core tests, integration tests, e2e/smoke tests.
Prefer documented local developer tasks over CI-specific commands when they cover the same area.
Do not run both an aggregate task and its constituent tasks. For example, if mise run check runs lint and tests, either run mise run check alone or run the narrower lint/test tasks, not both.
Treat CI matrix shards as duplicated slices of one suite. Do not run every *:shard:* command locally when an unsharded local task covers the suite.
If CI has only sharded commands and no local equivalent, ask before running all shards. Otherwise, run the smallest representative or changed-scope test command and note that the full shard matrix remains for CI.
Do not run CI-only canary/e2e jobs locally by default. Run them only when the PR changes that surface, when the user asks, or when the project documents them as required local PR verification.

Log which sources you used, which duplicate/CI-only commands you skipped, and what commands you will run. If the deduplication rules require asking before slow CI-only coverage, STOP for confirmation; otherwise immediately proceed to step 4.

4. Run Verification and Auto-Fix

Run the deduplicated command plan in the fewest safe batches. Prefer background processing for independent validation tasks instead of running everything sequentially.

The commands should cover, at minimum:

Build — the project compiles without errors
Lint / static analysis — no lint warnings or static analysis failures
Tests — the selected local test coverage passes without duplicating CI shards or aggregate/subtask combinations

Use the exact commands, flags, and build tags found in step 3 for the commands you selected. Do not invent your own flags.

Parallel Verification Rules

Partition the selected commands into dependency-safe batches before running them:

Run mutating commands alone and before validators that depend on their output. This includes formatters, generators, codegen, migrations, package installation, or commands known to update snapshots, lockfiles, generated files, caches in the repo, or test fixtures.
Run dependent commands after their prerequisite batch passes. For example, do not start tests that require generated code until generation succeeds.
Run independent read-only validation commands concurrently in the same background batch. Build, lint/static analysis, typecheck/vet, and unit tests can usually share a batch when they do not mutate the working tree and do not require the same exclusive service, port, database, or fixture directory.
Keep integration, e2e, or service-backed commands separate unless the project documents that they are parallel-safe.
If unsure whether two commands are independent, run them sequentially. Correctness of validation beats speed.

For each background batch:

Start every command from the same working-tree state.
Run each selected validator directly, for example mise run lint, go test ..., or npm test -- .... Do not wrap validators in sh -c, shell redirection, tee, command separators, or pipelines solely to capture logs; that defeats command-prefix approvals and causes extra permission prompts.
Capture each command's stdout, stderr, exit status, and command line from the tool output separately.
While the batch is running, do not edit files, start auto-fixes, or treat partial output as a result.
Wait for every command in the batch to finish, then show verification as a compact table:

Command Exit Relevant output
go test ./pkg/foo -run TestBar -count=1 0 Short success excerpt.
For failures or short outputs, show complete output in the relevant-output column or immediately below the table. For long successful outputs, show the relevant excerpt and state that the rest was truncated.
If any command in the batch fails, treat the whole batch as failed for the fix loop. Results from other commands in that stale batch may help diagnose, but they do not count as passing verification after files change.

Command	Exit	Relevant output
`go test ./pkg/foo -run TestBar -count=1`	0	Short success excerpt.

On Failure: Fix and Re-verify

If any command fails, do NOT stop. Instead:

Read the error output and identify every failure
Fix all issues — apply the minimal changes needed to make the failing command pass
Re-run the deduplicated verification plan from the top, using the same safe batching rules (not just the previously failing command — fixes can introduce new issues)
Show the updated verification table again, including complete failure output for any command that still fails

Repeat this cycle until all commands pass. Cap at 3 fix attempts. If verification still fails after 3 rounds, STOP and present the remaining failures to the user with full failure output — do not keep looping.

5. Prompt for Commit

After all verification passes, check for uncommitted changes:

If there are uncommitted changes (from auto-fixes in step 4):

Show the diff of all uncommitted changes
Propose a semantically correct commit message using the subject-plus-context style from AGENTS.md. The message must describe the net fix (e.g., "fix lint warnings in config parser" not "fix issues found during PR prep").
If compile/build did not pass for code changes, say the work is not commit-ready and do not ask to commit until the gap is resolved or the user explicitly takes over.
STOP and wait for user approval. The user may edit the message, split the changes, or commit themselves.

If the user approves the commit, do not rerun the full verification suite before committing unless files changed after step 4. If another sanity check is needed, use the commit-time verification scope from AGENTS.md: lint tasks, a compile/build check for code changes, and tests directly related to the changed code only.

If there are no uncommitted changes, proceed directly to step 6.

6. Push the Branch

If the branch has no upstream yet, use git push -u origin HEAD.

7. Create the PR

Determine a concise PR title (under 70 characters) from the commit history and diff.

Set the target base branch from the user-provided PR base, or main when the user did not provide one. Scope checks still use origin/main; the PR target base controls only the GitHub PR destination.

If the user provided a PR target base, set PR_BASE to that branch name instead.

Determine the pushed source branch:

If HEAD_BRANCH is empty, STOP and report that PR creation needs a named local branch.

Determine the GitHub repository slug from the origin remote before writing the PR body:

Extract GITHUB_REPO as <owner>/<repo> from these origin URL forms:

git@github.com:<owner>/<repo>.git
https://github.com/<owner>/<repo>.git
ssh://git@github.com/<owner>/<repo>.git
entire://<mirror-host>/gh/<owner>/<repo>

Strip a trailing .git when present. For entire:// remotes, ignore the mirror host and use only the suffix after /gh/; do not use any checkpoint-storage repository URL as the PR target when the entire://.../gh/... origin is available.

If the origin URL does not expose a GitHub repository, try:

If that still cannot identify a repository, STOP and ask the user for the GitHub target.

Use the same branch-only comparison from step 1 ($MERGE_BASE to the current working tree) when deriving the title, PR body, changed-file list, and mostly-Markdown detection. Do not use local main or direct git diff origin/main output for PR description decisions.

Write the PR body to help a reviewer (human or bot) understand the change without re-deriving it from the diff. Include these sections; omit any that genuinely don't apply:

Why — the motivation: what problem this solves, what behavior was broken or missing, what constraint forced the change. This is the most important section. Be specific so neither a reviewer nor a bot has to infer the reason from the diff alone.
What changed — a short, factual summary of the net change. One or two sentences; the diff is the source of truth.
Usage examples — for a new or changed command, API, config option, workflow, or user-facing behavior, show a small realistic example of how to use it and what to expect. For UI work, add screenshot placeholders such as Before: <screenshot> and After: <screenshot> when actual screenshots are not available yet.
Decisions made during development — non-obvious choices from the development process: why one approach over another, why an existing abstraction wasn't reused, why a check lives where it does, what assumptions shaped the implementation, and what constraints were intentionally accepted.
Technical tradeoffs — when a real engineering tradeoff was made, name the options weighed, what the chosen approach gives up, and why that tradeoff is acceptable. Skip if the change was mechanical with no meaningful alternatives.
Reviewer notes — only for migrations, deployment ordering, backwards-incompatible behavior, or known follow-up work not in this PR. Skip otherwise.
Rendered Markdown (for mostly Markdown PRs) — links to the changed Markdown files rendered on GitHub.

Do NOT include:

A "Test plan" or "Verification" section listing the CLI commands run. Verification already happened in step 4; the transcript doesn't help the reviewer.
A list of newly added tests. The diff already shows them; the list rots when tests are renamed or moved.
A file-by-file changes summary. The diff already shows this too.

Choose the PR creation command from the origin URL.

For entire://.../gh/<owner>/<repo> origins, do not use gh pr create. It may still inspect the local git remote and fail to infer a GitHub host even when --repo "$GITHUB_REPO" is supplied. Use the GitHub API through gh api with the already-derived repository slug and pushed branch:

For normal GitHub remotes, use gh pr create:

If a non-entire:// origin hits the same host-inference failure from gh pr create, use this gh api creation path once instead of retrying gh pr create.

Create a ready-for-review PR only when the user explicitly asks for it with wording such as "non-draft", "ready for review", or "publish it as ready". In that case, omit --draft from gh pr create or omit -F draft=true from the gh api call.

Show the PR URL and STOP.

Rules

Do NOT add "Generated with Claude Code" or any AI attribution anywhere
Do NOT summarize what you just did after showing the URL
Treat a PR as "mostly Markdown" when more than half of changed files are Markdown (.md, .mdx, .markdown) or the main review target is Markdown documentation. In that case, include GitHub rendered links for the changed Markdown files using the pushed branch, e.g. https://github.com/$GITHUB_REPO/blob/<branch>/<path>.md. Link all changed Markdown files when the list is short; for large docs PRs, link the main entry points or most important changed files.
If the user provides a title or description, use it verbatim instead of generating one, but append rendered Markdown links for mostly Markdown PRs unless the user explicitly says not to modify the description.
If the PR description contains checklist items (- [ ]), check them (- [x]) if and only if the corresponding step was actually verified during this workflow (e.g., build passed, tests passed, lint passed). Do NOT check items that were not verified. Do NOT leave items unchecked if they were verified.

2mo ago·1m