From 19135970144ca2b0d51bba54e9a43db94db32d64 Mon Sep 17 00:00:00 2001
From: Justin Lee <justinlee@91app.com>
Date: Tue, 7 Jul 2026 12:53:07 +0800
Subject: [PATCH 01/10] fix(refactor): regenerate cross-language cache when
 older than last commit

Stale .sourceatlas/cross-language.yaml from a previous run silently fed
months-old counts into pilot reports (caught by harness fact-check on
WordPress-iOS after repo update: 3/5 claims failed).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 plugin/commands/refactor/scripts/pilot-run.sh | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/plugin/commands/refactor/scripts/pilot-run.sh b/plugin/commands/refactor/scripts/pilot-run.sh
index d6ee2c3..fdca91e 100755
--- a/plugin/commands/refactor/scripts/pilot-run.sh
+++ b/plugin/commands/refactor/scripts/pilot-run.sh
@@ -72,9 +72,15 @@ bash "$SCRIPT_DIR/detect-zones.sh" "$TARGET" 2>&1 >> "$OUTPUT" || true
 echo '```' >> "$OUTPUT"
 echo "" >> "$OUTPUT"
 
-# Cross-language context (global — regenerate only if missing)
+# Cross-language context (global — regenerate if missing or older than last commit)
 xlang_file="$PROJECT_ROOT/.sourceatlas/cross-language.yaml"
-if [[ ! -f "$xlang_file" ]]; then
+xlang_stale=0
+if [[ -f "$xlang_file" ]]; then
+    last_commit=$(git -C "$PROJECT_ROOT" log -1 --format=%ct 2>/dev/null || echo 0)
+    cache_mtime=$(stat -f %m "$xlang_file" 2>/dev/null || stat -c %Y "$xlang_file" 2>/dev/null || echo 0)
+    [[ "$cache_mtime" -lt "$last_commit" ]] && xlang_stale=1
+fi
+if [[ ! -f "$xlang_file" || "$xlang_stale" = 1 ]]; then
     bash "$SCRIPT_DIR/cross-language-visibility.sh" "$PROJECT_ROOT" >/dev/null 2>&1 || true
 fi
 echo "## Cross-Language Visibility (project-level)" >> "$OUTPUT"

From fcedd313afe3506293c0f44d7fbcb2667428cdc9 Mon Sep 17 00:00:00 2001
From: Justin Lee <justinlee@91app.com>
Date: Tue, 7 Jul 2026 12:53:08 +0800
Subject: [PATCH 02/10] feat(refactor): extend state machine to Steps 8-13 with
 gate-postswap

- state.sh: step keys 8_new_impl..13_delete_legacy (shadow 9a/9b/9c share
  9_swap); advance refuses past final step 13
- init-state.sh + templates/state.yaml: schema 2.1 adds six step entries
  (old 2.0 state files unchanged through Step 7)
- mode-dispatch.yaml: S8-S13 apply in every mode
- gate-postswap.sh: Done-When grep signals for Steps 8/12/13 as exit
  codes; SKILL.md tables now point at it
- test-postswap.sh: 9-assertion self-check (state walk 7-13 + gate
  pass/fail both directions)
- SKILL.md: Gotchas section seeded with the stale-cache lesson

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 plugin/commands/refactor/SKILL.md             |  19 ++-
 .../refactor/references/mode-dispatch.yaml    |  40 +++++
 .../refactor/scripts/gate-postswap.sh         | 137 ++++++++++++++++++
 .../commands/refactor/scripts/init-state.sh   |   8 +-
 plugin/commands/refactor/scripts/state.sh     |  12 +-
 .../refactor/scripts/test-postswap.sh         |  71 +++++++++
 plugin/commands/refactor/templates/state.yaml |  10 +-
 7 files changed, 288 insertions(+), 9 deletions(-)
 create mode 100755 plugin/commands/refactor/scripts/gate-postswap.sh
 create mode 100755 plugin/commands/refactor/scripts/test-postswap.sh

diff --git a/plugin/commands/refactor/SKILL.md b/plugin/commands/refactor/SKILL.md
index 3d4ae5c..9b97316 100644
--- a/plugin/commands/refactor/SKILL.md
+++ b/plugin/commands/refactor/SKILL.md
@@ -170,7 +170,7 @@ The Playbook Navigator adds:
 
 ## Steps 8-13: Post-Tool Guidance
 
-Steps 8-13 are **user-driven** without tool assistance. After Step 7 passes, output the table below — each row names the starting artifact, the concrete action, and the verifiable Done signal so the user can self-check.
+Steps 8-13 are **user-driven**, but state-tracked: `state.sh advance` continues past Step 7, and `bash "${CLAUDE_PLUGIN_ROOT}/commands/refactor/scripts/gate-postswap.sh" --module <m> --step <8|12|13>` machine-verifies the grep-checkable Done signals below (Steps 9-11 are verified by test suites — re-run `gate-step7.sh` / the full suite). After Step 7 passes, output the table below — each row names the starting artifact, the concrete action, and the verifiable Done signal so the user can self-check.
 
 > **Mode variants**: The table below shows `seam-injection` (default). For `platform-migration`, `strangler-fig`, or `platform-strangler`, see **[references/steps-8-13-by-mode.md](references/steps-8-13-by-mode.md)**.
 > Check `state.yaml → migration_mode.mode_name` to determine which path to follow.
@@ -179,12 +179,12 @@ Steps 8-13 are **user-driven** without tool assistance. After Step 7 passes, out
 
 | Step | Start From | Do (concrete actions) | Done When (verifiable signal) |
 |------|------------|-----------------------|-------------------------------|
-| 8 — Write New Implementation | `5_interface.{ext}` + `4_tests.{ext}` | Create new file implementing the Seam Interface; no imports of legacy file; inject collaborators via constructor; write unit tests alongside | New file compiles, unit tests green, characterization tests still green, `grep -l "<LegacyClass>" <new-file>` returns no hits |
+| 8 — Write New Implementation | `5_interface.{ext}` + `4_tests.{ext}` | Create new file implementing the Seam Interface; no imports of legacy file; inject collaborators via constructor; write unit tests alongside | New file compiles, unit tests green, characterization tests still green; `gate-postswap.sh --step 8 --impl-file <new-file>` passes |
 | 9 — Swap Implementation | New impl + `3_seams.yaml.recommended.enabling_point` | Replace `LegacyAdapter` with new impl at the ONE injection-site line; no other files touched in this commit | Single-file, single-line wiring change committed; characterization tests still pass |
 | 10 — Run Verification | Swapped code + `7_gate_results.yaml` (baseline) | Re-run `gate-step7.sh`; diff each section (Layer A / Layer B / contract CI) against the baseline | New gate output matches baseline 1:1 — same passes, same counts, no new failures |
 | 11 — Integration Testing | Verified swap from Step 10 | Run full app test suite; manual smoke every user-facing flow touching this module; check perf on hot paths | Full suite green; manual flows pass; no perf regression flagged |
-| 12 — Clean Up | Integrated swap from Step 11 | Delete `6_adapter.{ext}`; rename Seam Interface → final Target Interface name; delete temporary mocks/shims; update imports / re-exports | `grep -r "<AdapterName>"` and `grep -r "<TemporarySeamName>"` both return zero hits; full suite green |
-| 13 — Delete Legacy | Cleaned codebase from Step 12 | `grep -r "<LegacyClassName>"` to confirm zero refs; delete legacy file(s); final full-suite run; one dedicated commit | Legacy file no longer exists; full suite green; deletion is its own commit (not bundled with refactor work) |
+| 12 — Clean Up | Integrated swap from Step 11 | Delete `6_adapter.{ext}`; rename Seam Interface → final Target Interface name; delete temporary mocks/shims; update imports / re-exports | `gate-postswap.sh --step 12` passes (adapter + temporary seam name zero refs); full suite green |
+| 13 — Delete Legacy | Cleaned codebase from Step 12 | Delete legacy file(s); final full-suite run; one dedicated commit | `gate-postswap.sh --step 13` passes (legacy file gone, zero class refs); full suite green; deletion is its own commit (not bundled with refactor work) |
 
 ### Mode: `seam-injection` — swap_strategy: `shadow`
 
@@ -198,8 +198,8 @@ Steps 8-13 are **user-driven** without tool assistance. After Step 7 passes, out
 | 9c — Hard Swap | Threshold met + `3_seams.yaml.recommended.enabling_point` | Replace `ShadowAdapter` with new impl directly at the ONE injection site. Single-file, single-line commit. | Characterization tests pass; shadow logger no longer called; `grep -l "ShadowAdapter" <wiring-file>` = 0 hits |
 | 10 — Run Verification | Swapped code + `7_gate_results.yaml` (baseline) | Re-run `gate-step7.sh`; diff against baseline | Baseline matched 1:1 |
 | 11 — Integration Testing | Verified swap from Step 10 | Full suite + manual smoke | Full suite green; no perf regression |
-| 12 — Clean Up | Integrated swap from Step 11 | Delete `6_adapter.{ext}` (ShadowAdapter) + `6_logger_protocol.{ext}`; rename Seam Interface; delete logger implementation | `grep -r "ShadowAdapter\|ShadowLogger"` = 0 hits; full suite green |
-| 13 — Delete Legacy | Cleaned codebase from Step 12 | Confirm zero refs to legacy class; delete; own commit | Legacy file deleted; full suite green |
+| 12 — Clean Up | Integrated swap from Step 11 | Delete `6_adapter.{ext}` (ShadowAdapter) + `6_logger_protocol.{ext}`; rename Seam Interface; delete logger implementation | `gate-postswap.sh --step 12` passes (also checks the shadow logger protocol); full suite green |
+| 13 — Delete Legacy | Cleaned codebase from Step 12 | Delete legacy file; own commit | `gate-postswap.sh --step 13` passes; full suite green |
 
 > See [references/playbook-overview.md](references/playbook-overview.md) for the complete 13-step overview with detailed checklists per step.
 
@@ -255,3 +255,10 @@ $STEP_OUTPUT
 - **[../seam/references/seam-types.md](../seam/references/seam-types.md)** — Seam type taxonomy
 - **scripts/gate-contracts.sh** — Gate 2: deterministic contract verification dry-run
 - **scripts/gate-seams.sh** — Gate 3: deterministic enabling point existence check
+- **scripts/gate-postswap.sh** — Steps 8/12/13: grep-checkable Done-When signals as exit codes (self-test: `scripts/test-postswap.sh`)
+
+---
+
+## Gotchas
+
+- **`.sourceatlas/` caches lie after the repo moves on.** A cached `cross-language.yaml` from months ago silently fed stale counts into pilot reports (caught by fact-checking against a freshly updated repo, 2026-07). `pilot-run.sh` now regenerates any cache older than the last commit — apply the same freshness check before trusting any other `.sourceatlas/` artifact.
diff --git a/plugin/commands/refactor/references/mode-dispatch.yaml b/plugin/commands/refactor/references/mode-dispatch.yaml
index 8260c10..8d15bf4 100644
--- a/plugin/commands/refactor/references/mode-dispatch.yaml
+++ b/plugin/commands/refactor/references/mode-dispatch.yaml
@@ -97,6 +97,46 @@ steps:
       replacement_script:    gate-platform-migration.sh
       note:                  "Runs both platform checks and strangler plan verification."
 
+  # Steps 8-13 apply in every mode; mode-specific actions live in
+  # references/steps-8-13-by-mode.md (strangler modes loop 8-12 per zone).
+  # gate-postswap.sh verifies the grep-checkable Done-When signals for 8/12/13.
+
+  S8_new_impl:
+    seam-injection:          applies
+    platform-migration:      applies
+    strangler-fig:           applies
+    platform-strangler:      applies
+
+  S9_swap:
+    seam-injection:          applies
+    platform-migration:      applies
+    strangler-fig:           applies
+    platform-strangler:      applies
+
+  S10_verification:
+    seam-injection:          applies
+    platform-migration:      applies
+    strangler-fig:           applies
+    platform-strangler:      applies
+
+  S11_integration:
+    seam-injection:          applies
+    platform-migration:      applies
+    strangler-fig:           applies
+    platform-strangler:      applies
+
+  S12_cleanup:
+    seam-injection:          applies
+    platform-migration:      applies
+    strangler-fig:           applies
+    platform-strangler:      applies
+
+  S13_delete_legacy:
+    seam-injection:          applies
+    platform-migration:      applies
+    strangler-fig:           applies
+    platform-strangler:      applies
+
 # Skip reasons written to state.yaml when dispatch == skip:
 #   state.steps.SN.status = "skipped"
 #   state.steps.SN.skip_reason = <skip_reason from above>
diff --git a/plugin/commands/refactor/scripts/gate-postswap.sh b/plugin/commands/refactor/scripts/gate-postswap.sh
new file mode 100755
index 0000000..ca6f4f8
--- /dev/null
+++ b/plugin/commands/refactor/scripts/gate-postswap.sh
@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# gate-postswap.sh — deterministic Done-When checks for Playbook Steps 8, 12, 13.
+#
+# Turns the grep-checkable signals from SKILL.md's Steps 8-13 tables into exit
+# codes, so "cleanup complete" is a gate, not a claim. Steps 9-11 are verified
+# by test suites (re-run gate-step7.sh / your full suite) — not this script.
+#
+# Usage:
+#   gate-postswap.sh --module <m> --step 8  --impl-file <path>
+#   gate-postswap.sh --module <m> --step 12 [--adapter-name <N>] [--seam-name <N>] [--skip-seam-check]
+#   gate-postswap.sh --module <m> --step 13
+#
+# Name resolution (when flags omitted):
+#   legacy class  = basename of 1_target.yaml `file:` without extension
+#   adapter name  = first class/struct/@interface identifier in 6_adapter.* artifact
+#   seam name     = 5_interface.yaml protocol.name
+#   shadow logger = 5_interface.yaml shadow_config.logger_protocol (shadow strategy only)
+#
+# Exit codes: 0 pass · 1 usage · 2 state/artifact missing · 3 gate failed
+set -uo pipefail
+
+PROJECT_ROOT="${PROJECT_ROOT:-$(pwd)}"
+
+MODULE="" STEP="" IMPL_FILE="" ADAPTER_NAME="" SEAM_NAME="" SKIP_SEAM=0
+
+usage() {
+    grep '^# ' "$0" | sed 's/^# //' >&2
+    exit 1
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --module)          MODULE="$2";       shift 2 ;;
+        --step)            STEP="$2";         shift 2 ;;
+        --impl-file)       IMPL_FILE="$2";    shift 2 ;;
+        --adapter-name)    ADAPTER_NAME="$2"; shift 2 ;;
+        --seam-name)       SEAM_NAME="$2";    shift 2 ;;
+        --skip-seam-check) SKIP_SEAM=1;       shift ;;
+        *) echo "error: unknown flag: $1" >&2; usage ;;
+    esac
+done
+
+[[ -n "$MODULE" && -n "$STEP" ]] || usage
+
+state_dir="$PROJECT_ROOT/.sourceatlas/refactor/$MODULE"
+target_yaml="$state_dir/1_target.yaml"
+interface_yaml="$state_dir/5_interface.yaml"
+[[ -d "$state_dir" ]] || { echo "error: no state dir at $state_dir" >&2; exit 2; }
+
+# Search excludes: vendored/build dirs plus the playbook's own artifacts,
+# which legitimately mention every name we grep for.
+GREP_EXCLUDES=(--exclude-dir=.git --exclude-dir=.sourceatlas --exclude-dir=Pods
+               --exclude-dir=node_modules --exclude-dir=build --exclude-dir=.build
+               --exclude-dir=DerivedData --exclude-dir=Carthage --exclude-dir=vendor)
+
+ref_count() {  # ref_count <name> → number of referencing lines in the project
+    grep -rn "${GREP_EXCLUDES[@]}" -- "$1" "$PROJECT_ROOT" 2>/dev/null | wc -l | tr -d ' '
+}
+
+yaml_value() {  # yaml_value <file> <key> → first "key: value", quotes stripped
+    awk -v key="$2" '$0 ~ "^[[:space:]]*" key ":" {
+        sub("^[[:space:]]*" key ":[[:space:]]*", ""); gsub(/["'"'"']/, ""); print; exit
+    }' "$1"
+}
+
+legacy_rel=$(yaml_value "$target_yaml" "file")
+[[ -n "$legacy_rel" ]] || { echo "error: cannot read file: from $target_yaml" >&2; exit 2; }
+legacy_file="$PROJECT_ROOT/$legacy_rel"
+legacy_class=$(basename "$legacy_rel"); legacy_class="${legacy_class%.*}"
+
+pass=0; fail=0
+check() {  # check <label> <ok:0|1> <detail>
+    if [[ "$2" -eq 0 ]]; then echo "  ✅ $1 — $3"; pass=$((pass+1))
+    else echo "  ❌ $1 — $3"; fail=$((fail+1)); fi
+}
+
+echo "gate-postswap: step $STEP · module $MODULE"
+echo "  legacy: $legacy_rel (class: $legacy_class)"
+
+case "$STEP" in
+    8)
+        [[ -n "$IMPL_FILE" ]] || { echo "error: --step 8 requires --impl-file" >&2; exit 1; }
+        [[ -f "$IMPL_FILE" ]]; check "impl_file_exists" $? "$IMPL_FILE"
+        if [[ -f "$IMPL_FILE" ]]; then
+            hits=$(grep -c -- "$legacy_class" "$IMPL_FILE" 2>/dev/null); hits=${hits:-0}
+            [[ "$hits" -eq 0 ]]; check "no_legacy_refs_in_impl" $? "grep '$legacy_class' → $hits hits (need 0)"
+        fi
+        echo "  ℹ compile + unit tests are your gate too — this script only checks the grep signals"
+        ;;
+
+    12)
+        if [[ -z "$ADAPTER_NAME" ]]; then
+            adapter_artifact=$(ls "$state_dir"/6_adapter.* 2>/dev/null | grep -v '\.patch$' | head -1)
+            [[ -n "$adapter_artifact" ]] && ADAPTER_NAME=$(grep -oE '(@interface|class|struct)[[:space:]]+[A-Za-z0-9_]+' "$adapter_artifact" | head -1 | awk '{print $2}')
+        fi
+        [[ -n "$ADAPTER_NAME" ]] || { echo "error: cannot derive adapter name — pass --adapter-name" >&2; exit 2; }
+        hits=$(ref_count "$ADAPTER_NAME")
+        [[ "$hits" -eq 0 ]]; check "adapter_deleted" $? "grep -r '$ADAPTER_NAME' → $hits hits (need 0)"
+
+        if [[ "$SKIP_SEAM" -eq 0 ]]; then
+            [[ -z "$SEAM_NAME" && -f "$interface_yaml" ]] && SEAM_NAME=$(yaml_value "$interface_yaml" "name")
+            if [[ -n "$SEAM_NAME" ]]; then
+                hits=$(ref_count "$SEAM_NAME")
+                [[ "$hits" -eq 0 ]]; check "seam_interface_renamed" $? "grep -r '$SEAM_NAME' → $hits hits (need 0; --skip-seam-check if final name kept)"
+            fi
+        fi
+
+        if [[ -f "$interface_yaml" ]] && [[ "$(yaml_value "$interface_yaml" "swap_strategy")" == "shadow" ]]; then
+            logger=$(yaml_value "$interface_yaml" "logger_protocol")
+            if [[ -n "$logger" ]]; then
+                hits=$(ref_count "$logger")
+                [[ "$hits" -eq 0 ]]; check "shadow_logger_deleted" $? "grep -r '$logger' → $hits hits (need 0)"
+            fi
+        fi
+        ;;
+
+    13)
+        [[ ! -f "$legacy_file" ]]; check "legacy_file_deleted" $? "$legacy_rel"
+        hits=$(ref_count "$legacy_class")
+        [[ "$hits" -eq 0 ]]; check "no_legacy_class_refs" $? "grep -r '$legacy_class' → $hits hits (need 0)"
+        ;;
+
+    *)
+        echo "error: --step must be 8, 12 or 13 (9-11 are test-suite gates)" >&2
+        exit 1
+        ;;
+esac
+
+echo "gate-postswap: $pass passed, $fail failed"
+if [[ "$fail" -eq 0 ]]; then
+    key=$(case "$STEP" in 8) echo 8_new_impl;; 12) echo 12_cleanup;; 13) echo 13_delete_legacy;; esac)
+    echo "PASS — promote with: state.sh set-status --module $MODULE --step $key --status verified"
+    exit 0
+else
+    echo "FAIL — fix the ❌ items above, then re-run"
+    exit 3
+fi
diff --git a/plugin/commands/refactor/scripts/init-state.sh b/plugin/commands/refactor/scripts/init-state.sh
index 4e72710..f6ba242 100755
--- a/plugin/commands/refactor/scripts/init-state.sh
+++ b/plugin/commands/refactor/scripts/init-state.sh
@@ -200,7 +200,7 @@ module_q=$(yaml_dq "$module_name")
 file_q=$(yaml_dq "$file_rel")
 
 cat > "$state_file" <<EOF
-schema_version: "2.0"
+schema_version: "2.1"
 module: $module_q
 file: $file_q
 language: "$language"
@@ -237,6 +237,12 @@ steps:
   5_interface: { status: pending, completed_at: null, migration_type: null, target_language: null, target_interface_ref: null, skip_reason: null }
   6_adapter:   { status: pending, completed_at: null, skip_reason: null }
   7_gate:      { status: pending, completed_at: null, replacement_script: null }
+  8_new_impl:       { status: pending, completed_at: null }
+  9_swap:           { status: pending, completed_at: null }
+  10_verification:  { status: pending, completed_at: null }
+  11_integration:   { status: pending, completed_at: null }
+  12_cleanup:       { status: pending, completed_at: null }
+  13_delete_legacy: { status: pending, completed_at: null }
 EOF
 
 # ── Write 1_target.yaml ─────────────────────────────────────────────────────
diff --git a/plugin/commands/refactor/scripts/state.sh b/plugin/commands/refactor/scripts/state.sh
index 4dae970..9852cf2 100755
--- a/plugin/commands/refactor/scripts/state.sh
+++ b/plugin/commands/refactor/scripts/state.sh
@@ -128,6 +128,12 @@ step_key_for_num() {
         5)   echo "5_interface" ;;
         6)   echo "6_adapter" ;;
         7)   echo "7_gate" ;;
+        8)   echo "8_new_impl" ;;
+        9|9a|9b|9c) echo "9_swap" ;;   # shadow sub-phases share one state entry
+        10)  echo "10_verification" ;;
+        11)  echo "11_integration" ;;
+        12)  echo "12_cleanup" ;;
+        13)  echo "13_delete_legacy" ;;
         *)   echo "" ;;
     esac
 }
@@ -181,12 +187,16 @@ $(get_scalar module) — current_step: $(get_scalar current_step)
   zone_id:       $(get_scalar zone_id)
   language:      $(get_scalar language)
 EOF
-        grep -E '^\s+(1_target|2a_zones|2_contracts|3_seams|4_tests|5_interface|6_adapter|7_gate):' "$state_file" \
+        grep -E '^\s+(1_target|2a_zones|2_contracts|3_seams|4_tests|5_interface|6_adapter|7_gate|8_new_impl|9_swap|10_verification|11_integration|12_cleanup|13_delete_legacy):' "$state_file" \
             | sed 's/^[[:space:]]*/  /'
         ;;
 
     advance)
         current=$(get_scalar current_step)
+        if [[ "$current" == "13" ]]; then
+            echo "error: already at final step 13 — playbook complete. Promote via: state.sh set-status --module $MODULE --step 13_delete_legacy --status verified" >&2
+            exit 3
+        fi
         target_step="${TO_STEP:-$((current + 1))}"
         prev_key=$(step_key_for_num "$current")
         [[ -n "$prev_key" ]] || { echo "error: cannot map current_step=$current" >&2; exit 4; }
diff --git a/plugin/commands/refactor/scripts/test-postswap.sh b/plugin/commands/refactor/scripts/test-postswap.sh
new file mode 100755
index 0000000..bf549cf
--- /dev/null
+++ b/plugin/commands/refactor/scripts/test-postswap.sh
@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# test-postswap.sh — self-check for the Steps 8-13 state extension + gate-postswap.sh.
+# Runs against a throwaway fixture project in mktemp; no network, no side effects.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+T=$(mktemp -d "${TMPDIR:-/tmp}/postswap-test.XXXXXX")
+trap 'rm -rf "$T"' EXIT
+export PROJECT_ROOT="$T"
+
+S() { bash "$SCRIPT_DIR/state.sh" "$@"; }
+G() { bash "$SCRIPT_DIR/gate-postswap.sh" "$@"; }
+
+fail=0
+expect() { # expect <label> <want_exit> <got_exit>
+    if [[ "$2" -eq "$3" ]]; then echo "ok  $1"
+    else echo "FAIL $1 (want exit $2, got $3)"; fail=1; fi
+}
+
+# ── Fixture ─────────────────────────────────────────────────────────────────
+mkdir -p "$T/.sourceatlas/refactor/legacy" "$T/src"
+cat > "$T/.sourceatlas/refactor/legacy/state.yaml" <<'EOF'
+schema_version: "2.1"
+module: "legacy"
+file: "src/Legacy.m"
+current_step: 7
+updated: "x"
+migration_mode:
+  mode_name: "seam-injection"
+steps:
+  7_gate:      { status: produced, completed_at: null, replacement_script: null }
+  8_new_impl:       { status: pending, completed_at: null }
+  9_swap:           { status: pending, completed_at: null }
+  10_verification:  { status: pending, completed_at: null }
+  11_integration:   { status: pending, completed_at: null }
+  12_cleanup:       { status: pending, completed_at: null }
+  13_delete_legacy: { status: pending, completed_at: null }
+EOF
+printf 'module: "legacy"\nfile: "src/Legacy.m"\n' > "$T/.sourceatlas/refactor/legacy/1_target.yaml"
+printf 'protocol:\n  name: "LegacySeam"\nswap_strategy: "direct"\n' > "$T/.sourceatlas/refactor/legacy/5_interface.yaml"
+printf 'class LegacyAdapter: LegacySeam {}\n' > "$T/.sourceatlas/refactor/legacy/6_adapter.swift"
+printf '@implementation Legacy\n@end\n' > "$T/src/Legacy.m"
+
+# ── State machine: advance 7 → 13, then terminal refusal ────────────────────
+S advance --module legacy >/dev/null; expect "advance 7→8" 0 $?
+for step in 8_new_impl 9_swap 10_verification 11_integration 12_cleanup; do
+    S set-status --module legacy --step "$step" --status produced >/dev/null
+    S advance --module legacy >/dev/null
+done
+expect "advance walk reached 13" 0 $?
+S advance --module legacy >/dev/null 2>&1; expect "advance at 13 refused" 3 $?
+
+# ── Gate step 8 ──────────────────────────────────────────────────────────────
+printf 'final class NewImpl {}\n' > "$T/src/NewImpl.swift"
+G --module legacy --step 8 --impl-file "$T/src/NewImpl.swift" >/dev/null; expect "step8 clean impl passes" 0 $?
+printf 'final class NewImpl { let l = Legacy() }\n' > "$T/src/NewImpl.swift"
+G --module legacy --step 8 --impl-file "$T/src/NewImpl.swift" >/dev/null; expect "step8 legacy ref fails" 3 $?
+printf 'final class NewImpl {}\n' > "$T/src/NewImpl.swift"
+
+# ── Gate step 12 ─────────────────────────────────────────────────────────────
+printf 'let x = LegacyAdapter()\n' > "$T/src/Wiring.swift"
+G --module legacy --step 12 >/dev/null; expect "step12 wired adapter fails" 3 $?
+printf 'let x = NewImpl()\n' > "$T/src/Wiring.swift"
+G --module legacy --step 12 >/dev/null; expect "step12 clean passes" 0 $?
+
+# ── Gate step 13 ─────────────────────────────────────────────────────────────
+G --module legacy --step 13 >/dev/null; expect "step13 legacy present fails" 3 $?
+rm "$T/src/Legacy.m"
+G --module legacy --step 13 >/dev/null; expect "step13 deleted passes" 0 $?
+
+[[ "$fail" -eq 0 ]] && echo "ALL PASS" || { echo "FAILURES"; exit 1; }
diff --git a/plugin/commands/refactor/templates/state.yaml b/plugin/commands/refactor/templates/state.yaml
index 8231292..a9ce133 100644
--- a/plugin/commands/refactor/templates/state.yaml
+++ b/plugin/commands/refactor/templates/state.yaml
@@ -1,4 +1,4 @@
-schema_version: "2.0"   # bump when adding required fields; old state without this = v1, treated as seam-injection
+schema_version: "2.1"   # 2.1 adds steps 8-13; old state without this = v1, treated as seam-injection
 module: "{module_name}"
 file: "{file_path}"
 language: "{language}"
@@ -42,3 +42,11 @@ steps:
   5_interface: { status: pending, completed_at: null, migration_type: null, target_language: null, target_interface_ref: null, skip_reason: null }
   6_adapter:   { status: pending, completed_at: null, skip_reason: null }
   7_gate:      { status: pending, completed_at: null, replacement_script: null }
+  # Steps 8-13: post-gate execution. User-driven; gate-postswap.sh verifies 8/12/13.
+  # Shadow swap (9a/9b/9c) shares the 9_swap entry — sub-phase progress lives in the shadow dashboard, not here.
+  8_new_impl:       { status: pending, completed_at: null }
+  9_swap:           { status: pending, completed_at: null }
+  10_verification:  { status: pending, completed_at: null }
+  11_integration:   { status: pending, completed_at: null }
+  12_cleanup:       { status: pending, completed_at: null }
+  13_delete_legacy: { status: pending, completed_at: null }

From ada5e62e2c5c6e3f0cf77f6ca420ec821ad9be55 Mon Sep 17 00:00:00 2001
From: Justin Lee <justinlee@91app.com>
Date: Tue, 7 Jul 2026 13:04:09 +0800
Subject: [PATCH 03/10] =?UTF-8?q?docs(refactor):=20Plan=20A=20redo=20spec?=
 =?UTF-8?q?=20executed=20=E2=80=94=20Step=201=20gate=20PASS=20on=20WordPre?=
 =?UTF-8?q?ss-iOS?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#28 fix verified E2E: init-state.sh reuses prior pilot report without
state.yaml, no hand-edits, schema 2.1, candidate locked. Step 2b blocked
by /atlas.audit external-CLI dependency (gemini CLI dead as of 2026-07)
— tracked as follow-up.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../2026-05/2026-05-05-plan-a-redo-spec.md    | 33 ++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/dev-notes/2026-05/2026-05-05-plan-a-redo-spec.md b/dev-notes/2026-05/2026-05-05-plan-a-redo-spec.md
index 0fe4e8e..362a9a5 100644
--- a/dev-notes/2026-05/2026-05-05-plan-a-redo-spec.md
+++ b/dev-notes/2026-05/2026-05-05-plan-a-redo-spec.md
@@ -1,9 +1,40 @@
 ---
 date: 2026-05-05
 session: Plan A redo spec
-status: pending execution
+status: executed 2026-07-07 — Step 1 gate PASS, Step 2a PASS, Step 2b blocked (see record below)
 ---
 
+## 執行紀錄（2026-07-07）
+
+實際執行環境與原 spec 不同：改在開源測試專案 WordPress-iOS 上執行（rank #1
+`AztecPostViewController.swift`，3742 行 Swift，Group A），以 harness pilot 報告
+複製為 `.sourceatlas/refactor/pilot-aztecpostviewcontroller.md` 重建 #28 場景
+（有 pilot、無 state.yaml）。由乾淨 context 的 agent 依 SKILL.md 執行。
+
+```
+執行日期：2026-07-07
+Step 1:
+  - 第一個實質 bash 呼叫：init-state.sh ✅（其前僅兩個唯讀 ls 環境確認）
+  - Reusing pilot report？ ✅ "→ Reusing existing pilot report: ..."
+  - 手改 state.yaml？ ✅ 無（全程走 init-state.sh / init-step2a.sh / state.sh）
+  - state.yaml schema_version：2.1（steps-8-13 擴充後的新 schema）
+  - current_step after Step 1：1 → 2a 後 2
+  - 1_target.yaml 存在？ ✅（score 18710 → proceed；candidate_lock.locked: true）
+  - 整體判定：PASS — #28 修法驗證通過
+Step 2:
+  - init-step2a.sh 呼叫？ ✅
+  - 2a_zones.yaml 產生？ ✅（67 zones；recommended: screenshot-generation-add-ons）
+  - state.sh advance 呼叫？ ✅（1_target verified）
+  - Session boundary STOP？ ⚠️ 未達 — Step 2b 被 /atlas.audit 的 gemini/codex
+    外部 CLI 硬依賴（CR5）擋下；gemini CLI 已被 Google 終止個人版（2026-07 實測
+    IneligibleTierError），真實使用者現在必然進 degraded mode
+  - 整體判定：Step 2a PASS；Step 2b 依賴問題另案處理（audit 改 subagent 化）
+
+結論：#28（CR14 unmanaged-state gap）修法驗證通過。後續：/atlas.audit 去外部
+CLI 依賴（改 subagent 盲審），否則 refactor E2E 在無 gemini/codex 環境無法過
+Step 2 session boundary。
+```
+
 # Plan A Redo — E2E Smoke Test Spec
 
 ## 目標

From 88781e559ebc6a45cbfecd603f41bdd4a897c674 Mon Sep 17 00:00:00 2001
From: Justin Lee <justinlee@91app.com>
Date: Tue, 7 Jul 2026 13:35:21 +0800
Subject: [PATCH 04/10] feat(audit,seam): replace gemini with agy; subagent
 fallback replaces degraded mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

gemini CLI is dead for individual accounts (IneligibleTierError, 2026-07).
Reviewer policy is now: blind scan = agy CLI, adversarial = codex CLI;
either missing or failing at runtime falls back to a fresh-context Claude
subagent with the identical prompt — independence comes from the clean
context, not the vendor. The pipeline never blocks, so the entire
degraded-mode machinery (prompt files for manual execution) is deleted.

- audit/seam SKILL.md: reviewer resolution, fallback rules, reviewers:
  field in outputs; Task added to allowed-tools; seam description gains
  when-to-use triggers; CONFIRM_RATIO 30-70% relabeled as unvalidated
  reference heuristic
- seam/refactor workflow.md: gemini sections rewritten as blind-scan with
  agy Option A / subagent Option B; vendor-neutral artifact names
  (3_seams_blind.md, adversary-output.md); audit_mode degraded → subagent

Verified live: refactor_harness grading now runs GRADERS=(agy claude) —
agy graded all 3 pilots successfully (~15s each).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 plugin/commands/audit/SKILL.md       |  37 ++++------
 plugin/commands/refactor/workflow.md |  62 ++++++++---------
 plugin/commands/seam/SKILL.md        |  44 ++++++------
 plugin/commands/seam/workflow.md     | 100 ++++++++++-----------------
 4 files changed, 103 insertions(+), 140 deletions(-)

diff --git a/plugin/commands/audit/SKILL.md b/plugin/commands/audit/SKILL.md
index 033cf27..9b137ec 100644
--- a/plugin/commands/audit/SKILL.md
+++ b/plugin/commands/audit/SKILL.md
@@ -1,12 +1,12 @@
 ---
 name: audit
-description: Extracts implicit behavior contracts from legacy code before refactoring, using a 3-LLM cross-validation pipeline (Gemini blind scan → Claude structured audit → Codex adversarial review) with machine-verifiable grep/ast-grep assertions. Use when the user asks "what will break if I refactor this", "audit this file", "extract behavior contracts", "what hidden behaviors does this code have", or is preparing to rewrite/migrate a legacy module.
+description: Extracts implicit behavior contracts from legacy code before refactoring, using a cross-validated pipeline (blind scan → Claude structured audit → adversarial review, each in an independent context) with machine-verifiable grep/ast-grep assertions. Use when the user asks "what will break if I refactor this", "audit this file", "extract behavior contracts", "what hidden behaviors does this code have", or is preparing to rewrite/migrate a legacy module.
 model: sonnet
-allowed-tools: Bash, Glob, Grep, Read, Write
+allowed-tools: Bash, Glob, Grep, Read, Write, Task
 argument-hint: "<file-path> [--language objc|swift|typescript|javascript] [--zone <zone-id>] [--force]"
 ---
 
-# SourceAtlas: Contract Audit (Multi-LLM Cross-Validation)
+# SourceAtlas: Contract Audit (Cross-Validation)
 
 **Arguments**: $ARGUMENTS
 
@@ -30,13 +30,13 @@ Warn if older than 30 days — code may have changed.
 - **Target**: first non-flag argument. If not a file, fuzzy-search (`find . -name "*<basename>*"`, excluding `.git/`, `node_modules/`) and ask the user to pick.
 - **Language**: `--language` flag wins; else map extension (`.m/.h`→objc, `.swift`→swift, `.ts/.tsx`→typescript, `.js/.jsx`→javascript, `.kt`→kotlin, `.py`→python, `.go`→go, `.rs`→rust, `.java`→java). Unknown → generic analysis with a note.
 - **Zone scoping**: with `--zone <id>`, read `.sourceatlas/seam/{module}.yaml` (from `/atlas.seam`), extract that zone's `start_line`/`end_line`, and audit only `sed -n "${START},${END}p"` of the file. Keep contract line references absolute to the original file. If the seam file or zone is missing, list available zones and stop.
-- **LLM CLIs**: check `command -v gemini` and `command -v codex`. Either missing → degraded mode (step 4).
+- **Reviewers**: blind scan runs on the `agy` CLI (`agy -p "<prompt>"`); adversarial review on the `codex` CLI (`codex exec -`). If either is missing or fails (e.g. quota), substitute a **fresh-context Claude subagent** (Task tool) given the exact same prompt — independence comes from the clean context, not the vendor. Record which reviewer actually ran (see report).
 
 ## 3. Pipeline
 
 **Step 0 — Boundary discovery.** `rg` the codebase for the module's neighbors: imports/includes of it, references to its types, and notification/event names it posts or observes. These files are context for every later step.
 
-**Step 1 — Gemini blind scan.** Ask the `gemini` CLI to independently list hidden behaviors of the target (plus boundary context), with file:line evidence. Blind means: do NOT show Gemini the contract taxonomy or your own draft — independence prevents confirmation bias.
+**Step 1 — Blind scan.** Ask the blind reviewer (`agy`, or subagent fallback) to independently list hidden behaviors of the target (plus boundary context), with file:line evidence. Blind means: do NOT show the reviewer the contract taxonomy or your own draft — independence prevents confirmation bias.
 
 **Step 2 — Claude structured audit (you).** Read the target and boundary files. Extract formal contracts using this taxonomy:
 
@@ -53,29 +53,20 @@ Warn if older than 30 days — code may have changed.
 
 Each contract records: Trigger, Input, Output, Condition, Ordering, Risk (LOW/MEDIUM/HIGH + reason), Evidence (file:line + snippet), Scope (method/class/module), Seam_Type (object/preprocessing/link/none), Pinch_Point (true/false), and a machine-verifiable grep or ast-grep assertion.
 
-**Step 3 — Codex adversarial review.** Feed the contract list to the `codex` CLI with an adversarial brief: for each contract answer CONFIRM, DISPUTE (with reasoning), or ADD missing contracts. CONFIRM_RATIO = confirmed/total; healthy range is 30–70%. >70% means the review wasn't critical enough; <30% means the contracts need revision.
+**Step 3 — Adversarial review.** Feed the contract list to the adversarial reviewer (`codex`, or subagent fallback) with an adversarial brief: for each contract answer CONFIRM, DISPUTE (with reasoning), or ADD missing contracts. CONFIRM_RATIO = confirmed/total; healthy range is 30–70% (unvalidated heuristic — treat as a reference value, not a gate). >70% means the review wasn't critical enough; <30% means the contracts need revision.
 
 **Step 4 — Merge (you).** Resolve disputes, integrate additions, produce the final list plus CI rules.
 
 **Methodology rules** (non-negotiable):
 1. Every contract cites file:line evidence — no evidence, no contract.
-2. A contract needs at least 2 of 3 LLMs agreeing to survive the merge.
+2. A contract needs at least 2 of the 3 independent reviewers agreeing to survive the merge.
 3. Every contract ships a runnable grep/ast-grep assertion (grep fallback when ast-grep is unavailable, e.g. Objective-C).
-4. Codex DISPUTEs often reveal real issues — resolve them explicitly, don't discard.
+4. Adversarial DISPUTEs often reveal real issues — resolve them explicitly, don't discard.
 5. If no contracts are found, say so: the file may be a leaf module — suggest `/atlas.impact` instead.
 
-## 4. Degraded mode
+## 4. Reviewer fallback
 
-If `gemini` or `codex` is missing, generate the prompts as files instead and tell the user how to run them manually:
-
-```
-.sourceatlas/audit/prompts/
-├── step1-gemini.md   # feed to Gemini
-├── step2-claude.md   # feed to Claude, include Gemini output
-└── step3-codex.md    # feed to Codex, include Claude output
-```
-
-Then: re-run `/atlas.audit <file> --force` and paste the outputs to merge. Still perform Step 2 yourself — Claude's structured audit is always available; mark the result `degraded: true`.
+The pipeline never blocks on a missing CLI. Blind scan: `agy` unavailable/failing → spawn a fresh-context Claude subagent with the same blind prompt (no taxonomy, no draft). Adversarial: `codex` unavailable/failing → same, with the adversarial brief. The subagent must not see this session's reasoning — pass only the prompt and file paths. Record the substitution in `reviewers:` so readers know the vendor diversity of this run.
 
 ## 5. Report
 
@@ -93,14 +84,14 @@ Then YAML:
 module: ...
 language: ...
 file: ...
-degraded: false
+reviewers: {blind: agy|claude-subagent, adversarial: codex|claude-subagent}
 summary:
   total_contracts: ...
   by_category: {M: ..., L: ..., N: ..., S: ..., E: ..., C: ..., D: ..., P: ...}
 cross_validation:
-  gemini_behaviors: ...
-  codex: {confirmed: ..., disputed: ..., added: ...}
-  confirm_ratio: ...        # healthy 30–70%
+  blind_behaviors: ...
+  adversarial: {confirmed: ..., disputed: ..., added: ...}
+  confirm_ratio: ...        # reference range 30–70% (unvalidated heuristic)
 contracts:
   - id: M-001               # unique, category prefix + 3 digits
     title: ...
diff --git a/plugin/commands/refactor/workflow.md b/plugin/commands/refactor/workflow.md
index 6c04b43..fede544 100644
--- a/plugin/commands/refactor/workflow.md
+++ b/plugin/commands/refactor/workflow.md
@@ -443,13 +443,13 @@ Run `/atlas.audit {file_path} --zone {zone_id}` on the selected zone.
 
 - If zone was selected, audit only those lines
 - If no zone (small file), audit the entire file
-- **IMPORTANT**: This MUST invoke the actual `/atlas.audit` command (which runs the multi-LLM pipeline: Gemini blind scan → Claude structured audit → Codex adversarial review). Do NOT perform inline contract analysis as a substitute.
+- **IMPORTANT**: This MUST invoke the actual `/atlas.audit` command (which runs the cross-validated pipeline: blind scan → Claude structured audit → adversarial review, each in an independent context). Do NOT perform inline contract analysis as a substitute.
 
 Save result as `2_contracts.yaml`.
 
 Record `audit_mode` in state:
-- `full` — all three LLMs ran (gemini + codex available)
-- `degraded` — one or more LLMs unavailable, Claude-only analysis
+- `full` — blind + adversarial ran on external CLIs (agy / codex)
+- `subagent` — one or both reviewers ran as fresh-context Claude subagents (CLI missing or failed); still cross-validated
 
 ### 2b-alt: Strangler Plan Generation (platform-migration / strangler-fig / platform-strangler only)
 
@@ -577,7 +577,7 @@ After Gate 2 passes, **STOP**. Output session boundary message and do not contin
 
 ```
 ✅ Step 2 complete — {rules_passed}/{rules_total} contract rules verified.
-   audit_mode: {full|degraded}
+   audit_mode: {full|subagent}
 
 ⏸️ Session boundary — start a new session to continue:
    /atlas.refactor {file_path} --step 3
@@ -613,12 +613,10 @@ if [ "$CONTRACT_STATUS" != "verified" ]; then
     exit 1
 fi
 
-# Check LLM CLI availability (degraded mode if missing)
-SEAM_DEGRADED=false
-SEAM_MISSING=""
-command -v gemini &>/dev/null || { SEAM_MISSING="$SEAM_MISSING gemini"; SEAM_DEGRADED=true; }
-command -v codex  &>/dev/null || { SEAM_MISSING="$SEAM_MISSING codex";  SEAM_DEGRADED=true; }
-[ "$SEAM_DEGRADED" = true ] && echo "⚠️ Seam analysis degraded mode: missing$SEAM_MISSING"
+# Resolve reviewers (missing/failing CLI → fresh-context Claude subagent)
+BLIND_REVIEWER=$(command -v agy >/dev/null 2>&1 && echo agy || echo claude-subagent)
+ADV_REVIEWER=$(command -v codex >/dev/null 2>&1 && echo codex || echo claude-subagent)
+echo "reviewers: blind=$BLIND_REVIEWER adversarial=$ADV_REVIEWER"
 ```
 
 **Only read the artifact file. Do NOT re-derive contracts from source code.**
@@ -630,19 +628,19 @@ From the contracts, extract:
 - **Internal dependencies**: Methods within the zone that call each other
 - **Shared state**: Global variables, singletons, class-level state
 
-### 3.2a Gemini Blind Scan
+### 3.2a Blind Scan
 
-> Skip if `SEAM_DEGRADED=true` — generate `.sourceatlas/refactor/{module}/3_seams_gemini_prompt.md` instead.
+Run on `$BLIND_REVIEWER` — `agy -p "<prompt>"`, or a fresh-context Claude subagent (Task tool) with the identical prompt when agy is unavailable/failing.
 
-Gemini receives **only** the source file and `2_contracts.yaml` — **no** Feathers taxonomy, no language group table, no schema. Independence is the value.
+The blind reviewer receives **only** the source file and `2_contracts.yaml` — **no** Feathers taxonomy, no language group table, no schema, none of this session's reasoning. Independence is the value.
 
-Ask Gemini: "Find every external dependency boundary in this file — places where an external class, function, or global is used directly. List them with file:line evidence. Do not classify them."
+Prompt: "Find every external dependency boundary in this file — places where an external class, function, or global is used directly. List them with file:line evidence. Do not classify them."
 
-Save Gemini output to `${STATE_DIR}/3_seams_gemini.md`.
+Save output to `${STATE_DIR}/3_seams_blind.md`.
 
 ### 3.2b Claude Structured Analysis (was 3.2)
 
-With Gemini's blind scan in hand, evaluate each external dependency as a potential seam point:
+With the blind scan in hand, evaluate each external dependency as a potential seam point:
 
 **Group A (Nominal)**:
 - Object Seam: Can we inject this dependency via constructor/init?
@@ -660,17 +658,17 @@ With Gemini's blind scan in hand, evaluate each external dependency as a potenti
 - Monkey-patch Seam: Can we override at runtime?
 - Enabling point: Import statement, module-level reference
 
-Also check Gemini's output for dependencies Claude might have missed — every item in Gemini's list that is not in Claude's candidates must be explicitly accounted for (incorporated or dismissed with reasoning).
+Also check the blind scan for dependencies Claude might have missed — every item in the blind list that is not in Claude's candidates must be explicitly accounted for (incorporated or dismissed with reasoning).
 
 Save Claude's draft candidates to `${STATE_DIR}/3_seams_claude_draft.md`.
 
-### 3.2c Codex Adversarial Review
+### 3.2c Adversarial Review
 
-> Skip if `SEAM_DEGRADED=true` — generate `.sourceatlas/refactor/{module}/3_seams_codex_prompt.md` instead.
+Run on `$ADV_REVIEWER` — `codex`, or a fresh-context Claude subagent with the identical brief when codex is unavailable/failing.
 
-Codex receives: source file, `2_contracts.yaml`, Gemini blind scan, Claude's draft candidates.
+The reviewer receives: source file, `2_contracts.yaml`, the blind scan, Claude's draft candidates.
 
-Codex issues one verdict per candidate, and independently adds any missing:
+It issues one verdict per candidate, and independently adds any missing:
 
 | Verdict | Meaning |
 |---------|---------|
@@ -679,12 +677,12 @@ Codex issues one verdict per candidate, and independently adds any missing:
 | **ADD** | Missing dependency or seam type |
 | **FLAG** | Architectural issue seams cannot solve (e.g., shared mutable state) |
 
-Save Codex output to `${STATE_DIR}/3_seams_codex.md`.
+Save output to `${STATE_DIR}/3_seams_adversary.md`.
 
 ### 3.2d Claude Merge
 
 Produce the final seam candidates:
-1. **DISPUTED**: Re-evaluate — drop if Codex's objection holds, keep with explicit reasoning if not
+1. **DISPUTED**: Re-evaluate — drop if the objection holds, keep with explicit reasoning if not
 2. **ADDED**: Incorporate with seam type classification + `verification_grep`
 3. **FLAGGED**: Record in `seam_validation.architectural_concerns` — not candidates, structural issues
 
@@ -748,18 +746,18 @@ recommended_seam:
   enabling_point: "{description}"
   reason: "{why this is the best seam}"
 seam_validation:
-  mode: "full|degraded"
-  gemini_candidates: {n}
+  reviewers: {blind: agy|claude-subagent, adversarial: codex|claude-subagent}
+  blind_candidates: {n}
   claude_candidates: {n}
-  codex_confirmed: {n}
-  codex_disputed: {n}
-  codex_added: {n}
-  codex_flagged: {n}
+  adversarial_confirmed: {n}
+  adversarial_disputed: {n}
+  adversarial_added: {n}
+  adversarial_flagged: {n}
   architectural_concerns:
     - "{description of structural issue no seam can fix}"
 ```
 
-Set `3_seams: { status: produced, seam_mode: full|degraded }`.
+Set `3_seams: { status: produced, seam_mode: full|subagent }`.
 
 ### Gate 3: Enabling Point Existence Check
 
@@ -885,7 +883,7 @@ Before designing the interface, read these artifacts and extract the listed fiel
 | Source | Fields to Extract | Why |
 |--------|-------------------|-----|
 | `3_seams.yaml` → `recommended_seam` | `seam_type`, `enabling_point`, `target_dependency` | Determines what the interface wraps |
-| `3_seams.yaml` → `seam_candidates[recommended].codex_note` | Parameter requirements, disputed items | Codex may impose constraints on method signature |
+| `3_seams.yaml` → `seam_candidates[recommended].adversarial_note` | Parameter requirements, disputed items | The adversarial reviewer may impose constraints on method signature |
 | `2_contracts.yaml` → contracts matching `recommended_seam.contracts_covered` | `trigger`, `input`, `output`, `ordering` | Method parameters derive from these |
 | Target file header (`.h` / class declaration) | Existing API style, naming conventions, init methods | Interface must match codebase conventions (Group A/B only; Group C skip) |
 | `1_target.yaml` → `language`, `language_group` | Language group for dispatch | Determines Group A/B/C path |
@@ -901,7 +899,7 @@ Before designing the interface, read these artifacts and extract the listed fiel
 
 #### Validation (must confirm before presenting to user)
 
-- [ ] Protocol parameters cover **all** fields required by Codex verdict
+- [ ] Protocol parameters cover **all** fields required by the adversarial verdict
 - [ ] At least one enabling point (init/constructor parameter) declared in target header
 - [ ] Every contract in `recommended_seam.contracts_covered` is mapped to either: a method on the protocol, OR a concrete interceptor/conformer
 - [ ] Layer B test skeletons (from `4_tests`) reference the protocol name — verify with: `grep -l '{ProtocolName}' {test_file}`
diff --git a/plugin/commands/seam/SKILL.md b/plugin/commands/seam/SKILL.md
index daf15cc..40e6444 100644
--- a/plugin/commands/seam/SKILL.md
+++ b/plugin/commands/seam/SKILL.md
@@ -1,8 +1,8 @@
 ---
 name: seam
-description: Discover responsibility zones and seam candidates using multi-LLM cross-validation (Gemini blind scan → Claude structured analysis → Codex adversarial review)
+description: Discover responsibility zones and seam candidates in a large file using cross-validation (blind scan → Claude structured analysis → adversarial review, each in an independent context). Use when a 200+ line file has mixed responsibilities, when audit output is too broad to act on, or before choosing which zone to refactor first.
 model: sonnet
-allowed-tools: Bash, Glob, Grep, Read, Write
+allowed-tools: Bash, Glob, Grep, Read, Write, Task
 argument-hint: "<file-path> [--language objc|swift|typescript|javascript|go|java|kotlin|python|rust] [--force]"
 ---
 
@@ -35,11 +35,11 @@ argument-hint: "<file-path> [--language objc|swift|typescript|javascript|go|java
 ## Quick Start
 
 1. **Parse arguments** → file path + language detection
-2. **Check environment** → gemini CLI, codex CLI (degraded mode if missing)
+2. **Resolve reviewers** → blind scan: `agy` CLI; adversarial: `codex` CLI; either missing/failing → fresh-context Claude subagent with the same prompt
 3. **Run `detect-zones.sh`** → raw zone map (boundaries + methods + message sends)
-4. **Gemini blind scan** → broad seam discovery without Claude framing
+4. **Blind scan** → broad seam discovery without Claude framing
 5. **Claude structured analysis** → cluster by responsibility, identify seam types
-6. **Codex adversarial review** → CONFIRM / DISPUTE / ADD / FLAG
+6. **Adversarial review** → CONFIRM / DISPUTE / ADD / FLAG
 7. **Claude merge** → resolve disputes, integrate additions
 8. **Present zone map** → ranked by refactoring priority + cross-validation summary
 9. **User selects zone** → pipe to `/atlas.audit`
@@ -79,19 +79,19 @@ The script outputs YAML with 3 layers:
 
 > If clang is unavailable, Layer 2/3 falls back to grep — still useful but less precise.
 
-### Step 2: Environment Check
+### Step 2: Resolve Reviewers
 
-Check for `gemini` and `codex` CLIs. If either is missing, enter **degraded mode**: generate prompt files for manual execution and continue with Claude-only analysis, marking output as `mode: degraded`.
+Blind scan runs on the `agy` CLI (`agy -p "<prompt>"`); adversarial review on the `codex` CLI. If either is missing or fails (e.g. quota), substitute a **fresh-context Claude subagent** (Task tool) given the exact same prompt — independence comes from the clean context, not the vendor. Record which reviewer ran in the output (`reviewers:` field).
 
-### Step 3: Gemini Blind Scan
+### Step 3: Blind Scan
 
-Gemini receives **only the source code and detect-zones.sh output** — no taxonomy framing, no Feathers schema. This prevents confirmation bias from Claude's structured prompt.
+The blind reviewer receives **only the source code and detect-zones.sh output** — no taxonomy framing, no Feathers schema. This prevents confirmation bias from Claude's structured prompt.
 
-Gemini outputs: a list of potential injection points, dependency boundaries, and patterns it finds suspicious or hard-coded.
+Blind scan output: a list of potential injection points, dependency boundaries, and patterns it finds suspicious or hard-coded.
 
 ### Step 4: Claude Structured Analysis
 
-With the raw zone map AND Gemini's blind scan in hand, perform semantic analysis:
+With the raw zone map AND the blind scan in hand, perform semantic analysis:
 
 #### 4a. Responsibility Clustering (Sandi Metz's message-passing)
 
@@ -120,23 +120,23 @@ Flag zones exhibiting:
 - **Divergent Change**: Zone changes for unrelated reasons
 - **Shotgun Surgery**: Small change requires touching many zones
 
-### Step 5: Codex Adversarial Review
+### Step 5: Adversarial Review
 
-Codex receives: source code, detect-zones.sh output, Gemini blind scan, Claude's seam candidates.
+The adversarial reviewer receives: source code, detect-zones.sh output, the blind scan, Claude's seam candidates.
 
-Codex issues one verdict per candidate — and independently adds any it finds missing:
+It issues one verdict per candidate — and independently adds any it finds missing:
 
 | Verdict | Meaning |
 |---------|---------|
 | **CONFIRM** | Seam candidate valid, enabling point exists, coverage claim accurate |
 | **DISPUTE** | Seam type wrong, enabling point missing, or coverage overstated |
-| **ADD** | Dependency or seam type Claude missed (Gemini or Codex found it) |
+| **ADD** | Dependency or seam type Claude missed (blind or adversarial reviewer found it) |
 | **FLAG** | Architectural issue seams cannot solve (e.g., shared mutable state) |
 
 ### Step 6: Claude Merge (1 minute)
 
 Resolve disputes and integrate additions to produce the final seam list:
-- **DISPUTED** candidates: re-evaluate with evidence from both sides; drop if Codex's objection holds
+- **DISPUTED** candidates: re-evaluate with evidence from both sides; drop if the objection holds
 - **ADDED** candidates: incorporate with Claude's seam type classification
 - **FLAGGED** concerns: record in `seam_validation.architectural_concerns`
 
@@ -196,9 +196,9 @@ Or suggest copy-pasting the zone into a temporary file for isolated audit.
 │  ...
 
 🎯 Cross-Validation
-- Gemini candidates: N
-- Claude candidates: M
-- Codex confirmed: X / disputed: Y / added: Z / flagged: W
+- Reviewers: blind=agy|claude-subagent, adversarial=codex|claude-subagent
+- Blind candidates: N / Claude candidates: M
+- Adversarial: confirmed X / disputed Y / added Z / flagged W
 [Architectural concerns, if any]
 
 🎯 Recommendation
@@ -220,9 +220,9 @@ Run: /atlas.audit $FILE_PATH --lines 295-410
 4. **Compose with audit**: Output must be directly usable as `/atlas.audit` input
 5. **One File at a Time**: Do not batch-process multiple files
 6. **Graceful Degradation**: No clang? Use grep-based deps. No pragma marks? Use method clustering.
-7. **Cross-Validated**: Seam candidates require Gemini blind scan + Codex adversarial review. Claude-only analysis is degraded mode only.
-8. **Gemini sees no taxonomy**: The blind scan prompt must NOT include Feathers seam types, language groups, or Claude's candidate list. Independence is the value.
-9. **Degraded Mode**: If `gemini` or `codex` CLI is unavailable, generate prompt files in `.sourceatlas/seam/prompts/` and mark output `mode: degraded`.
+7. **Cross-Validated**: Seam candidates require a blind scan + an adversarial review, each in an independent context (CLI or fresh Claude subagent). Never present Claude-only inline analysis as cross-validated.
+8. **Blind reviewer sees no taxonomy**: The blind scan prompt must NOT include Feathers seam types, language groups, or Claude's candidate list. Independence is the value.
+9. **Reviewer fallback, never blocked**: `agy` missing/failing → fresh-context Claude subagent for the blind scan; `codex` missing/failing → same for the adversarial review. The subagent gets only the prompt and file paths — none of this session's reasoning. Record substitutions in `reviewers:`.
 
 ---
 
diff --git a/plugin/commands/seam/workflow.md b/plugin/commands/seam/workflow.md
index 6b8d874..f57c40e 100644
--- a/plugin/commands/seam/workflow.md
+++ b/plugin/commands/seam/workflow.md
@@ -80,31 +80,15 @@ Use the existing complexity × coupling formula from Step 5.
 
 ---
 
-## Step 2b: Environment Check
-
-Check for required external LLM CLIs.
+## Step 2b: Resolve Reviewers
 
 ```bash
-DEGRADED=false
-MISSING_TOOLS=""
-
-if ! command -v gemini &>/dev/null; then
-    MISSING_TOOLS="$MISSING_TOOLS gemini"
-    DEGRADED=true
-fi
-
-if ! command -v codex &>/dev/null; then
-    MISSING_TOOLS="$MISSING_TOOLS codex"
-    DEGRADED=true
-fi
-
-if [ "$DEGRADED" = true ]; then
-    echo "⚠️ Degraded mode: missing$MISSING_TOOLS"
-    echo "Will generate prompt files for manual execution in .sourceatlas/seam/prompts/"
-fi
+BLIND_REVIEWER=$(command -v agy >/dev/null 2>&1 && echo agy || echo claude-subagent)
+ADV_REVIEWER=$(command -v codex >/dev/null 2>&1 && echo codex || echo claude-subagent)
+echo "reviewers: blind=$BLIND_REVIEWER adversarial=$ADV_REVIEWER"
 ```
 
-In degraded mode, skip Steps 3 (Gemini) and 5 (Codex) — run Claude-only and mark output `seam_validation.mode: degraded`.
+The pipeline never blocks: when a CLI is missing (or fails at runtime, e.g. quota), the corresponding step runs in a **fresh-context Claude subagent** (Task tool) with the exact same prompt. Independence comes from the clean context, not the vendor. Record what actually ran in `seam_validation.reviewers`.
 
 ---
 
@@ -153,20 +137,18 @@ If `marker_count: 0`, the script outputs `zones: []`. In this case:
 
 ---
 
-## Step 3b: Gemini Blind Scan
+## Step 3b: Blind Scan
 
-> Skip if `DEGRADED=true` — generate prompt file instead.
+The blind reviewer receives **only** the source file content and detect-zones.sh raw output. **Do NOT include**: Feathers seam taxonomy, language group table, or Claude's candidate list. The value of this step is independence.
 
-Gemini receives **only** the source file content and detect-zones.sh raw output. **Do NOT include**: Feathers seam taxonomy, language group table, or Claude's candidate list. The value of this step is independence.
-
-### Option A: Gemini CLI available
+### Option A: `agy` CLI
 
 ```bash
 PROMPTS_DIR=".sourceatlas/seam/prompts"
 mkdir -p "$PROMPTS_DIR"
 
 # Build blind scan prompt (no taxonomy framing)
-cat > "$PROMPTS_DIR/gemini-blind-scan.md" << PROMPT
+cat > "$PROMPTS_DIR/blind-scan.md" << PROMPT
 Look at this source file and the zone map below. Find every place where
 external dependencies are used — things that could be hard-coded, hard to
 replace, or that a test might want to substitute. List them with file:line
@@ -179,16 +161,13 @@ $(cat "$FILE_PATH")
 $(cat "$ZONES_OUTPUT")
 PROMPT
 
-gemini < "$PROMPTS_DIR/gemini-blind-scan.md" > "$PROMPTS_DIR/gemini-output.md"
-echo "✅ Gemini blind scan complete"
+agy -p "$(cat "$PROMPTS_DIR/blind-scan.md")" > "$PROMPTS_DIR/blind-output.md"
+echo "✅ Blind scan complete (agy)"
 ```
 
-### Option B: Degraded (gemini not available)
+### Option B: Claude subagent (agy unavailable or failed)
 
-```bash
-echo "📝 Gemini prompt saved to: $PROMPTS_DIR/gemini-blind-scan.md"
-echo "Run manually and paste output back, or proceed with Claude-only analysis"
-```
+Build the same `blind-scan.md` prompt file, then spawn a **fresh-context subagent** (Task tool) whose entire instruction is that prompt plus "write your findings to `$PROMPTS_DIR/blind-output.md`". Do not pass any of this session's analysis or the taxonomy. Set `reviewers.blind: claude-subagent`.
 
 ---
 
@@ -248,16 +227,14 @@ Check for Fowler's refactoring signals:
 
 ---
 
-## Step 4b: Codex Adversarial Review
+## Step 4b: Adversarial Review
 
-> Skip if `DEGRADED=true` — generate prompt file instead.
+The adversarial reviewer receives: source file, detect-zones.sh output, the blind scan, and Claude's seam candidates.
 
-Codex receives: source file, detect-zones.sh output, Gemini blind scan, and Claude's seam candidates.
-
-### Option A: Codex CLI available
+### Option A: `codex` CLI
 
 ```bash
-cat > "$PROMPTS_DIR/codex-adversary.md" << PROMPT
+cat > "$PROMPTS_DIR/adversary.md" << PROMPT
 You are an adversarial reviewer. Below are seam candidates proposed by two
 prior analyses. Your job: issue a verdict for each candidate, and add any
 you think are missing.
@@ -268,8 +245,8 @@ Verdicts:
 - ADD: dependency or seam type the prior analyses missed
 - FLAG: architectural issue that seams cannot solve (e.g., shared mutable state)
 
-=== GEMINI BLIND SCAN ===
-$(cat "$PROMPTS_DIR/gemini-output.md")
+=== BLIND SCAN ===
+$(cat "$PROMPTS_DIR/blind-output.md")
 
 === CLAUDE SEAM CANDIDATES ===
 $(cat "$PROMPTS_DIR/claude-candidates.md")
@@ -278,33 +255,30 @@ $(cat "$PROMPTS_DIR/claude-candidates.md")
 $(cat "$FILE_PATH")
 PROMPT
 
-codex < "$PROMPTS_DIR/codex-adversary.md" > "$PROMPTS_DIR/codex-output.md"
-echo "✅ Codex adversarial review complete"
+codex < "$PROMPTS_DIR/adversary.md" > "$PROMPTS_DIR/adversary-output.md"
+echo "✅ Adversarial review complete (codex)"
 ```
 
-### Option B: Degraded (codex not available)
+### Option B: Claude subagent (codex unavailable or failed)
 
-```bash
-echo "📝 Codex prompt saved to: $PROMPTS_DIR/codex-adversary.md"
-echo "Run manually and paste output back, or proceed without adversarial review"
-```
+Build the same `adversary.md` prompt file, then spawn a **fresh-context subagent** (Task tool) whose entire instruction is that prompt plus "write your verdicts to `$PROMPTS_DIR/adversary-output.md`". Set `reviewers.adversarial: claude-subagent`.
 
 ---
 
 ## Step 4c: Claude Merge
 
-Resolve the Codex verdicts and produce the final seam list:
+Resolve the adversarial verdicts and produce the final seam list:
 
-1. **DISPUTED candidates**: Re-evaluate with evidence from both sides. Drop if Codex's objection holds. Keep if Claude's evidence is stronger. Never keep without explicit reasoning.
+1. **DISPUTED candidates**: Re-evaluate with evidence from both sides. Drop if the objection holds. Keep if Claude's evidence is stronger. Never keep without explicit reasoning.
 2. **ADDED candidates**: Incorporate with Claude's seam type classification. Add `verification_grep` for each.
 3. **FLAGGED concerns**: Record in `seam_validation.architectural_concerns` — these are not seam candidates, they are structural issues that must be fixed separately.
 
 Tally cross-validation counts:
 ```bash
-CONFIRMED=$(grep -c '^CONFIRM' "$PROMPTS_DIR/codex-output.md" || echo 0)
-DISPUTED=$(grep -c '^DISPUTE' "$PROMPTS_DIR/codex-output.md" || echo 0)
-ADDED=$(grep -c '^ADD' "$PROMPTS_DIR/codex-output.md" || echo 0)
-FLAGGED=$(grep -c '^FLAG' "$PROMPTS_DIR/codex-output.md" || echo 0)
+CONFIRMED=$(grep -c '^CONFIRM' "$PROMPTS_DIR/adversary-output.md" || echo 0)
+DISPUTED=$(grep -c '^DISPUTE' "$PROMPTS_DIR/adversary-output.md" || echo 0)
+ADDED=$(grep -c '^ADD' "$PROMPTS_DIR/adversary-output.md" || echo 0)
+FLAGGED=$(grep -c '^FLAG' "$PROMPTS_DIR/adversary-output.md" || echo 0)
 ```
 
 ---
@@ -348,9 +322,9 @@ Use the output format from [SKILL.md#output-format](SKILL.md#output-format).
 Key presentation rules:
 1. **Ranked list**: Highest priority first
 2. **Visual hierarchy**: Use box-drawing characters for zone tree
-3. **Cross-validation section**: Always include the Gemini/Codex summary
+3. **Cross-validation section**: Always include the blind/adversarial summary and which reviewers ran
 4. **Actionable recommendation**: Always end with a specific `/atlas.audit` command
-5. **Architectural concerns**: If Codex flagged any, list them separately before the recommendation
+5. **Architectural concerns**: If the adversarial reviewer flagged any, list them separately before the recommendation
 6. **Save to cache**: Write YAML to `.sourceatlas/seam/`
 
 ---
@@ -363,13 +337,13 @@ mkdir -p .sourceatlas/seam
 # Include seam_validation block:
 #
 # seam_validation:
-#   mode: "full|degraded"
-#   gemini_candidates: N
+#   reviewers: {blind: agy|claude-subagent, adversarial: codex|claude-subagent}
+#   blind_candidates: N
 #   claude_candidates: M
-#   codex_confirmed: X
-#   codex_disputed: Y
-#   codex_added: Z
-#   codex_flagged: W
+#   adversarial_confirmed: X
+#   adversarial_disputed: Y
+#   adversarial_added: Z
+#   adversarial_flagged: W
 #   architectural_concerns:
 #     - "{description}"
 ```

From 84c763b52ed4caed3aa215174cb15eab8600f57d Mon Sep 17 00:00:00 2001
From: Justin Lee <justinlee@91app.com>
Date: Tue, 7 Jul 2026 15:48:49 +0800
Subject: [PATCH 05/10] fix(refactor): Group C battle scars from express E2E
 full walk (Steps 1-13)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First real run on a Dynamic-group target (express lib/response.js) — nine
script fixes, two documented gaps, all gates now pass end to end:

- detect-zones/pilot-run: kill 'grep -c || echo 0' double-zero (9 sites);
  zero-marker guard now works (the JS norm, previously never exercised)
- init-step2a: synthesize whole-file zone when detect-zones finds none
- gate-contracts/gate-seams/gate-step7: unescape YAML \" in extracted
  verification_grep rules (three copies of the same extraction bug)
- gate-step7: re-run as Step 10 verification no longer regresses
  current_step 10 -> 8 (only advances when current_step <= 7)
- gate-postswap: language-group dispatch for dynamic languages — Steps
  8/13 check module-path require refs instead of bare common-word class
  names ('response' matched ServerResponse and prose); Step 12 handles
  Group C no-adapter-class by design; adapter-name regex anchored to
  line start (was matching 'class exists' inside a comment)
- state.sh: set-status gains --audit-mode full|subagent (workflow requires
  recording it; Rule 15 forbids hand-edits; there was no API)
- SKILL.md: +9 gotchas (agy --add-dir, reviewer CLI death mid-playbook,
  quote-free verification_grep, mocha vs jest for Group C, audit --zone
  interop gap, etc.)
- dev-notes: full scar list for the express E2E run

Verified: test-postswap.sh ALL PASS (Group A unregressed); express walk
reached 13_delete_legacy: verified with npm test green (1258).
---
 .../2026-07-07-express-e2e-steps-1-13.md      | 44 ++++++++++++++++
 plugin/commands/refactor/SKILL.md             |  8 +++
 .../commands/refactor/scripts/detect-zones.sh | 10 ++--
 .../refactor/scripts/gate-contracts.sh        |  4 +-
 .../refactor/scripts/gate-postswap.sh         | 52 ++++++++++++++++---
 .../commands/refactor/scripts/gate-seams.sh   |  3 +-
 .../commands/refactor/scripts/gate-step7.sh   | 14 +++--
 .../commands/refactor/scripts/init-step2a.sh  | 17 ++++++
 plugin/commands/refactor/scripts/pilot-run.sh |  6 +--
 plugin/commands/refactor/scripts/state.sh     | 18 ++++++-
 plugin/commands/seam/scripts/detect-zones.sh  | 10 ++--
 11 files changed, 158 insertions(+), 28 deletions(-)
 create mode 100644 dev-notes/2026-07/2026-07-07-express-e2e-steps-1-13.md

diff --git a/dev-notes/2026-07/2026-07-07-express-e2e-steps-1-13.md b/dev-notes/2026-07/2026-07-07-express-e2e-steps-1-13.md
new file mode 100644
index 0000000..2b2c571
--- /dev/null
+++ b/dev-notes/2026-07/2026-07-07-express-e2e-steps-1-13.md
@@ -0,0 +1,44 @@
+# Express E2E — Playbook Steps 1→13 全程實走（Group C 首測）
+
+日期：2026-07-07 · 執行：Fable 5（handoff 指定下一棒；原規劃 Opus，實際由 Fable 執行）
+目標專案：`~/dev/test_targets/express`（分支 `experiment/refactor-playbook-e2e`，絕不推 upstream）
+Plugin：worktree `steps-8-13`（PR #130 未 merge）
+
+## 結果
+
+- **`13_delete_legacy: verified`** — 全程 `state.sh` / gate scripts 推進，零手改 state.yaml
+- Target：`lib/response.js`（rank-candidates #1，score 2100 = 1050 lines × 2 commits）
+- Seam：Module Seam @ `lib/express.js:21 require('./response')`（單行注入點，覆蓋全部 29 contracts）
+- Step 8 真重寫 895 行 `lib/response-new.js`；swap 前用 require-cache seed 過 400 測試；swap 後 `npm test` 1258 綠；Step 13 刪 `lib/response.js` 獨立 commit
+- express 分支 4 commits：artifacts(1-7) → new impl(8) → 單行 swap(9) → 刪 legacy(13)
+- 審查管線首走：Step 2b `reviewers: {blind: agy, adversarial: codex}`（audit_mode: full）；Step 3 codex 陣亡 → `{blind: agy, adversarial: claude-subagent}`（Sonnet，緩解 #1 順帶實現）
+
+## 傷痕清單（時序）
+
+1. **detect-zones.sh 雙零 bug（JS 零 marker 路徑首踩）** — `grep -c ... || echo 0` 在零命中時輸出 `0\n0`（grep -c 自己印 0 且回傳 1），炸掉 `-eq 0` guard → line 334 unbound variable。同款病灶掃出 3 檔 9 處（refactor/seam 兩份 detect-zones + pilot-run）。諷刺：pilot-run.sh:206 有註解記載此 bug 並寫了 `_ccount()` 正確版，但同檔 143-145 行沒用它——修一處不掃全倉的教訓。全部改 `|| true`。
+2. **init-step2a.sh 零 zone 直接 error** — workflow.md 宣稱 "handles small files (single zone)"，實際沒有 fallback。修：合成單一 whole-file zone。Group C 的 JS 檔沒有 `// MARK:` 是常態——這條路徑之前從未被走過。
+3. **`agy -p` 不繼承 cwd** — 在自己的 scratch dir（`~/.gemini/antigravity-cli/scratch`）遊蕩直到 timeout。修法：`--add-dir "$PWD"`。gemini→agy 換血（PR #130）後首次實戰即暴露。
+4. **三份 gate 腳本的 YAML `\"` 不反轉義** — gate-contracts / gate-seams / gate-step7 各自複製了 sed+eval 抽取邏輯，規則含引號時 eval 拿到字面 `\"`。Gate 2 首跑 21/29「失敗」全是 gate 自己的 bug（handoff gotcha「fact-check 失敗先懷疑 fact-checker」再次應驗）。三處都補 `sed 's/\\"/"/g'`；並學到規則寫法應避免引號（`grep -qE 'cookieParser..secret..'`）。
+5. **state.sh 缺 audit_mode setter** — workflow 要求記錄 audit_mode 到 state，但 Rule 15 禁手改且 state.sh 無 API。加 `set-status --audit-mode full|subagent`。
+6. **codex refresh token 中途陣亡** — Step 2b 正常，Step 3 空輸出 exit 1（`refresh_token_invalidated`）。fallback subagent 管線如設計運作；教訓：CLI 死活要逐次探測，reviewers: 逐 artifact 記錄。
+7. **gate-step7.sh 重跑倒退狀態機** — SKILL.md Step 10 明文要求重跑 gate-step7 驗證 swap，但腳本 pass 時無條件 `current_step: 8`，把 10 拉回 8。修：僅 `current_step ≤ 7` 時推進。
+8. **gate-postswap 通用字 legacy_class（Group C 結構性問題）** — `response` 匹配 `http.ServerResponse`、註解、一切。Step 8 gate 6 hits 全誤傷；Step 13 的全 repo zero-ref 檢查對 JS 通用字模組名不可滿足。修：dynamic languages 改查模組路徑引用 `require('./response')`。
+9. **adapter 名推導把註解當宣告** — regex 未錨行首，把 6_adapter.js 註解 "No adapter **class exists**" 抓成 class 名 `exists`（grep -r 'exists' → 4 hits）。修：錨定行首 + Group C 無 adapter class 時改查 artifact 引用。
+10. **audit `--zone` interop gap（未修，記錄）** — audit 讀 `.sourceatlas/seam/{module}.yaml`，refactor 2a 產 `2a_zones.yaml`。whole-file zone 繞過（不帶 --zone）；真 zone-scoped Group C 會撞牆。
+11. **Group C 指南假設 jest** — express 用 mocha。require-cache seed（6_adapter.js 模式）是 mocha 版 module-seam mock；已寫入 SKILL.md Gotchas。
+12. **gate-seams.sh parser 不停在 candidates 結束** — recommended_seam 欄位滲入最後一個 candidate 的標籤。無害（計數正確），未修。
+13. **express 套件 flaky** — `req.fresh without response headers` 以 ~1/3 機率 socket parse error（供 3 跑 2 綠佐證）；與 swap 無關。另學：`npm test | tail` 吃掉 exit code——差點紅燈 commit，驗證要 `; echo $?` 分開。
+14. **score threshold 對測試專案說 skip** — 2100 分被判 skip（低 churn）。handoff 明令全走 → 以任務授權 override，`--force` 重跑。
+
+## 流程妥協（誠實揭露）
+
+- **Session boundaries（Step 2 後、Step 5 後）被覆蓋** — handoff 明示單一 session 走完 1→13。Step 3 起僅讀 artifacts 不讀前段推理（盲掃/對抗審查本身即獨立 context），但「同 agent 寫同 agent 驗」的偏誤風險客觀存在。
+- **Step 5 swap_strategy 使用者決策點自主判定**（direct；準則表 3/3 指向 direct）——依 handoff 授權，理由記錄於 5_interface.yaml。
+- **Step 11 手動 smoke 從略** — express 無 UI，以 1258 全套件 + examples 隱含覆蓋替代。
+- 主 session 為 Fable（handoff 原規劃 Opus 主導）；subagent 指派遵循建議（對抗審查用 Sonnet、機械驗證直接跑腳本無需 agent）。
+
+## 對 Playbook 的量化回饋
+
+- Steps 1-7 工具鏈在 Group C 的第一次接觸戰打出 9 個 bug 修復 + 2 個記錄性 gap——「沒有傷痕的 workflow 是設計出來的」獲得直接證據。
+- Steps 8-13 表格本身（動作/Done 訊號）在 Group C 語義上成立，但 gate-postswap 的三個檢查全部需要 language-group 分派才能運作——已修。
+- 審查管線（盲掃+對抗）實質有效：對抗審查砍掉 2 個偽 seam 候選（「extraction 不是現存 seam」）、加 2 個我漏掉的消費者路徑、3 條 FLAG 直接變成 Step 8 重寫的硬約束。
diff --git a/plugin/commands/refactor/SKILL.md b/plugin/commands/refactor/SKILL.md
index 9b97316..cf57c87 100644
--- a/plugin/commands/refactor/SKILL.md
+++ b/plugin/commands/refactor/SKILL.md
@@ -262,3 +262,11 @@ $STEP_OUTPUT
 ## Gotchas
 
 - **`.sourceatlas/` caches lie after the repo moves on.** A cached `cross-language.yaml` from months ago silently fed stale counts into pilot reports (caught by fact-checking against a freshly updated repo, 2026-07). `pilot-run.sh` now regenerates any cache older than the last commit — apply the same freshness check before trusting any other `.sourceatlas/` artifact.
+- **`agy -p` runs in its own scratch directory, not your cwd.** Without `--add-dir "$PWD"` the blind reviewer wanders `~/.gemini/antigravity-cli/scratch` until print-timeout and returns garbage. Every agy invocation in this playbook must pass `--add-dir` (first hit: express E2E, 2026-07).
+- **Reviewer CLIs die mid-playbook — fall back per call, not per session.** codex ran Step 2b fine, then its refresh token was revoked before Step 3 (`refresh_token_invalidated`). Probe with a trivial prompt when output is empty, then substitute the fresh-context Claude subagent and record the actual reviewer in that artifact's `reviewers:` — one artifact may say `codex`, the next `claude-subagent`, both true.
+- **Write `verification_grep` rules quote-free.** Three gate scripts (gate-contracts, gate-seams, gate-step7) each re-extract rules with sed + `eval`; YAML `\"` escapes reached eval as literal backslash-quotes until 2026-07 (all three now unescape). Belt-and-braces: prefer `grep -qE` with `.` wildcards over embedded quotes — `cookieParser..secret..` instead of `cookieParser(\"secret\")`.
+- **Group C module names are common words — bare-word grep gates are unsatisfiable.** `lib/response.js` → legacy_class `response`, which matches `http.ServerResponse`, prose, everything. gate-postswap Steps 8/13 now check module-path references (`require('./response')`) for dynamic languages instead of the bare word. Same trap awaits any `utils`/`helpers`/`index` target.
+- **Re-running gate-step7.sh as the Step 10 verification used to reset `current_step` to 8.** SKILL.md Step 10 says "re-run gate-step7" — the script now only advances state when `current_step ≤ 7`. If state ever regresses after a gate, suspect the gate script, not your state.sh usage.
+- **Zero zone markers is the NORM for Group C, not an edge case.** JS/Python files rarely have `// MARK:`-style markers; the zero-marker path had never run before express: `grep -c ... || echo 0` printed a double zero (breaking the guard) and init-step2a.sh had no fallback. Both fixed (init-step2a synthesizes a single whole-file zone) — but treat any "first time on a new language group" run as hostile territory.
+- **`/atlas.audit --zone` reads `.sourceatlas/seam/{module}.yaml`, but refactor Step 2a writes `2a_zones.yaml`.** Interop gap, still open: whole-file zones sidestep it (audit without `--zone`); a real zone-scoped Group C run will hit it. Either run `/atlas.seam` first or pass explicit line ranges.
+- **Group C mock guidance says jest; the repo may use mocha.** Express uses mocha — `jest.mock` does not exist there. The working equivalents: require-cache seeding (see the `6_adapter.js` pattern from the express run) for pre-swap validation, and the require-line swap itself as the migration seam.
diff --git a/plugin/commands/refactor/scripts/detect-zones.sh b/plugin/commands/refactor/scripts/detect-zones.sh
index db2c94f..4efc5c7 100755
--- a/plugin/commands/refactor/scripts/detect-zones.sh
+++ b/plugin/commands/refactor/scripts/detect-zones.sh
@@ -181,22 +181,22 @@ detect_markers_rust() {
 
 detect_methods_objc() {
     local start=$1 end=$2
-    sed -n "${start},${end}p" "$FILE_PATH" | grep -c '^[+-] *(' || echo 0
+    sed -n "${start},${end}p" "$FILE_PATH" | grep -c '^[+-] *(' || true
 }
 
 detect_methods_swift() {
     local start=$1 end=$2
-    sed -n "${start},${end}p" "$FILE_PATH" | grep -cE '^\s*(func |init\(|deinit)' || echo 0
+    sed -n "${start},${end}p" "$FILE_PATH" | grep -cE '^\s*(func |init\(|deinit)' || true
 }
 
 detect_methods_typescript() {
     local start=$1 end=$2
-    sed -n "${start},${end}p" "$FILE_PATH" | grep -cE '^\s*(async\s+)?(function |.*\(.*\)\s*[:{])' || echo 0
+    sed -n "${start},${end}p" "$FILE_PATH" | grep -cE '^\s*(async\s+)?(function |.*\(.*\)\s*[:{])' || true
 }
 
 detect_methods_generic() {
     local start=$1 end=$2
-    sed -n "${start},${end}p" "$FILE_PATH" | grep -cE '^\s*(pub\s+)?(fn |func |def |fun )' || echo 0
+    sed -n "${start},${end}p" "$FILE_PATH" | grep -cE '^\s*(pub\s+)?(fn |func |def |fun )' || true
 }
 
 count_methods() {
@@ -299,7 +299,7 @@ detect_markers() {
 
 MARKERS=$(detect_markers)
 
-MARKER_COUNT=$(echo "$MARKERS" | grep -c . || echo 0)
+MARKER_COUNT=$(echo "$MARKERS" | grep -c . || true)
 
 # --- Output YAML ---
 
diff --git a/plugin/commands/refactor/scripts/gate-contracts.sh b/plugin/commands/refactor/scripts/gate-contracts.sh
index 353796e..7c1d285 100755
--- a/plugin/commands/refactor/scripts/gate-contracts.sh
+++ b/plugin/commands/refactor/scripts/gate-contracts.sh
@@ -152,7 +152,9 @@ else
             FAIL=$((FAIL + 1))
             FAILURES="${FAILURES}\n  - [$CONTRACT_ID] $line"
         fi
-    done < <(grep 'verification_grep:' "$CONTRACTS_FILE" | sed 's/.*verification_grep: *"\{0,1\}//' | sed 's/"\{0,1\} *$//')
+    # Final sed unescapes YAML \" sequences inside double-quoted scalars —
+    # without it, rules containing quotes reach eval as literal \" and fail.
+    done < <(grep 'verification_grep:' "$CONTRACTS_FILE" | sed 's/.*verification_grep: *"\{0,1\}//' | sed 's/"\{0,1\} *$//' | sed 's/\\"/"/g')
 
     # Try extraction method B: verification.grep fields (nested YAML)
     if [ "$TOTAL" -eq 0 ]; then
diff --git a/plugin/commands/refactor/scripts/gate-postswap.sh b/plugin/commands/refactor/scripts/gate-postswap.sh
index ca6f4f8..dde9cb4 100755
--- a/plugin/commands/refactor/scripts/gate-postswap.sh
+++ b/plugin/commands/refactor/scripts/gate-postswap.sh
@@ -68,6 +68,21 @@ legacy_rel=$(yaml_value "$target_yaml" "file")
 legacy_file="$PROJECT_ROOT/$legacy_rel"
 legacy_class=$(basename "$legacy_rel"); legacy_class="${legacy_class%.*}"
 
+# Group C (dynamic) module names are often common words ("response", "utils")
+# that appear everywhere as plain English or platform identifiers
+# (http.ServerResponse). For those languages the meaningful signal is a
+# module-path reference (require/import of the legacy file), not the bare word.
+TARGET_LANG=$(yaml_value "$target_yaml" "language")
+module_ref_pattern() {  # regex matching require('./<mod>') / from '.../<mod>.js'
+    printf '%s' "(require\(|from[[:space:]]).*['\"][^'\"]*/${legacy_class}(\.[a-z]+)?['\"]"
+}
+is_dynamic_lang() {
+    case "$TARGET_LANG" in javascript|typescript|python|ruby) return 0 ;; *) return 1 ;; esac
+}
+module_ref_count() {  # project-wide count of legacy module-path references
+    grep -rnE "${GREP_EXCLUDES[@]}" -- "$(module_ref_pattern)" "$PROJECT_ROOT" 2>/dev/null | wc -l | tr -d ' '
+}
+
 pass=0; fail=0
 check() {  # check <label> <ok:0|1> <detail>
     if [[ "$2" -eq 0 ]]; then echo "  ✅ $1 — $3"; pass=$((pass+1))
@@ -82,20 +97,36 @@ case "$STEP" in
         [[ -n "$IMPL_FILE" ]] || { echo "error: --step 8 requires --impl-file" >&2; exit 1; }
         [[ -f "$IMPL_FILE" ]]; check "impl_file_exists" $? "$IMPL_FILE"
         if [[ -f "$IMPL_FILE" ]]; then
-            hits=$(grep -c -- "$legacy_class" "$IMPL_FILE" 2>/dev/null); hits=${hits:-0}
-            [[ "$hits" -eq 0 ]]; check "no_legacy_refs_in_impl" $? "grep '$legacy_class' → $hits hits (need 0)"
+            if is_dynamic_lang; then
+                hits=$(grep -cE -- "$(module_ref_pattern)" "$IMPL_FILE" 2>/dev/null || true); hits=${hits:-0}
+                [[ "$hits" -eq 0 ]]; check "no_legacy_module_import_in_impl" $? "require/import of '$legacy_class' → $hits hits (need 0)"
+            else
+                hits=$(grep -c -- "$legacy_class" "$IMPL_FILE" 2>/dev/null); hits=${hits:-0}
+                [[ "$hits" -eq 0 ]]; check "no_legacy_refs_in_impl" $? "grep '$legacy_class' → $hits hits (need 0)"
+            fi
         fi
         echo "  ℹ compile + unit tests are your gate too — this script only checks the grep signals"
         ;;
 
     12)
+        adapter_artifact=""
         if [[ -z "$ADAPTER_NAME" ]]; then
             adapter_artifact=$(ls "$state_dir"/6_adapter.* 2>/dev/null | grep -v '\.patch$' | head -1)
-            [[ -n "$adapter_artifact" ]] && ADAPTER_NAME=$(grep -oE '(@interface|class|struct)[[:space:]]+[A-Za-z0-9_]+' "$adapter_artifact" | head -1 | awk '{print $2}')
+            # Anchored to line start so prose like "No adapter class exists"
+            # in comments cannot be mistaken for a declaration.
+            [[ -n "$adapter_artifact" ]] && ADAPTER_NAME=$(grep -oE '^[[:space:]]*(@interface|class|struct)[[:space:]]+[A-Za-z0-9_]+' "$adapter_artifact" | head -1 | awk '{print $NF}')
+        fi
+        if [[ -z "$ADAPTER_NAME" ]] && is_dynamic_lang; then
+            # Group C: no adapter class by design — 6_adapter.* is test-side
+            # mock setup. Done signal: production code never references it.
+            base=$(basename "${adapter_artifact:-6_adapter}"); base="${base%.*}"
+            hits=$(ref_count "$base")
+            [[ "$hits" -eq 0 ]]; check "no_adapter_artifact_refs" $? "grep -r '$base' → $hits hits (need 0; Group C has no adapter class)"
+        else
+            [[ -n "$ADAPTER_NAME" ]] || { echo "error: cannot derive adapter name — pass --adapter-name" >&2; exit 2; }
+            hits=$(ref_count "$ADAPTER_NAME")
+            [[ "$hits" -eq 0 ]]; check "adapter_deleted" $? "grep -r '$ADAPTER_NAME' → $hits hits (need 0)"
         fi
-        [[ -n "$ADAPTER_NAME" ]] || { echo "error: cannot derive adapter name — pass --adapter-name" >&2; exit 2; }
-        hits=$(ref_count "$ADAPTER_NAME")
-        [[ "$hits" -eq 0 ]]; check "adapter_deleted" $? "grep -r '$ADAPTER_NAME' → $hits hits (need 0)"
 
         if [[ "$SKIP_SEAM" -eq 0 ]]; then
             [[ -z "$SEAM_NAME" && -f "$interface_yaml" ]] && SEAM_NAME=$(yaml_value "$interface_yaml" "name")
@@ -116,8 +147,13 @@ case "$STEP" in
 
     13)
         [[ ! -f "$legacy_file" ]]; check "legacy_file_deleted" $? "$legacy_rel"
-        hits=$(ref_count "$legacy_class")
-        [[ "$hits" -eq 0 ]]; check "no_legacy_class_refs" $? "grep -r '$legacy_class' → $hits hits (need 0)"
+        if is_dynamic_lang; then
+            hits=$(module_ref_count)
+            [[ "$hits" -eq 0 ]]; check "no_legacy_module_refs" $? "require/import of '$legacy_class' → $hits hits (need 0)"
+        else
+            hits=$(ref_count "$legacy_class")
+            [[ "$hits" -eq 0 ]]; check "no_legacy_class_refs" $? "grep -r '$legacy_class' → $hits hits (need 0)"
+        fi
         ;;
 
     *)
diff --git a/plugin/commands/refactor/scripts/gate-seams.sh b/plugin/commands/refactor/scripts/gate-seams.sh
index f9d978c..0f495d8 100755
--- a/plugin/commands/refactor/scripts/gate-seams.sh
+++ b/plugin/commands/refactor/scripts/gate-seams.sh
@@ -142,7 +142,8 @@ while IFS= read -r line; do
     elif echo "$line" | grep -q 'target_dependency:'; then
         CURRENT_DEP=$(echo "$line" | sed 's/.*target_dependency: *"\{0,1\}//' | sed 's/"\{0,1\} *$//')
     elif echo "$line" | grep -q 'verification_grep:'; then
-        CURRENT_GREP=$(echo "$line" | sed 's/.*verification_grep: *"\{0,1\}//' | sed 's/"\{0,1\} *$//')
+        # Trailing sed unescapes YAML \" sequences — same fix as gate-contracts.sh
+        CURRENT_GREP=$(echo "$line" | sed 's/.*verification_grep: *"\{0,1\}//' | sed 's/"\{0,1\} *$//' | sed 's/\\"/"/g')
     fi
 done < "$SEAMS_FILE"
 
diff --git a/plugin/commands/refactor/scripts/gate-step7.sh b/plugin/commands/refactor/scripts/gate-step7.sh
index 0d3c500..face5bf 100755
--- a/plugin/commands/refactor/scripts/gate-step7.sh
+++ b/plugin/commands/refactor/scripts/gate-step7.sh
@@ -146,7 +146,8 @@ if [[ -f "$CONTRACTS_FILE" ]]; then
             current_id=$(echo "$line" | sed -E 's/.*(id|contract_id): *"?([^"]*)"?[[:space:]]*$/\2/')
             current_grep=""
         elif echo "$line" | grep -qE '^[[:space:]]*verification_grep:'; then
-            current_grep=$(echo "$line" | sed -E 's/^[[:space:]]*verification_grep: *"?(.*[^"])"?[[:space:]]*$/\1/')
+            # Trailing sed unescapes YAML \" sequences — same fix as gate-contracts.sh
+            current_grep=$(echo "$line" | sed -E 's/^[[:space:]]*verification_grep: *"?(.*[^"])"?[[:space:]]*$/\1/' | sed 's/\\"/"/g')
         fi
     done < "$CONTRACTS_FILE"
     # final block
@@ -206,10 +207,15 @@ fi
 sed -i.bak "s|^\([[:space:]]*\)7_gate:.*|\\17_gate: { status: $overall, completed_at: \"$timestamp\" }|" "$STATE_FILE" 2>/dev/null || true
 rm -f "${STATE_FILE}.bak"
 
-# If pass, advance current_step to 8
+# If pass, advance current_step to 8 — but only when actually at Step 7.
+# SKILL.md Step 10 re-runs this gate as the post-swap verification; that
+# re-run must not regress current_step (10 → 8).
 if [[ "$overall" = "pass" ]]; then
-    sed -i.bak "s|^current_step:.*|current_step: 8|" "$STATE_FILE" 2>/dev/null || true
-    rm -f "${STATE_FILE}.bak"
+    current=$(awk '/^current_step:/ {print $2; exit}' "$STATE_FILE")
+    if [[ "${current:-7}" -le 7 ]]; then
+        sed -i.bak "s|^current_step:.*|current_step: 8|" "$STATE_FILE" 2>/dev/null || true
+        rm -f "${STATE_FILE}.bak"
+    fi
 fi
 
 # ── 7.6 Print summary ────────────────────────────────────────────────
diff --git a/plugin/commands/refactor/scripts/init-step2a.sh b/plugin/commands/refactor/scripts/init-step2a.sh
index 291996a..3da2c3a 100755
--- a/plugin/commands/refactor/scripts/init-step2a.sh
+++ b/plugin/commands/refactor/scripts/init-step2a.sh
@@ -76,6 +76,23 @@ raw_zones=$(bash "$DETECT" "$target_abs" --language "$language" 2>"$stderr_tmp")
 }
 rm -f "$stderr_tmp"
 
+# ── Zero-marker fallback (Group C common case) ──────────────────────────────
+# JS/Python files rarely carry MARK-style markers; detect-zones.sh then emits
+# "zones: []". Synthesize a single whole-file zone so the pipeline proceeds
+# (workflow.md Step 2a: small/markerless files are handled as a single zone).
+if ! echo "$raw_zones" | grep -qE '^  - id:'; then
+    total_lines=$(wc -l < "$target_abs" | tr -d ' ')
+    raw_zones=$(echo "$raw_zones" | grep -vE '^zones: \[\]|^# WARNING')
+    raw_zones="$raw_zones
+zones:
+  - id: \"whole-file\"
+    name: \"Whole file (no zone markers)\"
+    lines: [1, ${total_lines}]
+    line_count: ${total_lines}
+    method_count: 0
+    deps: []"
+fi
+
 # ── Pick first-slice zone via deterministic ranking ─────────────────────────
 # Strategy: smallest line_count first; tie-break by fewest deps.
 # (Phase 2 high-deps preference handled by pilot-run.sh's recommended_zone;
diff --git a/plugin/commands/refactor/scripts/pilot-run.sh b/plugin/commands/refactor/scripts/pilot-run.sh
index fdca91e..9583af6 100755
--- a/plugin/commands/refactor/scripts/pilot-run.sh
+++ b/plugin/commands/refactor/scripts/pilot-run.sh
@@ -140,9 +140,9 @@ case "$TARGET" in
         header="${TARGET%.*}.h"
         if [[ -f "$header" ]]; then
             echo "## Paired Header API Surface (\`$(basename "$header")\`)" >> "$OUTPUT"
-            local_methods=$(grep -cE '^[-+] *\(' "$header" 2>/dev/null || echo 0)
-            local_props=$(grep -cE '^@property' "$header" 2>/dev/null || echo 0)
-            local_nullnonnull=$(grep -cE 'NS_ASSUME_NONNULL_BEGIN|_Nullable|_Nonnull|nullable|nonnull|NS_SWIFT_NAME|NS_REFINED_FOR_SWIFT' "$header" 2>/dev/null || echo 0)
+            local_methods=$(grep -cE '^[-+] *\(' "$header" 2>/dev/null || true)
+            local_props=$(grep -cE '^@property' "$header" 2>/dev/null || true)
+            local_nullnonnull=$(grep -cE 'NS_ASSUME_NONNULL_BEGIN|_Nullable|_Nonnull|nullable|nonnull|NS_SWIFT_NAME|NS_REFINED_FOR_SWIFT' "$header" 2>/dev/null || true)
             echo '```yaml' >> "$OUTPUT"
             echo "header_path: \"$header\"" >> "$OUTPUT"
             echo "public_methods: $local_methods" >> "$OUTPUT"
diff --git a/plugin/commands/refactor/scripts/state.sh b/plugin/commands/refactor/scripts/state.sh
index 9852cf2..e510c35 100755
--- a/plugin/commands/refactor/scripts/state.sh
+++ b/plugin/commands/refactor/scripts/state.sh
@@ -9,7 +9,7 @@
 #   advance     --module <m> [--to <step>]      Advance current_step + mark step verified
 #   set-zone    --module <m> --zone <id>        Set zone_id (requires 2a_zones.yaml)
 #   confirm-mode --module <m>                   Set migration_mode.confirmed=true
-#   set-status  --module <m> --step <key> --status <produced|verified|skipped> [--skip-reason <txt>]
+#   set-status  --module <m> --step <key> --status <produced|verified|skipped> [--skip-reason <txt>] [--audit-mode <full|subagent>]
 #   show        --module <m>                    Print current state summary
 #
 # Exit codes:
@@ -45,6 +45,7 @@ ZONE_ID=""
 STEP_KEY=""
 STATUS=""
 SKIP_REASON=""
+AUDIT_MODE=""
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
@@ -54,6 +55,7 @@ while [[ $# -gt 0 ]]; do
         --step)        STEP_KEY="$2";    shift 2 ;;
         --status)      STATUS="$2";      shift 2 ;;
         --skip-reason) SKIP_REASON="$2"; shift 2 ;;
+        --audit-mode)  AUDIT_MODE="$2";  shift 2 ;;
         *) echo "error: unknown flag: $1" >&2; usage ;;
     esac
 done
@@ -317,6 +319,20 @@ EOF
             *) echo "error: --status must be one of produced|verified|skipped" >&2; exit 4 ;;
         esac
         set_step_status "$STEP_KEY" "$STATUS" "$SKIP_REASON"
+        if [[ -n "$AUDIT_MODE" ]]; then
+            case "$AUDIT_MODE" in
+                full|subagent) ;;
+                *) echo "error: --audit-mode must be full|subagent" >&2; exit 4 ;;
+            esac
+            tmp="$state_file.tmp"
+            awk -v step="$STEP_KEY" -v am="$AUDIT_MODE" '
+                $0 ~ "^[[:space:]]+" step ":[[:space:]]*\\{" {
+                    sub(/audit_mode:[[:space:]]*[^,}]+/, "audit_mode: " am)
+                }
+                { print }
+            ' "$state_file" > "$tmp" && mv "$tmp" "$state_file"
+            echo "$STEP_KEY.audit_mode = $AUDIT_MODE"
+        fi
         set_scalar updated "\"$iso_now\""
         echo "$STEP_KEY.status = $STATUS"
         ;;
diff --git a/plugin/commands/seam/scripts/detect-zones.sh b/plugin/commands/seam/scripts/detect-zones.sh
index db2c94f..4efc5c7 100755
--- a/plugin/commands/seam/scripts/detect-zones.sh
+++ b/plugin/commands/seam/scripts/detect-zones.sh
@@ -181,22 +181,22 @@ detect_markers_rust() {
 
 detect_methods_objc() {
     local start=$1 end=$2
-    sed -n "${start},${end}p" "$FILE_PATH" | grep -c '^[+-] *(' || echo 0
+    sed -n "${start},${end}p" "$FILE_PATH" | grep -c '^[+-] *(' || true
 }
 
 detect_methods_swift() {
     local start=$1 end=$2
-    sed -n "${start},${end}p" "$FILE_PATH" | grep -cE '^\s*(func |init\(|deinit)' || echo 0
+    sed -n "${start},${end}p" "$FILE_PATH" | grep -cE '^\s*(func |init\(|deinit)' || true
 }
 
 detect_methods_typescript() {
     local start=$1 end=$2
-    sed -n "${start},${end}p" "$FILE_PATH" | grep -cE '^\s*(async\s+)?(function |.*\(.*\)\s*[:{])' || echo 0
+    sed -n "${start},${end}p" "$FILE_PATH" | grep -cE '^\s*(async\s+)?(function |.*\(.*\)\s*[:{])' || true
 }
 
 detect_methods_generic() {
     local start=$1 end=$2
-    sed -n "${start},${end}p" "$FILE_PATH" | grep -cE '^\s*(pub\s+)?(fn |func |def |fun )' || echo 0
+    sed -n "${start},${end}p" "$FILE_PATH" | grep -cE '^\s*(pub\s+)?(fn |func |def |fun )' || true
 }
 
 count_methods() {
@@ -299,7 +299,7 @@ detect_markers() {
 
 MARKERS=$(detect_markers)
 
-MARKER_COUNT=$(echo "$MARKERS" | grep -c . || echo 0)
+MARKER_COUNT=$(echo "$MARKERS" | grep -c . || true)
 
 # --- Output YAML ---
 

From 2372f36f6e47c8001ef291e619238149e7cd81a6 Mon Sep 17 00:00:00 2001
From: Justin Lee <justinlee@91app.com>
Date: Wed, 8 Jul 2026 22:57:39 +0800
Subject: [PATCH 06/10] =?UTF-8?q?fix(refactor):=20frontmatter=20--step=20r?=
 =?UTF-8?q?ange=201-7=20=E2=86=92=201-13?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

argument-hint and description didn't reflect that Steps 8-13 are
tracked by state.sh and verified by gate-postswap.sh since fcedd31.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 plugin/commands/refactor/SKILL.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/plugin/commands/refactor/SKILL.md b/plugin/commands/refactor/SKILL.md
index cf57c87..a7ad983 100644
--- a/plugin/commands/refactor/SKILL.md
+++ b/plugin/commands/refactor/SKILL.md
@@ -1,9 +1,9 @@
 ---
 name: refactor
-description: Guided legacy code migration using the 13-step Playbook (Steps 1-7 tool-assisted)
+description: Guided legacy code migration using the 13-step Playbook (Steps 1-7 tool-assisted, 8-13 gate-verified)
 model: sonnet
 allowed-tools: Bash, Glob, Grep, Read, Write
-argument-hint: "<file-path> [--zone <zone-id>] [--step <1-7>] [--zones-only] [--status] [--force]"
+argument-hint: "<file-path> [--zone <zone-id>] [--step <1-13>] [--zones-only] [--status] [--force]"
 ---
 
 # SourceAtlas: Refactor (Playbook Navigator)

From 0617d6042fcd7c07f2a7f3d465dcc8180956ac12 Mon Sep 17 00:00:00 2001
From: Justin Lee <justinlee@91app.com>
Date: Wed, 8 Jul 2026 23:50:51 +0800
Subject: [PATCH 07/10] =?UTF-8?q?feat(refactor):=20Step=2012=20=E8=A8=98?=
 =?UTF-8?q?=E9=8C=84=E7=B5=90=E6=A7=8B=E6=8C=87=E6=A8=99=E4=BD=9C=E7=82=BA?=
 =?UTF-8?q?=E6=94=B9=E5=96=84=E8=AD=89=E6=93=9A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

「測試全綠」只證明無回歸,不證明更好。gate-postswap --step 12
新增 [--impl-file] 並寫出 12_metrics.yaml(LOC、決策點 grep 代理、
零引用數,before vs after);反向訊號印 ⚠️ REVIEW 但不影響 exit
code——指標是證據,方向判斷留給人。

文件同步:SKILL.md 加 verification boundary 註記 + 兩張表 Step 12
row、workflow.md §4.3 加「characterization tests 是護欄,寫得出
fail-on-old 是警訊」、steps-8-13-by-mode.md 加全 mode 共用註記。

self-test 16 case ALL PASS(既有 9 case 不變綠)。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 plugin/commands/refactor/SKILL.md             |  6 +-
 .../refactor/references/steps-8-13-by-mode.md |  2 +
 .../refactor/scripts/gate-postswap.sh         | 69 +++++++++++++++++--
 .../refactor/scripts/test-postswap.sh         | 33 ++++++++-
 plugin/commands/refactor/workflow.md          |  2 +
 5 files changed, 105 insertions(+), 7 deletions(-)

diff --git a/plugin/commands/refactor/SKILL.md b/plugin/commands/refactor/SKILL.md
index a7ad983..f3c44ab 100644
--- a/plugin/commands/refactor/SKILL.md
+++ b/plugin/commands/refactor/SKILL.md
@@ -175,6 +175,8 @@ Steps 8-13 are **user-driven**, but state-tracked: `state.sh advance` continues
 > **Mode variants**: The table below shows `seam-injection` (default). For `platform-migration`, `strangler-fig`, or `platform-strangler`, see **[references/steps-8-13-by-mode.md](references/steps-8-13-by-mode.md)**.
 > Check `state.yaml → migration_mode.mode_name` to determine which path to follow.
 
+> **Verification boundary**: green gates at Steps 10–11 prove **no regression** only — they do not prove the refactor made anything better. Improvement evidence comes from Step 12's structural metrics (`12_metrics.yaml`: LOC, decision points, reference counts, before vs after) and gate-postswap's zero-reference checks. When reporting Step 10 results, state this boundary explicitly.
+
 ### Mode: `seam-injection` — swap_strategy: `direct` (default)
 
 | Step | Start From | Do (concrete actions) | Done When (verifiable signal) |
@@ -183,7 +185,7 @@ Steps 8-13 are **user-driven**, but state-tracked: `state.sh advance` continues
 | 9 — Swap Implementation | New impl + `3_seams.yaml.recommended.enabling_point` | Replace `LegacyAdapter` with new impl at the ONE injection-site line; no other files touched in this commit | Single-file, single-line wiring change committed; characterization tests still pass |
 | 10 — Run Verification | Swapped code + `7_gate_results.yaml` (baseline) | Re-run `gate-step7.sh`; diff each section (Layer A / Layer B / contract CI) against the baseline | New gate output matches baseline 1:1 — same passes, same counts, no new failures |
 | 11 — Integration Testing | Verified swap from Step 10 | Run full app test suite; manual smoke every user-facing flow touching this module; check perf on hot paths | Full suite green; manual flows pass; no perf regression flagged |
-| 12 — Clean Up | Integrated swap from Step 11 | Delete `6_adapter.{ext}`; rename Seam Interface → final Target Interface name; delete temporary mocks/shims; update imports / re-exports | `gate-postswap.sh --step 12` passes (adapter + temporary seam name zero refs); full suite green |
+| 12 — Clean Up | Integrated swap from Step 11 | Delete `6_adapter.{ext}`; rename Seam Interface → final Target Interface name; delete temporary mocks/shims; update imports / re-exports; run gate-postswap.sh --step 12 --impl-file <new-file> to record structural metrics (LOC / decision points / references, before vs after) into 12_metrics.yaml | `gate-postswap.sh --step 12` passes (adapter + temporary seam name zero refs); full suite green; 12_metrics.yaml written and its delta presented to the user (⚠️ REVIEW flags need human judgment, they do not fail the gate) |
 | 13 — Delete Legacy | Cleaned codebase from Step 12 | Delete legacy file(s); final full-suite run; one dedicated commit | `gate-postswap.sh --step 13` passes (legacy file gone, zero class refs); full suite green; deletion is its own commit (not bundled with refactor work) |
 
 ### Mode: `seam-injection` — swap_strategy: `shadow`
@@ -198,7 +200,7 @@ Steps 8-13 are **user-driven**, but state-tracked: `state.sh advance` continues
 | 9c — Hard Swap | Threshold met + `3_seams.yaml.recommended.enabling_point` | Replace `ShadowAdapter` with new impl directly at the ONE injection site. Single-file, single-line commit. | Characterization tests pass; shadow logger no longer called; `grep -l "ShadowAdapter" <wiring-file>` = 0 hits |
 | 10 — Run Verification | Swapped code + `7_gate_results.yaml` (baseline) | Re-run `gate-step7.sh`; diff against baseline | Baseline matched 1:1 |
 | 11 — Integration Testing | Verified swap from Step 10 | Full suite + manual smoke | Full suite green; no perf regression |
-| 12 — Clean Up | Integrated swap from Step 11 | Delete `6_adapter.{ext}` (ShadowAdapter) + `6_logger_protocol.{ext}`; rename Seam Interface; delete logger implementation | `gate-postswap.sh --step 12` passes (also checks the shadow logger protocol); full suite green |
+| 12 — Clean Up | Integrated swap from Step 11 | Delete `6_adapter.{ext}` (ShadowAdapter) + `6_logger_protocol.{ext}`; rename Seam Interface; delete logger implementation; run gate-postswap.sh --step 12 --impl-file <new-file> to record structural metrics (LOC / decision points / references, before vs after) into 12_metrics.yaml | `gate-postswap.sh --step 12` passes (also checks the shadow logger protocol); full suite green; 12_metrics.yaml written and its delta presented to the user (⚠️ REVIEW flags need human judgment, they do not fail the gate) |
 | 13 — Delete Legacy | Cleaned codebase from Step 12 | Delete legacy file; own commit | `gate-postswap.sh --step 13` passes; full suite green |
 
 > See [references/playbook-overview.md](references/playbook-overview.md) for the complete 13-step overview with detailed checklists per step.
diff --git a/plugin/commands/refactor/references/steps-8-13-by-mode.md b/plugin/commands/refactor/references/steps-8-13-by-mode.md
index 78e9c79..1e57fcb 100644
--- a/plugin/commands/refactor/references/steps-8-13-by-mode.md
+++ b/plugin/commands/refactor/references/steps-8-13-by-mode.md
@@ -6,6 +6,8 @@ For other modes, refer to the appropriate section below.
 
 > **How to use**: Check `state.yaml → migration_mode.mode_name`. Then jump to that mode's section.
 
+> **All modes**: whatever the mode, the final cleanup step (Step 12 in `seam-injection` / `platform-migration` / `platform-strangler`; after all zones are done in `strangler-fig`) also runs `gate-postswap.sh --step 12 [--impl-file <new-file>]` to record structural metrics into `12_metrics.yaml`. Metrics are evidence, not a gate — see the verification boundary note in [SKILL.md](../SKILL.md).
+
 ---
 
 ## Mode: `seam-injection` (default)
diff --git a/plugin/commands/refactor/scripts/gate-postswap.sh b/plugin/commands/refactor/scripts/gate-postswap.sh
index dde9cb4..2212e30 100755
--- a/plugin/commands/refactor/scripts/gate-postswap.sh
+++ b/plugin/commands/refactor/scripts/gate-postswap.sh
@@ -7,7 +7,7 @@
 #
 # Usage:
 #   gate-postswap.sh --module <m> --step 8  --impl-file <path>
-#   gate-postswap.sh --module <m> --step 12 [--adapter-name <N>] [--seam-name <N>] [--skip-seam-check]
+#   gate-postswap.sh --module <m> --step 12 [--impl-file <path>] [--adapter-name <N>] [--seam-name <N>] [--skip-seam-check]
 #   gate-postswap.sh --module <m> --step 13
 #
 # Name resolution (when flags omitted):
@@ -57,6 +57,12 @@ ref_count() {  # ref_count <name> → number of referencing lines in the project
     grep -rn "${GREP_EXCLUDES[@]}" -- "$1" "$PROJECT_ROOT" 2>/dev/null | wc -l | tr -d ' '
 }
 
+# Grep line-count PROXY for cyclomatic complexity — counts matching lines,
+# not branches, so it's evidence for review, never a gate.
+decision_points() {  # decision_points <file> → lines with branch keywords
+    grep -cE '\b(if|for|while|case|catch|guard|elif|when)\b' "$1" 2>/dev/null || true
+}
+
 yaml_value() {  # yaml_value <file> <key> → first "key: value", quotes stripped
     awk -v key="$2" '$0 ~ "^[[:space:]]*" key ":" {
         sub("^[[:space:]]*" key ":[[:space:]]*", ""); gsub(/["'"'"']/, ""); print; exit
@@ -109,6 +115,7 @@ case "$STEP" in
         ;;
 
     12)
+        adapter_refs=0 seam_refs=0
         adapter_artifact=""
         if [[ -z "$ADAPTER_NAME" ]]; then
             adapter_artifact=$(ls "$state_dir"/6_adapter.* 2>/dev/null | grep -v '\.patch$' | head -1)
@@ -120,18 +127,18 @@ case "$STEP" in
             # Group C: no adapter class by design — 6_adapter.* is test-side
             # mock setup. Done signal: production code never references it.
             base=$(basename "${adapter_artifact:-6_adapter}"); base="${base%.*}"
-            hits=$(ref_count "$base")
+            hits=$(ref_count "$base"); adapter_refs=$hits
             [[ "$hits" -eq 0 ]]; check "no_adapter_artifact_refs" $? "grep -r '$base' → $hits hits (need 0; Group C has no adapter class)"
         else
             [[ -n "$ADAPTER_NAME" ]] || { echo "error: cannot derive adapter name — pass --adapter-name" >&2; exit 2; }
-            hits=$(ref_count "$ADAPTER_NAME")
+            hits=$(ref_count "$ADAPTER_NAME"); adapter_refs=$hits
             [[ "$hits" -eq 0 ]]; check "adapter_deleted" $? "grep -r '$ADAPTER_NAME' → $hits hits (need 0)"
         fi
 
         if [[ "$SKIP_SEAM" -eq 0 ]]; then
             [[ -z "$SEAM_NAME" && -f "$interface_yaml" ]] && SEAM_NAME=$(yaml_value "$interface_yaml" "name")
             if [[ -n "$SEAM_NAME" ]]; then
-                hits=$(ref_count "$SEAM_NAME")
+                hits=$(ref_count "$SEAM_NAME"); seam_refs=$hits
                 [[ "$hits" -eq 0 ]]; check "seam_interface_renamed" $? "grep -r '$SEAM_NAME' → $hits hits (need 0; --skip-seam-check if final name kept)"
             fi
         fi
@@ -143,6 +150,60 @@ case "$STEP" in
                 [[ "$hits" -eq 0 ]]; check "shadow_logger_deleted" $? "grep -r '$logger' → $hits hits (need 0)"
             fi
         fi
+
+        # ── Structural metrics — informational evidence, NEVER a gate ────────
+        # All tests green only proves no regression, not improvement; these
+        # numbers are the improvement evidence. Recorded even when the checks
+        # above failed; flags never touch pass/fail or the exit code.
+        metrics_yaml="$state_dir/12_metrics.yaml"
+        legacy_loc=$(wc -l < "$legacy_file" 2>/dev/null | tr -d ' '); legacy_loc=${legacy_loc:-0}
+        legacy_dp=$(decision_points "$legacy_file"); legacy_dp=${legacy_dp:-0}
+        flags=""
+        {
+            echo "# 12_metrics.yaml — structural metrics evidence (informational, not a gate)"
+            echo "module: \"$MODULE\""
+            echo "legacy:"
+            echo "  file: \"$legacy_rel\""
+            echo "  loc: $legacy_loc"
+            echo "  decision_points: $legacy_dp"
+            echo "impl:"
+        } > "$metrics_yaml"
+        if [[ -n "$IMPL_FILE" && -f "$IMPL_FILE" ]]; then
+            impl_loc=$(wc -l < "$IMPL_FILE" | tr -d ' '); impl_loc=${impl_loc:-0}
+            impl_dp=$(decision_points "$IMPL_FILE"); impl_dp=${impl_dp:-0}
+            loc_pct=$(( legacy_loc > 0 ? impl_loc * 100 / legacy_loc : 0 ))
+            [[ "$loc_pct" -gt 150 ]] && flags="loc_ratio_gt_150"
+            [[ "$impl_dp" -gt "$legacy_dp" ]] && flags="${flags:+$flags, }decision_points_increased"
+            impl_rel="${IMPL_FILE#"$PROJECT_ROOT"/}"  # project-relative, like legacy_rel
+            {
+                echo "  file: \"$impl_rel\""
+                echo "  loc: $impl_loc"
+                echo "  decision_points: $impl_dp"
+                echo "delta:"
+                echo "  loc_pct: $loc_pct"
+                echo "  decision_points: $(( impl_dp - legacy_dp ))"
+            } >> "$metrics_yaml"
+        else
+            echo "  file: not_provided" >> "$metrics_yaml"
+        fi
+        {
+            echo "references:"
+            echo "  adapter_refs: $adapter_refs"
+            echo "  seam_refs: $seam_refs"
+            echo "flags: [$flags]"
+            echo "notes: \"decision_points is a grep line-count proxy for cyclomatic complexity\""
+        } >> "$metrics_yaml"
+
+        echo "  metrics (informational, not a gate) → $metrics_yaml"
+        printf '    %-8s %6s %16s\n' "" "loc" "decision_points"
+        printf '    %-8s %6s %16s\n' "legacy" "$legacy_loc" "$legacy_dp"
+        if [[ -n "$IMPL_FILE" && -f "$IMPL_FILE" ]]; then
+            printf '    %-8s %6s %16s\n' "impl" "$impl_loc" "$impl_dp"
+            [[ "$loc_pct" -gt 150 ]] && echo "  ⚠️ REVIEW — impl LOC is ${loc_pct}% of legacy (>150%); sometimes justified (interface boilerplate), needs human judgment"
+            [[ "$impl_dp" -gt "$legacy_dp" ]] && echo "  ⚠️ REVIEW — impl decision_points $impl_dp > legacy $legacy_dp; proxy metric, needs human judgment"
+        else
+            echo "  ℹ metrics recorded legacy-side only — pass --impl-file to compare against the new impl"
+        fi
         ;;
 
     13)
diff --git a/plugin/commands/refactor/scripts/test-postswap.sh b/plugin/commands/refactor/scripts/test-postswap.sh
index bf549cf..a8cdb69 100755
--- a/plugin/commands/refactor/scripts/test-postswap.sh
+++ b/plugin/commands/refactor/scripts/test-postswap.sh
@@ -16,6 +16,10 @@ expect() { # expect <label> <want_exit> <got_exit>
     if [[ "$2" -eq "$3" ]]; then echo "ok  $1"
     else echo "FAIL $1 (want exit $2, got $3)"; fail=1; fi
 }
+has() { # has <label> <file> <pattern>
+    if grep -q -- "$3" "$2" 2>/dev/null; then echo "ok  $1"
+    else echo "FAIL $1 (no '$3' in $2)"; fail=1; fi
+}
 
 # ── Fixture ─────────────────────────────────────────────────────────────────
 mkdir -p "$T/.sourceatlas/refactor/legacy" "$T/src"
@@ -39,7 +43,20 @@ EOF
 printf 'module: "legacy"\nfile: "src/Legacy.m"\n' > "$T/.sourceatlas/refactor/legacy/1_target.yaml"
 printf 'protocol:\n  name: "LegacySeam"\nswap_strategy: "direct"\n' > "$T/.sourceatlas/refactor/legacy/5_interface.yaml"
 printf 'class LegacyAdapter: LegacySeam {}\n' > "$T/.sourceatlas/refactor/legacy/6_adapter.swift"
-printf '@implementation Legacy\n@end\n' > "$T/src/Legacy.m"
+# 11 lines / 2 `if` lines, so step-12 metric ratios are meaningful
+cat > "$T/src/Legacy.m" <<'EOF'
+@implementation Legacy
+- (int)value:(int)x {
+    if (x > 0) {
+        return x;
+    }
+    if (x < -10) {
+        return -10;
+    }
+    return 0;
+}
+@end
+EOF
 
 # ── State machine: advance 7 → 13, then terminal refusal ────────────────────
 S advance --module legacy >/dev/null; expect "advance 7→8" 0 $?
@@ -63,6 +80,20 @@ G --module legacy --step 12 >/dev/null; expect "step12 wired adapter fails" 3 $?
 printf 'let x = NewImpl()\n' > "$T/src/Wiring.swift"
 G --module legacy --step 12 >/dev/null; expect "step12 clean passes" 0 $?
 
+# ── Gate step 12 metrics (informational — must never change exit codes) ──────
+M="$T/.sourceatlas/refactor/legacy/12_metrics.yaml"
+printf 'final class NewImpl {\n    func value(_ x: Int) -> Int {\n        if x > 0 { return x }\n        return 0\n    }\n}\n' > "$T/src/NewImpl.swift"
+G --module legacy --step 12 --impl-file "$T/src/NewImpl.swift" >/dev/null; expect "step12 metrics small impl passes" 0 $?
+has "step12 metrics writes loc_pct" "$M" "loc_pct"
+has "step12 metrics impl path is project-relative" "$M" 'file: "src/NewImpl.swift"'
+# bloated impl: >150% of Legacy.m LOC and more `if` lines → flags fire, exit still 0
+for i in $(seq 1 30); do echo "        if flag$i { total += $i }"; done > "$T/src/Bloat.swift"
+G --module legacy --step 12 --impl-file "$T/src/Bloat.swift" >/dev/null; expect "step12 bloated impl still passes" 0 $?
+has "step12 metrics flags loc_ratio_gt_150" "$M" "loc_ratio_gt_150"
+G --module legacy --step 12 >/dev/null; expect "step12 no impl-file passes" 0 $?
+has "step12 metrics records not_provided" "$M" "not_provided"
+printf 'final class NewImpl {}\n' > "$T/src/NewImpl.swift"
+
 # ── Gate step 13 ─────────────────────────────────────────────────────────────
 G --module legacy --step 13 >/dev/null; expect "step13 legacy present fails" 3 $?
 rm "$T/src/Legacy.m"
diff --git a/plugin/commands/refactor/workflow.md b/plugin/commands/refactor/workflow.md
index fede544..02d1829 100644
--- a/plugin/commands/refactor/workflow.md
+++ b/plugin/commands/refactor/workflow.md
@@ -843,6 +843,8 @@ For each contract in 2_contracts.yaml:
 
 Mark these as **skipped/pending** — they cannot run until Step 5+6 provide the mock infrastructure.
 
+> **Characterization tests are guardrails, not improvement evidence.** This playbook performs pure refactoring: the tests' only job is to pin existing behavior. If you find yourself able to write a test that FAILS on the legacy code and would pass only on the new implementation — stop. You have changed behavior; that is a warning, not an achievement. Go back and check Step 3 (seam) or Step 5 (interface) for accidental semantic changes. Conversely, all-green at Step 10 only proves "nothing broke" — evidence of improvement lives in Step 12's structural metrics (`12_metrics.yaml`).
+
 ### 4.4 Gate: Run Spike Tests
 
 ```bash

From ecbd900745ac397cb3a164de2f0359f90cc0580b Mon Sep 17 00:00:00 2001
From: Justin Lee <justinlee@91app.com>
Date: Thu, 9 Jul 2026 00:03:48 +0800
Subject: [PATCH 08/10] =?UTF-8?q?feat(refactor):=20Step=201=20=E5=AE=A3?=
 =?UTF-8?q?=E5=91=8A=20success=5Fcriteria,Step=2012=20=E6=A9=9F=E5=99=A8?=
 =?UTF-8?q?=E5=9B=9E=E7=85=A7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

「先寫紅」的指標版:動手前在 1_target.yaml 宣告這次重構的
「更好」定義(goal + 可機器驗的 checks),Step 12 gate-postswap
逐條跑 verify 並將 ✓/✗ 寫進 12_metrics.yaml → goal_checks。
未達成的宣告判準大聲印出但不改 exit code——達成與否是人的判決。

- init-state.sh scaffold success_criteria(空 = 靜默,向後相容)
- gate-postswap.sh 回照段沿用 gate-contracts.sh 的 \" unescape 先例
- templates/1_target.yaml 註明這是唯一允許事後手填的區塊
- workflow.md §1.5 說明宣告時機與 verify 規則慣例
- SKILL.md verification boundary 補 goal_checks

self-test 20 assertions ALL PASS(既有 16 個不變綠)。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 plugin/commands/refactor/SKILL.md             |  4 +-
 .../refactor/scripts/gate-postswap.sh         | 52 +++++++++++++++++++
 .../commands/refactor/scripts/init-state.sh   | 11 ++++
 .../refactor/scripts/test-postswap.sh         | 16 ++++++
 .../commands/refactor/templates/1_target.yaml | 13 ++++-
 plugin/commands/refactor/workflow.md          | 19 +++++++
 6 files changed, 112 insertions(+), 3 deletions(-)

diff --git a/plugin/commands/refactor/SKILL.md b/plugin/commands/refactor/SKILL.md
index f3c44ab..64dcb10 100644
--- a/plugin/commands/refactor/SKILL.md
+++ b/plugin/commands/refactor/SKILL.md
@@ -33,7 +33,7 @@ argument-hint: "<file-path> [--zone <zone-id>] [--step <1-13>] [--zones-only] [-
 ## Quick Start
 
 0. **No arguments?** → Discovery Mode: auto-find hotspots, show in-progress refactors, suggest candidates
-1. **Select target** → history hotspot + impact analysis → `1_target.yaml`
+1. **Select target** → history hotspot + impact analysis → `1_target.yaml` (+ optional `success_criteria` declaration)
 2. **Inventory contracts** → seam zones + audit → `2_contracts.yaml`
 3. **Find seams** → dependency graph + seam recommendations → `3_seams.yaml`
 4. **Record behavior** → spike tests + characterization test skeletons → `4_tests.{ext}`
@@ -175,7 +175,7 @@ Steps 8-13 are **user-driven**, but state-tracked: `state.sh advance` continues
 > **Mode variants**: The table below shows `seam-injection` (default). For `platform-migration`, `strangler-fig`, or `platform-strangler`, see **[references/steps-8-13-by-mode.md](references/steps-8-13-by-mode.md)**.
 > Check `state.yaml → migration_mode.mode_name` to determine which path to follow.
 
-> **Verification boundary**: green gates at Steps 10–11 prove **no regression** only — they do not prove the refactor made anything better. Improvement evidence comes from Step 12's structural metrics (`12_metrics.yaml`: LOC, decision points, reference counts, before vs after) and gate-postswap's zero-reference checks. When reporting Step 10 results, state this boundary explicitly.
+> **Verification boundary**: green gates at Steps 10–11 prove **no regression** only — they do not prove the refactor made anything better. Improvement evidence comes from Step 12's structural metrics (`12_metrics.yaml`: LOC, decision points, reference counts, before vs after) and gate-postswap's zero-reference checks. When reporting Step 10 results, state this boundary explicitly. If `success_criteria` were declared in `1_target.yaml` at Step 1, Step 12 echoes them back with per-check results (`12_metrics.yaml → goal_checks`) — an unmet declared criterion is loud evidence for review, not a gate failure.
 
 ### Mode: `seam-injection` — swap_strategy: `direct` (default)
 
diff --git a/plugin/commands/refactor/scripts/gate-postswap.sh b/plugin/commands/refactor/scripts/gate-postswap.sh
index 2212e30..5af91b3 100755
--- a/plugin/commands/refactor/scripts/gate-postswap.sh
+++ b/plugin/commands/refactor/scripts/gate-postswap.sh
@@ -4,6 +4,8 @@
 # Turns the grep-checkable signals from SKILL.md's Steps 8-13 tables into exit
 # codes, so "cleanup complete" is a gate, not a claim. Steps 9-11 are verified
 # by test suites (re-run gate-step7.sh / your full suite) — not this script.
+# Step 12 also records structural metrics and echoes the success_criteria
+# declared in 1_target.yaml into 12_metrics.yaml — evidence, never a gate.
 #
 # Usage:
 #   gate-postswap.sh --module <m> --step 8  --impl-file <path>
@@ -204,6 +206,56 @@ case "$STEP" in
         else
             echo "  ℹ metrics recorded legacy-side only — pass --impl-file to compare against the new impl"
         fi
+
+        # ── Goal checks — declared success_criteria echoed back, NEVER a gate ─
+        # Step 1 declared "better" in 1_target.yaml → success_criteria; run each
+        # verify and record met/unmet. Unmet criteria print loudly but never
+        # touch pass/fail or the exit code. Absent/empty block → fully silent.
+        if grep -q '^success_criteria:' "$target_yaml" 2>/dev/null; then
+            sc_goal=$(awk '/^success_criteria:/{f=1;next} f&&/^[^[:space:]]/{f=0}
+                f&&/^[[:space:]]*goal:/{sub(/^[[:space:]]*goal:[[:space:]]*/,"")
+                    sub(/[[:space:]]*$/,""); sub(/^"/,""); sub(/"$/,""); print; exit}' "$target_yaml")
+            sc_goal="${sc_goal//\\\"/\"}"  # unescape YAML \" before use (same care as gate-contracts.sh)
+            # pair each checks[] desc with its verify → tab-separated lines
+            sc_checks=$(awk '/^success_criteria:/{f=1;next} f&&/^[^[:space:]]/{f=0}
+                f&&/^[[:space:]]*-[[:space:]]*desc:/{d=$0
+                    sub(/^[[:space:]]*-[[:space:]]*desc:[[:space:]]*/,"",d)
+                    sub(/[[:space:]]*$/,"",d); sub(/^"/,"",d); sub(/"$/,"",d); desc=d; next}
+                f&&/^[[:space:]]*verify:/{v=$0
+                    sub(/^[[:space:]]*verify:[[:space:]]*/,"",v)
+                    sub(/[[:space:]]*$/,"",v); sub(/^"/,"",v); sub(/"$/,"",v)
+                    print desc "\t" v; desc=""}' "$target_yaml")
+            if [[ -n "$sc_goal" || -n "$sc_checks" ]]; then
+                goal_q="${sc_goal//\\/\\\\}"; goal_q="${goal_q//\"/\\\"}"
+                {
+                    echo "goal_checks:"
+                    echo "  goal: \"$goal_q\""
+                } >> "$metrics_yaml"
+                [[ -n "$sc_goal" ]] && echo "  goal: $sc_goal"
+                if [[ -n "$sc_checks" ]]; then
+                    echo "  checks:" >> "$metrics_yaml"
+                    while IFS=$'\t' read -r c_desc c_verify; do
+                        [[ -n "$c_verify" ]] || continue
+                        c_desc="${c_desc//\\\"/\"}"; c_verify="${c_verify//\\\"/\"}"
+                        if (cd "$PROJECT_ROOT" && bash -c "$c_verify") >/dev/null 2>&1; then met=true; else met=false; fi
+                        desc_q="${c_desc//\\/\\\\}"; desc_q="${desc_q//\"/\\\"}"
+                        {
+                            echo "    - desc: \"$desc_q\""
+                            echo "      met: $met"
+                        } >> "$metrics_yaml"
+                        if [[ "$met" == true ]]; then echo "    ✓ $c_desc"
+                        else echo "    ✗ $c_desc — declared criterion NOT met (evidence for review, does not fail this gate)"; fi
+                    done <<< "$sc_checks"
+                    echo "  unverified: false" >> "$metrics_yaml"
+                else
+                    {
+                        echo "  checks: []"
+                        echo "  unverified: true"
+                    } >> "$metrics_yaml"
+                    echo "  ℹ goal declared without machine checks — confirm attainment manually"
+                fi
+            fi
+        fi
         ;;
 
     13)
diff --git a/plugin/commands/refactor/scripts/init-state.sh b/plugin/commands/refactor/scripts/init-state.sh
index f6ba242..e0247f5 100755
--- a/plugin/commands/refactor/scripts/init-state.sh
+++ b/plugin/commands/refactor/scripts/init-state.sh
@@ -281,6 +281,14 @@ showstoppers:
   storyboard_dispatch: $storyboard_dispatch
   category_count: $category_count
   cross_language_exposed: $cross_language_exposed
+
+# Declared BEFORE work begins; Step 12 echoes these back with results.
+# goal: free-text definition of "better" for THIS refactor (empty = universal metrics only).
+# checks: machine-verifiable rules, each { desc, verify }. verify is a shell command,
+# exit 0 = met. Prefer quote-free grep -qE patterns (see SKILL.md Gotchas).
+success_criteria:
+  goal: ""
+  checks: []
 EOF
 
 # ── Summary to stdout ───────────────────────────────────────────────────────
@@ -321,3 +329,6 @@ echo
 echo "  artifacts: $state_file"
 echo "             $target_file"
 echo "             $pilot_report"
+echo
+echo "  optional: declare this refactor's success criteria (goal + checks) in"
+echo "            1_target.yaml → success_criteria — Step 12 will echo them back"
diff --git a/plugin/commands/refactor/scripts/test-postswap.sh b/plugin/commands/refactor/scripts/test-postswap.sh
index a8cdb69..0433775 100755
--- a/plugin/commands/refactor/scripts/test-postswap.sh
+++ b/plugin/commands/refactor/scripts/test-postswap.sh
@@ -94,6 +94,22 @@ G --module legacy --step 12 >/dev/null; expect "step12 no impl-file passes" 0 $?
 has "step12 metrics records not_provided" "$M" "not_provided"
 printf 'final class NewImpl {}\n' > "$T/src/NewImpl.swift"
 
+# ── Gate step 12 goal checks (declared criteria echo — never a gate) ─────────
+# Earlier step-12 runs covered the absent-block silent path; now declare one.
+cat >> "$T/.sourceatlas/refactor/legacy/1_target.yaml" <<'EOF'
+success_criteria:
+  goal: "wiring references NewImpl only"
+  checks:
+    - desc: "NewImpl wired"
+      verify: "grep -q NewImpl src/Wiring.swift"
+    - desc: "phantom symbol present"
+      verify: "grep -q NoSuchThing src/Wiring.swift"
+EOF
+G --module legacy --step 12 --impl-file "$T/src/NewImpl.swift" >/dev/null; expect "step12 unmet goal check still passes" 0 $?
+has "step12 metrics writes goal_checks" "$M" "goal_checks:"
+has "step12 goal check met recorded" "$M" "met: true"
+has "step12 goal check unmet recorded" "$M" "met: false"
+
 # ── Gate step 13 ─────────────────────────────────────────────────────────────
 G --module legacy --step 13 >/dev/null; expect "step13 legacy present fails" 3 $?
 rm "$T/src/Legacy.m"
diff --git a/plugin/commands/refactor/templates/1_target.yaml b/plugin/commands/refactor/templates/1_target.yaml
index fd9fe79..c48629c 100644
--- a/plugin/commands/refactor/templates/1_target.yaml
+++ b/plugin/commands/refactor/templates/1_target.yaml
@@ -1,5 +1,6 @@
 # 1_target.yaml — Step 1 Target Selection artifact template
-# Written by scripts/init-state.sh; do not edit by hand unless re-running Step 1.
+# Written by scripts/init-state.sh; do not edit by hand unless re-running Step 1 —
+# except `success_criteria`, the one block the user/LLM fills in after Step 1.
 
 module: "{module_name}"
 file: "{file_path}"
@@ -46,3 +47,13 @@ showstoppers:
   storyboard_dispatch: 0      # NSStringFromClass / IB dispatch
   category_count: 0           # categories on the target class
   cross_language_exposed: false   # appears in Bridging-Header or -Swift.h
+
+# ── Success criteria (fill in by hand AFTER Step 1) ─────────────────────────
+# Declared BEFORE work begins; Step 12 echoes these back with results.
+# goal: free-text definition of "better" for THIS refactor (empty = universal metrics only).
+# checks: machine-verifiable rules, each { desc, verify }. verify is a shell command,
+# exit 0 = met. Prefer quote-free grep -qE patterns (see SKILL.md Gotchas).
+
+success_criteria:
+  goal: ""
+  checks: []
diff --git a/plugin/commands/refactor/workflow.md b/plugin/commands/refactor/workflow.md
index 02d1829..6e45072 100644
--- a/plugin/commands/refactor/workflow.md
+++ b/plugin/commands/refactor/workflow.md
@@ -338,6 +338,25 @@ Verifiable signals:
 
 If `state.yaml` exists and `--force` is not passed, init-state.sh exits 3. Resume from `current_step` in state.yaml; do not re-run init-state.sh. This prevents re-ranking mid-refactor.
 
+### 1.5 Declare Success Criteria (optional but recommended)
+
+init-state.sh scaffolds an empty `success_criteria` block at the end of `1_target.yaml`:
+
+```yaml
+success_criteria:
+  goal: ""      # free-text: what "better" means for THIS refactor
+  checks: []    # machine-verifiable rules: { desc, verify } — verify is a shell command, exit 0 = met
+```
+
+After Step 1 completes, ask the user what this refactor is trying to achieve, and fill the block in. This is the **one** block in `1_target.yaml` the LLM may edit after init-state.sh runs — everything else is script-owned.
+
+Why before, not after: declaring the criteria up front is the metrics analogue of "write the red test first" — it forces "better" to be defined before any code moves, so Step 12 can confront you with the result instead of letting all-green pass as improvement. Step 12 (`gate-postswap.sh --step 12`) echoes the goal back, runs each check, and records results in `12_metrics.yaml → goal_checks`. An unmet declared check prints loudly but does not fail the gate — attainment is the user's verdict to make.
+
+Rules for `checks[].verify`:
+- Shell command run from the project root; exit 0 = criterion met
+- Prefer quote-free `grep -qE` patterns with `.` wildcards (see Gotchas in SKILL.md — embedded quotes have bitten every gate script)
+- Empty `goal` + empty `checks` = skip; Step 12 stays silent about goals
+
 ---
 
 ## Step 0.5: Pre-Refactor Cleanup (optional)

From a6a9f25b28ff1d5041cc136333f73317a5127631 Mon Sep 17 00:00:00 2001
From: Justin Lee <justinlee@91app.com>
Date: Thu, 9 Jul 2026 18:53:05 +0800
Subject: [PATCH 09/10] feat(refactor): worked examples + retrospective prompt
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

§1.5 加三個 success_criteria template（拆職責/可測試性/去耦合）
和紅燈指引（宣告後立刻跑,應該 fail）。Step 12 尾端印 retrospective
prompt 並寫 pending 進 12_metrics.yaml,由 LLM 向使用者確認後更新
為 yes/no/deferred。

self-test 21 assertions ALL PASS（+1 retrospective 斷言）。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 plugin/commands/refactor/SKILL.md               |  2 +-
 .../commands/refactor/scripts/gate-postswap.sh  |  4 ++++
 .../commands/refactor/scripts/test-postswap.sh  |  1 +
 plugin/commands/refactor/workflow.md            | 17 +++++++++++++++++
 4 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/plugin/commands/refactor/SKILL.md b/plugin/commands/refactor/SKILL.md
index 64dcb10..5b22033 100644
--- a/plugin/commands/refactor/SKILL.md
+++ b/plugin/commands/refactor/SKILL.md
@@ -175,7 +175,7 @@ Steps 8-13 are **user-driven**, but state-tracked: `state.sh advance` continues
 > **Mode variants**: The table below shows `seam-injection` (default). For `platform-migration`, `strangler-fig`, or `platform-strangler`, see **[references/steps-8-13-by-mode.md](references/steps-8-13-by-mode.md)**.
 > Check `state.yaml → migration_mode.mode_name` to determine which path to follow.
 
-> **Verification boundary**: green gates at Steps 10–11 prove **no regression** only — they do not prove the refactor made anything better. Improvement evidence comes from Step 12's structural metrics (`12_metrics.yaml`: LOC, decision points, reference counts, before vs after) and gate-postswap's zero-reference checks. When reporting Step 10 results, state this boundary explicitly. If `success_criteria` were declared in `1_target.yaml` at Step 1, Step 12 echoes them back with per-check results (`12_metrics.yaml → goal_checks`) — an unmet declared criterion is loud evidence for review, not a gate failure.
+> **Verification boundary**: green gates at Steps 10–11 prove **no regression** only — they do not prove the refactor made anything better. Improvement evidence comes from Step 12's structural metrics (`12_metrics.yaml`: LOC, decision points, reference counts, before vs after) and gate-postswap's zero-reference checks. When reporting Step 10 results, state this boundary explicitly. If `success_criteria` were declared in `1_target.yaml` at Step 1, Step 12 echoes them back with per-check results (`12_metrics.yaml → goal_checks`) — an unmet declared criterion is loud evidence for review, not a gate failure. Step 12 also prints a retrospective prompt (`retrospective: pending` in `12_metrics.yaml`) — the LLM should ask the user whether the refactoring achieved its goal and update the field to `yes`, `no`, or `deferred`.
 
 ### Mode: `seam-injection` — swap_strategy: `direct` (default)
 
diff --git a/plugin/commands/refactor/scripts/gate-postswap.sh b/plugin/commands/refactor/scripts/gate-postswap.sh
index 5af91b3..ef81d18 100755
--- a/plugin/commands/refactor/scripts/gate-postswap.sh
+++ b/plugin/commands/refactor/scripts/gate-postswap.sh
@@ -256,6 +256,10 @@ case "$STEP" in
                 fi
             fi
         fi
+
+        # ── Retrospective prompt — the human verdict ──────────────────────
+        echo "retrospective: pending" >> "$metrics_yaml"
+        echo "  🤔 這次重構達成你的目的了嗎？(由執行者向使用者確認，記入 retrospective: yes|no|deferred)"
         ;;
 
     13)
diff --git a/plugin/commands/refactor/scripts/test-postswap.sh b/plugin/commands/refactor/scripts/test-postswap.sh
index 0433775..51d79f2 100755
--- a/plugin/commands/refactor/scripts/test-postswap.sh
+++ b/plugin/commands/refactor/scripts/test-postswap.sh
@@ -109,6 +109,7 @@ G --module legacy --step 12 --impl-file "$T/src/NewImpl.swift" >/dev/null; expec
 has "step12 metrics writes goal_checks" "$M" "goal_checks:"
 has "step12 goal check met recorded" "$M" "met: true"
 has "step12 goal check unmet recorded" "$M" "met: false"
+has "step12 retrospective prompt recorded" "$M" "retrospective:"
 
 # ── Gate step 13 ─────────────────────────────────────────────────────────────
 G --module legacy --step 13 >/dev/null; expect "step13 legacy present fails" 3 $?
diff --git a/plugin/commands/refactor/workflow.md b/plugin/commands/refactor/workflow.md
index 6e45072..ea030a0 100644
--- a/plugin/commands/refactor/workflow.md
+++ b/plugin/commands/refactor/workflow.md
@@ -356,6 +356,23 @@ Rules for `checks[].verify`:
 - Shell command run from the project root; exit 0 = criterion met
 - Prefer quote-free `grep -qE` patterns with `.` wildcards (see Gotchas in SKILL.md — embedded quotes have bitten every gate script)
 - Empty `goal` + empty `checks` = skip; Step 12 stays silent about goals
+- After declaring checks, **run them from the project root now** — they should fail. If any already passes, it cannot distinguish before from after; revise that check
+
+Example templates (copy, edit, delete — not a taxonomy):
+
+```yaml
+# Split responsibilities: legacy fan-in drops to ≤1 file
+- desc: "legacy fan-in reduced"
+  verify: "test $(grep -rlE 'import.*LegacyModule|require.*LegacyModule' src/ | wc -l) -le 1"
+
+# Testability: characterization tests use mocks, not real deps
+- desc: "tests use injected deps"
+  verify: "grep -qE 'mock|stub|fake|spy' 4_tests.*"
+
+# Decouple: co-change coupling gone (requires /atlas.history data post-refactor)
+- desc: "no co-change coupling with OldDep"
+  verify: "! grep -q 'co_change.*OldDep' .sourceatlas/history/*.yaml"
+```
 
 ---
 

From 492f32837e3f0476e025a899fde14500617ba70a Mon Sep 17 00:00:00 2001
From: Justin Lee <justinlee@91app.com>
Date: Thu, 9 Jul 2026 18:59:45 +0800
Subject: [PATCH 10/10] =?UTF-8?q?test(refactor):=20=E8=A3=9C=20goal-only?=
 =?UTF-8?q?=20unverified=20path=20=E6=B8=AC=E8=A9=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fable 驗證計畫指出「goal 非空 + checks 空 → unverified: true」是
最常見使用模式但零覆蓋。補兩條斷言釘住這條 path。

self-test 23 assertions ALL PASS。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 plugin/commands/refactor/scripts/test-postswap.sh | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/plugin/commands/refactor/scripts/test-postswap.sh b/plugin/commands/refactor/scripts/test-postswap.sh
index 51d79f2..b9a7bb8 100755
--- a/plugin/commands/refactor/scripts/test-postswap.sh
+++ b/plugin/commands/refactor/scripts/test-postswap.sh
@@ -96,6 +96,21 @@ printf 'final class NewImpl {}\n' > "$T/src/NewImpl.swift"
 
 # ── Gate step 12 goal checks (declared criteria echo — never a gate) ─────────
 # Earlier step-12 runs covered the absent-block silent path; now declare one.
+# First: goal with no checks → unverified: true
+cat >> "$T/.sourceatlas/refactor/legacy/1_target.yaml" <<'EOF'
+success_criteria:
+  goal: "wiring references NewImpl only"
+  checks: []
+EOF
+G --module legacy --step 12 --impl-file "$T/src/NewImpl.swift" >/dev/null; expect "step12 goal-only still passes" 0 $?
+has "step12 goal-only marks unverified" "$M" "unverified: true"
+# Now add actual checks (overwrite success_criteria by rewriting the file tail)
+python3 -c "
+import re, sys
+t = open(sys.argv[1]).read()
+t = re.sub(r'success_criteria:.*', '', t, flags=re.DOTALL)
+open(sys.argv[1],'w').write(t)
+" "$T/.sourceatlas/refactor/legacy/1_target.yaml"
 cat >> "$T/.sourceatlas/refactor/legacy/1_target.yaml" <<'EOF'
 success_criteria:
   goal: "wiring references NewImpl only"