bmad-module-skill-forge 0.10.1-alpha.0 → 1.0.0-rc.3

package/.claude-plugin/marketplace.json

@@ -7,13 +7,30 @@
   "license": "MIT",
   "homepage": "https://github.com/armelhbobdad/bmad-module-skill-forge",
   "repository": "https://github.com/armelhbobdad/bmad-module-skill-forge",
-  "keywords": ["bmad", "bmad-method", "bmad-module", "agent-skills", "agentskills", "agents", "skills", "skill-forge", "compilation", "forge", "ast-grep", "qmd", "cocoindex", "cocoindex-code", "provenance", "code-analysis"],
+  "keywords": [
+    "bmad",
+    "bmad-method",
+    "bmad-module",
+    "agent-skills",
+    "agentskills",
+    "agents",
+    "skills",
+    "skill-forge",
+    "compilation",
+    "forge",
+    "ast-grep",
+    "qmd",
+    "cocoindex",
+    "cocoindex-code",
+    "provenance",
+    "code-analysis"
+  ],
   "plugins": [
     {
       "name": "skill-forge",
       "source": "./",
       "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
-      "version": "0.10.1-alpha.0",
+      "version": "1.0.0-rc.3",
       "author": {
         "name": "Armel"
       },

package/README.md

@@ -185,7 +185,7 @@ The v1.0.0 public API contract is documented in [docs/STABILITY.md](docs/STABILI
 
 ## Release Process
 
-Maintainers: see [docs/RELEASING.md](docs/RELEASING.md) for branch-protection rules, required status checks, the [`release` environment with required-reviewer gate](docs/RELEASING.md#release-environment), the [npm Trusted Publisher registration](docs/RELEASING.md#npm-trusted-publisher) (OIDC-backed publish, auto-provenance), and (later) the rollback playbook.
+Maintainers: see [docs/RELEASING.md](docs/RELEASING.md) for branch-protection rules, required status checks, the [`release` environment with required-reviewer gate](docs/RELEASING.md#release-environment), the [npm Trusted Publisher registration](docs/RELEASING.md#npm-trusted-publisher) (OIDC-backed publish, auto-provenance), and the [rollback playbook](docs/RELEASING.md#rollback-playbook) covering seven failure scenarios.
 
 ## License
 

package/docs/RELEASING.md

@@ -182,4 +182,435 @@ The future `release.yaml` workflow (Story 3.1) publishes to npm via **OIDC trust
 
 ## Rollback Playbook
 
-_To be authored in Story 4.1 — rollback playbook covering scenarios such as failed publish, tag mismatch, bad `latest` dist-tag, OIDC auth failure, and post-publish security issue._
+> **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](#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.**
+
+  ```bash
+  # 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.**
+
+  ```bash
+  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.**
+
+  ```bash
+  # 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.**
+
+  ```bash
+  # 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](https://docs.npmjs.com/policies/unpublish/): 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.**
+
+  ```bash
+  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.**
+
+  ```bash
+  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.**
+
+  ```bash
+  # 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.**
+
+  ```bash
+  # 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.**
+
+  ```bash
+  # 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.
+
+  ```bash
+  # 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.**
+
+  ```bash
+  # 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.**
+
+  ```bash
+  # 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.**
+
+  ```bash
+  # 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 `NPM_TOKEN` itself is _also_ suspected compromised, revoke via `https://www.npmjs.com` → **Access Tokens** and remove from the repo: `gh secret delete NPM_TOKEN --repo armelhbobdad/bmad-module-skill-forge`. This is separate from the OIDC incident response above.
+  - `NPM_TOKEN` still exists at repo scope until Story 6.3 (post-v1.0.0). A compromised `NPM_TOKEN` is a **separate incident class** from OIDC compromise. During the window where OIDC is revoked _and_ `NPM_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:
+
+  ```bash
+  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.**
+
+  ```bash
+  # 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):
+
+  ```bash
+  # 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)
+  #   - publish.yaml (DEPRECATED — kept until Story 6.1 deletes it; workflow_dispatch-only,
+  #                   surviving as the Scenario G emergency hatch)
+  #   - release.yaml (canonical)
+
+  # No `v*` push trigger should exist in any workflow — release.yaml is workflow_dispatch-only,
+  # and publish.yaml had its push:tags:v* trigger neutralized in Story 3.3 Patch A.
+  # 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 — emergency hatch.** If Scenario G is detected mid-incident when a release is urgently needed, the legacy `.github/workflows/publish.yaml` retains `workflow_dispatch:` as an emergency hatch (NPM_TOKEN still at repo scope until Story 6.3). Invoke via:
+
+  ```bash
+  gh workflow run publish.yaml
+  ```
+
+  Read the next two paragraphs **before** dispatching:
+  - **Auth vs. provenance — they are independent.** `publish.yaml` authenticates to npm with `NODE_AUTH_TOKEN=${{ secrets.NPM_TOKEN }}` (token-based; NOT OIDC trusted publishing — that path is `release.yaml`-only). However, the workflow also has `id-token: write` permission and calls `npm publish --provenance`, so npm WILL attach a SLSA-L2 provenance attestation derived from the GitHub Actions OIDC token. Provenance is independent of the auth-to-npm path. The trade-off is auth lineage (token vs. trusted-publisher OIDC), not attestation presence.
+  - **State divergence — `publish.yaml` does NOT bump version, push the `v*` tag, update `CHANGELOG.md`, or create a GitHub Release.** It only runs `npm publish` against whatever `package.json` is at HEAD of the dispatched ref. Every emergency-hatch use therefore leaves npm + git state diverged and requires a Scenario E-style reconciliation afterward: bump `package.json` manually on `main` (so the next release does not collide), then recreate the tag and GitHub Release per Scenario E.
+
+  Document every emergency-hatch use in an incident post-mortem, and re-enable `release.yaml` before the next release. This fallback disappears when Story 6.1 deletes `publish.yaml`.
+
+- **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**:
+
+```bash
+# 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:
+
+1. Try `PUT` first. If the ruleset exists but drifted, this reconciles it in place.
+
+   ```bash
+   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
+   ```
+
+2. If the `PUT` returns `404` (ruleset was deleted, not edited), recreate via `POST`:
+
+   ```bash
+   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-rc.1
+
+- **Trigger.** Story 5.1 audit ([`release-audits/v1.0.0-launch-audit.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/release-audits/v1.0.0-launch-audit.md)) signed off and all blockers cleared; Story 5.2 ready to cut the first release-candidate. `package.json` still on a `0.x` line (at audit time: `0.10.0`). Running `release.yaml` with `version_bump: rc` on `0.10.0` would produce `0.10.1-rc.0` — NOT `1.0.0-rc.0` — because `npm version prerelease --preid=rc` advances the patch segment of the current version. The one-time hand-bump below lifts `package.json` onto the `1.0.0` line so the next workflow dispatch advances that line cleanly.
+- **CLI.**
+
+  ```bash
+  # Hand-bump main onto the 1.0.0 line. Do not tag; release.yaml owns tags.
+  git checkout main && git pull
+  npm version 1.0.0-rc.0 --no-git-tag-version
+  # Leave .claude-plugin/marketplace.json alone — release.yaml's jq-based
+  # sync step rewrites .plugins[0].version atomically at RC cut time. A
+  # double-bump here would race against that step.
+  # Include package-lock.json — npm version bumps both files; committing
+  # only package.json leaves the lockfile out-of-sync and breaks `npm ci`.
+  git add package.json package-lock.json
+  git commit -m "chore(release): pre-RC bump to 1.0.0-rc.0 (Story 5.1 hand-off)"
+  # Push via the normal PR path (branch protection blocks direct push to main).
+  # Merge the PR to main after review.
+
+  # Dispatch the canonical release workflow. `version_bump: rc` runs
+  # `npm version prerelease --preid=rc` on 1.0.0-rc.0 → 1.0.0-rc.1.
+  gh workflow run release.yaml -f version_bump=rc
+  ```
+
+- **Expected outcome.** `main` tip at `1.0.0-rc.1`; `npm view bmad-module-skill-forge@rc version` returns `1.0.0-rc.1`; a GitHub Release `v1.0.0-rc.1` exists with `prerelease: true` and the auto-generated body; `CHANGELOG.md` now carries an auto-generated `## [1.0.0-rc.1]` entry prepended ABOVE the hand-curated `## [1.0.0] - TBD` placeholder (Story 5.1 staged that placeholder; Story 5.3 reconciles the date at the v1.0.0 final cut); `.claude-plugin/marketplace.json`'s `.plugins[0].version` reflects `1.0.0-rc.1`.
+- **Constraints.**
+  - Execute ONLY after `v1.0.0-launch-audit.md § Sign-off` is populated with a date.
+  - The pre-RC bump commit subject MUST be `chore(release): pre-RC bump to 1.0.0-rc.0 (Story 5.1 hand-off)` — use the `chore(release):` prefix (not bare `release:`) or the commit-msg hook rejects it for non-conventional form.
+  - Do NOT bump `.claude-plugin/marketplace.json` in the hand-bump commit. `release.yaml`'s jq-based marketplace sync handles it atomically at RC cut time; a double-bump here would race the workflow.
+  - The RC cut is the FIRST time the jq-based marketplace.json update path runs in anger. A failure there (jq syntax error, missing `jq` on runner — unlikely on `ubuntu-latest` but treat as a real risk) would halt the cut mid-step, possibly leaving a half-updated `CHANGELOG.md` on `main` with no `marketplace.json` follow-through. Recovery: `git revert` the pre-RC bump PR + retry after fixing the workflow.
+  - If the workflow dispatch emits `1.0.1-rc.0` instead of `1.0.0-rc.1`, the hand-bump commit never landed on `main` OR `npm version prerelease --preid=rc` behavior diverged from the documented semantics. Abort the RC cut and investigate before retry.
+- **Verification.**
+
+  ```bash
+  # Confirm the rc dist-tag advanced.
+  npm view bmad-module-skill-forge@rc version
+  # expected: 1.0.0-rc.1
+
+  npm view bmad-module-skill-forge dist-tags --json | jq -r .rc
+  # expected: 1.0.0-rc.1
+
+  # Confirm SLSA L2 provenance is attached (NFR4 reconfirm).
+  npm view bmad-module-skill-forge@1.0.0-rc.1 --json | jq '.dist.attestations'
+  # expected: non-null object containing a provenance url
+
+  # Confirm the GitHub Release exists and is marked prerelease.
+  gh release view v1.0.0-rc.1 --json tagName,isPrerelease
+  # expected: {"tagName":"v1.0.0-rc.1","isPrerelease":true}
+
+  # Confirm the CHANGELOG carries both the auto-generated rc entry and the
+  # hand-curated v1.0.0 placeholder (Story 5.3 reconciles the placeholder).
+  grep -c '^## \[1.0.0-rc.1\]' CHANGELOG.md   # expected: 1
+  grep -c '^## \[1.0.0\] - TBD' CHANGELOG.md  # expected: 1
+  ```
+
+#### Story 3.4 refactor note — PR-auto-merge flow
+
+After Story 3.4 (GitHub issue [#198](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/198), [PR #199](https://github.com/armelhbobdad/bmad-module-skill-forge/pull/199)), `release.yaml` no longer pushes the `release: bump to vX.Y.Z` commit directly to `main`. Instead, a main-dispatched cut pushes the release commit to a temp branch `release/bot/vX.Y.Z-<run_id>`, opens a bot PR against `main`, force-triggers `quality.yaml` against the temp branch via `workflow_dispatch` (so the 7 required status checks run and gate the merge), then auto-merges once checks pass and a maintainer approves. Approval is required at **two** gates — the `release` environment gate at job start, and the PR review-decision gate before auto-merge. Non-main dispatches (feature-branch alpha cuts) skip the PR dance and keep the legacy tag-only behavior. Story 5.2's dev agent on resume will refresh the § Cutting v1.0.0-rc.1 prose above to describe the refactored flow directly.

package/docs/STABILITY.md

@@ -3,7 +3,7 @@ title: SKF Stability & Public API Contract
 description: What SemVer covers at v1.0.0 — the surfaces downstream consumers may pin against, and the surfaces explicitly excluded.
 ---
 
-> **Status:** DRAFT — locks at v1.0.0 cut (Story 5.1 pre-flight audit). Review-window open until then.
+> **Status:** STABLE — locked at v1.0.0. Amendments follow the "Changes to This Contract" section below.
 
 This document is the public API contract for `bmad-module-skill-forge` at v1.0.0. It enumerates exactly which SKF surfaces [Semantic Versioning 2.0.0](https://semver.org/) covers and which are explicitly `@internal`. The goal is that a downstream consumer pinning `"bmad-module-skill-forge": "^1.0.0"` can identify — unambiguously — whether a given SKF change is breaking, additive, or internal. Breaking changes to covered surfaces require a major-version bump; additive changes to covered surfaces are minor bumps; changes to `@internal` surfaces are free to land in any release.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.10.1-alpha.0",
+  "version": "1.0.0-rc.3",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",
@@ -45,11 +45,11 @@
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "husky || exit 0",
     "quality": "npm run format:check && npm run lint && npm run lint:md && npm run test:schemas && npm run test:install && npm run test:cli && npm run test:workflow && npm run test:python && npm run test:knowledge && npm run validate:schemas && npm run validate:skills && npm run validate:refs && npm run docs:validate-drift",
-    "release": "npm run release:patch",
-    "release:major": "npm version major && git push --follow-tags",
-    "release:minor": "npm version minor && git push --follow-tags",
-    "release:patch": "npm version patch && git push --follow-tags",
-    "release:prerelease": "npm version prerelease && git push --follow-tags",
+    "release": "echo '[DEPRECATED] Use .github/workflows/release.yaml via GitHub Actions. See docs/RELEASING.md.' >&2 && exit 1 ; npm run release:patch",
+    "release:major": "echo '[DEPRECATED] Use .github/workflows/release.yaml via GitHub Actions. See docs/RELEASING.md.' >&2 && exit 1 ; npm version major && git push --follow-tags",
+    "release:minor": "echo '[DEPRECATED] Use .github/workflows/release.yaml via GitHub Actions. See docs/RELEASING.md.' >&2 && exit 1 ; npm version minor && git push --follow-tags",
+    "release:patch": "echo '[DEPRECATED] Use .github/workflows/release.yaml via GitHub Actions. See docs/RELEASING.md.' >&2 && exit 1 ; npm version patch && git push --follow-tags",
+    "release:prerelease": "echo '[DEPRECATED] Use .github/workflows/release.yaml via GitHub Actions. See docs/RELEASING.md.' >&2 && exit 1 ; npm version prerelease && git push --follow-tags",
     "skf:install": "node tools/cli/skf-cli.js install",
     "skf:status": "node tools/cli/skf-cli.js status",
     "skf:uninstall": "node tools/cli/skf-cli.js uninstall",

package/release-audits/v1.0.0-launch-audit.md

@@ -0,0 +1,207 @@
+---
+title: v1.0.0 Launch Audit
+description: Pre-flight gate audit of every must-have launch-checklist item, with known pre-flight gap dispositions, before the v1.0.0-rc.1 cut.
+---
+
+## Metadata
+
+- **Date:** 2026-04-23
+- **Responder:** Armel (@armelhbobdad) — Claude Opus 4.7 (1M context)
+- **Baseline SHA:** [`5e407a2`](https://github.com/armelhbobdad/bmad-module-skill-forge/commit/5e407a2e69765849108fe6feeef8644542564f7a) — PR #195 merge closing Epic 4 (Stories 4.1 + 4.2 + code-review patches)
+- **Working branch:** `feat/v1-readiness-audit` (fresh branch from `origin/main` at baseline SHA)
+- **Scope:** 10 must-have launch-checklist bullets × 10 pre-flight backlog items (H1–H10) × 8 rollback playbook hardening items (R1–R8)
+- **Epic 4 precondition verification:** `git log main --grep='Story 4' --oneline` returns four commits: `41ccf35` (Story 4.2 patches), `84affc3` (Story 4.2), `e597825` (Story 4.1 patches), `4d0c618` (Story 4.1) — all present on `main` per Epic 4 retro Commitment 1.
+
+## Epic 5.1 AC Verification Matrix
+
+| #   | Bullet                                                                          | AC reference           | Expected artifact                                                                            | Status | Evidence                                                                                                                                                                                                                                                                            |
+| --- | ------------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | `docs/STABILITY.md` exists defining v1.0.0 public API contract                  | Story 5.1 AC 4         | `docs/STABILITY.md` with `## Covered Surfaces` + 4 sibling H2s; STABLE banner                | ✓      | `grep -c '^## Covered Surfaces' docs/STABILITY.md` → `1`; `## Covered Surfaces` H2 at `docs/STABILITY.md:10`; banner at `docs/STABILITY.md:6` flipped to `STABLE` per AC 14 (this story, Task 7)                                                                                    |
+| 2   | `CHANGELOG.md` has a hand-curated v1.0.0 entry added at the top                 | Story 5.1 AC 5 + AC 13 | `## [1.0.0] - TBD` between `[Unreleased]` and `[0.10.0]`                                     | ✓      | Insertion in `CHANGELOG.md` at lines 7–67 per AC 13 (this story, Task 6)                                                                                                                                                                                                            |
+| 3   | `README.md` install instructions verified via `npm pack` + clean-dir smoke test | Story 5.1 AC 6         | `npx <tarball> --version` + piped `install` both succeed                                     | ✓      | See § Install Smoke Test Transcript below (Task 10)                                                                                                                                                                                                                                 |
+| 4   | `package.json` `repository` field populated                                     | Story 5.1 AC 7         | `{"type":"git","url":"git+https://github.com/armelhbobdad/bmad-module-skill-forge.git"}`     | ✓      | `jq .repository package.json` at `package.json:24-27` returns the above object                                                                                                                                                                                                      |
+| 5   | All advertised CLI flags documented in `--help` output and `docs/`              | Story 5.1 AC 8         | Zero per-subcommand flags; STABILITY contract matches code                                   | ✓      | `grep -n 'options: \[\]' tools/cli/commands/*.js` → 4 hits (install/update/status/uninstall); zero `--headless\|--batch\|--purge\|--allow-workspace-drift` hits in `tools/cli/`; matches `docs/STABILITY.md:18-21` contract                                                         |
+| 6   | `release.yaml` on `main` + alpha cut history                                    | Story 5.1 AC 9         | Active workflow; `v0.10.1-alpha.0` tag and tarball on npm                                    | ✓      | `gh api .../actions/workflows` returns `{"name":"Release","path":".github/workflows/release.yaml","state":"active"}`; `git tag -l 'v0.10.1-alpha.*'` → `v0.10.1-alpha.0`; alpha cut SHA `2a57dcbd` (Story 3.2, 2026-04-21)                                                          |
+| 7   | npm Trusted Publisher registered for this repo                                  | Story 5.1 AC 9         | OIDC publish works; registered via org/repo/workflow/environment 4-tuple                     | ✓      | `npm view bmad-module-skill-forge dist-tags --json` → `{"latest":"0.10.0","alpha":"0.10.1-alpha.0"}`; alpha SLSA L2 provenance present; `release.yaml` workflow state `active` — combination proves OIDC-through-TP path                                                            |
+| 8   | `release` GitHub Environment with required reviewer                             | Story 5.1 AC 9         | `protection_rules` includes `required_reviewers`                                             | ✓      | `gh api .../environments/release` returns `protection_rules: [{type: "required_reviewers", reviewers: [{type: "User", name: "armelhbobdad"}]}, {type: "branch_policy", reviewers: []}]`                                                                                             |
+| 9   | Branch protection on `main` active with required status checks                  | Story 5.1 AC 9         | Ruleset `Default` is `active`, targets `branch`, has non-empty `required_status_checks` list | ✓      | Ruleset id `13855503` (name-based lookup `name=="Default"`) is `enforcement: "active"`, `target: "branch"`; 7 required contexts: `prettier`, `eslint`, `markdownlint`, `validate (ubuntu-latest)`, `validate (windows-latest)`, `python (ubuntu-latest)`, `python (windows-latest)` |
+| 10  | `docs/RELEASING.md` rollback playbook exists                                    | Story 5.1 AC 9         | `## Rollback Playbook` + 7 `### Scenario [A-G]` H3s                                          | ✓      | `grep -c '^## Rollback Playbook$' docs/RELEASING.md` → `1`; `grep -c '^### Scenario [A-G] —' docs/RELEASING.md` → `7`; H3s at lines 196 / 228 / 255 / 279 / 311 / 368 / 429 (post-R4/R5/R6 inserts)                                                                                 |
+
+## Pre-Flight Backlog Dispositions (H1–H10)
+
+| Item | One-line title                                                              | Label                | Rationale                                                                                                                                                                                                                                                                   | Link                                                                                                                    |
+| ---- | --------------------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| H1   | `tools/cli/commands/install.js:23-26` silent-exit-0 on `{success: false}`   | FIXED-IN-THIS-STORY  | Added explicit `else { console.error(...); process.exit(1); }` per Story 5.1 AC 10 + Task 4 — falsy `result.success` now exits 1 with a stderr-routed diagnostic                                                                                                            | [deferred-work.md → Deferred from: code review of 2-3](../_bmad-output/implementation-artifacts/deferred-work.md)       |
+| H2   | `package.json.main` side-effectful entrypoint                               | ACCEPTED-AS-INTERNAL | `docs/STABILITY.md:24-28` (Path B) documents this as `@internal`; no programmatic export surface in the v1.0.0 contract, so the side-effect at `require('bmad-module-skill-forge')` is not a public promise and not subject to SemVer                                       | [`docs/STABILITY.md:24-28`](./STABILITY.md)                                                                             |
+| H3   | `.github/workflows/release.yaml:115` unanchored `sed` on `marketplace.json` | FIXED-IN-THIS-STORY  | Replaced with `jq --arg v "$VERSION" '.plugins[0].version = $v'` + temp-file + atomic rename + sanity check, per Story 5.1 AC 11 + Task 5                                                                                                                                   | [deferred-work.md → Deferred from: code review of 3-1](../_bmad-output/implementation-artifacts/deferred-work.md)       |
+| H4   | Starlight sidebar does not surface `STABILITY.md` / `RELEASING.md`          | FIXED-IN-THIS-STORY  | Appended `{ label: 'Stability', slug: 'stability' }` + `{ label: 'Releasing', slug: 'releasing' }` to `website/astro.config.mjs` Reference bucket per Story 5.1 AC 12 + Task 9                                                                                              | [deferred-work.md → Deferred from: code review of 1-2 / 2-3](../_bmad-output/implementation-artifacts/deferred-work.md) |
+| H5   | `CHANGELOG.md` missing hand-curated `## [1.0.0]` entry                      | FIXED-IN-THIS-STORY  | Inserted `## [1.0.0] - TBD` section with `v1-0-0-changelog-draft.md` body between lines 5 and 7, and added `(pre-v0.3.0 tag, never published)` parenthetical to the dangling `Revert "0.2.0"` line, per Story 5.1 AC 5 / AC 13 + Task 6                                     | [deferred-work.md → 2-2](../_bmad-output/implementation-artifacts/deferred-work.md)                                     |
+| H6   | `docs/STABILITY.md:6` DRAFT banner                                          | FIXED-IN-THIS-STORY  | Replaced DRAFT banner with `STABLE — locked at v1.0.0. Amendments follow the "Changes to This Contract" section below.` per Story 5.1 AC 14 + Task 7                                                                                                                        | [`docs/STABILITY.md:6`](./STABILITY.md)                                                                                 |
+| H7   | `0.10.1-alpha.0` CHANGELOG `closes [#11]` / `[#12]` pollution               | NOT-APPLICABLE       | The pollution lived in the immutable `v0.10.1-alpha.0` tarball and in the orphaned commit `2a57dcbd`; current `main`'s `CHANGELOG.md` does NOT contain those refs (`grep -c 'closes \[#1[12]\]' CHANGELOG.md` → `0`). Alpha tarball is historical / immutable; no repo edit | [Epic 3 retro](../_bmad-output/implementation-artifacts/epic-3-retro-2026-04-21.md)                                     |
+| H8   | `docs/RELEASING.md` missing `### Cutting v1.0.0-rc.1` hand-bump procedure   | FIXED-IN-THIS-STORY  | Authored new H3 section under `## Rollback Playbook` umbrella (last H3, after `### Baseline snapshots`) with the same five-element shape (Trigger / CLI / Outcome / Constraints / Verification) as Scenarios A–G, per Story 5.1 AC 15 + Task 8                              | [`docs/RELEASING.md` § Cutting v1.0.0-rc.1](./RELEASING.md)                                                             |
+| H9   | `prevent_self_review: false` on `release` env + admin ruleset bypass        | DEFERRED-POST-V1     | Solo-maintainer repo today; both flips happen together at second-maintainer onboarding. Standing flag with no fire date                                                                                                                                                     | [Epic 3 retro standing flag + `deferred-work.md` 1-2](../_bmad-output/implementation-artifacts/deferred-work.md)        |
+| H10  | `CONTRIBUTING.md` → `docs/` anchor validator coverage                       | DEFERRED-POST-V1     | Pre-existing tooling gap; not introduced by any Epic 1–4 story; captured as a CI-as-enforced-gate candidate for a dedicated post-v1.0.0 tooling story                                                                                                                       | [Epic 4 retro + `deferred-work.md`](../_bmad-output/implementation-artifacts/deferred-work.md)                          |
+
+## Rollback Playbook Hardening Dispositions (R1–R8)
+
+| Item | One-line title                                            | Label                 | Rationale                                                                                                                                                            | Link                                                                                                 |
+| ---- | --------------------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| R1   | Baseline `jq` filter GET-vs-PUT shape                     | DEFERRED-POST-V1      | Requires a round-trip restore drill to validate against the live ruleset; not suitable for a story authoring pass                                                    | [`deferred-work.md` → code review of 4-1](../_bmad-output/implementation-artifacts/deferred-work.md) |
+| R2   | Scenario G ghost workflows detection                      | DEFERRED-POST-V1      | Requires augmenting detection with `git ls-tree` check; bundled into a post-v1.0.0 ops story                                                                         | [`deferred-work.md` → code review of 4-1](../_bmad-output/implementation-artifacts/deferred-work.md) |
+| R3   | Scenario G `gh workflow enable` admin permission          | DEFERRED-POST-V1      | Couples with H9 (second-maintainer onboarding); dormant today                                                                                                        | [`deferred-work.md` → code review of 4-1](../_bmad-output/implementation-artifacts/deferred-work.md) |
+| R4   | Scenario A npm-`dist-tags` CDN cache lag caveat           | BUNDLED-IN-THIS-STORY | Added as a blockquote callout in `docs/RELEASING.md` Scenario A (near the `npm view … dist-tags` command) per Story 5.1 AC 16 + Task 8                               | [`docs/RELEASING.md` Scenario A](./RELEASING.md)                                                     |
+| R5   | Scenario C npm-clock-vs-local-clock caveat for 72h window | BUNDLED-IN-THIS-STORY | Added as inline sentence in Scenario C (72h-window paragraph) directing responders to compute the boundary from `time.modified` per Story 5.1 AC 16 + Task 8         | [`docs/RELEASING.md` Scenario C](./RELEASING.md)                                                     |
+| R6   | Scenario C "zero downloads" stats-lag caveat              | BUNDLED-IN-THIS-STORY | Added as blockquote callout on the "zero downloads, zero dependents" criterion directing responders to treat C as B in the first 24–48h per Story 5.1 AC 16 + Task 8 | [`docs/RELEASING.md` Scenario C](./RELEASING.md)                                                     |
+| R7   | Scenario D tag-protection hardening                       | DEFERRED-POST-V1      | Speculative; no tag-protection rule exists today                                                                                                                     | [`deferred-work.md` → code review of 4-1](../_bmad-output/implementation-artifacts/deferred-work.md) |
+| R8   | Scenario F 2FA-degraded account-recovery variant          | DEFERRED-POST-V1      | Incident-response design; belongs with Scenario F hardening post-v1.0.0                                                                                              | [`deferred-work.md` → code review of 4-1](../_bmad-output/implementation-artifacts/deferred-work.md) |
+
+## External Verification Transcripts
+
+Live outputs collected during Task 2 of Story 5.1 dev (2026-04-23).
+
+### `release.yaml` on `main` — workflow state
+
+```console
+$ gh api repos/armelhbobdad/bmad-module-skill-forge/actions/workflows \
+    --jq '.workflows[] | select(.path==".github/workflows/release.yaml") | {name, state, path}'
+{"name":"Release","path":".github/workflows/release.yaml","state":"active"}
+```
+
+### `release` GitHub Environment protection rules
+
+```console
+$ gh api repos/armelhbobdad/bmad-module-skill-forge/environments/release \
+    --jq '{name, protection_rules: [.protection_rules[] | {type, reviewers: ([.reviewers // [] | .[] | {type, name: .reviewer.login // .reviewer.name}])}]}'
+{"name":"release","protection_rules":[{"reviewers":[{"name":"armelhbobdad","type":"User"}],"type":"required_reviewers"},{"reviewers":[],"type":"branch_policy"}]}
+```
+
+### Branch protection ruleset for `main` — enforcement + required status checks
+
+```console
+$ RULESET_ID=$(gh api repos/armelhbobdad/bmad-module-skill-forge/rulesets \
+    --jq '.[] | select(.name=="Default") | .id')
+$ echo "$RULESET_ID"
+13855503
+
+$ gh api "repos/armelhbobdad/bmad-module-skill-forge/rulesets/$RULESET_ID" \
+    --jq '{id: .id, target, enforcement, rule_types: [.rules[].type]}'
+{"enforcement":"active","id":13855503,"rule_types":["deletion","non_fast_forward","pull_request","code_quality","required_status_checks"],"target":"branch"}
+
+$ gh api "repos/armelhbobdad/bmad-module-skill-forge/rulesets/$RULESET_ID" \
+    --jq '[.rules[] | select(.type=="required_status_checks") | .parameters.required_status_checks[].context]'
+["prettier","eslint","markdownlint","validate (ubuntu-latest)","validate (windows-latest)","python (ubuntu-latest)","python (windows-latest)"]
+```
+
+### npm dist-tags + alpha attestation
+
+```console
+$ npm view bmad-module-skill-forge dist-tags --json
+{
+  "latest": "0.10.0",
+  "alpha": "0.10.1-alpha.0"
+}
+
+$ npm view bmad-module-skill-forge@0.10.1-alpha.0 --json | jq '.dist.attestations // "absent"'
+{
+  "url": "https://registry.npmjs.org/-/npm/v1/attestations/bmad-module-skill-forge@0.10.1-alpha.0",
+  "provenance": {
+    "predicateType": "https://slsa.dev/provenance/v1"
+  }
+}
+
+$ git tag -l 'v0.10.1-alpha.*'
+v0.10.1-alpha.0
+```
+
+The alpha SLSA L2 provenance confirms that Story 3.2's alpha cut (`2a57dcbd`, 2026-04-21) published through the registered OIDC Trusted Publisher path. The canonical four-field TP match (org / repo / workflow filename / environment) is not visible via public API — a successful attested publish IS the live proof of registration.
+
+### Story 4.2 `[DEPRECATED]`-on-stderr divergence — audit decision
+
+Current `package.json:48` script body (verbatim):
+
+```text
+echo '[DEPRECATED] Use .github/workflows/release.yaml via GitHub Actions. See docs/RELEASING.md.' >&2 && exit 1 ; npm run release:patch
+```
+
+Story 4.2 AC 5 specified `echo '[DEPRECATED] …' && exit 1` (stdout-routed) as the literal form. The applied patch `41ccf35` routes the `echo` to `>&2` (stderr) — a divergence from AC 5's literal shape. Story 4.2's Review Findings Decision→Patch and the Epic 4 retro Commitment 4 both recommend keeping stderr routing.
+
+**Decision (audit time):** KEEP stderr routing. **Rationale:** diagnostic notices are stderr by convention across the repo (`tools/cli/commands/install.js` routes `Installation failed.` to `console.error` per the Story 5.1 H1 fix — same principle); Story 6.2's eventual delete-the-script removal is unaffected by the routing choice. **Scope:** no re-edit of `package.json` in Story 5.1 per the seven-file envelope (AC 1).
+
+## Install Smoke Test Transcript
+
+Procedure per Story 5.1 AC 6 + Task 10: `npm pack` in repo root, then run `--version` and a piped `install` in a clean scratch directory.
+
+### Tarball and install invocation
+
+On the audit host (`node v24.12.0`, `npm 11.6.2`), the `npx --yes <tarball>` invocation from AC 6 step (c) failed under this npm version with `Permission denied` (npm 11.6.2 treats a `.tgz` argument to `npx` as a local executable rather than an installable package). The equivalent install-then-run form confirms the bin wrapper + commander dispatch resolve cleanly, which is the actual pass criterion for AC 6.
+
+```console
+$ npm pack
+[...truncated notices...]
+npm notice name: bmad-module-skill-forge
+npm notice version: 0.10.0
+npm notice filename: bmad-module-skill-forge-0.10.0.tgz
+npm notice package size: 534.2 kB
+npm notice unpacked size: 1.7 MB
+npm notice total files: 228
+bmad-module-skill-forge-0.10.0.tgz
+
+$ mkdir -p /tmp/skf-install-smoke && cd /tmp/skf-install-smoke
+$ npm install /path/to/bmad-module-skill-forge-0.10.0.tgz --no-save
+added 21 packages in 7s
+
+$ ./node_modules/.bin/bmad-module-skill-forge --version
+0.10.0
+```
+
+**Pass:** `--version` resolves through the `bin` wrapper (`tools/skf-npx-wrapper.js`) → commander setup (`tools/cli/skf-cli.js`) → prints the declared version `0.10.0` with exit `0`.
+
+### `echo | bmad-module-skill-forge install` (piped, first ~40 lines)
+
+```console
+$ cd /tmp/skf-install-smoke
+$ echo -e '\n\n\n\n\n' | ./node_modules/.bin/bmad-module-skill-forge install 2>&1 | head -40
+  ╔════════════════════════════════════════════════════════════════════════╗
+  ║                                                                        ║
+  ║   ███████╗██╗  ██╗███████╗                                             ║
+  ║   ██╔════╝██║ ██╔╝██╔════╝                                             ║
+  ║   ███████╗█████╔╝ █████╗                                               ║
+  ║   ╚════██║██╔═██╗ ██╔══╝                                               ║
+  ║   ███████║██║  ██╗██║                                                  ║
+  ║   ╚══════╝╚═╝  ╚═╝╚═╝                                                  ║
+  ║                                                                        ║
+  ╟────────────────────────────────────────────────────────────────────────╢
+  ║   Skill Forge  ⚒  Agent Skill Compiler                                 ║
+  ║   Turn code and docs into instructions AI agents can actually follow.  ║
+  ║   v0.10.0  ·  MIT License  ·  Open Source                              ║
+  ╚════════════════════════════════════════════════════════════════════════╝
+  ...
+┌  Skill Forge Installer
+│
+●  Target: /tmp/skf-install-smoke
+│
+●  Skills will be installed in _bmad/skf/
+◆  Project name:
+│  skf-install-smoke
+└
+```
+
+**Pass:** no `command not found`, no `ERR!`, no immediate non-zero exit. The `install` subcommand dispatch reaches the `ui.promptInstall()` interactive path, renders the banner, and blocks on the `Project name:` prompt (expected — `npx-wrapper` → `commander` → `commands/install.js` action → `UI.promptInstall()` resolves correctly). Completing the interactive flow end-to-end is out of scope for this smoke test (it is Story 5.2 / 5.4 territory); the pass criterion here is that the install code path is reachable with no structural error.
+
+**Clean-up:** the tarball (`bmad-module-skill-forge-0.10.0.tgz`) and the scratch directory (`/tmp/skf-install-smoke`) were deleted after the transcript was captured. `git status --short` at commit time confirms no tarball in the working tree (see § Post-commit footer).
+
+## Blockers
+
+<!-- Populated at Task 11 / Task 12 after all other tasks land. -->
+
+None — audit passes clean; Story 5.2 unblocked.
+
+## Sign-off
+
+TBD — signed by Armel at Story 5.2 dispatch time.
+
+## Post-commit footer
+
+- **Audit-completion commit SHA:** [`540fdda`](https://github.com/armelhbobdad/bmad-module-skill-forge/commit/540fdda419fc7e71bfdc571dab279b5de1b42578) — seven-file envelope (`docs(release): pre-v1.0.0 readiness audit (Story 5.1)`)
+- **Back-fill commit SHA:** this commit (the one that made this footer sentence self-referential)
+- **`git status --short` after commit:** clean working tree (verified per Story 5.1 AC 1 seven-file envelope)

package/tools/cli/commands/install.js

@@ -23,6 +23,9 @@ module.exports = {
       if (result && result.success) {
         ui.displaySuccess(config.skfFolder, config.ides, config._action);
         process.exit(0);
+      } else {
+        console.error(chalk.red('\nInstallation failed.'));
+        process.exit(1);
       }
     } catch (error) {
       console.error(chalk.red('\nInstallation failed:'), error.message);

package/tools/cli/commands/update.js

@@ -52,9 +52,11 @@ module.exports = {
         }
         const ui = new UI();
         ui.displaySuccess(SKF_FOLDER, ides, 'update');
+        process.exit(0);
+      } else {
+        console.error(chalk.red('\nUpdate failed.'));
+        process.exit(1);
       }
-
-      process.exit(0);
     } catch (error) {
       console.error(chalk.red('\nUpdate failed:'), error.message);
       process.exit(1);