submodule bump

Bump a submodule pointer

PETROVA-HQ has two submodules:

core/prompts → petrova-hq/prompts repo
core/templates → petrova-hq/templates repo

Edits to files inside these directories live in the submodule repo, not the parent. The parent’s submodule pointer must be bumped after the inner commit. This runbook is the disciplined sequence.

Why submodules at all

Both prompts and templates are versioned independently from the control plane. A consumer repo bootstrapped today should be able to pull a specific snapshot of the prompts as they were at the time of bootstrap, rather than always-latest. Submodules give us pinned references with explicit bumps.

The rule

Edit inside the submodule, commit + push there, then bump the parent. Never commit a dirty submodule from the parent (it produces a parent commit that points at an SHA that doesn’t exist on the submodule’s remote).

This is also stated in petrova-hq/CLAUDE.md:

Edits to prompt or template files happen inside the submodule and must be committed and pushed there before the parent’s submodule pointer can be bumped — do not commit submodule changes from the parent.

Sequence

Step 1 — edit inside the submodule

cd ~/code/workspace/petrova-hq/core/templates
# Edit files
$EDITOR shared/conventions.md
git status

Step 2 — commit + push inside the submodule

git add shared/conventions.md
git commit -m "$(cat <<'EOF'
docs: clarify ISO date handling in conventions

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
git push origin main

The submodule remote (petrova-hq/templates) now has the new commit. The parent’s submodule pointer is still pointing at the old SHA.

Step 3 — bump the pointer in the parent

cd ~/code/workspace/petrova-hq
git status   # → modified: core/templates (new commits)
git diff --submodule
# Submodule core/templates 0e7b375..8d6b505:
#   > docs: clarify ISO date handling in conventions

Stage and commit the bump:

git add core/templates
git commit -m "$(cat <<'EOF'
chore(submodule): bump core/templates for conventions update

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
git push origin main

Step 4 — verify

cd /tmp && rm -rf petrova-test && \
  git clone --recurse-submodules https://github.com/petrova-hq/petrova.git petrova-test
cd petrova-test/core/templates
git log -1 --oneline
# Should show your new commit.

Recovery from a botched bump

Symptom 1: parent points at SHA not on remote

A teammate clones --recurse-submodules and hits:

fatal: Needed a single revision
Unable to find current revision in submodule path 'core/templates'

Cause: you bumped the parent before pushing the submodule.

Fix:

cd ~/code/workspace/petrova-hq/core/templates
git push origin main

The teammate re-clones; the submodule remote now has the SHA the parent expects.

Symptom 2: dirty submodule on parent main

git status in parent shows modified: core/templates (modified content).

Cause: the submodule has uncommitted edits.

Fix:

cd core/templates
git status
# decide: commit + push, or stash + restore

Don’t commit the parent until the submodule is clean.

Symptom 3: detached HEAD inside submodule

Submodules check out by SHA, leaving you on detached HEAD. Editing in detached HEAD orphans the commits on push.

Fix: before editing, cd core/templates && git checkout main (or whichever default branch).

CI implications

The sync-docs GitHub Action checks out with submodules: recursive. So pushed submodule bumps trigger doc-site rebuilds correctly. But: if you push a submodule commit without bumping the parent pointer, the parent’s CI run will keep using the OLD submodule content. Always bump.