fix(sc-gh-stack): resolve verification-pass findings from Opus review

- major: dry-run preview now uses the SAME freshness classifier as execution
  (_freshness_verdict shared by chain and plan_chain), so a re-run preview
  reports skip, never a false refuse_diverged that could lure a caller into
  rebasing an already-converted layer onto stale remote state; the plan stops
  at the first refusal instead of printing speculative entries; regression
  test pins preview==execution agreement on re-runs
- minor: agent dry_run now skips worktree creation entirely and runs the
  script against repo_root — a preview creates nothing
- minor: preflight distinguishes PREFLIGHT.GIT_MISSING (rc 127) from
  PREFLIGHT.NOT_A_REPO and adds a git_cli check symmetric with gh_cli
- minor: CHANGELOG/README caught up (--dry-run, Standard envelope, *_RISKY
  codes, rc-127 envelope guarantee, 60 tests)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: randlee

packages/sc-gh-stack/CHANGELOG.md

@@ -28,7 +28,18 @@ Orchestration release: background agents over the deterministic scripts.
   and `playbook-landing.md` were folded into existing routes instead of shipping
   separately (new stack = `playbook-graph-to-stacks.md` step 3; daily loop =
   `playbook-sync.md`; landing = `gh stack merge --yes` via SKILL.md).
-- 55 pytest cases.
+- `gh_stack_convert.py --dry-run` (alias `--validate`): previews the per-layer
+  plan (skip / rebase / fast-forward / refuse) using the same freshness
+  classifier the executor uses, mutating nothing; with preflight this is the
+  package's `--validate` surface (`--auto-fix` is deliberately replaced by the
+  trivial-conflict rubric).
+- Convert and sync agents use the Standard envelope (`canceled`, `aborted_by`,
+  `metadata.*`); a risky-conflict stop is `canceled: true, aborted_by: "policy"`
+  with `CONVERT.CONFLICT_RISKY` / `SYNC.CONFLICT_RISKY`, `recoverable: false`.
+- Scripts survive missing binaries (synthetic rc-127 results — always a fenced
+  envelope, never a traceback; `PREFLIGHT.GIT_MISSING` distinct from
+  `PREFLIGHT.NOT_A_REPO`).
+- 60 pytest cases.
 
 ## 0.1.0 — 2026-08-28
 

packages/sc-gh-stack/README.md

@@ -36,7 +36,10 @@ Invoked by the skill via the Task tool (`run_in_background: true`), one per stac
   (all-or-nothing: conflicts restore every branch), same conflict rubric,
   verifies layers above a fix contain it.
 
-Every report carries per-branch `before`/`after` SHAs and a `pushed` flag.
+Convert and sync report with the Standard envelope (`canceled`/`aborted_by`/
+`metadata`): every report carries per-branch `before`/`after` SHAs and a
+`pushed` flag, and a risky-conflict stop comes back as `canceled: true,
+aborted_by: "policy"` (`*_RISKY` error codes) — a hold for review, not a failure.
 
 ## Scripts
 
@@ -49,6 +52,7 @@ Stdlib-only Python 3; every run emits one fenced JSON envelope (`success`/`data`
   idempotent on re-run; refuses dirty trees, in-progress rebases, and diverged
   branches; fast-forwards branches merely behind; linearises trunk-merge
   layers; then `gh stack init`. Exit 5 on bad input or refused state.
+  `--dry-run` (alias `--validate`) previews the per-layer plan, mutating nothing.
 - `scripts/gh_stack_sync.py` — wraps `gh stack sync` with the same guards and
   envelope; exit 3 on conflict (all branches restored).
 - `scripts/gh_stack_shared.py` — git/gh wrappers and the envelope.

packages/sc-gh-stack/agents/sc-stack-convert.md

@@ -31,8 +31,10 @@ Complete the task quickly; report only decisions and discrepancies.
 - **worktree** (optional): worktree path; default `<repo_root>-worktrees/stack/<bottom-slug>`
   where `<bottom-slug>` is the resolved bottom branch name with `/` replaced by `-`
 - **push** (optional, default `true`): run `gh stack submit --auto` when fully clean
-- **dry_run** (optional, default `false`): pass `--dry-run` to the convert script and return
-  its per-layer plan without executing anything (skip steps 6–7)
+- **dry_run** (optional, default `false`): preview only — skip the worktree steps (2–3) and
+  the execution steps (6–7), and run the convert script with `--dry-run` directly against
+  `--cwd <repo_root>`; nothing is created or mutated (the fetch updates remote-tracking refs
+  only). Return the script's per-layer plan.
 
 ## Execution
 

packages/sc-gh-stack/scripts/gh_stack_convert.py

@@ -144,18 +144,20 @@ def begin_conversion(trunk: str, layers: List[str], cwd: Optional[Path] = None)
         gs.git(["config", "sc-gh-stack.conversion", conv_id], cwd=cwd)
 
 
-def _check_remote_freshness(layer: str, remote: str, cwd: Optional[Path]) -> Optional[Dict[str, Any]]:
-    """Refuse to chain a local branch missing remote commits; ff if merely behind.
+def _freshness_verdict(layer: str, remote: str, cwd: Optional[Path]) -> str:
+    """Pure classifier shared by execution (chain) and preview (plan_chain):
+    "ok" | "fast_forward" | "diverged".
 
     A layer already adopted by this conversion (orig ref recorded and the branch
     tip has moved off it) is judged against its recorded pre-rebase tip instead:
     the rebase rewrote local history, so plain ancestry against the remote no
     longer means anything — but any commit the remote gained AFTER adoption
     shows up as the remote tip no longer being an ancestor of the recorded tip.
-    Returns a failure dict, or None when the layer is safe to chain.
     """
+    if not gs.local_branch_exists(layer, cwd=cwd):
+        return "ok"    # will be created tracking the remote tip
     if not gs.remote_branch_exists(remote, layer, cwd=cwd):
-        return None
+        return "ok"
     remote_ref = f"{remote}/{layer}"
     orig = _orig_tip(layer, cwd=cwd)
     adopted = orig is not None and orig != _rev(_head(layer), cwd=cwd)
@@ -166,10 +168,23 @@ def _check_remote_freshness(layer: str, remote: str, cwd: Optional[Path]) -> Opt
         # (`git rebase <remote>/<layer>`), both of which must pass.
         if gs.is_ancestor(remote_ref, orig, cwd=cwd) \
                 or gs.is_ancestor(remote_ref, _head(layer), cwd=cwd):
-            return None
-    elif gs.is_ancestor(remote_ref, _head(layer), cwd=cwd):
+            return "ok"
+        return "diverged"
+    if gs.is_ancestor(remote_ref, _head(layer), cwd=cwd):
+        return "ok"
+    if gs.is_ancestor(_head(layer), remote_ref, cwd=cwd):
+        return "fast_forward"
+    return "diverged"
+
+
+def _check_remote_freshness(layer: str, remote: str, cwd: Optional[Path]) -> Optional[Dict[str, Any]]:
+    """Refuse to chain a local branch missing remote commits; ff if merely behind.
+    Returns a failure dict, or None when the layer is safe to chain."""
+    verdict = _freshness_verdict(layer, remote, cwd)
+    if verdict == "ok":
         return None
-    elif gs.is_ancestor(_head(layer), remote_ref, cwd=cwd):
+    remote_ref = f"{remote}/{layer}"
+    if verdict == "fast_forward":
         ff = _fast_forward(layer, remote_ref, cwd=cwd)
         if ff.returncode == 0:
             return None
@@ -285,13 +300,13 @@ def plan_chain(layers: List[str], trunk_ref: str, remote: str,
             else f"refs/remotes/{remote}/{layer}"
         entry: Dict[str, Any] = {"branch": layer,
                                  "onto": below if below_name is None else below_name}
-        remote_ref = f"{remote}/{layer}"
-        if gs.remote_branch_exists(remote, layer, cwd=cwd) \
-                and not gs.is_ancestor(remote_ref, layer_ref, cwd=cwd):
-            if gs.is_ancestor(layer_ref, remote_ref, cwd=cwd):
-                entry["action"] = "fast_forward_then_rebase"
-            else:
-                entry["action"] = "refuse_diverged"
+        verdict = _freshness_verdict(layer, remote, cwd)   # same classifier chain() uses
+        if verdict == "diverged":
+            entry["action"] = "refuse_diverged"
+            planned.append(entry)
+            break    # chain() stops here too; later entries would be speculative
+        if verdict == "fast_forward":
+            entry["action"] = "fast_forward_then_rebase"
             planned.append(entry)
             below, below_name = layer_ref, layer
             continue

packages/sc-gh-stack/scripts/gh_stack_preflight.py

@@ -32,6 +32,7 @@ def run_checks(cwd: Optional[Path] = None) -> List[Dict[str, Any]]:
     """All checks, in order. Pure function of the environment; no side effects."""
     checks: List[Dict[str, Any]] = []
 
+    checks.append(_check("git_cli", gs.git(["--version"], cwd=cwd).returncode == 0, INSTALL_DOC))
     checks.append(_check("gh_cli", gs.gh(["--version"], cwd=cwd).returncode == 0, INSTALL_DOC))
     ext = gs.gh(["extension", "list"], cwd=cwd)
     checks.append(_check("gh_stack_extension",
@@ -74,7 +75,13 @@ def main(argv: Optional[List[str]] = None) -> int:
     parser.add_argument("--cwd", type=Path, default=None, help="repository path (default: current dir)")
     args = parser.parse_args(argv)
 
-    if not gs.in_git_repo(cwd=args.cwd):
+    probe = gs.git(["rev-parse", "--is-inside-work-tree"], cwd=args.cwd)
+    if probe.returncode == 127:
+        gs.emit(gs.envelope(False, None, gs.error_obj(
+            "PREFLIGHT.GIT_MISSING", "git is not on PATH", False,
+            f"install git or fix PATH (probe loop in SKILL.md Step 1); {INSTALL_DOC}")))
+        return 1
+    if probe.returncode != 0:
         gs.emit(gs.envelope(False, None, gs.error_obj(
             "PREFLIGHT.NOT_A_REPO", "not inside a git repository", False, "cd into the repository")))
         return 1

packages/sc-gh-stack/tests/test_convert.py

@@ -498,6 +498,16 @@ def test_dry_run_previews_without_mutating(self, repo):
         assert gs.config_get("rerere.enabled", cwd=repo) == ""
         assert _orig_refs(repo) == ""
 
+    def test_dry_run_agrees_with_execution_on_rerun(self, repo):
+        """The preview must make the SAME decision the executor makes: after a
+        successful conversion, --dry-run reports skip (never refuse_diverged)
+        for every already-chained layer."""
+        code, env = cv.convert("main", ["pr1", "pr3"], cwd=repo)
+        assert code == cv.EXIT_OK, env
+        code, env = cv.convert("main", ["pr1", "pr3"], cwd=repo, dry_run=True)
+        assert code == cv.EXIT_OK, env
+        assert [p["action"] for p in env["data"]["planned"]] == ["skip", "skip"]
+
     def test_pr_number_resolution_uses_gh_stub(self, repo):
         # No patching: the PATH gh stub answers `gh pr view <n> --json headRefName -q .headRefName`.
         code, env = cv.convert("main", ["1", "3"], cwd=repo)

packages/sc-gh-stack/tests/test_preflight.py

@@ -63,6 +63,7 @@ def test_preflight_emits_envelope_when_no_binaries_on_path(self, monkeypatch, ca
         out = capsys.readouterr().out
         payload = json.loads(out.split("```json")[1].split("```")[0])
         assert payload["success"] is False
+        assert payload["error"]["code"] == "PREFLIGHT.GIT_MISSING"
 
     def test_envelope_error_shape(self):
         env = gs.envelope(False, None, gs.error_obj("X.Y", "m", True, "do it"))
@@ -78,6 +79,7 @@ def _healthy_env(monkeypatch, **overrides):
     }
     gh_map.update(overrides.pop("gh", {}))
     monkeypatch.setattr(gs, "gh", lambda args, cwd=None: gh_map[tuple(args)])
+    monkeypatch.setattr(gs, "git", lambda args, cwd=None: cp(0, "git version 2.44.0"))
     cfg = {"rerere.enabled": "true", "remote.pushDefault": ""}
     cfg.update(overrides.pop("config", {}))
     monkeypatch.setattr(gs, "config_get", lambda key, cwd=None: cfg.get(key, ""))
@@ -146,6 +148,13 @@ def test_main_reports_failed_names_and_exit_1(self, monkeypatch, capsys):
         assert payload["data"]["failed"] == ["working_tree_clean"]
 
     def test_main_outside_repo(self, monkeypatch, capsys):
-        monkeypatch.setattr(gs, "in_git_repo", lambda cwd=None: False)
+        monkeypatch.setattr(gs, "git", lambda args, cwd=None: cp(128, "", "not a git repository"))
         assert pf.main([]) == 1
         assert "PREFLIGHT.NOT_A_REPO" in capsys.readouterr().out
+
+    def test_main_git_missing_is_distinct_from_not_a_repo(self, monkeypatch, capsys):
+        monkeypatch.setattr(gs, "git", lambda args, cwd=None: cp(127, "", "git: cannot execute"))
+        assert pf.main([]) == 1
+        out = capsys.readouterr().out
+        assert "PREFLIGHT.GIT_MISSING" in out
+        assert "PREFLIGHT.NOT_A_REPO" not in out