@natjswenson/shipflow 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,83 @@
 
 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

package/SKILL.md

@@ -164,15 +164,23 @@ at all and `--component` may be omitted.
    - `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.**
-   **`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.
+   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
@@ -183,8 +191,9 @@ at all and `--component` may be omitted.
    ```
    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.
+   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.**
    ```
@@ -194,12 +203,25 @@ at all and `--component` may be omitted.
    `--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, 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.
+   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 —

package/bin/shipflow.js

@@ -336,6 +336,7 @@ function cmdReleaseCut(args) {
       'expect-status-hash': { type: 'string' },
       'skip-hash-check': { type: 'boolean', default: false },
       wait: { type: 'string' },
+      version: { type: 'string' },
     },
   });
   const resolved = resolveReleaseArgs(values, 'release-cut');
@@ -348,6 +349,7 @@ function cmdReleaseCut(args) {
       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);
@@ -388,7 +390,7 @@ Commands:
   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>]
+  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.`);

package/lib/release.mjs

@@ -337,11 +337,19 @@ function dirtyPaths(repoPath, relPaths) {
   return r.stdout.split('\n').map((l) => l.slice(3).trim()).filter(Boolean);
 }
 
-// Every OTHER component whose version at `dev` carries no tag. Those ride along
-// on the same dev → main promotion — a promotion is atomic and carries all of
-// dev, so "release devlog" physically also releases them. Surfacing this list
-// is not advisory: releasing a component the user never named is the worst
-// thing this engine can do, and the only defence is saying so first.
+// Every OTHER component whose version at `dev` carries no tag. A promotion is
+// atomic and carries all of dev, so these components' bumps land on `main`
+// alongside the one being released, whether or not anyone asked.
+//
+// They are NOT released by that. Since the release jobs became
+// workflow_dispatch-only, landing on main tags nothing — each of these simply
+// becomes `untagged-bump-on-main`, releasable later by an explicit `release-cut`.
+// That is a far safer default than the old behaviour, where the same promotion
+// tagged and npm-published every one of them within seconds of merging.
+//
+// It is still worth saying out loud: the user should know what their promotion
+// is moving to main, and which components are now sitting one dispatch away
+// from a release they did not ask for.
 export function collateralComponents(repoPath, config, exceptName, devRef) {
   const out = [];
   for (const name of listComponentNames(config, repoPath)) {
@@ -380,6 +388,21 @@ export function readStatus(repoPath, config, name) {
 
   const blockers = [];
   const notes = [];
+  // A shallow clone cannot answer "what is unreleased?" — and it does not fail
+  // when asked, which is the dangerous part. `git log <tag>..<ref>` excludes
+  // everything reachable from <tag>, and that exclusion needs full ancestry;
+  // in a grafted history it silently under-applies and the range returns
+  // commits that were released long ago. Observed on this repo: a depth-1
+  // checkout of main reported 1 unreleased commit for a component that a full
+  // clone correctly reported as 0 — which would have proposed a patch release
+  // for nothing. A wrong commit list also means a wrong suggestedBump, so this
+  // is a blocker rather than a note: every number below it is untrustworthy.
+  if (git(['rev-parse', '--is-shallow-repository'], { cwd: repoPath }).stdout.trim() === 'true') {
+    blockers.push({
+      id: 'shallow-clone',
+      detail: 'this is a shallow clone, so commit ranges and the bump derived from them cannot be trusted — run `git fetch --unshallow` first',
+    });
+  }
   if (!fetched || fetched.status !== 0) {
     notes.push(`could not fetch origin (${fetched?.stderr || 'unknown error'}) — versions and tags below may be stale`);
   }
@@ -419,6 +442,33 @@ export function readStatus(repoPath, config, name) {
     state = 'untagged-bump-on-main'; // never released; whatever is on main is the first release
   }
 
+  // A fact, not a state — computed independently of the branch above so it is
+  // ALSO set when lastVersion is null (a component's first release). Folding
+  // this into `state` is the bug this field exists to fix (#173): "main has an
+  // untagged bump" and "dev already carries something higher" are
+  // independently true, and a single mutually-exclusive `state` string can
+  // only ever report one of them. `cut()`'s fast path acts on `state` alone —
+  // without `devAhead`, it would dispatch a release for whatever is on main
+  // while the version actually being released sits unread on dev.
+  const devAhead = onMain.ok && onDev.ok && cmpSemver(onDev.version, onMain.version) > 0
+    ? { version: onDev.version, aheadOfMain: true }
+    : null;
+
+  // The fast path is only armed in `untagged-bump-on-main`, so this blocker is
+  // deliberately scoped to that state alone. `bump-on-dev-unpromoted` also has
+  // `devAhead` set — that is its normal, expected shape (no fast path is
+  // reachable there, nothing can be mis-tagged) — and flagging it too would
+  // permanently mark a routine state as blocked, which is how a blocker stops
+  // being read.
+  if (devAhead && state === 'untagged-bump-on-main') {
+    blockers.push({
+      id: 'dev-ahead-of-main',
+      detail: `${mainBranch} carries ${onMain.version} but ${devBranch} carries ${devAhead.version} — cutting here would tag ` +
+        `${tagFor(component, onMain.version)}, not ${tagFor(component, devAhead.version)}. Promote ${devBranch} → ${mainBranch} ` +
+        `and re-run status, or pass --version ${onMain.version} to release exactly what is on ${mainBranch}.`,
+    });
+  }
+
   const since = commitsSince(repoPath, component, lastTag, mainRef);
   const suggestion = suggestBump(since.commits, onMain.version ?? '0.0.0');
   const nextVersion = suggestion.bump && onMain.ok ? bumpSemver(onMain.version, suggestion.bump) : null;
@@ -453,6 +503,7 @@ export function readStatus(repoPath, config, name) {
     state,
     versionOnMain: onMain.version,
     versionOnDev: onDev.version,
+    devAhead,
     versionSources: onMain.sources,
     lastTag,
     commits: since.commits,
@@ -608,6 +659,55 @@ export function prepare(repoPath, config, name, version, notes, { date, featureB
   }
 }
 
+// ─── resolving the release target ────────────────────────────────────────────
+// The one place a target version is decided. Before this existed, `cut()`
+// derived it twice, ten lines apart — once preferring dev, once preferring
+// main — and those two derivations could disagree. That disagreement IS #173:
+// the fast path would tag whatever sat on main while the version actually
+// being released sat, unread, on dev. `cut()` now calls this once, before any
+// network call, and uses its result for both the dispatch and the tag it
+// waits for, so there is no longer a code path where those two can differ.
+//
+// Pure function of a `readStatus()` result plus an optional operator-supplied
+// `requestedVersion` (`--version`). `requestedVersion` is a CONFIRMATION, not
+// a bypass: it is only ever accepted when it matches a version already
+// present on `main` or `dev` in this status, so there is no value of it that
+// releases a version which isn't actually on the branch being dispatched.
+export function resolveReleaseTarget(status, requestedVersion = null) {
+  const { state, versionOnMain, versionOnDev, devAhead, component } = status;
+
+  if (state === 'untagged-bump-on-main') {
+    if (!devAhead) {
+      // The common, unambiguous case: whatever is on main is the only
+      // candidate, dev has nothing higher.
+      return { ok: true, version: versionOnMain, via: 'dispatch-on-main' };
+    }
+    if (requestedVersion === versionOnMain) {
+      // Confirmed: release exactly what is on main, knowingly leaving dev's
+      // higher version for a later, separate release.
+      return { ok: true, version: versionOnMain, via: 'dispatch-on-main', confirmed: true };
+    }
+    if (requestedVersion === versionOnDev) {
+      return {
+        ok: false,
+        error: `${versionOnDev} is on dev but not on main — a dispatch on main cannot cut it. ` +
+          `Promote dev → main first, then re-run release-status.`,
+      };
+    }
+    return {
+      ok: false,
+      error: `${component.name}: main carries ${versionOnMain} but dev carries ${versionOnDev} — ambiguous which one ` +
+        `to release, so refusing to guess. Promote dev → main and re-run release-status to release ${versionOnDev}, ` +
+        `or pass --version ${versionOnMain} to release exactly what is on main.`,
+    };
+  }
+
+  // Every other state (`clean`, `bump-on-dev-unpromoted`, `version-behind-tag`)
+  // already has a single unambiguous candidate — dev, when it carries the
+  // prepared bump, else main — matching what `cut()` used before this existed.
+  return { ok: true, version: versionOnDev ?? versionOnMain, via: 'prepared-branch' };
+}
+
 // ─── cut ─────────────────────────────────────────────────────────────────────
 // Resumable and bounded on purpose. The full path (feature PR → checks → merge
 // → promotion → auto-merge → release run → tag) routinely takes longer than a
@@ -628,7 +728,7 @@ function sleepSync(ms) {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 
-export function cut(repoPath, config, name, { waitSeconds = 240, expectStatusHash = null, skipHashCheck = false, ownerRepo, pollSeconds = 15 } = {}) {
+export function cut(repoPath, config, name, { waitSeconds = 240, expectStatusHash = null, skipHashCheck = false, ownerRepo, pollSeconds = 15, version = null } = {}) {
   const component = resolveComponent(repoPath, config, name);
   const mainBranch = config?.branches?.main ?? 'main';
   const devBranch = config?.branches?.dev ?? 'dev';
@@ -644,7 +744,14 @@ export function cut(repoPath, config, name, { waitSeconds = 240, expectStatusHas
     }
   }
 
-  const targetVersion = status.versionOnDev ?? status.versionOnMain;
+  // The ONLY place the release target is decided — see resolveReleaseTarget's
+  // own comment for why. Called before any network call, so an ambiguous
+  // three-way state (#173: main has an untagged bump AND dev carries
+  // something higher) is refused here rather than acted on by the fast path
+  // below.
+  const target = resolveReleaseTarget(status, version);
+  if (!target.ok) return { ok: false, error: target.error };
+  const targetVersion = target.version;
   const tag = tagFor(component, targetVersion);
   const branch = releaseBranchName(name, targetVersion);
   const deadline = Date.now() + waitSeconds * 1000;
@@ -653,15 +760,16 @@ export function cut(repoPath, config, name, { waitSeconds = 240, expectStatusHas
 
   // Fast path: the bump is already on main and simply was never tagged (a
   // failed or cancelled push run). No PR is needed at all — dispatch and prove.
-  if (status.state === 'untagged-bump-on-main') {
-    const already = tagExistsOnRemote(repoPath, tagFor(component, status.versionOnMain));
+  if (target.via === 'dispatch-on-main') {
+    const already = tagExistsOnRemote(repoPath, tag);
     if (already.ok && already.exists) {
-      return { ok: true, done: true, stage: 'tag', tag: tagFor(component, status.versionOnMain), note: 'already released' };
+      return { ok: true, done: true, stage: 'tag', tag, targetVersion, note: 'already released' };
     }
     const d = spawnArgs('gh', ['workflow', 'run', component.workflowFile, '--ref', mainBranch, '--repo', ownerRepo]);
     if (d.status !== 0) return { ok: false, error: `workflow dispatch failed: ${d.stderr}` };
     note('dispatch', `dispatched ${component.workflowFile} on ${mainBranch}`);
-    return waitForTag(repoPath, tagFor(component, status.versionOnMain), deadline, pollSeconds, log, ownerRepo, null);
+    const result = waitForTag(repoPath, tag, deadline, pollSeconds, log, ownerRepo, null);
+    return { ...result, targetVersion };
   }
 
   // 1. push the prepared branch
@@ -698,7 +806,7 @@ export function cut(repoPath, config, name, { waitSeconds = 240, expectStatusHas
   if (featurePr) {
     const gate = waitForChecks(ownerRepo, featurePr, deadline, pollSeconds, log);
     if (!gate.ok) return gate;
-    if (!gate.done) return { ok: true, done: false, stage: 'feature-pr', featurePr, tag, log, next: 'call release-cut again — waiting on the feature PR’s checks' };
+    if (!gate.done) return { ok: true, done: false, stage: 'feature-pr', featurePr, tag, targetVersion, log, next: 'call release-cut again — waiting on the feature PR’s checks' };
     const method = config?.mergeMethod?.featureToDevMethod ?? 'squash';
     const merged = spawnArgs('gh', ['pr', 'merge', String(featurePr), '--repo', ownerRepo, `--${method}`, '--delete-branch']);
     if (merged.status !== 0) return { ok: false, error: `gh pr merge failed on the feature PR: ${merged.stderr}` };
@@ -728,14 +836,41 @@ export function cut(repoPath, config, name, { waitSeconds = 240, expectStatusHas
   const landed = waitForMerge(ownerRepo, promotion, deadline, pollSeconds, log);
   if (!landed.ok) return landed;
   if (!landed.done) {
-    return { ok: true, done: false, stage: 'promotion-open', promotion, tag, log, next: 'call release-cut again — waiting on the promotion to auto-merge' };
+    return { ok: true, done: false, stage: 'promotion-open', promotion, tag, targetVersion, log, next: 'call release-cut again — waiting on the promotion to auto-merge' };
+  }
+
+  // 6. The promotion landing cuts NOTHING on its own. Every caller's release
+  //    job is `workflow_dispatch`-only by deliberate design, so that this line
+  //    is the single point at which a tag is ever created — one named
+  //    component, released because someone asked for it.
+  //
+  //    This is load-bearing, not ceremony: until 2026-08-02 the release jobs
+  //    also ran on `push`, and a `dev -> main` merge therefore tagged and npm-
+  //    published everything bumped on dev, seconds after merging, with no
+  //    dispatch involved. Removing `push` without adding this dispatch would
+  //    leave cut() waiting forever for a tag nobody cuts.
+  //
+  //    Safe to re-run: _release.yml no-ops on an existing tag, and its
+  //    `concurrency: release-<skill>` group serialises a resumed call behind
+  //    an in-flight one.
+  const already = tagExistsOnRemote(repoPath, tag);
+  if (!(already.ok && already.exists)) {
+    const d = spawnArgs('gh', ['workflow', 'run', component.workflowFile, '--ref', mainBranch, '--repo', ownerRepo]);
+    if (d.status !== 0) {
+      return { ok: false, error: `the promotion merged but dispatching ${component.workflowFile} failed: ${d.stderr}. Nothing is tagged; re-run release-cut to retry the dispatch.` };
+    }
+    note('dispatch', `dispatched ${component.workflowFile} on ${mainBranch} — this, not the merge, is what cuts the tag`);
   }
-  return waitForTag(repoPath, tag, deadline, pollSeconds, log, ownerRepo, promotion);
+  const result = waitForTag(repoPath, tag, deadline, pollSeconds, log, ownerRepo, promotion);
+  return { ...result, targetVersion };
 }
 
 function releaseBody(name, version, collateral) {
   const extra = collateral.length
-    ? `\n\n**This promotion also releases:** ${collateral.map((c) => `\`${c.tag}\``).join(', ')} — a promotion is atomic and carries all of dev.`
+    ? `\n\n**This promotion also moves these bumps to main** (a promotion is atomic and carries all of dev): ` +
+      `${collateral.map((c) => `\`${c.tag}\``).join(', ')}. ` +
+      `They are **not** released by merging — the release jobs are \`workflow_dispatch\`-only — but each becomes ` +
+      `\`untagged-bump-on-main\`, one \`release-cut\` away from a tag.`
     : '';
   return `Promotes \`${name}\` v${version} to main.${extra}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natjswenson/shipflow",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Scaffold a configurable dev/main branching, auto-merge, branch-cleanup, and release-tagging workflow into any repo",
   "license": "MIT",
   "author": "Nate Swenson",

package/skill-invariants.json

@@ -105,6 +105,11 @@
       "id": "ambiguous-pattern-no-silent-pick",
       "pattern": "present all 3 (templates|patterns).{0,60}ask the user to choose",
       "rationale": "Ambiguous/greenfield autodetection must never silently pick a workflow pattern — mirrors the existing protectionOwner disambiguation precedent (ambiguous-protection-owner-prompt)."
+    },
+    {
+      "id": "untagged-bump-is-not-permission-to-cut",
+      "pattern": "is not, by itself, permission to cut",
+      "rationale": "#173: `untagged-bump-on-main` collapsed two independently-true facts (main has an untagged bump; dev already carries something higher) into one state string, and the fast path acted on it without checking which one was true — silently tagging the OLDER version while a human meant the one on dev. This line is what stops an agent (or a human skimming the state table) from treating the state name alone as a green light; `devAhead` and the refusal it drives are the actual gate."
     }
   ],
   "cli_commands_referenced": ["detect", "plan", "apply", "releases", "release-dispatch", "release-status", "release-prepare", "release-cut", "rename-default-branch"],
@@ -120,6 +125,14 @@
       ],
       "update_command": "node evals/baseline/update.mjs",
       "rationale": "This monorepo dogfoods shipflow on itself, so .github/shipflow.json and the workflow rendered from it are a genuine input/output pair from a real `apply` run, and that config's renderedTemplateHashes is the receipt shipflow wrote at the time. The baseline re-runs config -> params -> render and asserts byte equality against the frozen golden, that the golden's sha256 still equals the recorded receipt, and that the frozen golden still equals the repo's live committed workflow (so the fixture cannot quietly go stale). Byte-exactness is correct here and nowhere else in the baseline suite: for a workflow file, one changed character is a behavior change to the repo's merge automation. The paired negative assertions (quote injection rejected, missing param throws, merge method actually reaches the output) stop the golden from passing while the validators rot -- the missing-param one found a real bug on its first run: a present-but-undefined param rendered the literal string 'undefined' into `branches: [...]`, installing a workflow that could never fire."
+    },
+    {
+      "id": "dev-ahead-fast-path-refused",
+      "kind": "trap",
+      "test": "tests/release.test.mjs",
+      "fixtures": [],
+      "update_command": "these are regression tests built inline against a real temp git repo (makeThreeWayRepo / makeUnpromotedRepo) — nothing to refresh",
+      "rationale": "#173: release-cut's fast path used to act on `state` alone, so when main carried an untagged bump AND dev independently carried something higher, it silently tagged the OLDER version (main's) while reporting success -- hit for real during `/release eval` on 2026-08-03. Pinned against the exact reported shape (lastTag < main < dev) plus its D2 sibling (the same ambiguity on a component's never-released first bump, which a fix scoped only to the `cmpSemver > 0` branch would leave exposed). The known-bad half: cut() must refuse before any dispatch is ever reachable, naming both versions; --version must be a confirmation validated against what is actually on the named branch, never a bare bypass; and the dev-ahead-of-main blocker must stay two-sided -- absent in `clean` and in `bump-on-dev-unpromoted` (where devAhead is normal, expected shape, not an ambiguity), or a blocker that is always on for those states stops being read."
     }
   ]
 }