@natjswenson/shipflow 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -2,21 +2,137 @@
 
 All notable changes to `@natjswenson/shipflow` are documented here.
 
-## 0.3.2 (2026-07-28) — actually render the README on npmjs.com
-
-- **Fixed: the npm page still showed "No README data found" after 0.3.1.** That
-  release put README.md, LICENSE and CHANGELOG.md into the tarball (verified by
-  downloading it), which fixed what `npm install` delivers — but not the website.
-  npm reads README.md to populate the registry manifest's `readme` field when it
-  builds the publish manifest, which happens BEFORE the package's own `prepack`
-  hook runs. So the tarball had the file and the registry record did not.
-  Worse than merely empty: the stored value was the literal string
-  `ERROR: No README data found!`, and npmjs.com falls back to reading the
-  tarball only when that field is *absent* (compare `zod`, which renders fine
-  with no packument readme at all), so the error string kept winning.
-  The release workflow now stages the three files into the package directory
-  before `npm publish` is invoked at all, rather than relying on `prepack`.
-  Code unchanged.
+## 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
+  every job in the file got them whether it needed them or not.** zizmor flags
+  this as `excessive-permissions` (High), and it was failing this repo's own
+  `security / workflows` gate on `dev-to-main-automerge.yml`. All six templates
+  now deny by default (`permissions: {}`) and grant per job.
+
+  A workflow-level grant is not just untidy — it silently extends to jobs added
+  later that were never reviewed for it. Scoping is the fix; waiving the rule
+  would have kept the finding *and* the exposure.
+
+- **`contents: write` is dropped from the auto-merge workflows entirely, not
+  moved.** `gh pr merge --auto` only *enables* native auto-merge, which is a
+  pull-requests operation; GitHub performs the merge itself afterwards under its
+  own automation rather than this token. Those workflows now grant
+  `pull-requests: write` to the two jobs that call `gh`, and nothing else.
+
+  Where `release.releaseCredential` names a real PAT (the supported setup), the
+  workflow token's permissions never applied to those steps in the first place.
+  These grants are what matters for a repo that left the credential defaulted to
+  `GITHUB_TOKEN`.
+
+### Fixed
+
+- **The gitflow merge-back workflows could not open their own fallback PR.**
+  `release-merge-back` and `hotfix-merge-back` granted only `contents: write`,
+  but their "on any failure, open a PR for manual resolution" step calls
+  `gh pr create` — which needs `pull-requests: write`. Under a defaulted
+  `GITHUB_TOKEN` that step would have failed exactly when it was needed most:
+  after a merge conflict, with nothing else left to surface it. Found while
+  scoping the permissions above, not by a report.
+
+## 0.3.2 (2026-07-28) — attempted npm-page fix; did NOT work
+
+- **Attempted and failed: making npmjs.com render the README.** 0.3.1 put
+  README.md, LICENSE and CHANGELOG.md into the tarball (verified by downloading
+  the published artifact), which fixed what `npm install` delivers. This release
+  additionally staged those files into the package directory before
+  `npm publish` was invoked, on the theory that npm populates the registry
+  manifest's `readme` field from disk at that point. **It did not work.** After
+  publishing, `npm view <pkg> readme` still returns the literal string
+  `ERROR: No README data found!` for both packages.
+  That field appears to be sticky: it was set once by an early release that had
+  no README, and republishing with one present does not overwrite it. Since
+  npmjs.com only falls back to reading the tarball when the field is *absent*
+  (compare `zod`, which renders fine with none at all), the stale error string
+  keeps winning.
+  The ineffective staging step was reverted in the release workflow; the
+  `prepack` hook stays, because the tarball fix is real and verified. **The npm
+  web page for both packages is still blank** — an open issue, likely needing
+  npm support to clear the cached field.
+  Code unchanged in both skills.
 
 ## 0.3.1 (2026-07-28) — publish the README, LICENSE and CHANGELOG to npm
 

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
 
@@ -62,7 +63,31 @@ 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, 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.
+   **If the candidate list is empty, a CI workflow has to exist before auto-merge
+   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
+   `action.yml`, reports how many majors behind each pin is, and runs actionlint
+   and zizmor before showing you anything. Two skills answering "scaffold me a CI
+   workflow" differently is worse than either answer.
+
+   > 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 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.
+   **Never silently overwrite an existing workflow file.** Present it and wait for
+   explicit confirmation before writing it — the same confirm-before-write pattern
+   as everything else in this skill.
+
+   Either way, say plainly that a fresh workflow is a starting point, 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 run successfully
+   before relying on it as one. 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.
 
 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.
@@ -116,6 +141,70 @@ 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.
+   - `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.**
+   **`collateral` is not advisory.** A `dev → main` promotion is atomic and carries all of dev, so
+   every component listed there is released by the same promotion — "release devlog" really does
+   also release them. **Never run `release-cut` without naming that list to the user first.**
+   Releasing something the user did not ask for is the worst thing this flow can do.
+
+   `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**, because releases are publish-on-merge — a
+   follow-up promotion to fix release notes is too late, the tag is already cut.
+
+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.
+
+   **`release-cut` is resumable and bounded, and it will usually return `done: false`.** The full
+   path — feature PR, checks, merge, promotion, auto-merge, 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.
+
+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.
@@ -129,6 +218,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,117 @@ 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' },
+    },
+  });
+  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,
+    });
+    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 +386,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>]
   rename-default-branch --repo <path> --branch <current-name> --to <new-name>
 
 Every command prints JSON to stdout.`);
@@ -314,6 +429,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 };
 }