Decompose And Commit Unstaged Changes

Decompose and Commit Unstaged Changes

Orchestrate the decomposition of unstaged working-tree changes into a clean commit series through three phases, each delegated to a specialized agent. When requested, polish an already-built commit series without re-running the decomposition phases.

Usage

/decompose-and-commit-unstaged-changes
/decompose-and-commit-unstaged-changes deconstruct
/decompose-and-commit-unstaged-changes reconstruct
/decompose-and-commit-unstaged-changes resume
/decompose-and-commit-unstaged-changes history-polish BASE_SHA

Without an argument, run all three phases end to end. With deconstruct, run Phases 1-2 only. With reconstruct, assume batches already exist and run Phase 3 only. With resume, inspect the workspace-local workflow state directory, batch refs, and the current HEAD, then continue from the latest phase whose gate can still be proven. With history-polish, assume the final tree is already committed and rewrite only the existing commit series between the explicit BASE_SHA and HEAD; do not read an old checkpoint to choose the base for a fresh history-polish run.

This skill is autonomous and non-interactive. Do not ask the user to review intermediate steps.

If git-stage-batch is available directly in PATH, use it. If not, fall back to pipx run git-stage-batch.

Before using any git-stage-batch command, read the installed command documentation for the top-level command and every subcommand you intend to use. The installed man pages/help output are the authority. Do not invent subcommands, selectors, flags, or argument shapes from memory.

git-stage-batch --help
git-stage-batch start --help
git-stage-batch show --help
git-stage-batch status --help
git-stage-batch include --help
git-stage-batch discard --help
git-stage-batch apply --help
git-stage-batch reset --help
git-stage-batch again --help
git-stage-batch stop --help
git-stage-batch list --help
git-stage-batch drop --help
git-stage-batch block-file --help
git-stage-batch suggest-fixup --help

If a command or option is not shown by the installed documentation, do not use it. If the skill text and installed help disagree, follow the installed help and report the discrepancy.

Use the checkpoint helper for every mode. First move to the repository root, create the workspace-local state directory, and locally block it from git-stage-batch review:

REPO_ROOT=$(git --no-optional-locks rev-parse --show-toplevel)
cd "$REPO_ROOT"
export DECOMPOSE_STATE_DIR=$(python .claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py state-dir)
mkdir -p "$DECOMPOSE_STATE_DIR"
git-stage-batch block-file --local-only .git-stage-batch/
python .claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py status

Before a full run or a deconstruct run, check for stale batch state:

git-stage-batch status
git-stage-batch list

If a session is active or git-stage-batch list shows preexisting decompose-* batches, stop and report the stale state before Phase 1. Do not fold old batches into a new plan. In reconstruct mode, existing batches are allowed only because they are the requested input, and Gate 2 must still pass. In resume mode, existing batches are potential checkpoint state, not stale by default. They must still pass Gate 2 before Phase 3.

Before a full run or a deconstruct run, also treat any existing decompose-plan.json and decompose-narrative.md in the workflow state directory as stale output from another attempt. Phase 1 must not read them as input. Remove any old candidate and narrative files before analysis; the final plan is overwritten only after the candidate passes Gate 1:

python - <<'PY'
import subprocess
from pathlib import Path
state_dir = Path(subprocess.check_output(
    ["python", ".claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py", "state-dir"],
    text=True,
).strip())
state_dir.mkdir(parents=True, exist_ok=True)
(state_dir / "decompose-plan.candidate.json").unlink(missing_ok=True)
(state_dir / "decompose-plan.json").unlink(missing_ok=True)
(state_dir / "decompose-narrative.md").unlink(missing_ok=True)
(state_dir / "decompose-refinement.md").unlink(missing_ok=True)
PY

For a fresh full or deconstruct run, record the new checkpoint immediately after recording the base commit:

python .claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py start --mode full --base "$BASE_SHA"

Use --mode deconstruct instead of --mode full for a deconstruct run.

Resume Mode

resume is conservative. It may reuse artifacts only after re-running the gate that proves those artifacts are valid for the current tree.

Start with:

REPO_ROOT=$(git --no-optional-locks rev-parse --show-toplevel)
cd "$REPO_ROOT"
export DECOMPOSE_STATE_DIR=$(python .claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py state-dir)
mkdir -p "$DECOMPOSE_STATE_DIR"
git-stage-batch block-file --local-only .git-stage-batch/
python .claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py status --json
git --no-optional-locks status --short
git --no-optional-locks log --oneline -20

Then choose the resume point:

1. If resume_target is gate1, rerun Gate 1 against $DECOMPOSE_STATE_DIR/decompose-plan.candidate.json. If Gate 1 passes, promote the plan and continue to Phase 2. If Gate 1 fails, discard the candidate/narrative as stale analysis output and rerun Phase 1.
2. If resume_target is phase2-after-gate1, rerun Gate 1 against the current plan. If it passes, continue Phase 2. If it fails, rerun Phase 1.
3. If resume_target is phase3-after-gate2, rerun Gate 2 from refs. If it passes, continue Phase 3 with remaining batches. If it fails, return to Phase 2 and fix the batch plan before rebuilding.
4. If resume_target is gate3-or-manual-audit, rerun Gate 3 and the committed-snapshot verification loop before reporting success. If any batch refs remain, prefer phase3-after-gate2 instead.
5. If resume_target is fresh, run the normal full workflow from Phase 1.

Do not treat a candidate plan plus narrative as sufficient progress by itself. Candidate artifacts are resumable only through Gate 1. A failed Gate 1 means the prior analysis was not a checkpoint; it was a rejected draft.

After every successful gate or phase transition, run:

python .claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py mark --phase PHASE-NAME

History-Polish Mode

history-polish is a targeted rewrite mode for a series that has already been rebuilt and committed. It does not run Phase 1 analysis, Phase 2 deconstruction, or Phase 3 batch application. Its only job is to improve the existing commit series so it reads like a natural incremental evolution while preserving the final tree exactly.

Use this mode when the final HEAD tree is correct but the series still has broad snapshot commits, late repair/process commits, generic artifact-shaped subjects, docs-before-code commits, implementation-only runs followed by test-only runs, or other narrative problems. This mode is also the resumable entry point for rerunning only the final split and repair-integration stages after an earlier full run was interrupted.

Start from the repository root, block workflow state from batch review, and read the installed git-stage-batch help before using any batch command:

REPO_ROOT=$(git --no-optional-locks rev-parse --show-toplevel)
cd "$REPO_ROOT"
export DECOMPOSE_STATE_DIR=$(python .claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py state-dir)
mkdir -p "$DECOMPOSE_STATE_DIR"
git-stage-batch block-file --local-only .git-stage-batch/
python .claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py status --json
git-stage-batch --help
git-stage-batch start --help
git-stage-batch show --help
git-stage-batch include --help
git-stage-batch stop --help
git-stage-batch status --help
git-stage-batch list --help

Determine the base of the series from the explicit BASE_SHA argument. Fresh history-polish must not read an old checkpoint, history-polish-* file, narrative, plan, audit, or review artifact before the fresh start step clears the state directory. Existing state files are contaminated inputs from another attempt, not context for the current polish run. If no base argument was supplied, stop and ask for BASE_SHA; do not guess from branch names, old refs, reflog entries, or checkpoint state.

if test -z "${BASE_SHA:-}"; then
  echo "history-polish requires BASE_SHA; rerun as history-polish BASE_SHA"
  exit 1
fi
git --no-optional-locks merge-base --is-ancestor "$BASE_SHA" HEAD

Require a clean tree and no stale batch session before rewriting history:

git --no-optional-locks status --short
git-stage-batch list
git-stage-batch status

If any command reports pending work, active state, or stale decompose-* batches, stop and report the blocker. Do not start history polishing while ordinary working-tree changes or old batch refs are present.

Start a fresh checkpoint before reading or writing any state artifacts. The start command clears stale files in .git-stage-batch/ for non-resume modes; that cleanup is intentional. Only after that fresh start should this run record the tree and series it is about to preserve:

python .claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py start --mode history-polish --base "$BASE_SHA"
git --no-optional-locks rev-parse HEAD^{tree} > "$DECOMPOSE_STATE_DIR/history-polish-pre-tree.txt"
git --no-optional-locks rev-list --count "$BASE_SHA"..HEAD > "$DECOMPOSE_STATE_DIR/history-polish-pre-count.txt"
git --no-optional-locks log --reverse --format='%H %s' "$BASE_SHA"..HEAD > "$DECOMPOSE_STATE_DIR/history-polish-pre-series.txt"
python .claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py mark --phase history-polish-running --note "starting history polish"

Before judging commits, generate a pressure list of commits that are presumed split candidates. Do not rely on intuition or subject lines alone:

python - "$BASE_SHA" <<'PY' > "$DECOMPOSE_STATE_DIR/history-polish-pressure-list.txt"
import re
import subprocess
import sys

base = sys.argv[1]
log = subprocess.check_output(
    ["git", "--no-optional-locks", "log", "--reverse", "--format=%H%x00%s", f"{base}..HEAD"],
    text=True,
)
for line in log.splitlines():
    if not line:
        continue
    sha, subject = line.split("\x00", 1)
    stat = subprocess.check_output(
        ["git", "--no-optional-locks", "show", "--shortstat", "--format=", "--find-renames", sha],
        text=True,
    )
    names = subprocess.check_output(
        ["git", "--no-optional-locks", "show", "--name-only", "--format=", "--find-renames", sha],
        text=True,
    ).splitlines()
    files = insertions = deletions = 0
    m = re.search(r"(\d+) files? changed", stat)
    if m:
        files = int(m.group(1))
    m = re.search(r"(\d+) insertions?", stat)
    if m:
        insertions = int(m.group(1))
    m = re.search(r"(\d+) deletions?", stat)
    if m:
        deletions = int(m.group(1))
    reasons = []
    if insertions + deletions >= 500:
        reasons.append(f"{insertions + deletions} changed lines")
    if files >= 10:
        reasons.append(f"{files} files")
    if re.search(r"\b(Add|Register|Cover|Scaffold|Invoke|Wire|Expand)\b", subject, re.I):
        reasons.append("artifact/action-shaped subject")
    if any(re.search(r"(^docs?/|README|examples/|tests?/|workflows?|cli|build|pyproject|setup|Makefile)", p) for p in names):
        reasons.append("docs/tests/orchestration/build surface")
    if reasons:
        print(f"{sha[:12]} {subject} :: {'; '.join(reasons)}")
PY

Then run the polish in three passes:

1. Final evolution split audit. Inspect every commit in BASE_SHA..HEAD in order. For each commit, record keep, split, reword, or integrate in $DECOMPOSE_STATE_DIR/history-polish-audit.md, with the concrete reason and the smaller product state that should exist after any replacement commit. Use the Split a broad committed snapshot procedure below for every split candidate. Every commit in history-polish-pressure-list.txt starts as split until proven otherwise. A keep verdict for one of those commits is valid only when the audit lists the concrete split probes considered and the exact immediate breakage or narrative regression each probe would cause. Also reconcile the subject and body against the patch: every meaningful helper, result field, fixture family, REST surface, data model, CLI branch, docs section, and build hook must be either the named outcome of the commit, required support for that named outcome, or a separate outcome that needs a later replacement commit. A narrow subject does not make unmentioned patch content part of the same concern. Vague explanations such as "single behavior", "same module", "one module", "same function", "one function", "one entry point", "single CLI entry point", "fixture set", "tests belong together", "tests for one module", "tests for one function", "coherent unit", "shared helper", "large but related", "single pipeline", "one pipeline", "same pipeline", "full pipeline", "execution pipeline", "artificial subdivision", "no meaningful subdivision", "across its variants", or "all stages" are failed audit entries.

   A pipeline, function, module, command, test file, or fixture tree is not a concern boundary by itself. If a pressured keep claims that a patch is one pipeline, one function, or one module, the audit must name the smallest first runnable version of that pipeline/function/module, then list each later enrichment, adopter, variant, error path, docs section, fixture, and proof that could land after the spine. If any later item can be added while the earlier spine still builds and passes its narrow proof, split it. A keep is valid only when every proposed later item would immediately break the committed snapshot or make the history less coherent in a concrete, path-specific way.

   After any rewrite, restart the audit from the beginning because later SHAs and dependencies have changed. Use this shape for pressured keeps:

   #### SHA subject
   - Verdict: KEEP
   - Pressure: 1530 changed lines; tests/orchestration surface
   - Smallest runnable spine: parser setup plus one executor assertion that
     proves the command dispatches a minimal request.
   - Later enrichments checked: fixture builders, second executor mode,
     error-path assertions, docs examples.
   - Split probes considered:
     1. Move parser setup before executor assertions.
        Immediate breakage: test file imports helper X that is introduced by the
        executor assertion block on the same commit; separating would require a
        new smaller helper commit, so create that helper split first or keep is
        invalid.
     2. Move fixture builders before lookaside assertions.
        Immediate breakage: no breakage; split this commit.
   - Result: SPLIT because probe 2 is independently coherent.
   

   A pressured keep with any "no breakage" probe is not a keep; split it. A pressured keep that does not name a smallest runnable spine and later enrichments is not a keep; continue splitting.

2. Repair/process integration. Scan the full range for commits that restore, repair, clean up, compensate for decomposition, or mention process mechanics. Use the Integrate late repair commits procedure below to amend each hunk into the earlier commit where it first belonged, then drop the repair/process commit. If a hunk cannot be placed confidently, fail the workflow instead of keeping a repair commit.

3. Subject and narrative cleanup. Reword subjects that describe artifacts instead of outcomes, contain multiple actions, contain and, also, as well as, or a semicolon, or hide multiple behaviors behind a generic summary. Reword with an edit stop so the replacement subject can be checked against the actual patch:

BASE_SHA=PUT_BASE_SHA_HERE
BAD_SHA=PUT_COMMIT_WITH_BAD_SUBJECT_HERE
BAD_SHORT=$(git rev-parse --short=7 "$BAD_SHA")
GIT_SEQUENCE_EDITOR="sed -i -E 's/^pick (${BAD_SHORT}[0-9a-f]*) /edit \\1 /'" git rebase -i "$BASE_SHA"
git --no-optional-locks show --stat --patch --find-renames HEAD
NEW_SUBJECT='PUT_SINGLE_OUTCOME_SUBJECT_HERE'
git commit --amend -m "$NEW_SUBJECT"
python .claude/skills/decompose-and-commit-unstaged-changes/scripts/verify-head-snapshot.py --ref HEAD -- python -m compileall -q src tests
git rebase --continue

After every split, integration, or reword, rerun the relevant verification loop over the changed committed snapshots. Do not continue with a failing intermediate commit just because the final tree will be fixed later.

Before reporting success, reject weak audit language, rerun Gate 3 in full, and verify that the final tree did not change:

python - <<'PY'
import os
import re
import sys
from pathlib import Path

audit = Path(os.environ["DECOMPOSE_STATE_DIR"]) / "history-polish-audit.md"
text = audit.read_text(encoding="utf-8")
weak = re.compile(
    r"\b(single behavior|same module|one module|same function|one function|"
    r"one entry point|single CLI entry point|fixture set|tests belong together|"
    r"tests for one module|tests for one function|coherent unit|shared helper|"
    r"large but related|single pipeline|one pipeline|same pipeline|"
    r"full pipeline|execution pipeline|artificial subdivision|"
    r"no meaningful subdivision|across its variants|all stages)\b",
    re.I,
)
matches = [line for line in text.splitlines() if weak.search(line)]
if matches:
    print("history-polish audit has weak keep rationale; split or write concrete immediate breakage")
    print("\n".join(matches[:20]))
    sys.exit(1)
blocks = re.split(r"\n####\s+", text)
missing_spine = []
for block in blocks:
    if "Verdict: KEEP" not in block or "Pressure:" not in block:
        continue
    if not re.search(r"\b(pipeline|function|module|command|entry point|test file|fixture tree)\b", block, re.I):
        continue
    if not re.search(r"Smallest runnable", block, re.I):
        missing_spine.append(block.splitlines()[0][:160])
if missing_spine:
    print("pressured keep lacks Smallest runnable spine analysis:")
    print("\n".join(missing_spine[:20]))
    sys.exit(1)
PY
test "$(git --no-optional-locks rev-parse HEAD^{tree})" = "$(cat "$DECOMPOSE_STATE_DIR/history-polish-pre-tree.txt")"
git --no-optional-locks rev-list --count "$BASE_SHA"..HEAD > "$DECOMPOSE_STATE_DIR/history-polish-post-count.txt"
git --no-optional-locks log --reverse --format='%H %s' "$BASE_SHA"..HEAD > "$DECOMPOSE_STATE_DIR/history-polish-post-series.txt"
python .claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py mark --phase history-polish-complete --note "history polish passed"

The completion report for this mode must include the original commit count, the final commit count, which commits were split, which repair/process commits were integrated or dropped, which subjects were reworded, which pressured commits were kept with exact breakage reasons, and the validation commands that passed.

Operating Contract

These rules override any conflicting behavior. They apply to all phases.

• A concern is a product, workflow, or architectural capability — not an artifact category.
• The primary deliverable is a believable evolving history where each commit reads like the next step a maintainer could have taken.
• Before choosing concern boundaries, build a simplified-project evolution ladder. Each ladder step names the smaller product that would exist after that step, the regions/tests that prove it, and the future content that must not appear yet. Concerns and rebuild commits must trace back to this ladder.
• After drafting concerns, run a concern refinement pass before Gate 1. Inspect every concern as if it were an incoming batch. Expand its expected_commits, internal_slices, files_wholly_owned, and shared regions into plausible smaller concerns. If any smaller concern would be coherent, promote it into the concern list before batching. Do not leave independently useful behaviors hidden inside expected_commits or internal_slices.
• Write transient decomposition artifacts under the workspace-local workflow state directory printed by decompose-checkpoint.py state-dir. The default is $REPO_ROOT/.git-stage-batch/, not .git, .claude, or /var/tmp. At the start of every run, create that directory and run git-stage-batch block-file --local-only .git-stage-batch/ before writing state. Override with DECOMPOSE_STATE_DIR only when needed.
• Before writing JSON, write decompose-narrative.md in that workflow state directory. The narrative must describe the current committed HEAD in detail, the final working tree in detail, and how each module, command, test file, docs section, build file, or fixture tree that already exists at HEAD evolves. For each new file, it must describe the smallest first version and later growth.
• The narrative must describe changes, not only additions. For every existing committed code path, command, test, docs section, build file, or fixture surface that is touched, say how the existing thing changes at each relevant step and which final-tree content is still absent.
• Every intermediate HEAD must be coherent. Do not create a commit that knowingly leaves an import, parser, registry, submodule, or tested entry point broken for a later commit to repair.
• An adopter cannot land before the behavior it adopts. CLI handlers, parser entries, docs sections, examples, and coordinators must not rely on call-time imports, untested branches, placeholders, or future providers to be coherent. High-level user workflows land after the lower operations they invoke.
• Final module-level imports are not hard dependency constraints. Imports, __all__ entries, parser registrations, dispatch tables, registry rows, and docs indexes must evolve with the concern that first uses each symbol or entry. Do not force a provider to land early merely because the final file imports it at top level.
• Shared infrastructure is not a keep-together reason. It is the reason to create an earlier scaffold concern, followed by one consumer, provider, workflow, command branch, or result shape at a time.
• Do not create broad foundation/core/infrastructure buckets. Independent no-import utilities, model records, enforcement hooks, replay paths, and test groups still land one first-consumer behavior at a time.
• Every concern batch must also be coherent as a replayable unit. During deconstruction, validate the batch ref itself before moving on; a remaining working tree can be repaired while the batch still contains a partial parser call, partial test, or other unrebuildable slice.
• Distinguish ownership from shared syntax context. Use discard --to for the current concern's owned lines. Use include --to to copy shared wrappers, neighboring entries, or aggregation context needed for the batch to parse; copied context does not become part of the concern.
• Commit subjects must name one action in one clause. If the subject contains and, also, as well as, a semicolon, or two independent actions, the commit must be split.
• A generic subject is not a loophole. If expanding the staged diff into concrete items reveals multiple independently useful behaviors, split the commit even when the subject itself is short and grammatical.
• A complete file, module, test suite, coordinator, or docs section is not a concern by default. If it looks like a finished subsystem copied from the final tree, split it into the ladder steps by which the subsystem could have grown.
• A pipeline, function, module, command, test file, or fixture tree is not a concern by default. First commit the smallest runnable spine that has a coherent product outcome and narrow proof. Later enrichments, variants, adopters, error paths, docs sections, fixtures, and tests land as subsequent commits unless moving them later would immediately break a committed snapshot in a concrete, path-specific way.
• Do not mention decomposition, batches, repairs, peeling, reconstruction, or process mechanics in commit messages.
• Scale is not a split criterion. Hundreds of tool calls means the work is large, not that the split should be broadened.
• Pragmatic shortcuts are false economy. "Good enough for now", broad grouping to save time, shared-region-only ownership, deferred tests, future repair commits, and vague summaries will fail the gates and force the work to be repeated with more context spent. Get the concern boundary, batch boundary, and commit boundary right the first time.
• git-stage-batch apply --from BATCH restores batch content to the working tree only. It does not stage anything. During rebuild, treat the restored content as an unstaged diff, then stage commit-sized slices with the same care used by commit-unstaged-changes.
• The staging primitive for this workflow is git-stage-batch include. Do not use Git's native interactive, partial, path, or whole-tree staging to assemble commit slices. Plain git add is reserved only for marking manually resolved rebase conflicts, not for ordinary commit construction. When the right historical snapshot is clearer as a rewritten file than as selected original hunks, stage that intentional snapshot with git-stage-batch include --file PATH --as-stdin; it is still a git-stage-batch include operation and must be audited as one atomic commit.
• Before choosing git-stage-batch syntax, re-check the relevant installed subcommand help. Never use a guessed git-stage-batch command, flag, or selector; the command must be present in the help/man page you just read.
• Do not describe apply --from as applying to the index. If a batch should be staged directly, the command family is include --from; do not use that shortcut during this workflow unless there is a deliberate reason and the resulting staged diff is still audited as one atomic commit.
• A fresh end-to-end run must not reuse old decompose-* batches or an old git-stage-batch session. Stale batches are inputs from another attempt, not evidence for the current decomposition.

Git Command Concurrency

Always pass --no-optional-locks to read-only git commands (status, diff, log, show, ls-tree). Without it, parallel git commands race for .git/index.lock.

Phase 1: Analysis

Record the base commit for later reference:

BASE_SHA=$(git --no-optional-locks log --format='%H' -1)
python .claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py start --mode full --base "$BASE_SHA"

For a deconstruct run, use --mode deconstruct. For a resume run that reruns Phase 1, use --mode resume and keep the original checkpoint base if one exists.

Spawn Agent(decompose-analyzer) with this prompt:

Analyze the unstaged working tree and produce a structured concern plan. Compute DECOMPOSE_STATE_DIR with python .claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py state-dir. First write $DECOMPOSE_STATE_DIR/decompose-narrative.md: a prose evolution narrative from the current committed state to the final working tree. Describe the current committed state in detail, the final working tree in detail, the beginning/middle/end of the history, how each module, command, test file, docs section, build file, or fixture tree that already exists at HEAD evolves, including a required Existing Surface Evolution table for every touched committed path, and the smallest first version of each new file in a required New Surface Growth table. Treat final module-level imports, registries, parser tables, dispatch maps, and docs indexes as evolving surfaces, not fixed constraints from the final tree; describe them in a required Aggregation Evolution table. Then write a simplified-project evolution ladder. Derive concern boundaries from that narrative and ladder instead of from final file/module boundaries. Run a concern refinement pass before writing the final candidate: for every concern, review its expected commits, internal slices, whole-file claims, shared regions, docs, tests, fixtures, and CLI/build/parser changes as possible sub-concerns. Split any independently coherent behavior into a new concern. Write $DECOMPOSE_STATE_DIR/decompose-refinement.md with the before/after concern list and the exact immediate breakage for every retained keep-together decision. Do not read any existing $DECOMPOSE_STATE_DIR/decompose-plan.json as input. Write only $DECOMPOSE_STATE_DIR/decompose-plan.candidate.json; replace that candidate path if it already exists. After writing the narrative and candidate plan, run python .claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py mark --phase phase1-candidate --note "candidate plan written". The current base commit is {BASE_SHA}.

Concern Refinement Pass

Before Gate 1 promotion, the candidate must pass a refinement pass. This pass prevents broad batches from surviving by hiding smaller behaviors inside expected_commits, internal_slices, or whole-file ownership.

Read $DECOMPOSE_STATE_DIR/decompose-plan.candidate.json and $DECOMPOSE_STATE_DIR/decompose-narrative.md, then verify every concern:

1. Expand each expected_commits entry into a candidate sub-concern. If two entries would each leave a coherent product state, split the concern.
2. Expand every internal_slices entry into a candidate sub-concern. If a slice has its own proving tests, user-visible result, parser branch, provider variant, fixture path, data record, or docs section, split it.
3. Treat files_wholly_owned as suspicious, not reassuring. Large source, test, docs, coordinator, fixture, and orchestration files must evolve through concerns unless generated or data-only.
4. For each shared file region, ask whether the region is owned behavior or only syntax context. Owned behavior becomes a concern; context stays include-only.
5. Rewrite the candidate so the concern list, peel order, rebuild order, evolution ladder, dependencies, and narrative milestones reflect the refined concerns.
6. Write $DECOMPOSE_STATE_DIR/decompose-refinement.md with one section per original concern: original purpose, proposed sub-concerns, promoted sub-concerns, retained keep-together decisions, and exact immediate breakage for each retained decision.

internal_slices are allowed only as a scalpel map for one retained concern that truly cannot be made coherent as smaller concerns. They are not a substitute for concern splitting.

Gate 1: Validate the concern plan

After Phase 1 completes, read $DECOMPOSE_STATE_DIR/decompose-narrative.md and $DECOMPOSE_STATE_DIR/decompose-plan.candidate.json, then run this mechanical validator before doing any subjective review:

Run this validator exactly as written against the candidate path. Do not substitute an older validator, a shorter validator, or validation against $DECOMPOSE_STATE_DIR/decompose-plan.json.

python - <<'PY'
import json, re, subprocess, sys
from pathlib import Path
state_dir = Path(subprocess.check_output(
    ["python", ".claude/skills/decompose-and-commit-unstaged-changes/scripts/decompose-checkpoint.py", "state-dir"],
    text=True,
).strip())
narrative_path = state_dir / "decompose-narrative.md"
if not narrative_path.exists():
    print(f"- missing {narrative_path}", file=sys.stderr)
    sys.exit(1)
narrative = narrative_path.read_text(encoding="utf-8")
refinement_path = state_dir / "decompose-refinement.md"
if not refinement_path.exists():
    print(f"- missing {refinement_path}", file=sys.stderr)
    sys.exit(1)
refinement = refinement_path.read_text(encoding="utf-8")
if len(refinement.strip()) < 200 or not re.search(r"\b(promoted sub-concerns|retained keep-together|expected_commits|internal_slices)\b", refinement, re.I):
    print(f"- {refinement_path} does not look like a real concern refinement audit", file=sys.stderr)
    sys.exit(1)
required_sections = [
    "Current Committed State",
    "Final Working Tree State",
    "Existing Surface Evolution",
    "New Surface Growth",
    "Aggregation Evolution",
    "Beginning",
    "Middle",
    "End",
    "Forbidden Shortcuts Found",
]
narrative_bad = [
    section for section in required_sections
    if not re.search(rf"^#+\s+{re.escape(section)}\s*$", narrative, re.M)
]
if narrative_bad:
    print(
        "\n".join(f"- narrative missing section: {section}" for section in narrative_bad),
        file=sys.stderr,
    )
    sys.exit(1)

def section_body(text, heading):
    match = re.search(rf"^#+\s+{re.escape(heading)}\s*$", text, re.M)
    if match is None:
        return ""
    rest = text[match.end():]
    next_heading = re.search(r"^#+\s+\S.*$", rest, re.M)
    return rest[: next_heading.start()] if next_heading else rest

existing_surface_section = section_body(narrative, "Existing Surface Evolution")
new_surface_section = section_body(narrative, "New Surface Growth")
aggregation_section = section_body(narrative, "Aggregation Evolution")
middle_section = section_body(narrative, "Middle")
plan = json.load(open(state_dir / "decompose-plan.candidate.json", encoding="utf-8"))
plan_text = json.dumps(plan, sort_keys=True)
bad = []
try:
    modified_existing_paths = subprocess.check_output(
        ["git", "--no-optional-locks", "diff", "--name-only", "--diff-filter=M", "HEAD"],
        text=True,
    ).splitlines()
    added_paths = subprocess.check_output(
        ["git", "--no-optional-locks", "diff", "--name-only", "--diff-filter=A", "HEAD"],
        text=True,
    ).splitlines()
    untracked_paths = subprocess.check_output(
        ["git", "--no-optional-locks", "ls-files", "--others", "--exclude-standard", "--directory"],
        text=True,
    ).splitlines()
    added_paths = sorted(set(added_paths + untracked_paths))
except subprocess.CalledProcessError as exc:
    bad.append(f"failed to inspect working tree paths: {exc}")
    modified_existing_paths = []
    added_paths = []

large_new_code_paths = []
for path in added_paths:
    path_obj = Path(path)
    if path_obj.exists() and path_obj.is_file() and path.endswith((".py", ".pyi")):
        try:
            line_count = len(path_obj.read_text(encoding="utf-8", errors="ignore").splitlines())
        except OSError:
            line_count = 0
        if line_count > 600:
            large_new_code_paths.append((path, line_count))

def is_new_surface_path(path):
    if path.startswith(".git/"):
        return False
    if path == ".gitmodules":
        return True
    if path.endswith("/"):
        return path.startswith(("examples/", "docs/", "src/", "tests/"))
    return path.endswith((".py", ".md", ".toml", ".json", ".yaml", ".yml"))

for path in modified_existing_paths:
    if path not in existing_surface_section:
        bad.append(f"Existing Surface Evolution missing modified HEAD path: {path}")
for path in added_paths:
    if path not in new_surface_section and is_new_surface_path(path):
        bad.append(f"New Surface Growth missing added surface: {path}")
module_catalog_headings = re.findall(
    r"^#{3,}\s+.*\.(?:py|md|toml|json|ya?ml)\b",
    middle_section,
    re.M,
)
if len(module_catalog_headings) >= 5:
    bad.append("Middle looks like a file/module catalog; make Middle historical-step prose")
for paragraph in re.split(r"\n\s*\n", middle_section):
    file_mentions = re.findall(r"\b[\w./-]+\.(?:py|md|toml|json|ya?ml)\b", paragraph)
    if len(set(file_mentions)) >= 5:
        bad.append("Middle paragraph bundles too many files; split it into behavior steps")
    variants = set(re.findall(r"\b(triage|backport|rebase|rebuild)\b", paragraph, re.I))
    if len(variants) > 1:
        bad.append("Middle paragraph bundles multiple workflow variants")
if re.search(
    r"\b(call[- ]time imports?|imported at call time|lazy imports?|placeholder|"
    r"untested branches?|future providers?|primary user workflow)\b",
    narrative + "\n" + plan_text,
    re.I,
):
    bad.append("Plan uses call-time imports, placeholders, untested branches, future providers, or primary-workflow priority as a coherence excuse")
if re.search(r"\b(foundation|core|infrastructure)\s+(layer|bucket)\b", middle_section, re.I):
    bad.append("Middle uses a broad foundation/core/infrastructure bucket")
if modified_existing_paths and "|" not in existing_surface_section:
    bad.append("Existing Surface Evolution must use a table with step, before, change, and absent columns")
if added_paths and "|" not in new_surface_section:
    bad.append("New Surface Growth must use a table with step, smallest version, first consumer/test, and absent columns")
if "|" not in aggregation_section:
    bad.append("Aggregation Evolution must use a table for imports, parser registrations, registries, dispatch maps, and docs indexes")
raw_concerns = plan.get("concerns", [])
if not isinstance(raw_concerns, list):
    bad.append("concerns must be a list")
    raw_concerns = []
raw_ladder = plan.get("evolution_ladder", [])
if not isinstance(raw_ladder, list) or not raw_ladder:
    bad.append("evolution_ladder must be a non-empty list")
    raw_ladder = []
ladder_steps = []
ladder_region_paths = set()
modified_ladder_paths = set()
for i, step in enumerate(raw_ladder, 1):
    if not isinstance(step, dict):
        bad.append(f"evolution_ladder entry {i} must be an object")
        continue
    step_no = step.get("step")
    if not isinstance(step_no, int):
        bad.append(f"evolution_ladder entry {i}: step must be an integer")
    else:
        ladder_steps.append(step_no)
    for key in ("behavior_after", "why_next_simplest"):
        if not isinstance(step.get(key), str) or not step.get(key, "").strip():
            bad.append(f"evolution_ladder entry {i}: missing {key}")
    for key in ("regions_introduced_or_evolved", "tests", "must_not_appear_yet"):
        value = step.get(key)
        if not isinstance(value, list) or not value:
            bad.append(f"evolution_ladder entry {i}: {key} must be a non-empty list")
    regions = step.get("regions_introduced_or_evolved")
    if isinstance(regions, list):
        for j, region in enumerate(regions, 1):
            if not isinstance(region, dict):
                bad.append(f"evolution_ladder entry {i}: region {j} must be an object")
                continue
            for key in ("path", "anchor", "change_kind", "before_state", "after_state", "still_absent"):
                if key == "still_absent":
                    if not isinstance(region.get(key), list):
                        bad.append(f"evolution_ladder entry {i}: region {j} still_absent must be a list")
                elif not isinstance(region.get(key), str) or not region.get(key, "").strip():
                    bad.append(f"evolution_ladder entry {i}: region {j} missing {key}")
            path = region.get("path")
            if isinstance(path, str):
                ladder_region_paths.add(path)
            change_kind = region.get("change_kind")
            if change_kind not in {"introduced", "modified-from-head", "modified-from-earlier"}:
                bad.append(f"evolution_ladder 

…(truncated)