Submodule pointer bumps belong at wrap-up

Path
reminders/Submodule-Pointer-Bumps-Belong-At-Wrap-Up.md
Authors
Michael Staton
Augmented with
Claude Code on Claude Opus 5 (1M context)

The ruling

Every commit inside a submodule dirties the parent’s recorded gitlink. That is mechanics, not a problem.

Bumping the parent each time turns one unit of work into two commits — the real one, and a second that says only pointer moved. Across a working day that is pure drag, and it drowns the parent’s history in noise.

When What
During the session Commit and push freely in the child. Leave the parent’s M <submodule> dirty.
At wrap-up Bump every moved pointer once, in a single chore(submodule): bump <names> commit.

Wrap-up means end of session, end of day, or handing off.

For agents — the part that keeps getting violated

Do not offer to commit parent pointers mid-session, and do not treat a dirty gitlink as an error worth reporting. Mention it at wrap-up or when asked.

A M ai-labs in git status is not a finding. Reporting it as one trains the operator to ignore your status summaries, which is expensive in a tree this deep — this repo alone routinely carries five or six dirty gitlinks at once from work spanning several days.

Judge the dirty pointer the same way you judge any other uncommitted change: is it yours, from this session? If not, leave it alone and don’t narrate it.

The exception — collaboration

A parent pointer is how another person’s clone resolves which child commit to check out. If someone else is working the same tree, a stale pointer hands them a checkout that does not match what you said you shipped.

So bump more eagerly when collaborating. The once-at-wrap-up rhythm assumes a single operator — usually true in this tree, but check rather than assume.

Why this is a reminder and not just a skill section

The authority is the skill; this file exists because the failure mode is one of recall under momentum. An agent deep in a child repo, having just pushed, sees the parent go dirty and reaches to “finish the job” — which is exactly wrong, and exactly the moment nobody is re-reading a skill.

  • [[../agent-skills/pseudomonorepos/SKILL|pseudomonorepos]] — the full rhythm, the collaboration exception, and the agent corollary (the authoritative statement)
  • [[../agent-skills/git-conventions/SKILL|git-conventions]] — same corollary from the commit-hygiene side
  • [[Pseudomonorepo-Settings]] — sibling reminder on tree-wide git settings