fix(sc-gh-stack): resolve Opus guidelines-review findings F1,F3-F12

- F1: gh_stack_shared.run() returns a synthetic rc-127 CompletedProcess when a
  binary is missing/unexecutable, so every script still emits its fenced JSON
  envelope instead of a traceback; tests pin run() and an empty-PATH preflight
- F3+F6: convert and sync agents promoted to the Standard envelope (canceled,
  aborted_by, metadata.duration_ms/tool_calls/retry_count); a risky-conflict
  stop is canceled:true aborted_by:policy with CONVERT/SYNC.CONFLICT_RISKY and
  recoverable:false; mirrored in both playbooks and SKILL.md report contract
- F4: pushed flag sourcing disambiguated — script SHAs are pre-submit; agents
  re-derive pushed after gh stack submit per step 7
- F5: agent sections renamed to '## Output Format' per the Agent Template
- F7: delegation guardrails completed: correlation_id per stack, spec
  aggregation object ordered by correlation_id, summary.failed surfaced,
  timeout departure recorded as intentional
- F8: install-doc Validation expects both normal warns
- F9: worktree slug examples fixed (no case folding); rule restated in sync
  agent inputs
- F10: convert agent error boundary now a catch-all (forward any unlisted
  script envelope unchanged) with codes as illustrations
- F11: Step 1 and install-doc PATH probes iterate gh/git/python3 incl. pyenv
  shims
- F12: gh_stack_convert.py --dry-run/--validate previews the per-layer plan
  mutating nothing (dry_run agent input added; SKILL.md records preflight +
  dry-run as the --validate surface and the trivial-conflict rubric as the
  bounded --auto-fix); GIT.FETCH now recoverable:false per the package rule
F2 (registry entries for the agents in repo .claude) is REJECTED per user
directive: no installed copies in this repo's .claude — packages/ is the
single source of truth. 58 tests green.

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

Author: randlee

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

@@ -31,6 +31,8 @@ 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)
 
 ## Execution
 
@@ -63,15 +65,18 @@ Complete the task quickly; report only decisions and discrepancies.
 8. Never resolve a risky conflict, never `git push` directly, never force-push, never
    `git reset --hard`, never run bare interactive `gh stack` commands.
 
-## Output
+## Output Format
 
-Return ONE fenced JSON block. Success is a minimal decision log; failure must let the caller
-recover without investigating (the scripts' envelopes already carry the failing command,
-stderr, and recovery action — forward those fields, do not paraphrase them away).
+Return ONE fenced JSON block using the Standard envelope (this agent is multi-step). Success
+is a minimal decision log; failure must let the caller recover without investigating (the
+scripts' envelopes already carry the failing command, stderr, and recovery action — forward
+those fields, do not paraphrase them away).
 
 ```json
 {
   "success": true,
+  "canceled": false,
+  "aborted_by": null,
   "data": {
     "shape": "(main) <- feat/schema <- feat/api",
     "worktree": "/path/to/repo-worktrees/stack/feat-schema",
@@ -85,16 +90,26 @@ stderr, and recovery action — forward those fields, do not paraphrase them awa
     "surfaced": [],
     "next_step": null
   },
-  "error": null
+  "error": null,
+  "metadata": { "duration_ms": 48000, "tool_calls": 14, "retry_count": 0 }
 }
 ```
 
-On risky conflicts: `success: false`, `error` = the script's error object, `surfaced` lists
-each unresolved conflict as `{ "file", "layer", "worktree", "why_risky", "suggested_resolution" }`,
-and `next_step` says exactly where the rebase is paused. Every output produced after the
-convert script has run must include `branches` (with `pushed` per branch — the script's
-`data.branches` supplies it); outputs that stop earlier (PR resolution, worktree check,
-preflight) return that step's envelope alone.
+Field sourcing: `branches[].before`/`after` come from the script's `data.branches`;
+`pushed` MUST be re-derived after `gh stack submit --auto` per step 7 (the script never
+pushes, so its `pushed` values are pre-submit). When submit did not run (`push: false`,
+`dry_run: true`, or an early stop), report `pushed: false` for every rebased layer.
+
+Stopping on a risky conflict is a deliberate policy abort, not a failure of the operation:
+set `success: false, canceled: true, aborted_by: "policy"`, re-code the script's error as
+`CONVERT.CONFLICT_RISKY` with `recoverable: false` (a bare retry must not be attempted —
+a human resolves first), keep its forensic fields (`cmd`, files, `next_step`) intact, and
+list each conflict in `surfaced` as
+`{ "file", "layer", "worktree", "why_risky", "suggested_resolution" }`. Genuine failures
+(fetch, init, non-conflict rebase errors) keep `canceled: false` and the script's error
+object unchanged. Every output produced after the convert script has run must include
+`branches`; outputs that stop earlier (PR resolution, worktree check, preflight) return that
+step's envelope alone, wrapped with the `canceled`/`metadata` fields.
 
 ## Error Handling
 
@@ -104,8 +119,11 @@ preflight) return that step's envelope alone.
   recipe; earlier pushes stand.
 
 ### Propagated to caller (stop and report):
-- Preflight failures, `GIT.BRANCH_DIVERGED`, `CONVERT.REBASE_FAILED`, `STACK.INIT_FAILED`,
-  submit exit 9, and every risky conflict.
+- Every non-zero exit from the preflight or convert script not explicitly handled above —
+  forward the envelope unchanged. Illustrations: preflight failures, `GIT.BRANCH_DIVERGED`,
+  `GIT.DIRTY_TREE`, `GIT.REBASE_IN_PROGRESS`, `GIT.FETCH`, `CONVERT.REBASE_FAILED`,
+  `CONVERT.FF_FAILED`, `STACK.INIT_FAILED`, `VALIDATION.INPUT`, submit exit 9, and every
+  risky conflict.
 
 ## Constraints
 

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

@@ -51,9 +51,9 @@ Apply the mapping rules (a stack is strictly linear; its only external dependenc
 Ambiguous dependencies (order both unknown and consequential): do not guess — list them in
 `questions` and mark the affected stack `blocked: true`.
 
-## Output
+## Output Format
 
-Return ONE fenced JSON block:
+Return ONE fenced JSON block (Basic envelope — this agent is single-step and read-only):
 
 ```json
 {

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

@@ -25,8 +25,9 @@ made and any discrepancy the caller must handle.
 
 ## Inputs
 
-- **worktree** (required): path of the stack's worktree (a stack branch must be checked out
-  there; `gh stack checkout <branch>` if not)
+- **worktree** (required): path of the stack's worktree, computed with the SKILL.md slug rule
+  (`<repo_root>-worktrees/stack/<bottom-slug>`, `/` → `-`, no case folding); a stack branch
+  must be checked out there (`gh stack checkout <branch>` if not)
 - **fix_branch** (optional): a middle layer that just received commits — after syncing, verify
   every layer above it contains its tip
 
@@ -62,17 +63,20 @@ gh-stack tracking is per-worktree. When the given worktree does not track the st
 4. Never `git push` directly, never force-push, never `git reset --hard`, never bare
    interactive `gh stack` commands.
 
-## Output
+## Output Format
 
-Return ONE fenced JSON block. Success is a minimal decision log; failure must let the caller
-recover without investigation (the script's envelope carries the failing command, stderr, and
-recovery action — forward those fields, do not paraphrase them away).
+Return ONE fenced JSON block using the Standard envelope (this agent is multi-step). Success
+is a minimal decision log; failure must let the caller recover without investigation (the
+script's envelope carries the failing command, stderr, and recovery action — forward those
+fields, do not paraphrase them away).
 
 ```json
 {
   "success": true,
+  "canceled": false,
+  "aborted_by": null,
   "data": {
-    "worktree": "/path/to/repo-worktrees/stack/l1",
+    "worktree": "/path/to/repo-worktrees/stack/L1",
     "branches": [
       { "name": "L2", "before": "abc1", "after": "def2", "pushed": true },
       { "name": "L3", "before": "1122", "after": "3344", "pushed": true }
@@ -85,16 +89,21 @@ recovery action — forward those fields, do not paraphrase them away).
     "fix_contained_by": ["L3", "L4"],
     "next_step": null
   },
-  "error": null
+  "error": null,
+  "metadata": { "duration_ms": 32000, "tool_calls": 9, "retry_count": 0 }
 }
 ```
 
-On risky conflicts: `success: false`, `error` = the script's error object, `surfaced` lists
-each unresolved conflict as `{ "file", "layer", "worktree", "why_risky", "suggested_resolution" }`,
-and `next_step` says exactly where the rebase is paused. Include `branches` (with `pushed`
-per branch) in every output produced after `gh_stack_sync.py` has run — its `data.branches`
-supplies them; `fix_contained_by` appears only when `fix_branch` was given (layers above it
-that contain its tip; report any that do not).
+Stopping on a risky conflict is a deliberate policy abort: set
+`success: false, canceled: true, aborted_by: "policy"`, re-code the script's error as
+`SYNC.CONFLICT_RISKY` with `recoverable: false` (a human resolves before any retry), keep
+its forensic fields intact, and list each conflict in `surfaced` as
+`{ "file", "layer", "worktree", "why_risky", "suggested_resolution" }` with `next_step`
+saying exactly where the rebase is paused. Genuine failures keep `canceled: false` and the
+script's error object unchanged. Include `branches` (with `pushed` per branch) in every
+output produced after `gh_stack_sync.py` has run — its `data.branches` supplies them;
+`fix_contained_by` appears only when `fix_branch` was given (layers above it that contain
+its tip; report any that do not).
 
 ## Error Handling
 

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

@@ -1,7 +1,10 @@
 #!/usr/bin/env python3
 """Convert N existing branches (each based on trunk) into one linear gh stack.
 
-Usage: python3 gh_stack_convert.py <trunk> <bottom> ... <top> [--cwd PATH]
+Usage: python3 gh_stack_convert.py <trunk> <bottom> ... <top> [--cwd PATH] [--dry-run]
+
+--dry-run (alias --validate) previews the per-layer plan (skip / rebase /
+fast_forward_then_rebase / refuse_diverged) after a fetch, mutating nothing.
 
 Arguments after trunk are branch names or PR numbers (resolved via `gh pr view`),
 bottom to top. Each layer is rebased `--onto` the layer below, replaying only
@@ -270,8 +273,55 @@ def init_stack(trunk: str, layers: List[str], cwd: Optional[Path] = None) -> Dic
     return {"action": "initialised"}
 
 
-def convert(trunk: str, raw_layers: List[str], cwd: Optional[Path] = None) -> tuple[int, Dict[str, Any]]:
-    """Full workflow. Returns (exit_code, envelope). Testable without argparse."""
+def plan_chain(layers: List[str], trunk_ref: str, remote: str,
+               cwd: Optional[Path] = None) -> List[Dict[str, Any]]:
+    """Read-only preview of what chain() would do per layer. Mutates nothing:
+    no fast-forwards, no orig refs, no rebases."""
+    planned: List[Dict[str, Any]] = []
+    below = trunk_ref
+    below_name: Optional[str] = None
+    for layer in layers:
+        layer_ref = _head(layer) if gs.local_branch_exists(layer, cwd=cwd) \
+            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"
+            planned.append(entry)
+            below, below_name = layer_ref, layer
+            continue
+        if gs.is_ancestor(below, layer_ref, cwd=cwd) and not _has_merges(below, layer_ref, cwd=cwd):
+            entry["action"] = "skip"
+        else:
+            upstream = trunk_ref
+            if below_name is not None:
+                orig_below = _orig_tip(below_name, cwd=cwd)
+                if orig_below and gs.is_ancestor(orig_below, layer_ref, cwd=cwd):
+                    upstream = orig_below
+                elif gs.is_ancestor(below, layer_ref, cwd=cwd):
+                    upstream = below
+                else:
+                    fork = gs.git_out(["merge-base", orig_below or below, layer_ref], cwd=cwd)
+                    if fork:
+                        upstream = fork
+            entry["action"] = "rebase"
+            entry["upstream"] = upstream
+        planned.append(entry)
+        below, below_name = layer_ref, layer
+    return planned
+
+
+def convert(trunk: str, raw_layers: List[str], cwd: Optional[Path] = None,
+            dry_run: bool = False) -> tuple[int, Dict[str, Any]]:
+    """Full workflow. Returns (exit_code, envelope). Testable without argparse.
+
+    dry_run=True previews the per-layer plan (skip/rebase/fast-forward/refuse)
+    after a fetch, mutating nothing beyond remote-tracking refs."""
     def fail(code: int, err_code: str, msg: str, action: str,
              data: Optional[Dict[str, Any]] = None, recoverable: bool = True):
         # recoverable means: apply suggested_action, re-run, and it succeeds by
@@ -302,14 +352,15 @@ def fail(code: int, err_code: str, msg: str, action: str,
                     "git config remote.pushDefault origin")
     remote = gs.resolve_remote(cwd=cwd)
 
-    gs.git(["config", "rerere.enabled", "true"], cwd=cwd)
-    # autoUpdate stages rerere's replayed resolutions, so a fully-rerere-resolved
-    # stop reports conflict.files == [] and needs only `git rebase --continue`.
-    gs.git(["config", "rerere.autoUpdate", "true"], cwd=cwd)
+    if not dry_run:
+        gs.git(["config", "rerere.enabled", "true"], cwd=cwd)
+        # autoUpdate stages rerere's replayed resolutions, so a fully-rerere-resolved
+        # stop reports conflict.files == [] and needs only `git rebase --continue`.
+        gs.git(["config", "rerere.autoUpdate", "true"], cwd=cwd)
     fetch = gs.git(["fetch", remote, "--prune"], cwd=cwd)
     if fetch.returncode != 0:
         return fail(EXIT_ERR, "GIT.FETCH", f"git fetch {remote} failed: {fetch.stderr.strip()}",
-                    "check network/auth and re-run")
+                    "check network/auth and re-run", recoverable=False)
 
     trunk_ref = f"{remote}/{trunk}"
     if not gs.remote_branch_exists(remote, trunk, cwd=cwd):
@@ -320,11 +371,25 @@ def fail(code: int, err_code: str, msg: str, action: str,
         layers = resolve_layers(raw_layers, cwd=cwd)
         if trunk in layers:
             raise ValueError(f"layer equals trunk: {trunk}")
-        ensure_local_branches(layers, remote, cwd=cwd)
+        if dry_run:
+            for b in layers:
+                if not gs.local_branch_exists(b, cwd=cwd) \
+                        and not gs.remote_branch_exists(remote, b, cwd=cwd):
+                    raise ValueError(f"branch not found locally or on {remote}: {b}")
+        else:
+            ensure_local_branches(layers, remote, cwd=cwd)
     except ValueError as exc:
         return fail(EXIT_INPUT, "VALIDATION.INPUT", str(exc), "fix the layer list and re-run",
                     recoverable=False)
 
+    if dry_run:
+        data = {"mode": "dry_run", "trunk": trunk, "remote": remote, "layers": layers,
+                "shape": stack_shape(trunk, layers),
+                "planned": plan_chain(layers, trunk_ref, remote, cwd=cwd),
+                "next_step": "review the plan (any refuse_diverged layer must be reconciled "
+                             "first), then re-run without --dry-run to execute"}
+        return EXIT_OK, gs.envelope(True, data)
+
     before = {b: _rev(_head(b), cwd=cwd) for b in layers}
     base = {"trunk": trunk, "remote": remote, "layers": layers, "shape": stack_shape(trunk, layers)}
     begin_conversion(trunk, layers, cwd=cwd)
@@ -360,8 +425,10 @@ def main(argv: Optional[List[str]] = None) -> int:
     parser.add_argument("trunk")
     parser.add_argument("layers", nargs="+", help="branch names or PR numbers, bottom to top")
     parser.add_argument("--cwd", type=Path, default=None)
+    parser.add_argument("--dry-run", "--validate", action="store_true", dest="dry_run",
+                        help="preview the per-layer plan; mutate nothing")
     args = parser.parse_args(argv)
-    code, payload = convert(args.trunk, args.layers, cwd=args.cwd)
+    code, payload = convert(args.trunk, args.layers, cwd=args.cwd, dry_run=args.dry_run)
     gs.emit(payload)
     return code
 

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

@@ -16,8 +16,14 @@
 
 
 def run(cmd: Sequence[str], cwd: Optional[Path] = None) -> subprocess.CompletedProcess:
-    """Run a command, capturing output; never raises on non-zero exit."""
-    return subprocess.run(list(cmd), cwd=cwd, capture_output=True, text=True, check=False)
+    """Run a command, capturing output; never raises. A binary missing from
+    PATH returns a synthetic CompletedProcess (rc 127) so callers always get a
+    structured result and scripts always emit their fenced JSON envelope."""
+    try:
+        return subprocess.run(list(cmd), cwd=cwd, capture_output=True, text=True, check=False)
+    except (FileNotFoundError, NotADirectoryError, PermissionError) as exc:
+        return subprocess.CompletedProcess(args=list(cmd), returncode=127, stdout="",
+                                           stderr=f"{cmd[0]}: cannot execute ({exc})")
 
 
 def git(args: Sequence[str], cwd: Optional[Path] = None) -> subprocess.CompletedProcess:

packages/sc-gh-stack/skills/managing-gh-stacks/SKILL.md

@@ -50,12 +50,16 @@ which git && git --version
 which python3 && python3 --version   # scripts need >= 3.9
 ```
 
-If `gh` is not on PATH, probe common install locations before assuming it is absent —
-Claude Code's bash may not share PATH with the interactive shell:
+If any of them is not on PATH, probe common install locations before assuming it is absent —
+Claude Code's bash may not share PATH with the interactive shell (Homebrew dirs and pyenv
+shims are the usual omissions):
 
 ```bash
-for p in "/opt/homebrew/bin/gh" "/usr/local/bin/gh" "$HOME/.local/bin/gh"; do
-  [ -x "$p" ] && echo "Found at: $p" && break
+for cli in gh git python3; do
+  command -v "$cli" >/dev/null && continue
+  for d in /opt/homebrew/bin /usr/local/bin "$HOME/.local/bin" "$HOME/.pyenv/shims"; do
+    [ -x "$d/$cli" ] && echo "$cli found at: $d/$cli" && break
+  done
 done
 ```
 
@@ -104,9 +108,15 @@ All stack execution happens in dedicated worktrees, never in the user's checkout
 
 Delegate convert and sync via the Task tool with `run_in_background: true`; the plan agent is
 read-only and fast, so it may run in the foreground. Background agents complete
-asynchronously — wait for the completion notification rather than assuming a timeout, and
-never start a second agent on the same worktree while one is running. Cap 3–4 concurrent;
-one agent per stack:
+asynchronously — wait for the completion notification rather than assuming a timeout (a
+deliberate departure from the spec's per-task timeouts: background Task agents signal
+completion themselves). Never start a second agent on the same worktree while one is
+running. Cap 3–4 concurrent; one agent per stack, each invocation tagged with a
+`correlation_id` (use the stack's bottom-branch slug). When running agents over several
+stacks, aggregate per the spec: `{ "parallel": true, "concurrency": N, "results": [...],
+"summary": { "all_successful", "failed", "succeeded" } }`, results ordered by
+`correlation_id`, and surface `summary.failed` to the user — never silently drop a failed
+stack:
 
 | Situation | Agent | Input (as `<input_json>`) | Returns |
 |---|---|---|---|
@@ -148,6 +158,15 @@ the expected report. Simple one-command situations (land a green stack:
 - **Failure = forensic**: the exact command that failed, its stderr, per-branch state, and
   one concrete recovery action — replaying the tool calls must show what happened without
   further investigation.
+- **Envelope levels**: convert and sync agents use the Standard envelope (`canceled`,
+  `aborted_by`, `metadata.duration_ms`/`tool_calls`/`retry_count` added); a risky-conflict
+  stop is `canceled: true, aborted_by: "policy"` with error code `*_RISKY` and
+  `recoverable: false` — a deliberate hold for human review, not an operation failure. The
+  plan agent and the scripts use the Basic envelope.
+- **Validation surface**: `gh_stack_preflight.py` (environment) plus
+  `gh_stack_convert.py --dry-run` (per-layer plan preview, nothing mutated) are this
+  package's `--validate` mode; `--auto-fix` is deliberately absent — its bounded-fix role is
+  filled by the trivial-conflict rubric above.
 - **State guarantees**: scripts never push, never force, never delete refs; conversion stops
   at the first conflict with finished layers skipped on re-run; `gh stack sync` restores
   every branch on conflict (all-or-nothing); agents push only via `gh stack submit --auto` /