@natjswenson/shipflow 0.2.6 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,320 @@
+# Changelog
+
+All notable changes to `@natjswenson/shipflow` are documented here.
+
+## 0.3.1 (2026-07-28) — publish the README, LICENSE and CHANGELOG to npm
+
+- **Fixed: the npm package shipped with no README, LICENSE or CHANGELOG.**
+  `package.json`'s `files` listed all three, but they live at the plugin root
+  (beside `.claude-plugin/`), one level above the package directory — and npm only
+  includes files from inside the package directory, so the entries silently matched
+  nothing. Every release through 0.3.0 published a tarball without them, and
+  `npm view @natjswenson/shipflow readme` returned *"No README data found"*, leaving
+  the npm page blank for anyone evaluating the CLI. A `prepack` script now stages the
+  three files into the package directory before the tarball is built, and `postpack`
+  removes them again so the working tree stays clean; they are gitignored at that
+  path so a interrupted pack cannot leave committable strays. Code unchanged.
+
+## 0.3.0 (2026-07-28) — multi-pattern workflow templates; `undefined` param fix
+
+Minor, not patch: this release carries the multi-pattern feature work that had been
+sitting unreleased on `main` since 0.2.6, plus one bug fix found by the new baseline
+eval. Existing `dev-main-promotion` repos are unaffected — see the compatibility note
+below.
+
+- **Fixed: a missing config field rendered the literal string `"undefined"` into the
+  workflow.** `renderTemplate` tested param presence with `key in params`, which is
+  true for a key whose value is `undefined`, so `String(undefined)` flowed through as
+  a real value and passed the safety regexes. A config with no `branches.main`
+  rendered `name: auto-merge dev to undefined` and `branches: [undefined]` — a
+  syntactically valid workflow that installs cleanly and can never fire, with no
+  error at `apply` time. Present-but-`undefined` and `null` now count as missing and
+  raise the same "missing param(s)" error as an absent key. Found by
+  `tests/baseline.test.mjs` on its first run.
+
+Generalizes shipflow from one hardcoded branching pattern to a registry of three
+selectable patterns, with deterministic autodetection. Backward compatible: a repo's
+existing `.github/shipflow.json` with no `workflowPattern` field keeps resolving to
+`dev-main-promotion` with identical behavior — confirmed against this repo's own live
+config (a `noops`-only plan, byte-identical to before this change).
+
+- **Added: `github-flow` pattern** — a single long-lived `main`; every PR merges (and
+  auto-merges) directly to it, no separate promotion branch. New
+  `main-automerge.yml.tmpl` template.
+- **Added: `gitflow` pattern** — `develop` + `main` + transient `release/*`/`hotfix/*`
+  branches, for software maintaining multiple released versions concurrently. New
+  `release-automerge.yml.tmpl`/`hotfix-automerge.yml.tmpl` templates (prefix-matched
+  `head.ref` guards) and `hotfix-merge-back.yml.tmpl`/`release-merge-back.yml.tmpl`
+  (GitFlow's defining dual-merge-back semantic: a hotfix/release merges into both
+  `main` and `develop`; a merge-back conflict or push failure opens a PR for manual
+  resolution instead of force-pushing or silently dropping the merge).
+- **Added: deterministic autodetection.** `shipflow detect` now returns a
+  `rankedPatterns` array (every pattern's score + evidence). Classification is
+  `confident` (top score `>= 0.7` and a `> 0.3` gap over second place), `greenfield`
+  (top score `< 0.4`), or `ambiguous` (the residual case) — the first-run interview
+  confirms a confident detection's evidence with the user rather than silently
+  applying it, and presents all 3 patterns for an explicit choice otherwise.
+- **Added: `workflowPattern` + `patternConfig` config fields.** `patternConfig.gitflow`
+  holds `releaseBranchPrefix`/`hotfixBranchPrefix` (default `release/`/`hotfix/`).
+  `branches.dev` remains the sole source of truth for gitflow's develop-branch name —
+  no separate `developBranch` field.
+- **Architecture:** new `lib/pattern-registry.mjs` (`listPatterns`/`resolvePattern`/
+  `scoreAll`) and one `lib/patterns/<id>/index.mjs` module per pattern. `detect.mjs`,
+  `plan.mjs`, and `apply.mjs` are now thin dispatchers over whatever the registry
+  returns, instead of hardcoding `dev-main-promotion`'s logic inline — adding a 4th
+  pattern in the future needs no changes to any of the three.
+- Existing single-pattern behavior (branch protection, auto-merge, branch cleanup,
+  release tagging) is unchanged for repos already on `dev-main-promotion`.
+
+## 0.2.6 (2026-07-15) — pin `@latest` on every invocation; docs pass
+
+Self-discovered during the PAT-wiring dogfood step that immediately followed
+0.2.5's release — not a Siege audit finding, but adjacent to the same
+class of risk the audit was meant to close.
+
+- **Fixed: silent global-install shadowing.** `npx -y @natjswenson/shipflow
+  <command>` (no version/tag) can resolve an already-installed copy on
+  `PATH` — e.g. a stale `npm install -g @natjswenson/shipflow` left over
+  from manual testing — instead of fetching the current version from the
+  registry, with **no warning that this happened**. Confirmed concretely on
+  `claude-skills` itself: a bare invocation silently ran a stale global
+  0.2.0 install, missing every fix through 0.2.5, including the Critical
+  template-injection fix (0.2.3). `npx -y @natjswenson/shipflow@latest
+  <command>` correctly resolved 0.2.5. This meant a repo could run
+  `shipflow` believing it was getting current, audited behavior while
+  silently getting pre-audit, vulnerable behavior instead.
+- **Fix: every invocation in `SKILL.md` now pins `@latest`.** New
+  regression tests (`tests/skill_contract.test.mjs`) assert every `npx`
+  invocation of shipflow in `SKILL.md` is pinned, and fail if a future edit
+  reintroduces a bare invocation. New skill-invariant entry
+  (`npx-must-pin-latest`).
+- **Docs pass**, per user request before this release: root `README.md`
+  gained a `shipflow` row in the skills table, marketplace/manual-install
+  instructions, and a rewritten Branch & release flow section describing
+  the actual shipflow-managed automation this repo runs (replacing stale
+  prose describing the pre-dogfood bespoke flow); `skills/shipflow/README.md`
+  gained current usage instructions (with the `@latest` pin and its
+  rationale), an updated Status section reflecting 0.2.5's live validation
+  and completed security audit, and a pointer to remove a shadowing global
+  install if one exists (`npm uninstall -g @natjswenson/shipflow`).
+- No code changes to `lib/`/`bin/` in this release — SKILL.md, tests,
+  README, and version metadata only.
+
+## 0.2.5 (2026-07-15) — mandatory TOCTOU guard, forced-override auditability, subprocess timeouts, YAML-validity CI check
+
+The four remaining findings from the same Siege audit as 0.2.3/0.2.4, all
+presented to the user for a fix-vs-accept decision and fixed on explicit
+go-ahead.
+
+- **High, fixed (SIEGE-2026-07-15-002):** `--force allow-no-checks` /
+  `--force <template-id>` had zero code-level friction beyond the flag
+  itself — "get explicit user confirmation before forcing" lived entirely in
+  SKILL.md prose, not in the CLI. `apply` now refuses any `--force` unless
+  accompanied by `--force-reason "<text>"`; the reason is echoed back on
+  each forced entry in the apply result (`{ forced: true, forceReason }`)
+  for auditability. This doesn't stop a determined bypass, but it raises
+  the bar from a single flag to an explicit, logged justification.
+- **Medium, fixed (SIEGE-2026-07-15-003):** `--expect-state-hash` (the
+  documented TOCTOU guard) was optional — omitting it silently proceeded
+  with zero drift protection. A real (non-dry-run) `apply` now hard-refuses
+  without it, unless the caller explicitly passes the new, named
+  `--skip-hash-check` escape hatch.
+- **Medium, fixed (SIEGE-2026-07-15-004):** no subprocess timeout was set
+  anywhere in `gh.mjs`'s `spawnSync` calls — a hung/rate-limited `gh api` or
+  stuck `git` call could hang the whole process indefinitely. All
+  `spawnArgs` calls now default to a 30s timeout, with the resulting
+  `ETIMEDOUT` surfaced in the returned `stderr`.
+- **Low, fixed (SIEGE-2026-07-15-005):** no test rendered the template and
+  validated the output as syntactically valid YAML — the exact bug class
+  that bit 0.2.1/0.2.2 (a silently-broken generated workflow) was caught
+  only by live production testing, not the unit suite. New
+  `tests/template-validity.test.mjs` parses the rendered workflow with the
+  `yaml` package (dev-only dependency, not shipped to consumers) across a
+  range of legal inputs.
+- New CLI integration test file (`tests/cli-apply-guards.test.mjs`) spawns
+  the real `bin/shipflow.js` to exercise both new refusals end-to-end.
+- This closes out the Siege security audit run before rolling shipflow out
+  to repos beyond `claude-skills` — zero Critical/High findings remain open.
+
+## 0.2.4 (2026-07-15) — REST-path encoding, resolveOwnerRepo hardening, file-size cap
+
+Three more findings from the same Siege audit as 0.2.3, surfaced by an
+independently-dispatched Boundary Attacker pass that (eventually) returned
+its report and cross-confirmed the 0.2.3 fix while adding new findings:
+
+- **Medium, fixed:** `fetchBranchProtection` and `checkSecretPresent`
+  interpolated `branch`/`secretName` unencoded into `gh api` REST path
+  segments — inconsistent with `checkLabelExists`, which already used
+  `encodeURIComponent` for the same class of input. Both now encode.
+- **Low, fixed:** `resolveOwnerRepo`'s regex capture (`[\w.-]+`) admitted
+  all-dots segments (`.`, `..`) since `.` is in the character class with no
+  further constraint — a crafted remote like `github.com/../claude-skills`
+  could yield an `ownerRepo` that normalizes away the intended
+  `repos/<owner>/<repo>` prefix once interpolated downstream. Now rejects
+  any owner/repo segment matching `^\.+$`.
+- **Medium, fixed:** no file shipflow reads from a target repo
+  (`.github/shipflow.json`, candidate settings-as-code artifacts, workflow
+  YAML, the rendered template) had a size guard — all of these are
+  repo-write-controlled, not admin-only, so a maliciously huge or
+  pathologically nested file could exhaust memory on an unbounded
+  `readFileSync`/`JSON.parse`. New `readFileCapped` helper in `gh.mjs`
+  (1 MB cap) used at every such read site.
+- 8 new regression tests.
+
+## 0.2.3 (2026-07-15) — Critical: unescaped template substitution allowed workflow injection
+
+Found by a Siege security audit run before rolling shipflow out to other
+repos, immediately after 0.2.1/0.2.2 landed the previous two fixes.
+
+- **Critical, fixed:** `render.mjs`'s `renderTemplate` did pure string
+  substitution with zero escaping. `config.branches.dev`/`main` and
+  `config.release.releaseCredential` — all sourced from
+  `.github/shipflow.json`, a file anyone with repo **write** access can
+  edit, not just the admin who ran shipflow's setup — were substituted
+  directly into single-quoted YAML string comparisons and a
+  `${{ secrets.X }}` GitHub Actions expression with no validation.
+  Concretely: a `branches.dev` value of `dev' || 'x'=='x` rendered the
+  auto-merge job's `if:` condition to `... == 'dev' || 'x'=='x'` —
+  unconditionally true, enabling auto-merge on **any** pull request into
+  `main`, not just genuine `dev`-branch promotions. A `releaseCredential`
+  value containing a newline could inject arbitrary new YAML keys/steps
+  into the committed, then-executed workflow file. Both are a privilege
+  escalation: a repo-write-level actor reaching an admin-scoped mutation
+  through the credential the rendered workflow runs with.
+- **Fix:** `renderTemplate` now validates each substituted value against a
+  per-token safety rule before rendering — `DEV_BRANCH`/`MAIN_BRANCH` reject
+  any single quote or newline; `RELEASE_CREDENTIAL_SECRET` must match
+  GitHub's own secret-naming rule (`^[A-Za-z_][A-Za-z0-9_]*$`). A rejected
+  value throws rather than silently rendering unsafe YAML.
+- **Also fixed:** `bin/shipflow.js`'s `cmdPlan`/`cmdApply` never wrapped
+  `computePlan` in a try/catch, so this (and the pre-existing "missing
+  param") error would have crashed with a raw stack trace instead of the
+  clean `{"error": ...}` JSON contract every other failure mode uses —
+  breaking the "every command prints JSON to stdout" guarantee agents rely
+  on to parse output.
+- New regression tests assert the exploit renders are rejected, and that
+  ordinary branch/secret names still render normally.
+
+## 0.2.2 (2026-07-15) — `label-release-pending` never fires under `GITHUB_TOKEN`
+
+Found by the same dogfood run as 0.2.1, one merge later — a second, more
+serious bug than the missing `--repo`: the manual-gate release-ask flow's
+whole premise (a durable label survives the async gap between auto-merge
+enabling and completing) silently didn't work at all.
+
+- **Root cause: GitHub's loop-prevention rule.** A PR auto-merged via `gh pr
+  merge --auto` run under the default `secrets.GITHUB_TOKEN` completes
+  (later, once checks pass) attributed to the `github-actions[bot]`
+  identity. A `pull_request: closed` event from that bot-attributed merge
+  does **not** trigger this or any other workflow's `on: pull_request`
+  handlers. Confirmed empirically, not just from docs: an otherwise-identical
+  promotion 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 of polling. This means `label-release-pending` never ran for
+  any normally-auto-merged promotion — only for a promotion a human merged
+  by hand — which is the opposite of the common case the feature exists for.
+- **Fix: both `gh` calls now use `config.release.releaseCredential`** instead
+  of a hardcoded `secrets.GITHUB_TOKEN`. Wired a new `RELEASE_CREDENTIAL_SECRET`
+  template token through `render.mjs` and `plan.mjs`'s
+  `computeTemplatePlanEntry` (previously `releaseCredential` was read by
+  `detect.mjs` only to check whether a named secret *existed* — it was never
+  actually substituted into the rendered workflow).
+- **First-run setup (SKILL.md) now has an explicit step** requiring the user
+  to create a real PAT/App-installation-token secret and record its name in
+  `release.releaseCredential` — defaulting to `GITHUB_TOKEN` is called out as
+  a silent-failure trap, not a safe default. `config.example.json`'s
+  placeholder changed from `"GITHUB_TOKEN"` to `"SHIPFLOW_AUTOMERGE_PAT"` so
+  copying the example doesn't propagate the trap.
+- New regression test asserts both `GH_TOKEN` lines use the configured
+  secret name and never fall back to a hardcoded `GITHUB_TOKEN`.
+
+## 0.2.1 (2026-07-14) — rendered workflow was missing `--repo`
+
+Found by dogfooding shipflow on its own home repo (`claude-skills`) — the
+very first live promotion PR after switching over would have silently
+broken auto-merge and release labeling.
+
+- **Fix: both `gh` calls in the rendered `dev-to-main-automerge.yml` now pass
+  `--repo "${{ github.repository }}"` explicitly.** Neither the `auto-merge`
+  job's `gh pr merge` nor the `label-release-pending` job's `gh pr edit` had
+  it, and the workflow has no `actions/checkout` step for `gh` to infer the
+  repo from — every run failed with `fatal: not a git repository (or any of
+  the parent directories): .git`. This masked itself in the first dogfood
+  migration only because the hand-built workflow it was replacing (which did
+  pass `--repo`) happened to still be present on `main` and fired on the same
+  transitional PR.
+- **New regression tests** (`tests/render.test.mjs`) read the actual
+  `.tmpl` file's rendered output and assert `--repo` is present on both `gh`
+  invocations — no prior test read the template's real command lines, only a
+  synthetic placeholder string, so this shipped with zero coverage of the
+  actual `gh` calls.
+
+## 0.2.0 (2026-07-14) — first live-repo fixes
+
+Fixes found by running shipflow end-to-end against a real repo
+(`natejswenson/1.00s`) for the first time, beyond the read-only smoke test
+against `claude-skills` itself:
+
+- **First-run setup is now an explicit, unskippable interview.** SKILL.md's
+  setup steps must present detected branch names, `requiredChecks`, and the
+  resolved `protectionOwner` and wait for confirmation before writing
+  `.github/shipflow.json` — even when the detected values already look
+  correct. Previously nothing stopped an orchestrating agent from silently
+  narrating findings and proceeding straight to the config write.
+- **Default-branch mismatch detection.** `detect` now reports the repo's
+  actual GitHub default branch (`repoSettings.defaultBranch`). First-run
+  setup surfaces a mismatch against the assumed `main` name and asks the
+  user to either map shipflow's `main` role onto the existing default branch
+  name, or rename the repo's default branch via the new
+  `rename-default-branch` command.
+- **New `rename-default-branch` command**, wrapping GitHub's native
+  branch-rename endpoint (which retargets the default-branch pointer and
+  open PRs automatically when the renamed branch is the current default).
+- **Honest classification of the tier-gated ruleset failure.** Creating the
+  deletion-protection ruleset 403s on private repos without GitHub
+  Pro/Team/Enterprise (rulesets are free for public repos only). This now
+  surfaces as a `skipped` entry with a clear reason instead of an `errors`
+  entry — it's an expected environment limitation, not a shipflow bug. No
+  fallback to classic branch protection was added (declined — out of scope
+  for this fix).
+- **`requiredChecks` candidates are now filtered to actually PR-triggered
+  jobs.** `detect`'s `workflows.jobNames` previously listed every job name
+  from every workflow file regardless of its `on:` trigger — a
+  `schedule`/`workflow_dispatch`-only job (like `1.00s`'s `weekly-archive.yml`)
+  could be picked as a required check that would never run on a PR and
+  would block every future merge forever. Now only jobs from
+  `pull_request`/`pull_request_target`-triggered workflows are offered as
+  candidates.
+- **Agent-driven CI scaffolding when no PR check exists.** Rather than
+  teaching shipflow's deterministic CLI about every language/build-tool
+  ecosystem, first-run setup now has the orchestrating agent investigate the
+  repo and draft a starter `pull_request`-triggered build+test workflow when
+  the (now-accurate) required-checks candidate list is empty, with the same
+  confirm-before-write discipline as every other step — never a silent
+  overwrite, always shown to the user first.
+
+## 0.1.0 (2026-07-14) — Phase A: manual-gate core
+
+Initial release. Implements the fully-specified, reference-repo-validated slice
+of the [shipflow design](../../docs/plans/2026-07-14-shipflow-skill-design.md):
+
+- Long-lived `dev`/`main` branches with configurable names.
+- `dev → main` promotion PRs that auto-merge once configured required checks pass.
+- Automatic branch cleanup (`delete_branch_on_merge` + a deletion ruleset) for
+  every branch except `dev`/`main` — zero custom mutation logic, a native
+  GitHub setting.
+- `protectionOwner` detection: defers to an existing settings-as-code
+  mechanism (e.g. `repo-settings.sh`, Terraform) rather than installing a
+  competing ruleset, with an explicit user prompt when protection exists
+  with no artifact behind it.
+- `release.mode: "manual-gate"` — the deliberate, ask-before-tagging release
+  flow (a durable `release-pending` label survives the async gap between a
+  promotion merging and the next interactive `shipflow` run).
+
+`release.mode: "auto"` (release-please-driven automatic tagging) is accepted
+in the config schema but **not yet implemented** — `apply.mjs` refuses to run
+against an `"auto"` config with a clear "not yet implemented" error rather
+than silently no-oping. Tracked as Phase B; needs a live GitHub sandbox to
+build and verify the two-hop `RELEASE_PAT` credential wiring and the
+release-please byte-equality pre-flight safely.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nate Swenson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# shipflow
+
+[![npm](https://img.shields.io/npm/v/@natjswenson/shipflow?color=blue)](https://www.npmjs.com/package/@natjswenson/shipflow)
+[![license](https://img.shields.io/npm/l/@natjswenson/shipflow)](./LICENSE)
+
+A Claude Code skill that scaffolds a configurable branching, auto-merge, branch-cleanup, and release-tagging workflow into any repo — across three selectable patterns, not just one.
+
+Run it in a target repo and it detects existing branch protection, CI checks, release conventions, and which branching pattern the repo already uses, shows you a plan, and only mutates anything after you confirm. The skill package is identical everywhere — the actual policy (workflow pattern, branch names, required checks, release mode, ...) lives in the target repo's own `.github/shipflow.json`, committed and auditable.
+
+## Patterns
+
+| Pattern | Shape |
+|---|---|
+| `dev-main-promotion` | Long-lived `dev` + `main`; a promotion PR auto-merges `dev` into `main` |
+| `github-flow` | Single long-lived `main`; every PR merges (and auto-merges) directly to it |
+| `gitflow` | `develop` + `main` + transient `release/*`/`hotfix/*` branches, for software maintaining multiple released versions concurrently |
+
+`shipflow detect` scores all three against the repo's existing shape (branches, tags, workflow files) and either confirms a confident match with you or asks you to pick when detection is ambiguous or the repo is greenfield — it never silently picks one.
+
+## How it works
+
+1. **`/shipflow` in Claude Code** runs an interactive setup interview — detects the workflow pattern, branch protection, CI, and the default branch, confirms them (plus `requiredChecks` and `protectionOwner`) with you, and writes `.github/shipflow.json`.
+2. **`shipflow plan`** diffs that config against live repo state and shows exactly what would change, before anything is touched.
+3. **`shipflow apply`** — only after you confirm — renders the resolved pattern's workflow file(s) and makes the confirmed mutations. Nothing happens outside what the plan showed.
+4. Ongoing: promotions/merges auto-merge once required checks pass; a durable `release-pending` label survives the async gap until a later `shipflow releases` check asks whether to cut a release.
+
+## Quick start
+
+All deterministic work runs through the published CLI:
+
+```sh
+npx -y @natjswenson/shipflow@latest detect --repo . --main main --dev dev
+```
+
+> **Always pin `@latest`.** Without an explicit version/tag, `npx` can silently resolve a stale install already on your `PATH` instead of fetching the current version from the registry — with no warning. If you've ever run `npm install -g @natjswenson/shipflow` for manual testing, remove it: `npm uninstall -g @natjswenson/shipflow`.
+
+Full interactive setup flow: [`skills/shipflow/SKILL.md`](skills/shipflow/SKILL.md).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `detect --repo <path> [--main <name>] [--dev <name>]` | Inspect live repo state: branch protection, CI checks, release conventions |
+| `plan --repo <path>` | Diff `.github/shipflow.json` against live state; prints what would change + a state hash |
+| `apply --repo <path> --expect-state-hash <hash> [--dry-run] [--force <id> --force-reason <text>]` | Apply a confirmed plan |
+| `releases --repo <path>` | List `dev → main` promotions still labeled `release-pending` |
+| `release-dispatch --repo <path> --pr <n> --workflow-file <f>... --ref <ref>` | Dispatch each changed skill's release workflow; clear the label on success |
+| `rename-default-branch --repo <path> --branch <old> --to <new>` | One-time bootstrap: rename a repo's default branch |
+
+Every command prints JSON to stdout.
+
+## Status
+
+**`release.mode: "manual-gate"`** (the only implemented mode) is live-validated end-to-end — dogfooded on this repo (`claude-skills`) and an external repo (`natejswenson/1.00s`). A full Siege security audit found and fixed 9 findings (1 Critical, 1 High, the rest Medium/Low) before wider rollout; zero Critical/High findings remain open. See [`CHANGELOG.md`](./CHANGELOG.md) for the fix-by-fix history.
+
+**`release.mode: "auto"`** (fully automatic tagging via `release-please`) is accepted in the config schema but not yet implemented — `apply` refuses with a clear error until it ships.
+
+## Design
+
+[`docs/plans/2026-07-14-shipflow-skill-design.md`](../../docs/plans/2026-07-14-shipflow-skill-design.md) — the original single-pattern design (7 rounds of adversarial review, score 12 → 0).
+
+[`docs/plans/2026-07-16-shipflow-multi-pattern-design.md`](../../docs/plans/2026-07-16-shipflow-multi-pattern-design.md) — the multi-pattern registry design (10 rounds of adversarial review).
+
+## License
+
+MIT

package/SKILL.md

@@ -41,9 +41,18 @@ user; the CLI is the only thing that *does*.
    ```
    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:
      ```
@@ -51,41 +60,41 @@ user; the CLI is the only thing that *does*.
      ```
      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@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@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@latest 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)
 

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);