- Count a submodule tag as local work only when origin lacks it or names
  another object, so upstream tags no longer block removal forever.
- Force removal when Git would refuse it (a populated Gitlink or a
  modules/ directory), not when .gitmodules exists, and keep a worktree
  whose modules/ holds a submodule Git directory without a checkout,
  which a forced removal would delete unseen.
- Fail the submodule walk when the superproject index cannot be read.
- Carry the update walk's error into strandedSubmodulesError and the
  failure row; scope that row and the stranded-submodule decision to
  checkouts on the default branch, the only ones the driver updates.
- Apply the wording and test items deferred on #78, #79, and #80.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@@ -5,3 +5,3 @@
 ## What the driver already updates
 
-The driver fast-forwards a default-branch checkout only when its comparison is fresh, it has no local commits, and it is strictly behind `origin/<default>`. A dirty checkout qualifies only when every changed path is deferred guidance (`AGENTS.md`, `.agents/**`, at any depth), a first-party `.gitmodules` edit, or a first-party Gitlink change on a submodule with a `branch` or `tag` selector, and upstream did not touch those paths. The merge runs `--ff-only` with `merge.autostash=false`, because autostash would round-trip the tree through a stash and silently unstage staged guidance. After a fast-forward it initializes committed submodules and checks them out at the recorded Gitlinks. When any populated submodule, at any depth, found from the Gitlinks rather than `.gitmodules`, is checked out at a commit that its superproject does not record and no ref holds, the driver skips the fast-forward and every selector move for that checkout, and the report lists it under "Needs your decision" with the submodule's path.
+The driver fast-forwards a default-branch checkout only when its comparison is fresh, it has no local commits, and it is strictly behind `origin/<default>`. A dirty checkout qualifies only when every changed path is deferred guidance (`AGENTS.md`, `.agents/**`, at any depth), a first-party `.gitmodules` edit, or a first-party Gitlink change on a submodule with a `branch` or `tag` selector, and upstream did not touch those paths. The merge runs `--ff-only` with `merge.autostash=false`, because autostash would round-trip the tree through a stash and silently unstage staged guidance. After a fast-forward it initializes committed submodules and checks them out at the recorded Gitlinks. The driver skips the fast-forward and every selector move for a checkout holding a populated submodule, at any depth, that is checked out at a commit its superproject does not record and no ref in the submodule holds; the report lists the checkout under "Needs your decision" with the submodule's path. Submodules are found from the Gitlinks in HEAD and the index, so neither a removed `.gitmodules` nor an `ignore` setting hides one. When that submodule check itself fails, the driver changes nothing in the checkout, and its failure row says the submodule check failed and names the submodule it could not read: make that submodule readable, then rerun.

@@ -19,3 +19,3 @@
 A worktree lock is an owner pin that expires seven days after its `locked` file's mtime. `git worktree lock` refuses an already locked worktree, so the mtime dates from the original lock; to renew a pin, unlock and lock again. A future-dated lock counts as young. The driver unlocks an expired lock only after every other gate passes, immediately before removal. It reads the lock once, at the gate: a pin renewed during the containment proof and ignored scan that follow is unlocked anyway. If unlock fails, the outcome is `operational/removal-failed`. If removal then fails, the worktree stays unlocked and the next run evaluates it from scratch. Expiry deliberately overrides pins agents leave behind.
 
-Worktrees containing `.gitmodules` are removed with `--force`, because Git otherwise refuses any worktree with submodules; the repeated status check replaces the check `--force` disables. Removal also deletes each submodule's Git directory, local branches and stash included, so right before the status check the driver walks every populated submodule at any depth. A submodule keeps the worktree (`judgment/submodule-local-work`, paths in `removal.error`) when it has uncommitted files, a stash, a branch or tag commit no remote-tracking ref holds, or a HEAD no remote-tracking ref holds. A Gitlink names a commit without keeping it, so a recorded HEAD needs a remote-tracking ref too. Ignored files inside submodules are not scanned.
+Git refuses to remove a worktree with a populated Gitlink or a submodule Git directory under the worktree's own `modules/`, with or without `.gitmodules`, so the driver removes such a worktree with `--force`; the repeated status check replaces the check `--force` disables. Removal also deletes each submodule's Git directory, local branches and stash included, so immediately before the second status check the driver walks every populated submodule at any depth. A submodule keeps the worktree (`judgment/submodule-local-work`, paths in `removal.error`) when it has uncommitted files, a stash, a HEAD or branch commit no remote-tracking ref holds, or a tag on such a commit that origin lacks or names for another object. A Gitlink names a commit without holding it, so a recorded HEAD needs a remote-tracking ref too. A submodule Git directory with no checkout, such as one `git submodule deinit` leaves, cannot be inspected, so it keeps the worktree too, listed as `<name> (not checked out)`. Ignored files inside submodules are not scanned.

@@ -46,3 +46,3 @@
 | `judgment/sparse-checkout` | Keep the cone's `skip-worktree` bits: clearing them turns absent files into apparent deletions. Confirm the cone with `git sparse-checkout list`, verify no file outside it is materialized, then remove manually once every other gate holds. |
 | `judgment/precious-ignored-files` | Leave `preciousPaths` in place until the owner disposes of them or authorizes their deletion, then rerun. |
-| `judgment/submodule-local-work` | The listed submodules hold work only this worktree has. Show the owner what each holds; rerun once it is pushed or they authorize discarding it. |
+| `judgment/submodule-local-work` | The listed submodules hold work only this worktree has. Show the owner what each holds; rerun once the work is pushed. If the owner authorizes discarding it instead, discard it in the submodule first, then rerun. For a `(not checked out)` entry, run `git submodule update --init` in the worktree first, so the next run can inspect it. |

@@ -491,3 +503,4 @@
 #            remote-tracking ref, and the submodule must have no uncommitted
-#            files, no stash, and no branch or tag commit that no
+#            files, no stash, no branch commit that no remote-tracking ref
+#            holds, and no tag that origin lacks whose commit no
 #            remote-tracking ref holds.

@@ -1553,6 +1644,7 @@ function createActivityFixture(context, headActionDate = "2001-09-09T01:46:40Z")
     branch: { current: "feature", isDetached: false },
     workingTree: { isClean: false, files: { staged: [], unstaged: ["sample.txt"], untracked: [] } },
   }));
+  // A shim ending in a semicolon yields `;;` and a bash parse error, not a test failure.

@@ -19,3 +19,3 @@
 A worktree lock is an owner pin that expires seven days after its `locked` file's mtime. `git worktree lock` refuses an already locked worktree, so the mtime dates from the original lock; to renew a pin, unlock and lock again. A future-dated lock counts as young. The driver unlocks an expired lock only after every other gate passes, immediately before removal. It reads the lock once, at the gate: a pin renewed during the containment proof and ignored scan that follow is unlocked anyway. If unlock fails, the outcome is `operational/removal-failed`. If removal then fails, the worktree stays unlocked and the next run evaluates it from scratch. Expiry deliberately overrides pins agents leave behind.
 
-Worktrees containing `.gitmodules` are removed with `--force`, because Git otherwise refuses any worktree with submodules; the repeated status check replaces the check `--force` disables. Removal also deletes each submodule's Git directory, local branches and stash included, so right before the status check the driver walks every populated submodule at any depth. A submodule keeps the worktree (`judgment/submodule-local-work`, paths in `removal.error`) when it has uncommitted files, a stash, a branch or tag commit no remote-tracking ref holds, or a HEAD no remote-tracking ref holds. A Gitlink names a commit without keeping it, so a recorded HEAD needs a remote-tracking ref too. Ignored files inside submodules are not scanned.
+Git refuses to remove a worktree with a populated Gitlink or a submodule Git directory under the worktree's own `modules/`, with or without `.gitmodules`, so the driver removes such a worktree with `--force`; the repeated status check replaces the check `--force` disables. Removal also deletes each submodule's Git directory, local branches and stash included, so immediately before the second status check the driver walks every populated submodule at any depth. A submodule keeps the worktree (`judgment/submodule-local-work`, paths in `removal.error`) when it has uncommitted files, a stash, a linked worktree of its own, a HEAD or branch commit no remote-tracking ref holds, or a tag that names no commit or whose commit no remote-tracking ref holds, unless origin has the same tag on the same object (a lightweight tag also matches origin's tag on its commit). A Gitlink names a commit without holding it, so a recorded HEAD needs a remote-tracking ref too. Files under a Gitlink path with no checkout keep the worktree as `<path> (files without a checkout)`, because status never lists them. A submodule Git directory with no checkout, such as one `git submodule deinit` or `git rm` leaves under `$(git -C <worktree> rev-parse --path-format=absolute --git-path modules)`, is not inspected, so it keeps the worktree too, listed as `<name> (not checked out)`. Ignored files inside submodules are not scanned.

@@ -46,3 +46,3 @@
 | `judgment/sparse-checkout` | Keep the cone's `skip-worktree` bits: clearing them turns absent files into apparent deletions. Confirm the cone with `git sparse-checkout list`, verify no file outside it is materialized, then remove manually once every other gate holds. |
 | `judgment/precious-ignored-files` | Leave `preciousPaths` in place until the owner disposes of them or authorizes their deletion, then rerun. |
-| `judgment/submodule-local-work` | The listed submodules hold work only this worktree has. Show the owner what each holds; rerun once it is pushed or they authorize discarding it. |
+| `judgment/submodule-local-work` | The listed submodules hold work only this worktree has. Show the owner what each holds; rerun once the work is pushed. If the owner authorizes discarding it instead, discard it in the submodule first, then rerun. For a `(not checked out)` entry whose submodule still has a Gitlink, as after `git submodule deinit`, run `git submodule update --init` in the worktree so the next run can inspect it. When no Gitlink is left, as after `git rm`, show the owner what the Git directory holds (`git --git-dir <dir> --work-tree <dir> log --oneline --branches --tags --not --remotes` and `… stash list`; `--work-tree` overrides the deleted checkout its config names), delete the directory only on their authorization, then rerun. |

@@ -31,0 +29,4 @@
+  echo "  a fast-forward or selector move while a submodule, at any depth, sits on a commit"
+  echo "  that its superproject does not record and no ref in the submodule holds;"
+  echo "  replacing a local selector tag unless the fetched tag or another ref holds its commit;"
+  echo "  removing a worktree while a submodule holds a commit, stash, or edit that origin lacks,"

@@ -508,3 +525,5 @@
+      continue
+    fi
     # A submodule the walk cannot read may hold anything; fail rather than report it empty.
     if ! head=$(git -C "$submodule_path" rev-parse --verify --quiet HEAD); then
       printf 'cannot read submodule %s\n' "$prefix$gitlink_path" >&2

@@ -1424,0 +1483,7 @@
+  git(dependencyPath, "tag", "--no-sign", "--force", "-a", "v0.9", "-m", "local v0.9", "v0.9^{commit}");
+  assert.equal(remove().removal.outcome, "judgment/submodule-local-work");
+
+  git(dependencyPath, "update-ref", "refs/tags/v0.9", upstreamTag);
+  const blob = execFileSync("git", ["-C", dependencyPath, "hash-object", "-w", "--stdin"], { input: "private note\n", encoding: "utf8" }).trim();
+  git(dependencyPath, "tag", "--no-sign", "note", blob);
+  assert.equal(remove().removal.outcome, "judgment/submodule-local-work");

@@ -201,3 +207,3 @@
   if (comparison.ahead > 0) return `${count(comparison.ahead, "local commit")} not pushed${dirtyNote}`;
   if (dirty > 0 && comparison.behind > 0) {
-    return `behind; uncommitted changes (${count(dirty, "file")}) block the fast-forward. A dirty checkout fast-forwards only when every changed path is AGENTS.md or under .agents/, at any depth, or first-party submodule metadata, and upstream changed none of those paths.`;
+    return `behind; uncommitted changes (${count(dirty, "file")}) block the fast-forward (see references/checkout-updates.md)`;

@@ -335,2 +341,2 @@
-      if ((isMain || onDefault) && stranded.length > 0) {
-        const why = `submodule on a commit no ref holds: ${listPaths(stranded)}; not updated`;
+      if (onDefault && stranded.length > 0) {
+        const why = `submodules on a commit no ref holds: ${listPaths(stranded)}; not updated`;

@@ -46,3 +46,3 @@
 | `judgment/sparse-checkout` | Keep the cone's `skip-worktree` bits: clearing them turns absent files into apparent deletions. Confirm the cone with `git sparse-checkout list`, verify no file outside it is materialized, then remove manually once every other gate holds. |
 | `judgment/precious-ignored-files` | Leave `preciousPaths` in place until the owner disposes of them or authorizes their deletion, then rerun. |
-| `judgment/submodule-local-work` | The listed submodules hold work only this worktree has. Show the owner what each holds; rerun once it is pushed or they authorize discarding it. |
+| `judgment/submodule-local-work` | The listed submodules hold work only this worktree has. Show the owner what each holds; rerun once the work is pushed. If the owner authorizes discarding it instead, discard it in the submodule first, then rerun. For a `(not checked out)` entry whose submodule still has a Gitlink, as after `git submodule deinit`, run `git submodule update --init` in the worktree so the next run can inspect it. When no Gitlink is left, as after `git rm`, show the owner what the Git directory holds (`git --git-dir <dir> --work-tree <dir> log --oneline --branches --tags --not --remotes` and `… stash list`; `--work-tree` overrides the deleted checkout its config names), delete the directory only on their authorization, then rerun. |

@@ -31,1 +31,4 @@
+  echo "  replacing a local selector tag unless the fetched tag or another ref holds its commit;"
+  echo "  removing a worktree while a submodule holds a commit, stash, or edit that origin lacks,"
+  echo "  or while files or a submodule Git directory in it have no checkout to inspect."
   echo "Branch refs and stashes are never deleted."

@@ -1099,5 +1193,6 @@
   # is-it-clean safeguard inside worktree remove. Never -f -f: that also
   # bypasses Git's unclean refusal.
+  # Git refuses a populated Gitlink or a modules/ directory, not .gitmodules.
   worktree_remove_args=(worktree remove)
-  if [ -e "$worktree_path/.gitmodules" ]; then
+  if [ -n "$populated_git_dirs" ] || [ -d "$modules_path" ]; then
     worktree_remove_args+=(--force)

@@ -5,3 +5,3 @@
 ## What the driver already updates
 
-The driver fast-forwards a default-branch checkout only when its comparison is fresh, it has no local commits, and it is strictly behind `origin/<default>`. A dirty checkout qualifies only when every changed path is deferred guidance (`AGENTS.md`, `.agents/**`, at any depth), a first-party `.gitmodules` edit, or a first-party Gitlink change on a submodule with a `branch` or `tag` selector, and upstream did not touch those paths. The merge runs `--ff-only` with `merge.autostash=false`, because autostash would round-trip the tree through a stash and silently unstage staged guidance. After a fast-forward it initializes committed submodules and checks them out at the recorded Gitlinks. When any populated submodule, at any depth, found from the Gitlinks rather than `.gitmodules`, is checked out at a commit that its superproject does not record and no ref holds, the driver skips the fast-forward and every selector move for that checkout, and the report lists it under "Needs your decision" with the submodule's path.
+The driver fast-forwards a default-branch checkout only when its comparison is fresh, it has no local commits, and it is strictly behind `origin/<default>`. A dirty checkout qualifies only when every changed path is deferred guidance (`AGENTS.md`, `.agents/**`, at any depth), a first-party `.gitmodules` edit, or a first-party Gitlink change on a submodule with a `branch` or `tag` selector, and upstream did not touch those paths. The merge runs `--ff-only` with `merge.autostash=false`, because autostash would round-trip the tree through a stash and silently unstage staged guidance. After a fast-forward it initializes committed submodules and checks them out at the recorded Gitlinks. The driver skips the fast-forward and every selector move for a checkout holding a populated submodule, at any depth, that is checked out at a commit its superproject does not record and no ref in the submodule holds; the report lists the checkout under "Needs your decision" with the submodule's path. Submodules are found from the Gitlinks in HEAD and the index, so neither a removed `.gitmodules` nor an `ignore` setting hides one. When that submodule check itself fails, the driver changes nothing in the checkout, and its failure row says the submodule check failed, followed by the first line of the error. That line names the submodule when one could not be read and otherwise quotes Git; `strandedSubmodulesError` in the JSON record holds the full text. Repair what it names, then rerun.

@@ -19,3 +19,3 @@
 A worktree lock is an owner pin that expires seven days after its `locked` file's mtime. `git worktree lock` refuses an already locked worktree, so the mtime dates from the original lock; to renew a pin, unlock and lock again. A future-dated lock counts as young. The driver unlocks an expired lock only after every other gate passes, immediately before removal. It reads the lock once, at the gate: a pin renewed during the containment proof and ignored scan that follow is unlocked anyway. If unlock fails, the outcome is `operational/removal-failed`. If removal then fails, the worktree stays unlocked and the next run evaluates it from scratch. Expiry deliberately overrides pins agents leave behind.
 
-Worktrees containing `.gitmodules` are removed with `--force`, because Git otherwise refuses any worktree with submodules; the repeated status check replaces the check `--force` disables. Removal also deletes each submodule's Git directory, local branches and stash included, so right before the status check the driver walks every populated submodule at any depth. A submodule keeps the worktree (`judgment/submodule-local-work`, paths in `removal.error`) when it has uncommitted files, a stash, a branch or tag commit no remote-tracking ref holds, or a HEAD no remote-tracking ref holds. A Gitlink names a commit without keeping it, so a recorded HEAD needs a remote-tracking ref too. Ignored files inside submodules are not scanned.
+Git refuses to remove a worktree with a populated Gitlink or a submodule Git directory under the worktree's own `modules/`, with or without `.gitmodules`, so the driver removes such a worktree with `--force`; the repeated status check replaces the check `--force` disables. Removal also deletes each submodule's Git directory, local branches and stash included, so immediately before the second status check the driver walks every populated submodule at any depth. A submodule keeps the worktree (`judgment/submodule-local-work`, paths in `removal.error`) when it has uncommitted files, a stash, a linked worktree of its own, a HEAD or branch commit no remote-tracking ref holds, or a tag that names no commit or whose commit no remote-tracking ref holds, unless origin has the same tag on the same object (a lightweight tag also matches origin's tag on its commit). A Gitlink names a commit without holding it, so a recorded HEAD needs a remote-tracking ref too. Files under a Gitlink path with no checkout keep the worktree as `<path> (files without a checkout)`, because status never lists them. A submodule Git directory with no checkout, such as one `git submodule deinit` or `git rm` leaves under `$(git -C <worktree> rev-parse --path-format=absolute --git-path modules)`, is not inspected, so it keeps the worktree too, listed as `<name> (not checked out)`: `<name>` is the directory's path relative to that `modules` directory, which is the submodule's name, not its checkout path. Ignored files inside each populated submodule are scanned like the worktree's own, against the primary checkout's copy of that submodule, and precious ones keep the worktree as `judgment/precious-ignored-files` with paths relative to the worktree.

@@ -32,0 +29,6 @@
+  echo "  a fast-forward or selector move while a submodule, at any depth, sits on a commit"
+  echo "  that its superproject does not record and no ref in the submodule holds;"
+  echo "  replacing a local selector tag unless the fetched tag or another ref holds its commit;"
+  echo "  removing a worktree while a submodule holds a stash, an edit, a commit no remote-tracking"
+  echo "  ref holds, or a tag origin lacks, or while files or a submodule Git directory in it"
+  echo "  have no checkout to inspect."

@@ -552,0 +617,4 @@
+    if [ -n "$primary_path" ] && [ -e "$primary_path/$gitlink_path/.git" ]; then
+      submodule_primary="$primary_path/$gitlink_path"
+    fi
+    if ! list_precious_ignored_paths "$submodule_path" "$submodule_primary" "$scratch.status" "$scratch.error" >"$scratch.precious"; then

@@ -22,0 +26,4 @@
+- `<path> (files without a checkout)`: files under a Gitlink path that has no checkout, which status never lists.
+- `<name> (not checked out)`: a submodule Git directory that no checkout uses, such as one `git submodule deinit` or `git rm` leaves under `$(git -C <worktree> rev-parse --path-format=absolute --git-path modules)`. The driver does not inspect it. `<name>` is its path relative to that `modules` directory, which is the submodule's name, not its checkout path.
+
+Ignored files inside each populated submodule are scanned like the worktree's own, against the primary checkout's copy of that submodule, with paths and `AUDIT_CHECKOUTS_REGENERABLE_IGNORED` globs relative to the worktree; precious ones keep the worktree as `judgment/precious-ignored-files`.

@@ -32,0 +34,5 @@
+  echo "  origin lacks, or while files or a submodule Git directory in it have no checkout to"
+  echo "  inspect."
+  echo "The audited repositories' branch refs and stashes are never deleted. Removing a"
+  echo "worktree deletes its submodules' Git directories, local branches included, once every"
+  echo "commit there is held by a remote-tracking ref."

@@ -493,1 +505,9 @@
-#            remote-tracking ref holds.
+#            directories, so only commits remote-tracking refs hold, and tags
+#            origin has, survive; a recorded Gitlink names a commit without
+#            holding it. HEAD must be held by a remote-tracking ref, and the
+#            submodule must have no uncommitted
+#            files, no stash, no linked worktree, no branch commit that no
+#            remote-tracking ref holds, and no tag on a non-commit or on a
+#            commit no remote-tracking ref holds unless origin has that tag
+#            on the same object. A Gitlink path without a checkout must be
+#            empty.

@@ -1065,0 +1192,5 @@
+    echo operational/gate-check-failed
+    return
+  fi
+  if [ -d "$modules_path" ]; then
+    if ! unchecked_git_dirs=$(list_submodule_git_dirs_without_checkout "$modules_path" "$populated_git_dirs" 2>>"$gate_error_path"); then

@@ -46,3 +54,3 @@
 | `judgment/sparse-checkout` | Keep the cone's `skip-worktree` bits: clearing them turns absent files into apparent deletions. Confirm the cone with `git sparse-checkout list`, verify no file outside it is materialized, then remove manually once every other gate holds. |
 | `judgment/precious-ignored-files` | Leave `preciousPaths` in place until the owner disposes of them or authorizes their deletion, then rerun. |
-| `judgment/submodule-local-work` | The listed submodules hold work only this worktree has. Show the owner what each holds; rerun once it is pushed or they authorize discarding it. |
+| `judgment/submodule-local-work` | The listed submodules hold work only this worktree has, or content the driver could not inspect. Show the owner what each holds; rerun once the work is pushed. If the owner authorizes discarding it instead, discard it in the submodule first, then rerun. For a `(not checked out)` entry, first show the owner what `<modules>/<name>` (or the listed worktree-relative path) holds, before anything checks it out: `git --git-dir <modules>/<name> --work-tree <modules>/<name> log --oneline HEAD --branches --tags --not --remotes` and `… stash list` (`--work-tree` overrides the deleted checkout its config names). Then, on their decision, restore the checkout with `git submodule update --init -- <path>` while a Gitlink remains, or delete the directory, and rerun. |

@@ -32,0 +34,5 @@
+  echo "  origin lacks, or while files or a submodule Git directory in it have no checkout to"
+  echo "  inspect."
+  echo "The audited repositories' branch refs and stashes are never deleted. Removing a"
+  echo "worktree deletes its submodules' Git directories, local branches included, once every"
+  echo "commit there is held by a remote-tracking ref."