@natjswenson/shipflow 0.3.2 → 0.4.0

package/package.json

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

@@ -81,13 +81,33 @@
       "pattern": "always with the explicit\\s+`@latest` tag, never bare",
       "rationale": "Self-discovered 2026-07-15 during PAT-wiring dogfood on claude-skills itself: a bare `npx -y @natjswenson/shipflow <command>` silently resolved a stale global install (0.2.0) instead of fetching the current version from the registry, with no warning — meaning every fix through 0.2.5 (including the Critical template-injection fix) was silently skipped. Every CLI invocation in this file must pin @latest."
     },
+    {
+      "id": "collateral-must-be-named-before-cutting",
+      "pattern": "[Nn]ever run `release-cut` without naming that list to the user first",
+      "rationale": "A dev -> main promotion is atomic and carries ALL of dev, so cutting a release for one named component also releases every other component sitting bumped-but-untagged on dev. That is the worst failure this flow has — the user asked for one thing and got several, with tags and npm publishes that cannot be un-cut. The collateral list must be spoken aloud before the irreversible step, not merely present in JSON the agent may skim past."
+    },
+    {
+      "id": "tag-read-back-is-the-only-proof",
+      "pattern": "A dispatched workflow, a merged PR and a green check are \\*\\*not\\*\\* a release",
+      "rationale": "Every intermediate signal in the release path can succeed while the tag is never cut — a dispatch exits 0 for a run that later fails, a promotion can merge while the release job errors, and _release.yml deliberately no-ops when a tag already exists. The only evidence a release happened is the tag fetched back from origin, which is why release-cut polls for it and why the agent must not report success from anything else."
+    },
+    {
+      "id": "zero-major-bump-cap-is-the-users-call",
+      "pattern": "going to 1\\.0\\.0 is a\\s+release decision, never a commit message",
+      "rationale": "Conventional-commit tooling maps a breaking change to a major bump, which for an 0.x component means silently declaring 1.0.0 — an API-stability promise no commit message is entitled to make on the maintainer's behalf. suggestBump caps it at minor and reports capped: true so the promotion is offered, never taken."
+    },
+    {
+      "id": "prepare-isolated-from-unrelated-work",
+      "pattern": "throwaway git worktree",
+      "rationale": "A real repo's working tree routinely holds unrelated uncommitted work from parallel sessions — this monorepo's did, including an entire untracked skill, while this feature was written. Branching and staging under that tree is how someone else's in-flight work gets swept into a release commit. The isolated worktree makes that structurally impossible rather than relying on careful pathspecs."
+    },
     {
       "id": "ambiguous-pattern-no-silent-pick",
       "pattern": "present all 3 (templates|patterns).{0,60}ask the user to choose",
       "rationale": "Ambiguous/greenfield autodetection must never silently pick a workflow pattern — mirrors the existing protectionOwner disambiguation precedent (ambiguous-protection-owner-prompt)."
     }
   ],
-  "cli_commands_referenced": ["detect", "plan", "apply", "releases", "release-dispatch", "rename-default-branch"],
+  "cli_commands_referenced": ["detect", "plan", "apply", "releases", "release-dispatch", "release-status", "release-prepare", "release-cut", "rename-default-branch"],
   "_baseline_comment": "Baseline eval sets: deterministic, offline, $0 checks pinned against artifacts from real local runs. These gate `ci / shipflow` alongside the unit tests. Every entry names the test that enforces it so tools/lint_baseline.py can verify the declaration is not aspirational.",
   "baseline": [
     {

package/templates/dev-main-promotion/dev-to-main-automerge.yml.tmpl

@@ -24,9 +24,18 @@ on:
     types: [opened, reopened, synchronize, closed]
     branches: [{{MAIN_BRANCH}}]
 
-permissions:
-  contents: write
-  pull-requests: write
+# Deny by default at the workflow level, grant per job. A workflow-level grant
+# applies to every job in the file, including ones added later that never
+# needed it — which is why zizmor's excessive-permissions rule flags it, and
+# why the fix is to scope rather than to waive.
+#
+# `contents: write` is dropped entirely, not moved. `gh pr merge --auto` only
+# *enables* native auto-merge, a pull-requests operation; GitHub performs the
+# merge itself afterwards, under its own automation rather than this token. The
+# grants below are what matters when releaseCredential is left as GITHUB_TOKEN
+# — where a real PAT is configured (the supported setup, see above), the
+# workflow token's permissions do not apply to these steps at all.
+permissions: {}
 
 jobs:
   # Enables native GitHub auto-merge on open/reopen/synchronize — this job
@@ -39,6 +48,8 @@ jobs:
       github.event.action != 'closed' &&
       github.event.pull_request.head.ref == '{{DEV_BRANCH}}'
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
     steps:
       - name: Enable auto-merge
         run: gh pr merge --auto {{MERGE_FLAG}} "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}"

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

@@ -24,9 +24,15 @@ on:
     types: [opened, reopened, synchronize, closed]
     branches: [{{MAIN_BRANCH}}]
 
-permissions:
-  contents: write
-  pull-requests: write
+# Deny by default at the workflow level, grant per job. A workflow-level grant
+# applies to every job in the file, including ones added later that never
+# needed it — which is why zizmor's excessive-permissions rule flags it, and
+# why the fix is to scope rather than to waive.
+#
+# `contents: write` is dropped entirely, not moved. `gh pr merge --auto` only
+# *enables* native auto-merge, a pull-requests operation; GitHub performs the
+# merge itself afterwards, under its own automation rather than this token.
+permissions: {}
 
 jobs:
   # Enables native GitHub auto-merge on open/reopen/synchronize — this job
@@ -39,6 +45,8 @@ jobs:
       github.event.action != 'closed' &&
       startsWith(github.event.pull_request.head.ref, '{{HOTFIX_BRANCH_PREFIX}}')
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
     steps:
       - name: Enable auto-merge
         run: gh pr merge --auto {{MERGE_FLAG}} "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}"

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

@@ -15,8 +15,11 @@ on:
     types: [closed]
     branches: [{{MAIN_BRANCH}}]
 
-permissions:
-  contents: write
+# Deny by default at the workflow level, grant per job — a workflow-level grant
+# applies to every job in the file, including ones added later that never needed
+# it. `contents: write` is genuinely required here (this job pushes a merge
+# commit), so it is scoped to the job rather than dropped.
+permissions: {}
 
 jobs:
   merge-back-to-dev:
@@ -24,6 +27,9 @@ jobs:
       github.event.pull_request.merged == true &&
       startsWith(github.event.pull_request.head.ref, '{{HOTFIX_BRANCH_PREFIX}}')
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
       - uses: actions/checkout@v4
         with:

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

@@ -24,9 +24,15 @@ on:
     types: [opened, reopened, synchronize, closed]
     branches: [{{MAIN_BRANCH}}]
 
-permissions:
-  contents: write
-  pull-requests: write
+# Deny by default at the workflow level, grant per job. A workflow-level grant
+# applies to every job in the file, including ones added later that never
+# needed it — which is why zizmor's excessive-permissions rule flags it, and
+# why the fix is to scope rather than to waive.
+#
+# `contents: write` is dropped entirely, not moved. `gh pr merge --auto` only
+# *enables* native auto-merge, a pull-requests operation; GitHub performs the
+# merge itself afterwards, under its own automation rather than this token.
+permissions: {}
 
 jobs:
   # Enables native GitHub auto-merge on open/reopen/synchronize — this job
@@ -39,6 +45,8 @@ jobs:
       github.event.action != 'closed' &&
       startsWith(github.event.pull_request.head.ref, '{{RELEASE_BRANCH_PREFIX}}')
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
     steps:
       - name: Enable auto-merge
         run: gh pr merge --auto {{MERGE_FLAG}} "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}"

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

@@ -15,8 +15,11 @@ on:
     types: [closed]
     branches: [{{MAIN_BRANCH}}]
 
-permissions:
-  contents: write
+# Deny by default at the workflow level, grant per job — a workflow-level grant
+# applies to every job in the file, including ones added later that never needed
+# it. `contents: write` is genuinely required here (this job pushes a merge
+# commit), so it is scoped to the job rather than dropped.
+permissions: {}
 
 jobs:
   merge-back-to-dev:
@@ -24,6 +27,9 @@ jobs:
       github.event.pull_request.merged == true &&
       startsWith(github.event.pull_request.head.ref, '{{RELEASE_BRANCH_PREFIX}}')
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
       - uses: actions/checkout@v4
         with:

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

@@ -28,9 +28,15 @@ on:
     types: [opened, reopened, synchronize, closed]
     branches: [{{MAIN_BRANCH}}]
 
-permissions:
-  contents: write
-  pull-requests: write
+# Deny by default at the workflow level, grant per job. A workflow-level grant
+# applies to every job in the file, including ones added later that never
+# needed it — which is why zizmor's excessive-permissions rule flags it, and
+# why the fix is to scope rather than to waive.
+#
+# `contents: write` is dropped entirely, not moved. `gh pr merge --auto` only
+# *enables* native auto-merge, a pull-requests operation; GitHub performs the
+# merge itself afterwards, under its own automation rather than this token.
+permissions: {}
 
 jobs:
   # Enables native GitHub auto-merge on open/reopen/synchronize — this job
@@ -41,6 +47,8 @@ jobs:
   auto-merge:
     if: github.event.action != 'closed'
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
     steps:
       - name: Enable auto-merge
         run: gh pr merge --auto {{MERGE_FLAG}} "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}"