Delete a leftover only after confirming its commit is reachable from main.

August 7, 2026 · View on GitHub

This document records the configuration that gates releases of bmad-module-skill-forge. It exists so a future maintainer (including future-you) can audit, restore, or extend the pipeline without reverse-engineering GitHub settings.

For background on GitHub rulesets vs legacy branch protection, see the GitHub ruleset docs.

Branch Protection on `main`

main is gated by a GitHub repository ruleset (not legacy branch protection). The legacy "Settings → Branches → Branch protection rules" surface returns 404 for this repo.

Ruleset: Default — id 13855503 — applies to ~DEFAULT_BRANCH (currently main) — enforcement active.

Active rules (5):

Rule	Effect
`deletion`	Branch cannot be deleted.
`non_fast_forward`	Force-push blocked.
`pull_request`	Requires ≥ 1 approving review; `require_code_owner_review: true` (see CODEOWNERS note below); merge/squash/rebase allowed.
`code_quality`	Blocks merge on `severity: errors` from GitHub code-quality checks.
`required_status_checks`	Merge blocked until all seven `quality.yaml` checks pass (names below).

Required status checks (8): sourced from .github/workflows/quality.yaml job keys. Matrix jobs expand to jobname (matrix-value):

prettier
eslint
markdownlint
validate (ubuntu-latest)
validate (windows-latest)
python (ubuntu-latest)
python (windows-latest)
docs-links

Coupling with quality.yaml: if that workflow renames a job or changes the strategy.matrix.os for validate or python, the ruleset's required_status_checks list must be updated in lock-step — otherwise merges to main will either block on a check name that no longer reports, or silently pass without the renamed check. Update both in the same PR.

strict_required_status_checks_policy: false — PR branches are not forced to be up-to-date with main before merging. This avoids constant rebases on a low-traffic repo. Flip to true if concurrent merges start producing logical conflicts the checks can't catch.

CODEOWNERS note: the pull_request rule has require_code_owner_review: true, but no .github/CODEOWNERS file exists in the repo today. GitHub treats the code-owner requirement as vacuously satisfied when the file is absent, so this setting is currently a no-op — the only active review gate is required_approving_review_count: 1. If a CODEOWNERS file is added later, make sure the listed owners can actually approve PRs from other authors. GitHub's universal rule is that a PR author cannot approve their own PR — so a CODEOWNERS file that lists only a solo maintainer would deadlock every PR that maintainer opens (they'd be the sole eligible code-owner reviewer but also the author).

Bypass actors: RepositoryRole actor_id=5 (Admin), bypass_mode: pull_request. Admins can bypass the ruleset only via a pull request, never via direct push. This preserves non_fast_forward and the required-checks gate for the github-actions[bot] account that the future release.yaml workflow (Story 3.1) will use to push tags and commits to main. Do not add a bot-specific bypass; it would defeat the whole purpose of this ruleset.

Inspect current state

gh api repos/armelhbobdad/bmad-module-skill-forge/rulesets/13855503

Restore from a saved baseline

A JSON baseline captured before any change can be replayed via:

# Extract the full set of fields required by a ruleset PUT from a saved baseline.json.
# PUT replaces the resource wholesale — omitting any of these fields either 422s or
# silently resets them server-side. `bypass_actors` is optional (empty array is the
# default) but is included here to preserve the admin-via-PR bypass.
jq '{name, target, enforcement, conditions, rules, bypass_actors}' baseline.json > /tmp/restore.json

gh api --method PUT \
  repos/armelhbobdad/bmad-module-skill-forge/rulesets/13855503 \
  --input /tmp/restore.json

The GitHub ruleset API uses PUT (not PATCH) for updates, and the rules array is replaced wholesale — it is not merged server-side. Always fetch current state, modify the in-memory copy, and PUT the complete list.

Release Environment

The publish job is gated by a GitHub deployment environment with a required-reviewer rule (not by workflow logic). A job declaring environment: release pauses until a listed reviewer clicks "Approve and deploy" in the Actions UI.

Environment: release — id 14347249917 — created 2026-04-20.

Setting	Value
`wait_timer`	`0` (no artificial delay; approval is the only gate)
`prevent_self_review`	`false` — see rationale below
`reviewers`	`armelhbobdad` (user id `132626034`), 1 approver
`deployment_branch_policy`	`custom_branch_policies: true`, list: `main` only
Environment-scoped secrets	`0` (invariant — see "No secret is scoped to this environment" note below)
Cost	`$0` on public-repo tier (environments, required reviewers, and branch policies are free for public repositories)

prevent_self_review: false — correctness constraint, not a loosened control. Solo-maintainer setups cannot self-approve when this is true, so the gate would deadlock on any maintainer-triggered publish. The value flips to true the moment a second reviewer joins — do not leave it loose by inertia.

No secret is scoped to this environment. The repo no longer carries an NPM_TOKEN secret at any scope (removed in Story 6.3 post-v1.0.0 once OIDC trusted publishing was operationally proven by the v1.0.0 launch). The invariant: the release env must have zero environment-scoped secrets, and the repo must have zero NPM_TOKEN-shaped secrets at any scope. If a future change scopes any secret to this environment, or if an NPM_TOKEN secret is ever re-added at repo scope, re-audit whether the OIDC trusted-publisher path is still in force — the OIDC path SHOULD be self-sufficient and a re-added token is a signal that something has regressed off the canonical path.

Audit command. Both halves of the invariant are machine-checkable:

# Repo-scope: expect 0
gh secret list --repo armelhbobdad/bmad-module-skill-forge | grep -ci npm_token

# Env-scope: expect {"total_count":0,"secrets":[]}
gh api repos/armelhbobdad/bmad-module-skill-forge/environments/release/secrets

Coupling with npm trusted publishing (Story 1.3). The npm trusted publisher binds on four fields — organization=armelhbobdad, repository=bmad-module-skill-forge, workflow filename=release.yaml, environment=release. The environment name above is load-bearing: any rename here must be accompanied by a matching npm-side update in the same change, or the next publish returns 404.

Inspect current state

# Environment itself (reviewers, branch-policy shape, prevent_self_review)
gh api repos/armelhbobdad/bmad-module-skill-forge/environments/release

# Allowed deployment branches (expect: one entry, name "main")
gh api repos/armelhbobdad/bmad-module-skill-forge/environments/release/deployment-branch-policies

# Environment-scoped secrets (expect: zero)
gh api repos/armelhbobdad/bmad-module-skill-forge/environments/release/secrets

Restore / re-apply

Two-call pattern — the environment and its branch-policy list are separate resources. Creating the environment alone with custom_branch_policies: true leaves the allow-list empty, which rejects every dispatch; the second call is mandatory.

# (1) Create or update the environment with the required-reviewer gate
gh api --method PUT repos/armelhbobdad/bmad-module-skill-forge/environments/release --input - <<'JSON'
{
  "wait_timer": 0,
  "prevent_self_review": false,
  "reviewers": [{ "type": "User", "id": 132626034 }],
  "deployment_branch_policy": {
    "protected_branches": false,
    "custom_branch_policies": true
  }
}
JSON

# (2) Add main to the allowed deployment branches.
#     Returns HTTP 422 ("already_exists") if main is already on the list —
#     safe to ignore on re-apply. To pre-check:
#     gh api repos/armelhbobdad/bmad-module-skill-forge/environments/release/deployment-branch-policies
gh api --method POST repos/armelhbobdad/bmad-module-skill-forge/environments/release/deployment-branch-policies --input - <<'JSON'
{ "name": "main" }
JSON

Temporarily allowing a feature branch

A release workflow that declares environment: release will be rejected from any branch not on the allow-list. For legitimate validation cuts from a feature branch (Story 3.2's alpha cut is the canonical case), widen the allow-list for the duration of the test and tighten it back immediately:

# Allow the feature branch and capture the returned policy id into a shell var.
# Using command substitution + --jq .id avoids the "eyeball the JSON and paste
# the id later" footgun — if the POST succeeds, $POLICY_ID is ready for the revoke.
POLICY_ID=$(gh api --method POST \
  repos/armelhbobdad/bmad-module-skill-forge/environments/release/deployment-branch-policies \
  --input - --jq .id <<'JSON'
{ "name": "feat/my-validation-branch" }
JSON
)
echo "POLICY_ID=$POLICY_ID"  # confirm a numeric id was captured before proceeding

# ... run the validation cut, approve via the reviewer UI, confirm publish ...

# Revoke immediately — the allow-list must return to { main } before leaving the session.
# Quote the expansion so the shell never interprets the id as a redirection token.
gh api --method DELETE \
  "repos/armelhbobdad/bmad-module-skill-forge/environments/release/deployment-branch-policies/$POLICY_ID"

Leaving a feature branch on the allow-list is an unguarded hole — any later workflow_dispatch from that branch would be able to reach the publish path. Treat the revoke as the last step of the validation, not a follow-up.

npm Trusted Publisher

The future release.yaml workflow (Story 3.1) publishes to npm via OIDC trusted publishing — no NPM_TOKEN is consulted during the publish step, and every published version carries an auto-attached SLSA Build Level 2 provenance attestation. For this to work, the npm package bmad-module-skill-forge has a trusted-publisher entry on npmjs.com that binds on four fields exactly matching what the workflow asserts at run time. A mismatch on any field causes an opaque 404 at publish time — the error ("npm could not match your workflow run") surfaces the failure class but does not name which of the four fields is wrong.

Registered: 2026-04-20 by armelhbobdad.

Field	Value
Publisher type	`GitHub Actions`
Organization/user	`armelhbobdad`
Repository	`bmad-module-skill-forge`
Workflow filename	`release.yaml`
Environment	`release`

Inspect current state: visit the npm package settings for bmad-module-skill-forge → Settings tab → Trusted Publisher section (npm UI as of 2026-04-20; if the tab is reorganised later, the section still lives on the package Settings page). Modification requires 2FA re-entry on the maintainer account. No CLI or public API for programmatic inspection of Trusted Publisher state exists as of 2026-04-20 — drift detection is UI-only until npm exposes one.

Case-sensitive. All four fields above use the exact lowercase forms shown; npm's matcher is an exact-string comparison. Do not capitalize on re-registration even if GitHub's UI surfaces a display-form with capitals.

Rename coupling — the four fields are load-bearing. Renaming OR deleting the release GitHub environment (see § Release Environment), renaming or moving release.yaml within .github/workflows/, or flipping the extension between .yaml and .yml each require matching updates in the same PR to: (a) the npm-side Trusted Publisher, (b) the Registered table above, and (c) the ## Release Process enumeration in README.md (which names both release and the Trusted Publisher). Skipping any of these produces an opaque 404 on the next publish — the error names the failure class, not the specific field.

Pre-registration inversion. This entry was registered before release.yaml was authored (Story 3.1). The first live validator of the full OIDC chain is Story 3.2's alpha cut. If that cut's publish step 404s, open a three-way comparison: (1) the npm Settings tab, (2) the workflow YAML's name / on / jobs.<id>.environment lines, and (3) the Registered table above. The table is the ground truth because it captured the values at npm-save time — compare both the npm record and the workflow header against the table, never the workflow against itself (verifying the workflow against its own header will silently confirm a typo).

NPM_TOKEN is gone — OIDC is the only publish credential surface. The token was removed from repo-level secrets in Story 6.3 (post-v1.0.0, once OIDC trusted publishing was operationally proven by the v1.0.0 launch). SKF's npm publish credential surface is now OIDC-only. Future incidents requiring credential revocation involve npmjs.com's trusted-publisher config, not a repo secret. release.yaml authenticates via Trusted Publisher OIDC and continues to set NPM_TOKEN: "" explicitly in both the pre-publish dry-run step and the final publish step as defense-in-depth against a stale token being auto-picked-up by npm from the runner env — those literal empty-string assignments are not secrets.* reads and stay load-bearing regardless of the secret's presence or absence. Both sites carry a # DO NOT REMOVE — FR4 defense-in-depth inline comment so a future cleanup pass does not silently delete them; audit with grep -c 'NPM_TOKEN: ""' .github/workflows/release.yaml (expect 2). If a future OIDC incident forces a last-resort token-based re-publish path, re-adding NPM_TOKEN at repo scope is the exception-path, not the default — document the flip in the commit body, file an issue for the OIDC incident class that required it, and remove the token again the moment OIDC is restored.

Fixing a bad registration. The npm UI exposes both Edit and Delete on an existing Trusted Publisher entry (observed 2026-04-20). Prefer edit for a single-field typo; prefer delete-and-re-add if multiple fields are wrong or the edit form ever feels ambiguous. Pre-Story 3.2: there is no destructive side effect because no publish is attempted yet, and delete-and-re-add keeps the audit trail cleaner. Post-Story 3.2: a publish that fires during the delete-and-re-add window will 404 — gate any delete-and-re-add behind a manual publish freeze (pause any active release.yaml runs, confirm no tags are in-flight) before touching the entry.

Cutting a Release

The dispatch mechanics are worked end-to-end in § Cutting v1.0.0 under --tag latest. That section is a launch-specific record, but its dispatch command, two-gate sequence, and verification block are the same for every cut. The two steps below are general, apply to every cut, and have no other home — both are invisible until they bite, because the default state of each is the harmless one.

Pre-dispatch — reconcile a non-empty `## [Unreleased]`

The Restore CHANGELOG preamble step splits CHANGELOG.md at the first ## [X.Y.Z] header and treats everything above it as preamble. The generated block for the new version is therefore inserted below any prose sitting under ## [Unreleased], and the workflow neither empties that section nor warns about it. Check before dispatching:

sed -n '/^## \[Unreleased\]/,/^## \[[0-9]/p' CHANGELOG.md

If the ## [Unreleased] header is immediately followed by the first released header, there is nothing to do — that was the state at every cut through v2.0.2, which is why the interaction went unexercised for so long. If it carries prose, those entries describe work that is about to ship, and after the cut they read as unreleased directly above the release containing them.

Do not hand-edit it before dispatch. The ## [X.Y.Z] header the prose belongs under does not exist until the workflow generates it. Reconcile after publish in a normal PR: move the prose under the generated version header and leave the ## [Unreleased] header in place with an empty body — deleting the header itself breaks the section split the preamble-restore step depends on.

Prefer moving the prose over dropping it in favour of the generated list. Under conventionalcommits, test: and chore: subjects produce no generated entry at all, and one fix: subject often stands in for several distinct fixes, so the hand-written text is frequently the only record of both. v2.1.0 is the worked example: five bullets stranded, moved under ## [2.1.0] in a follow-up PR.

Post-publish — delete the bot temp branch after an admin-bypass merge

Auto-merge bot PR runs gh pr merge --auto --merge --delete-branch, so on the auto-merge path the temp branch release/bot/vX.Y.Z-<run_id> is removed when the queued merge fires. Clearing gate 2 with the PR merge button instead — admin bypass, the observed pattern for most cuts — merges the PR directly, and the queued --delete-branch never runs. The branch stays on origin.

# Expect zero once a cut is fully closed out.
git ls-remote --heads origin 'release/bot/*'

# Delete a leftover only after confirming its commit is reachable from main.
git fetch origin --quiet
git merge-base --is-ancestor <temp-branch-sha> origin/main \
  && git push origin --delete release/bot/vX.Y.Z-<run_id>

The tag anchors on the bot PR's merge commit on main, not on the temp branch (see the Create and push tag step's main-dispatch path), so deleting the branch after the merge orphans nothing. The reachability check is what distinguishes this from the tag-orphan case in § Scenario D; if the commit is not reachable, the merge did not land and the branch is still load-bearing.

Rollback Playbook

NEVER npm unpublish v1.0.0. Once bmad-module-skill-forge is published under --tag latest at v1.0.0, the version is immutable by policy (NFR6). The default rollback is npm deprecate + ship forward. See Scenario C for the narrow 72h / zero-dependents exception — which applies to pre-v1.0.0 versions only.

Scenarios A–F are recovery paths for a bad publish; Scenario G is a meta-recovery path for the release workflow itself. Each scenario follows a five-element shape: Trigger → CLI → Expected outcome → Constraints → Verification. A compact cross-reference matrix sits at the end of this section for under-pressure triage. All gh api examples in this section use name-based lookups (ruleset by name=="Default", environment by literal release) so they survive ruleset or environment re-creation.

Placeholder substitutions used throughout:

<bad> — the broken version just published (e.g. 0.10.1).
<previous_good> — the last known-good version immediately before <bad> (e.g. 0.10.0).
<next_version> — the fix version produced by the next release.yaml dispatch (e.g. 0.10.2).
<run-id> — a GitHub Actions run id visible in the Actions UI and via gh run list --workflow=release.yaml.

Scenario A — "Bad version published to `latest`, no users yet (within ~minutes)"

Trigger. Maintainer notices a defect within minutes of publish; npm view bmad-module-skill-forge dist-tags still shows <bad> on latest; download count is negligible; no dependents have pinned <bad> yet.

Note on cache lag. npm view … dist-tags reads through a CDN with multi-second to multi-minute eventual consistency. "Still shows <bad> on latest" is not an authoritative "no users yet" signal. For freshness, cross-check with npm view bmad-module-skill-forge@<bad> time --json | jq '. | to_entries | last'.

CLI.

# Flip latest back to the last known-good version.
npm dist-tag add bmad-module-skill-forge@<previous_good> latest

# Verify the flip landed.
npm dist-tag ls bmad-module-skill-forge

# Warn anyone who did install <bad> in the meantime.
npm deprecate bmad-module-skill-forge@<bad> "Pulled - use <previous_good> instead"

# Cut the fix forward via the canonical workflow (OIDC publish, SLSA-L2 provenance).
gh workflow run release.yaml -f version_bump=patch

Expected outcome. latest now resolves to <previous_good>; npm install bmad-module-skill-forge@<bad> emits a deprecation warning; the subsequent patch cut advances latest to <next_version> cleanly.
Constraints. Valid only while the blast radius is small. If any downstream has already pinned to <bad>, Scenario B applies instead — reverting latest won't reach those installs.

Verification.

npm view bmad-module-skill-forge dist-tags --json
# expected: {"latest":"<previous_good>", ...}
# Other dist-tags (e.g. "alpha") may also appear depending on prior releases.

Scenario B — "Bad version live for hours/days, users may be installing it"

Trigger. Defect discovered after <bad> has held latest long enough that download count is non-zero, or dependents may have already pinned.

CLI.

# Warn immediately — every install of <bad> now prints this string.
npm deprecate bmad-module-skill-forge@<bad> "Critical bug - use <next_version> instead"

# Cut the fix forward. release.yaml's dist-tag case-chain auto-updates `latest`
# for non-prerelease versions, so no manual `dist-tag add` is needed here.
gh workflow run release.yaml -f version_bump=patch

Expected outcome. npm install bmad-module-skill-forge starts emitting the deprecation warning; the new patch publishes cleanly; latest advances to <next_version>.
Constraints. Do NOT npm dist-tag add @<previous_good> latest in this scenario. For post-v1.0.0 releases that is an NFR6 violation (it re-exposes a deprecated version as latest); for pre-v1.0.0 it fragments user expectation and hides the fix. Ship forward via patch bump.

Verification.

# Confirm the deprecation message landed on the registry (no install required —
# `npm install` would mutate the cwd's package.json/package-lock.json).
npm view bmad-module-skill-forge@<bad> deprecated
# expected: the exact deprecation string set above ("Critical bug - use <next_version> instead")

NFR3 (rollback frequency <1/quarter post-v1.0.0) is evaluated against the frequency of Scenario B invocations — each trip through Scenario B is an NFR3 data point.

Scenario C — "Bad version within last 72h, zero downloads, zero dependents"

Trigger. A narrow eligibility window per the npm unpublish policy: less than 72 hours since publish AND zero downloads AND zero dependent packages registered on npmjs.com. All three conditions must be true. Compute the 72-hour boundary from the time.modified field of npm view bmad-module-skill-forge@<bad> --json, NOT from the responder's local clock — npm's policy engine uses its server timestamp and a drift of even a few minutes at the boundary will 422 the unpublish.

Caveat on the "zero downloads" criterion. npm's downloads API is documented as eventually consistent with up to 24–48h lag post-publish. A version can show "0 downloads" while having been installed by hundreds of CI runs in that window. When in doubt in the first 24–48 hours, treat C as Scenario B.

CLI.

npm unpublish bmad-module-skill-forge@<bad>

Expected outcome. The version disappears from npm view. But the version number is permanently burned — npm rejects any future publish of that same version string forever.

Permanent-burn warning. The version number is burned. After npm unpublish bmad-module-skill-forge@0.10.1, the next release.yaml dispatch with version_bump: patch on 0.10.0 will produce 0.10.2, not 0.10.1 again. Attempting npm version 0.10.1 --no-git-tag-version would drive the workflow's npm publish toward an npm-burned version and return 403. Treat the unpublish as a one-way jump in the version number line, not a true undo.
Constraints. This scenario does NOT apply to v1.0.0. Per NFR6, v1.0.0 is never unpublished regardless of eligibility window — use Scenario B instead. Scenario C is a pre-v1.0.0-only path.

Verification.

npm view bmad-module-skill-forge@<bad> 2>&1
# expected: npm error 404 No match found for version <bad>

Scenario D — "Tag exists but npm publish failed"

Trigger. release.yaml pushed the v* tag (tag-creation step runs before the npm publish step) and then the publish step failed — OIDC 404, tarball validation error, network drop. npm view bmad-module-skill-forge@<version> returns 404; git tag -l v<version> shows the tag locally and on origin.

CLI.

# VERIFY FIRST that npm did NOT publish — a tag-delete after a successful
# publish would orphan the npm artifact. If this returns a manifest, STOP
# and go to Scenario E.
npm view bmad-module-skill-forge@<version> 2>&1

# Tag-only recovery: clear the tag locally and on origin, then re-dispatch.
git tag -d v<version>
git push --delete origin v<version>

# Re-dispatch with the same bump input — release.yaml will produce a fresh
# clean tag and successful publish.
gh workflow run release.yaml -f version_bump=<same-input-as-before>

Expected outcome. Tag cleared from origin; re-run produces a fresh clean tag plus a successful publish under the next version number.
Constraints. Only safe if publish failed. If npm did publish, use Scenario E — tag-deletion after a successful publish leaves the npm artifact without a matching git ref.
Do-NOT clause. Never re-use the burned <version> number. release.yaml will produce the next version on redispatch (for example, re-running an alpha bump over 0.10.1-alpha.0 produces 0.10.1-alpha.1, not 0.10.1-alpha.0 again). Forcing the original version back via npm version <exact> --no-git-tag-version is out of scope for rollback.
Story 3.2 load-bearing context. The current release.yaml pushes the git tag before the npm publish step (see the Create and push tag job step vs. the Publish to npm via OIDC trusted publishing step). This ordering is pre-existing from Story 3.1 and tracked in _bmad-output/implementation-artifacts/deferred-work.md under § 3-1/3-2 code review "Create and push tag pushes the git tag BEFORE Publish to npm" as a post-v1.0.0 hardening candidate. Until that lands, Scenario D's tag-delete path is the recovery.

Verification.

# Tag gone on origin.
gh api repos/armelhbobdad/bmad-module-skill-forge/git/refs/tags/v<version> 2>&1
# expected: 404 Not Found

Scenario E — "npm publish succeeded but GitHub Release / tag push failed"

Trigger. Publish succeeded (npm view bmad-module-skill-forge@<version> returns a manifest) but one of: tag-push to origin failed (network drop, branch-protection edge case); the Create GitHub Release softprops step failed (API rate limit, auth expiry); the Push commit to main step was (correctly) skipped but the release artifact diverged from main.
Premise inversion note. In the research doc's scenario ordering, publish was assumed to happen before tag push — so publish failure was the likely branch. In the live release.yaml the ordering is reversed: the tag push runs before the npm publish. That means a publish-succeeded-but-tag-missing window is small, but real — the Create GitHub Release and Push commit to main steps still run after publish and either can fail independently. This scenario covers the post-publish-tag-or-release-missing recovery path.

CLI — tag recovery.

# Obtain the commit-sha the workflow used as its HEAD during the publish run
# (returns the SHA directly; do not grep the run log — the bump-commit echo
# line does not contain the SHA, only the post-commit confirmation does).
COMMIT_SHA=$(gh api \
  repos/armelhbobdad/bmad-module-skill-forge/actions/runs/<run-id> \
  --jq .head_sha)

# Recreate the annotated tag and push.
git tag -a v<version> "$COMMIT_SHA" -m "Release v<version>"
git push origin v<version>

CLI — GitHub Release recovery. The workflow's Generate release notes step writes to release_notes.md inside the runner; that file is not uploaded as an artifact, so it does not exist outside the run. Either scrape the body from the run log first, or use --generate-notes to let GitHub regenerate from commit subjects.

# Option A: scrape the notes body from the run log into a local file.
gh run view <run-id> --log \
  | sed -n '/^## Generate release notes/,/^##[^#]/p' \
  > release_notes.md
gh release create v<version> \
  --notes-file release_notes.md \
  --title "Skill Forge (SKF) v<version>"

# Option B: let GitHub regenerate from commit subjects (loses the curated
# changelog body but always works).
gh release create v<version> \
  --generate-notes \
  --title "Skill Forge (SKF) v<version>"

Expected outcome. Tag landed on origin pointing at the correct commit; GitHub Release page reflects the published npm artifact; npm + GitHub + git state are now consistent.
Constraints. npm state is immutable. Do NOT try to "clean up" the npm artifact so the release can be re-run from scratch. The npm artifact plus the orphaned post-recovery git state is the canonical record — NFR5 (audit-trail completeness) is satisfied by the successful npm publish plus the recovered tag and GitHub Release, not by a clean rerun.
Orphaned-commit caveat (Story 3.2 context). If the run was dispatched from a feature branch and Push commit to main was correctly skipped, the release: bump to v<version> commit lives only in the workflow run log until the recovered tag above anchors it. This is NFR12-compliant and expected pre-v1.0.0 behavior; the tag is the authoritative pointer. This is exactly the pattern observed in the Story 3.2 alpha cut (bmad-module-skill-forge@0.10.1-alpha.0, run 24714953668, tag v0.10.1-alpha.0, orphaned commit 2a57dcbd).

Verification.

# Tag resolves.
gh api repos/armelhbobdad/bmad-module-skill-forge/git/refs/tags/v<version>

# GitHub Release exists.
gh release view v<version>

# npm + GitHub provenance still match.
npm view bmad-module-skill-forge@<version> --json | jq '.dist.attestations'

Scenario F — "Suspected OIDC compromise / unauthorized publish"

Trigger (any of).
- npm view bmad-module-skill-forge time shows a publish with a timestamp no maintainer triggered.
- npm audit signatures on a published tarball reports attestation verification failure.
- A GitHub Actions run shows reviewer approval that was not given.
- npm support notifies of suspected compromise.
Immediate CLI (within minutes of detection). Revoke the OIDC trust surface before doing anything else:
- Visit https://www.npmjs.com/package/bmad-module-skill-forge → Settings tab → Trusted Publisher section → Delete the registration.
- This blocks all future OIDC publishes until re-registered, stopping any further unauthorized use of the OIDC path mid-incident.

Audit CLI.

# Full publish timeline.
npm view bmad-module-skill-forge time

# Per-version provenance shape (script-friendly).
npm view bmad-module-skill-forge@<suspect> --json \
  | jq '.dist.attestations'
# expected shape:
# {
#   "url": "https://registry.npmjs.org/-/npm/v1/attestations/bmad-module-skill-forge@<suspect>",
#   "provenance": { "predicateType": "https://slsa.dev/provenance/v1" }
# }

# Human-friendly signature-chain check. `npm audit signatures` operates on
# the cwd's installed dependency tree — running it in an empty dir returns
# "0 packages have verified attestations", which is a false-clean signal
# mid-incident. Wrap the install in a throwaway dir, ignore lifecycle
# scripts (the suspect tarball may be hostile), then audit.
mkdir -p /tmp/skf-incident-verify && cd /tmp/skf-incident-verify
npm init -y >/dev/null
npm install --ignore-scripts bmad-module-skill-forge@<suspect>
npm audit signatures
# expected: "X packages have verified attestations" with attestation count >= 1

If dist.attestations is missing or the url field points somewhere unexpected, the publish bypassed the OIDC path.

Coordination CLI. If a malicious version was actually published, contact support@npmjs.com with the version string, the attestation URL, and the Trusted Publisher registration timestamp; request a manual takedown. npm support can unpublish outside the 72-hour window for security-compromise cases.

Lockdown CLI.

# Confirm no unexpected secrets were added to the repo.
gh api repos/armelhbobdad/bmad-module-skill-forge/actions/secrets

# Confirm the write-access list is unchanged.
gh api repos/armelhbobdad/bmad-module-skill-forge/collaborators

# Review all workflows for any pull_request trigger type that could run
# attacker-controlled code with repo secrets (e.g. `types: [opened]`
# without a trusted-author gate).
grep -rn "pull_request:" .github/workflows/

Post-incident reactivation. After audit completes and root cause is identified and patched, re-register the Trusted Publisher via the npm UI with the four fields matching the table in ## npm Trusted Publisher above (organization=armelhbobdad, repository=bmad-module-skill-forge, workflow filename=release.yaml, environment=release). Re-verify via an alpha cut (dispatch release.yaml from a temporarily-allowed feature branch per the ## Release Environment § Temporarily allowing a feature branch procedure) before any stable release.
Pre-v1.0.0 context. Trusted Publisher was pre-registered on 2026-04-20 (Story 1.3). A compromise discovered pre-v1.0.0 is recoverable via delete-and-re-register with no downstream-consumer blast radius (no stable release users yet). Post-v1.0.0, the incident has downstream blast radius and the support@npmjs.com coordination path is load-bearing.
Do-NOT clause — NPM_TOKEN rotation is not OIDC incident response. Do NOT rotate NPM_TOKEN as a first response. The token is not on the OIDC path; rotating it does nothing to stop an OIDC compromise.
- If an NPM_TOKEN exists at repo scope at the time of an incident (exception-path per § npm Trusted Publisher), revoke it at https://www.npmjs.com → Access Tokens AND remove it from the repo: gh secret delete NPM_TOKEN --repo armelhbobdad/bmad-module-skill-forge. A compromised NPM_TOKEN would be a separate incident class from OIDC compromise. Expected outcomes of the delete command under incident pressure — read the response before escalating: (a) Secret deleted = success, token revoked at repo-scope; (b) could not find secret NPM_TOKEN (exit 1, 404) = no-op SAFE, the token is already absent per the post-Story-6.3 default and this is the expected normal-operation state, not a broken scope or auth issue; (c) any 401 / 403 / scope-permission error = investigate before retrying, likely a gh auth or org-permissions issue unrelated to the token's presence. Story 6.3 removed the token in 2026-04 post-v1.0.0 so outcome (b) is the default; outcome (a) only applies during the exception-path window where a temporary token re-add has already happened. During a window where OIDC is revoked AND an exception-path token is also compromised, there is no valid publish path — the repo enters lockdown until Trusted Publisher is re-registered. Document the flip in the incident post-mortem; do not publish via any stale path.

Scenario G — "release.yaml disabled, reverted, or missing from main"

Trigger. release.yaml is the single-rooted release workflow (Story 3.3 Patch A neutralized the legacy publish.yaml v* tag trigger). If release.yaml is reverted, renamed, moved, or disabled at the repo-settings level (gh workflow disable release.yaml) and someone tries to cut a release, no workflow fires. Silent no-op until a maintainer checks npm view or the Actions UI.
Detection. After any PR that touches .github/workflows/* — and before any release attempt — run:
```
gh api repos/armelhbobdad/bmad-module-skill-forge/actions/workflows \
  --jq '.workflows[] | select(.name=="Release") | {name, state, path}'
# expected: {"name":"Release","state":"active","path":".github/workflows/release.yaml"}
```
If state is not active (the GitHub Actions API reports disabled_manually when disabled via the UI or gh workflow disable), or no matching workflow is returned at all (file renamed, moved, or deleted), Scenario G applies.

Recovery CLI.

# Case 1: workflow is disabled but the file is present.
gh workflow enable release.yaml

# Case 2: the file is missing or reverted.
# Revert the offending PR via the normal branch-protection review path.
# Do NOT hand-edit main — branch protection blocks direct push anyway.
gh pr view <offending-pr-number>
# `gh pr revert` opens a NEW revert PR; it does not merge anything itself.
# Capture the URL it prints, then approve + merge that revert PR through
# the standard review path before retrying the release.
gh pr revert <offending-pr-number>
# After approval (manual review step required by branch protection):
gh pr merge <revert-pr-number> --squash

Expected outcome. release.yaml is back on main with state: "active"; next dispatch fires normally.

Prevention. Single-root invariants to spot-check after any workflow-dir PR. The globs below cover both .yaml and .yml extensions (the repo currently has at least one .yml workflow):

# Any workflow with id-token: write should be a known release/provenance workflow.
grep -l 'id-token: write' .github/workflows/*.{yaml,yml} 2>/dev/null
# expected set:
#   - docs.yaml (GitHub Pages — orthogonal to release)
#   - release.yaml (canonical)

# No `v*` push trigger should exist in any workflow — release.yaml is workflow_dispatch-only.
# Scan the 3 lines following each `push:` block for a v* tag pattern.
grep -A3 -E '^\s*push:' .github/workflows/*.{yaml,yml} 2>/dev/null \
  | grep -E "['\"]v\*['\"]"
# expected: zero matches.

Escalation path — PR-revert only. There is no out-of-band emergency hatch. Recovery flows exclusively through the Case 2 PR-revert path above: revert the offending workflow change via gh pr revert, merge through branch protection, then retry the release via release.yaml. Every release threads through branch protection + code review + OIDC Trusted Publisher, matching NFR2 and NFR3.
Constraints. Branch protection on main blocks direct pushes — recovery goes through a PR in every case. Do not attempt to sidestep branch protection to "fix" release.yaml faster; the cost of a bad release (NFR5 audit-trail breakage, NFR10 commit-trail breakage) far exceeds the cost of a normal-review PR.

Cross-reference matrix

Scenario	Trigger class	Primary CLI verb	NFR linkage
A	Fresh bad latest	`dist-tag` + `deprecate`	NFR3
B	Stale bad latest	`deprecate` + ship forward	NFR3, NFR6
C	Eligible unpublish	`unpublish`	(pre-v1.0.0 only)
D	Tag orphan (publish failed)	`tag -d` + `push --delete`	NFR12
E	Post-publish state drift	`tag -a` + `gh release create`	NFR5
F	OIDC compromise	revoke Trusted Publisher + audit	NFR7
G	`release.yaml` disabled/missing	`workflow enable` / `pr revert`	NFR5, NFR10

Baseline snapshots

The ruleset-restore snippet at the top of this document (## Branch Protection on main § Restore from a saved baseline) uses gh api --method PUT .../rulesets/<id>. That call returns 404 if the Default ruleset has been deleted, not merely edited. Keeping a recent baseline-ruleset-Default-YYYYMMDD.json on disk lets the PUT-then-POST fallback below recover from either case.

One-time capture pattern — run after any maintainer-initiated change to the ruleset or to the release environment, not on a schedule:

# Capture the current Default ruleset as a disaster-recovery baseline.
# Uses name-based lookup so the snippet survives ruleset re-creation (IDs change, names don't).
RULESET_ID=$(gh api repos/armelhbobdad/bmad-module-skill-forge/rulesets \
  --jq '.[] | select(.name=="Default") | .id')
gh api "repos/armelhbobdad/bmad-module-skill-forge/rulesets/$RULESET_ID" \
  > "_bmad-output/planning-artifacts/baseline-ruleset-Default-$(date +%Y%m%d).json"

# Capture the release environment + its branch policy list (two separate resources).
gh api repos/armelhbobdad/bmad-module-skill-forge/environments/release \
  > "_bmad-output/planning-artifacts/baseline-env-release-$(date +%Y%m%d).json"
gh api repos/armelhbobdad/bmad-module-skill-forge/environments/release/deployment-branch-policies \
  > "_bmad-output/planning-artifacts/baseline-env-release-branch-policies-$(date +%Y%m%d).json"

Baselines live in _bmad-output/planning-artifacts/ (already git-tracked, not shipped with the npm package). The filename date stamp makes the freshness of the baseline obvious at a glance.

Ruleset-deletion recovery path — PUT-then-POST. The canonical restore flow is:

Try PUT first. If the ruleset exists but drifted, this reconciles it in place.

RULESET_ID=$(gh api repos/armelhbobdad/bmad-module-skill-forge/rulesets \
  --jq '.[] | select(.name=="Default") | .id')
# Pick the most recent baseline file (the YYYYMMDD suffix is a real date
# written by the capture command above; the glob avoids hard-coding it).
BASELINE=$(ls -t _bmad-output/planning-artifacts/baseline-ruleset-Default-*.json \
  | head -1)
jq '{name, target, enforcement, conditions, rules, bypass_actors}' "$BASELINE" \
  > /tmp/restore.json
gh api --method PUT \
  "repos/armelhbobdad/bmad-module-skill-forge/rulesets/$RULESET_ID" \
  --input /tmp/restore.json

If the PUT returns 404 (ruleset was deleted, not edited), recreate via POST:

gh api --method POST \
  repos/armelhbobdad/bmad-module-skill-forge/rulesets \
  --input /tmp/restore.json

The POST body needs the same name, target, enforcement, conditions, rules, and bypass_actors fields as the PUT — all captured by the baseline snapshot above. Try PUT first; on 404, POST recreates with identical semantics. The ruleset gets a new id on re-creation (IDs are not stable across delete+create cycles); update any hard-coded id references in this document on the next planned edit pass.

For the release environment, a deletion+restore similarly uses the two-call pattern already documented at ## Release Environment § Restore / re-apply — feed the environment-level baseline JSON to the PUT .../environments/release call, then re-POST each entry from the branch-policies baseline to .../environments/release/deployment-branch-policies.

Cutting v1.0.0 under --tag latest

Trigger. The passing RC has survived a clean-environment smoke test (release-audits/v1.0.0-launch-audit.md § Story 5.2 RC Cut + Smoke Test § Decision: PASS — cleared for Story 5.3 promotion to v1.0.0 under --tag latest with manual approval); npm view bmad-module-skill-forge@rc version returns the passing RC (at Story 5.3 dispatch time: 1.0.0-rc.3); Story 5.3 is ready to promote to latest under manual approval.

CLI.

git checkout main && git pull

# Pre-dispatch sanity check (read version from remote, not local clone).
gh api repos/armelhbobdad/bmad-module-skill-forge/contents/package.json \
  --jq '.content' | base64 -d | jq -r .version
# expected: the passing RC (e.g., 1.0.0-rc.3)

# Dispatch the canonical release workflow. `version_bump: major` on
# 1.0.0-rc.N strips the prerelease suffix and produces 1.0.0 (node-semver
# inc(ver, 'major') behavior on a prerelease). `--ref main` is explicit
# (gh defaults to the repo's default branch, but any non-main ref takes
# the legacy tag-only path inside release.yaml, so pass it defensively).
gh workflow run release.yaml -f version_bump=major --ref main

# Capture the run id for monitoring + audit transcript.
RUN_ID=$(gh run list --workflow=release.yaml --limit 1 \
  --json databaseId --jq '.[0].databaseId')
gh run watch $RUN_ID

The workflow pauses at two gates that the maintainer must clear in the browser. Gate 1 requires explicit approval; gate 2 accepts either approval or admin-bypass-merge:

The release environment deployment gate (at job start). Approve via "Review deployments" → "Approve and deploy" on the run page.
The bot PR review-decision gate (after the 8 required status checks pass). EITHER approve the bot PR via the review UI, OR admin-bypass-merge via the PR merge button — both paths are accepted by release.yaml's Wait for PR approval or admin-bypass merge step. Admin-bypass-merge is the observed pattern for prior cuts (PRs #209 and #213).

Expected wall-clock: ~5–8 minutes end-to-end when both gates are approved promptly.

Expected outcome. main tip advances by 2 commits (the release: bump to v1.0.0 commit on the bot temp branch release/bot/v1.0.0-<run_id>, plus the merge commit from the auto-merged or admin-bypass-merged bot PR); jq -r .version package.json → 1.0.0; jq -r '.plugins[0].version' .claude-plugin/marketplace.json → 1.0.0; npm view bmad-module-skill-forge dist-tags.latest → 1.0.0 (flipped from the prior stable, e.g. 0.10.0); rc dist-tag UNCHANGED at the prior RC; SLSA L2 provenance attached (NFR4); GitHub Release v1.0.0 with prerelease: false (NFR6 threshold — 1.0.0 contains no alpha|beta|rc substring); tag v1.0.0 anchors on the bot PR's merge commit per Story 3.4 P9 (the tag is annotated, so git rev-parse 'v1.0.0^{}' gives the commit SHA to compare against main tip).
Constraints.
- Execute ONLY after the RC audit § Sign-off is populated AND the smoke-test Decision is PASS.
- The cut is IRREVERSIBLE — once npm publish --tag latest succeeds for 1.0.0, NFR6 forbids unpublish regardless of eligibility window. Rollback is npm deprecate + ship-forward (Scenarios A / B).
- The CHANGELOG reconciliation is a POST-workflow step (authored as a separate sign-off commit on feat/v1-final-signoff). Do NOT hand-edit the ## [1.0.0] - TBD placeholder BEFORE dispatch — let the workflow auto-generate its ## [1.0.0] block (which may be EMPTY when there are zero conventional-commit feat: / fix: entries between the RC and the final cut, which is the normal case), then merge the hand-curated prose into the auto-gen header's position and delete the stale placeholder in one commit.
- Do NOT pre-bump package.json or .claude-plugin/marketplace.json — the workflow's Bump version and Update marketplace.json version steps handle both atomically and own those files.
- If npm version major unexpectedly emits 2.0.0 instead of 1.0.0 on 1.0.0-rc.N, the node-semver engine behavior has regressed. Abort the dispatch and investigate before retry — a workflow override (npm version 1.0.0 --no-git-tag-version) would be required in release.yaml.

Verification.

# Confirm the latest dist-tag flipped to 1.0.0.
npm view bmad-module-skill-forge dist-tags --json
# expected: {"latest":"1.0.0","alpha":"...","rc":"1.0.0-rc.N"}

npm view bmad-module-skill-forge@latest version
# expected: 1.0.0

# Confirm SLSA L2 provenance (NFR4 CRITICAL). A null attestation is a
# blocker — emergency-deprecate + cut 1.0.1 with provenance per Scenario B.
npm view bmad-module-skill-forge@1.0.0 --json | jq '.dist.attestations'
# expected: non-null object; .provenance.predicateType starts with
#           "https://slsa.dev/provenance/"

# Confirm the GitHub Release exists and is NOT a prerelease (NFR6 threshold).
gh release view v1.0.0 --json tagName,isPrerelease
# expected: {"tagName":"v1.0.0","isPrerelease":false}

# Confirm the v1.0.0 tag is reachable from main (annotated tag — dereference with ^{}).
# Uses --is-ancestor so the check stays valid after subsequent commits land on main;
# pin to the recorded merge SHA if you need strict tag-anchor equivalence.
git fetch origin --tags
git merge-base --is-ancestor "$(git rev-parse 'v1.0.0^{}')" origin/main && echo OK
# expected: OK

# Confirm CHANGELOG reconciliation after the sign-off commit lands on main.
grep -c '^## \[1\.0\.0\] - TBD' CHANGELOG.md    # expected: 0 (stale placeholder gone)
grep -cE '^## \[1\.0\.0\]' CHANGELOG.md         # expected: 1 (one reconciled block)
grep -cE '^## \[1\.0\.0\]\(https' CHANGELOG.md  # expected: 1 (compare-URL header survived)

NFR6 immutability activation is the npm publish --tag latest success timestamp for 1.0.0, recorded verbatim in release-audits/v1.0.0-launch-audit.md § Story 5.3 v1.0.0 Final Cut § NFR6 v1.0.0 immutability activation. For Story 5.3's dispatch, that instant was 2026-04-23T18:56:39Z. From that moment, v1.0.0 is forever-burned — npm deprecate + ship-forward is the only rollback path.

The release environment + bot PR approval-or-admin-bypass-merge pattern is the canonical flow for all main-dispatched cuts since Story 3.4 (GitHub issue #198, PR #199): the release commit is pushed to a temp branch release/bot/vX.Y.Z-<run_id>, a bot PR is opened against main, the 7 required status checks are force-triggered against the temp branch via workflow_dispatch, and the merge is gated behind maintainer approval at both the release environment gate and the PR review-decision gate. Non-main dispatches (feature-branch alpha cuts) skip the PR dance entirely and keep the legacy tag-only behavior.

Post-publish verification (NFR9)

Cross-platform install verification for any cut is performed by the install-smoke.yaml workflow, not by release.yaml itself. Dispatch it within 1 hour of publish per NFR9:

gh workflow run install-smoke.yaml -f version=latest --ref main

The workflow fans a workflow_dispatch input over ubuntu-latest, windows-latest, and macos-latest, running npx --yes bmad-module-skill-forge@<version> --version on each runner. A clean three-leg run is the canonical post-publish evidence. Any failing leg routes through the Rollback Playbook § Scenario B (deprecate + ship vX.Y.Z+1).

Where the evidence lives. For a routine release the workflow run is the record — the dispatch satisfies NFR9 on its own and no audit artifact is written. Launch cuts additionally transcribe the run URL and matrix table into a per-launch audit artifact under release-audits/; v1.0.0-launch-audit.md § Story 5.4 Post-Publish Verification is the worked example and remains the only such artifact. Do not append routine releases to it — each audit file is a forensic record scoped to the launch that produced it.