bmad-module-skill-forge 1.0.0-rc.3 → 1.1.0

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

@@ -38,7 +38,7 @@ description: Pre-flight gate audit of every must-have launch-checklist item, wit
 | 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)                                                             |
+| 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 (section subsequently renamed to `### Cutting v1.0.0 under --tag latest` by Story 5.3 Commit 2 per AC 14)                              | [`docs/RELEASING.md` § Cutting v1.0.0 under --tag latest](./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)                          |
 
@@ -198,10 +198,531 @@ None — audit passes clean; Story 5.2 unblocked.
 
 ## Sign-off
 
-TBD — signed by Armel at Story 5.2 dispatch time.
+Signed off by Armel (@armelhbobdad) at 2026-04-23 16:40Z (post-publish, after smoke test completion). v1.0.0-rc.3 survived smoke test clean; Story 5.3 unblocked. v1.0.0 launched 2026-04-23 18:56:39Z; Story 5.4 cross-platform verification in scope. v1.0.0 cross-platform install verification VERIFIED at 2026-04-23T20:23:53Z; Epic 5 cleared.
 
 ## 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)
+
+## Story 5.2 RC Cut + Smoke Test
+
+### Hand-bump commit
+
+- **Commit 1 subject:** `chore(release): pre-RC bump to 1.0.0-rc.0 (Story 5.1 hand-off)`
+- **PR:** [#197](https://github.com/armelhbobdad/bmad-module-skill-forge/pull/197)
+- **Merge commit on main:** [`689501c`](https://github.com/armelhbobdad/bmad-module-skill-forge/commit/689501c) (merge-commit pattern, matching PR #195/#196)
+- **Hand-bump commit SHA under merge:** [`3fc1f00`](https://github.com/armelhbobdad/bmad-module-skill-forge/commit/3fc1f00)
+- **Scope:** `package.json` + `package-lock.json` — single-line version flip `0.10.0 → 1.0.0-rc.0`. No other files touched per AC 1(a) / AC 16.
+- **`npm run quality`:** all 13 subcommands green before opening PR.
+- **PR checks:** all 7 required status checks passed (eslint 22s, markdownlint 21s, prettier 24s, python ubuntu 24s, python windows 1m22s, validate ubuntu 21s, validate windows 1m10s).
+- **Remote `main` post-merge verification (AC 5 stronger precondition):** `gh api repos/.../contents/package.json` → `1.0.0-rc.0`.
+
+### Workflow dispatch run
+
+**Seven dispatch attempts** (numbered 1–7 below, of which the 7th passed) were required to land a passing RC end-to-end. Each failed attempt surfaced a distinct latent defect in the release pipeline — none of which had been exercised by the pre-v1.0.0 alpha cut (`v0.10.1-alpha.0`) because that cut dispatched from a feature branch and took the `Skip main push` pattern, bypassing the entire `main`-bound path. Story 5.2 was the first real E2E validation of the canonical path.
+
+| # | Run ID | Failed step | Root cause | Remediation |
+|---|---|---|---|---|
+| 1 | [24829166764](https://github.com/armelhbobdad/bmad-module-skill-forge/actions/runs/24829166764) | `Push commit to main` | Branch protection ruleset `Default` rejected direct `github-actions[bot]` push (GH013). AC 17's claimed bot-bypass-via-PR was factually wrong. | Story 3.4 refactor: push via auto-merge PR ([issue #198](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/198)); merged as PRs #199 + #200. |
+| 2 | [24838486851](https://github.com/armelhbobdad/bmad-module-skill-forge/actions/runs/24838486851) | `Open bot PR` | Repo setting `can_approve_pull_request_reviews: false` blocked `gh pr create` under GITHUB_TOKEN. | Side-fix: `gh api -X PUT /actions/permissions/workflow -F can_approve_pull_request_reviews=true`. Should be codified as a Story 3.4 follow-up. |
+| 3 | [24838762562](https://github.com/armelhbobdad/bmad-module-skill-forge/actions/runs/24838762562) | `Wait for required status checks` | `gh pr checks --required --watch` does NOT see check-runs posted by `workflow_dispatch`-triggered runs (they land in a different check suite than the PR's pull_request suite). All 7 required contexts were green on the SHA but invisible to the PR rollup. | Story 3.5: replace `gh pr checks` with direct `/commits/:sha/check-runs` API polling ([issue #202](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/202)); merged as PR #203. |
+| 4 | [24842070205](https://github.com/armelhbobdad/bmad-module-skill-forge/actions/runs/24842070205) | `Wait for required status checks` (20-min timeout) | Story 3.5's `for CTX in $(jq -r '.[]')` unquoted command substitution word-split context names with spaces (`validate (ubuntu-latest)`, etc.) into separate tokens. | PR [#205](https://github.com/armelhbobdad/bmad-module-skill-forge/pull/205): swap to `while IFS= read -r CTX; do ... done < <(...)`. |
+| 5 | [24844278359](https://github.com/armelhbobdad/bmad-module-skill-forge/actions/runs/24844278359) | `Wait for PR approval or admin-bypass merge` (30-min step timeout) | `gh pr view --json merged` is invalid — the valid field is `state` (returns `"OPEN"`/`"CLOSED"`/`"MERGED"`). The call exited 1, the guard treated it as transient and retried on every poll iteration until the enclosing `timeout-minutes: 30` on the step fired. Blocked both admin-bypass AND formal-approval paths. | PR [#207](https://github.com/armelhbobdad/bmad-module-skill-forge/pull/207): swap `--json merged` → `--json state` + string comparison update in both Wait steps. |
+| 6 | [24845860915](https://github.com/armelhbobdad/bmad-module-skill-forge/actions/runs/24845860915) | `Create and push tag` | Transient GitHub git-backend 500 on `git fetch origin main` (`remote: Internal Server Error` + `fatal: unable to access ...: The requested URL returned error: 500`, raw log from the failed step). The tag-step's Story 3.4 P9 defensive guard correctly bailed rather than anchoring on stale `origin/main` tip. Not a code bug; the guard behaved as designed. | Dispatch again; 500 self-resolved on retry. |
+| 7 (passing) | [24846332151](https://github.com/armelhbobdad/bmad-module-skill-forge/actions/runs/24846332151) | — | Full end-to-end success. | — |
+
+- **Passing run:** [24846332151](https://github.com/armelhbobdad/bmad-module-skill-forge/actions/runs/24846332151)
+- **Start:** `2026-04-23T16:21:33Z`
+- **End:** `2026-04-23T16:27:30Z`
+- **Duration:** 5m 4s
+- **Conclusion:** `success`
+- **Release commit subject:** `release: bump to v1.0.0-rc.3`
+- **Release commit SHA:** [`78ac999`](https://github.com/armelhbobdad/bmad-module-skill-forge/commit/78ac999) (authored by `github-actions[bot]`)
+- **Bot PR merged via:** [#209](https://github.com/armelhbobdad/bmad-module-skill-forge/pull/209) (admin-bypass-merge by @armelhbobdad at `2026-04-23T16:27:20Z`)
+- **Merge commit on main:** [`5fad470`](https://github.com/armelhbobdad/bmad-module-skill-forge/commit/5fad470)
+
+### npm publish evidence
+
+Excerpted fields from `npm view bmad-module-skill-forge@1.0.0-rc.3 --json` (full output is ~200 lines; the fields below are the ones the ACs gate on):
+
+```json
+{
+  "version": "1.0.0-rc.3",
+  "dist": {
+    "tarball": "https://registry.npmjs.org/bmad-module-skill-forge/-/bmad-module-skill-forge-1.0.0-rc.3.tgz",
+    "shasum": "85bcb22f65cb98debda06c9ec22062bdc85fea4f",
+    "attestations": {
+      "url": "https://registry.npmjs.org/-/npm/v1/attestations/bmad-module-skill-forge@1.0.0-rc.3",
+      "provenance": { "predicateType": "https://slsa.dev/provenance/v1" }
+    }
+  }
+}
+```
+
+`npm view bmad-module-skill-forge dist-tags --json` before and after the cut:
+
+```json
+// Pre-publish baseline (recorded at Task 1 recon per AC 7 baseline requirement)
+{ "latest": "0.10.0", "alpha": "0.10.1-alpha.0" }
+
+// Post-publish (observed after run 24846332151 completed)
+{ "latest": "0.10.0", "alpha": "0.10.1-alpha.0", "rc": "1.0.0-rc.3" }
+```
+
+`npm view bmad-module-skill-forge versions --json` (all published versions — confirms rc.1/rc.2 were never published to the registry):
+
+```json
+["0.2.0","0.3.0","0.4.0","0.5.0","0.6.0","0.7.0","0.7.1","0.7.2","0.7.3","0.7.4","0.8.0","0.8.1","0.8.2","0.8.3","0.8.4","0.9.0","0.10.0","0.10.1-alpha.0","1.0.0-rc.3"]
+```
+
+- **AC 6 provenance:** ✅ SLSA L2 attestation present (`provenance/v1`).
+- **AC 7 dist-tag:** ✅ `rc: 1.0.0-rc.3` added; `latest: 0.10.0` preserved from baseline; `alpha: 0.10.1-alpha.0` preserved from baseline. Baseline-vs-post diff is additive only.
+
+### GitHub Release v1.0.0-rc.3
+
+```json
+{
+  "tagName": "v1.0.0-rc.3",
+  "isPrerelease": true,
+  "createdAt": "2026-04-23T16:27:20Z",
+  "name": "Skill Forge (SKF) v1.0.0-rc.3",
+  "url": "https://github.com/armelhbobdad/bmad-module-skill-forge/releases/tag/v1.0.0-rc.3"
+}
+```
+
+### Main-branch side-effects
+
+- `git log main -1 --format='%H %s'` → `5fad470 Merge pull request #209 from armelhbobdad/release/bot/v1.0.0-rc.3-24846332151`
+- `git log main --grep='bump to v1.0.0-rc.3' --oneline` → `78ac999 release: bump to v1.0.0-rc.3` (workflow-authored, one behind merge tip)
+- `jq -r .version package.json` → `1.0.0-rc.3` ✅ (AC 8b)
+- `jq -r '.plugins[0].version' .claude-plugin/marketplace.json` → `1.0.0-rc.3` ✅ (AC 8c — **first live proof of Story 5.1 H3 jq fix working end-to-end**)
+- `grep -c '^## \[1.0.0-rc.3\]' CHANGELOG.md` → `1` ✅ (AC 8d)
+- `grep -c '^## \[1.0.0\] - TBD' CHANGELOG.md` → `1` ✅ (AC 8e — placeholder survives)
+- `head -5 CHANGELOG.md` → `# Changelog` + preamble + `## [Unreleased]` ✅ (AC 8f — Story 3.3 awk preamble-restore verified)
+- `git tag -l 'v1.0.0-rc.3'` → `v1.0.0-rc.3` ✅ (AC 8g)
+- `gh release view v1.0.0-rc.3` → `isPrerelease: true` ✅ (AC 8h)
+
+**Topology note (AC 8 re-interpretation under Story 3.4 PR-auto-merge flow):** the pre-3.4 AC 8(a) wording ("main tip SHA advanced by exactly one commit") is outdated — under the new PR-auto-merge flow, main advances by TWO commits per release cut (merge commit + the release commit underneath). `git log main -1` returns the merge commit; the release commit is reachable via `git log main --grep='bump to v1.0.0-rc.3'`. Functionally equivalent; the verification grep in AC 1 still works unchanged.
+
+### Clean-env smoke test transcripts
+
+**`--version` transcript (AC 9b):** `npx --yes bmad-module-skill-forge@rc --version` in a fresh `/tmp/skf-rc3-smoke/` → printed `1.0.0-rc.3`, exit `0`. The npm `11.6.2` `Permission denied` issue that Story 5.1 Task 10 hit on `.tgz`-path did NOT recur on the registry-resolved `@rc` path — as expected per Story 5.2 Dev Notes (F).
+
+**`install` transcript (AC 9d) — deviation from spec noted:** AC 9(d) specified piped-defaults via `printf 'skf-rc1-smoke\n\n\n\n\n' | npx ... install`, but the install TUI's `multiselect` IDE prompt (`required: true`) cannot be driven by piped stdin — the piped newlines get consumed by the first 3 text prompts (project name, skills folder, forge folder), and prompt 4 (multiselect) requires keystroke-level interaction (space + enter). Story 5.1 Task 10 also only smoke-tested `--version`, not the full install. **This is an AC 9 documentation defect, not an RC defect — tracked at [issue #211](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/211) for Story 5.4 / Epic 5 retrospective resolution.** To complete the install smoke test, Armel ran the install **interactively** in a real terminal, selecting Claude Code as the IDE; `echo "install exit: $?"` after completion printed `install exit: 0`. Install completed cleanly with Ferris agent set up and all expected artifacts present:
+
+```
+◇  Installation complete! ──────────────────────────────────╮
+│                                                           │
+│  Get Started                                              │
+│  1. Open this folder in Claude Code                       │
+│  2. Activate Ferris:  /skf-forger                         │
+│  3. Ferris (your Skill Architect) will guide you through  │
+│     setting up and forging your first agent skill         │
+│                                                           │
+├───────────────────────────────────────────────────────────╯
+│
+└  ⚒  Agent: Ferris (Skill Architect & Integrity Guardian)
+```
+
+Artifact verification:
+
+- `ls /tmp/skf-rc3-smoke/_bmad/skf/` (full listing):
+  - `config.yaml` (installer-generated)
+  - `knowledge/`, `shared/`, `module.yaml`, `module-help.csv` (module metadata)
+  - Skill dirs: `skf-analyze-source`, `skf-audit-skill`, `skf-brief-skill`, `skf-create-skill`, `skf-create-stack-skill`, `skf-drop-skill`, `skf-export-skill`, `skf-forger`, `skf-quick-skill`, `skf-refine-architecture`, `skf-rename-skill`, `skf-setup`, `skf-test-skill`, `skf-update-skill`, `skf-verify-stack`
+- `[ -f /tmp/skf-rc3-smoke/_bmad/_config/skf-manifest.yaml ]` → present
+- Zero `Installation failed.` in stderr
+
+**Skill count note:** the tarball ships 15 `skf-*` directories (listed above); the `status` command's `Skills: 14` count excludes one of them (likely `skf-setup`, which is a one-shot initialization helper rather than an invocable skill). This 15-vs-14 drift is a status-counting semantics detail, not a shipping defect — recorded here for Story 5.4 / Epic 5 retrospective to codify which `skf-*` prefix entries the count should include.
+
+**`status` transcript (AC 10):** `npx --yes bmad-module-skill-forge@rc status` exit `0`. All 6 STABILITY.md contract fields present in stdout:
+
+```
+  Skill Forge — Status
+  v1.0.0-rc.3
+
+  Installation
+    Project:      skf-rc3-smoke
+    SKF folder:   _bmad/skf/
+    Agent:        installed
+    Skills:       14
+    Installed:    4/23/2026
+    Manifest:     present
+
+  IDEs
+    ● Claude Code
+
+  Forge Tier
+    Not detected yet — run @Ferris SF
+    ast-grep:     not detected
+    gh CLI:       not detected
+    ccc:          not detected
+    QMD:          not detected
+
+  Output Folders
+    Skills:       skills/ ✓
+    Forge data:   forge-data/ ✓
+
+  Sidecar
+    State:        initialized
+    Location:     _bmad/_memory/forger-sidecar/
+```
+
+| STABILITY.md contract field | Observed | ✓ |
+|---|---|---|
+| installation-present | Installation section rendered | ✓ |
+| installed version string | `v1.0.0-rc.3` | ✓ |
+| forge-tier name | `Not detected yet` (plus ast-grep/gh/ccc/QMD tool rows) | ✓ |
+| configured IDE list | `● Claude Code` | ✓ |
+| workflow-skill count | `Skills: 14` | ✓ |
+| sidecar state | `State: initialized` | ✓ |
+| output-folder paths | `Skills: skills/ ✓` + `Forge data: forge-data/ ✓` | ✓ |
+
+**`uninstall` transcript (AC 11):** `printf 'y\n' | npx --yes bmad-module-skill-forge@rc uninstall` — note that unlike `install`, uninstall's only prompt is a simple `Yes/No` confirm which IS satisfied by piped `y\n`. Exit `0`. Final message: `SKF uninstalled successfully.` Post-uninstall:
+
+- `ls /tmp/skf-rc3-smoke/_bmad/skf/ 2>/dev/null | wc -l` → `0`
+- `[ -f /tmp/skf-rc3-smoke/_bmad/_config/skf-manifest.yaml ]` → absent ✓
+
+### NFR1 cycle-time record
+
+- **Dispatch → success wall-clock:** 5m 4s (run 24846332151: `2026-04-23T16:21:33Z` → `16:27:30Z`).
+- **NFR1 target:** 20 min (15 CI + 5 approval).
+- **Status:** **Provisional PASS — 1/10 data points collected** against NFR1's rolling-over-10-releases target. The 5m 4s run is well under the 20-min envelope, but a single observation cannot confirm the rolling target; Stories 5.3 / 5.4 will add the next two data points.
+- **Caveat:** this measurement excludes the cumulative time of attempts 1–6 (all failures). Total story wall-clock from first dispatch attempt to successful publish was ~6 hours including dev-cycle time on Stories 3-4, 3-5, and PRs #205/#207. That cumulative cost is retrospective-relevant but does NOT represent steady-state NFR1 performance — it represents first-time E2E discovery overhead, which by definition cannot repeat.
+
+### Decision: v1.0.0-rc.3 status
+
+**PASS — cleared for Story 5.3 promotion to v1.0.0 under --tag latest with manual approval.**
+
+Note to Story 5.3 dev-agent: the `## [1.0.0] - TBD` block at `CHANGELOG.md:396` was verified accurate against shipped rc.3 behavior (AC 15 — all bullets match: 1 agent Ferris, 14 workflows, 23 IDEs via `platform-codes.yaml`, tier names Quick/Forge/Forge+/Deep match the `Forge Tier` detection section). No CHANGELOG refinements flagged for Story 5.3. The only date-flip Story 5.3 must handle is `- TBD` → `- 2026-04-23` (or whatever date 5.3 dispatches).
+
+**Derogation from original AC 1 RC-number envelope:** the originally-planned RC number was `rc.1`; actually-shipped is `rc.3`. Stories 5.1 and 5.2 both authored AC text referencing `rc.1` literal. Under Story 5.2's 7-attempt execution, `rc.1` and `rc.2` were both committed to main (via PR #206's bypass-merge and PR #208's auto-merge respectively) but never tagged or published because downstream defects blocked each. Both are cosmetic-only stale release commits on main — npm immutability does NOT apply (nothing was published under those names); dist-tags never pointed at them. Story 5.3 dispatches on top of `rc.3` → `1.0.0`. This derogation is recorded per AC 12's spirit (defect discovery protocol), though each failure was a pipeline defect rather than an RC-content defect.
+
+**Negative-evidence for the rc.1/rc.2 "never tagged/never published" claim** (run 2026-04-23 post-publish):
+
+```
+$ git tag -l 'v1.0.0-rc.1' 'v1.0.0-rc.2' 'v1.0.0-rc.3'
+v1.0.0-rc.3
+# rc.1 and rc.2 absent — only rc.3 was tagged
+
+$ npm view bmad-module-skill-forge versions --json | jq '. | map(select(startswith("1.0.0-rc")))'
+["1.0.0-rc.3"]
+# rc.1 and rc.2 absent — only rc.3 was published to the registry
+```
+
+**AC 12 title-convention note (D2 resolution):** AC 12 prescribes issue titles `v1.0.0-rc.N blocker: <one-line>` for failures of AC 6/7/8/9/10/11 (RC-content defects). Issues [#198](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/198) and [#202](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/202) were filed during Story 5.2 with `release.yaml`-prefixed titles instead, because each failure was a pipeline/workflow defect (failing step inside `release.yaml`), not an RC-content defect — none of the ACs 6–11 fired. The title-convention distinction: use `v1.0.0-rc.N blocker:` when the RC itself has a content defect (wrong version on npm, missing attestation, broken install, etc.); use `fix(release):` conventional-commit prefix when the release workflow has a defect. Codify this split at the Epic 5 retrospective.
+
+**Lesson for Epic 5 retrospective:** The canonical release path from `main` dispatch had zero prior E2E validation before Story 5.2 attempted it. Stories 3-1 through 3-4 implicitly assumed the path worked; each defect surfaced by Story 5.2 was invisible because the alpha cut (`v0.10.1-alpha.0`) took the non-main-dispatch branch and skipped every affected step. Recommendation: future release-pipeline epics must include a **staging dispatch test** against a sandbox repo (or at minimum a full-workflow dry-run against the default branch) before declaring the pipeline ready. Catching 5+ defects via the first real v1.0.0 cut is demonstrably more expensive than discovering them in pre-launch testing.
+
+## Story 5.3 v1.0.0 Final Cut
+
+Story 5.3 promoted the passing `v1.0.0-rc.3` RC to `v1.0.0` under `--tag latest` via the canonical `release.yaml` workflow with two-gate maintainer approval. The dispatch succeeded on the first attempt (in contrast to Story 5.2's 7-attempt saga), validating that the pipeline defects surfaced during Story 5.2 (Stories 3-4, 3-5, and PRs #205 / #207) were fully resolved. The cut is the NFR6 immutability activation event: from `2026-04-23T18:56:39Z`, `v1.0.0` is forever-burned on npm under `--tag latest`; rollback from this instant is `npm deprecate` + ship-forward only.
+
+### Workflow dispatch run
+
+- **Run URL:** <https://github.com/armelhbobdad/bmad-module-skill-forge/actions/runs/24852899833>
+- **Run id:** `24852899833`
+- **Dispatch command:** `gh workflow run release.yaml -f version_bump=major --ref main`
+- **Dispatch timestamp:** `2026-04-23T18:49:46Z` (per GitHub API `run_started_at` on run `24852899833`)
+- **Release env gate approved at:** `2026-04-23T18:52:32Z` (set-up-job start; 2m 46s gate wait from dispatch)
+- **Bot PR approval-or-admin-bypass merge at:** `2026-04-23T18:56:30Z` (admin-bypass-merge — the PR's `Wait for PR approval or admin-bypass merge` step cleared in 0s because the merge had already happened by the time that step evaluated; matches the rc.3 pattern where PR #209 was admin-bypass-merged)
+- **Run completion:** `2026-04-23T18:56:48Z`
+- **Final conclusion:** `success`
+- **Step failures:** none. Of 31 declared job steps, 30 ran successfully and 1 (step 27 `Skip PR flow (non-main dispatch ref)`) was skipped by design: the step's `if: github.ref != 'refs/heads/main'` guard evaluated false (the ref IS main), so the non-main fallback path was correctly bypassed.
+
+### Bot PR auto-merge evidence
+
+- **Bot PR:** [#213 `release: bump to v1.0.0`](https://github.com/armelhbobdad/bmad-module-skill-forge/pull/213)
+- **Head branch:** `release/bot/v1.0.0-24852899833` (temp branch; auto-deleted post-merge per standard flow)
+- **Head commit:** `62d56418836c90153401eae2d49500dbfa1c70d8` (the `release: bump to v1.0.0` commit)
+- **Merge commit:** `393a5a2012e8914faa3f67e1af94bc3ca0c90062`
+- **Merged at:** `2026-04-23T18:56:30Z`
+- **Merge path:** admin-bypass-merge (maintainer clicked merge on the PR without formal review approval; both `reviewDecision == APPROVED` and `state == MERGED` are accepted by `release.yaml:481-569`). This matches the Story 5.2 rc.3 pattern and is the expected path per Story 3.4.
+
+### npm publish evidence
+
+**Pre-cut dist-tags snapshot (from Task 1 recon, `2026-04-23 ~18:48Z`):**
+
+```json
+{
+  "latest": "0.10.0",
+  "alpha": "0.10.1-alpha.0",
+  "rc": "1.0.0-rc.3"
+}
+```
+
+**Post-cut dist-tags snapshot (from Task 3 verification, `2026-04-23 ~18:57Z`):**
+
+```json
+{
+  "latest": "1.0.0",
+  "alpha": "0.10.1-alpha.0",
+  "rc": "1.0.0-rc.3"
+}
+```
+
+**Dist-tag deltas:** `latest` flipped `0.10.0` → `1.0.0` (the whole point of Story 5.3); `rc` UNCHANGED at `1.0.0-rc.3` (Story 5.3's `major`-from-rc cut does NOT bump the rc tag); `alpha` UNCHANGED at `0.10.1-alpha.0`.
+
+**`npm view bmad-module-skill-forge@1.0.0 --json | jq '.dist'` (verbatim):**
+
+```json
+{
+  "integrity": "sha512-6tQOBCuf05SMRs/1MNWm6+f7OYOGh6tz62AbTvMG3bjspqMQa6Ln9y5paQtQRh4eWyuPvTlPaKqV6Vug8IIOeA==",
+  "shasum": "a582acf226016bb075dc5235a721da9d16104b35",
+  "tarball": "https://registry.npmjs.org/bmad-module-skill-forge/-/bmad-module-skill-forge-1.0.0.tgz",
+  "fileCount": 227,
+  "unpackedSize": 1697974,
+  "attestations": {
+    "url": "https://registry.npmjs.org/-/npm/v1/attestations/bmad-module-skill-forge@1.0.0",
+    "provenance": {
+      "predicateType": "https://slsa.dev/provenance/v1"
+    }
+  },
+  "signatures": [
+    {
+      "keyid": "SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U",
+      "sig": "MEUCIHcz/PIyH7DaVNN872V0uwQXmO29h6WmeXgGRxP0RFR7AiEA2zX6/x2aXiDN4V7irzXiWKNYG+uqFiQwBRGdt0DGFvg="
+    }
+  ]
+}
+```
+
+**Provenance attestation URL:** <https://registry.npmjs.org/-/npm/v1/attestations/bmad-module-skill-forge@1.0.0>
+
+**Versions list (after publish):**
+
+```
+$ npm view bmad-module-skill-forge versions --json | jq '. | map(select(startswith("1.0.0")))'
+[
+  "1.0.0-rc.3",
+  "1.0.0"
+]
+```
+
+**AC 6 NFR4 provenance-coverage status:** PASS — SLSA L2 attestation present for `1.0.0` (`predicateType: https://slsa.dev/provenance/v1`; the SLSA Build L2 level follows from npm's trusted-publishing design, which signs provenance statements via GitHub Actions OIDC with tamper-evident build metadata — see <https://docs.npmjs.com/generating-provenance-statements>).
+
+### GitHub Release v1.0.0
+
+**`gh release view v1.0.0 --json tagName,isPrerelease,name,createdAt,url`:**
+
+```json
+{
+  "createdAt": "2026-04-23T18:56:33Z",
+  "isPrerelease": false,
+  "name": "Skill Forge (SKF) v1.0.0",
+  "tagName": "v1.0.0",
+  "url": "https://github.com/armelhbobdad/bmad-module-skill-forge/releases/tag/v1.0.0"
+}
+```
+
+- `isPrerelease: false` ✓ — load-bearing for NFR6 threshold; `release.yaml:697-704` computes `prerelease` as `contains(version, 'alpha|beta|rc')` and `1.0.0` contains none of those substrings.
+- Release URL: <https://github.com/armelhbobdad/bmad-module-skill-forge/releases/tag/v1.0.0>
+- Release body: auto-generated by `release.yaml § Generate release notes` from the conventional-commits between `v1.0.0-rc.3` and `v1.0.0` (expected empty — the commit range contains only `docs(release):` and `chore(release):` entries, neither of which emits `### Features` or `### Bug Fixes` under conventional-changelog; the reconciled CHANGELOG carries the hand-curated v1.0.0 prose separately). **Post-sign-off amplification (Story 5.3 code-review patch 2a, 2026-04-23):** the Release body was subsequently replaced via `gh release edit v1.0.0 --notes-file …` with the verbatim hand-curated CHANGELOG § [1.0.0] prose (First Major Release / Initial Release / Highlights / Workflows / Confidence Tiers / IDE Support / Links) plus a 6-line footer linking to the CHANGELOG entry and the `v1.0.0-rc.3...v1.0.0` compare view. Post-amplification body length: 3844 bytes (up from 473). This edit does not alter npm, the tag, or provenance; it only changes the public Release-page prose for discoverability.
+
+### Main-branch side-effects
+
+**`main` branch advance (AC 8a):**
+
+```
+$ git log main -2 --format='%H %an %s'
+393a5a2012e8914faa3f67e1af94bc3ca0c90062 github-actions[bot] Merge pull request #213 from armelhbobdad/release/bot/v1.0.0-24852899833
+62d56418836c90153401eae2d49500dbfa1c70d8 github-actions[bot] release: bump to v1.0.0
+```
+
+- Merge commit: `393a5a2` (parents: `3e60788` pre-Story-5.3 main tip + `62d56418` bot release commit)
+- Release commit: `62d56418` (parent: `3e60788`)
+- Topology matches rc.3 precedent: PR merge commit on top, workflow-authored release commit underneath.
+
+**Version-file bumps (AC 8b, 8c):**
+
+```
+$ jq -r .version package.json
+1.0.0
+
+$ jq -r '.plugins[0].version' .claude-plugin/marketplace.json
+1.0.0
+```
+
+AC 8c: 2nd live end-to-end proof of the Story 5.1 H3 jq-based marketplace-sync step (1st was rc.3).
+
+**CHANGELOG post-workflow topology (AC 8d, 8e, 8f):**
+
+```
+$ grep -cE '^## \[1\.0\.0\]' CHANGELOG.md    # 2 (auto-gen + stale TBD; reconciled in Commit 2)
+$ grep -c '^## \[1.0.0-rc.3\]' CHANGELOG.md  # 1 (rc.3 block survived)
+$ head -5 CHANGELOG.md                        # # Changelog + preamble + ## [Unreleased]
+```
+
+**Zero-conventional-commit edge case:** the auto-generated `## [1.0.0]` block had an EMPTY body (no `### Features` / `### Bug Fixes` sub-sections) because the commit range `v1.0.0-rc.3..v1.0.0` contained only `docs(release):` and `chore(release):` entries. This is the expected behavior per deferred-work 3-3; AC 10 reconciliation preserves the auto-gen header (compare URL + date) and injects the hand-curated prose. The `awk`-based preamble-restore from Story 3.3 worked correctly despite the empty block.
+
+**Tag anchor verification (AC 9):**
+
+```
+$ git tag -l 'v1.0.0'
+v1.0.0
+
+$ git rev-parse 'v1.0.0^{}'   # dereference annotated tag to commit
+393a5a2012e8914faa3f67e1af94bc3ca0c90062
+
+$ git log main -1 --format='%H'
+393a5a2012e8914faa3f67e1af94bc3ca0c90062
+
+=> MATCH ✓ (tag anchors on PR merge commit per Story 3.4 P9 defensive guard)
+
+$ git log v1.0.0 -1 --format='%s'
+Merge pull request #213 from armelhbobdad/release/bot/v1.0.0-24852899833
+```
+
+**Note:** `v1.0.0` is an **annotated tag object** (tag SHA `4579b954ee6512a1c39ef4e3f06ecdb60e67358f`), not a lightweight tag. `git rev-parse v1.0.0` returns the tag object SHA, not the commit SHA — use `^{}` to dereference. This is consistent with the rc.3 tag shape from Story 5.2.
+
+### CHANGELOG reconciliation
+
+**Pre-reconciliation state (post-workflow):** two `## [1.0.0]` H2 blocks — (A) auto-generated at line 7 with compare URL `compare/v1.0.0-rc.3...v1.0.0` and empty body, (B) hand-curated `## [1.0.0] - TBD` placeholder at line 397 (originally staged by Story 5.1).
+
+**Post-reconciliation state:** single `## [1.0.0]` block at line 7 with preserved auto-gen header (compare URL + date `2026-04-23`) and hand-curated body (First Major Release → Initial Release → Highlights → Workflows → Confidence Tiers → IDE Support → Links); stale TBD placeholder deleted.
+
+**Post-edit verification (AC 10 iii):**
+
+```
+$ grep -cE '^## \[1\.0\.0\]' CHANGELOG.md         # 1 (exactly one reconciled block)
+$ grep -c  '^## \[1\.0\.0\] - TBD' CHANGELOG.md   # 0 (stale placeholder gone)
+$ grep -cE '^## \[1\.0\.0\]\(https' CHANGELOG.md  # 1 (compare-URL header preserved)
+$ grep -c  '^## \[1.0.0-rc.3\]' CHANGELOG.md      # 1 (rc.3 block untouched)
+$ grep -c  '^## \[0.10.0\]' CHANGELOG.md          # 1 (older history intact)
+```
+
+**Diff excerpt (block A insertion, head):**
+
+```diff
+ ## [1.0.0](https://github.com/armelhbobdad/bmad-module-skill-forge/compare/v1.0.0-rc.3...v1.0.0) (2026-04-23)
++
++### First Major Release
++
++First major release of Skill Forge (SKF). Introduces the `INCONCLUSIVE` test verdict, atomic stack-skill writes, a shared feasibility schema across VS/RA/SS, and formalizes Linux/macOS-only support. Sets the stable contract for subsequent 1.x releases.
++
++### Initial Release
++
++Skill Forge (SKF) — an agent skill compiler that transforms code repositories, documentation, and developer discourse into [agentskills.io](https://agentskills.io)-compliant agent skills with AST-backed provenance.
++[... hand-curated body continues with Highlights / Workflows / Confidence Tiers / IDE Support / Links ...]
+ ## [1.0.0-rc.3](https://github.com/armelhbobdad/bmad-module-skill-forge/compare/v0.10.0...v1.0.0-rc.3) (2026-04-23)
+```
+
+**Diff excerpt (block B deletion, tail — the bracketed placeholder line inside the code fence below is narrative, not a literal diff line; run `git diff c0b2b67^..c0b2b67 -- CHANGELOG.md` for the verbatim body):**
+
+```diff
+-## [1.0.0] - TBD
+-
+-<!--
+-Hand-curated v1.0.0 release notes. Source: _bmad-output/planning-artifacts/v1-0-0-changelog-draft.md.
+-Date placeholder "TBD" — replaced with actual publish date at Story 5.3's v1.0.0 final cut (see
+-docs/RELEASING.md § Cutting v1.0.0-rc.1 for the reconciliation procedure).
+--->
+-
+-### First Major Release
+-[... full hand-curated body deleted from here (moved up into reconciled block A) ...]
+-- npm: <https://www.npmjs.com/package/bmad-module-skill-forge>
+-
+ ## [0.10.0](https://github.com/armelhbobdad/bmad-module-skill-forge/compare/v0.9.0...v0.10.0) (2026-04-06)
+```
+
+**Net CHANGELOG delta:** 710 lines → 703 lines (−7 lines from removing the TBD placeholder's HTML comment + header markers; the body itself was relocated, not deleted).
+
+### NFR1 cycle-time record
+
+- **Dispatch → success wall-clock:** **7m 2s** (run `24852899833`: `2026-04-23T18:49:46Z` → `2026-04-23T18:56:48Z`)
+- **Env-gate approval sub-budget:** 2m 46s (`2026-04-23T18:49:46Z` dispatch → `2026-04-23T18:52:32Z` set-up-job start)
+- **Workflow automation sub-budget:** 4m 16s (`2026-04-23T18:52:32Z` → `2026-04-23T18:56:48Z`)
+- **NFR1 target:** 20 min (15 CI + 5 approval)
+- **Status:** within envelope; 13 min of headroom against the 20-min target.
+- **Rolling-10-release window:** 2 / 10 data points collected — `[Story 5.2 rc.3: 5m 4s, Story 5.3 v1.0.0: 7m 2s]`. Both well under NFR1's 20-min target. Stories 5.4 onward continue filling the window.
+- **Story 5.2 retrospective comparison:** Story 5.3 dispatched successfully on the first attempt (7m 2s wall-clock). Story 5.2 took 7 attempts and ~6 hours of cumulative dev-cycle time to discover and fix 5 pipeline defects (Stories 3-4, 3-5, PRs #205 / #207). Story 5.3's first-attempt success is evidence that those fixes landed correctly; the pipeline is now E2E-proven for main-dispatched cuts.
+
+### NFR6 v1.0.0 immutability activation
+
+**v1.0.0 is live on npm under --tag latest as of 2026-04-23T18:56:39Z. NFR6 immutability policy is now in force: this version SHALL NEVER be unpublished or republished; rollback uses npm deprecate + ship forward per docs/RELEASING.md § Scenario A/B.**
+
+This timestamp is the `Publish to npm via OIDC trusted publishing` step's completion time (step 29 of run `24852899833`; `2026-04-23T18:56:34Z` → `2026-04-23T18:56:39Z` in the GitHub Actions step timeline). From this instant, the version-number `1.0.0` on npm is an irreversible forensic fact: any future defect surfaced against `1.0.0` is resolved via `npm deprecate bmad-module-skill-forge@1.0.0 "<reason>"` and shipping `1.0.1` forward with the fix, NEVER via `npm unpublish` (regardless of eligibility-window rules — NFR6 forbids reclaim). This record is the auditable boundary between "pre-NFR6 state" and "NFR6-active state."
+
+### Decision: v1.0.0 launch status
+
+**LAUNCHED — v1.0.0 is live on npm under --tag latest with SLSA L2 provenance. Story 5.4 cross-platform verification cleared to begin (NFR9: within 1h of publish).**
+
+The `## Sign-off` section (above) is updated with the dual-sentence form:
+
+> Signed off by Armel (@armelhbobdad) at 2026-04-23 16:40Z (post-publish, after smoke test completion). v1.0.0-rc.3 survived smoke test clean; Story 5.3 unblocked. v1.0.0 launched 2026-04-23 18:56:39Z; Story 5.4 cross-platform verification in scope.
+
+Story 5.4 opens with `v1.0.0 is live on npm` as its precondition; NFR9 requires cross-platform install verification (Linux + Windows via the `quality.yaml` matrix + macOS manual spot-check) within 60 minutes of the `2026-04-23T18:56:39Z` publish timestamp. Story 5.4 dispatches are in scope starting immediately after Story 5.3's Commit 2 (this audit append) lands on `main`.
+
+## Story 5.4 Post-Publish Verification
+
+### Workflow dispatch run
+
+- **Workflow:** `.github/workflows/install-smoke.yaml` (authored in Story 5.4 Commit 1, PR [#219](https://github.com/armelhbobdad/bmad-module-skill-forge/pull/219), merged at `2026-04-23T20:22:07Z`, merge commit [`075dbcb`](https://github.com/armelhbobdad/bmad-module-skill-forge/commit/075dbcb2fd8100036822aa172712db07867b5e73))
+- **Dispatch command:** `gh workflow run install-smoke.yaml -f version=latest --ref main`
+- **Run ID:** `24856988815`
+- **Run URL:** <https://github.com/armelhbobdad/bmad-module-skill-forge/actions/runs/24856988815>
+- **Dispatch timestamp:** `2026-04-23T20:23:07Z`
+- **Completion timestamp:** `2026-04-23T20:23:53Z`
+- **Final conclusion:** `success` (all three matrix legs `success`)
+- **Total wall-clock:** 46 seconds
+
+### Matrix results
+
+| Runner | Job status | `--version` stdout | Exit code | Wall-clock | Runner image version |
+|--------|-----------|---------------------|-----------|------------|----------------------|
+| `ubuntu-latest` | `success` | `stdout: 1.0.0` | 0 | ~5s (start `20:23:13Z` → end `20:23:18Z`) | `Runner Image 20260213.493`, `Runner Image Provisioner 20260413.86.1` |
+| `windows-latest` | `success` | `stdout: 1.0.0` | 0 | ~40s (start `20:23:12Z` → end `20:23:52Z`) | `Runner Image 20260213.493`, `Runner Image Provisioner 20260413.84.1` |
+| `macos-latest` | `success` | `stdout: 1.0.0` | 0 | ~8s (start `20:23:13Z` → end `20:23:21Z`) | `Runner Image 20260422.526`, `Runner Image Provisioner 20260421.0007.1` |
+
+All three legs printed `1.0.0` verbatim (matching `package.json.version` for v1.0.0), exited 0, and completed well inside the 60-second-typical target from Story 5.4 AC 4. Windows was the slowest at 40s (expected — npx warm-up + longer shebang resolution on Windows); ubuntu-latest fastest at 5s.
+
+### NFR9 elapsed-time record
+
+- **Publish timestamp (Story 5.3 activating NFR6):** `2026-04-23T18:56:39Z`
+- **NFR9 60-minute target deadline:** `2026-04-23T19:56:39Z`
+- **Smoke-workflow dispatch timestamp:** `2026-04-23T20:23:07Z`
+- **Smoke-workflow completion timestamp:** `2026-04-23T20:23:53Z`
+- **Wall-clock delta from publish to completion:** `01:27` (1 hour 27 minutes 14 seconds)
+- **NFR9 status classification:** `missed-target-non-blocking`
+
+**Disposition rationale.** The 60-minute NFR9 target closed at `2026-04-23T19:56:39Z`; verification completed 27 minutes past the target. All three matrix legs passed with no surfaced regressions, so no live cross-platform defect existed during the unobserved window — the policy's safety goal (catching a platform regression fast while blast radius is small) was achieved in practice, just later than the 1-hour target. Per Story 5.4 AC 2, this disposition is non-blocking for Epic 5 closure. The first NFR9 data point goes into the Epic 5 retrospective, which will weigh whether the 1-hour target needs (i) softening to a 24-hour bucket for solo-maintainer operability, (ii) automation via tag-push auto-trigger to push verification toward near-real-time, or (iii) maintainer on-call commitments for future launches.
+
+### Marketplace.json post-publish invariant
+
+Re-verified post-smoke (Story 5.4 Task 4) — all four invariants hold, zero drift from Story 5.3 final state:
+
+```
+$ gh api repos/armelhbobdad/bmad-module-skill-forge/contents/package.json \
+    --jq '.content' | base64 -d | jq -r .version
+1.0.0
+
+$ gh api repos/armelhbobdad/bmad-module-skill-forge/contents/.claude-plugin/marketplace.json \
+    --jq '.content' | base64 -d | jq -r '.plugins[0].version'
+1.0.0
+
+$ npm view bmad-module-skill-forge@latest version
+1.0.0
+
+$ npm view bmad-module-skill-forge dist-tags --json
+{
+  "latest": "1.0.0",
+  "alpha": "0.10.1-alpha.0",
+  "rc": "1.0.0-rc.3"
+}
+```
+
+### Any observations or defects surfaced
+
+None — all three matrix legs clean. No stderr noise, no deprecation warnings, no platform-specific anomalies. The published v1.0.0 tarball resolves and executes cleanly on `ubuntu-latest`, `windows-latest`, and `macos-latest` under Node 22, through the `tools/skf-npx-wrapper.js` bin entrypoint and commander dispatch.
+
+### Decision: v1.0.0 cross-platform verification status
+
+**VERIFIED — v1.0.0 install clean on ubuntu-latest + windows-latest + macos-latest via npm dist-tag @latest. NFR9 missed-target-non-blocking. Epic 5 cleared for close; Epic 6 cleanup unblocked.**
+
+The `## Sign-off` block at the top of this audit is updated to the four-sentence form per Story 5.4 AC 8:
+
+> Signed off by Armel (@armelhbobdad) at 2026-04-23 16:40Z (post-publish, after smoke test completion). v1.0.0-rc.3 survived smoke test clean; Story 5.3 unblocked. v1.0.0 launched 2026-04-23 18:56:39Z; Story 5.4 cross-platform verification in scope. v1.0.0 cross-platform install verification VERIFIED at 2026-04-23T20:23:53Z; Epic 5 cleared.
+
+Story 5.4 closes with Epic 5 at `done`. Epic 6 cleanup stories (6-1 delete legacy `publish.yaml` + `manual-release.yaml`; 6-2 remove `release:*` scripts from `package.json`; 6-3 remove `NPM_TOKEN` secret) are now unblocked. The `install-smoke.yaml` workflow remains as a permanent reusable artifact — every future release (v1.0.1, v1.1.0, v2.0.0, ...) can redispatch it with the new version tag to produce the same cross-platform evidence.

package/src/skf-audit-skill/steps-c/step-01-init.md

@@ -104,12 +104,72 @@ If `{legacy_stack_provenance}` is true: log a note that this stack uses v1 prove
 **If provenance map loaded:**
 - Use `source_root` from provenance map as source code path
 - Verify source path still exists and is accessible
+- Extract `baseline_commit` = `provenance-map.source_commit` (fall back to `metadata.source_commit` if absent from the provenance map)
+- Extract `baseline_ref` = `metadata.source_ref` (may be a tag, branch, `HEAD`, or `"local"`)
 
 **If degraded mode:**
 - Ask user: "Please provide the path to the current source code."
+- `baseline_commit` and `baseline_ref` are unavailable — §5b will short-circuit
 
 **Validate:** Confirm source directory exists and contains expected files.
 
+### 5b. Detect Upstream Drift
+
+Upstream drift detection is the primary use case of this workflow. If the local clone is still pinned to the baseline commit while upstream has shipped newer tags, auditing against the unchanged tree will misleadingly report CLEAN even after a major release.
+
+**Skip this section** if any of the following hold:
+- `baseline_ref` is `"local"`, `null`, or unset (non-git source)
+- `{source_root}` is not a git worktree (`git -C {source_root} rev-parse --git-dir` fails)
+- `baseline_commit` is unavailable
+- Degraded mode is active (no provenance map)
+
+When skipping, log the reason, then set the audit-ref context variables to baseline values so step-06 renders a coherent Provenance row: `audit_ref = baseline_ref or "(unknown)"`, `audit_ref_source = "baseline"` (or `"unavailable"` if both `baseline_ref` and `baseline_commit` are unset), `audit_commit = baseline_commit or "(unknown)"`, `latest_tag = null`, `remote_head = null`. Continue to §6.
+
+**Otherwise:**
+
+1. **Fetch upstream refs** (read-only, no working-tree mutation):
+
+   ```bash
+   git -C {source_root} fetch --tags --quiet origin
+   ```
+
+   If fetch fails (no network, no remote, detached clone), log the reason, record `upstream_fetch: "failed:{reason}"` in context, set `audit_ref = baseline_ref`, `audit_ref_source = "baseline"`, `audit_commit = baseline_commit`, `latest_tag = null`, `remote_head = null`, and continue to §6 without gating.
+
+2. **Find latest remote ref:**
+   - Remote default-branch HEAD: `git -C {source_root} rev-parse origin/HEAD` (fall back to `origin/main` or `origin/master` if the symbolic ref is unavailable) — record as `remote_head`.
+   - Newest semver tag: `git -C {source_root} for-each-ref --sort=-v:refname --format='%(refname:short)' 'refs/tags/v*' | head -1` — record as `latest_tag`.
+
+3. **Compare to baseline:**
+   - If `baseline_commit` equals the commit that `remote_head` resolves to AND (`latest_tag` is empty OR semver-equals `baseline_ref` OR is older than `baseline_ref`), upstream has not moved. Set `audit_ref = baseline_ref`, `audit_ref_source = "baseline"`, `audit_commit = baseline_commit`. Continue to §6.
+   - Otherwise upstream has moved — proceed to the gate.
+
+4. **User gate — Upstream drift detected:**
+
+   "**Upstream has moved since this skill was created.**
+
+   | | Baseline | Upstream |
+   |---|---|---|
+   | Ref | `{baseline_ref}` | `{latest_tag}` (newest tag) / `{remote_head}` (default HEAD) |
+   | Commit | `{baseline_commit_short}` | `{latest_tag_commit_short}` / `{remote_head_short}` |
+
+   Auditing against the baseline clone will report little-to-no structural drift even if the upstream API has changed. Options:
+
+   - **[C] Checkout-and-audit-against-latest** — checkout `{latest_tag}` (or `{remote_head}` if no newer tag) in `{source_root}` and audit against that. Re-extraction will reflect the current upstream surface.
+   - **[S] Stay-on-baseline** — keep `{source_root}` at `{baseline_ref}` and audit structural drift against the unchanged tree. The report will note `audit_ref = baseline`.
+   - **[X] Abort** — halt the workflow without producing a report.
+
+   **Select:** [C] / [S] / [X]"
+
+   **Gate handling:**
+   - **[C]:** Acquire an exclusive lock on `{source_root}/.skf-workspace.lock` (`flock -x` or `fcntl.flock(LOCK_EX)`) before mutating the working tree — matches the concurrency discipline in `src/skf-create-skill/references/source-resolution-protocols.md` and avoids racing with a concurrent create-skill / test-skill run against the same workspace clone. If `flock` is unavailable, emit a warning and proceed. Then `git -C {source_root} checkout {chosen_ref}` (prefer `latest_tag` when present, else `remote_head`). Set `audit_ref = {chosen_ref}`, `audit_ref_source = "checkout-latest"`, `audit_commit = git rev-parse HEAD`. Hold the lock through step-02 re-extraction and release only after the extraction snapshot is complete.
+   - **[S]:** Keep baseline. Set `audit_ref = baseline_ref`, `audit_ref_source = "baseline"`, `audit_commit = baseline_commit`.
+   - **[X]:** HALT workflow — do not create drift report.
+   - **Other input:** help user, redisplay gate.
+
+   **Headless default** (when `{headless_mode}`): auto-select **[S]** and emit a loud log line: `"headless: upstream drift detected ({baseline_ref} → {latest_tag or remote_head}); staying on baseline. Re-run interactively to audit against latest."` Do not check out in headless mode — silent ref changes under automation would mutate the user's working tree without consent.
+
+5. **Record for report:** store `audit_ref`, `audit_ref_source`, `audit_commit`, `latest_tag`, `remote_head`, and `baseline_commit` in context. Step-06 surfaces them in the Provenance section so readers can tell which comparison actually ran.
+
 ### 6. Create Drift Report
 
 Create `{outputFile}` from `{templateFile}`: