claude-dev-env 1.58.0 → 1.59.0

package/skills/pr-converge/scripts/check_convergence.py

@@ -2,12 +2,18 @@
 
 Usage:
   python scripts/check_convergence.py --owner <O> --repo <R> --pr-number <N>
-                                      [--bugbot-down]
+                                      [--bugbot-down] [--copilot-down]
 
 The bugbot check-run gate is bypassed when either ``--bugbot-down`` is
 passed OR the ``CLAUDE_REVIEWS_DISABLED`` environment variable lists the
 ``bugbot`` token, so a Bugbot opt-out closes the gate without the flag.
 
+The Copilot review gate and the pending-requested-reviews gate are bypassed
+when either ``--copilot-down`` is passed OR the ``CLAUDE_REVIEWS_DISABLED``
+environment variable lists the ``copilot`` token, so a Copilot outage or
+quota exhaustion closes the broader convergence gate on the remaining
+signals without the flag.
+
 Exit codes:
   0 — all pre-conditions met
   1 — one or more conditions not met (FAIL lines printed to stdout)
@@ -58,7 +64,10 @@ _shared_pr_loop_scripts_dir = (
 if str(_shared_pr_loop_scripts_dir) not in sys.path:
     sys.path.insert(0, str(_shared_pr_loop_scripts_dir))
 
-from reviews_disabled import is_bugbot_disabled_via_env
+from reviews_disabled import (
+    is_bugbot_disabled_via_env,
+    is_copilot_disabled_via_env,
+)
 
 
 def _is_bugteam_review(review_body: str) -> bool:
@@ -489,14 +498,141 @@ def _check_no_pending_reviews(
     return True, "no pending reviewers"
 
 
-def check_all(*, owner: str, repo: str, number: int, bugbot_down: bool) -> int:
+def _bugbot_conditions(
+    *, owner: str, repo: str, number: int, head_sha: str, is_bugbot_down: bool
+) -> list[tuple[str, tuple[bool, str]]]:
+    """Build the Bugbot gate conditions, bypassed when Bugbot is down.
+
+    Args:
+        owner: GitHub repository owner login.
+        repo: GitHub repository name.
+        number: Pull request number to inspect.
+        head_sha: Current PR HEAD SHA the gates evaluate against.
+        is_bugbot_down: When True, emit a single bypassed check-run
+            condition and skip the review-body content gate entirely.
+
+    Returns:
+        The bugbot check-run condition, plus the review-body content
+        condition when the check-run gate is present and passing.
+    """
+    if is_bugbot_down:
+        return [("bugbot_clean_at == current_head", (True, "bypassed (bugbot_down)"))]
+    conditions: list[tuple[str, tuple[bool, str]]] = [
+        (
+            "bugbot_clean_at == current_head",
+            _check_bugbot(owner=owner, repo=repo, sha=head_sha),
+        )
+    ]
+    if conditions[-1][1][0]:
+        conditions.append(
+            (
+                "bugbot review body clean",
+                _check_bugbot_not_dirty(
+                    owner=owner, repo=repo, number=number, head_sha=head_sha
+                ),
+            )
+        )
+    return conditions
+
+
+def _copilot_review_condition(
+    *, owner: str, repo: str, number: int, head_sha: str, is_copilot_down: bool
+) -> tuple[str, tuple[bool, str]]:
+    """Build the Copilot review gate condition, bypassed when Copilot is down.
+
+    Args:
+        owner: GitHub repository owner login.
+        repo: GitHub repository name.
+        number: Pull request number to inspect.
+        head_sha: Current PR HEAD SHA the gate evaluates against.
+        is_copilot_down: When True, return a bypassed condition rather than
+            demanding a Copilot review that an outage or quota exhaustion
+            keeps from landing.
+
+    Returns:
+        The Copilot review gate condition for the current HEAD.
+    """
+    if is_copilot_down:
+        return ("copilot_clean_at == current_head", (True, "bypassed (copilot_down)"))
+    return (
+        "copilot_clean_at == current_head",
+        _check_bot_review(
+            owner=owner,
+            repo=repo,
+            number=number,
+            head_sha=head_sha,
+            login_substring=COPILOT_LOGIN_FILTER_SUBSTRING,
+            clean_states=ALL_COPILOT_CLEAN_REVIEW_STATES,
+            dirty_states=ALL_COPILOT_DIRTY_REVIEW_STATES,
+            label="copilot",
+        ),
+    )
+
+
+def _pending_reviews_condition(
+    *, owner: str, repo: str, number: int, is_copilot_down: bool
+) -> tuple[str, tuple[bool, str]]:
+    """Build the pending-requested-reviews condition, bypassed when Copilot is down.
+
+    Args:
+        owner: GitHub repository owner login.
+        repo: GitHub repository name.
+        number: Pull request number to inspect.
+        is_copilot_down: When True, return a bypassed condition so a Copilot
+            review request that will never land does not strand the gate.
+
+    Returns:
+        The pending-requested-reviews condition, which the gate checks for a
+        still-pending Copilot reviewer.
+    """
+    if is_copilot_down:
+        return ("no pending requested reviews", (True, "bypassed (copilot_down)"))
+    return (
+        "no pending requested reviews",
+        _check_no_pending_reviews(owner=owner, repo=repo, number=number),
+    )
+
+
+def _print_conditions(all_conditions: list[tuple[str, tuple[bool, str]]]) -> int:
+    """Print one PASS/FAIL line per condition and return the aggregate exit code.
+
+    Args:
+        all_conditions: Ordered (label, (passed, detail)) gate results.
+
+    Returns:
+        ``0`` when every condition passed, ``1`` when at least one failed.
+    """
+    is_all_passed = True
+    for each_index, (each_label, (each_passed, each_detail)) in enumerate(
+        all_conditions, start=1
+    ):
+        status = "PASS" if each_passed else "FAIL"
+        print(f"{each_index}. {each_label}: {status} — {each_detail}")
+        if not each_passed:
+            is_all_passed = False
+    print()
+    if is_all_passed:
+        print("All pre-conditions met — PR is ready to mark ready.")
+    else:
+        print("One or more pre-conditions not met — do not mark ready.")
+    return 0 if is_all_passed else 1
+
+
+def check_all(
+    *,
+    owner: str,
+    repo: str,
+    number: int,
+    is_bugbot_down: bool,
+    is_copilot_down: bool,
+) -> int:
     """Run every convergence gate and print one PASS/FAIL line per condition.
 
     Args:
         owner: GitHub repository owner login.
         repo: GitHub repository name.
         number: Pull request number to inspect.
-        bugbot_down: When True, bypass both the Cursor Bugbot check-run
+        is_bugbot_down: When True, bypass both the Cursor Bugbot check-run
             presence gate and the bugbot review-body content gate. The
             check-run gate appears in the condition list with a
             ``bypassed (bugbot_down)`` note; the review-body gate is
@@ -504,6 +640,13 @@ def check_all(*, owner: str, repo: str, number: int, bugbot_down: bool) -> int:
             declared Cursor Bugbot unreachable on the current HEAD so the
             broader convergence gate can still close on the remaining
             signals.
+        is_copilot_down: When True, bypass both the Copilot review gate and
+            the pending-requested-reviews gate, each shown with a
+            ``bypassed (copilot_down)`` note. Callers pass True when Copilot
+            is down or out of quota on the current HEAD so the broader
+            convergence gate can still close on the remaining signals; the
+            bypassed pending gate keeps a Copilot review request that will
+            never land from stranding the gate.
 
     Returns:
         ``0`` when every gate reports PASS, ``1`` when at least one gate
@@ -522,29 +665,15 @@ def check_all(*, owner: str, repo: str, number: int, bugbot_down: bool) -> int:
     print(f"HEAD: {head_sha[:7]}\n")
 
     conditions: list[tuple[str, tuple[bool, str]]] = []
-
-    if bugbot_down:
-        conditions.append(
-            (
-                "bugbot_clean_at == current_head",
-                (True, "bypassed (bugbot_down)"),
-            )
+    conditions.extend(
+        _bugbot_conditions(
+            owner=owner,
+            repo=repo,
+            number=number,
+            head_sha=head_sha,
+            is_bugbot_down=is_bugbot_down,
         )
-    else:
-        conditions.append(
-            (
-                "bugbot_clean_at == current_head",
-                _check_bugbot(owner=owner, repo=repo, sha=head_sha),
-            )
-        )
-        if conditions[-1][1][0]:
-            conditions.append(
-                (
-                    "bugbot review body clean",
-                    _check_bugbot_not_dirty(owner=owner, repo=repo, number=number, head_sha=head_sha),
-                )
-            )
-
+    )
     conditions.append(
         (
             "bugteam_clean_at == current_head",
@@ -553,54 +682,30 @@ def check_all(*, owner: str, repo: str, number: int, bugbot_down: bool) -> int:
             ),
         )
     )
-
     conditions.append(
-        (
-            "copilot_clean_at == current_head",
-            _check_bot_review(
-                owner=owner,
-                repo=repo,
-                number=number,
-                head_sha=head_sha,
-                login_substring=COPILOT_LOGIN_FILTER_SUBSTRING,
-                clean_states=ALL_COPILOT_CLEAN_REVIEW_STATES,
-                dirty_states=ALL_COPILOT_DIRTY_REVIEW_STATES,
-                label="copilot",
-            ),
+        _copilot_review_condition(
+            owner=owner,
+            repo=repo,
+            number=number,
+            head_sha=head_sha,
+            is_copilot_down=is_copilot_down,
         )
     )
-
     conditions.append(
         (
             "zero unresolved bot threads",
             _count_unresolved_bot_threads(owner=owner, repo=repo, number=number),
         )
     )
-
     conditions.append(
         ("PR is mergeable", _get_mergeable(owner=owner, repo=repo, number=number))
     )
-
     conditions.append(
-        (
-            "no pending requested reviews",
-            _check_no_pending_reviews(owner=owner, repo=repo, number=number),
+        _pending_reviews_condition(
+            owner=owner, repo=repo, number=number, is_copilot_down=is_copilot_down
         )
     )
-
-    is_all_passed = True
-    for each_index, (each_label, (each_passed, each_detail)) in enumerate(conditions, start=1):
-        status = "PASS" if each_passed else "FAIL"
-        print(f"{each_index}. {each_label}: {status} — {each_detail}")
-        if not each_passed:
-            is_all_passed = False
-
-    print()
-    if is_all_passed:
-        print("All pre-conditions met — PR is ready to mark ready.")
-    else:
-        print("One or more pre-conditions not met — do not mark ready.")
-    return 0 if is_all_passed else 1
+    return _print_conditions(conditions)
 
 
 def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
@@ -611,10 +716,10 @@ def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
             ``sys.argv[1:]``.
 
     Returns:
-        Namespace exposing ``owner``, ``repo``, ``pr_number``, and
-        ``bugbot_down`` attributes. ``bugbot_down`` defaults to False so
-        the unmodified hook contract (``--owner X --repo Y --pr-number N``)
-        still picks up the full gate set.
+        Namespace exposing ``owner``, ``repo``, ``pr_number``,
+        ``bugbot_down``, and ``copilot_down`` attributes. ``bugbot_down``
+        and ``copilot_down`` default to False so the base hook contract
+        (``--owner X --repo Y --pr-number N``) picks up the full gate set.
     """
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--owner", required=True, help="GitHub repository owner")
@@ -630,6 +735,14 @@ def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
             "declared Cursor Bugbot unreachable on the current HEAD."
         ),
     )
+    parser.add_argument(
+        "--copilot-down",
+        action="store_true",
+        help=(
+            "Bypass the Copilot review gate and the pending-requested-reviews "
+            "gate when Copilot is down or out of quota on the current HEAD."
+        ),
+    )
     return parser.parse_args(all_argv)
 
 
@@ -647,6 +760,23 @@ def _resolve_bugbot_down(bugbot_down_flag: bool) -> bool:
     return bugbot_down_flag or is_bugbot_disabled_via_env()
 
 
+def _resolve_copilot_down(is_copilot_down_flag: bool) -> bool:
+    """Combine the explicit flag with the CLAUDE_REVIEWS_DISABLED env opt-out.
+
+    Args:
+        is_copilot_down_flag: Value of the ``--copilot-down`` CLI flag.
+
+    Returns:
+        True when the flag is set OR ``CLAUDE_REVIEWS_DISABLED`` lists the
+        ``copilot`` token, so a Copilot outage signalled through the env var
+        bypasses the Copilot gates even when the caller omits the flag. The
+        mark-ready blocker hook re-runs this script without the flag, so the
+        env token is the only channel a genuine Copilot outage has to pass
+        that independent gate.
+    """
+    return is_copilot_down_flag or is_copilot_disabled_via_env()
+
+
 def main(all_arguments: list[str]) -> int:
     """Run the script end-to-end against parsed CLI arguments.
 
@@ -661,7 +791,8 @@ def main(all_arguments: list[str]) -> int:
         owner=arguments.owner,
         repo=arguments.repo,
         number=getattr(arguments, "pr_number"),
-        bugbot_down=_resolve_bugbot_down(arguments.bugbot_down),
+        is_bugbot_down=_resolve_bugbot_down(arguments.bugbot_down),
+        is_copilot_down=_resolve_copilot_down(arguments.copilot_down),
     )
 
 

package/skills/pr-converge/scripts/test_check_convergence.py

@@ -245,6 +245,34 @@ def should_resolve_bugbot_down_false_when_env_disables_only_bugteam(
     assert check_convergence._resolve_bugbot_down(False) is False
 
 
+def should_resolve_copilot_down_true_when_flag_set(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
+    assert check_convergence._resolve_copilot_down(True) is True
+
+
+def should_resolve_copilot_down_true_when_env_disables_copilot(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "copilot")
+    assert check_convergence._resolve_copilot_down(False) is True
+
+
+def should_resolve_copilot_down_false_when_flag_unset_and_env_empty(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
+    assert check_convergence._resolve_copilot_down(False) is False
+
+
+def should_resolve_copilot_down_false_when_env_disables_only_bugbot(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugbot")
+    assert check_convergence._resolve_copilot_down(False) is False
+
+
 def should_bypass_bugbot_gates_when_bugbot_down_is_true(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:
@@ -324,7 +352,7 @@ def should_bypass_bugbot_gates_when_bugbot_down_is_true(
     )
 
     exit_code = check_convergence.check_all(
-        owner="o", repo="r", number=1, bugbot_down=True
+        owner="o", repo="r", number=1, is_bugbot_down=True, is_copilot_down=False
     )
     captured_stdout = capsys.readouterr().out
 
@@ -334,6 +362,122 @@ def should_bypass_bugbot_gates_when_bugbot_down_is_true(
     assert exit_code == 0
 
 
+def should_bypass_copilot_gates_when_copilot_down_is_true(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    all_invocation_names: list[str] = []
+
+    def stub_get_pr_head_sha(*, owner: str, repo: str, number: int) -> str:
+        return CURRENT_HEAD_SHA
+
+    def stub_check_bugbot(*, owner: str, repo: str, sha: str) -> tuple[bool, str]:
+        return True, "stub passing"
+
+    def stub_check_bugbot_not_dirty(
+        *, owner: str, repo: str, number: int, head_sha: str
+    ) -> tuple[bool, str]:
+        return True, "stub passing"
+
+    def stub_check_bugteam_clean(
+        *, owner: str, repo: str, number: int, head_sha: str
+    ) -> tuple[bool, str]:
+        return True, "stub passing"
+
+    def stub_check_bot_review_should_not_be_called(
+        *,
+        owner: str,
+        repo: str,
+        number: int,
+        head_sha: str,
+        login_substring: str,
+        clean_states: tuple[str, ...],
+        dirty_states: tuple[str, ...],
+        label: str,
+    ) -> tuple[bool, str]:
+        all_invocation_names.append("_check_bot_review")
+        raise AssertionError(
+            "_check_bot_review must not be invoked when copilot_down=True"
+        )
+
+    def stub_count_unresolved_bot_threads(
+        *, owner: str, repo: str, number: int
+    ) -> tuple[bool, str]:
+        return True, "stub passing"
+
+    def stub_get_mergeable(
+        *, owner: str, repo: str, number: int
+    ) -> tuple[bool, str]:
+        return True, "stub passing"
+
+    def stub_check_no_pending_reviews_should_not_be_called(
+        *, owner: str, repo: str, number: int
+    ) -> tuple[bool, str]:
+        all_invocation_names.append("_check_no_pending_reviews")
+        raise AssertionError(
+            "_check_no_pending_reviews must not be invoked when copilot_down=True"
+        )
+
+    monkeypatch.setattr(check_convergence, "_get_pr_head_sha", stub_get_pr_head_sha)
+    monkeypatch.setattr(check_convergence, "_check_bugbot", stub_check_bugbot)
+    monkeypatch.setattr(
+        check_convergence, "_check_bugbot_not_dirty", stub_check_bugbot_not_dirty
+    )
+    monkeypatch.setattr(check_convergence, "_check_bugteam_clean", stub_check_bugteam_clean)
+    monkeypatch.setattr(
+        check_convergence,
+        "_check_bot_review",
+        stub_check_bot_review_should_not_be_called,
+    )
+    monkeypatch.setattr(
+        check_convergence, "_count_unresolved_bot_threads", stub_count_unresolved_bot_threads
+    )
+    monkeypatch.setattr(check_convergence, "_get_mergeable", stub_get_mergeable)
+    monkeypatch.setattr(
+        check_convergence,
+        "_check_no_pending_reviews",
+        stub_check_no_pending_reviews_should_not_be_called,
+    )
+
+    exit_code = check_convergence.check_all(
+        owner="o", repo="r", number=1, is_bugbot_down=False, is_copilot_down=True
+    )
+    captured_stdout = capsys.readouterr().out
+
+    assert "_check_bot_review" not in all_invocation_names
+    assert "_check_no_pending_reviews" not in all_invocation_names
+    assert "bypassed (copilot_down)" in captured_stdout
+    assert exit_code == 0
+
+
+def should_accept_copilot_down_flag_in_parsed_arguments() -> None:
+    arguments = check_convergence.parse_arguments(
+        ["--owner", "o", "--repo", "r", "--pr-number", "1", "--copilot-down"]
+    )
+    assert arguments.copilot_down is True
+
+
+def should_return_zero_from_print_conditions_when_every_condition_passes(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    exit_code = check_convergence._print_conditions(
+        [("gate one", (True, "ok")), ("gate two", (True, "ok"))]
+    )
+    captured_stdout = capsys.readouterr().out
+    assert exit_code == 0
+    assert "All pre-conditions met" in captured_stdout
+
+
+def should_return_one_from_print_conditions_when_any_condition_fails(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    exit_code = check_convergence._print_conditions(
+        [("gate one", (True, "ok")), ("gate two", (False, "nope"))]
+    )
+    captured_stdout = capsys.readouterr().out
+    assert exit_code == 1
+    assert "One or more pre-conditions not met" in captured_stdout
+
+
 def should_propagate_systemexit_from_get_pr_head_sha(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
@@ -347,6 +491,33 @@ def should_propagate_systemexit_from_get_pr_head_sha(
     )
 
     with pytest.raises(SystemExit) as exc_info:
-        check_convergence.check_all(owner="o", repo="r", number=1, bugbot_down=False)
+        check_convergence.check_all(
+            owner="o", repo="r", number=1, is_bugbot_down=False, is_copilot_down=False
+        )
 
     assert exc_info.value.code == check_convergence.EXIT_CODE_GH_ERROR
+
+
+def should_derive_copilot_down_from_env_when_main_omits_the_flag(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "copilot")
+    captured_copilot_down: list[bool] = []
+
+    def stub_check_all(
+        *,
+        owner: str,
+        repo: str,
+        number: int,
+        is_bugbot_down: bool,
+        is_copilot_down: bool,
+    ) -> int:
+        captured_copilot_down.append(is_copilot_down)
+        return 0
+
+    monkeypatch.setattr(check_convergence, "check_all", stub_check_all)
+    exit_code = check_convergence.main(
+        ["--owner", "o", "--repo", "r", "--pr-number", "1"]
+    )
+    assert exit_code == 0
+    assert captured_copilot_down == [True]

package/skills/update/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: update
-description: Fast-forwards a local git repository's main branch to a remote's main, after confirming both the local repo path and the source remote through AskUserQuestion. Fetches the chosen remote, checks that the move is a true fast-forward (never a force, never a merge commit), and updates main whether or not main is the checked-out branch. Use when the user says "/update", "update main", "fast-forward main", "sync main from origin", "pull latest main into <path>", or "bring main up to date". Triggers on "/update", "update main", "fast-forward main", "sync main".
+description: Fast-forwards a local git repository's main branch to a remote's main, after confirming both the local repo path and the source remote through AskUserQuestion. Fetches the chosen remote, checks that the move is a true fast-forward (never a force, never a merge commit), and updates main whether or not main is the checked-out branch. When main is not the checked-out branch, it then offers to switch the checkout to main so the update reaches the files on disk. Use when the user says "/update", "update main", "fast-forward main", "sync main from origin", "pull latest main into <path>", or "bring main up to date". Triggers on "/update", "update main", "fast-forward main", "sync main".
 ---
 
 # update
 
 ## Overview
 
-Fast-forwards the local `main` branch of a given repository to a chosen remote's `main`. The move is always a true fast-forward: the skill fetches the remote, checks that local `main` is an ancestor of the remote's `main`, and advances the ref. It never forces, never creates a merge commit, and never touches any branch other than `main`.
+Fast-forwards the local `main` branch of a given repository to a chosen remote's `main`. The move is always a true fast-forward: the skill fetches the remote, checks that local `main` is an ancestor of the remote's `main`, and advances the ref. It never forces, never creates a merge commit, and never rewrites any branch other than `main`. When `main` is not the checked-out branch, a final confirmed step offers to switch the checkout to `main` so the new commits reach the files on disk — the only branch switch the skill makes, and only after the operator approves it.
 
 The repository is whatever path the user gives as the `/update <path>` argument. With no argument, the default is the current repository's top level. Either way the path is confirmed before any write.
 
@@ -121,11 +121,42 @@ git -C "<path>" status --short
 - **Checked-out branch.** When a branch other than `main` is checked out, say so plainly: the fast-forward moves a ref only and no file on disk changes. Code that runs from this checkout comes from the checked-out branch, not from `main`.
 - **Dirty tracked files.** List every modified tracked file from `status --short`. Uncommitted edits sit on top of the checked-out branch and are what runs — flag them, because a ref update can neither see nor repair them. When the tree is clean, report "working tree clean".
 
+### Phase 5 — Offer to land `main` on disk
+
+A fast-forward of the `main` ref leaves the files on disk untouched when another branch is checked out. The new commits exist in the repo but not in the working tree — the gap Phase 4 reports. This phase offers to close it.
+
+Skip this phase and finish when the checked-out branch is already `main`: the new commits are already on disk.
+
+Otherwise, when the checked-out branch is not `main`, run two safety checks before offering a switch:
+
+1. **Tree clean of tracked changes.** Read `git -C "<path>" status --porcelain` and treat any line that does not start with `??` as a change to a tracked file. If any exist, do not offer the switch: report that `main` moved in the ref only, that switching would risk the uncommitted work, and stop. Never stash, reset, or discard. Untracked files (lines starting with `??`) are fine — they carry across a switch.
+2. **`main` free to check out.** Read `git -C "<path>" worktree list`. If another worktree holds `main`, an in-place switch is impossible; report that path and stop.
+
+When both checks pass, ask **one** `AskUserQuestion` — header "Get on disk":
+
+- Recommended first choice, "Switch checkout to main": `git -C "<path>" checkout main` puts the new commits on disk. The branch you were on keeps its commits and is left unchanged.
+- Second choice, "Stay on `<branch>`": leave the checkout where it is. The update stays in the `main` ref only and reaches disk later.
+
+On "Switch", run:
+
+```
+git -C "<path>" checkout main
+```
+
+If `checkout` reports it would overwrite untracked files, stop and report those paths — never pass `-f`, which would drop the operator's untracked file. On success, confirm the branch and the tip now on disk:
+
+```
+git -C "<path>" branch --show-current
+git -C "<path>" log --oneline -1
+```
+
+On "Stay", report that `main` is current in the ref and the new content reaches disk only after a later switch.
+
 ## Constraints (non-negotiable)
 
 - **Fast-forward only.** If the remote's `main` is not a descendant of local `main`, stop. Never `--force`, never `branch -f`, never a merge commit. Divergence is a job for `/rebase`.
 - **Always confirm both** the path and the source remote first, even when the path is given as an argument. Skipping a confirmation is not allowed — the confirmation is the point of this skill.
-- **Touch only `main`.** Never switch the repo's checked-out branch. The single exception is advancing `main` in place when `main` is already checked out.
+- **Switch the checkout only with approval.** The fast-forward itself touches the `main` ref alone. Switching the checked-out branch to `main` happens only in Phase 5, only after the operator approves the `AskUserQuestion`, only with a tree clean of tracked changes, and never with `-f`. The skill never switches to any branch but `main`.
 - **Never discard local work.** A dirty tree blocks the in-place fast-forward; stop and report rather than stash or reset.
 
 ## Gotchas
@@ -135,12 +166,13 @@ git -C "<path>" status --short
 - `<remote>/main` only moves after an explicit `git fetch`. Fetch inside every run; never compare against a remote-tracking ref left over from an earlier fetch.
 - `origin` is not always the source of truth. When a fork is `origin` and the canonical repo is another remote (often `upstream`), the confirmed remote should be the canonical one, not whichever is named `origin`.
 - Quote the path on every command — `git -C "<path>"` — so paths with spaces or a NAS drive letter survive.
-- "Up to date" describes the `main` ref, not the running code. A checkout deployed on a feature branch, or carrying uncommitted edits, runs that branch plus those edits regardless of where `main` points. Phase 4's checkout-state report exists so the operator sees that gap on every run.
+- "Up to date" describes the `main` ref, not the running code. A checkout deployed on a feature branch, or carrying uncommitted edits, runs that branch plus those edits regardless of where `main` points. Phase 4's checkout-state report exists so the operator sees that gap on every run, and Phase 5 offers to close it.
+- `git checkout main` carries untracked files across unchanged, but refuses with "untracked working tree files would be overwritten" when an untracked file sits at a path `main` tracks. Phase 5 reports those paths and stops rather than passing `-f`, which would drop the operator's untracked file.
 
 ## What this skill does NOT do
 
 - Does not push, open a PR, or change any branch other than `main`.
-- Does not create or switch feature branches — that is `/fresh-branch`.
+- Does not create feature branches, and switches only to `main` (Phase 5, with approval) — creating or switching to any other branch is `/fresh-branch`.
 - Does not reconcile a diverged `main` — that is `/rebase`.
 
 ## File index