Happier Commit Worktree

Happier Commit Worktree

Turn an existing moving worktree into a sequence of reviewable commits without treating file count, directory boundaries, or the current index as truth. Preserve all bytes on disk, prove what each commit contains, and leave uncertain material uncommitted with a specific reason.

A large-worktree request is a campaign, not a request for one commit or one analysis wave. Continue recon, packet preparation, committing, and residual classification until every current path is committed or has an evidence-backed exclusion or blocker. Producing a few commits while commit-ready paths remain is incomplete execution unless the user explicitly pauses the campaign.

1. Establish authority and safety

Require an explicit user request to commit. Analysis alone does not authorize staging or commits.

Apply these invariants throughout:

• Never run git reset, git restore, git clean, git checkout, git switch, or an equivalent destructive operation.
• Never overwrite, delete, or normalize unrelated work merely to make status clean.
• Never trust or wholesale-commit the shared index. Stage every commit from explicit paths or hunks in a fresh private index.
• Treat the checkout as live. A path can change before, during, or after a commit.
• Serialize HEAD mutations even when reconnaissance and validation run in parallel.
• Use Conventional Commit subjects and explanatory bodies.
• Commit only changes whose intent, ownership, and suitability are understood.
• Use the checkout's existing current-user git config user.name and git config user.email for every ordinary commit. Verify both before the first commit; never rewrite them to a bot, PR author, issue author, or other contributor, and stop rather than inventing a missing identity.
• Evaluate Co-authored-by: attribution per packet. Add a verified contributor only when that packet materially incorporates their code, patch, design, causal diagnosis, decisive reproduction, or substantially adopted fix direction; never infer attribution from PR/issue authorship or participation alone.

Read private-index-protocol.md before the first commit in a campaign. Read recovery-and-audit.md whenever the index is unusual, a process was interrupted, HEAD moved, a lock appeared, or the user asks whether everything was preserved.

2. Snapshot the current basis

Record compact observed evidence before grouping:

git rev-parse HEAD
git status --short
git diff --cached --name-status
git diff --stat
git ls-files --others --exclude-standard

Do not equate a clean shared index with a clean worktree. Do not equate an untracked path with source code. If the shared index is non-empty, inspect it before proceeding; never clear inherited staging by assumption.

Build a resumable inventory grouped by package, domain, change kind, and likely provenance. Snapshot at wave boundaries and refresh paths that overlap a completed commit or changed during analysis; do not repeat repository-wide recon after every commit when independent inventory remains valid.

3. Run reconnaissance before committing

Use maximum useful parallelism where it shortens the critical path. Give each lane an exact, preferably disjoint path inventory and require:

• candidate groups with exact paths and any hunk-level splits;
• the user or system behavior each group establishes;
• canonical owner, coupled tests, fixtures, schemas, docs, and generated contracts;
• suspected artifacts or uncertain paths and the evidence for exclusion;
• dependency ordering and validation commands;
• a proposed Conventional Commit subject and explanatory body.

The lane must account for every assigned path as part of a commit-ready packet, an evidence-backed exclusion, or an unresolved item with the exact missing fact. It does not finish after finding representative groups or the first few commits. Sampling is not successful reconnaissance.

Reconnaissance lanes do not stage or mutate Git unless explicitly assigned commit authority. A single orchestrator should normally perform HEAD updates. If multiple agents must commit, each uses a private index and compare-and-swap update from its observed parent; a stale agent rebuilds from the new HEAD rather than forcing or replaying blindly.

Follow the active subagent context policy. Default to no inherited transcript and provide a self-contained brief with exact scope, evidence, paths, checks, output, and stop conditions. Do not let lanes create ad hoc review files or use path "custody" as a substitute for checking current bytes and actual hunk collisions.

Read campaign-throughput.md before orchestrating a large or continuing campaign. It defines rolling waves, confidence lanes, packet queues, parallel topology, validation reuse, progress gates, compaction anchors, and valid stopping conditions. Read grouping-and-messages.md for the classification rubric, artifact policy, commit sizing, and message standard.

4. Operate a rolling commit campaign

Keep the serial commit authority supplied with prepared work:

1. classify current paths into green, yellow, and red confidence lanes;
2. prepare several coherent packets ahead, commonly 5-15 when scope permits;
3. validate independent packets concurrently and drain ready packets through serial HEAD updates;
4. re-snapshot after the wave and refresh only overlapping, newly landed, or invalidated paths;
5. repeat while any commit-ready or safely investigable source work remains.

Green packets proceed immediately. Yellow investigation and red exclusions must not idle unrelated green work. Maintain a compact in-memory queue containing each packet's intent, owner, exact paths/hunks, dependencies, message, validation, and confidence. If many valid paths remain but the ready queue is empty, reconnaissance has failed and must resume rather than ending the campaign.

Parallelize reconnaissance, history/provenance checks, message preparation, and independent validation. Keep final packet adjudication, private-index creation, CAS HEAD updates, and shared-index synchronization under one serial authority by default. Parallel commit writers are exceptional: private indexes isolate staging but not history, so CAS retries and overlap recovery can cost more than they save.

5. Form coherent change packets

Group by one reviewable intent, invariant, migration, or user outcome, not by arbitrary path count. Include the complete slice needed to understand and verify that intent:

• canonical implementation and its directly coupled adapters;
• tests that define the behavior;
• required fixtures, types, schemas, migrations, and compatibility handling;
• consumed wiring and narrowly coupled documentation;
• tracked generated output only when the repository contract requires it.

Prefer useful batches, commonly 5-50 files and sometimes larger for uniform mechanical migrations, provider matrices, icon replacements, snapshots, or generated-contract updates. File count is a throughput heuristic, never permission to mix unrelated work. Avoid one-file commits when nearby changes complete the same idea, but keep a truly self-contained one-file correction separate.

Split a file by hunk when its changes serve different intents. Do not force an entire mixed file into the first convenient group.

Order packets by dependency: contracts and shared owners before consumers, implementation with defining tests, migrations before cleanup, and mechanical follow-ups after behavior is established.

6. Reject dumping grounds and unwanted material

Before staging an unfamiliar path, determine what produced it and whether it belongs in source control. Use current bytes, repository references, ignore rules, tracked history, build scripts, test harnesses, and timestamps as evidence. Typical exclusions include:

• build products, caches, compiler output, vendored downloads, archives, and oversized binaries;
• .tmp*, .vite-node, probes, logs, screenshots, recordings, coverage, evidence, and QA captures;
• local credentials, machine state, private diagnostics, and uploads;
• semantic no-ops, accidental formatting, obsolete scratch code, and speculative dormant mechanisms;
• tests or helpers whose production owner was removed unless the deletion itself is intentional and coherent.

Do not delete uncertain paths as part of committing. Leave them uncommitted and report why. Add a narrow ignore rule when the producer is legitimate, recurrence is likely, and the path class is never source material. Do not hide a tracked source path or broad directory merely to make status disappear.