feat(gx): auto-sync submodule working dirs on gx setup for monorepo shops (#557)

When `<repoRoot>/.gitmodules` exists, `gx setup` now:

- Sets `pull.recurseSubmodules=true` so `git pull` auto-updates submodule
  working dirs (only when unset; pre-existing values are preserved).
- Sets `fetch.recurseSubmodules=on-demand` so submodule commits are
  fetched as parent pointers move.
- Runs `git submodule update --init --recursive` once to snap working
  dirs to the parent index — fixes the screenshot case where the parent
  is `0↓ 2↑` (pointer bumps already in the index, working dir stale).

`submodule.recurse` is intentionally NOT touched — push behavior stays
default, avoiding cascade with the Codex external-remote approval block
(prior incident S715/S716).

Repos without `.gitmodules` are untouched (helper returns `[]` early).

Files:
- src/git/index.js — add `ensureSubmoduleAutoSync` helper.
- src/cli/main.js — call it from `runSetupBootstrapInternal`.

Smoke-tested via dry-run against `medusa-shops/compastor`:
- would-set    git config pull.recurseSubmodules
- would-set    git config fetch.recurseSubmodules
- would-sync   git submodule update --init --recursive

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>

Author: NagyVikt

openspec/changes/agent-claude-submodule-auto-sync-on-setup-2026-05-11-13-32/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-11

openspec/changes/agent-claude-submodule-auto-sync-on-setup-2026-05-11-13-32/notes.md

@@ -0,0 +1,50 @@
+# submodule-auto-sync-on-setup (T1)
+
+Branch: `agent/claude/submodule-auto-sync-on-setup-2026-05-11-13-32`
+
+## Why
+
+Monorepo shops (`medusa-shops/lifted`, `compastor`, `koronakert`, `teherguminet`, …) pin `apps/backend` and `apps/storefront` as independent submodule repos. When an agent commits inside a submodule (in a separate `.omc/agent-worktrees/...` lane) and the parent PR merges, the user's primary checkout never updates the submodule working dir until they manually run `git submodule update --init --recursive`. Symptom: `pnpm storefront:dev` shows stale code, looking like the agent did nothing.
+
+`submodule.recurse=true` would fix this but also affects `push` and cascades into the Codex external-remote approval block (S715/S716). Targeted pair is safer and pull-only.
+
+## Change
+
+In `runSetupBootstrapInternal` (src/cli/main.js), after `ensureSetupProtectedBranches`, call a new `ensureSubmoduleAutoSync(repoRoot, dryRun)` helper (src/git/index.js).
+
+The helper:
+1. Returns `[]` immediately if `<repoRoot>/.gitmodules` is absent — non-monorepo repos are untouched.
+2. For each of `pull.recurseSubmodules=true` and `fetch.recurseSubmodules=on-demand`: only writes when the key is unset locally. Pre-existing values are preserved (the user may have a reason).
+3. Runs `git submodule update --init --recursive` once to snap working dirs to the parent index — this is the part that fixes the screenshot case where the parent is `0↓ 2↑` (pointer bumps already in the index, working dir stale).
+4. Operations show up in the normal `Setup/install` output as `would-set` / `set` / `unchanged` / `synced`.
+
+`submodule.recurse` is intentionally not touched — push behavior stays default.
+
+## Files
+
+- `src/git/index.js` — add `ensureSubmoduleAutoSync` + `SUBMODULE_AUTO_SYNC_CONFIGS`, export.
+- `src/cli/main.js` — import + call from `runSetupBootstrapInternal`.
+
+## Verification
+
+Dry-run against `/home/deadpool/Documents/medusa-shops/compastor`:
+
+```
+- would-set    git config pull.recurseSubmodules (true (auto-update submodule working dirs on `git pull`))
+- would-set    git config fetch.recurseSubmodules (on-demand (fetch submodule commits as parent pointers move))
+- would-sync   git submodule update --init --recursive (snap submodule working dirs to parent index)
+```
+
+Idempotency: `readGitConfig` returns `''` only when truly unset, so any pre-existing value (including `false`) is preserved and surfaced as `unchanged`.
+
+## Follow-ups (not in this PR)
+
+- Phase B (T1): standalone `gx submodule sync` verb that fetches each submodule, bumps the parent pointer to the tracked branch's remote tip, commits.
+- Phase C (T2): workspace-aware `gx branch finish` — fans out child PRs, bumps parent pointer, opens parent PR with dependency.
+
+## Cleanup
+
+- [x] Run dry-run smoke test on compastor — three new ops appear correctly.
+- [ ] Run: `gx branch finish --branch agent/claude/submodule-auto-sync-on-setup-2026-05-11-13-32 --base main --via-pr --wait-for-merge --cleanup`
+- [ ] Record PR URL + `MERGED` state in the completion handoff.
+- [ ] Confirm sandbox worktree is gone (`git worktree list`, `git branch -a`).

src/cli/main.js

@@ -89,6 +89,7 @@ const {
   readConfiguredProtectedBranches,
   readProtectedBranches,
   ensureSetupProtectedBranches,
+  ensureSubmoduleAutoSync,
   writeProtectedBranches,
   readGitConfig,
   resolveBaseBranch,
@@ -383,6 +384,9 @@ function runSetupBootstrapInternal(options) {
   installPayload.operations.push(
     ensureSetupProtectedBranches(installPayload.repoRoot, Boolean(options.dryRun)),
   );
+  installPayload.operations.push(
+    ...ensureSubmoduleAutoSync(installPayload.repoRoot, Boolean(options.dryRun)),
+  );
 
   let parentWorkspace = null;
   if (options.parentWorkspaceView) {

src/git/index.js

@@ -319,6 +319,70 @@ function writeProtectedBranches(repoRoot, branches) {
   gitRun(repoRoot, ['config', GIT_PROTECTED_BRANCHES_KEY, branches.join(' ')]);
 }
 
+const SUBMODULE_AUTO_SYNC_CONFIGS = [
+  {
+    key: 'pull.recurseSubmodules',
+    value: 'true',
+    note: 'auto-update submodule working dirs on `git pull`',
+  },
+  {
+    key: 'fetch.recurseSubmodules',
+    value: 'on-demand',
+    note: 'fetch submodule commits as parent pointers move',
+  },
+];
+
+function ensureSubmoduleAutoSync(repoRoot, dryRun) {
+  const gitmodulesPath = path.join(repoRoot, '.gitmodules');
+  if (!fs.existsSync(gitmodulesPath)) {
+    return [];
+  }
+
+  const operations = [];
+  for (const { key, value, note } of SUBMODULE_AUTO_SYNC_CONFIGS) {
+    const existing = readGitConfig(repoRoot, key);
+    if (existing) {
+      operations.push({
+        status: 'unchanged',
+        file: `git config ${key}`,
+        note: `respected pre-existing value: ${existing}`,
+      });
+      continue;
+    }
+    if (!dryRun) {
+      gitRun(repoRoot, ['config', key, value]);
+    }
+    operations.push({
+      status: dryRun ? 'would-set' : 'set',
+      file: `git config ${key}`,
+      note: `${value} (${note})`,
+    });
+  }
+
+  if (dryRun) {
+    operations.push({
+      status: 'would-sync',
+      file: 'git submodule update --init --recursive',
+      note: 'snap submodule working dirs to parent index',
+    });
+    return operations;
+  }
+
+  const result = gitRun(
+    repoRoot,
+    ['submodule', 'update', '--init', '--recursive'],
+    { allowFailure: true },
+  );
+  operations.push({
+    status: result.status === 0 ? 'synced' : 'failed',
+    file: 'git submodule update --init --recursive',
+    note: result.status === 0
+      ? 'submodule working dirs snapped to parent index'
+      : `failed: ${(result.stderr || '').trim().split('\n')[0] || 'unknown'}`,
+  });
+  return operations;
+}
+
 function readGitConfig(repoRoot, key) {
   const result = gitRun(repoRoot, ['config', '--get', key], { allowFailure: true });
   if (result.status !== 0) {
@@ -697,6 +761,7 @@ module.exports = {
   hasSignificantWorkingTreeChanges,
   readProtectedBranches,
   ensureSetupProtectedBranches,
+  ensureSubmoduleAutoSync,
   writeProtectedBranches,
   readGitConfig,
   resolveBaseBranch,