Restructure Commits by Component

Rewrite a feature branch into one commit per architectural group (API, Dependencies, Vendor, CLI, HO, CPO, E2E, Docs, Tooling) without changing the branch's final file content.

This is the canonical, model-neutral procedure. Any coding agent or human can follow it with git, python3 (standard library only), make, and optionally gh. All paths are relative to the repository root.

When to Use

• The user asks to "redo", "restructure", "squash by component", or "organize" commits
• Preparing a branch for PR review, or cleaning history after addressing review comments

Ownership

ownership.json maps every path to a group; commit_layout.py applies it. Both the file and the table below are generated by generate_ownership.py (make ownership-rules, also run by make update); never edit them by hand. Commit groups in this order and skip groups with no changes:

• Derived, not curated. Each binary built by make build belongs to the group in the generator's policy, and other top-level Go directories follow the binaries that import them (several groups: HO; none: Tooling). Files marked as generated, Makefile output directories, and vendor trees go to Vendor; hand-written files inside them keep their component's group.
• First match wins. Specific exceptions are listed before broad directories; ownership.json lists the rules in precedence order with the reason for each.
• Modules vs generated trees: api/go.mod and api/go.sum stay in API; root, tools, and workspace module files go in Dependencies; every vendor tree goes in Vendor. A commit must never mix module definitions with vendor output.
• Tests and fixtures: component tests, testdata/, and zz_fixture_* files stay with their owning component. Only test/, api/**/*_test.go, and CRD envtest suites go to E2E.
• No silent defaults: an unclassified path blocks the rewrite. Run make ownership-rules, which gives every path in the checkout a group, and commit the result before the snapshot. If a derived group is wrong, agree the right one with the user and change the generator's policy (see Maintenance).
• Several consecutive commits in the same group are allowed; groups must never interleave or appear out of order.

Procedure

TOOL=skills/restructure-commits/commit_layout.py

1. Preflight (read-only except for the backup branch)

1. Resolve the real target. Determine the PR base repository and branch, for example from gh pr view --json url,baseRefName; ask the user when there is no PR. Pick the remote whose URL points at that base repository and the remote that hosts the PR branch. Do not assume remote names, do not assume main (release branches are valid targets), and do not rebase unless the user asks for it.

   BRANCH=$(git symbolic-ref --short HEAD)
   TARGET_REMOTE=<remote for the PR base repository>
   TARGET_BRANCH=<PR base branch, e.g. main or release-4.18>
   PUSH_REMOTE=<remote that hosts $BRANCH>
   git fetch "$TARGET_REMOTE" "refs/heads/$TARGET_BRANCH"
   MERGE_BASE=$(git merge-base FETCH_HEAD HEAD)
   PUSHED_SHA=$(git ls-remote "$PUSH_REMOTE" "refs/heads/$BRANCH" | cut -f1)   # empty if never pushed
   if [ -n "$PUSHED_SHA" ]; then
     git fetch "$PUSH_REMOTE" "refs/heads/$BRANCH"
     git merge-base --is-ancestor "$PUSHED_SHA" HEAD || echo "STOP: remote $BRANCH has commits not in HEAD"
   fi

   If the remote branch has commits that are not in local HEAD (review suggestions, "Update branch", a collaborator's push), stop and ask the user to integrate them first; the rewrite would otherwise discard them.

2. Finish background work. Wait for running generators, formatters, make update, or tests that write files.
3. Handle existing work explicitly. If git status --porcelain --untracked-files=all is not empty, stop and ask whether to commit it to the branch first, stash it with git stash push --include-untracked -m "restructure-commits: preserved work" (restore it at the end), or abort. Never use git reset --hard, git checkout -- ., git clean, or drop stashes or branches.

4. Record the snapshot and create a backup branch. Report these values to the user.

   ORIG_HEAD_SHA=$(git rev-parse HEAD)
   ORIG_TREE=$(git rev-parse "HEAD^{tree}")
   BACKUP="backup/restructure/$BRANCH-$(date +%Y%m%d%H%M%S)"
   git branch "$BACKUP" "$ORIG_HEAD_SHA"

5. Show the complete plan. Resolve every unclassified path, then present the file-to-commit plan with the proposed commit subjects and get the user's approval before rewriting.

   python3 "$TOOL" plan --base "$MERGE_BASE" --head "$ORIG_HEAD_SHA"

2. Rewrite history (lossless)

git reset --soft "$MERGE_BASE" && git reset -q   # index = merge base; working tree still equals $ORIG_TREE

For each non-empty group, in table order:

python3 "$TOOL" stage --base "$MERGE_BASE" --head "$ORIG_HEAD_SHA" --group <GROUP>
git commit -s   # message rules below

stage copies exactly that group's paths (including deletions and paths with spaces) from the snapshot into the index and fails if anything else is staged.

3. Verify (required before declaring completion)

python3 "$TOOL" verify --base "$MERGE_BASE" --head HEAD --expect-tree "$ORIG_TREE"
make run-gitlint PULL_BASE_SHA="$MERGE_BASE" PULL_PULL_SHA=HEAD   # message syntax only, not file grouping
git status --porcelain --untracked-files=all                        # must be empty

make verify-commit-layout BASE="$MERGE_BASE" EXPECT_TREE="$ORIG_TREE" is equivalent to the first command. Without make, run gitlint --commits "$MERGE_BASE..HEAD" instead. The layout check verifies that every commit in the range touches a single group, that groups are in order, and that no path is unclassified, and confirms the final tree equals the snapshot. If it fails, do not push: fix the commits and re-run, or show git diff "$ORIG_TREE" HEAD and, with the user's agreement, return to the snapshot with git reset --keep "$BACKUP". Restore any stash from preflight with git stash pop.

4. Push (only after explicit user confirmation)

git push --force-with-lease="refs/heads/$BRANCH:$PUSHED_SHA" "$PUSH_REMOTE" "HEAD:refs/heads/$BRANCH"

The lease protects against remote updates made after preflight (earlier ones were checked in preflight). If it is rejected, stop and ask. Keep $BACKUP until the user agrees to delete it.

Commit Messages

Read and follow skills/git-commit-format/SKILL.md directly (harnesses with native skill support may load it as the git-commit-format skill). Validate with gitlint as shown above.

• Use the group's prefix from the table. Where it contains <type>, pick the allowed type that describes the change (feat new behavior, fix bug fix, build dependency or build change, refactor restructuring or removal, perf performance, test test or fixture-only change); for Tooling also choose a fitting scope such as ci(envtest). Fixed prefixes are used as-is; Docs is docs: without a scope.
• Subject: imperative mood, describes the purpose (for example build(deps): bump Kubernetes dependencies to 1.37).
• Body: what changed and why, bullets for distinct changes; title at most 120 and body lines at most 140 characters.

Maintenance

• Change ownership: edit the POLICY section of generate_ownership.py (groups, binary groups, conventions), then run make ownership-rules and make test-commit-layout. Because make update regenerates the rules, make verify fails when a PR leaves ownership.json or this table stale.
• Practice or demonstrate: python3 skills/restructure-commits/sample_branch.py <empty-dir> builds a repository whose branch reproduces the PR #9568 module/vendor mistake; follow this procedure in <empty-dir>/work.
• Enforcement scope: the layout check is a required gate of this workflow only; it is not enforced repository-wide by pre-push hooks or CI. Gitlint remains the repository-wide message check. The tool's own tests run in the path-filtered Unit Tests (Restructure Commits) GitHub workflow.
• Adapters: harness-specific entry points (.claude/skills/restructure-commits/SKILL.md, .cursor/rules/restructure-commits.mdc) only point here. Replace personal copies (such as a user-installed restructure-hypershift-commits skill) with a pointer to this file instead of maintaining separate rules.