feat(gx): add --advance-submodules flag to gx branch finish (#559)

When passed AND the agent lane has `.gitmodules`, the finish flow runs
`submoduleModule.advance({ commit: true })` on the lane before spawning
agent-branch-finish.sh. Pointer bumps land as a commit on the agent
branch, so the resulting PR contains the user's code edits + the
submodule pointer bumps as one atomic unit.

Closes the manual ritual for monorepo shops: instead of running
`gx submodule advance --push` in a separate lane after merge, users
can include `--advance-submodules` in the finish command and get one
combined PR.

Safety:
- Opt-in flag — default off, no behavior change for non-users.
- Reuses Phase B plumbing (PR #558): refuses to commit if any
  submodule is dirty or if the lane's working tree has unrelated
  changes.
- Dry-run path shows the would-advance preview without mutating.
- If lane has no `.gitmodules`, flag is logged as ignored and the
  rest of finish proceeds normally.

Verified end-to-end against gitguardex's own .gitmodules:
- `node bin/multiagent-safety.js finish --dry-run --advance-submodules`
  correctly reports `would-init` for each uninitialized submodule
  then continues with the normal finish dry-run output.

Files:
- src/cli/args.js — add --advance-submodules/--no-advance-submodules
- src/finish/index.js — import submoduleModule, call advance() in
  the finish loop between auto-commit and runPackageAsset('branchFinish')

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

Author: NagyVikt

openspec/changes/agent-claude-branch-finish-advance-submodules-flag-2026-05-11-13-50/.openspec.yaml

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

openspec/changes/agent-claude-branch-finish-advance-submodules-flag-2026-05-11-13-50/proposal.md

@@ -0,0 +1,17 @@
+## Why
+
+In monorepo shops (`medusa-shops/lifted`, `compastor`, etc.) the parent repo pins `apps/backend` and `apps/storefront` as submodules. When an agent's lane includes both code edits AND new commits in submodules, the user has to run `gx submodule advance` (Phase B) as a separate step before finishing the lane — otherwise the parent PR ships with stale submodule pointers and reviewers see "no actual change."
+
+## What Changes
+
+- Add `--advance-submodules` / `--no-advance-submodules` to `gx branch finish`. Default off.
+- When `--advance-submodules` is passed AND the worktree has `.gitmodules`, the finish flow runs `submoduleModule.advance({ commit: true })` on the lane *before* spawning `agent-branch-finish.sh`. Pointer bumps land as a commit on the agent's branch, so the resulting PR contains the user's code edits + the pointer bumps in one atomic unit.
+- In `--dry-run` mode, the advance preview is printed without mutating anything.
+- If the worktree has no `.gitmodules`, the flag is logged as ignored and finish proceeds normally.
+
+## Impact
+
+- Opt-in flag: no behavior change for non-monorepo lanes or for users who don't pass the flag.
+- Uses the existing `submoduleModule.advance` plumbing (Phase B) — already battle-tested via PR #558.
+- Safety: advance refuses to commit if any submodule is dirty or if the lane's working tree has unrelated changes, so the existing finish gates aren't bypassed.
+- Future: `--advance-submodules` could become the default for repos with `.gitmodules` once we're confident in the flow.

openspec/changes/agent-claude-branch-finish-advance-submodules-flag-2026-05-11-13-50/specs/branch-finish-advance-submodules-flag/spec.md

@@ -0,0 +1,9 @@
+## ADDED Requirements
+
+### Requirement: branch-finish-advance-submodules-flag behavior
+The system SHALL enforce branch-finish-advance-submodules-flag behavior as defined by this change.
+
+#### Scenario: Baseline acceptance
+- **WHEN** branch-finish-advance-submodules-flag behavior is exercised
+- **THEN** the expected outcome is produced
+- **AND** regressions are covered by tests.

openspec/changes/agent-claude-branch-finish-advance-submodules-flag-2026-05-11-13-50/tasks.md

@@ -0,0 +1,34 @@
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches `MERGED` state on `origin` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a `BLOCKED:` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+## Handoff
+
+- Handoff: change=`agent-claude-branch-finish-advance-submodules-flag-2026-05-11-13-50`; branch=`agent/<your-name>/<branch-slug>`; scope=`TODO`; action=`continue this sandbox or finish cleanup after a usage-limit/manual takeover`.
+- Copy prompt: Continue `agent-claude-branch-finish-advance-submodules-flag-2026-05-11-13-50` on branch `agent/<your-name>/<branch-slug>`. Work inside the existing sandbox, review `openspec/changes/agent-claude-branch-finish-advance-submodules-flag-2026-05-11-13-50/tasks.md`, continue from the current state instead of creating a new sandbox, and when the work is done run `gx branch finish --branch agent/<your-name>/<branch-slug> --base dev --via-pr --wait-for-merge --cleanup`.
+
+## 1. Specification
+
+- [ ] 1.1 Finalize proposal scope and acceptance criteria for `agent-claude-branch-finish-advance-submodules-flag-2026-05-11-13-50`.
+- [ ] 1.2 Define normative requirements in `specs/branch-finish-advance-submodules-flag/spec.md`.
+
+## 2. Implementation
+
+- [ ] 2.1 Implement scoped behavior changes.
+- [ ] 2.2 Add/update focused regression coverage.
+
+## 3. Verification
+
+- [ ] 3.1 Run targeted project verification commands.
+- [ ] 3.2 Run `openspec validate agent-claude-branch-finish-advance-submodules-flag-2026-05-11-13-50 --type change --strict`.
+- [ ] 3.3 Run `openspec validate --specs`.
+
+## 4. Cleanup (mandatory; run before claiming completion)
+
+- [ ] 4.1 Run the cleanup pipeline: `gx branch finish --branch agent/<your-name>/<branch-slug> --base dev --via-pr --wait-for-merge --cleanup`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 4.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is gone (`git worktree list` no longer shows the agent path; `git branch -a` shows no surviving local/remote refs for the branch).

src/cli/args.js

@@ -1002,6 +1002,7 @@ function parseFinishArgs(rawArgs, defaults = {}) {
     keepRemote: false,
     noAutoCommit: false,
     parentGitlinkCommit: defaults.parentGitlinkCommit ?? true,
+    advanceSubmodules: false,
     failFast: false,
     commitMessage: '',
     mergeMode: defaults.mergeMode || 'pr',
@@ -1109,6 +1110,14 @@ function parseFinishArgs(rawArgs, defaults = {}) {
       options.failFast = true;
       continue;
     }
+    if (arg === '--advance-submodules') {
+      options.advanceSubmodules = true;
+      continue;
+    }
+    if (arg === '--no-advance-submodules') {
+      options.advanceSubmodules = false;
+      continue;
+    }
     throw new Error(`Unknown option: ${arg}`);
   }
 

src/finish/index.js

@@ -26,6 +26,7 @@ const {
   parseFinishArgs,
   parseSyncArgs,
 } = require('../cli/args');
+const submoduleModule = require('../submodule');
 
 function claimLocksForAutoCommit(repoRoot, worktreePath, branch) {
   const changedFiles = uniquePreserveOrder([
@@ -305,6 +306,32 @@ function finish(rawArgs, defaults = {}) {
         console.log(`[${TOOL_NAME}] [dry-run] Would auto-commit pending changes on '${branch}'.`);
       }
 
+      if (options.advanceSubmodules && worktreePath) {
+        const gitmodulesPath = path.join(worktreePath, '.gitmodules');
+        if (fs.existsSync(gitmodulesPath)) {
+          if (options.dryRun) {
+            const preview = submoduleModule.advance({
+              target: worktreePath,
+              push: false,
+              commit: false,
+              dryRun: true,
+            });
+            console.log(`[${TOOL_NAME}] [dry-run] Would advance submodules for '${branch}':`);
+            submoduleModule.printAdvanceResult(preview);
+          } else {
+            const advanceResult = submoduleModule.advance({
+              target: worktreePath,
+              push: false,
+              commit: true,
+              dryRun: false,
+            });
+            submoduleModule.printAdvanceResult(advanceResult);
+          }
+        } else {
+          console.log(`[${TOOL_NAME}] --advance-submodules ignored: '${branch}' has no .gitmodules.`);
+        }
+      }
+
       const finishArgs = [
         '--branch',
         branch,