@natjswenson/shipflow 0.3.3 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,161 @@
 
 All notable changes to `@natjswenson/shipflow` are documented here.
 
+## 0.6.0 (2026-08-03) — the ambiguous fast path is refused, not guessed
+
+### Fixed
+
+- **`release-cut`'s fast path could silently tag the OLDER version.** When a
+  component's `main` carried an untagged bump *and* `dev` independently carried
+  something higher — `lastTag < main < dev` — `readStatus` collapsed both facts
+  into the single `untagged-bump-on-main` state, and `cut()`'s fast path acted
+  on that state alone, dispatching a release for whatever sat on `main` while
+  the version actually being released sat, unread, on `dev`. Hit for real
+  during `/release eval` on 2026-08-03: `main` was at 0.2.1, `dev` at 0.3.0 —
+  `cut` would have tagged `eval-v0.2.1` and reported success. Caught only by
+  reading `release.mjs` before running the irreversible step.
+
+  `readStatus` now reports a `devAhead` fact (`{ version, aheadOfMain: true }`)
+  independently of `state` — including on a component's never-released first
+  bump, the sibling case a fix scoped only to the existing `state` branch would
+  have missed — plus a `dev-ahead-of-main` blocker, scoped to exactly the state
+  where the fast path is armed. A new pure `resolveReleaseTarget(status,
+  requestedVersion)` is the single place the release target is now decided;
+  `cut()` calls it once, before any network call, and refuses outright when
+  the target is ambiguous, naming both versions. There is no longer a code
+  path on which the tag `cut` waits for can disagree with the version it
+  decided to release.
+
+  The refusal is escapable, deliberately not inescapable: `release-cut` gains
+  `--version <x.y.z>`, a *confirmation* rather than a bypass — it is only ever
+  accepted when it names a version already present on `main` or `dev` in that
+  status, so there is no value of it that releases a version which isn't
+  actually on the branch being dispatched.
+
+## 0.5.0 (2026-08-02) — the merge stops cutting tags; the dispatch is the release
+
+### Changed
+
+- **`release-cut` now dispatches the component's release workflow itself, after
+  the promotion lands.** Previously it merged the promotion and then *waited*
+  for a tag that a `push`-triggered job happened to cut. That made a merge the
+  real release trigger, which meant any promotion released everything bumped on
+  `dev` — whether or not anyone asked, and irreversibly for skills that publish
+  to npm.
+
+  Paired with every caller's `release` job becoming `workflow_dispatch`-only,
+  this makes the dispatch the **single point at which a tag is ever created**.
+  A `dev → main` merge now moves a version bump to `main` and stops there; the
+  component simply becomes `untagged-bump-on-main` until someone releases it on
+  purpose.
+
+  The two halves are load-bearing together. Removing the `push` gate without
+  this dispatch leaves `release-cut` waiting forever for a tag nobody cuts;
+  adding the dispatch without removing the gate double-releases.
+
+- **`collateral` means something smaller and safer now.** It still lists every
+  other component whose bump the same promotion moves to `main` — that is
+  unavoidable, a promotion is atomic — but those components are no longer
+  *released* by it. The disclosure stays because the user should know what their
+  promotion moves, and which components are now one dispatch from a release
+  nobody asked for.
+
+### Fixed
+
+- **`release-status` returned a wrong commit list in a shallow clone, silently.**
+  `git log <tag>..<ref>` excludes everything reachable from `<tag>`, and that
+  exclusion needs full ancestry. In a grafted history it under-applies, so the
+  range returns commits that shipped long ago — without erroring, and therefore
+  with a `suggestedBump` derived from fiction.
+
+  Observed on this repo the day 0.4.0 shipped: a depth-1 checkout of `main`
+  reported **1 unreleased commit** for a component a full clone correctly
+  reported as **0**, which would have proposed a patch release for nothing.
+  `actions/checkout` is depth-1 by default, so any CI job calling `release-status`
+  hit this.
+
+  A shallow repository is now a **blocker**, not a note — every number derived
+  from the commit range is untrustworthy, so the honest answer is to refuse and
+  say `git fetch --unshallow`, rather than to report a plausible wrong one.
+
+## 0.4.0 (2026-08-02) — release one named thing, and prove the tag exists
+
+### Added
+
+- **Component releases: `release-status`, `release-prepare`, `release-cut`.**
+  A *component* is one independently-versioned thing in a repo — a skill in a
+  monorepo, or the repo itself. `release.componentLayout` says where its
+  version files, changelog, tag and release workflow live, with `{name}` as the
+  only substitution token, and `release.components` lists the names. A repo
+  with neither gets a single component inferred from its root, so a one-project
+  repo needs no config at all and `--component` may be omitted.
+
+  This closes the half of releasing that was never automated. The mechanical
+  end already worked — `_release.yml` is version-driven and idempotent, every
+  caller has `workflow_dispatch`, `release-dispatch` exists. Everything
+  *upstream* of the dispatch was manual, and that is where the friction and the
+  mistakes lived.
+
+- **`release-status` reads state instead of guessing it.** The version on main
+  and on dev (read via `git show`, so the user's working tree is never touched
+  or checked out), the last tag, every commit since that tag that touched this
+  component's paths, a suggested bump with its reason, and a `statusHash` that
+  `release-cut` requires back — the same TOCTOU discipline `apply` already has.
+
+- **`collateral`: every other component the same promotion would release.** A
+  `dev → main` promotion is atomic and carries all of dev, so cutting a release
+  for one component also releases anything else sitting bumped-but-untagged
+  there. The SKILL.md rule is that this list is named to the user before the
+  irreversible step, never merely present in JSON an agent might skim past.
+
+- **`release-cut` is resumable, bounded, and proves the tag.** The full path —
+  feature PR, checks, merge, promotion, auto-merge, release run, tag — takes
+  longer than one call should block for, so each call advances as far as it can
+  and returns the stage it is parked at. Every stage is derived from live remote
+  state, never from a record of a previous call, so a resumed run and a fresh
+  one are the same code path. It reports `done: true` only after reading the tag
+  back from origin: a dispatched workflow, a merged PR and a green check are all
+  still "not done."
+
+- **Version files can be `package.json`, `SKILL.md` frontmatter, `pyproject.toml`
+  or a top-level `project.yml`.** A component model that only reads
+  `package.json` is not generic, it is a node model — the first two non-node
+  repos this was pointed at were a Python project and an Xcode project. TOML and
+  YAML are matched at column zero only: both formats nest, and an indented
+  `version` is a dependency pin, not the project's own version. Releasing the
+  wrong number is worse than reporting none.
+
+### Fixed
+
+- **`spliceChangelog` built a regex out of the version string and escaped only
+  the dots**, leaving `\`, `*`, `+`, `(` and `[` live all the way into
+  `new RegExp`. `prepare` rejects a non-semver version before reaching it, so
+  this was not exploitable through the CLI — but the function is exported and
+  independently callable, and a guard that lives in the caller is not a guard.
+  It now matches with plain string operations, which is also exactly what
+  `_release.yml`'s `awk` does (`/^## / && index($0, ver)`), so the duplicate
+  check and the release-time extractor answer the same question the same way.
+  Found by CodeQL (`js/incomplete-sanitization`, high) on PR #158.
+
+- **`dispatchReleaseWorkflow` ignored the `ownerRepo` it was given.** It shelled
+  out to `gh workflow run` with no `--repo`, so `gh` inferred the repository
+  from the process's working directory — which is routinely *not* the repo
+  `--repo <path>` points at. A dispatch into the wrong repository still exits 0,
+  so this failed silently in exactly the setup the flag exists for.
+
+### Notes
+
+- A breaking change on a component still in 0.x is capped at a **minor** bump,
+  and reported as capped rather than applied silently. Declaring 1.0.0 is an
+  API-stability promise, and no commit message is entitled to make it on the
+  maintainer's behalf.
+- `release-prepare` does its work in a throwaway `git worktree`, so unrelated
+  uncommitted work in the user's tree cannot be swept into a release commit.
+  Real trees have parallel work in them; this monorepo's had an entire untracked
+  skill in it while this feature was written.
+- No template changed, so no rendered workflow and no `renderedTemplateHashes`
+  entry moves in this release.
+
 ## 0.3.3 (2026-08-01) — least-privilege permissions in every rendered workflow
 
 - **Every rendered workflow granted its permissions at the workflow level, so

package/README.md

@@ -1,47 +1,105 @@
 # 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)
+<!-- >>> press:masthead v0.9.0 sha256:2c0f2d9aea4a GENERATED by @natjswenson/press, do not edit -->
+**NS** · NATE SWENSON · CLAUDE CODE SKILL · PRESS v0.9.0 · linkedin.com/in/natejswenson
 
-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.
+---
+<!-- <<< press:masthead -->
 
-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.
+*Scaffold branching, auto-merge, branch cleanup and release tagging into any repo.*
 
-## Patterns
+> **Nothing is mutated that the plan did not show, and nothing is mutated before you confirm it.**
 
-| 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 |
+[![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)
 
-`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.
+## Why install this
 
-## How it works
+Branch protection, auto-merge and release tagging are the settings everybody
+configures once, by hand, in a web UI, and then cannot answer questions about six
+months later. Nothing records what was intended, so drift is undetectable.
 
-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.
+shipflow makes the policy a committed file. 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 lives in the target repo's own `.github/shipflow.json`, auditable in a
+diff.
 
-## Quick start
+It supports three patterns rather than imposing one, and `detect` scores all
+three against the repo's real shape — it never silently picks one.
 
-All deterministic work runs through the published CLI:
+## What you get
+
+| Path | What it provides |
+|---|---|
+| `skills/shipflow/SKILL.md` | The interactive setup interview, and where it must stop and ask. |
+| `skills/shipflow/bin/` | The CLI: `detect`, `plan`, `apply`, `releases`, `release-dispatch`. |
+| `skills/shipflow/templates/` | The workflow files each pattern renders. |
+| `skills/shipflow/skill-invariants.json` | The prose guardrails and the baseline eval declaration. |
+
+## Quick start
 
 ```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`.
+> **Always pin `@latest`.** Without an explicit version or tag, `npx` can
+> silently resolve a stale install already on your `PATH` instead of fetching the
+> current version from the registry, with no warning. This cost this very repo a
+> release: a bare invocation ran a stale global 0.2.0, missing every fix through
+> 0.2.5 including a Critical template-injection fix. If you have ever run
+> `npm install -g @natjswenson/shipflow`, remove it.
+
+## Triggers
+
+- Setting up branch protection standards on a repo.
+- Applying deployment or release standards to a repo.
+- Wanting long-lived `dev`/`main` branches with auto-merge and branch cleanup.
+- "why did this PR not auto-merge", or a release that should have been tagged and
+  was not.
+
+## Requirements
+
+- Node 18+.
+- [`gh`](https://cli.github.com/), authenticated with admin rights on the target
+  repo — branch protection cannot be read or written without them.
+- A GitHub repo. Deletion rulesets need GitHub Pro or a public repo; on a private
+  free-tier repo that call returns 403 and shipflow reports it rather than
+  pretending it applied.
 
-Full interactive setup flow: [`skills/shipflow/SKILL.md`](skills/shipflow/SKILL.md).
+## 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/*`, for software maintaining multiple released versions concurrently |
+
+`detect` scores all three against the repo's branches, tags and workflow files,
+then either confirms a confident match with you or asks you to pick when
+detection is ambiguous or the repo is greenfield.
+
+## How it works
+
+1. **`/shipflow` in Claude Code** runs an interactive setup interview — detects
+   the 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 files and makes the confirmed mutations. Nothing happens outside what
+   the plan showed.
+4. Ongoing: promotions 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.
 
 ## 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 |
+| `plan --repo <path>` | Diff `.github/shipflow.json` against live state; prints what would change plus a state hash |
 | `apply --repo <path> --expect-state-hash <hash> [--dry-run] [--force <id> --force-reason <text>]` | Apply a confirmed plan |
 | `releases --repo <path>` | List `dev → main` promotions still labeled `release-pending` |
 | `release-dispatch --repo <path> --pr <n> --workflow-file <f>... --ref <ref>` | Dispatch each changed skill's release workflow; clear the label on success |
@@ -51,16 +109,39 @@ 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: "manual-gate"`** — the only implemented mode — is live-validated
+end to end, dogfooded on this repo and on 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 or High
+findings remain open.
 
-**`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.
+**`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).
+- [`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).
+- [`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).
+
+## Development
+
+```bash
+cd skills/shipflow/skills/shipflow
+npm test
+```
+
+Node skill. `ci / shipflow` runs the same tests plus the house lints on every
+pull request. The baseline is pinned against this repo's own `shipflow.json` and
+the workflow it renders, byte-exact — the rendered file *is* the contract.
+
+## Changelog
 
-[`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).
+See [`CHANGELOG.md`](CHANGELOG.md). Releases are cut by a version bump, tagged
+`shipflow-v<version>`, and published to npm.
 
 ## License
 
-MIT
+MIT — see [`LICENSE`](LICENSE).

package/SKILL.md

@@ -32,6 +32,7 @@ user; the CLI is the only thing that *does*.
 | `.github/shipflow.json` doesn't exist in the target repo yet | **First-run setup** |
 | `.github/shipflow.json` exists, user wants to check/repair drift | **Re-run / audit** |
 | User asks "any releases pending?" / periodic check-in / after a `dev → main` merge | **Check pending releases** |
+| User wants to cut a release for one named thing ("release devlog") | **Cut a component release** |
 
 ## First-run setup
 
@@ -63,7 +64,7 @@ user; the CLI is the only thing that *does*.
 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, a CI workflow has to exist before auto-merge
-   can be enabled. Hand that job to the `forge` skill** — authoring and *verifying*
+   can be enabled. Hand that job to the `ghfactory` skill** — authoring and *verifying*
    workflow YAML is its whole subject, and it does things shipflow never will:
    it resolves every action ref against the real API (no linter checks that an
    action exists), validates each `with:` key against the action's own
@@ -71,10 +72,10 @@ user; the CLI is the only thing that *does*.
    and zizmor before showing you anything. Two skills answering "scaffold me a CI
    workflow" differently is worse than either answer.
 
-   > Use the forge skill to create a `pull_request`-triggered build+test workflow
+   > Use the ghfactory skill to create a `pull_request`-triggered build+test workflow
    > for this repo, then come back here with the job name.
 
-   **If forge is not installed**, draft it here instead: investigate the repo
+   **If ghfactory is not installed**, draft it here instead: investigate the repo
    directly (`package.json`, `Cargo.toml`, `project.yml`/`.xcodeproj`, `go.mod`,
    `pyproject.toml`, or whatever's actually there) and write a minimal,
    conservative `pull_request`-triggered build+test workflow.
@@ -140,6 +141,92 @@ This is a **separate, later invocation** from the one that ran the promotion's `
 
 4. If no, leave the label as-is — there is no "defer" state in this version; declining is final for that promotion short of a manual dispatch. (Deliberate v1 simplification, not an oversight.)
 
+## Cut a component release
+
+For the conversational "release devlog" flow, prefer the **`release` skill** — it owns the
+bump judgment, the CHANGELOG prose and the run presentation. This section is the CLI contract
+underneath it, and the fallback when that skill is not installed.
+
+A **component** is one independently-versioned thing in a repo: a skill in a monorepo, or the
+repo itself. `release.componentLayout` describes where a component's version, changelog, tag
+and release workflow live, with `{name}` as the only substitution token;
+`release.components` lists the names. A repo with neither gets a single component inferred from
+its root (`package.json`, `CHANGELOG.md`, `v{version}`), so a one-project repo needs no config
+at all and `--component` may be omitted.
+
+1. **Read the state. Never guess it.**
+   ```
+   npx -y @natjswenson/shipflow@latest release-status --repo <path> --component <name>
+   ```
+   Returns `state`, the version on main and dev, the last tag, every commit since that tag that
+   touched this component's paths, a `suggestedBump` with its reason, `blockers`, `notes`, and a
+   `statusHash`. `state` decides the path:
+   - `clean` — the released version is what's on main. A bump is needed: go to step 2.
+   - `untagged-bump-on-main` — the bump is already on main and was never tagged (a cancelled or
+     failed release run). **No PR is needed** — `release-cut` dispatches and verifies. Skip to step 3.
+     **`untagged-bump-on-main` is not, by itself, permission to cut.** Check `devAhead` first: if
+     it is set, dev already carries a *higher* version than what's on main, and cutting here would
+     tag the version on main, not the one on dev — the version you almost certainly mean to
+     release. `release-cut` refuses in this shape unless you pass `--version` naming exactly which
+     one to release (see step 3); it never guesses.
+   - `bump-on-dev-unpromoted` — the bump is on dev, waiting for a promotion. Skip to step 3.
+   - `version-behind-tag` — main carries a *lower* version than an existing tag. Stop and ask;
+     this means a tag was cut from something other than main, and guessing is how it gets worse.
+
+2. **Show the user `collateral`, `blockers` and the proposed version, and wait.**
+   A `dev → main` promotion is atomic and carries all of dev, so every component listed under
+   `collateral` has its bump moved to `main` by the same promotion. It is **not released** by
+   that — every caller's release job is `workflow_dispatch`-only, so merging tags nothing; each
+   becomes `untagged-bump-on-main`, one deliberate `release-cut` away from a tag.
+   **Never run `release-cut` without naming that list to the user first.** They should know what
+   their promotion moves, and which components are now one dispatch from a release nobody asked
+   for.
+
+   `suggestedBump` is a suggestion. The user decides, and a `suggestedBumpCapped: true` means a
+   breaking change was held at minor because the component is still 0.x — going to 1.0.0 is a
+   release decision, never a commit message's. Then:
+   ```
+   npx -y @natjswenson/shipflow@latest release-prepare --repo <path> --component <name> \
+     --version <x.y.z> --notes-file <path>
+   ```
+   Local only, no network. It works in a **throwaway git worktree**, so unrelated uncommitted work
+   in the user's tree is untouched and cannot be swept into the release commit. The version bump
+   and the CHANGELOG entry land in **one commit** — the notes are read off `main` at dispatch
+   time, so a CHANGELOG that lands in a later promotion than its version is notes the release
+   will never carry.
+
+3. **Cut it, and prove it.**
+   ```
+   npx -y @natjswenson/shipflow@latest release-cut --repo <path> --component <name> \
+     --expect-status-hash <hash-from-step-1> --wait 240
+   ```
+   `--expect-status-hash` is mandatory (same TOCTOU discipline as `apply`'s `--expect-state-hash`);
+   `--skip-hash-check` is a named escape hatch, never a default.
+
+   If step 1's `devAhead` was set, `release-cut` refuses outright with an error naming both
+   versions — this is the ambiguous three-way state (main has an untagged bump, dev already
+   carries something higher) where guessing would tag the wrong one. Promote `dev → main` and
+   re-run `release-status` to release what's on dev (the normal recovery), **or** add
+   `--version <x.y.z>` naming exactly the version on main, if you deliberately mean to release
+   that one and leave dev's higher version for later. `--version` is a confirmation, not a
+   bypass — it is only ever accepted when it matches a version already on main or dev; anything
+   else is refused the same as passing nothing.
+
+   **`release-cut` is resumable and bounded, and it will usually return `done: false`.** The full
+   path — feature PR, checks, merge, promotion, auto-merge, **dispatch**, release run, tag — takes
+   longer than one call should block for. Each call advances as far as it can, then returns the
+   `stage` it is parked at and a `next` line. **Call it again, unchanged, until `done: true`.** It
+   derives every stage from live remote state and never from a record of what a previous call did,
+   so a resumed run and a fresh one are the same code path.
+
+   **The promotion merging cuts nothing.** `release-cut` dispatches the component's release
+   workflow itself, after the promotion lands — that dispatch is the single point at which any tag
+   is created in this repo, which is why a merge can no longer surprise anyone with a release.
+
+4. **Report the tag, and only the tag.** `done: true` carries `tag` and `releaseUrl`, read back
+   from origin. A dispatched workflow, a merged PR and a green check are **not** a release —
+   `release-cut` confirms the tag exists on the remote before it says done, and so must you.
+
 ## Auto mode (not yet implemented)
 
 `release.mode: "auto"` is a valid value in the config schema (the full design covers automatic tagging via `release-please`), but `shipflow apply` in this version **refuses to run** against a config with `release.mode: "auto"`, with a clear error rather than silently no-oping. If a user asks for fully automatic tagging, tell them it's designed but not yet shipped (see `CHANGELOG.md`) and that `"manual-gate"` — the deliberate ask-before-tagging flow above — is what's available today.
@@ -153,6 +240,15 @@ This is a **separate, later invocation** from the one that ran the promotion's `
 - **`release.releaseCredential` left as (or defaulted to) `GITHUB_TOKEN`:** auto-merge and the required-check gate still work, but `label-release-pending` will silently never run — a `GITHUB_TOKEN`-attributed auto-merge's `pull_request: closed` event never triggers it, so no promotion will ever surface via `shipflow releases`. This fails silently, not loudly — there's no error to catch it — so it must be caught at setup time (step 5) rather than discovered later. If a user reports "releases never show up," check this first.
 - **`--expect-state-hash is required` refusal:** a real apply was attempted with neither `--expect-state-hash` nor `--skip-hash-check`. Go back and get (or re-fetch via `plan`) the hash — don't reach for `--skip-hash-check` just to make the error go away; that flag exists for a deliberate, documented exception, not as a default workaround.
 - **`--force was passed without --force-reason` refusal:** a `--force` flag was about to be sent with no accompanying justification. Stop and get (or write) an explicit reason tied to what the user actually confirmed before retrying — never pass a placeholder string just to satisfy the flag.
+- **`release-cut` returns `done: false`:** not an error. It is parked at the `stage` it reports,
+  waiting on something remote. Call it again with the same arguments. Do not report a release.
+- **`release-status` reports `component-files-dirty`:** this component's own version files or
+  CHANGELOG have uncommitted edits, so a bump would collide with them. Unrelated dirt elsewhere in
+  the tree is reported under `notes` and is deliberately **not** a blocker — `prepare` runs in an
+  isolated worktree specifically so other people's in-flight work is safe.
+- **`release-status` reports `version-unreadable-on-main`:** the component's version files do not
+  exist on main, or they disagree with each other. A disagreement is a hard refusal, never a
+  "pick the highest" — releasing from a disagreeing set tags one version and ships another.
 - **A `gh`/`git` call hangs or times out:** every subprocess call has a 30-second timeout (`ETIMEDOUT` surfaces in the error message). A timeout on `detect`/`plan` usually means a real GitHub outage or rate-limit — retry once, and if it persists, tell the user rather than looping silently.
 
 ## Security rules

package/bin/shipflow.js

@@ -16,6 +16,7 @@ import {
 } from '../lib/apply.mjs';
 import { readFileCapped } from '../lib/gh.mjs';
 import { resolvePattern, scoreAll } from '../lib/pattern-registry.mjs';
+import { readStatus, prepare, cut, listComponentNames } from '../lib/release.mjs';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -244,6 +245,119 @@ function cmdReleaseDispatch(args) {
   printJson({ dispatched: results, labelCleared: cleared.ok, labelClearError: cleared.ok ? null : cleared.error });
 }
 
+// --- component releases -----------------------------------------------------
+// Shared resolution for the three release-* commands. `--component` is optional
+// when the repo has exactly one component (the inferred single-component case),
+// because in a repo with one thing to release, naming it is ceremony.
+function resolveReleaseArgs(values, commandName) {
+  if (!values.repo) return { error: `${commandName}: --repo is required` };
+  const configPath = values.config ?? defaultConfigPath(values.repo);
+  let config;
+  try {
+    config = readConfig(configPath);
+  } catch (e) {
+    return { error: `${commandName}: could not read config at ${configPath}: ${e.message}` };
+  }
+  const names = listComponentNames(config, values.repo);
+  let name = values.component;
+  if (!name) {
+    if (names.length !== 1) {
+      return { error: `${commandName}: --component is required (this repo declares ${names.length}: ${names.join(', ')})` };
+    }
+    name = names[0];
+  } else if (!names.includes(name)) {
+    return { error: `${commandName}: "${name}" is not a declared component. This repo has: ${names.join(', ')}` };
+  }
+  return { config, name };
+}
+
+function cmdReleaseStatus(args) {
+  const { values } = parseArgs({
+    args,
+    options: { repo: { type: 'string' }, config: { type: 'string' }, component: { type: 'string' } },
+  });
+  const resolved = resolveReleaseArgs(values, 'release-status');
+  if (resolved.error) return fail(resolved.error);
+  try {
+    printJson(readStatus(values.repo, resolved.config, resolved.name));
+  } catch (e) {
+    return fail(`release-status: ${e.message}`);
+  }
+}
+
+function cmdReleasePrepare(args) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      repo: { type: 'string' },
+      config: { type: 'string' },
+      component: { type: 'string' },
+      version: { type: 'string' },
+      'notes-file': { type: 'string' },
+      date: { type: 'string' },
+    },
+  });
+  const resolved = resolveReleaseArgs(values, 'release-prepare');
+  if (resolved.error) return fail(resolved.error);
+  if (!values.version || !values['notes-file']) {
+    return fail('release-prepare: --version and --notes-file are both required');
+  }
+  let notes;
+  try {
+    notes = readFileCapped(values['notes-file']);
+  } catch (e) {
+    return fail(`release-prepare: could not read --notes-file: ${e.message}`);
+  }
+  if (notes.trim().length === 0) {
+    // An empty CHANGELOG entry is how a release ships with notes that say
+    // nothing. _release.yml falls back to a bare "<skill> v<version>" title,
+    // which looks deliberate and is not.
+    return fail('release-prepare: --notes-file is empty — a release with no notes is not a release');
+  }
+  try {
+    const result = prepare(values.repo, resolved.config, resolved.name, values.version, notes, {
+      date: values.date,
+      featureBranchPrefix: resolved.config.featureBranchPrefix,
+    });
+    if (!result.ok) return fail(`release-prepare: ${result.error}`);
+    printJson(result);
+  } catch (e) {
+    return fail(`release-prepare: ${e.message}`);
+  }
+}
+
+function cmdReleaseCut(args) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      repo: { type: 'string' },
+      config: { type: 'string' },
+      component: { type: 'string' },
+      'expect-status-hash': { type: 'string' },
+      'skip-hash-check': { type: 'boolean', default: false },
+      wait: { type: 'string' },
+      version: { type: 'string' },
+    },
+  });
+  const resolved = resolveReleaseArgs(values, 'release-cut');
+  if (resolved.error) return fail(resolved.error);
+  const ownerRepo = resolveOwnerRepo(values.repo);
+  if (!ownerRepo) return fail('release-cut: could not resolve owner/repo from git remote');
+  try {
+    const result = cut(values.repo, resolved.config, resolved.name, {
+      waitSeconds: values.wait ? Number(values.wait) : 240,
+      expectStatusHash: values['expect-status-hash'] ?? null,
+      skipHashCheck: values['skip-hash-check'],
+      ownerRepo,
+      version: values.version ?? null,
+    });
+    if (!result.ok) return fail(`release-cut: ${result.error}${result.currentStatusHash ? ` (current statusHash: ${result.currentStatusHash})` : ''}`);
+    printJson(result);
+  } catch (e) {
+    return fail(`release-cut: ${e.message}`);
+  }
+}
+
 function cmdRenameDefaultBranch(args) {
   const { values } = parseArgs({
     args,
@@ -274,6 +388,9 @@ Commands:
   apply --repo <path> [--config <path>] [--dry-run] [--expect-state-hash <hash> | --skip-hash-check] [--force <id>]... [--force-reason <text>]
   releases --repo <path> [--config <path>]
   release-dispatch --repo <path> --pr <number> --workflow-file <file>... --ref <ref>
+  release-status --repo <path> [--component <name>]
+  release-prepare --repo <path> [--component <name>] --version <x.y.z> --notes-file <path> [--date <YYYY-MM-DD>]
+  release-cut --repo <path> [--component <name>] (--expect-status-hash <hash> | --skip-hash-check) [--wait <seconds>] [--version <x.y.z>]
   rename-default-branch --repo <path> --branch <current-name> --to <new-name>
 
 Every command prints JSON to stdout.`);
@@ -314,6 +431,15 @@ if (isMain) {
     case 'release-dispatch':
       cmdReleaseDispatch(rest);
       break;
+    case 'release-status':
+      cmdReleaseStatus(rest);
+      break;
+    case 'release-prepare':
+      cmdReleasePrepare(rest);
+      break;
+    case 'release-cut':
+      cmdReleaseCut(rest);
+      break;
     case 'rename-default-branch':
       cmdRenameDefaultBranch(rest);
       break;

package/lib/apply.mjs

@@ -198,8 +198,15 @@ export function clearReleasePendingLabel(ownerRepo, prNumber) {
   return r.ok ? { ok: true } : { ok: false, error: r.stderr };
 }
 
+// `--repo` is not optional here even though `gh` would infer it: the CLI is
+// invoked with `--repo <path>` pointing at an arbitrary target repo, which is
+// routinely NOT the process's cwd. Without it, `gh` resolves the repo from
+// whatever directory the agent happened to be in and dispatches a release in
+// the wrong repository — silently, since a successful dispatch elsewhere still
+// exits 0. ownerRepo was already threaded in for exactly this and was being
+// ignored.
 export function dispatchReleaseWorkflow(ownerRepo, skillWorkflowFile, ref) {
-  const r = spawnArgs('gh', ['workflow', 'run', skillWorkflowFile, '--ref', ref]);
+  const r = spawnArgs('gh', ['workflow', 'run', skillWorkflowFile, '--ref', ref, '--repo', ownerRepo]);
   return r.status === 0 ? { ok: true } : { ok: false, error: r.stderr };
 }