fix: remove --phase flag from merge-to-main.sh to prevent phase-name confusion (merge worktree-20260323-193735)

Author: JoeOakhartNava

CLAUDE.md

@@ -148,7 +148,7 @@ After ExitPlanMode approval, do NOT begin implementation. Create a ticket epic (
 #    Review uses autonomous resolution (2 fix/defend attempts before user escalation).
 #    On attempt 2+, /dso:oscillation-check runs automatically if same files targeted.
 # 2. git push (or plugins/dso/scripts/merge-to-main.sh in worktree sessions — handles .claude/scripts/dso ticket sync + merge + push)
-#    Supports phased execution: --phase=<name> (run one phase) or --resume (continue from last state file checkpoint).
+#    Supports --resume (continue from last state file checkpoint).
 #    Phases: sync → merge → validate → push → archive → ci_trigger
 #    # REVIEW-DEFENSE: checkpoint_verify phase removed from docs here intentionally — story dso-q0df (batch 2) removes _phase_checkpoint_verify() from merge-to-main.sh. Docs lead code in this multi-story epic.
 #    State file: /tmp/merge-to-main-state-<branch>.json (expires after 4h); lock file: /tmp/merge-to-main-lock-<hash>

plugins/dso/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dso",
-  "version": "0.25.11",
+  "version": "0.25.12",
   "description": "Workflow infrastructure plugin for Claude Code projects",
   "commands": "./commands/",
   "skills": "./skills/",

plugins/dso/docs/WORKTREE-GUIDE.md

@@ -598,15 +598,15 @@ ${CLAUDE_PLUGIN_ROOT}/scripts/merge-to-main.sh --resume
 
 **Lock file**: `/tmp/merge-to-main-lock-<hash>` — prevents concurrent merge runs against the same repo. If a stale lock exists (process died), it is automatically broken on the next run.
 
-### Running a Single Phase
+### Resuming After a Failure
 
-To re-run one specific phase (e.g., after a partial failure):
+To resume from the last incomplete phase after a partial failure:
 
 ```bash
-${CLAUDE_PLUGIN_ROOT}/scripts/merge-to-main.sh --phase=push
+${CLAUDE_PLUGIN_ROOT}/scripts/merge-to-main.sh --resume
 ```
 
-Valid phase names: `sync`, `merge`, `validate`, `push`, `archive`, `ci_trigger`.
+The script records completed phases in a state file and resumes from the first incomplete one.
 
 ---
 

plugins/dso/scripts/merge-to-main.sh

@@ -18,15 +18,13 @@ set -euo pipefail
 for _arg in "$@"; do
     if [[ "$_arg" == "--help" ]]; then
         cat <<'USAGE'
-Usage: merge-to-main.sh [--phase=<name>|--resume|--help]
+Usage: merge-to-main.sh [--resume|--help]
 
-  --phase=<name>  Run a single named phase and exit. Valid phase names:
-                    sync  merge  validate  push  archive  ci_trigger
   --resume        Resume from last incomplete phase. On merge failure, squash-rebase
                   recovery runs automatically before retrying (up to 5 retries).
   --help          Print this usage message and exit.
 
-  (no args)       Run all phases sequentially (backward compatible).
+  (no args)       Run all phases sequentially.
 
 Merge recovery: on git merge failure the script squash-rebases the branch onto
 main and retries. If recovery fails, run --resume (retry budget: 5 attempts).
@@ -1274,14 +1272,10 @@ _phase_ci_trigger() {
 _ALL_PHASES=(sync merge validate push archive ci_trigger)
 
 # --- Parse CLI arguments ---
-_CLI_PHASE=""
 _CLI_RESUME=false
 
 for _arg in "$@"; do
     case "$_arg" in
-        --phase=*)
-            _CLI_PHASE="${_arg#--phase=}"
-            ;;
         --resume)
             _CLI_RESUME=true
             ;;
@@ -1295,19 +1289,6 @@ for _arg in "$@"; do
     esac
 done
 
-# --- Dispatch: --phase=<name> ---
-if [[ -n "$_CLI_PHASE" ]]; then
-    _DISPATCH_FN="_phase_${_CLI_PHASE}"
-    if declare -f "$_DISPATCH_FN" > /dev/null 2>&1; then
-        "$_DISPATCH_FN"
-        echo "DONE: phase '$_CLI_PHASE' completed."
-        exit 0
-    else
-        echo "ERROR: Unknown phase '$_CLI_PHASE'. Valid phases: ${_ALL_PHASES[*]}" >&2
-        exit 1
-    fi
-fi
-
 # --- Dispatch: --resume ---
 if [[ "$_CLI_RESUME" == "true" ]]; then
     _sf=$(_state_file_path)
@@ -1418,8 +1399,8 @@ fi
 
 # --- No-args (or state file missing for --resume): run all phases sequentially ---
 if [[ $# -eq 0 ]]; then
-    echo "WARNING: Running all phases sequentially. Use --phase=<name> to run a single phase" \
-         "or --resume to continue from the last incomplete phase." >&2
+    echo "Running all phases sequentially. Use --resume to continue from the last" \
+         "incomplete phase if interrupted." >&2
 fi
 
 _phase_sync

tests/hooks/test-merge-to-main-portability.sh

@@ -172,10 +172,10 @@ assert_contains "test_portability_baseline_skip_info" \
 assert_contains "test_portability_ci_skip_info" \
     "INFO: merge.ci_workflow_name not configured" "$MERGE_OUTPUT1"
 
-# WARNING for no-args sequential run must appear — merge-to-main.sh always emits
-# this when invoked with no arguments (the normal single-step usage pattern).
-assert_contains "test_portability_noargs_warning_present" \
-    "WARNING: Running all phases sequentially" "$MERGE_OUTPUT1"
+# Info message for no-args sequential run must appear — merge-to-main.sh always
+# emits this when invoked with no arguments (the normal single-step usage pattern).
+assert_contains "test_portability_noargs_message_present" \
+    "Running all phases sequentially" "$MERGE_OUTPUT1"
 
 cleanup_env "$TMPENV1"
 

tests/scripts/test-merge-to-main.sh

@@ -642,10 +642,10 @@ HAS_HELP_PHASE=$(grep -c 'phase' "$MERGE_SCRIPT" || true)
 assert_ne "test_cli_help_output_contains_phase" "0" "$HAS_HELP_PHASE"
 
 # =============================================================================
-# Test: --phase argument is parsed in the script
+# Test: --phase argument has been removed from the script
 # =============================================================================
 HAS_PHASE_ARG=$(grep -c '\-\-phase' "$MERGE_SCRIPT" || true)
-assert_ne "test_cli_phase_arg_handled" "0" "$HAS_PHASE_ARG"
+assert_eq "test_cli_phase_arg_removed" "0" "$HAS_PHASE_ARG"
 
 # =============================================================================
 # Test: --resume argument is parsed in the script
@@ -676,12 +676,10 @@ assert_eq "test_cli_help_output_mentions_phase" "true" "$_HELP_HAS_PHASE"
 assert_eq "test_cli_help_exits_0" "0" "$_HELP_RC"
 
 # =============================================================================
-# Test: --phase=<name> dispatches a single named phase and exits
-# We use a no-op phase by checking that passing --phase=push invokes _phase_push
-# via structural check (arg parsing dispatches _phase_$name)
+# Test: --phase flag has been removed (agents should use --resume instead)
 # =============================================================================
-HAS_PHASE_DISPATCH=$(grep -cE '_phase_\$|_phase_.*\$\{.*\}|"_phase_\$' "$MERGE_SCRIPT" || true)
-assert_ne "test_cli_phase_dispatches_function" "0" "$HAS_PHASE_DISPATCH"
+HAS_PHASE_FLAG=$(grep -c '\-\-phase=' "$MERGE_SCRIPT" || true)
+assert_eq "test_cli_phase_flag_removed" "0" "$HAS_PHASE_FLAG"
 
 # =============================================================================
 # Test: --resume reads state file (structural: script uses completed_phases or _state_is_fresh)