@natjswenson/shipflow 0.2.5 → 0.3.0

package/SKILL.md

@@ -7,8 +7,17 @@ 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.
+`npx -y @natjswenson/shipflow@latest <command>` — **always with the explicit
+`@latest` tag, never bare `@natjswenson/shipflow`.** Without a version/tag,
+`npx` prefers an already-resolvable install on `PATH` (e.g. a stale global
+`npm install -g @natjswenson/shipflow` from a prior manual test) over
+fetching the current version from the registry, and does so silently with
+no warning. This isn't hypothetical: it happened in this exact repo — the
+same command with the `@latest` tag omitted silently ran a stale global
+0.2.0 install (missing every fix through 0.2.5, including the Critical
+template-injection fix), while `npx -y @natjswenson/shipflow@latest -v`
+correctly resolved 0.2.5. 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
@@ -30,53 +39,62 @@ user; the CLI is the only thing that *does*.
 
 1. **Detect.** Run:
    ```
-   npx -y @natjswenson/shipflow detect --repo <path> --main main --dev dev
+   npx -y @natjswenson/shipflow@latest 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:
+   (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"`, and now also a `rankedPatterns` array — every pattern's `{id, score, evidence}`, sorted descending by score.
+
+2. **Resolve `workflowPattern` before anything else** — a `github-flow` repo never asks about a `dev` branch name at all, so this has to happen before step 3 below. Classify `rankedPatterns` per these rules: **confident** if the top score is `>= 0.7` AND the gap over the second-place score is `> 0.3`; **greenfield** if the top score is `< 0.4`; **ambiguous** otherwise (the residual case — no separate condition to satisfy).
+   - **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.
+     - `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.
+
+3. **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 4. 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
+     npx -y @natjswenson/shipflow@latest 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.
+4. **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`:**
+5. **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. **Resolve `release.releaseCredential` — never default it to `GITHUB_TOKEN`.** The rendered `dev-to-main-automerge.yml`'s `GH_TOKEN` comes from this secret name. A PR auto-merged under `secrets.GITHUB_TOKEN` completes (once checks pass) attributed to the `github-actions[bot]` identity, and GitHub's loop-prevention rule means that bot-attributed merge's `pull_request: closed` event **never triggers this or any other workflow** — so `label-release-pending` silently never runs, and the entire manual-gate release-ask flow never has anything to find. This was confirmed empirically, not theoretically: an otherwise-identical PR merged by a real, PAT-authenticated actor fired the closed-event trigger within 2 seconds; one completed by `GITHUB_TOKEN`-enabled auto-merge fired no run at all, even after 100+ seconds. Ask the user to create a fine-grained PAT (or GitHub App installation token) scoped to this repo with `contents: write` + `pull-requests: write`, and to store it as a repo secret themselves (e.g. `gh secret set <NAME> --repo <owner>/<repo>`, run in *their own* shell so the token value never passes through the agent or the transcript). Record only the secret's *name* in `release.releaseCredential` — never its value.
+6. **Resolve `release.releaseCredential` — never default it to `GITHUB_TOKEN`.** The rendered auto-merge workflow's `GH_TOKEN` comes from this secret name. A PR auto-merged under `secrets.GITHUB_TOKEN` completes (once checks pass) attributed to the `github-actions[bot]` identity, and GitHub's loop-prevention rule means that bot-attributed merge's `pull_request: closed` event **never triggers this or any other workflow** — so `label-release-pending` silently never runs, and the entire manual-gate release-ask flow never has anything to find. This was confirmed empirically, not theoretically: an otherwise-identical PR merged by a real, PAT-authenticated actor fired the closed-event trigger within 2 seconds; one completed by `GITHUB_TOKEN`-enabled auto-merge fired no run at all, even after 100+ seconds. Ask the user to create a fine-grained PAT (or GitHub App installation token) scoped to this repo with `contents: write` + `pull-requests: write`, and to store it as a repo secret themselves (e.g. `gh secret set <NAME> --repo <owner>/<repo>`, run in *their own* shell so the token value never passes through the agent or the transcript). Record only the secret's *name* in `release.releaseCredential` — never its value.
 
-6. **Present the interview summary and write `.github/shipflow.json`.** Before writing anything, show the user the resolved branch names, `requiredChecks`, `protectionOwner`, and `release.releaseCredential` 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 10 produces one.
+7. **Present the interview summary and write `.github/shipflow.json`.** Before writing anything, show the user the resolved `workflowPattern`, branch names, `requiredChecks`, `protectionOwner`, and `release.releaseCredential` 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(s), once step 11 produces them.
 
-7. **Show the plan.** Run:
+8. **Show the plan.** Run:
    ```
-   npx -y @natjswenson/shipflow plan --repo <path>
+   npx -y @natjswenson/shipflow@latest 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 9).
+   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 10).
 
-8. **Dry-run apply** (optional sanity check, same output shape as the real apply but nothing is mutated):
+9. **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
+   npx -y @natjswenson/shipflow@latest apply --repo <path> --dry-run
    ```
 
-9. **Apply for real**, passing the `stateHash` from step 7'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. **`--expect-state-hash` is mandatory for a real (non-dry-run) apply** — omitting it is a hard CLI refusal, not a silent skip of the check; the only way around it is the explicitly-named `--skip-hash-check` escape hatch, which you should never reach for as a matter of course.
-   ```
-   npx -y @natjswenson/shipflow apply --repo <path> --expect-state-hash <hash-from-step-7>
-   ```
-   If a `handEditDetected` entry was confirmed for override in step 7, pass `--force <entry-id>` (repeatable — one flag per confirmed entry id, never a blanket override) **and** `--force-reason "<short justification>"` — the CLI refuses any `--force` without an accompanying reason, and that reason is echoed back in the apply result for auditability. Write a real justification tied to the user's actual confirmation (e.g. `--force-reason "user confirmed hand-edit override for the branch-rename migration on 2026-07-15"`), never a placeholder string.
+10. **Apply for real**, passing the `stateHash` from step 8'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. **`--expect-state-hash` is mandatory for a real (non-dry-run) apply** — omitting it is a hard CLI refusal, not a silent skip of the check; the only way around it is the explicitly-named `--skip-hash-check` escape hatch, which you should never reach for as a matter of course.
+    ```
+    npx -y @natjswenson/shipflow@latest apply --repo <path> --expect-state-hash <hash-from-step-8>
+    ```
+    If a `handEditDetected` entry was confirmed for override in step 8, pass `--force <entry-id>` (repeatable — one flag per confirmed entry id, never a blanket override) **and** `--force-reason "<short justification>"` — the CLI refuses any `--force` without an accompanying reason, and that reason is echoed back in the apply result for auditability. Write a real justification tied to the user's actual confirmation (e.g. `--force-reason "user confirmed hand-edit override for the branch-rename migration on 2026-07-15"`), never a placeholder string.
 
-10. **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.
+11. **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(s) **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, 7, 8, 9, 10 above, skipping the interview (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). 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.
+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.
 
 ## Check pending releases (`manual-gate` ask-flow)
 
@@ -84,7 +102,7 @@ This is a **separate, later invocation** from the one that ran the promotion's `
 
 1. Run:
    ```
-   npx -y @natjswenson/shipflow releases --repo <path>
+   npx -y @natjswenson/shipflow@latest 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).
 
@@ -92,7 +110,7 @@ This is a **separate, later invocation** from the one that ran the promotion's `
 
 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
+   npx -y @natjswenson/shipflow@latest 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).
 

package/bin/shipflow.js

@@ -15,9 +15,18 @@ import {
   renameDefaultBranch,
 } from '../lib/apply.mjs';
 import { readFileCapped } from '../lib/gh.mjs';
+import { resolvePattern, scoreAll } from '../lib/pattern-registry.mjs';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const TEMPLATE_PATH = join(PACKAGE_ROOT, 'templates', 'dev-to-main-automerge.yml.tmpl');
+
+function buildTemplateSources(config) {
+  const pattern = resolvePattern(config);
+  const sources = {};
+  for (const entry of pattern.templates(config)) {
+    sources[entry.id] = readFileSync(entry.templateSourcePath, 'utf8');
+  }
+  return sources;
+}
 
 function readPackageVersion() {
   const pkg = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'));
@@ -63,7 +72,8 @@ function cmdDetect(args) {
     releaseCredentialName: values['release-credential'] ?? null,
   });
   const protectionOwner = classifyProtectionOwner(repoState);
-  printJson({ ...repoState, protectionOwnerClassification: protectionOwner });
+  const rankedPatterns = scoreAll(repoState);
+  printJson({ ...repoState, protectionOwnerClassification: protectionOwner, rankedPatterns });
 }
 
 function cmdPlan(args) {
@@ -88,10 +98,10 @@ function cmdPlan(args) {
     branches: config.branches,
     releaseCredentialName: config.release?.releaseCredential ?? null,
   });
-  const templateSource = readFileSync(TEMPLATE_PATH, 'utf8');
+  const templateSources = buildTemplateSources(config);
   let plan;
   try {
-    plan = computePlan(repoState, config, templateSource);
+    plan = computePlan(repoState, config, templateSources);
   } catch (e) {
     return fail(`plan: ${e.message}`);
   }
@@ -149,10 +159,10 @@ function cmdApply(args) {
     branches: config.branches,
     releaseCredentialName: config.release?.releaseCredential ?? null,
   });
-  const templateSource = readFileSync(TEMPLATE_PATH, 'utf8');
+  const templateSources = buildTemplateSources(config);
   let plan;
   try {
-    plan = computePlan(repoState, config, templateSource);
+    plan = computePlan(repoState, config, templateSources);
   } catch (e) {
     return fail(`apply: ${e.message}`);
   }

package/lib/apply.mjs

@@ -1,6 +1,7 @@
 import { writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { spawnArgs, ghApiJson } from './gh.mjs';
+import { resolvePattern } from './pattern-registry.mjs';
 
 // applyPlan(plan, opts): opts extends the schematic { dryRun, currentStateHash,
 // force } from the design contract with the execution context (ownerRepo,
@@ -29,6 +30,22 @@ export function classifyRulesetError(stderr) {
   return { tierGated: false, reason: null };
 }
 
+// Pure — no I/O, no gh calls. Exported so it's directly unit-testable without
+// mocking the network layer, matching this file's existing classifyRulesetError
+// pattern. protectedBranchList must come from a FRESH call to the resolved
+// pattern's protectedBranches(config) — never from a stored config field — so
+// this function intentionally takes a plain string array, not a config object,
+// making "read a stale stored value" structurally impossible to do by accident.
+export function buildDeletionRulesetBody(protectedBranchList) {
+  return {
+    name: 'shipflow-branch-deletion-protection',
+    target: 'branch',
+    enforcement: 'active',
+    conditions: { ref_name: { include: protectedBranchList.map((b) => `refs/heads/${b}`), exclude: [] } },
+    rules: [{ type: 'deletion' }],
+  };
+}
+
 export function applyPlan(plan, opts) {
   const { dryRun, currentStateHash, force = [], forceReason = null, ownerRepo, repoPath, config } = opts;
 
@@ -114,15 +131,8 @@ function applyOne(entry, { ownerRepo, repoPath, config }) {
   }
 
   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 protectedBranchList = resolvePattern(config).protectedBranches(config);
+    const body = JSON.stringify(buildDeletionRulesetBody(protectedBranchList));
     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);

package/lib/detect.mjs

@@ -1,8 +1,8 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnArgs, ghApiJson, git, sha256, readFileCapped } from './gh.mjs';
+import { listPatterns } from './pattern-registry.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
@@ -93,8 +93,67 @@ export function listWorkflowJobNames(repoPath, trackedFiles) {
   return [...names].sort();
 }
 
-export function readTemplateFileHash(repoPath) {
-  const full = join(repoPath, TEMPLATE_RELATIVE_PATH);
+const GH_PR_MERGE_AUTO_RE = /gh pr merge --auto/;
+const HEAD_REF_EQ_RE = /head\.ref\s*==/;
+
+// One level finer than listWorkflowJobNames()'s whole-jobs:-section boundary: bounds
+// each INDIVIDUAL job's own line range (its jobNameRe-matching name line down to the
+// next line at that same or lesser indent — the next sibling job, or EOF) so a
+// head.ref == check in one job is never misattributed to a different job's
+// gh pr merge --auto step in the same file.
+export function scanWorkflowShapeSignals(repoPath, trackedFiles) {
+  let restricted = false;
+  let unrestricted = false;
+  for (const f of trackedFiles.filter((f) => /^\.github\/workflows\/.*\.ya?ml$/.test(f))) {
+    const full = join(repoPath, f);
+    if (!existsSync(full)) continue;
+    const lines = readFileCapped(full).split('\n');
+    const jobsLineIdx = lines.findIndex((l) => l.trim() === 'jobs:');
+    if (jobsLineIdx === -1) continue;
+    let i = jobsLineIdx + 1;
+    while (i < lines.length) {
+      // Mirrors listWorkflowJobNames's own dedent-out-of-block termination: a line
+      // that dedents all the way to column 0 ends the WHOLE jobs: section (a
+      // trailing env:/concurrency: block, or EOF), not just the current job — stop
+      // the outer scan entirely rather than treating it as another job candidate.
+      if (lines[i].trim() !== '' && /^\S/.test(lines[i])) break;
+      const nameMatch = lines[i].match(/^\s{2}([\w.-]+):\s*$/);
+      if (!nameMatch) { i++; continue; }
+      const jobStart = i;
+      let jobEnd = lines.length;
+      for (let j = i + 1; j < lines.length; j++) {
+        if (lines[j].trim() === '') continue;
+        if (/^\S/.test(lines[j])) { jobEnd = j; break; }          // dedents to column 0 — end of jobs: section
+        if (lines[j].match(/^\s{2}([\w.-]+):\s*$/)) { jobEnd = j; break; } // next sibling job
+      }
+      const jobBlock = lines.slice(jobStart, jobEnd).join('\n');
+      if (GH_PR_MERGE_AUTO_RE.test(jobBlock)) {
+        if (HEAD_REF_EQ_RE.test(jobBlock)) restricted = true;
+        else unrestricted = true;
+      }
+      i = jobEnd;
+    }
+  }
+  return { hasRestrictedPromotionWorkflow: restricted, hasUnrestrictedAutomergeWorkflow: unrestricted };
+}
+
+export function hasTagsFromMain(repoPath, mainBranch) {
+  const r = git(['tag', '--merged', mainBranch], { cwd: repoPath });
+  return r.status === 0 && r.stdout.trim().length > 0;
+}
+
+export function hasGitflowMarker(repoPath) {
+  if (existsSync(join(repoPath, '.gitflow'))) return true;
+  return git(['config', '--get', 'gitflow.branch.develop'], { cwd: repoPath }).status === 0;
+}
+
+export function listConfiguredRemotes(repoPath) {
+  const r = git(['remote'], { cwd: repoPath });
+  return r.status === 0 ? r.stdout.split('\n').filter(Boolean) : [];
+}
+
+export function readTemplateFileHash(repoPath, targetPath) {
+  const full = join(repoPath, targetPath);
   if (!existsSync(full)) return { exists: false, sha256: null };
   const content = readFileCapped(full);
   return { exists: true, sha256: sha256(content) };
@@ -172,8 +231,18 @@ export function detectRepoState(repoPath, { branches = { main: 'main', dev: 'dev
   const localBranches = branchList.status === 0 ? branchList.stdout.split('\n').filter(Boolean) : [];
 
   const workflowJobNames = listWorkflowJobNames(repoPath, trackedFiles);
-  const templateFiles = { [TEMPLATE_RELATIVE_PATH]: readTemplateFileHash(repoPath) };
+  // Union of every registered pattern's templateTargetPaths — computed unconditionally
+  // with no resolved pattern in hand (there's no config yet on a genuine first run, so
+  // nothing to call resolvePattern(config) with). detect.mjs never imports a
+  // lib/patterns/<id>/index.mjs module directly, only listPatterns() — this is what
+  // keeps "adding a 4th pattern needs no changes to detect.mjs" true in practice.
+  const templateTargetPaths = listPatterns().flatMap((p) => p.templateTargetPaths);
+  const templateFiles = Object.fromEntries(
+    templateTargetPaths.map((path) => [path, readTemplateFileHash(repoPath, path)])
+  );
   const settingsAsCodeArtifact = findSettingsAsCodeArtifact(repoPath, trackedFiles);
+  const { hasRestrictedPromotionWorkflow, hasUnrestrictedAutomergeWorkflow } =
+    scanWorkflowShapeSignals(repoPath, trackedFiles);
 
   const protection = ownerRepo
     ? {
@@ -219,6 +288,11 @@ export function detectRepoState(repoPath, { branches = { main: 'main', dev: 'dev
     repoSettings,
     releasePendingLabelExists,
     stateHash,
+    hasTagsFromMain: hasTagsFromMain(repoPath, branches.main),
+    hasGitflowMarker: hasGitflowMarker(repoPath),
+    configuredRemotes: listConfiguredRemotes(repoPath),
+    hasRestrictedPromotionWorkflow,
+    hasUnrestrictedAutomergeWorkflow,
   };
 }
 

package/lib/pattern-registry.mjs

@@ -0,0 +1,79 @@
+import * as devMainPromotion from './patterns/dev-main-promotion/index.mjs';
+import * as githubFlow from './patterns/github-flow/index.mjs';
+import * as gitflow from './patterns/gitflow/index.mjs';
+
+const PATTERNS = [devMainPromotion, githubFlow, gitflow];
+
+export function listPatterns() {
+  return PATTERNS.map((p) => ({ id: p.id, templateTargetPaths: p.templateTargetPaths }));
+}
+
+export function resolvePattern(config) {
+  const wanted = config?.workflowPattern ?? 'dev-main-promotion';
+  const found = PATTERNS.find((p) => p.id === wanted);
+  if (!found) throw new Error(`resolvePattern: unknown workflowPattern "${wanted}"`);
+  return found;
+}
+
+// Strips a leading '<remote>/' ONLY when it exactly matches one of repoState's
+// configuredRemotes — never a blind "strip to first slash," which would corrupt a
+// purely local release/1.2.0 into 1.2.0. configuredRemotes is populated by
+// detect.mjs (Task 7) via `git remote` — this function takes the already-collected
+// repoState, no git calls of its own, keeping it a pure, easily-testable function.
+function normalizeBranchName(name, remotes) {
+  for (const remote of remotes) {
+    if (name.startsWith(`${remote}/`)) return name.slice(remote.length + 1);
+  }
+  return name;
+}
+
+const DEV_BRANCH_RE = /^(dev|develop|staging)$/;
+const RELEASE_HOTFIX_RE = /^(release|hotfix)\//;
+
+// Computes the 6 shared boolean signals every pattern's detect() consumes. Pure
+// given its single repoState input (matches the contract's scoreAll(repoState)
+// signature — repoPath/git calls stay confined to detect.mjs's collection step,
+// Task 7 — repoState must already carry the raw material (branches,
+// configuredRemotes, tags, .gitflow marker, workflow-shape scan) that step gathers.
+export function computeDetectionSignals(repoState) {
+  const remotes = repoState.configuredRemotes ?? [];
+  const normalized = (repoState.branches?.local ?? []).map((b) => normalizeBranchName(b, remotes));
+  return {
+    hasDevBranch: normalized.some((b) => DEV_BRANCH_RE.test(b)),
+    hasReleaseOrHotfixBranch: normalized.some((b) => RELEASE_HOTFIX_RE.test(b)),
+    hasGitflowMarker: repoState.hasGitflowMarker ?? false,
+    hasRestrictedPromotionWorkflow: repoState.hasRestrictedPromotionWorkflow ?? false,
+    hasUnrestrictedAutomergeWorkflow: repoState.hasUnrestrictedAutomergeWorkflow ?? false,
+    hasTagsFromMain: repoState.hasTagsFromMain ?? false,
+  };
+}
+
+function scoreFromSignals(signals) {
+  return PATTERNS.map((p) => ({ id: p.id, ...p.detect(signals) })).sort((a, b) => b.score - a.score);
+}
+
+export function scoreAll(repoState) {
+  return scoreFromSignals(computeDetectionSignals(repoState));
+}
+// Test-only seam: exercise scoring against a hand-built DetectionSignals object
+// directly, bypassing computeDetectionSignals/repoState entirely. Not part of the
+// public CLI-facing API — the 5 worked-example tests above use this seam because
+// they're testing the SCORING rules in isolation; the two normalization tests
+// above instead call computeDetectionSignals(repoState) directly, since THAT is
+// what those tests are about. Attaching a property to an exported `function`
+// declaration works fine in ESM (the export binding is the function object
+// itself, and function objects are ordinary mutable objects) — this is not the
+// same footgun as trying to reassign a `const`-exported binding from outside the
+// module, which ESM does forbid.
+scoreAll.__scoreFromSignals = scoreFromSignals;
+
+// Confident: top >= 0.7 AND (top - second) > 0.3. Greenfield: top < 0.4. Else
+// Ambiguous — the residual/else branch, no separate condition to satisfy, which is
+// what makes this exhaustive by construction (see design doc's Autodetection section).
+export function classify(ranked) {
+  const [top, second] = ranked;
+  const secondScore = second?.score ?? 0;
+  if (top.score >= 0.7 && top.score - secondScore > 0.3) return 'confident';
+  if (top.score < 0.4) return 'greenfield';
+  return 'ambiguous';
+}

package/lib/patterns/dev-main-promotion/index.mjs

@@ -0,0 +1,49 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mergeMethodToFlag } from '../../render.mjs';
+
+const PATTERN_DIR = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_SOURCE_PATH = join(
+  PATTERN_DIR, '..', '..', '..', 'templates', 'dev-main-promotion', 'dev-to-main-automerge.yml.tmpl'
+);
+const TARGET_PATH = '.github/workflows/dev-to-main-automerge.yml';
+
+export const id = 'dev-main-promotion';
+export const templateTargetPaths = [TARGET_PATH];
+
+export function protectedBranches(config) {
+  return [config.branches.dev, config.branches.main];
+}
+
+export function templates(config) {
+  return [{
+    id: 'dev-to-main-automerge',
+    targetPath: TARGET_PATH,
+    templateSourcePath: TEMPLATE_SOURCE_PATH,
+    params: {
+      devBranch: config.branches.dev,
+      mainBranch: config.branches.main,
+      mergeFlag: mergeMethodToFlag(config.mergeMethod?.devToMainMethod),
+      releaseCredentialSecret: config.release?.releaseCredential ?? 'GITHUB_TOKEN',
+    },
+  }];
+}
+
+// signals: precomputed DetectionSignals (see pattern-registry.mjs's computeDetectionSignals).
+export function detect(signals) {
+  const evidence = [];
+  let score = 0;
+  if (signals.hasDevBranch && !signals.hasReleaseOrHotfixBranch) {
+    score += 0.5;
+    evidence.push('a dev/develop/staging branch exists with no release/*  or hotfix/*  branches present');
+  }
+  if (signals.hasRestrictedPromotionWorkflow) {
+    score += 0.5;
+    evidence.push('an existing workflow restricts auto-merge-to-main to one specific branch');
+  }
+  return { score, evidence };
+}
+
+export function planEntries(_repoState, _config) {
+  return [];
+}

package/lib/patterns/gitflow/index.mjs

@@ -0,0 +1,55 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mergeMethodToFlag } from '../../render.mjs';
+
+const PATTERN_DIR = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = join(PATTERN_DIR, '..', '..', '..', 'templates', 'gitflow');
+
+export const id = 'gitflow';
+export const templateTargetPaths = [
+  '.github/workflows/release-automerge.yml',
+  '.github/workflows/hotfix-automerge.yml',
+  '.github/workflows/hotfix-merge-back.yml',
+  '.github/workflows/release-merge-back.yml',
+];
+
+// release/*  and hotfix/*  are deliberately excluded — transient, cleaned up
+// post-merge like any feature branch under every pattern.
+export function protectedBranches(config) {
+  return [config.branches.dev, config.branches.main];
+}
+
+export function templates(config) {
+  const releasePrefix = config.patternConfig?.gitflow?.releaseBranchPrefix ?? 'release/';
+  const hotfixPrefix = config.patternConfig?.gitflow?.hotfixBranchPrefix ?? 'hotfix/';
+  const baseParams = {
+    devBranch: config.branches.dev,
+    mainBranch: config.branches.main,
+    mergeFlag: mergeMethodToFlag(config.mergeMethod?.devToMainMethod),
+    releaseCredentialSecret: config.release?.releaseCredential ?? 'GITHUB_TOKEN',
+    releaseBranchPrefix: releasePrefix,
+    hotfixBranchPrefix: hotfixPrefix,
+  };
+  return [
+    { id: 'release-automerge', targetPath: '.github/workflows/release-automerge.yml',
+      templateSourcePath: join(TEMPLATE_DIR, 'release-automerge.yml.tmpl'), params: baseParams },
+    { id: 'hotfix-automerge', targetPath: '.github/workflows/hotfix-automerge.yml',
+      templateSourcePath: join(TEMPLATE_DIR, 'hotfix-automerge.yml.tmpl'), params: baseParams },
+    { id: 'hotfix-merge-back', targetPath: '.github/workflows/hotfix-merge-back.yml',
+      templateSourcePath: join(TEMPLATE_DIR, 'hotfix-merge-back.yml.tmpl'), params: baseParams },
+    { id: 'release-merge-back', targetPath: '.github/workflows/release-merge-back.yml',
+      templateSourcePath: join(TEMPLATE_DIR, 'release-merge-back.yml.tmpl'), params: baseParams },
+  ];
+}
+
+export function detect(signals) {
+  const evidence = [];
+  let score = 0;
+  if (signals.hasDevBranch) { score += 0.5; evidence.push('a develop/dev/staging branch exists'); }
+  if (signals.hasReleaseOrHotfixBranch) { score += 0.5; evidence.push('a release/*  or hotfix/*  branch exists'); }
+  // hasGitflowMarker is a best-effort bonus signal only — carries no numeric
+  // weight in v1 (see design doc's Autodetection section).
+  return { score, evidence };
+}
+
+export function planEntries() { return []; }

package/lib/patterns/github-flow/index.mjs

@@ -0,0 +1,43 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mergeMethodToFlag } from '../../render.mjs';
+
+const PATTERN_DIR = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_SOURCE_PATH = join(PATTERN_DIR, '..', '..', '..', 'templates', 'github-flow', 'main-automerge.yml.tmpl');
+const TARGET_PATH = '.github/workflows/main-automerge.yml';
+
+export const id = 'github-flow';
+export const templateTargetPaths = [TARGET_PATH];
+
+export function protectedBranches(config) {
+  return [config.branches.main];
+}
+
+export function templates(config) {
+  return [{
+    id: 'main-automerge',
+    targetPath: TARGET_PATH,
+    templateSourcePath: TEMPLATE_SOURCE_PATH,
+    params: {
+      mainBranch: config.branches.main,
+      mergeFlag: mergeMethodToFlag(config.mergeMethod?.devToMainMethod),
+      releaseCredentialSecret: config.release?.releaseCredential ?? 'GITHUB_TOKEN',
+    },
+  }];
+}
+
+export function detect(signals) {
+  const evidence = [];
+  let score = 0;
+  if (signals.hasUnrestrictedAutomergeWorkflow || signals.hasTagsFromMain) {
+    score += 0.5;
+    evidence.push('an unrestricted auto-merge-to-main workflow exists, or tags are reachable from main');
+  }
+  if (!signals.hasDevBranch && !signals.hasReleaseOrHotfixBranch) {
+    score += 0.3;
+    evidence.push('no dev/develop/staging branch and no release/*  or hotfix/*  branches exist');
+  }
+  return { score, evidence };
+}
+
+export function planEntries() { return []; }

package/lib/plan.mjs

@@ -1,17 +1,18 @@
-import { renderTemplate, mergeMethodToFlag } from './render.mjs';
+import { resolvePattern } from './pattern-registry.mjs';
+import { renderTemplate } 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) {
+export function computePlan(repoState, config, templateSources) {
+  const pattern = resolvePattern(config);
+  const protectedBranchList = pattern.protectedBranches(config);
   const creates = [];
   const updates = [];
   const noops = [];
 
-  // 1. delete_branch_on_merge repo setting
+  // 1. delete_branch_on_merge — unchanged, repo-wide boolean, no branch names involved.
   const wantDeleteOnMerge = config.branchCleanup?.deleteOnMerge ?? true;
   const haveDeleteOnMerge = repoState.repoSettings?.deleteBranchOnMerge;
   if (haveDeleteOnMerge === wantDeleteOnMerge) {
@@ -24,38 +25,48 @@ export function computePlan(repoState, config, templateSource) {
     });
   }
 
-  // 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.
+  // 2. deletion-ruleset — protects protectedBranchList, not a hardcoded [dev, main].
+  // Description strings below are copied VERBATIM from the pre-existing (single-pattern)
+  // plan.mjs, not rephrased — this repo's own live .github/shipflow.json has
+  // protectionOwner: "external", so the dogfood smoke test
+  // (`node bin/shipflow.js plan --repo .../claude-skills`) exercises this exact else-branch
+  // and must reproduce byte-identical plan-entry text, not just equivalent behavior.
   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` });
+      creates.push({ id: 'deletion-ruleset', description: `create a ruleset protecting ${protectedBranchList.join('/')} 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);
+  // 3. per-pattern templates — generalized from one hardcoded entry to N.
+  for (const entry of pattern.templates(config)) {
+    const templateSource = templateSources[entry.id];
+    if (templateSource === undefined) {
+      throw new Error(`computePlan: no templateSources entry for template id "${entry.id}"`);
+    }
+    const planEntry = computeTemplatePlanEntry(repoState, config, entry, templateSource);
+    if (planEntry.kind === 'noop') noops.push(planEntry);
+    else if (planEntry.kind === 'create') creates.push(planEntry);
+    else updates.push(planEntry);
+  }
 
-  // 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).
+  // 4. release-pending label — unconditional across every release.mode and pattern.
   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' });
   }
 
+  // 5. pattern-specific entries beyond the 4 common ones above (empty for all 3 v1 patterns).
+  for (const entry of pattern.planEntries(repoState, config)) {
+    if (entry.kind === 'noop') noops.push(entry);
+    else if (entry.kind === 'create') creates.push(entry);
+    else updates.push(entry);
+  }
+
   // 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
@@ -65,51 +76,46 @@ export function computePlan(repoState, config, templateSource) {
   const rulesetChecks = (repoState.rulesets ?? []).flatMap((rs) => rs.requiredChecks ?? []);
   const liveRequiredChecks = [...new Set([...classicChecks, ...rulesetChecks])].sort();
 
-  return {
-    creates,
-    updates,
-    noops,
-    sourceStateHash: repoState.stateHash,
-    liveRequiredChecks,
-  };
+  return { creates, updates, noops, sourceStateHash: repoState.stateHash, liveRequiredChecks, protectedBranches: protectedBranchList };
 }
 
-function computeTemplatePlanEntry(repoState, config, templateSource) {
-  const params = {
-    devBranch: config.branches.dev,
-    mainBranch: config.branches.main,
-    mergeFlag: mergeMethodToFlag(config.mergeMethod?.devToMainMethod),
-    // Must be a real PAT/App-installation-token secret name, not
-    // "GITHUB_TOKEN" — see the template's header comment for why a
-    // GITHUB_TOKEN-attributed auto-merge never fires the closed-event
-    // label job at all.
-    releaseCredentialSecret: config.release?.releaseCredential ?? 'GITHUB_TOKEN',
-  };
-  const renderedContent = renderTemplate(templateSource, params);
+// entry is one {id, targetPath, templateSourcePath, params} item from
+// pattern.templates(config); templateSource is that entry's already-read-off-disk
+// content (looked up from the caller-supplied templateSources map above).
+//
+// IMPORTANT: the returned plan entry's `id` field is NOT entry.id (the pattern
+// module's own template identifier, e.g. 'release-automerge') — it MUST stay the
+// pre-existing 'template:' + targetPath convention, because apply.mjs's dispatch
+// (`entry.id.startsWith('template:')`) and the empty-required-checks refusal both
+// key off that exact prefix today. Reusing the pattern module's own template id
+// verbatim here would silently break both of those existing mechanisms.
+function computeTemplatePlanEntry(repoState, config, entry, templateSource) {
+  const planId = 'template:' + entry.targetPath;
+  const renderedContent = renderTemplate(templateSource, entry.params);
   const freshHash = sha256(renderedContent);
-  const onDisk = repoState.templateFiles?.[TEMPLATE_PATH];
-  const lastRenderedHash = config.renderedTemplateHashes?.[TEMPLATE_PATH] ?? null;
+  const onDisk = repoState.templateFiles?.[entry.targetPath];
+  const lastRenderedHash = config.renderedTemplateHashes?.[entry.targetPath] ?? null;
 
   if (!onDisk || !onDisk.exists) {
-    return { id: 'template:' + TEMPLATE_PATH, kind: 'create', path: TEMPLATE_PATH, description: `write ${TEMPLATE_PATH}`, renderedHash: freshHash, content: renderedContent };
+    return { id: planId, kind: 'create', path: entry.targetPath, description: `write ${entry.targetPath}`, renderedHash: freshHash, content: renderedContent };
   }
   if (onDisk.sha256 === freshHash) {
-    return { id: 'template:' + TEMPLATE_PATH, kind: 'noop', path: TEMPLATE_PATH, description: `${TEMPLATE_PATH} already matches config` };
+    return { id: planId, kind: 'noop', path: entry.targetPath, description: `${entry.targetPath} 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 };
+    return { id: planId, kind: 'update', path: entry.targetPath, description: `re-render ${entry.targetPath} (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,
+    id: planId,
     kind: 'update',
-    path: TEMPLATE_PATH,
-    description: `${TEMPLATE_PATH} was hand-edited — blocked pending --force`,
+    path: entry.targetPath,
+    description: `${entry.targetPath} was hand-edited — blocked pending --force`,
     renderedHash: freshHash,
     content: renderedContent,
     handEditDetected: true,

package/lib/render.mjs

@@ -35,11 +35,28 @@ const UNSAFE_YAML_STRING_RE = /['\r\n]/;
 // with a digit (case-insensitivity aside, this is the full safe charset).
 const SAFE_SECRET_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
+// Prefix tokens for gitflow's release/*  and hotfix/*  head.ref match guards.
+// These do NOT reuse DEV_BRANCH/MAIN_BRANCH's bare UNSAFE_YAML_STRING_RE check
+// unmodified: those two substitute into an == equality comparison, where an
+// empty string is just a branch name that will never equal anything and so
+// fails CLOSED. These two instead substitute into
+// startsWith(head.ref, '{{...}}') — and EVERY string starts with the empty
+// string, so an empty prefix fails OPEN, collapsing gitflow's release/hotfix-
+// scoped auto-merge into an unrestricted one matching any PR into main. That
+// is the same severity class as the quote-injection Critical finding this
+// module was already hardened against, and it's trivially reachable non-
+// maliciously (a user who wants "no prefix restriction" would naturally try
+// ""). Reject a non-empty-string requirement in addition to the quote/newline
+// check.
+const NON_EMPTY_SAFE_STRING_RE = (v) => v.length > 0 && !UNSAFE_YAML_STRING_RE.test(v);
+
 const TOKEN_VALIDATORS = Object.freeze({
   DEV_BRANCH: (v) => !UNSAFE_YAML_STRING_RE.test(v),
   MAIN_BRANCH: (v) => !UNSAFE_YAML_STRING_RE.test(v),
   MERGE_FLAG: () => true, // closed enum from mergeMethodToFlag — never attacker-shaped
   RELEASE_CREDENTIAL_SECRET: (v) => SAFE_SECRET_NAME_RE.test(v),
+  RELEASE_BRANCH_PREFIX: NON_EMPTY_SAFE_STRING_RE,
+  HOTFIX_BRANCH_PREFIX: NON_EMPTY_SAFE_STRING_RE,
 });
 
 // params: { devBranch, mainBranch, mergeFlag, releaseCredentialSecret }
@@ -53,7 +70,14 @@ export function renderTemplate(templateSource, params) {
   const unsafe = [];
   const rendered = templateSource.replace(TOKEN_RE, (_, name) => {
     const key = TOKEN_TO_PARAM[name];
-    if (!key || !(key in params)) {
+    // A present-but-undefined param counts as MISSING, not as the string
+    // "undefined". `key in params` alone was true for it, so String(undefined)
+    // flowed through as a real value and passed the safety regexes — a config
+    // with no `branches.main` rendered `branches: [undefined]` and
+    // `name: auto-merge dev to undefined`, installing a workflow that could
+    // never fire, with no error at apply time. Found by the rendered-workflow
+    // baseline (tests/baseline.test.mjs) on its first run.
+    if (!key || params[key] === undefined || params[key] === null) {
       missing.push(name);
       return `{{${name}}}`;
     }
@@ -69,7 +93,7 @@ export function renderTemplate(templateSource, params) {
   }
   if (unsafe.length > 0) {
     throw new Error(
-      `renderTemplate: unsafe value for token(s): ${unsafe.join(', ')} — branch names must not contain a quote or newline, and the release-credential secret name must match GitHub's secret-naming rules (letters/digits/underscore, not starting with a digit)`
+      `renderTemplate: unsafe value for token(s): ${unsafe.join(', ')} — branch names and release/hotfix prefixes must be non-empty and must not contain a quote or newline, and the release-credential secret name must match GitHub's secret-naming rules (letters/digits/underscore, not starting with a digit)`
     );
   }
   return rendered;
@@ -80,8 +104,24 @@ const TOKEN_TO_PARAM = Object.freeze({
   MAIN_BRANCH: 'mainBranch',
   MERGE_FLAG: 'mergeFlag',
   RELEASE_CREDENTIAL_SECRET: 'releaseCredentialSecret',
+  RELEASE_BRANCH_PREFIX: 'releaseBranchPrefix',
+  HOTFIX_BRANCH_PREFIX: 'hotfixBranchPrefix',
 });
 
+// INV-MP-12: every TOKEN_TO_PARAM key must have a matching TOKEN_VALIDATORS key, or a
+// substituted value could reach a template with zero validation (the exact class of
+// gap a 2026-07-15 Siege audit found and fixed). Called once at module load against
+// the real exported objects; also independently callable so a unit test can assert
+// the logic itself (not just today's two maps happening to agree) by passing in
+// deliberately-mismatched local fixture objects.
+export function assertTokenValidatorsComplete(tokenToParam, tokenValidators) {
+  const missing = Object.keys(tokenToParam).filter((key) => !(key in tokenValidators));
+  if (missing.length > 0) {
+    throw new Error(`assertTokenValidatorsComplete: TOKEN_VALIDATORS missing entr(y/ies) for: ${missing.join(', ')}`);
+  }
+}
+assertTokenValidatorsComplete(TOKEN_TO_PARAM, TOKEN_VALIDATORS);
+
 export function mergeMethodToFlag(devToMainMethod) {
   switch (devToMainMethod) {
     case 'squash':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natjswenson/shipflow",
-  "version": "0.2.5",
+  "version": "0.3.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

@@ -75,7 +75,31 @@
       "id": "force-requires-reason",
       "pattern": "refuses any `--force` without an accompanying reason",
       "rationale": "Found by a Siege security audit (2026-07-15, SIEGE-2026-07-15-002): --force had zero code-level friction beyond the flag itself, so a confused or prompt-injected agent could force through an unprotected merge or a tampered template with no audit trail. --force now requires --force-reason, echoed back in the apply result."
+    },
+    {
+      "id": "npx-must-pin-latest",
+      "pattern": "always with the explicit\\s+`@latest` tag, never bare",
+      "rationale": "Self-discovered 2026-07-15 during PAT-wiring dogfood on claude-skills itself: a bare `npx -y @natjswenson/shipflow <command>` silently resolved a stale global install (0.2.0) instead of fetching the current version from the registry, with no warning — meaning every fix through 0.2.5 (including the Critical template-injection fix) was silently skipped. Every CLI invocation in this file must pin @latest."
+    },
+    {
+      "id": "ambiguous-pattern-no-silent-pick",
+      "pattern": "present all 3 (templates|patterns).{0,60}ask the user to choose",
+      "rationale": "Ambiguous/greenfield autodetection must never silently pick a workflow pattern — mirrors the existing protectionOwner disambiguation precedent (ambiguous-protection-owner-prompt)."
     }
   ],
-  "cli_commands_referenced": ["detect", "plan", "apply", "releases", "release-dispatch", "rename-default-branch"]
+  "cli_commands_referenced": ["detect", "plan", "apply", "releases", "release-dispatch", "rename-default-branch"],
+  "_baseline_comment": "Baseline eval sets: deterministic, offline, $0 checks pinned against artifacts from real local runs. These gate `ci / shipflow` alongside the unit tests. Every entry names the test that enforces it so tools/lint_baseline.py can verify the declaration is not aspirational.",
+  "baseline": [
+    {
+      "id": "dogfood-rendered-workflow-golden",
+      "kind": "golden",
+      "test": "tests/baseline.test.mjs",
+      "fixtures": [
+        "evals/baseline/dogfood-shipflow.json",
+        "evals/baseline/dogfood-dev-to-main-automerge.yml"
+      ],
+      "update_command": "node evals/baseline/update.mjs",
+      "rationale": "This monorepo dogfoods shipflow on itself, so .github/shipflow.json and the workflow rendered from it are a genuine input/output pair from a real `apply` run, and that config's renderedTemplateHashes is the receipt shipflow wrote at the time. The baseline re-runs config -> params -> render and asserts byte equality against the frozen golden, that the golden's sha256 still equals the recorded receipt, and that the frozen golden still equals the repo's live committed workflow (so the fixture cannot quietly go stale). Byte-exactness is correct here and nowhere else in the baseline suite: for a workflow file, one changed character is a behavior change to the repo's merge automation. The paired negative assertions (quote injection rejected, missing param throws, merge method actually reaches the output) stop the golden from passing while the validators rot -- the missing-param one found a real bug on its first run: a present-but-undefined param rendered the literal string 'undefined' into `branches: [...]`, installing a workflow that could never fire."
+    }
+  ]
 }

package/templates/gitflow/hotfix-automerge.yml.tmpl

@@ -0,0 +1,65 @@
+name: auto-merge hotfix/*  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.
+#
+# GH_TOKEN uses config.release.releaseCredential, NOT a hardcoded
+# secrets.GITHUB_TOKEN, because of GitHub's loop-prevention rule: a PR
+# auto-merged via `gh pr merge --auto` run under the default GITHUB_TOKEN
+# completes (later, asynchronously, once checks pass) attributed to the
+# github-actions[bot] identity — and a `pull_request: closed` event
+# resulting from that bot-attributed merge does NOT trigger this or any
+# other workflow's `on: pull_request` handlers. Confirmed empirically:
+# an identical PR merged by a real, PAT-authenticated actor fired the
+# closed-event trigger immediately; one completed by GITHUB_TOKEN-enabled
+# auto-merge fired no run at all. releaseCredential must therefore name a
+# real PAT/App-installation-token secret (not GITHUB_TOKEN) for
+# label-release-pending to ever actually run.
+
+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' &&
+      startsWith(github.event.pull_request.head.ref, '{{HOTFIX_BRANCH_PREFIX}}')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Enable auto-merge
+        run: gh pr merge --auto {{MERGE_FLAG}} "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}"
+        env:
+          GH_TOKEN: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}
+
+  # Fires once, when the hotfix 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 — the 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 &&
+      startsWith(github.event.pull_request.head.ref, '{{HOTFIX_BRANCH_PREFIX}}')
+    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 }}"
+        env:
+          GH_TOKEN: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}

package/templates/gitflow/hotfix-merge-back.yml.tmpl

@@ -0,0 +1,54 @@
+name: merge {{MAIN_BRANCH}} back to {{DEV_BRANCH}} after a hotfix
+
+# Rendered by shipflow's apply.mjs. See dev-to-main-automerge.yml.tmpl's header
+# comment for the general hand-edit/renderedTemplateHashes discipline — same rules
+# apply here.
+#
+# GitFlow's hotfix branches merge into BOTH main and develop — this is the
+# defining semantic of a hotfix, not an optional convention (confirmed via
+# research: git-flow CLI's own `hotfix finish` command does both merges
+# atomically). This job runs the develop-side merge automatically once the
+# main-side merge (hotfix-automerge.yml) lands.
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [{{MAIN_BRANCH}}]
+
+permissions:
+  contents: write
+
+jobs:
+  merge-back-to-dev:
+    if: >-
+      github.event.pull_request.merged == true &&
+      startsWith(github.event.pull_request.head.ref, '{{HOTFIX_BRANCH_PREFIX}}')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}
+      - name: Attempt a clean merge of {{MAIN_BRANCH}} into {{DEV_BRANCH}}
+        id: merge
+        continue-on-error: true
+        run: |
+          git config user.name "shipflow"
+          git config user.email "shipflow@users.noreply.github.com"
+          git checkout {{DEV_BRANCH}}
+          git merge origin/{{MAIN_BRANCH}} --no-edit
+          git push origin {{DEV_BRANCH}}
+        env:
+          GH_TOKEN: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}
+      - name: On any failure (conflict, rejected push, or otherwise), open a PR for manual resolution
+        if: steps.merge.outcome == 'failure'
+        run: |
+          git merge --abort || true
+          BRANCH="shipflow/merge-back-{{MAIN_BRANCH}}-to-{{DEV_BRANCH}}-${{ github.run_id }}"
+          git checkout -b "$BRANCH" origin/{{MAIN_BRANCH}}
+          git push origin "$BRANCH"
+          gh pr create --base {{DEV_BRANCH}} --head "$BRANCH" \
+            --title "Manual merge-back needed: {{MAIN_BRANCH}} -> {{DEV_BRANCH}}" \
+            --body "Automatic merge-back failed (conflict or rejected push) after a hotfix/release merged to {{MAIN_BRANCH}}. Resolve and merge this PR manually."
+        env:
+          GH_TOKEN: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}

package/templates/gitflow/release-automerge.yml.tmpl

@@ -0,0 +1,65 @@
+name: auto-merge release/*  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.
+#
+# GH_TOKEN uses config.release.releaseCredential, NOT a hardcoded
+# secrets.GITHUB_TOKEN, because of GitHub's loop-prevention rule: a PR
+# auto-merged via `gh pr merge --auto` run under the default GITHUB_TOKEN
+# completes (later, asynchronously, once checks pass) attributed to the
+# github-actions[bot] identity — and a `pull_request: closed` event
+# resulting from that bot-attributed merge does NOT trigger this or any
+# other workflow's `on: pull_request` handlers. Confirmed empirically:
+# an identical PR merged by a real, PAT-authenticated actor fired the
+# closed-event trigger immediately; one completed by GITHUB_TOKEN-enabled
+# auto-merge fired no run at all. releaseCredential must therefore name a
+# real PAT/App-installation-token secret (not GITHUB_TOKEN) for
+# label-release-pending to ever actually run.
+
+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' &&
+      startsWith(github.event.pull_request.head.ref, '{{RELEASE_BRANCH_PREFIX}}')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Enable auto-merge
+        run: gh pr merge --auto {{MERGE_FLAG}} "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}"
+        env:
+          GH_TOKEN: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}
+
+  # Fires once, when the release 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 — the 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 &&
+      startsWith(github.event.pull_request.head.ref, '{{RELEASE_BRANCH_PREFIX}}')
+    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 }}"
+        env:
+          GH_TOKEN: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}

package/templates/gitflow/release-merge-back.yml.tmpl

@@ -0,0 +1,54 @@
+name: merge {{MAIN_BRANCH}} back to {{DEV_BRANCH}} after a release
+
+# Rendered by shipflow's apply.mjs. See dev-to-main-automerge.yml.tmpl's header
+# comment for the general hand-edit/renderedTemplateHashes discipline — same rules
+# apply here.
+#
+# GitFlow's release branches merge into BOTH main and develop — this is the
+# defining semantic of a release, not an optional convention (confirmed via
+# research: git-flow CLI's own `release finish` command does both merges
+# atomically, mirroring hotfix finish). This job runs the develop-side merge
+# automatically once the main-side merge (release-automerge.yml) lands.
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [{{MAIN_BRANCH}}]
+
+permissions:
+  contents: write
+
+jobs:
+  merge-back-to-dev:
+    if: >-
+      github.event.pull_request.merged == true &&
+      startsWith(github.event.pull_request.head.ref, '{{RELEASE_BRANCH_PREFIX}}')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}
+      - name: Attempt a clean merge of {{MAIN_BRANCH}} into {{DEV_BRANCH}}
+        id: merge
+        continue-on-error: true
+        run: |
+          git config user.name "shipflow"
+          git config user.email "shipflow@users.noreply.github.com"
+          git checkout {{DEV_BRANCH}}
+          git merge origin/{{MAIN_BRANCH}} --no-edit
+          git push origin {{DEV_BRANCH}}
+        env:
+          GH_TOKEN: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}
+      - name: On any failure (conflict, rejected push, or otherwise), open a PR for manual resolution
+        if: steps.merge.outcome == 'failure'
+        run: |
+          git merge --abort || true
+          BRANCH="shipflow/merge-back-{{MAIN_BRANCH}}-to-{{DEV_BRANCH}}-${{ github.run_id }}"
+          git checkout -b "$BRANCH" origin/{{MAIN_BRANCH}}
+          git push origin "$BRANCH"
+          gh pr create --base {{DEV_BRANCH}} --head "$BRANCH" \
+            --title "Manual merge-back needed: {{MAIN_BRANCH}} -> {{DEV_BRANCH}}" \
+            --body "Automatic merge-back failed (conflict or rejected push) after a hotfix/release merged to {{MAIN_BRANCH}}. Resolve and merge this PR manually."
+        env:
+          GH_TOKEN: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}

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

@@ -0,0 +1,66 @@
+name: auto-merge 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.
+#
+# 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.
+#
+# GH_TOKEN uses config.release.releaseCredential, NOT a hardcoded
+# secrets.GITHUB_TOKEN, because of GitHub's loop-prevention rule: a PR
+# auto-merged via `gh pr merge --auto` run under the default GITHUB_TOKEN
+# completes (later, asynchronously, once checks pass) attributed to the
+# github-actions[bot] identity — and a `pull_request: closed` event
+# resulting from that bot-attributed merge does NOT trigger this or any
+# other workflow's `on: pull_request` handlers. Confirmed empirically:
+# an identical PR merged by a real, PAT-authenticated actor fired the
+# closed-event trigger immediately; one completed by GITHUB_TOKEN-enabled
+# auto-merge fired no run at all. releaseCredential must therefore name a
+# real PAT/App-installation-token secret (not GITHUB_TOKEN) for
+# label-release-pending to ever actually run.
+
+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'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Enable auto-merge
+        run: gh pr merge --auto {{MERGE_FLAG}} "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}"
+        env:
+          GH_TOKEN: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}
+
+  # Fires once, when a 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 merge and ask about a release — the 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
+    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 }}"
+        env:
+          GH_TOKEN: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}