@natjswenson/shipflow 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `@natjswenson/shipflow` are documented here.
 
+## 0.7.0 (2026-09-17)
+
+### Added
+
+- Added guarded main-only policy and GitHub Flow support.
+
+### Fixed
+
+- Hardened draft/fork pull request handling and legacy release recovery.
+
 ## 0.6.0 (2026-08-03) — the ambiguous fast path is refused, not guessed
 
 ### Fixed

package/README.md

@@ -1,7 +1,7 @@
 # shipflow
 
-<!-- >>> press:masthead v0.9.0 sha256:2c0f2d9aea4a GENERATED by @natjswenson/press, do not edit -->
-**NS** · NATE SWENSON · CLAUDE CODE SKILL · PRESS v0.9.0 · linkedin.com/in/natejswenson
+<!-- >>> press:masthead v0.11.0 sha256:582134ecd7a5 GENERATED by @natjswenson/press, do not edit -->
+**NS** · NATE SWENSON · CLAUDE CODE + CODEX SKILL · PRESS v0.11.0 · linkedin.com/in/natejswenson
 
 ---
 <!-- <<< press:masthead -->
@@ -34,11 +34,32 @@ three against the repo's real shape — it never silently picks one.
 |---|---|
 | `skills/shipflow/SKILL.md` | The interactive setup interview, and where it must stop and ask. |
 | `skills/shipflow/bin/` | The CLI: `detect`, `plan`, `apply`, `releases`, `release-dispatch`. |
-| `skills/shipflow/templates/` | The workflow files each pattern renders. |
+| `skills/shipflow/templates/` | GitHub Flow auto-merge for ready same-repository PRs, including `ready_for_review`; drafts and forks skip. |
 | `skills/shipflow/skill-invariants.json` | The prose guardrails and the baseline eval declaration. |
 
 ## Quick start
 
+Claude Code — run in chat:
+
+```text
+/plugin marketplace add natejswenson/claude-skills
+/plugin install shipflow@claude-skills
+/shipflow
+```
+
+Codex — run in a terminal from the root of this repository checkout:
+
+```bash
+codex plugin marketplace add "$PWD"
+codex plugin add shipflow@claude-skills
+```
+
+Start a new Codex session, then invoke in chat:
+
+```text
+$shipflow
+```
+
 ```sh
 npx -y @natjswenson/shipflow@latest detect --repo . --main main --dev dev
 ```
@@ -60,6 +81,13 @@ npx -y @natjswenson/shipflow@latest detect --repo . --main main --dev dev
 
 ## Requirements
 
+- **Claude Code:** Expose the authenticated `gh` CLI to shell tools.
+- **Codex:** Use the same `gh` authentication and repository permissions; Claude app connections are not imported.
+- **GitHub Flow credentials:** A configured PAT/App repository secret is required; an unavailable token skips cleanly. Maintainers handle fork merges and optional reminders with their own credentials.
+- **Personal data:** Configuration stays in `.github/shipflow.json` in the target repository; no private `~/.claude/shipflow` store is required.
+
+See [Codex migration notes](../../docs/codex-migration.md) for host tools and retained data paths.
+
 - Node 18+.
 - [`gh`](https://cli.github.com/), authenticated with admin rights on the target
   repo — branch protection cannot be read or written without them.
@@ -72,7 +100,7 @@ npx -y @natjswenson/shipflow@latest detect --repo . --main main --dev dev
 | Pattern | Shape |
 |---|---|
 | `dev-main-promotion` | Long-lived `dev` + `main`; a promotion PR auto-merges `dev` into `main` |
-| `github-flow` | Single long-lived `main`; every PR merges (and auto-merges) directly to it |
+| `github-flow` | Single long-lived `main`; ready same-repository PRs can auto-merge directly to it |
 | `gitflow` | `develop` + `main` + transient `release/*`/`hotfix/*`, for software maintaining multiple released versions concurrently |
 
 `detect` scores all three against the repo's branches, tags and workflow files,
@@ -90,10 +118,42 @@ detection is ambiguous or the repo is greenfield.
 3. **`shipflow apply`** — only after you confirm — renders the resolved pattern's
    workflow files and makes the confirmed mutations. Nothing happens outside what
    the plan showed.
-4. Ongoing: promotions auto-merge once required checks pass; a durable
+4. Ongoing: eligible PRs auto-merge once required checks pass; a durable
    `release-pending` label survives the async gap until a later
    `shipflow releases` check asks whether to cut a release.
 
+## GitHub Flow contributions
+
+Draft PRs skip merge automation. Ready PRs from the same repository can enable
+native auto-merge on `opened`, `reopened`, `synchronize` or `ready_for_review`;
+GitHub's required checks gate the merge. Keep implementation PRs draft until review
+and the authorized merge decision are complete.
+
+Repository write access is the trust boundary. Forks and missing head repositories
+skip both jobs. Maintainers review fork PRs and explicitly enable auto-merge or
+merge with their own authorized credentials after required checks. The workflow
+uses `pull_request` and executes no PR code.
+
+Configure `release.releaseCredential` as the name of a PAT/App repository secret
+with `contents: write` and `pull-requests: write`. Both commands skip cleanly if that
+named secret is unavailable, without falling back to `GITHUB_TOKEN`; setup must
+still provision it. Omitting the credential name instead retains the renderer’s
+legacy `GITHUB_TOKEN` default, which does not guarantee a skip or the merged-PR
+reminder. Always configure and provision the named PAT/App secret for this flow.
+A merged same-repository PR receives an optional `release-pending` label;
+unmerged closes and fork merges skip it. Maintainers may label fork merges manually,
+and component `release-status` discovers untagged work without labels. No PR event
+creates a tag or release.
+
+To migrate an existing generated workflow, run plan/apply with the corrected engine.
+During unreleased development, invoke `node <skill-directory>/bin/shipflow.js` from
+the corrected checkout; after release use `npx -y @natjswenson/shipflow@latest`.
+Review the plan, including any live settings changes, and apply with its state hash.
+An existing workflow matching its old `renderedTemplateHashes` receipt is recognized
+as a generator update. Commit the generated YAML and returned receipt together,
+then replan to confirm no template drift. Genuine hand edits still block apply;
+never edit the hash to hide them.
+
 ## Commands
 
 | Command | What it does |
@@ -101,7 +161,7 @@ detection is ambiguous or the repo is greenfield.
 | `detect --repo <path> [--main <name>] [--dev <name>]` | Inspect live repo state: branch protection, CI checks, release conventions |
 | `plan --repo <path>` | Diff `.github/shipflow.json` against live state; prints what would change plus a state hash |
 | `apply --repo <path> --expect-state-hash <hash> [--dry-run] [--force <id> --force-reason <text>]` | Apply a confirmed plan |
-| `releases --repo <path>` | List `dev → main` promotions still labeled `release-pending` |
+| `releases --repo <path>` | List merged main PR reminders (`mergedPrs` for GitHub flow, `promotions` for legacy consumers) |
 | `release-dispatch --repo <path> --pr <n> --workflow-file <f>... --ref <ref>` | Dispatch each changed skill's release workflow; clear the label on success |
 | `rename-default-branch --repo <path> --branch <old> --to <new>` | One-time bootstrap: rename a repo's default branch |
 
@@ -145,3 +205,10 @@ See [`CHANGELOG.md`](CHANGELOG.md). Releases are cut by a version bump, tagged
 ## License
 
 MIT — see [`LICENSE`](LICENSE).
+
+Component releases honor the selected branch pattern. GitHub flow prepares and
+merges its version/changelog PR directly into configured main; two-branch repos
+retain promotion. `release-status` discovers pending components without labels.
+`release-cut --version <x.y.z>` checks required CI, verifies the intended version
+and notes on fetched main, explicitly dispatches one workflow, and proves the
+remote tag. A merge or push alone does not release a component.

package/SKILL.md

@@ -2,10 +2,28 @@
 name: shipflow
 description: Scaffold a configurable dev/main branching, auto-merge, branch-cleanup, and release-tagging workflow into any repo. Detects existing branch protection, CI checks, and release conventions; always shows a plan and waits for confirmation before mutating anything. Use when the user asks to set up branch protection standards, apply deployment/release standards to a repo, or wants long-lived dev/main branches with auto-merge and branch cleanup.
 user_invocable: true
+version: 0.7.0
 ---
 
+## Codex runtime
+
+When running in Codex, invoke this skill as `$shipflow`. Resolve scripts, assets,
+and references from the directory containing this SKILL.md, regardless of the
+current working directory. Existing `~/.claude/` personal-data paths remain valid
+and are still used by the bundled scripts; they do not require Claude to run.
+Map `Read`/`Write`/`Edit`/`Bash` to the available file and shell tools, and
+`WebSearch`/`WebFetch` to available web tools. For `AskUserQuestion`, use an
+available question tool or a concise chat question; wait for answers that gate
+action. Use Codex's delegation tools for required subagents when available;
+otherwise disclose that independent execution is unavailable. Discover connected
+apps by capability rather than assuming Claude MCP tool names exist.
+
 # /shipflow — branching + release-automation setup
 
+<!-- press:runtime -->
+In Claude Code, load `/press`; in Codex, load `$press`; then follow the shared PRESS terminal/UI contract from `brand/agent-ui.md`. Do not copy or override that contract here.
+<!-- press:runtime -->
+
 All deterministic work is delegated to the CLI. Invoke it as
 `npx -y @natjswenson/shipflow@latest <command>` — **always with the explicit
 `@latest` tag, never bare `@natjswenson/shipflow`.** Without a version/tag,
@@ -48,7 +66,7 @@ user; the CLI is the only thing that *does*.
    - **Confident:** state what was detected and why (the top entry's `evidence` array) — *"I detected this repo is using **`<pattern-id>`** because: `<evidence bullets>`. I'll set `workflowPattern` to this — confirm before I proceed, or tell me if you'd rather pick a different pattern."* This is still a confirm-before-write checkpoint per this section's mandatory-interview rule — a confident autodetect is not a substitute for the user's explicit confirmation.
    - **Ambiguous or greenfield:** present all 3 patterns and ask the user to choose. Do not silently pick one:
      - `dev-main-promotion` — long-lived `dev` + `main`; a promotion PR auto-merges `dev` into `main`.
-     - `github-flow` — single long-lived `main`; every PR merges (and auto-merges) directly to `main`. Suggest this as the lightweight default for a **greenfield** repo specifically, without auto-picking it.
+     - `github-flow` — single long-lived `main`; ready same-repository PRs can auto-merge directly to `main`; forks require maintainer action. Suggest this as the lightweight default for a **greenfield** repo specifically, without auto-picking it.
      - `gitflow` — `develop` + `main` + transient `release/*`/`hotfix/*` branches, for software that maintains multiple released versions concurrently.
    - Once resolved, proceed with only the interview fields that pattern's config actually uses — skip asking about a `dev` branch name under `github-flow`, for instance.
    - If `workflowPattern` is `gitflow`, additionally ask for `releaseBranchPrefix`/`hotfixBranchPrefix` (defaulting to `release/`/`hotfix/` if the user has no preference) — recorded under `patternConfig.gitflow` in the config.
@@ -121,6 +139,45 @@ user; the CLI is the only thing that *does*.
 
 Same as steps 1, 8, 9, 10, 11 above, skipping the interview (`workflowPattern`/branch names/checks/protectionOwner/releaseCredential are already recorded in `.github/shipflow.json` — read it, don't re-ask, unless the user explicitly says they want to reconfigure). Step 2's pattern resolution never runs on a re-run — `workflowPattern`'s absence from a config genuinely means "not yet resolved," and its presence means "already resolved," so there's nothing to detect again. If `plan.creates`/`plan.updates` is non-empty, that's drift since the last apply — show it and confirm before applying, exactly as in first-run setup.
 
+## GitHub Flow readiness, forks and migration
+
+For `workflowPattern: "github-flow"`, the generated `pull_request` workflow handles
+`opened`, `reopened`, `synchronize`, `ready_for_review` and `closed` on configured
+main. Only a non-draft PR whose head repository matches the target repository can
+enable native auto-merge. Drafts skip cleanly; making a reviewed draft ready has
+its own trigger. Native GitHub required checks still gate the merge. Keep an
+implementation PR draft until review and the authorized merge decision are complete.
+
+Repository write access is the trust boundary. Forks and missing head repositories
+skip both jobs, regardless of contributor association or labels. Maintainers must
+review fork PRs and explicitly enable native auto-merge or merge with their own
+authorized credentials after required checks. Do not switch to
+`pull_request_target`, check out PR code, or run contributor-controlled scripts to
+make credentials available.
+
+Both commands use the configured `release.releaseCredential` PAT/App secret from
+setup step 6. If that named secret is unavailable or unset, the step reports a clean
+skip and invokes no `gh` command; it does not fall back to `GITHUB_TOKEN`. This does
+not provision or validate the credential. Omitting `release.releaseCredential`
+from configuration instead retains the renderer’s legacy `GITHUB_TOKEN` default,
+which does not guarantee a skip or the merged-PR reminder. Always configure and
+provision the named PAT/App secret for this flow.
+
+Only a merged same-repository PR receives the optional `release-pending` reminder.
+Unmerged closes and fork merges skip it; a maintainer may label a fork merge
+manually. Component `release-status` discovers untagged work without labels. No
+PR event cuts a tag or release.
+
+When upgrading this template, use the corrected checkout's
+`node <skill-directory>/bin/shipflow.js plan --repo <target>` and matching `apply`
+during unreleased development; use the explicit `@latest` invocation after release.
+Follow the reviewed plan and state-hash apply process above, including any live
+settings changes it proposes. If the existing workflow matches its recorded old
+`renderedTemplateHashes` receipt, plan recognizes a template update. Apply generates
+new bytes and returns the new receipt; commit both together and replan to verify
+no template drift. A genuine hand edit still requires the explicit scoped override;
+never manufacture a matching receipt by hand to bypass that refusal.
+
 ## Check pending releases (`manual-gate` ask-flow)
 
 This is a **separate, later invocation** from the one that ran the promotion's `apply` — native GitHub auto-merge completes asynchronously, with no live session attached at the moment of the actual merge. A durable `release-pending` label is what survives that gap.
@@ -154,11 +211,29 @@ and release workflow live, with `{name}` as the only substitution token;
 its root (`package.json`, `CHANGELOG.md`, `v{version}`), so a one-project repo needs no config
 at all and `--component` may be omitted.
 
+`workflowPattern: "github-flow"` is authoritative: preparation and feature PRs
+use configured main, status never reads dev, and cut skips promotion. A stale dev
+field does not change that. Absent-pattern and two-branch consumers retain the
+integration branch, promotion and dev-ahead refusal. GitHub-flow `releases`
+returns `mergedPrs`; legacy consumers retain `promotions`. These labels are
+optional reminders: component `release-status` inventories pending versions and
+tags without them, and `release-cut` requires no label.
+
+For the declared `skills/{name}/.codex-plugin/plugin.json` layout, preparation
+requires this repository's `tools/sync_codex.py` and `tools/check_compatibility.py`.
+It checks existing metadata, updates both lockfile version fields and the shared
+version files, runs generation and compatibility checks in the worktree, and
+refuses unrelated generated edits. Generic consumers have no Python dependency.
+Before requesting merge, cut reads the full live required-check set; before
+explicit dispatch, it fetches and verifies main's intended version and changelog.
+Keep main PRs draft until their review and authorized merge decision are complete;
+the existing GitHub-flow workflow enables native auto-merge on eligible PRs.
+
 1. **Read the state. Never guess it.**
    ```
    npx -y @natjswenson/shipflow@latest release-status --repo <path> --component <name>
    ```
-   Returns `state`, the version on main and dev, the last tag, every commit since that tag that
+   Returns `state`, `workflowPattern`, `releaseBase`, the version on main (and dev for two-branch repos), the last tag, every commit since that tag that
    touched this component's paths, a `suggestedBump` with its reason, `blockers`, `notes`, and a
    `statusHash`. `state` decides the path:
    - `clean` — the released version is what's on main. A bump is needed: go to step 2.
@@ -198,7 +273,7 @@ at all and `--component` may be omitted.
 3. **Cut it, and prove it.**
    ```
    npx -y @natjswenson/shipflow@latest release-cut --repo <path> --component <name> \
-     --expect-status-hash <hash-from-step-1> --wait 240
+     --version <prepared-or-confirmed-version> --expect-status-hash <hash-from-step-1> --wait 240
    ```
    `--expect-status-hash` is mandatory (same TOCTOU discipline as `apply`'s `--expect-state-hash`);
    `--skip-hash-check` is a named escape hatch, never a default.
@@ -209,7 +284,7 @@ at all and `--component` may be omitted.
    re-run `release-status` to release what's on dev (the normal recovery), **or** add
    `--version <x.y.z>` naming exactly the version on main, if you deliberately mean to release
    that one and leave dev's higher version for later. `--version` is a confirmation, not a
-   bypass — it is only ever accepted when it matches a version already on main or dev; anything
+   bypass — it is only ever accepted when it matches a version already on main, dev, or the verified prepared branch; anything
    else is refused the same as passing nothing.
 
    **`release-cut` is resumable and bounded, and it will usually return `done: false`.** The full
@@ -219,8 +294,8 @@ at all and `--component` may be omitted.
    derives every stage from live remote state and never from a record of what a previous call did,
    so a resumed run and a fresh one are the same code path.
 
-   **The promotion merging cuts nothing.** `release-cut` dispatches the component's release
-   workflow itself, after the promotion lands — that dispatch is the single point at which any tag
+   **Merging cuts nothing.** `release-cut` dispatches the component's release
+   workflow itself, after the selected version and notes reach main — that dispatch is the single point at which any tag
    is created in this repo, which is why a merge can no longer surprise anyone with a release.
 
 4. **Report the tag, and only the tag.** `done: true` carries `tag` and `releaseUrl`, read back

package/bin/shipflow.js

@@ -211,7 +211,7 @@ function cmdReleases(args) {
     ...p,
     ...confirmPromotionMerged(ownerRepo, p.number),
   }));
-  printJson({ promotions: withMergeCheck });
+  printJson(config.workflowPattern === 'github-flow' ? { mergedPrs: withMergeCheck } : { promotions: withMergeCheck });
 }
 
 function cmdReleaseDispatch(args) {

package/lib/release.mjs

@@ -12,13 +12,14 @@
 //   prepare()     — local writes only, in a THROWAWAY WORKTREE (see below)
 //   cut()         — the only irreversible one, gated on a status hash
 //
-// Why a throwaway worktree: `prepare` has to branch off dev and commit, and a
+// Why a throwaway worktree: `prepare` branches from the configured base and commits, and a
 // real repo's working tree routinely has unrelated in-flight work in it (this
 // monorepo's own tree did while this was written). Checking out a branch under
 // that, or staging from it, is how another session's uncommitted work gets
 // swept into a release commit. A `git worktree` is a clean, isolated checkout
-// of dev that cannot see the user's dirt at all, so there is nothing to sweep.
+// of that base that cannot see the user's dirt at all, so there is nothing to sweep.
 
+import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
 import { tmpdir } from 'node:os';
@@ -332,9 +333,19 @@ function revParse(repoPath, ref) {
 }
 
 function dirtyPaths(repoPath, relPaths) {
-  const r = git(['status', '--porcelain', '--', ...relPaths], { cwd: repoPath });
+  const r = spawnSync('git', ['status', '--porcelain=v1', '-z', '--untracked-files=all', '--', ...relPaths], {
+    cwd: repoPath, encoding: 'utf8', timeout: 30_000,
+  });
   if (r.status !== 0 || !r.stdout) return [];
-  return r.stdout.split('\n').map((l) => l.slice(3).trim()).filter(Boolean);
+  const records = r.stdout.split('\0');
+  const paths = [];
+  for (let i = 0; i < records.length; i++) {
+    const record = records[i];
+    if (!record) continue;
+    paths.push(record.slice(3));
+    if (/[RC]/.test(record.slice(0, 2))) i++; // rename/copy source follows destination
+  }
+  return paths;
 }
 
 // Every OTHER component whose version at `dev` carries no tag. A promotion is
@@ -369,20 +380,28 @@ export function collateralComponents(repoPath, config, exceptName, devRef) {
   return out;
 }
 
+// An explicit pattern is authoritative even during a migration with stale dev fields.
+function branchPolicy(config) {
+  const workflowPattern = config?.workflowPattern ?? 'dev-main-promotion';
+  const main = config?.branches?.main ?? 'main';
+  const dev = workflowPattern === 'github-flow' ? null : (config?.branches?.dev ?? 'dev');
+  return { workflowPattern, main, dev, base: dev ?? main };
+}
+
 export function readStatus(repoPath, config, name) {
   const component = resolveComponent(repoPath, config, name);
-  const mainBranch = config?.branches?.main ?? 'main';
-  const devBranch = config?.branches?.dev ?? 'dev';
+  const policy = branchPolicy(config);
+  const { main: mainBranch, dev: devBranch } = policy;
 
   // Read from the REMOTE-tracking refs, not the local branches: a local `main`
   // that has not been fetched in a week would compute a bump against a stale
   // baseline and silently propose a version that is already tagged.
   const fetched = git(['fetch', 'origin', '--tags', '--prune'], { cwd: repoPath });
   const mainRef = revParse(repoPath, `origin/${mainBranch}`) ? `origin/${mainBranch}` : mainBranch;
-  const devRef = revParse(repoPath, `origin/${devBranch}`) ? `origin/${devBranch}` : devBranch;
+  const devRef = devBranch ? (revParse(repoPath, `origin/${devBranch}`) ? `origin/${devBranch}` : devBranch) : null;
 
   const onMain = readVersionAt(repoPath, component, mainRef);
-  const onDev = readVersionAt(repoPath, component, devRef);
+  const onDev = devRef ? readVersionAt(repoPath, component, devRef) : { ok: false, version: null };
   const lastVersion = latestVersionTagged(repoPath, component);
   const lastTag = lastVersion ? tagFor(component, lastVersion) : null;
 
@@ -407,7 +426,7 @@ export function readStatus(repoPath, config, name) {
     notes.push(`could not fetch origin (${fetched?.stderr || 'unknown error'}) — versions and tags below may be stale`);
   }
   if (!onMain.ok) blockers.push({ id: 'version-unreadable-on-main', detail: onMain.error });
-  if (!onDev.ok) blockers.push({ id: 'version-unreadable-on-dev', detail: onDev.error });
+  if (devBranch && !onDev.ok) blockers.push({ id: 'version-unreadable-on-dev', detail: onDev.error });
 
   const changelogAbs = join(repoPath, component.changelog);
   if (!existsSync(changelogAbs)) {
@@ -473,17 +492,26 @@ export function readStatus(repoPath, config, name) {
   const suggestion = suggestBump(since.commits, onMain.version ?? '0.0.0');
   const nextVersion = suggestion.bump && onMain.ok ? bumpSemver(onMain.version, suggestion.bump) : null;
 
-  const collateral = collateralComponents(repoPath, config, name, devRef);
+  const collateral = devRef ? collateralComponents(repoPath, config, name, devRef) : [];
+  const pendingComponents = collateralComponents(repoPath, config, name, mainRef);
 
   // The TOCTOU guard for cut(). Everything that could change the meaning of a
   // release decision between the moment it is shown to a human and the moment
   // it is acted on: both branch heads, the versions, the last tag, and who
   // else is riding along.
+  const preparedBranches = git(['for-each-ref', '--format=%(refname)',
+    `refs/heads/feature/release-${name}-v*`, `refs/remotes/origin/feature/release-${name}-v*`], { cwd: repoPath })
+    .stdout.split('\n').filter(Boolean).sort().map((ref) => {
+      const version = readVersionAt(repoPath, component, ref).version;
+      return { ref, sha: revParse(repoPath, ref), version, notes: notesAt(repoPath, component, ref, version) };
+    });
   const statusHash = sha256(
     JSON.stringify({
       component: name,
+      preparedBranches,
       mainSha: revParse(repoPath, mainRef),
-      devSha: revParse(repoPath, devRef),
+      workflowPattern: policy.workflowPattern,
+      devSha: devRef ? revParse(repoPath, devRef) : null,
       versionOnMain: onMain.version,
       versionOnDev: onDev.version,
       lastTag,
@@ -500,6 +528,12 @@ export function readStatus(repoPath, config, name) {
       paths: component.paths,
       inferredLayout: component.inferredLayout,
     },
+    workflowPattern: policy.workflowPattern,
+    releaseBase: policy.base,
+    mainBranch,
+    devBranch,
+    pendingComponents,
+    preparedBranches,
     state,
     versionOnMain: onMain.version,
     versionOnDev: onDev.version,
@@ -520,6 +554,13 @@ export function readStatus(repoPath, config, name) {
 
 // ─── prepare ─────────────────────────────────────────────────────────────────
 function writeVersionInto(relPath, text, version) {
+  if (relPath.endsWith('package-lock.json')) {
+    const data = JSON.parse(text);
+    if (!data.version) return null;
+    data.version = version;
+    if (data.packages?.['']?.version) data.packages[''].version = version;
+    return JSON.stringify(data, null, 2) + '\n';
+  }
   if (relPath.endsWith('.json')) {
     // Line-targeted rather than JSON.parse → JSON.stringify: reserializing
     // would reformat the whole file (key order, indentation, trailing
@@ -585,11 +626,12 @@ export function spliceChangelog(existing, version, notes, date) {
 }
 
 export const releaseBranchName = (name, version) => `feature/release-${name}-v${version}`;
-const worktreeDir = (name, version) => join(tmpdir(), `shipflow-release-${name}-${version}`);
+const worktreeDir = (repoPath, name, version) => join(tmpdir(), `shipflow-release-${sha256(resolve(repoPath)).slice(0, 16)}-${name}-${version}`);
 
 export function prepare(repoPath, config, name, version, notes, { date, featureBranchPrefix } = {}) {
   const component = resolveComponent(repoPath, config, name);
-  const devBranch = config?.branches?.dev ?? 'dev';
+  const policy = branchPolicy(config);
+  const devBranch = policy.base;
   const tag = tagFor(component, version);
   const stamp = date ?? new Date().toISOString().slice(0, 10);
 
@@ -608,7 +650,7 @@ export function prepare(repoPath, config, name, version, notes, { date, featureB
   if (featureBranchPrefix && !branch.startsWith(featureBranchPrefix)) {
     return { ok: false, error: `release branch ${branch} does not start with the configured featureBranchPrefix ${featureBranchPrefix}` };
   }
-  const dir = worktreeDir(name, version);
+  const dir = worktreeDir(repoPath, name, version);
 
   // A leftover worktree from an aborted run must not silently become the base
   // for this one — remove it, then re-create from the CURRENT dev.
@@ -620,7 +662,9 @@ export function prepare(repoPath, config, name, version, notes, { date, featureB
   if (added.status !== 0) return { ok: false, error: `git worktree add failed: ${added.stderr}` };
 
   const changed = [];
+  const dualHost = component.versionFiles.includes(`skills/${name}/.codex-plugin/plugin.json`);
   try {
+    if (dualHost) checkDualHost(dir, true);
     for (const relPath of component.versionFiles) {
       const abs = join(dir, relPath);
       if (!existsSync(abs)) continue;
@@ -645,6 +689,16 @@ export function prepare(repoPath, config, name, version, notes, { date, featureB
     writeFileSync(clAbs, spliced.content);
     changed.push(component.changelog);
 
+    if (dualHost) {
+      const catalog = readFileSync(join(dir, '.agents/plugins/marketplace.json'), 'utf8');
+      checkDualHost(dir, false);
+      if (readFileSync(join(dir, '.agents/plugins/marketplace.json'), 'utf8') !== catalog) throw new Error('unexpected generated catalog edit during version-only preparation');
+      const allowed = new Set([...changed, '.agents/plugins/marketplace.json']);
+      const actual = dirtyPaths(dir, ['.']);
+      const unexpected = actual.filter((path) => !allowed.has(path));
+      if (unexpected.length) throw new Error(`unexpected generated edits: ${unexpected.join(', ')}`);
+      changed.push(...actual.filter((path) => !changed.includes(path)));
+    }
     // Explicit pathspecs, never `git add -A`. The worktree should contain
     // nothing else, but "should" is not a guarantee worth a release commit.
     const staged = git(['add', '--', ...changed], { cwd: dir });
@@ -659,6 +713,21 @@ export function prepare(repoPath, config, name, version, notes, { date, featureB
   }
 }
 
+// Fixed adapter for this repository's declared dual-host layout. Ordinary
+// consumers never execute Python. Refuse pre-existing drift before rewriting.
+function checkDualHost(dir, before) {
+  for (const file of ['tools/sync_codex.py', 'tools/check_compatibility.py']) {
+    if (!existsSync(join(dir, file))) throw new Error(`dual-host preparation requires ${file}`);
+  }
+  const commands = before
+    ? [['tools/sync_codex.py', '--check'], ['tools/check_compatibility.py']]
+    : [['tools/sync_codex.py'], ['tools/sync_codex.py', '--check'], ['tools/check_compatibility.py']];
+  for (const args of commands) {
+    const result = spawnArgs('python3', args, { cwd: dir, env: { ...process.env, PYTHONDONTWRITEBYTECODE: '1' } });
+    if (result.status !== 0) throw new Error(`dual-host ${args.join(' ')} failed: ${result.stderr || result.stdout}`);
+  }
+}
+
 // ─── resolving the release target ────────────────────────────────────────────
 // The one place a target version is decided. Before this existed, `cut()`
 // derived it twice, ten lines apart — once preferring dev, once preferring
@@ -675,9 +744,18 @@ export function prepare(repoPath, config, name, version, notes, { date, featureB
 // releases a version which isn't actually on the branch being dispatched.
 export function resolveReleaseTarget(status, requestedVersion = null) {
   const { state, versionOnMain, versionOnDev, devAhead, component } = status;
+  if (requestedVersion && !parseSemver(requestedVersion)) return { ok: false, error: 'requested version is not valid semver' };
+  if (status.preparedVersion && requestedVersion === status.preparedVersion) {
+    return { ok: true, version: requestedVersion, via: 'prepared-branch' };
+  }
+  if (requestedVersion && ![versionOnMain, versionOnDev].includes(requestedVersion)) {
+    return { ok: false, error: `requested version ${requestedVersion} is not on main, dev, or a verified prepared branch` };
+  }
+
 
   if (state === 'untagged-bump-on-main') {
     if (!devAhead) {
+      if (requestedVersion && requestedVersion !== versionOnMain) return { ok: false, error: 'requested version does not match main' };
       // The common, unambiguous case: whatever is on main is the only
       // candidate, dev has nothing higher.
       return { ok: true, version: versionOnMain, via: 'dispatch-on-main' };
@@ -705,7 +783,7 @@ export function resolveReleaseTarget(status, requestedVersion = null) {
   // Every other state (`clean`, `bump-on-dev-unpromoted`, `version-behind-tag`)
   // already has a single unambiguous candidate — dev, when it carries the
   // prepared bump, else main — matching what `cut()` used before this existed.
-  return { ok: true, version: versionOnDev ?? versionOnMain, via: 'prepared-branch' };
+  return { ok: true, version: requestedVersion ?? versionOnDev ?? versionOnMain, via: 'prepared-branch' };
 }
 
 // ─── cut ─────────────────────────────────────────────────────────────────────
@@ -730,8 +808,8 @@ function sleepSync(ms) {
 
 export function cut(repoPath, config, name, { waitSeconds = 240, expectStatusHash = null, skipHashCheck = false, ownerRepo, pollSeconds = 15, version = null } = {}) {
   const component = resolveComponent(repoPath, config, name);
-  const mainBranch = config?.branches?.main ?? 'main';
-  const devBranch = config?.branches?.dev ?? 'dev';
+  const policy = branchPolicy(config);
+  const { main: mainBranch, dev: devBranch } = policy;
   const owner = ownerRepo.split('/')[0];
 
   const status = readStatus(repoPath, config, name);
@@ -749,13 +827,28 @@ export function cut(repoPath, config, name, { waitSeconds = 240, expectStatusHas
   // three-way state (#173: main has an untagged bump AND dev carries
   // something higher) is refused here rather than acted on by the fast path
   // below.
+  if (version && parseSemver(version)) {
+    const preparedRef = releaseBranchName(name, version);
+    const prepared = readVersionAt(repoPath, component, preparedRef);
+    if (prepared.ok && prepared.version === version && version !== status.versionOnMain) status.preparedVersion = version;
+  }
   const target = resolveReleaseTarget(status, version);
   if (!target.ok) return { ok: false, error: target.error };
   const targetVersion = target.version;
   const tag = tagFor(component, targetVersion);
   const branch = releaseBranchName(name, targetVersion);
+  const released = tagExistsOnRemote(repoPath, tag);
+  if (released.ok && released.exists) {
+    const rel = ghApiJson(`repos/${ownerRepo}/releases/tags/${tag}`);
+    return { ok: true, done: true, stage: 'tag', tag, targetVersion, releaseUrl: rel.ok ? rel.data?.html_url ?? null : null, note: 'already released' };
+  }
   const deadline = Date.now() + waitSeconds * 1000;
   const log = [];
+  const preparedExists = Boolean(revParse(repoPath, branch));
+  const onBase = readVersionAt(repoPath, component, `origin/${policy.base}`);
+  const baseHasVersion = onBase.ok && onBase.version === targetVersion;
+  const sourceRef = target.via === 'prepared-branch' ? (preparedExists ? branch : `origin/${policy.base}`) : `origin/${mainBranch}`;
+  const expectedNotes = notesAt(repoPath, component, sourceRef, targetVersion);
   const note = (stage, msg) => log.push({ stage, msg });
 
   // Fast path: the bump is already on main and simply was never tagged (a
@@ -765,6 +858,8 @@ export function cut(repoPath, config, name, { waitSeconds = 240, expectStatusHas
     if (already.ok && already.exists) {
       return { ok: true, done: true, stage: 'tag', tag, targetVersion, note: 'already released' };
     }
+    const verified = verifyDispatch(repoPath, component, mainBranch, targetVersion, expectedNotes);
+    if (!verified.ok) return verified;
     const d = spawnArgs('gh', ['workflow', 'run', component.workflowFile, '--ref', mainBranch, '--repo', ownerRepo]);
     if (d.status !== 0) return { ok: false, error: `workflow dispatch failed: ${d.stderr}` };
     note('dispatch', `dispatched ${component.workflowFile} on ${mainBranch}`);
@@ -773,44 +868,46 @@ export function cut(repoPath, config, name, { waitSeconds = 240, expectStatusHas
   }
 
   // 1. push the prepared branch
-  if (!revParse(repoPath, branch)) {
+  if (!preparedExists && !baseHasVersion) {
     return { ok: false, error: `branch ${branch} does not exist — run release-prepare first` };
   }
-  const dir = worktreeDir(name, targetVersion);
+  const dir = worktreeDir(repoPath, name, targetVersion);
   const pushCwd = existsSync(dir) ? dir : repoPath;
-  if (!revParse(repoPath, `origin/${branch}`)) {
+  if (preparedExists && !baseHasVersion && !revParse(repoPath, `origin/${branch}`)) {
     const pushed = git(['push', '-u', 'origin', branch], { cwd: pushCwd });
     if (pushed.status !== 0) return { ok: false, error: `git push failed: ${pushed.stderr}` };
     note('push', `pushed ${branch}`);
   }
 
-  // 2. open the feature → dev PR
-  let featurePr = prNumberFor(ownerRepo, `${owner}:${branch}`, devBranch);
+  const featureBase = policy.base;
+
+  // 2. open the feature PR against the configured base
+  let featurePr = prNumberFor(ownerRepo, `${owner}:${branch}`, featureBase);
   if (!featurePr) {
-    const devHasIt = readVersionAt(repoPath, component, `origin/${devBranch}`);
+    const devHasIt = readVersionAt(repoPath, component, `origin/${featureBase}`);
     if (devHasIt.ok && cmpSemver(devHasIt.version, targetVersion) >= 0) {
       note('feature-merged', `${targetVersion} is already on ${devBranch}`);
     } else {
       const created = spawnArgs('gh', [
-        'pr', 'create', '--repo', ownerRepo, '--base', devBranch, '--head', branch,
+        'pr', 'create', '--repo', ownerRepo, '--base', featureBase, '--head', branch,
         '--title', `chore(${name}): release v${targetVersion}`,
-        '--body', `Release ${tag}.\n\nVersion bump and CHANGELOG entry land together, in this one change — releases here are publish-on-merge, so a follow-up promotion to fix notes is too late.`,
+        '--body', `Release ${tag}.\n\nVersion bump and CHANGELOG entry land together, in this one change — an explicit dispatch reads both from main before creating the tag.`,
       ]);
       if (created.status !== 0) return { ok: false, error: `gh pr create failed: ${created.stderr}` };
-      featurePr = prNumberFor(ownerRepo, `${owner}:${branch}`, devBranch);
+      featurePr = prNumberFor(ownerRepo, `${owner}:${branch}`, featureBase);
       note('feature-pr', `opened #${featurePr}`);
     }
   }
 
   // 3. wait for its checks, then squash it into dev
   if (featurePr) {
-    const gate = waitForChecks(ownerRepo, featurePr, deadline, pollSeconds, log);
+    const gate = waitForChecks(ownerRepo, featurePr, featureBase, config, deadline, pollSeconds, log);
     if (!gate.ok) return gate;
     if (!gate.done) return { ok: true, done: false, stage: 'feature-pr', featurePr, tag, targetVersion, log, next: 'call release-cut again — waiting on the feature PR’s checks' };
-    const method = config?.mergeMethod?.featureToDevMethod ?? 'squash';
+    const method = (devBranch ? config?.mergeMethod?.featureToDevMethod : config?.mergeMethod?.devToMainMethod) ?? 'squash';
     const merged = spawnArgs('gh', ['pr', 'merge', String(featurePr), '--repo', ownerRepo, `--${method}`, '--delete-branch']);
     if (merged.status !== 0) return { ok: false, error: `gh pr merge failed on the feature PR: ${merged.stderr}` };
-    note('feature-merged', `merged #${featurePr} into ${devBranch} (${method})`);
+    note('feature-merged', `merged #${featurePr} into ${featureBase} (${method})`);
     rmSync(dir, { recursive: true, force: true });
     git(['worktree', 'prune'], { cwd: repoPath });
   }
@@ -818,25 +915,28 @@ export function cut(repoPath, config, name, { waitSeconds = 240, expectStatusHas
   // 4. open (or find) the dev → main promotion. shipflow's rendered auto-merge
   //    workflow turns on native auto-merge from here; nothing polls for it.
   git(['fetch', 'origin', '--prune'], { cwd: repoPath });
-  let promotion = prNumberFor(ownerRepo, `${owner}:${devBranch}`, mainBranch);
-  if (!promotion) {
-    const created = spawnArgs('gh', [
-      'pr', 'create', '--repo', ownerRepo, '--base', mainBranch, '--head', devBranch,
-      '--title', `release: ${name} v${targetVersion}`,
-      '--body', releaseBody(name, targetVersion, status.collateral),
-    ]);
-    if (created.status !== 0) return { ok: false, error: `gh pr create failed on the promotion: ${created.stderr}` };
+  let promotion = null;
+  if (devBranch) {
     promotion = prNumberFor(ownerRepo, `${owner}:${devBranch}`, mainBranch);
-    note('promotion-open', `opened promotion #${promotion}`);
-  } else {
-    note('promotion-open', `promotion #${promotion} already open`);
-  }
+    if (!promotion) {
+      const created = spawnArgs('gh', [
+        'pr', 'create', '--repo', ownerRepo, '--base', mainBranch, '--head', devBranch,
+        '--title', `release: ${name} v${targetVersion}`,
+        '--body', releaseBody(name, targetVersion, status.collateral),
+      ]);
+      if (created.status !== 0) return { ok: false, error: `gh pr create failed on the promotion: ${created.stderr}` };
+      promotion = prNumberFor(ownerRepo, `${owner}:${devBranch}`, mainBranch);
+      note('promotion-open', `opened promotion #${promotion}`);
+    } else {
+      note('promotion-open', `promotion #${promotion} already open`);
+    }
 
-  // 5. wait for the promotion to auto-merge, then for the tag to appear
-  const landed = waitForMerge(ownerRepo, promotion, deadline, pollSeconds, log);
-  if (!landed.ok) return landed;
-  if (!landed.done) {
-    return { ok: true, done: false, stage: 'promotion-open', promotion, tag, targetVersion, log, next: 'call release-cut again — waiting on the promotion to auto-merge' };
+    // 5. wait for the promotion to auto-merge, then for the tag to appear
+    const landed = waitForMerge(ownerRepo, promotion, deadline, pollSeconds, log);
+    if (!landed.ok) return landed;
+    if (!landed.done) {
+      return { ok: true, done: false, stage: 'promotion-open', promotion, tag, targetVersion, log, next: 'call release-cut again — waiting on the promotion to auto-merge' };
+    }
   }
 
   // 6. The promotion landing cuts NOTHING on its own. Every caller's release
@@ -855,6 +955,8 @@ export function cut(repoPath, config, name, { waitSeconds = 240, expectStatusHas
   //    an in-flight one.
   const already = tagExistsOnRemote(repoPath, tag);
   if (!(already.ok && already.exists)) {
+    const verified = verifyDispatch(repoPath, component, mainBranch, targetVersion, expectedNotes);
+    if (!verified.ok) return verified;
     const d = spawnArgs('gh', ['workflow', 'run', component.workflowFile, '--ref', mainBranch, '--repo', ownerRepo]);
     if (d.status !== 0) {
       return { ok: false, error: `the promotion merged but dispatching ${component.workflowFile} failed: ${d.stderr}. Nothing is tagged; re-run release-cut to retry the dispatch.` };
@@ -865,6 +967,27 @@ export function cut(repoPath, config, name, { waitSeconds = 240, expectStatusHas
   return { ...result, targetVersion };
 }
 
+function notesAt(repoPath, component, ref, version) {
+  const result = git(['show', `${ref}:${component.changelog}`], { cwd: repoPath });
+  if (result.status !== 0) return null;
+  const lines = result.stdout.split('\n');
+  const start = lines.findIndex((line) => line.startsWith('## ') && (line.slice(3).split(/\s+/)[0] === version || line.slice(3).split(/\s+/)[0] === `[${version}]`));
+  if (start < 0) return null;
+  const end = lines.findIndex((line, i) => i > start && line.startsWith('## '));
+  return lines.slice(start + 1, end < 0 ? undefined : end).join('\n').trim() || null;
+}
+
+function verifyDispatch(repoPath, component, mainBranch, version, expectedNotes) {
+  const fetched = git(['fetch', 'origin', '--tags', '--prune'], { cwd: repoPath });
+  if (fetched.status !== 0) return { ok: false, error: 'cannot fetch main before dispatch' };
+  const current = readVersionAt(repoPath, component, `origin/${mainBranch}`);
+  if (!current.ok || current.version !== version) return { ok: false, error: `main version changed before dispatch; expected ${version}` };
+  if (!expectedNotes || notesAt(repoPath, component, `origin/${mainBranch}`, version) !== expectedNotes) {
+    return { ok: false, error: 'main changelog missing or changed before dispatch' };
+  }
+  return { ok: true };
+}
+
 function releaseBody(name, version, collateral) {
   const extra = collateral.length
     ? `\n\n**This promotion also moves these bumps to main** (a promotion is atomic and carries all of dev): ` +
@@ -875,25 +998,60 @@ function releaseBody(name, version, collateral) {
   return `Promotes \`${name}\` v${version} to main.${extra}`;
 }
 
-function waitForChecks(ownerRepo, prNumber, deadline, pollSeconds, log) {
+function waitForChecks(ownerRepo, prNumber, base, config, deadline, pollSeconds, log) {
+  const protection = ghApiJson(`repos/${ownerRepo}/branches/${encodeURIComponent(base)}/protection`);
+  if (!protection.ok && !/404/.test(protection.stderr)) return { ok: false, error: 'could not read required branch checks' };
+  const rules = ghApiJson(`repos/${ownerRepo}/rules/branches/${encodeURIComponent(base)}`);
+  if (!rules.ok) return { ok: false, error: 'could not read branch rules' };
+  const checks = protection.data?.required_status_checks?.checks ?? [];
+  const required = [
+    ...checks.map((c) => ({ context: c.context, appId: c.app_id })),
+    ...(protection.data?.required_status_checks?.contexts ?? [])
+      .filter((context) => !checks.some((c) => c.context === context))
+      .map((context) => ({ context })),
+    ...(rules.data ?? []).filter((r) => r.type === 'required_status_checks')
+      .flatMap((r) => (r.parameters?.required_status_checks ?? []).map((c) => ({ context: c.context, appId: c.integration_id }))),
+    ...(base === branchPolicy(config).main && config?.protectionOwner !== 'external' ? config?.requiredChecks ?? [] : [])
+      .map((context) => ({ context })),
+  ];
+  const matchesRun = (required, run) => run.name === required.context &&
+    (required.appId == null || required.appId === -1 || run.app?.id === required.appId);
+  const matchesStatus = (required, status) => status.context === required.context &&
+    (required.appId == null || required.appId === -1);
   for (;;) {
     const r = ghApiJson(`repos/${ownerRepo}/pulls/${prNumber}`);
     if (!r.ok) return { ok: false, error: `could not read PR #${prNumber}: ${r.stderr}` };
     const sha = r.data?.head?.sha;
-    const cr = ghApiJson(`repos/${ownerRepo}/commits/${sha}/check-runs?per_page=100`);
-    if (!cr.ok) return { ok: false, error: `could not read check runs: ${cr.stderr}` };
-    const runs = cr.data?.check_runs ?? [];
+    const runs = [];
+    const contexts = [];
+    for (let page = 1; ; page++) {
+      const cr = ghApiJson(`repos/${ownerRepo}/commits/${sha}/check-runs?per_page=100&page=${page}`);
+      if (!cr.ok) return { ok: false, error: `could not read check runs: ${cr.stderr}` };
+      const batch = cr.data?.check_runs ?? [];
+      runs.push(...batch);
+      if (batch.length < 100) break;
+    }
+    for (let page = 1; ; page++) {
+      const cs = ghApiJson(`repos/${ownerRepo}/commits/${sha}/status?per_page=100&page=${page}`);
+      if (!cs.ok) return { ok: false, error: 'could not read commit statuses' };
+      const batch = cs.data?.statuses ?? [];
+      contexts.push(...batch);
+      if (batch.length < 100) break;
+    }
+    const missing = required.filter((r) => !runs.some((c) => matchesRun(r, c) && c.status === 'completed' && ['success', 'neutral', 'skipped'].includes(c.conclusion)) && !contexts.some((c) => matchesStatus(r, c) && c.state === 'success'));
+    const failedStatuses = contexts.filter((c) => required.some((r) => matchesStatus(r, c)) && ['failure', 'error'].includes(c.state));
+    if (failedStatuses.length) return { ok: false, error: `required statuses failed: ${failedStatuses.map((c) => c.context).join(', ')}` };
     const pending = runs.filter((c) => c.status !== 'completed');
     const failed = runs.filter((c) => c.status === 'completed' && !['success', 'neutral', 'skipped'].includes(c.conclusion));
     if (failed.length > 0) {
       return { ok: false, error: `checks failed on PR #${prNumber}: ${failed.map((c) => c.name).join(', ')} — fix them, then call release-cut again` };
     }
-    if (runs.length > 0 && pending.length === 0) {
+    if ((runs.length > 0 || contexts.length > 0) && pending.length === 0 && missing.length === 0) {
       log.push({ stage: 'feature-pr', msg: `${runs.length} checks green` });
       return { ok: true, done: true };
     }
     if (Date.now() + pollSeconds * 1000 > deadline) {
-      log.push({ stage: 'feature-pr', msg: `${pending.length}/${runs.length} checks still running` });
+      log.push({ stage: 'feature-pr', msg: `${pending.length}/${runs.length} checks still running; missing required checks: ${missing.map((r) => r.context).join(', ')}` });
       return { ok: true, done: false };
     }
     sleepSync(pollSeconds * 1000);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natjswenson/shipflow",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Scaffold a configurable dev/main branching, auto-merge, branch-cleanup, and release-tagging workflow into any repo",
   "license": "MIT",
   "author": "Nate Swenson",

package/skill-invariants.json

@@ -109,7 +109,7 @@
     {
       "id": "untagged-bump-is-not-permission-to-cut",
       "pattern": "is not, by itself, permission to cut",
-      "rationale": "#173: `untagged-bump-on-main` collapsed two independently-true facts (main has an untagged bump; dev already carries something higher) into one state string, and the fast path acted on it without checking which one was true — silently tagging the OLDER version while a human meant the one on dev. This line is what stops an agent (or a human skimming the state table) from treating the state name alone as a green light; `devAhead` and the refusal it drives are the actual gate."
+      "rationale": "For legacy two-branch consumers only (GitHub flow never reads dev): #173: `untagged-bump-on-main` collapsed two independently-true facts (main has an untagged bump; dev already carries something higher) into one state string, and the fast path acted on it without checking which one was true — silently tagging the OLDER version while a human meant the one on dev. This line is what stops an agent (or a human skimming the state table) from treating the state name alone as a green light; `devAhead` and the refusal it drives are the actual gate."
     }
   ],
   "cli_commands_referenced": ["detect", "plan", "apply", "releases", "release-dispatch", "release-status", "release-prepare", "release-cut", "rename-default-branch"],

package/templates/github-flow/main-automerge.yml.tmpl

@@ -6,9 +6,13 @@ name: auto-merge to {{MAIN_BRANCH}}
 # (handEditDetected) until an explicit --force is passed. Commit both files
 # together in the same commit.
 #
-# GitHub Flow has no separate "promotion" branch — every PR into {{MAIN_BRANCH}}
-# is eligible for auto-merge and every merge is release-worthy, so unlike
-# dev-main-promotion's template, neither job here restricts on head.ref.
+# GitHub Flow has no separate promotion branch. Only ready PRs from this
+# repository are eligible for auto-merge; repository write access is the trust
+# boundary. Forks (and missing head repositories) skip both jobs because ordinary
+# pull_request events cannot supply repository secrets to forks. Maintainers
+# review fork PRs and enable auto-merge or merge with their own credentials after
+# required checks, and may add release-pending manually. No PR code is executed.
+# Same-repository merged PRs receive an optional reminder, never a tag or release.
 #
 # GH_TOKEN uses config.release.releaseCredential, NOT a hardcoded
 # secrets.GITHUB_TOKEN, because of GitHub's loop-prevention rule: a PR
@@ -25,7 +29,7 @@ name: auto-merge to {{MAIN_BRANCH}}
 
 on:
   pull_request:
-    types: [opened, reopened, synchronize, closed]
+    types: [opened, reopened, synchronize, ready_for_review, closed]
     branches: [{{MAIN_BRANCH}}]
 
 # Deny by default at the workflow level, grant per job. A workflow-level grant
@@ -39,20 +43,30 @@ on:
 permissions: {}
 
 jobs:
-  # Enables native GitHub auto-merge on open/reopen/synchronize — this job
+  # Enables native GitHub auto-merge on open/reopen/synchronize/ready — this job
   # does NOT wait for checks itself; it turns on auto-merge and exits. The
   # actual merge happens asynchronously, later, whenever GitHub's own
   # required-checks gate is satisfied (see the design's discussion of why a
   # bespoke polling/blocking job was rejected).
   auto-merge:
-    if: github.event.action != 'closed'
+    if: >-
+      github.event.action != 'closed' &&
+      github.event.pull_request.draft == false &&
+      github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     permissions:
       pull-requests: write
     steps:
       - name: Enable auto-merge
-        run: gh pr merge --auto {{MERGE_FLAG}} "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}"
+        run: |
+          if [ -z "$GH_TOKEN" ]; then
+            echo "Skipping auto-merge: GH_TOKEN is unavailable or not configured."
+            exit 0
+          fi
+          gh pr merge --auto {{MERGE_FLAG}} "$PR_NUMBER" --repo "$PR_REPO"
         env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_REPO: ${{ github.repository }}
           GH_TOKEN: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}
 
   # Fires once, when a PR actually merges (a separate event from the job
@@ -63,12 +77,20 @@ jobs:
   label-release-pending:
     if: >-
       github.event.action == 'closed' &&
-      github.event.pull_request.merged == true
+      github.event.pull_request.merged == true &&
+      github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     permissions:
       pull-requests: write
     steps:
       - name: Apply release-pending label
-        run: gh pr edit "${{ github.event.pull_request.number }}" --add-label release-pending --repo "${{ github.repository }}"
+        run: |
+          if [ -z "$GH_TOKEN" ]; then
+            echo "Skipping release reminder: GH_TOKEN is unavailable or not configured."
+            exit 0
+          fi
+          gh pr edit "$PR_NUMBER" --add-label release-pending --repo "$PR_REPO"
         env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_REPO: ${{ github.repository }}
           GH_TOKEN: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}