run

issue-to-pr — issue → merge-ready PR pipeline

Ten steps from an issue to a merged PR: the gates block, the depth between them scales to the tier. Use the current host's tools following R/companions.md; the workflow is shared across Claude Code and Codex. Resolve S/ to ../../scripts/ relative to this installed SKILL.md's directory, and R/ to its references/. Use absolute, quoted paths in shell calls, never paths relative to the project or a plugin environment variable. Run scripts with Bash (Git Bash on Windows), keeping the working directory on the checkout named by the step. One todo per step. A script prints KEY=value lines. Exit 2 is a stop: STOP_REASON on stdout, the instruction on stderr — do what it says, report any PUSH_ERROR, MERGE_ERROR or DIRTY_FILES verbatim, never work around it, and the same stop a third time is a livelock: hand back. Exit 4 means the call itself was wrong: fix the call and re-run. A red gate exits 1, with the gate's own code in GATE_<NAME>_EXIT.

Hard rules (never violate)

• Merge is gated on explicit in-session approval, runs ONLY in the main session, via S/finish.sh merge — never a bare gh pr merge, never --admin, never on the turn the PR opens, except a headless self-merge, which happens on the report's turn. Force-push only with --force-with-lease. Under --headless the go-ahead is the owner reply merge, or the --auto-merge policy through S/finish.sh merge --auto; a run on an issue that already stopped once never self-merges (R/headless.md).
• Ask contract: three moments, --grill reshapes the first (R/judgment.md) — (1) Step 3: ONE batched question if the ledger has open items, or the grill in its place, (2) the merge gate, (3) a hard stop. Decide everything else yourself and log it, and never ask what a script or the code can answer.
• Stage and commit through S/stage.sh with explicit paths; never git add -A/. or a diff piped into xargs git add. The script audits the index immediately before committing. Use the host's file-editing tools for multi-line code. Give PR and issue bodies to gh with --body-file, not interpolated shell strings.
• Keep every generated plan, ledger, draft body and resume note under RUN_DIR from Step 1, including files written by companions. Before an owned branch exists, use a unique OS-temp directory (mktemp -d) and retain its absolute path for resume. Never write early notes into the checkout or a shared run-main directory.
• Inspect tracked-state candidates reported by S/state.sh. Preserve project configuration and unrelated files. Report generated files and offer git rm --cached -- <exact paths> after approval; never delete them or rewrite history. Exclude confirmed generated paths from review inputs with Git pathspecs, even if tracked, and never stage them. Keep config changes in review.
• Evidence before assertion: no "green/passing" without the command output; look up any claim about the world outside this repo before building on it, ledgered either way (R/judgment.md).
• Humanize all human-facing text (report, PR body, UI strings > 1–2 words) at every tier, using the companion or its fallback — not code, logs or commit subjects.