@natjswenson/shipflow 0.2.0

package/SKILL.md

@@ -0,0 +1,120 @@
+---
+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
+---
+
+# /shipflow — branching + release-automation setup
+
+All deterministic work is delegated to the CLI. Invoke it as
+`npx -y @natjswenson/shipflow <command>`. Every command prints JSON to
+stdout — parse it, don't try to re-derive what it computed.
+
+**This skill never mutates repo state directly.** Every mutating action goes
+through `shipflow apply`, and the computed plan is always shown to the user
+and confirmed before the real (non-dry-run) apply runs. This is the
+deterministic/nondeterministic split: you decide *what* and confirm with the
+user; the CLI is the only thing that *does*.
+
+## Decide which mode you're in
+
+| Situation | Mode |
+|---|---|
+| `.github/shipflow.json` doesn't exist in the target repo yet | **First-run setup** |
+| `.github/shipflow.json` exists, user wants to check/repair drift | **Re-run / audit** |
+| User asks "any releases pending?" / periodic check-in / after a `dev → main` merge | **Check pending releases** |
+
+## First-run setup
+
+**This whole section is a mandatory interactive interview, not a narrate-and-proceed pass.** Steps 2–4 below must end with the agent presenting a plain-language summary of what was detected and what's about to be written, and waiting for the user's explicit go-ahead — even when detected values already look correct. Never go from step 1's `detect` straight to step 4's config write without that confirmation turn; a value looking right is not the same as the user confirming it.
+
+1. **Detect.** Run:
+   ```
+   npx -y @natjswenson/shipflow detect --repo <path> --main main --dev dev
+   ```
+   (Use whatever branch names the user has, or `main`/`dev` as a starting guess — you'll confirm them next.) This prints a `RepoState` plus a `protectionOwnerClassification` of `"external"`, `"shipflow"`, or `"ambiguous"`.
+
+2. **Resolve a default-branch mismatch, if any.** Compare `repoState.repoSettings.defaultBranch` (the repo's actual GitHub default branch) to the `--main` name used in step 1. If they match, skip to step 3. If they differ (e.g. the repo's default is `master`), ask the user explicitly — do not silently assume either path:
+   - **Map onto the existing default branch** — set the config's `branches.main` to the detected default branch name and continue with the rest of setup treating that as "main." No mutating calls needed; `branches.main` is fully configurable.
+   - **Switch the repo's default branch to `main`** — flag this as a bigger, more disruptive action than the rest of setup (it affects every collaborator and every open PR), get a distinct explicit confirmation for it specifically, separate from the general setup go-ahead, then run:
+     ```
+     npx -y @natjswenson/shipflow rename-default-branch --repo <path> --branch <old-default> --to main
+     ```
+     GitHub natively retargets the default-branch pointer and open PRs' base ref. On success, tell the user their own local checkout still points at the old name and needs `git fetch origin && git checkout main` to follow, then re-run step 1's `detect` (repo state changed) before continuing.
+
+3. **Confirm branch names and required checks with the user.** Show `workflows.jobNames` from the detect output as candidate `requiredChecks` (this list is already filtered to jobs from workflows that actually trigger on `pull_request` — a job that only runs on `schedule`/`workflow_dispatch` can never satisfy a required check, so it's never offered as a candidate) and let the user confirm/edit the list. **An empty `requiredChecks` list is a fail-open state, not a valid steady state** — `shipflow apply` will hard-refuse to enable auto-merge with zero required checks (see Error handling below). Don't let the user skip this without understanding that consequence.
+
+   **If the candidate list is empty, offer to scaffold a starter CI workflow yourself** — this is a judgment call for the agent, not something shipflow's CLI does (the CLI stays free of per-language/build-tool logic). Investigate the repo directly (`package.json`, `Cargo.toml`, `project.yml`/`.xcodeproj`, `go.mod`, `pyproject.toml`, or whatever's actually there) and draft a minimal, conservative `pull_request`-triggered build+test workflow. **Never silently overwrite an existing workflow file.** Present the drafted YAML to the user and wait for explicit confirmation before writing it — the same confirm-before-write pattern as everything else in this skill. Say plainly that this is a best-effort starting point inferred from repo structure, not a guarantee it's green on the first run — a required check that never passes blocks every future merge, so the user should watch it actually run successfully before relying on it as a required check. Once it exists, re-run step 1's `detect` (repo state changed) and continue this step with the new job name as a real candidate.
+
+4. **Resolve `protectionOwner`:**
+   - `"external"` → tell the user which settings-as-code artifact was found (`settingsAsCodeArtifact` in the detect output) and that shipflow will defer to it, managing only cleanup/automerge/release, not installing a competing ruleset.
+   - `"shipflow"` → tell the user no existing branch protection was found and shipflow will own it going forward.
+   - `"ambiguous"` → **branch protection exists but no settings-as-code artifact was found** (e.g. hand-configured via the GitHub UI). Do NOT silently pick either value — this is exactly the false-positive failure mode a prior design iteration got wrong. Ask explicitly: *"Branch protection exists on this repo but isn't managed as code — should shipflow take ownership of it, or keep managing it externally even though no artifact was found?"* Record whichever the user picks.
+
+5. **Present the interview summary and write `.github/shipflow.json`.** Before writing anything, show the user the resolved branch names, `requiredChecks`, and `protectionOwner` together in one place and wait for explicit confirmation — this is the checkpoint called out at the top of this section. Then write the config in the target repo (never inside the skill package) using `config.example.json` as the template, with `release.mode: "manual-gate"` (the only implemented mode in this version — see Auto mode, below). Tell the user `.github/shipflow.json` is committed policy and should be `git add`/committed — ideally in the same commit as the rendered auto-merge workflow, once step 9 produces one.
+
+6. **Show the plan.** Run:
+   ```
+   npx -y @natjswenson/shipflow plan --repo <path>
+   ```
+   This prints `{ plan, stateHash }`. Present `plan.creates`/`plan.updates`/`plan.noops` to the user in plain language — what will be created, what will change, what's already correct. **Wait for explicit confirmation before proceeding.** If any entry has `handEditDetected: true`, call it out specifically and ask whether to override (see step 8).
+
+7. **Dry-run apply** (optional sanity check, same output shape as the real apply but nothing is mutated):
+   ```
+   npx -y @natjswenson/shipflow apply --repo <path> --dry-run
+   ```
+
+8. **Apply for real**, passing the `stateHash` from step 6's plan output as `--expect-state-hash` — this is the TOCTOU guard: if repo state drifted between the plan you showed the user and this call, `apply` refuses to mutate anything and tells you to re-plan.
+   ```
+   npx -y @natjswenson/shipflow apply --repo <path> --expect-state-hash <hash-from-step-6>
+   ```
+   If a `handEditDetected` entry was confirmed for override in step 6, pass `--force <entry-id>` (repeatable — one flag per confirmed entry id, never a blanket override).
+
+9. **Report the result.** Read `applied`/`skipped`/`errors` from the response. A `skipped` entry can be a deliberate refusal (empty checks, hand-edit) or an environment limitation shipflow can't do anything about (e.g. a deletion-ruleset skipped because the repo is private and not on a paid GitHub tier) — read each `reason` and relay it plainly rather than treating every `skipped` entry the same. If `renderedTemplateHashes` is non-empty, update `.github/shipflow.json`'s `renderedTemplateHashes` field with those values and tell the user to commit the config change *and* the rendered workflow file **together, in the same commit** — a split commit is exactly what causes a false `handEditDetected` on a clean checkout later.
+
+## Re-run / audit
+
+Same as steps 1, 6, 7, 8, 9 above, skipping the interview (branch names/checks/protectionOwner are already recorded in `.github/shipflow.json` — read it, don't re-ask, unless the user explicitly says they want to reconfigure). 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.
+
+## 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.
+
+1. Run:
+   ```
+   npx -y @natjswenson/shipflow releases --repo <path>
+   ```
+   This returns every `dev → main` PR still labeled `release-pending`, each with a `merged` flag (confirmed independently, not just inferred from the label).
+
+2. For **each** promotion returned (there can be more than one if several merged before you last checked — handle the whole list, not just the most recent): if `merged` is `false`, skip it for now (native auto-merge hasn't landed yet; don't ask about a promotion that isn't actually on `main`). If `merged` is `true`, ask the user: *"A promotion merged to main — cut a release for [changed skills]?"*
+
+3. If yes, dispatch each changed skill's release workflow and clear the label **only after every dispatch is confirmed successful**:
+   ```
+   npx -y @natjswenson/shipflow release-dispatch --repo <path> --pr <number> --workflow-file <skill1>.yml --workflow-file <skill2>.yml --ref main
+   ```
+   If `dispatched` shows a partial failure, the label is deliberately left in place — report this to the user and note the promotion will resurface next time `releases` is checked; a later re-dispatch is safe (each skill's release workflow is idempotent).
+
+4. If no, leave the label as-is — there is no "defer" state in this version; declining is final for that promotion short of a manual dispatch. (Deliberate v1 simplification, not an oversight.)
+
+## Auto mode (not yet implemented)
+
+`release.mode: "auto"` is a valid value in the config schema (the full design covers automatic tagging via `release-please`), but `shipflow apply` in this version **refuses to run** against a config with `release.mode: "auto"`, with a clear error rather than silently no-oping. If a user asks for fully automatic tagging, tell them it's designed but not yet shipped (see `CHANGELOG.md`) and that `"manual-gate"` — the deliberate ask-before-tagging flow above — is what's available today.
+
+## Error handling
+
+- **Empty `requiredChecks`:** `apply` refuses to wire up auto-merge with zero required checks. Don't work around this by suggesting `--force allow-no-checks` unless the user has explicitly and knowingly accepted an unprotected merge — surface the refusal message plainly first.
+- **`handEditDetected`:** a template file's on-disk content doesn't match what shipflow last rendered *or* what it would freshly render — someone hand-edited it. Never silently pass `--force` for this; always show the user what changed and get explicit confirmation per entry.
+- **TOCTOU abort:** if `apply` returns a `toctou` error, repo state changed between plan and apply — re-run the plan step, don't retry the same `--expect-state-hash`.
+- **`gh auth` failures:** surface these immediately; branch protection and rulesets need repo-admin scope. Don't proceed partway through a plan on missing auth.
+
+## Security rules
+
+- All `gh`/`git` invocations in the CLI are argv-style (`spawnSync` with an args array, no shell) — never construct a shell command string from user input when extending this skill.
+- `.github/shipflow.json` is committed policy, not secrets — never write credential *values* into it, only the *name* of a secret (`release.releaseCredential`).
+- Never write shipflow's config anywhere other than `.github/shipflow.json` in the target repo.
+
+## Edge cases
+
+- **Greenfield repo, no CI yet:** `requiredChecks` will detect empty. Don't silently proceed — tell the user auto-merge can't be enabled until at least one check exists, and that's a real ordering dependency (CI first, then shipflow setup), not a shipflow bug.
+- **Repo already has `shipflow.json` with `release.mode: "auto"`:** refuse per "Auto mode," above, even on a re-run/audit — don't silently downgrade it to `"manual-gate"` either; surface the refusal and let the user decide.
+- **Private repo on a free GitHub plan:** the deletion-protection ruleset requires GitHub Pro/Team/Enterprise for private repos (rulesets are free for public repos only). `apply` reports this as a `skipped` entry with that reason, not an `errors` entry — it's an expected environment limitation, not a shipflow bug. Cleanup and the release-pending label still apply normally.

package/bin/shipflow.js

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+
+import { detectRepoState, classifyProtectionOwner, resolveOwnerRepo } from '../lib/detect.mjs';
+import { computePlan } from '../lib/plan.mjs';
+import {
+  applyPlan,
+  listPendingReleasePromotions,
+  confirmPromotionMerged,
+  clearReleasePendingLabel,
+  dispatchReleaseWorkflow,
+  renameDefaultBranch,
+} from '../lib/apply.mjs';
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const TEMPLATE_PATH = join(PACKAGE_ROOT, 'templates', 'dev-to-main-automerge.yml.tmpl');
+
+function readPackageVersion() {
+  const pkg = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+  return pkg.version;
+}
+
+function readConfig(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function defaultConfigPath(repoPath) {
+  return join(repoPath, '.github', 'shipflow.json');
+}
+
+function printJson(obj) {
+  console.log(JSON.stringify(obj, null, 2));
+}
+
+function fail(message) {
+  console.error(JSON.stringify({ error: message }));
+  process.exit(1);
+}
+
+// --- commands ---------------------------------------------------------------
+
+function cmdDetect(args) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      repo: { type: 'string' },
+      main: { type: 'string', default: 'main' },
+      dev: { type: 'string', default: 'dev' },
+      'release-credential': { type: 'string' },
+    },
+  });
+  if (!values.repo) return fail('detect: --repo is required');
+
+  const repoState = detectRepoState(values.repo, {
+    branches: { main: values.main, dev: values.dev },
+    releaseCredentialName: values['release-credential'] ?? null,
+  });
+  const protectionOwner = classifyProtectionOwner(repoState);
+  printJson({ ...repoState, protectionOwnerClassification: protectionOwner });
+}
+
+function cmdPlan(args) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      repo: { type: 'string' },
+      config: { type: 'string' },
+    },
+  });
+  if (!values.repo) return fail('plan: --repo is required');
+
+  const configPath = values.config ?? defaultConfigPath(values.repo);
+  let config;
+  try {
+    config = readConfig(configPath);
+  } catch (e) {
+    return fail(`plan: could not read config at ${configPath}: ${e.message}`);
+  }
+
+  const repoState = detectRepoState(values.repo, {
+    branches: config.branches,
+    releaseCredentialName: config.release?.releaseCredential ?? null,
+  });
+  const templateSource = readFileSync(TEMPLATE_PATH, 'utf8');
+  const plan = computePlan(repoState, config, templateSource);
+  printJson({ plan, stateHash: repoState.stateHash });
+}
+
+function cmdApply(args) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      repo: { type: 'string' },
+      config: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+      'expect-state-hash': { type: 'string' },
+      force: { type: 'string', multiple: true, default: [] },
+    },
+  });
+  if (!values.repo) return fail('apply: --repo is required');
+
+  const configPath = values.config ?? defaultConfigPath(values.repo);
+  let config;
+  try {
+    config = readConfig(configPath);
+  } catch (e) {
+    return fail(`apply: could not read config at ${configPath}: ${e.message}`);
+  }
+
+  if (config.release?.mode === 'auto') {
+    return fail(
+      'apply: release.mode "auto" is accepted in config but not yet implemented in this version of shipflow — see CHANGELOG.md (Phase B, not yet shipped). Set release.mode to "manual-gate" or wait for a future release.'
+    );
+  }
+
+  const ownerRepo = resolveOwnerRepo(values.repo);
+  const repoState = detectRepoState(values.repo, {
+    branches: config.branches,
+    releaseCredentialName: config.release?.releaseCredential ?? null,
+  });
+  const templateSource = readFileSync(TEMPLATE_PATH, 'utf8');
+  const plan = computePlan(repoState, config, templateSource);
+
+  // The CLI-level TOCTOU gate: compare the freshly-detected state against
+  // what the user confirmed at plan time (--expect-state-hash, captured
+  // from an earlier `shipflow plan` call). applyPlan's own internal check
+  // (currentStateHash vs plan.sourceStateHash) is always trivially satisfied
+  // here since both are computed from the same fresh detect — this
+  // CLI-level comparison against the user-confirmed hash is the meaningful
+  // gate against drift between plan-confirmation and apply-start.
+  if (!values['dry-run'] && values['expect-state-hash'] && values['expect-state-hash'] !== repoState.stateHash) {
+    return printJson({
+      applied: [],
+      skipped: [],
+      errors: [{ id: 'toctou', message: 'repo state changed since the plan was confirmed — re-run to get an updated plan' }],
+      renderedTemplateHashes: {},
+    });
+  }
+
+  const result = applyPlan(plan, {
+    dryRun: values['dry-run'],
+    currentStateHash: repoState.stateHash,
+    force: values.force,
+    ownerRepo,
+    repoPath: values.repo,
+    config,
+  });
+  printJson(result);
+}
+
+function cmdReleases(args) {
+  const { values } = parseArgs({ args, options: { repo: { type: 'string' }, config: { type: 'string' } } });
+  if (!values.repo) return fail('releases: --repo is required');
+  const configPath = values.config ?? defaultConfigPath(values.repo);
+  const config = readConfig(configPath);
+  const ownerRepo = resolveOwnerRepo(values.repo);
+  if (!ownerRepo) return fail('releases: could not resolve owner/repo from git remote');
+
+  const result = listPendingReleasePromotions(ownerRepo, config.branches.main);
+  if (!result.ok) return fail(`releases: ${result.error}`);
+
+  const withMergeCheck = result.promotions.map((p) => ({
+    ...p,
+    ...confirmPromotionMerged(ownerRepo, p.number),
+  }));
+  printJson({ promotions: withMergeCheck });
+}
+
+function cmdReleaseDispatch(args) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      repo: { type: 'string' },
+      pr: { type: 'string' },
+      'workflow-file': { type: 'string', multiple: true },
+      ref: { type: 'string' },
+    },
+  });
+  if (!values.repo || !values.pr || !values['workflow-file'] || !values.ref) {
+    return fail('release-dispatch: --repo, --pr, --workflow-file (repeatable), and --ref are required');
+  }
+  const ownerRepo = resolveOwnerRepo(values.repo);
+  if (!ownerRepo) return fail('release-dispatch: could not resolve owner/repo from git remote');
+
+  const merged = confirmPromotionMerged(ownerRepo, values.pr);
+  if (!merged.ok || !merged.merged) {
+    return fail(`release-dispatch: PR #${values.pr} is not confirmed MERGED — refusing to dispatch`);
+  }
+
+  const results = values['workflow-file'].map((wf) => ({ workflowFile: wf, ...dispatchReleaseWorkflow(ownerRepo, wf, values.ref) }));
+  const allOk = results.every((r) => r.ok);
+  if (!allOk) {
+    printJson({ dispatched: results, labelCleared: false, note: 'not all dispatches succeeded — label left in place, will resurface next run' });
+    return;
+  }
+  const cleared = clearReleasePendingLabel(ownerRepo, values.pr);
+  printJson({ dispatched: results, labelCleared: cleared.ok, labelClearError: cleared.ok ? null : cleared.error });
+}
+
+function cmdRenameDefaultBranch(args) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      repo: { type: 'string' },
+      branch: { type: 'string' },
+      to: { type: 'string' },
+    },
+  });
+  if (!values.repo || !values.branch || !values.to) {
+    return fail('rename-default-branch: --repo, --branch, and --to are all required');
+  }
+  const ownerRepo = resolveOwnerRepo(values.repo);
+  if (!ownerRepo) return fail('rename-default-branch: could not resolve owner/repo from git remote');
+
+  const result = renameDefaultBranch(ownerRepo, values.branch, values.to);
+  printJson(result);
+}
+
+function printHelp() {
+  console.log(`shipflow ${readPackageVersion()}
+
+Usage: shipflow <command> [options]
+
+Commands:
+  detect --repo <path> [--main <name>] [--dev <name>] [--release-credential <name>]
+  plan --repo <path> [--config <path>]
+  apply --repo <path> [--config <path>] [--dry-run] [--expect-state-hash <hash>] [--force <id>]...
+  releases --repo <path> [--config <path>]
+  release-dispatch --repo <path> --pr <number> --workflow-file <file>... --ref <ref>
+  rename-default-branch --repo <path> --branch <current-name> --to <new-name>
+
+Every command prints JSON to stdout.`);
+}
+
+// ─── dispatch ────────────────────────────────────────────────────────────────
+// Only run the CLI dispatch when this file is executed directly, not when it
+// is imported (e.g. by the test suite). Both sides are realpath'd: under
+// npm/npx, argv[1] is the node_modules/.bin/shipflow SYMLINK while
+// import.meta.url is the resolved file — a naive === never matches and
+// every npx invocation becomes a silent no-op (this exact bug bit devlog —
+// see this repo's CHANGELOG/commit e69b6ba).
+const isMain = (() => {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  const arg = process.argv[2];
+  const rest = process.argv.slice(3);
+  switch (arg) {
+    case 'detect':
+      cmdDetect(rest);
+      break;
+    case 'plan':
+      cmdPlan(rest);
+      break;
+    case 'apply':
+      cmdApply(rest);
+      break;
+    case 'releases':
+      cmdReleases(rest);
+      break;
+    case 'release-dispatch':
+      cmdReleaseDispatch(rest);
+      break;
+    case 'rename-default-branch':
+      cmdRenameDefaultBranch(rest);
+      break;
+    case '-v':
+    case '--version':
+      console.log(readPackageVersion());
+      break;
+    case undefined:
+    case '-h':
+    case '--help':
+      printHelp();
+      break;
+    default:
+      console.error(`Unknown command: ${arg}`);
+      printHelp();
+      process.exit(1);
+  }
+}

package/config.example.json

@@ -0,0 +1,23 @@
+{
+  "branches": { "main": "main", "dev": "dev" },
+  "featureBranchPrefix": "feature/",
+  "requiredChecks": [],
+  "mergeMethod": {
+    "featureToDevMethod": "squash",
+    "devToMainMethod": "merge"
+  },
+  "protectionOwner": "external",
+  "release": {
+    "enabled": true,
+    "mode": "manual-gate",
+    "tool": "release-please",
+    "layout": "manifest",
+    "releaseCredential": "GITHUB_TOKEN"
+  },
+  "branchCleanup": {
+    "deleteOnMerge": true,
+    "protectedBranches": ["dev", "main"]
+  },
+  "enforceAdmins": false,
+  "renderedTemplateHashes": {}
+}

package/lib/apply.mjs

@@ -0,0 +1,203 @@
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawnArgs, ghApiJson } from './gh.mjs';
+
+// applyPlan(plan, opts): opts extends the schematic { dryRun, currentStateHash,
+// force } from the design contract with the execution context (ownerRepo,
+// repoPath, config) apply.mjs actually needs to perform mutations — the
+// contract captured intent, not a literal final call signature.
+//
+// opts.force: an array of plan-entry ids the caller has explicitly confirmed
+// should proceed despite a handEditDetected flag, OR the literal string
+// "allow-no-checks" to override the empty-required-checks refusal. Never a
+// global boolean — a force scoped to one entry can't accidentally blanket-
+// override every other flagged entry in the same plan.
+// Repository Rulesets are gated behind GitHub Pro/Team/Enterprise for
+// private repos (free only for public repos) — this is GitHub's exact error
+// string for that case, distinct from a generic 403 (bad token, no admin
+// scope, etc.) which should still surface as a real error.
+const RULESET_TIER_GATED_RE = /Upgrade to GitHub (Pro|Team|Enterprise)/i;
+
+export function classifyRulesetError(stderr) {
+  if (RULESET_TIER_GATED_RE.test(stderr)) {
+    return {
+      tierGated: true,
+      reason:
+        'deletion-protection ruleset requires GitHub Pro/Team/Enterprise for private repos on the free tier — skipped, not a shipflow bug. Make the repo public or upgrade to enable it.',
+    };
+  }
+  return { tierGated: false, reason: null };
+}
+
+export function applyPlan(plan, opts) {
+  const { dryRun, currentStateHash, force = [], ownerRepo, repoPath, config } = opts;
+
+  // TOCTOU guard — refuse before making ANY mutating call if live state has
+  // drifted since the plan was computed. Idempotency is the primary safety
+  // net (re-running is always safe); this is the narrower, single-shot
+  // pre-flight that catches drift between plan-confirmation and apply-start.
+  if (!dryRun && currentStateHash !== plan.sourceStateHash) {
+    return {
+      applied: [],
+      skipped: [],
+      errors: [
+        {
+          id: 'toctou',
+          message: 'repo state changed since the plan was confirmed — re-run to get an updated plan',
+        },
+      ],
+      renderedTemplateHashes: {},
+    };
+  }
+
+  const applied = [];
+  const skipped = [];
+  const errors = [];
+  const renderedTemplateHashes = {};
+
+  const mutating = [...plan.creates, ...plan.updates];
+
+  // Empty-required-checks hard refusal (fail-open guard). Effective required
+  // checks are config.requiredChecks under shipflow-owned protection, or the
+  // live-detected union (plan.liveRequiredChecks) under external ownership
+  // — see the design's protectionOwner discussion for why these differ.
+  const effectiveChecks = config.protectionOwner === 'shipflow' ? config.requiredChecks ?? [] : plan.liveRequiredChecks ?? [];
+  const templateEntries = mutating.filter((e) => e.id.startsWith('template:'));
+  if (effectiveChecks.length === 0 && templateEntries.length > 0 && !force.includes('allow-no-checks')) {
+    for (const entry of templateEntries) {
+      skipped.push({
+        id: entry.id,
+        reason:
+          'refusing to enable auto-merge with zero required checks — set requiredChecks or pass force: ["allow-no-checks"] to override',
+      });
+    }
+  }
+
+  for (const entry of mutating) {
+    if (skipped.some((s) => s.id === entry.id)) continue; // already skipped above (empty-checks refusal)
+
+    if (entry.handEditDetected && !force.includes(entry.id)) {
+      skipped.push({ id: entry.id, reason: `hand-edit detected — pass force: ["${entry.id}"] to override` });
+      continue;
+    }
+
+    if (dryRun) {
+      applied.push({ id: entry.id, description: entry.description, dryRun: true });
+      continue;
+    }
+
+    const result = applyOne(entry, { ownerRepo, repoPath, config });
+    if (result.ok) {
+      applied.push({ id: entry.id, description: entry.description });
+      if (entry.id.startsWith('template:') && entry.renderedHash) {
+        renderedTemplateHashes[entry.path] = entry.renderedHash;
+      }
+    } else if (result.tierGated) {
+      skipped.push({ id: entry.id, reason: result.error });
+    } else {
+      errors.push({ id: entry.id, message: result.error });
+    }
+  }
+
+  return { applied, skipped, errors, renderedTemplateHashes };
+}
+
+function applyOne(entry, { ownerRepo, repoPath, config }) {
+  if (entry.id === 'delete-branch-on-merge') {
+    const r = ghApiJson(`repos/${ownerRepo}`, ['-X', 'PATCH', '-f', `delete_branch_on_merge=${entry.desired}`]);
+    return r.ok ? { ok: true } : { ok: false, error: r.stderr };
+  }
+
+  if (entry.id === 'deletion-ruleset') {
+    const body = JSON.stringify({
+      name: 'shipflow-branch-deletion-protection',
+      target: 'branch',
+      enforcement: 'active',
+      conditions: {
+        ref_name: { include: [`refs/heads/${config.branches.dev}`, `refs/heads/${config.branches.main}`], exclude: [] },
+      },
+      rules: [{ type: 'deletion' }],
+    });
+    const r = spawnArgs('gh', ['api', `repos/${ownerRepo}/rulesets`, '-X', 'POST', '--input', '-'], { input: body });
+    if (r.status === 0) return { ok: true };
+    const { tierGated, reason } = classifyRulesetError(r.stderr);
+    return tierGated ? { ok: false, tierGated: true, error: reason } : { ok: false, error: r.stderr };
+  }
+
+  if (entry.id === 'release-pending-label') {
+    const r = ghApiJson(`repos/${ownerRepo}/labels`, [
+      '-f', 'name=release-pending',
+      '-f', 'color=0E8A16',
+      '-f', 'description=shipflow: this dev-to-main promotion is awaiting a release decision',
+    ]);
+    return r.ok ? { ok: true } : { ok: false, error: r.stderr };
+  }
+
+  if (entry.id.startsWith('template:')) {
+    const full = join(repoPath, entry.path);
+    try {
+      mkdirSync(dirname(full), { recursive: true });
+      writeFileSync(full, entry.content, 'utf8');
+      return { ok: true };
+    } catch (e) {
+      return { ok: false, error: String(e.message || e) };
+    }
+  }
+
+  return { ok: false, error: `unknown plan entry id: ${entry.id}` };
+}
+
+// --- Manual-gate ask-flow helpers -----------------------------------------
+//
+// These are invoked by a SEPARATE, later shipflow invocation than the one
+// that ran applyPlan for the promotion — the design established (round 3)
+// that the ask cannot happen at promotion time, since native async
+// auto-merge completes with no live session attached. A subsequent
+// interactive run enumerates every promotion PR still labeled
+// release-pending, confirms each is actually MERGED (not just labeled —
+// belt and suspenders against a labeling-job race), and only clears a
+// label after its own release dispatch is confirmed successful.
+
+export function listPendingReleasePromotions(ownerRepo, mainBranch) {
+  const r = ghApiJson(
+    `search/issues?q=${encodeURIComponent(`repo:${ownerRepo} is:pr is:merged base:${mainBranch} label:release-pending`)}`
+  );
+  if (!r.ok) return { ok: false, error: r.stderr, promotions: [] };
+  const items = r.data?.items ?? [];
+  return { ok: true, promotions: items.map((i) => ({ number: i.number, title: i.title, mergedAt: i.pull_request?.merged_at ?? null })) };
+}
+
+export function confirmPromotionMerged(ownerRepo, prNumber) {
+  const r = ghApiJson(`repos/${ownerRepo}/pulls/${prNumber}`);
+  if (!r.ok) return { ok: false, merged: false, error: r.stderr };
+  return { ok: true, merged: r.data?.merged === true, mergeCommitSha: r.data?.merge_commit_sha ?? null };
+}
+
+// Clears the release-pending label — MUST only be called after every
+// changed skill's release dispatch for this promotion has been confirmed
+// successful. A partial failure must leave the label in place so the whole
+// set resurfaces on the next run (already-released skills re-dispatch as
+// idempotent no-ops, per the design's Testing strategy).
+export function clearReleasePendingLabel(ownerRepo, prNumber) {
+  const r = ghApiJson(`repos/${ownerRepo}/issues/${prNumber}/labels/release-pending`, ['-X', 'DELETE']);
+  return r.ok ? { ok: true } : { ok: false, error: r.stderr };
+}
+
+export function dispatchReleaseWorkflow(ownerRepo, skillWorkflowFile, ref) {
+  const r = spawnArgs('gh', ['workflow', 'run', skillWorkflowFile, '--ref', ref]);
+  return r.status === 0 ? { ok: true } : { ok: false, error: r.stderr };
+}
+
+// A one-time bootstrap action, not part of the steady-state plan/apply diff
+// model — renaming a repo's default branch affects every collaborator and
+// open PR, so it's a distinct, explicitly-confirmed CLI command rather than
+// a plan entry. GitHub's rename endpoint natively moves the default-branch
+// pointer and retargets open PRs when the renamed branch is the current
+// default; no extra shipflow-side logic is needed for that part.
+export function renameDefaultBranch(ownerRepo, fromBranch, toBranch) {
+  const r = spawnArgs('gh', [
+    'api', '-X', 'POST', `repos/${ownerRepo}/branches/${fromBranch}/rename`,
+    '-f', `new_name=${toBranch}`,
+  ]);
+  return r.status === 0 ? { ok: true } : { ok: false, error: r.stderr };
+}

package/lib/detect.mjs

@@ -0,0 +1,235 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnArgs, ghApiJson, git, sha256 } from './gh.mjs';
+
+const TEMPLATE_RELATIVE_PATH = '.github/workflows/dev-to-main-automerge.yml';
+const CONFIG_RELATIVE_PATH = '.github/shipflow.json';
+
+// Files/content patterns that indicate branch protection is already managed
+// as code elsewhere in the repo — see the design's "Rulesets vs. an existing
+// settings-as-code source of truth" discussion. Matching one of these is
+// what makes protectionOwner classify as "external" instead of falling
+// through to the ambiguous (protection-exists-but-no-artifact) prompt case.
+const SETTINGS_AS_CODE_NAME_RE = /repo-settings\.(sh|js|mjs|py)$/i;
+const SETTINGS_AS_CODE_CONTENT_RE =
+  /github_branch_protection|github_repository_ruleset|branches\/[\w-]+\/protection/;
+
+export function resolveOwnerRepo(repoPath) {
+  const r = git(['remote', 'get-url', 'origin'], { cwd: repoPath });
+  if (r.status !== 0) return null;
+  const m = r.stdout.match(/github\.com[:/]([\w.-]+)\/([\w.-]+?)(\.git)?$/);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+export function listTrackedFiles(repoPath) {
+  const r = git(['ls-files'], { cwd: repoPath });
+  return r.status === 0 ? r.stdout.split('\n').filter(Boolean) : [];
+}
+
+// Finds a settings-as-code artifact by name pattern first (cheap), then by
+// content pattern for anything under .github/ or a common IaC directory
+// (avoids grepping the whole tree — bounded to files a settings-as-code
+// script/config plausibly lives in).
+export function findSettingsAsCodeArtifact(repoPath, trackedFiles) {
+  const byName = trackedFiles.find((f) => SETTINGS_AS_CODE_NAME_RE.test(f));
+  if (byName) return byName;
+
+  const candidates = trackedFiles.filter(
+    (f) => f.startsWith('.github/') || /\.(tf|tfvars)$/i.test(f) || /pulumi/i.test(f)
+  );
+  for (const f of candidates) {
+    const full = join(repoPath, f);
+    if (!existsSync(full)) continue;
+    let content;
+    try {
+      content = readFileSync(full, 'utf8');
+    } catch {
+      continue;
+    }
+    if (SETTINGS_AS_CODE_CONTENT_RE.test(content)) return f;
+  }
+  return null;
+}
+
+// A job that never runs on a pull_request can never satisfy a required
+// status check — picking one as requiredChecks would block every future
+// merge forever. This is a text-based heuristic (matching the rest of this
+// file's no-YAML-parser style), not a full YAML parse: good enough to catch
+// the common schedule/workflow_dispatch-only case.
+const PULL_REQUEST_TRIGGER_RE = /pull_request(_target)?\b/;
+
+export function listWorkflowJobNames(repoPath, trackedFiles) {
+  const names = new Set();
+  const jobNameRe = /^\s{2}([\w.-]+):\s*$/;
+  for (const f of trackedFiles.filter((f) => /^\.github\/workflows\/.*\.ya?ml$/.test(f))) {
+    const full = join(repoPath, f);
+    if (!existsSync(full)) continue;
+    let content;
+    try {
+      content = readFileSync(full, 'utf8');
+    } catch {
+      continue;
+    }
+    const lines = content.split('\n');
+    const jobsLineIdx = lines.findIndex((l) => l.trim() === 'jobs:');
+    if (jobsLineIdx === -1) continue;
+    const triggerSection = lines.slice(0, jobsLineIdx).join('\n');
+    if (!PULL_REQUEST_TRIGGER_RE.test(triggerSection)) continue; // never PR-triggered
+    for (const line of lines.slice(jobsLineIdx + 1)) {
+      if (line.trim() !== '' && /^\S/.test(line)) break; // dedented out of the jobs: block
+      const m = line.match(jobNameRe);
+      if (m) names.add(m[1]);
+    }
+  }
+  return [...names].sort();
+}
+
+export function readTemplateFileHash(repoPath) {
+  const full = join(repoPath, TEMPLATE_RELATIVE_PATH);
+  if (!existsSync(full)) return { exists: false, sha256: null };
+  const content = readFileSync(full, 'utf8');
+  return { exists: true, sha256: sha256(content) };
+}
+
+export function readExistingConfig(repoPath) {
+  const full = join(repoPath, CONFIG_RELATIVE_PATH);
+  if (!existsSync(full)) return null;
+  try {
+    return JSON.parse(readFileSync(full, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function fetchBranchProtection(ownerRepo, branch) {
+  const r = ghApiJson(`repos/${ownerRepo}/branches/${branch}/protection`);
+  if (!r.ok) return null;
+  const checks = r.data?.required_status_checks?.contexts ?? [];
+  return { requiredChecks: checks, raw: r.data };
+}
+
+export function fetchRulesets(ownerRepo) {
+  const r = ghApiJson(`repos/${ownerRepo}/rulesets`);
+  if (!r.ok) return [];
+  const list = Array.isArray(r.data) ? r.data : [];
+  return list.map((rs) => ({
+    id: rs.id,
+    name: rs.name,
+    target: rs.target,
+    enforcement: rs.enforcement,
+  }));
+}
+
+// Rulesets' required_status_checks live under a rule of type
+// "required_status_checks", not on the list-rulesets summary response — a
+// second call per ruleset is required to get the parameter detail.
+export function fetchRulesetRequiredChecks(ownerRepo, rulesetId) {
+  const r = ghApiJson(`repos/${ownerRepo}/rulesets/${rulesetId}`);
+  if (!r.ok) return [];
+  const rules = r.data?.rules ?? [];
+  const rule = rules.find((x) => x.type === 'required_status_checks');
+  const checks = rule?.parameters?.required_status_checks ?? [];
+  return checks.map((c) => c.context).filter(Boolean);
+}
+
+export function checkSecretPresent(ownerRepo, secretName) {
+  const r = ghApiJson(`repos/${ownerRepo}/actions/secrets/${secretName}`);
+  return r.ok;
+}
+
+export function fetchRepoSettings(ownerRepo) {
+  const r = ghApiJson(`repos/${ownerRepo}`);
+  if (!r.ok) return { deleteBranchOnMerge: null, defaultBranch: null };
+  return {
+    deleteBranchOnMerge: r.data?.delete_branch_on_merge ?? false,
+    defaultBranch: r.data?.default_branch ?? null,
+  };
+}
+
+export function checkLabelExists(ownerRepo, labelName) {
+  const r = ghApiJson(`repos/${ownerRepo}/labels/${encodeURIComponent(labelName)}`);
+  return r.ok;
+}
+
+// branches: { main: string, dev: string } — the candidate names to inspect
+// protection for. Caller (SKILL.md's setup wizard, or a re-run reading
+// existingConfig) supplies these; detect.mjs does not guess branch names on
+// its own, keeping it a pure "read what I'm told to look at" function.
+export function detectRepoState(repoPath, { branches = { main: 'main', dev: 'dev' }, releaseCredentialName = null } = {}) {
+  const ownerRepo = resolveOwnerRepo(repoPath);
+  const trackedFiles = listTrackedFiles(repoPath);
+
+  const branchList = git(['branch', '-a', '--format=%(refname:short)'], { cwd: repoPath });
+  const localBranches = branchList.status === 0 ? branchList.stdout.split('\n').filter(Boolean) : [];
+
+  const workflowJobNames = listWorkflowJobNames(repoPath, trackedFiles);
+  const templateFiles = { [TEMPLATE_RELATIVE_PATH]: readTemplateFileHash(repoPath) };
+  const settingsAsCodeArtifact = findSettingsAsCodeArtifact(repoPath, trackedFiles);
+
+  const protection = ownerRepo
+    ? {
+        [branches.main]: fetchBranchProtection(ownerRepo, branches.main),
+        [branches.dev]: fetchBranchProtection(ownerRepo, branches.dev),
+      }
+    : {};
+
+  const rulesetsRaw = ownerRepo ? fetchRulesets(ownerRepo) : [];
+  const rulesets = rulesetsRaw.map((rs) => ({
+    ...rs,
+    requiredChecks: ownerRepo ? fetchRulesetRequiredChecks(ownerRepo, rs.id) : [],
+  }));
+
+  const existingConfig = readExistingConfig(repoPath);
+  const releaseCredentialPresent =
+    ownerRepo && releaseCredentialName ? checkSecretPresent(ownerRepo, releaseCredentialName) : null;
+  const repoSettings = ownerRepo ? fetchRepoSettings(ownerRepo) : { deleteBranchOnMerge: null, defaultBranch: null };
+  const releasePendingLabelExists = ownerRepo ? checkLabelExists(ownerRepo, 'release-pending') : null;
+
+  const stateHash = sha256(
+    JSON.stringify({
+      branches: localBranches.sort(),
+      protectionMain: protection[branches.main]?.requiredChecks ?? null,
+      protectionDev: protection[branches.dev]?.requiredChecks ?? null,
+      rulesetIds: rulesets.map((r) => r.id).sort(),
+      workflowJobNames,
+      deleteBranchOnMerge: repoSettings.deleteBranchOnMerge,
+      releasePendingLabelExists,
+    })
+  );
+
+  return {
+    ownerRepo,
+    branches: { configured: branches, local: localBranches },
+    workflows: { jobNames: workflowJobNames },
+    templateFiles,
+    protection,
+    rulesets,
+    settingsAsCodeArtifact,
+    existingConfig,
+    releaseCredentialPresent,
+    repoSettings,
+    releasePendingLabelExists,
+    stateHash,
+  };
+}
+
+// Three-way protectionOwner classification (see design, "Rulesets vs. an
+// existing settings-as-code source of truth"). Returns:
+//   "external"  — a settings-as-code artifact was found; that mechanism
+//                 owns protection, shipflow must not install a competing one
+//   "shipflow"  — no protection exists at all; shipflow becomes the owner
+//   "ambiguous" — protection exists but no artifact was found (e.g.
+//                 hand-configured via the UI) — caller MUST prompt the user
+//                 rather than silently pick either value (this is the
+//                 round-2 false-positive fix: silently defaulting here left
+//                 protection un-audited AND un-managed by anyone)
+export function classifyProtectionOwner(repoState) {
+  const { settingsAsCodeArtifact, protection } = repoState;
+  if (settingsAsCodeArtifact) return 'external';
+
+  const hasProtection = Object.values(protection).some(
+    (p) => p && (p.requiredChecks?.length > 0 || p.raw)
+  );
+  if (!hasProtection) return 'shipflow';
+  return 'ambiguous';
+}

package/lib/gh.mjs

@@ -0,0 +1,40 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+
+// argv-style invocation; no shell, so user-supplied args cannot inject.
+// Returns { status, stdout, stderr } so callers can distinguish failure modes
+// (e.g. a 404 from gh vs. a network error) instead of collapsing to a boolean.
+export function spawnArgs(cmd, args, opts = {}) {
+  try {
+    const r = spawnSync(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', ...opts });
+    return {
+      status: r.status ?? 1,
+      stdout: (r.stdout || '').trim(),
+      stderr: (r.stderr || '').trim(),
+    };
+  } catch (e) {
+    return { status: 1, stdout: '', stderr: String((e && e.message) || e) };
+  }
+}
+
+export function ghApi(path, args = []) {
+  return spawnArgs('gh', ['api', path, ...args]);
+}
+
+export function ghApiJson(path, args = []) {
+  const r = ghApi(path, args);
+  if (r.status !== 0) return { ok: false, status: r.status, stderr: r.stderr };
+  try {
+    return { ok: true, data: JSON.parse(r.stdout) };
+  } catch (e) {
+    return { ok: false, status: r.status, stderr: `unparseable JSON: ${e.message}` };
+  }
+}
+
+export function git(args, opts = {}) {
+  return spawnArgs('git', args, opts);
+}
+
+export function sha256(content) {
+  return createHash('sha256').update(content, 'utf8').digest('hex');
+}

package/lib/plan.mjs

@@ -0,0 +1,112 @@
+import { renderTemplate, mergeMethodToFlag } from './render.mjs';
+import { sha256 } from './gh.mjs';
+
+const TEMPLATE_PATH = '.github/workflows/dev-to-main-automerge.yml';
+
+// Pure function — no I/O, no gh/git calls. Diffs repoState (what detect.mjs
+// observed) against config (what the user wants) into a Plan the caller
+// shows to the user before any mutation happens.
+export function computePlan(repoState, config, templateSource) {
+  const creates = [];
+  const updates = [];
+  const noops = [];
+
+  // 1. delete_branch_on_merge repo setting
+  const wantDeleteOnMerge = config.branchCleanup?.deleteOnMerge ?? true;
+  const haveDeleteOnMerge = repoState.repoSettings?.deleteBranchOnMerge;
+  if (haveDeleteOnMerge === wantDeleteOnMerge) {
+    noops.push({ id: 'delete-branch-on-merge', description: 'delete_branch_on_merge already set correctly' });
+  } else {
+    updates.push({
+      id: 'delete-branch-on-merge',
+      description: `set delete_branch_on_merge to ${wantDeleteOnMerge}`,
+      desired: wantDeleteOnMerge,
+    });
+  }
+
+  // 2. deletion-protecting ruleset — only shipflow's job when it owns protection.
+  // Coarse check (v1 scope): whether *any* ruleset exists at all, not whether
+  // it specifically restricts deletion on the configured branches — apply.mjs
+  // re-checks live state immediately before creating (idempotency guarantee),
+  // so an imprecise plan preview here cannot cause a wrong mutation, only a
+  // possibly-stale preview label.
+  if (config.protectionOwner === 'shipflow') {
+    if ((repoState.rulesets ?? []).length > 0) {
+      noops.push({ id: 'deletion-ruleset', description: 'a ruleset already exists (coarse check — see plan.mjs comment)' });
+    } else {
+      creates.push({ id: 'deletion-ruleset', description: `create a ruleset protecting ${config.branches.dev}/${config.branches.main} from deletion` });
+    }
+  } else {
+    noops.push({ id: 'deletion-ruleset', description: `protectionOwner is "${config.protectionOwner}" — deferring to existing mechanism, shipflow installs nothing` });
+  }
+
+  // 3. dev-to-main-automerge.yml — content-hash diff against a fresh render,
+  // with hand-edit detection against the last hash shipflow itself recorded.
+  const templateEntry = computeTemplatePlanEntry(repoState, config, templateSource);
+  if (templateEntry.kind === 'noop') noops.push(templateEntry);
+  else if (templateEntry.kind === 'create') creates.push(templateEntry);
+  else updates.push(templateEntry);
+
+  // 4. release-pending label — unconditional across every release.mode
+  // (round-6 fix: the labeling job in the template above ships regardless
+  // of mode, so the label must exist regardless of mode too).
+  if (repoState.releasePendingLabelExists) {
+    noops.push({ id: 'release-pending-label', description: 'release-pending label already exists' });
+  } else {
+    creates.push({ id: 'release-pending-label', description: 'create the release-pending label' });
+  }
+
+  // liveRequiredChecks: union of classic branch-protection required checks
+  // (on the configured main branch) and every fetched ruleset's required
+  // checks. v1 scope note: rulesets are unioned without filtering by which
+  // branch they target (no ref-pattern matching implemented yet) — a
+  // documented simplification, not a silent gap.
+  const classicChecks = repoState.protection?.[config.branches.main]?.requiredChecks ?? [];
+  const rulesetChecks = (repoState.rulesets ?? []).flatMap((rs) => rs.requiredChecks ?? []);
+  const liveRequiredChecks = [...new Set([...classicChecks, ...rulesetChecks])].sort();
+
+  return {
+    creates,
+    updates,
+    noops,
+    sourceStateHash: repoState.stateHash,
+    liveRequiredChecks,
+  };
+}
+
+function computeTemplatePlanEntry(repoState, config, templateSource) {
+  const params = {
+    devBranch: config.branches.dev,
+    mainBranch: config.branches.main,
+    mergeFlag: mergeMethodToFlag(config.mergeMethod?.devToMainMethod),
+  };
+  const renderedContent = renderTemplate(templateSource, params);
+  const freshHash = sha256(renderedContent);
+  const onDisk = repoState.templateFiles?.[TEMPLATE_PATH];
+  const lastRenderedHash = config.renderedTemplateHashes?.[TEMPLATE_PATH] ?? null;
+
+  if (!onDisk || !onDisk.exists) {
+    return { id: 'template:' + TEMPLATE_PATH, kind: 'create', path: TEMPLATE_PATH, description: `write ${TEMPLATE_PATH}`, renderedHash: freshHash, content: renderedContent };
+  }
+  if (onDisk.sha256 === freshHash) {
+    return { id: 'template:' + TEMPLATE_PATH, kind: 'noop', path: TEMPLATE_PATH, description: `${TEMPLATE_PATH} already matches config` };
+  }
+  if (onDisk.sha256 === lastRenderedHash) {
+    // On-disk content matches what shipflow itself last rendered, but the
+    // config has changed since — a legitimate re-render, not a hand-edit.
+    return { id: 'template:' + TEMPLATE_PATH, kind: 'update', path: TEMPLATE_PATH, description: `re-render ${TEMPLATE_PATH} (config changed)`, renderedHash: freshHash, content: renderedContent, handEditDetected: false };
+  }
+  // On-disk content matches neither the fresh render nor our last recorded
+  // render — someone hand-edited it (or it was never rendered by shipflow).
+  // Flagged, not silently overwritten; apply.mjs blocks this entry unless
+  // the caller passes an explicit force override naming this entry's id.
+  return {
+    id: 'template:' + TEMPLATE_PATH,
+    kind: 'update',
+    path: TEMPLATE_PATH,
+    description: `${TEMPLATE_PATH} was hand-edited — blocked pending --force`,
+    renderedHash: freshHash,
+    content: renderedContent,
+    handEditDetected: true,
+  };
+}

package/lib/render.mjs

@@ -0,0 +1,55 @@
+// Pure template-substitution. No I/O, no gh/git calls — used by both plan.mjs
+// (to compute a content-hash for the "would render" side of the hand-edit
+// diff) and apply.mjs (to actually write the file). Keeping it here, not
+// duplicated between the two, is what makes plan.mjs's hash comparison and
+// apply.mjs's write guaranteed to agree.
+//
+// Required-check names are deliberately NOT a substitution parameter here.
+// Native `gh pr merge --auto` takes no check-name input — GitHub gates the
+// eventual async merge on whatever live branch protection/rulesets mark
+// required, not on anything baked into this workflow file. Baking check
+// names in would be a dead parameter at best and an invitation to
+// reconstruct the bespoke-polling mechanism (rejected — see the design's
+// Fatal #1 discussion) at worst.
+
+const TOKEN_RE = /\{\{(\w+)\}\}/g;
+
+// params: { devBranch, mainBranch, mergeFlag }
+// mergeFlag is one of "--merge" | "--squash" | "--rebase", derived from
+// config.mergeMethod.devToMainMethod by the caller (not this function —
+// mapping method name -> gh flag is a config-schema concern, kept out of
+// the pure-substitution layer so this function has zero knowledge of the
+// config shape, only of the template's token names).
+export function renderTemplate(templateSource, params) {
+  const missing = [];
+  const rendered = templateSource.replace(TOKEN_RE, (_, name) => {
+    const key = TOKEN_TO_PARAM[name];
+    if (!key || !(key in params)) {
+      missing.push(name);
+      return `{{${name}}}`;
+    }
+    return String(params[key]);
+  });
+  if (missing.length > 0) {
+    throw new Error(`renderTemplate: missing param(s) for token(s): ${missing.join(', ')}`);
+  }
+  return rendered;
+}
+
+const TOKEN_TO_PARAM = Object.freeze({
+  DEV_BRANCH: 'devBranch',
+  MAIN_BRANCH: 'mainBranch',
+  MERGE_FLAG: 'mergeFlag',
+});
+
+export function mergeMethodToFlag(devToMainMethod) {
+  switch (devToMainMethod) {
+    case 'squash':
+      return '--squash';
+    case 'rebase':
+      return '--rebase';
+    case 'merge':
+    default:
+      return '--merge';
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@natjswenson/shipflow",
+  "version": "0.2.0",
+  "description": "Scaffold a configurable dev/main branching, auto-merge, branch-cleanup, and release-tagging workflow into any repo",
+  "license": "MIT",
+  "author": "Nate Swenson",
+  "homepage": "https://github.com/natejswenson/shipflow",
+  "repository": { "type": "git", "url": "git+https://github.com/natejswenson/shipflow.git" },
+  "bugs": { "url": "https://github.com/natejswenson/shipflow/issues" },
+  "keywords": ["shipflow", "claude-code", "claude-skill", "git", "branching", "release-automation", "ci-cd"],
+  "type": "module",
+  "bin": { "shipflow": "bin/shipflow.js" },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "skill-invariants.json",
+    "SKILL.md",
+    "CHANGELOG.md",
+    "config.example.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "test": "node --test \"tests/**/*.test.mjs\"",
+    "audit": "npm audit --audit-level=moderate"
+  },
+  "dependencies": {}
+}

package/skill-invariants.json

@@ -0,0 +1,61 @@
+{
+  "comment": "Prose guardrails in SKILL.md that must survive edits. Each pattern is a case-insensitive regex tested against the full SKILL.md text by tests/skill_contract.test.mjs. If you intentionally change one, update it here in the same commit and say why in the PR.",
+  "prose": [
+    {
+      "id": "never-mutates-directly",
+      "pattern": "never mutates repo state directly",
+      "rationale": "The deterministic/nondeterministic split is load-bearing: the agent decides, the CLI does. Losing this line reopens ad-hoc direct gh/git calls from the agent."
+    },
+    {
+      "id": "always-confirm-before-apply",
+      "pattern": "Wait for explicit confirmation before proceeding",
+      "rationale": "A plan must be shown and confirmed before any real apply — this is the safety property the whole design rests on."
+    },
+    {
+      "id": "ambiguous-protection-owner-prompt",
+      "pattern": "Do NOT silently pick either value",
+      "rationale": "The round-2 false-positive fix: ambiguous branch protection must be explicitly disambiguated with the user, never silently defaulted, or protection ends up un-audited and un-managed by anyone."
+    },
+    {
+      "id": "empty-required-checks-refusal",
+      "pattern": "refuses to wire up auto-merge with zero required checks",
+      "rationale": "The fail-open guard: an empty requiredChecks list must never silently enable an unprotected auto-merge."
+    },
+    {
+      "id": "hand-edit-never-silent-force",
+      "pattern": "[Nn]ever silently pass `--force`",
+      "rationale": "A hand-edited template file must always be surfaced and explicitly confirmed per entry, never auto-overridden."
+    },
+    {
+      "id": "toctou-reredetect",
+      "pattern": "re-run the plan step, don't retry the same `--expect-state-hash`",
+      "rationale": "A TOCTOU abort means state drifted — retrying the same stale hash would just abort again or, worse, apply against stale assumptions if the guard were bypassed."
+    },
+    {
+      "id": "auto-mode-refuses",
+      "pattern": "refuses to run.{0,40}against a config with `release\\.mode: \"auto\"`",
+      "rationale": "Auto mode is unimplemented in this version; it must fail loudly, never silently no-op, so a user's config request isn't silently ignored."
+    },
+    {
+      "id": "argv-style-no-shell",
+      "pattern": "argv-style.{0,60}no shell",
+      "rationale": "Command-injection defense: every gh/git invocation must stay argv-style, never a shell string built from user input."
+    },
+    {
+      "id": "config-path-fixed",
+      "pattern": "[Nn]ever write shipflow's config anywhere other than `\\.github/shipflow\\.json`",
+      "rationale": "A committed, repo-specific policy file must live in the target repo's own tree at a fixed, predictable path — never inside the shipped skill package, never at an arbitrary location."
+    },
+    {
+      "id": "first-run-interview-mandatory",
+      "pattern": "even when detected values already look correct",
+      "rationale": "First live end-to-end run (2026-07-14, against natejswenson/1.00s) showed an orchestrating agent can silently skip the confirmation turn when detected values look right. This line makes the interview checkpoint explicit and unskippable, not just implied by 'confirm with the user.'"
+    },
+    {
+      "id": "ci-scaffold-never-overwrites",
+      "pattern": "[Nn]ever silently overwrite an existing workflow file",
+      "rationale": "Agent-driven CI scaffolding (added after 1.00s had no pull_request-triggered CI at all) must never clobber a workflow file that's already there — same confirm-before-write discipline as every other mutation in this skill, applied to a step the CLI itself never touches."
+    }
+  ],
+  "cli_commands_referenced": ["detect", "plan", "apply", "releases", "release-dispatch", "rename-default-branch"]
+}

package/templates/dev-to-main-automerge.yml.tmpl

@@ -0,0 +1,52 @@
+name: auto-merge {{DEV_BRANCH}} to {{MAIN_BRANCH}}
+
+# Rendered by shipflow's apply.mjs from this template. Do not hand-edit
+# without also updating .github/shipflow.json's renderedTemplateHashes entry
+# for this file, or shipflow's next apply will refuse to overwrite it
+# (handEditDetected) until an explicit --force is passed. Commit both files
+# together in the same commit.
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, closed]
+    branches: [{{MAIN_BRANCH}}]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  # Enables native GitHub auto-merge on open/reopen/synchronize — 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' &&
+      github.event.pull_request.head.ref == '{{DEV_BRANCH}}'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Enable auto-merge
+        run: gh pr merge --auto {{MERGE_FLAG}} "${{ github.event.pull_request.number }}"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # Fires once, when the promotion PR actually merges (a separate event from
+  # the job above, which only *enables* auto-merge). Applies a durable
+  # release-pending label so a later, disconnected shipflow invocation can
+  # find this promotion and ask about a release — this repo's actual merge
+  # completion has no live Claude session attached to react to it directly.
+  label-release-pending:
+    if: >-
+      github.event.action == 'closed' &&
+      github.event.pull_request.merged == true &&
+      github.event.pull_request.head.ref == '{{DEV_BRANCH}}'
+    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
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}