bmad-module-skill-forge 0.10.0 → 0.10.1-alpha.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,39 @@
+{
+  "name": "bmad-module-skill-forge",
+  "owner": {
+    "name": "Armel"
+  },
+  "description": "Turn code and docs into instructions AI agents can actually follow. Evidence-based skill compilation with progressive capability tiers.",
+  "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"],
+  "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",
+      "author": {
+        "name": "Armel"
+      },
+      "skills": [
+        "./src/skf-forger",
+        "./src/skf-setup",
+        "./src/skf-analyze-source",
+        "./src/skf-brief-skill",
+        "./src/skf-create-skill",
+        "./src/skf-quick-skill",
+        "./src/skf-create-stack-skill",
+        "./src/skf-update-skill",
+        "./src/skf-audit-skill",
+        "./src/skf-test-skill",
+        "./src/skf-export-skill",
+        "./src/skf-rename-skill",
+        "./src/skf-drop-skill",
+        "./src/skf-verify-stack",
+        "./src/skf-refine-architecture"
+      ]
+    }
+  ]
+}

package/.gitattributes

@@ -0,0 +1,16 @@
+# Normalize all text files to LF in the repo and on checkout, regardless of
+# the contributor's platform or core.autocrlf setting. SKF runs on Linux,
+# macOS, and Windows (Git Bash / WSL2); LF-everywhere keeps prettier
+# `endOfLine: 'lf'` clean and avoids spurious diffs from line-ending churn.
+* text=auto eol=lf
+
+# Binary blobs — never touch.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary
+*.zip binary
+*.gz binary
+*.tgz binary

package/README.md

@@ -9,13 +9,17 @@
 [![Quality & Validation](https://github.com/armelhbobdad/bmad-module-skill-forge/actions/workflows/quality.yaml/badge.svg)](https://github.com/armelhbobdad/bmad-module-skill-forge/actions/workflows/quality.yaml)
 [![npm](https://img.shields.io/npm/v/bmad-module-skill-forge)](https://www.npmjs.com/package/bmad-module-skill-forge)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![BMad Module](https://img.shields.io/badge/BMad-module-blue)](https://github.com/bmad-code-org/BMAD-METHOD)
+[![BMAD Module](https://img.shields.io/badge/BMAD-module-blue)](https://github.com/bmad-code-org/BMAD-METHOD)
+[![Python Version](https://img.shields.io/badge/python-%3E%3D3.10-blue?logo=python&logoColor=white)](https://www.python.org)
+[![uv](https://img.shields.io/badge/uv-package%20manager-blueviolet?logo=uv)](https://docs.astral.sh/uv/)
 [![Docs](https://img.shields.io/badge/docs-online-green)](https://armelhbobdad.github.io/bmad-module-skill-forge/)
+[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
 [![GitHub stars](https://img.shields.io/github/stars/armelhbobdad/bmad-module-skill-forge?style=social)](https://github.com/armelhbobdad/bmad-module-skill-forge/stargazers)
 
-*Skill Forge analyzes your code repositories, documentation, and developer discourse to build verified instruction files for AI agents. Every instruction links back to where it came from — nothing is made up.*
+_Skill Forge analyzes your code repositories, documentation, and developer discourse to build verified instruction files for AI agents. Every instruction links back to a specific file and line in the source it was compiled from._
 
-**If SKF helps your agent stop hallucinating, give it a ⭐ — it helps others find this tool.**
+**If SKF fixes your agent's API guesses, give it a ⭐ — it helps others find this tool.**
+**If it saved you an afternoon, [grab me a coffee ☕](https://buymeacoffee.com/armelhbobdad) — it helps me keep forging.**
 
 </div>
 
@@ -27,13 +31,7 @@ You ask an AI agent to use a library. It invents function names that don't exist
 
 This isn't an edge case. It's the default experience.
 
-## How Skill Forge Fixes This
-
-1. **Analyzes your sources** — extracts real function signatures, types, and patterns from code repositories, documentation websites, and developer discourse
-2. **Compiles verified instruction files** — every instruction links to the exact file and line it came from
-3. **Version-aware** — skills are stored per-version, so updating to v2.0 doesn't break your v1.x skill. Compatible with [skill.sh](https://skill.sh) and [npx skills](https://www.npmjs.com/package/skills)
-4. **Manageable lifecycle** — rename skills and drop deprecated versions without manual file surgery. Transactional safety for destructive operations.
-5. **Follows an open standard** — skills comply with the [agentskills.io](https://agentskills.io) spec and work across Claude, Cursor, Copilot, and other AI agents
+For the full story behind SKF, read [_Hallucination has a line number_](https://medium.com/@armelhbobdad/hallucination-has-a-line-number-32209b4688de) on Medium.
 
 ## Before vs After
 
@@ -53,80 +51,149 @@ import cognee
 
 # Agent follows the skill instruction:
 # `search(query_text: str, query_type: SearchType = GRAPH_COMPLETION) -> List[SearchResult]`
-# [AST:cognee/api/v1/search/search.py:L26]
+# [AST:cognee/api/v1/search/search.py:L27]
 results = await cognee.search(
     query_text="What does Cognee do?",
     query_type=cognee.SearchType.GRAPH_COMPLETION
 )
 ```
 
-The skill told the agent the real function name, the real parameters, and that the call requires `await` — all traced to the exact source line. This is from a [real generated skill](https://github.com/armelhbobdad/oh-my-skills).
+The skill told the agent the real function name, the real parameters, and that the call is async — all traced to the exact source line. This example is from the real [`oms-cognee`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/oms-cognee/1.0.0/oms-cognee/SKILL.md) skill in [**oh-my-skills**](https://github.com/armelhbobdad/oh-my-skills) — SKF's reference output. The [**Verifying a Skill**](#verifying-a-skill) section below shows how to walk the citation chain yourself.
 
 ## Install
 
-Requires [Node.js](https://nodejs.org/) >= 22.
+Linux, Windows, and macOS supported ([platform details](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/#platform-support)). Requires [Node.js](https://nodejs.org/) >= 22, [Python](https://www.python.org/) >= 3.10, and [uv](https://docs.astral.sh/uv/) (Python package runner).
 
 ```bash
 npx bmad-module-skill-forge install
 ```
 
-You'll be prompted for project name, output folders, and IDE configuration. See the [docs](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/) for other install methods.
+You'll be prompted for project name, output folders, and IDE configuration. When the install completes, open your IDE and invoke `@Ferris SF` to confirm Ferris is reachable. Ferris reports your detected tools and capability tier. See the [docs](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/) for other install methods.
 
 ## Quick Start
 
-1. **Set up your environment:** `@Ferris SF` — detects your tools and sets your capability tier
-2. **Generate your first skill:** `@Ferris QS <package-name>` — creates a verified skill in under a minute
-3. **Full quality path:** `@Ferris BS` → clear session → `@Ferris CS` — brief first, then compile for maximum accuracy
+1. **Set up your environment:** `@Ferris SF` _(Setup Forge)_ — detects your tools and sets your capability tier
+2. **Generate your first skill:** `@Ferris QS <package-name>` _(Quick Skill)_ — creates a verified skill in under a minute
+3. **Full quality path:** `@Ferris forge <your-library>` chains Brief → Create → Test → Export automatically — or run manually: `@Ferris BS` → clear session → `@Ferris CS` for maximum control
 
-> **Tip:** Start a fresh conversation before each workflow. SKF workflows load significant context — clearing between them prevents interference.
+> **Tip:** Start a fresh conversation before each workflow, or use pipeline mode to chain them automatically. SKF workflows load significant context; clearing between them prevents interference.
 
-See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/) for all 14 available workflows.
+See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/) for all available workflows, pipeline aliases, and headless mode.
 
 ## Who Is This For?
 
-- **You use AI agents to write code** and they keep getting API calls wrong — hallucinating function names, guessing parameter types, inventing methods that don't exist
+- **You use AI agents to write code** and they keep guessing API calls wrong
 - **You maintain a library** and want to ship official, verified instruction files so AI agents use your API correctly
 - **You manage a codebase with many dependencies** and want a consolidated "stack skill" that teaches your agent how all the pieces fit together
 - **You use a SaaS API or closed-source tool** with no public code — SKF can generate skills from documentation alone
 - **You need different skills for different use cases** from the same target — compile multiple skills with different scopes from one repo or doc set (e.g., a core API skill and a migration guide skill)
 
+## How SKF Compares
+
+A skeptical reader is probably already considering one of these alternatives:
+
+|                            | **Skill Forge**                           | MCP doc servers   | Hand-edited `.cursorrules` | awesome-\* lists |
+| -------------------------- | ----------------------------------------- | ----------------- | -------------------------- | ---------------- |
+| Reproducible from source   | AST extraction + pinned commit            | varies; opaque    | whatever you wrote         | none             |
+| Version-pinned & immutable | yes — per-version directories             | runtime-dependent | rots silently              | no               |
+| Audit trail                | `provenance-map.json` + test + evidence   | depends on server | none                       | none             |
+| Runtime cost               | zero (markdown + JSON)                    | a running process | zero                       | zero             |
+| Lifecycle tooling          | rename, drop, update, export transactions | varies            | file surgery               | none             |
+| Falsifiable                | yes — three steps, 60 seconds             | rarely            | no                         | no               |
+
+The others aren't bad. They solve different problems. **SKF solves exactly one: the claim your agent is reading about a library was true at a specific commit on a specific day, and you can prove it in under a minute.**
+
+## How Skill Forge Fixes This
+
+SKF extracts real function signatures, types, and patterns from code, docs, and developer discourse — every instruction links to the exact file and line it came from. On top of that foundation:
+
+1. **Version-pinned** — skills are stored per-version, so updating to v2.0 doesn't replace your v1.x skill. Compatible with [skills.sh](https://skills.sh) and [npx skills](https://www.npmjs.com/package/skills)
+2. **Lifecycle tooling** — rename skills and drop deprecated versions without manual file surgery. Destructive operations are transactional.
+3. **Follows an open standard** — skills comply with the [agentskills.io](https://agentskills.io) spec and work across Claude, Cursor, Copilot, and other AI agents
+
+> **Every skill ships two files — `SKILL.md` (the full instruction set, loaded on trigger) and `context-snippet.md` (an 80–120 token always-on index injected into `CLAUDE.md` / `AGENTS.md` / `.cursorrules`). Why both?** Per Vercel's agent evals, passive context achieves a **100% pass rate vs. 79% for active skills loaded alone** (see [Skill Model → Dual-Output Strategy](https://armelhbobdad.github.io/bmad-module-skill-forge/skill-model/#dual-output-strategy)).
+
+## Verifying a Skill
+
+You can falsify any AST citation in an SKF-compiled skill in under a minute:
+
+1. **Open the skill's `provenance-map.json`** — find your symbol; read its `source_file` and `source_line`.
+2. **Open the skill's `metadata.json`** — read `source_commit` and `source_repo`.
+3. **Jump to the upstream repo at that commit**, open that file, find that line. The signature in `SKILL.md` should match the one you're reading.
+
+If it doesn't, that's a bug — open an issue and SKF will republish with a new commit SHA and a new provenance map. Falsifiability isn't a feature; it's the whole deal.
+
+**Reference output: [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills)** — four Deep-tier skills compiled by SKF (cocoindex, cognee, Storybook v10, uitripled), each shipping its full audit trail in-repo. Scores range from 99.0% to 99.49%. Every claim walks to an upstream line in under 60 seconds. Serves as both the worked example for this section and ongoing proof that the pipeline does what it says.
+
+## Help SKF Improve
+
+Workflows end with a health check that can file bug or friction reports as GitHub issues (auto-deduped by fingerprint — re-reporting is safe). **Please let workflows run to completion**, or [open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) directly. [Full details →](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/#terminal-step-health-check)
+
 ## Learn More
 
-- **[Getting Started](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/)** — Installation, prerequisites, and your first skill
-- **[Concepts](https://armelhbobdad.github.io/bmad-module-skill-forge/concepts/)** — Plain-English definitions of all key terms
-- **[How It Works](https://armelhbobdad.github.io/bmad-module-skill-forge/how-it-works/)** — Architecture, capability tiers, output format, and design decisions
+The docs are organized into three buckets — **Why** (start here), **Try** (do stuff), and **Reference** (look things up):
+
+**Why**
+
+- **[Why Skill Forge?](https://armelhbobdad.github.io/bmad-module-skill-forge/why-skf/)** — The JTBD pitch, persona router, and the honest anti-pitch
+- **[Verifying a Skill](https://armelhbobdad.github.io/bmad-module-skill-forge/verifying-a-skill/)** — The 60-second audit recipe and scoring formula
+
+**Try**
+
+- **[Getting Started](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/)** — Install, first skill, prereqs, and config
+- **[How It Works](https://armelhbobdad.github.io/bmad-module-skill-forge/how-it-works/)** — Plain-English walkthrough of one skill being built, end to end
+- **[Examples](https://armelhbobdad.github.io/bmad-module-skill-forge/examples/)** — Real-world scenarios with full command transcripts
 - **[Workflows](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/)** — All 14 workflows with commands and connection diagrams
-- **[Agents](https://armelhbobdad.github.io/bmad-module-skill-forge/agents/)** — Ferris: the AI agent that runs all SKF workflows
-- **[Examples](https://armelhbobdad.github.io/bmad-module-skill-forge/examples/)** — Real-world scenarios, tips, and troubleshooting
+
+**Reference**
+
+- **[Concepts](https://armelhbobdad.github.io/bmad-module-skill-forge/concepts/)** — Seven load-bearing terms: provenance, confidence tiers, drift, and more
+- **[Architecture](https://armelhbobdad.github.io/bmad-module-skill-forge/architecture/)** — Runtime flow, 7 tools, workspace artifacts, security, and the design decisions behind them
+- **[Skill Model](https://armelhbobdad.github.io/bmad-module-skill-forge/skill-model/)** — Capability tiers, confidence tiers, output format, dual-output strategy, ownership model
+- **[Agents](https://armelhbobdad.github.io/bmad-module-skill-forge/agents/)** — Ferris: the single AI agent that runs every SKF workflow
+- **[BMAD Synergy](https://armelhbobdad.github.io/bmad-module-skill-forge/bmad-synergy/)** — How SKF pairs with BMAD CORE phases and optional modules (TEA, BMB, GDS, CIS)
+- **[Troubleshooting](https://armelhbobdad.github.io/bmad-module-skill-forge/troubleshooting/)** — Common errors (forge setup, ecosystem checks, tier confidence) and how to resolve them
 
 ## Acknowledgements
 
 SKF builds on these excellent open-source tools:
 
-| Tool                                                         | Role in SKF                                                        |
-|--------------------------------------------------------------|--------------------------------------------------------------------|
-| [agentskills.io](https://github.com/agentskills/agentskills) | Skill specification and ecosystem standard                         |
-| [GitHub CLI](https://cli.github.com/)                        | Source code access and repository intelligence (all tiers)         |
-| [ast-grep](https://github.com/ast-grep/ast-grep)             | AST-based structural code extraction (Forge/Forge+/Deep tiers)     |
-| [ast-grep MCP](https://github.com/ast-grep/ast-grep-mcp)     | MCP server for memory-efficient AST queries (recommended)          |
-| [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) | Semantic code search and file discovery pre-ranking (Forge+ tier)  |
-| [QMD](https://github.com/tobi/qmd)                           | Local hybrid search engine for knowledge indexing (Deep tier)      |
-| [skill-check](https://github.com/thedaviddias/skill-check)   | Skill validation, auto-fix, quality scoring, and security scanning |
-| [Snyk Agent Scan](https://github.com/snyk/agent-scan)   | Security scanning for prompt injection and data exposure (optional) |
-| [tessl](https://tessl.io)                                     | Content quality review, actionability scoring, and AI judge evaluation |
-| [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD)  | Agent-workflow framework that SKF extends as a module              |
+| Tool                                                             | Role in SKF                                                            |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| [agentskills.io](https://github.com/agentskills/agentskills)     | Skill specification and ecosystem standard                             |
+| [GitHub CLI](https://cli.github.com/)                            | Source code access and repository intelligence (all tiers)             |
+| [ast-grep](https://github.com/ast-grep/ast-grep)                 | AST-based structural code extraction (Forge/Forge+/Deep tiers)         |
+| [ast-grep MCP](https://github.com/ast-grep/ast-grep-mcp)         | MCP server for memory-efficient AST queries (recommended)              |
+| [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) | Semantic code search and file discovery pre-ranking (Forge+ tier)      |
+| [QMD](https://github.com/tobi/qmd)                               | Local hybrid search engine for knowledge indexing (Deep tier)          |
+| [skill-check](https://github.com/thedaviddias/skill-check)       | Skill validation, auto-fix, quality scoring, and security scanning     |
+| [Snyk Agent Scan](https://github.com/snyk/agent-scan)            | Security scanning for prompt injection and data exposure (optional)    |
+| [tessl](https://tessl.io)                                        | Content quality review, actionability scoring, and AI judge evaluation |
+| [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD)      | Agent-workflow framework that SKF extends as a module                  |
 
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
+## Changelog
+
+Past releases are documented in [CHANGELOG.md](CHANGELOG.md).
+
+## Versioning & Stability
+
+The v1.0.0 public API contract is documented in [docs/STABILITY.md](docs/STABILITY.md).
+
+## 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.
+
 ## License
 
 MIT License — see [LICENSE](LICENSE) for details.
 
 ---
 
-**Skill Forge (SKF)** — A standalone [BMad](https://github.com/bmad-code-org/BMAD-METHOD) module for agent skill compilation.
+**Skill Forge (SKF)** — A standalone [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) module for agent skill compilation.
 
 [![Contributors](https://contrib.rocks/image?repo=armelhbobdad/bmad-module-skill-forge)](https://github.com/armelhbobdad/bmad-module-skill-forge/graphs/contributors)
 

package/docs/404.md

@@ -1,20 +1,23 @@
 ---
 title: Page Not Found
-description: The page you're looking for doesn't exist
+description: The URL you tried didn't resolve. Use the search or the links below to continue.
 template: splash
 ---
 
-# Page Not Found
+## 404 — no source cited
 
-The page you're looking for doesn't exist.
+No page resolves to that URL. In keeping with the rest of this site, if a claim can't cite a source, we don't fake it — even for our own docs.
 
-## What can you do?
+Try one of these cited sources instead, or use the **search bar** at the top of the page:
 
-- Check the URL for typos
-- Go back to the [home page](/)
-- Browse the [Getting Started guide](/getting-started/)
-- Search for what you need using the search bar above
+**Why** — [Why Skill Forge?](/why-skf/) · [Verifying a Skill](/verifying-a-skill/)
 
-## Need Help?
+**Try** — [Getting Started](/getting-started/) · [How It Works](/how-it-works/) · [Examples](/examples/) · [Workflows](/workflows/)
 
-If you think this page should exist, please [open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues) on GitHub.
+**Reference** — [Concepts](/concepts/) · [Architecture](/architecture/) · [Skill Model](/skill-model/) · [Agents](/agents/) · [BMAD Synergy](/bmad-synergy/) · [Troubleshooting](/troubleshooting/)
+
+---
+
+### Think this page should exist?
+
+A missing page is drift — a citation the docs site made to itself that no longer resolves. [Open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) with the URL you tried. SKF's docs ship a [drift validator](/verifying-a-skill/#build-time-drift-detection-for-docs-themselves) that catches exactly this pattern — if one slipped through, it's a bug we want to know about.

package/docs/RELEASING.md

@@ -0,0 +1,185 @@
+---
+title: Releasing SKF
+description: Maintainer reference for the release pipeline — branch protection, release workflow, and rollback procedures.
+---
+
+This document records the configuration that gates releases of `bmad-module-skill-forge`. It exists so a future maintainer (including future-you) can audit, restore, or extend the pipeline without reverse-engineering GitHub settings.
+
+For background on GitHub rulesets vs legacy branch protection, see the [GitHub ruleset docs](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets).
+
+## Branch Protection on `main`
+
+`main` is gated by a **GitHub repository ruleset** (not legacy branch protection). The legacy "Settings → Branches → Branch protection rules" surface returns 404 for this repo.
+
+**Ruleset:** `Default` — id `13855503` — applies to `~DEFAULT_BRANCH` (currently `main`) — enforcement `active`.
+
+**Active rules (5):**
+
+| Rule                     | Effect                                                                                                                     |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `deletion`               | Branch cannot be deleted.                                                                                                  |
+| `non_fast_forward`       | Force-push blocked.                                                                                                        |
+| `pull_request`           | Requires ≥ 1 approving review; `require_code_owner_review: true` (see CODEOWNERS note below); merge/squash/rebase allowed. |
+| `code_quality`           | Blocks merge on `severity: errors` from GitHub code-quality checks.                                                        |
+| `required_status_checks` | Merge blocked until all seven `quality.yaml` checks pass (names below).                                                    |
+
+**Required status checks (7):** sourced from `.github/workflows/quality.yaml` job keys. Matrix jobs expand to `jobname (matrix-value)`:
+
+- `prettier`
+- `eslint`
+- `markdownlint`
+- `validate (ubuntu-latest)`
+- `validate (windows-latest)`
+- `python (ubuntu-latest)`
+- `python (windows-latest)`
+
+**Coupling with `quality.yaml`:** if that workflow renames a job or changes the `strategy.matrix.os` for `validate` or `python`, the ruleset's `required_status_checks` list must be updated in lock-step — otherwise merges to `main` will either block on a check name that no longer reports, or silently pass without the renamed check. Update both in the same PR.
+
+**`strict_required_status_checks_policy: false`** — PR branches are not forced to be up-to-date with `main` before merging. This avoids constant rebases on a low-traffic repo. Flip to `true` if concurrent merges start producing logical conflicts the checks can't catch.
+
+**CODEOWNERS note:** the `pull_request` rule has `require_code_owner_review: true`, but no `.github/CODEOWNERS` file exists in the repo today. GitHub treats the code-owner requirement as vacuously satisfied when the file is absent, so this setting is currently a no-op — the only active review gate is `required_approving_review_count: 1`. If a CODEOWNERS file is added later, make sure the listed owners can actually approve PRs from other authors. GitHub's universal rule is that a PR author cannot approve their own PR — so a CODEOWNERS file that lists only a solo maintainer would deadlock every PR that maintainer opens (they'd be the sole eligible code-owner reviewer but also the author).
+
+**Bypass actors:** `RepositoryRole` actor_id=5 (Admin), `bypass_mode: pull_request`. Admins can bypass the ruleset **only via a pull request**, never via direct push. This preserves `non_fast_forward` and the required-checks gate for the `github-actions[bot]` account that the future `release.yaml` workflow (Story 3.1) will use to push tags and commits to `main`. **Do not add a bot-specific bypass**; it would defeat the whole purpose of this ruleset.
+
+### Inspect current state
+
+```bash
+gh api repos/armelhbobdad/bmad-module-skill-forge/rulesets/13855503
+```
+
+### Restore from a saved baseline
+
+A JSON baseline captured before any change can be replayed via:
+
+```bash
+# Extract the full set of fields required by a ruleset PUT from a saved baseline.json.
+# PUT replaces the resource wholesale — omitting any of these fields either 422s or
+# silently resets them server-side. `bypass_actors` is optional (empty array is the
+# default) but is included here to preserve the admin-via-PR bypass.
+jq '{name, target, enforcement, conditions, rules, bypass_actors}' baseline.json > /tmp/restore.json
+
+gh api --method PUT \
+  repos/armelhbobdad/bmad-module-skill-forge/rulesets/13855503 \
+  --input /tmp/restore.json
+```
+
+The GitHub ruleset API uses `PUT` (not `PATCH`) for updates, and the `rules` array is replaced wholesale — it is not merged server-side. Always fetch current state, modify the in-memory copy, and `PUT` the complete list.
+
+## Release Environment
+
+The publish job is gated by a **GitHub [deployment environment](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment) with a required-reviewer rule** (not by workflow logic). A job declaring `environment: release` pauses until a listed reviewer clicks "Approve and deploy" in the Actions UI.
+
+**Environment:** `release` — id `14347249917` — created 2026-04-20.
+
+| Setting                    | Value                                                                                                                                                                                                                                                    |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `wait_timer`               | `0` (no artificial delay; approval is the only gate)                                                                                                                                                                                                     |
+| `prevent_self_review`      | `false` — see rationale below                                                                                                                                                                                                                            |
+| `reviewers`                | `armelhbobdad` (user id `132626034`), 1 approver                                                                                                                                                                                                         |
+| `deployment_branch_policy` | `custom_branch_policies: true`, list: `main` only                                                                                                                                                                                                        |
+| Environment-scoped secrets | `0` (invariant — see `NPM_TOKEN` note below)                                                                                                                                                                                                             |
+| Cost                       | `$0` on public-repo tier (environments, required reviewers, and branch policies are [free for public repositories](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#about-environments)) |
+
+**`prevent_self_review: false` — correctness constraint, not a loosened control.** Solo-maintainer setups cannot self-approve when this is `true`, so the gate would deadlock on any maintainer-triggered publish. The value flips to `true` the moment a second reviewer joins — do not leave it loose by inertia.
+
+**`NPM_TOKEN` is NOT scoped to this environment.** It remains at repo-level secrets during the OIDC transition and is removed entirely post-v1.0.0 (see Story 6.3). The invariant: the `release` env must have zero secrets. If a future change scopes any secret here, re-audit whether the OIDC trusted-publisher path is still in force.
+
+**Coupling with npm trusted publishing (Story 1.3).** The npm trusted publisher binds on four fields — `organization=armelhbobdad`, `repository=bmad-module-skill-forge`, `workflow filename=release.yaml`, `environment=release`. The environment name above is load-bearing: any rename here must be accompanied by a matching npm-side update in the same change, or the next publish returns 404.
+
+### Inspect current state
+
+```bash
+# Environment itself (reviewers, branch-policy shape, prevent_self_review)
+gh api repos/armelhbobdad/bmad-module-skill-forge/environments/release
+
+# Allowed deployment branches (expect: one entry, name "main")
+gh api repos/armelhbobdad/bmad-module-skill-forge/environments/release/deployment-branch-policies
+
+# Environment-scoped secrets (expect: zero)
+gh api repos/armelhbobdad/bmad-module-skill-forge/environments/release/secrets
+```
+
+### Restore / re-apply
+
+Two-call pattern — the environment and its branch-policy list are separate resources. Creating the environment alone with `custom_branch_policies: true` leaves the allow-list empty, which rejects every dispatch; the second call is mandatory.
+
+```bash
+# (1) Create or update the environment with the required-reviewer gate
+gh api --method PUT repos/armelhbobdad/bmad-module-skill-forge/environments/release --input - <<'JSON'
+{
+  "wait_timer": 0,
+  "prevent_self_review": false,
+  "reviewers": [{ "type": "User", "id": 132626034 }],
+  "deployment_branch_policy": {
+    "protected_branches": false,
+    "custom_branch_policies": true
+  }
+}
+JSON
+
+# (2) Add main to the allowed deployment branches.
+#     Returns HTTP 422 ("already_exists") if main is already on the list —
+#     safe to ignore on re-apply. To pre-check:
+#     gh api repos/armelhbobdad/bmad-module-skill-forge/environments/release/deployment-branch-policies
+gh api --method POST repos/armelhbobdad/bmad-module-skill-forge/environments/release/deployment-branch-policies --input - <<'JSON'
+{ "name": "main" }
+JSON
+```
+
+### Temporarily allowing a feature branch
+
+A release workflow that declares `environment: release` will be rejected from any branch not on the allow-list. For legitimate validation cuts from a feature branch (Story 3.2's alpha cut is the canonical case), widen the allow-list for the duration of the test and tighten it back immediately:
+
+```bash
+# Allow the feature branch and capture the returned policy id into a shell var.
+# Using command substitution + --jq .id avoids the "eyeball the JSON and paste
+# the id later" footgun — if the POST succeeds, $POLICY_ID is ready for the revoke.
+POLICY_ID=$(gh api --method POST \
+  repos/armelhbobdad/bmad-module-skill-forge/environments/release/deployment-branch-policies \
+  --input - --jq .id <<'JSON'
+{ "name": "feat/my-validation-branch" }
+JSON
+)
+echo "POLICY_ID=$POLICY_ID"  # confirm a numeric id was captured before proceeding
+
+# ... run the validation cut, approve via the reviewer UI, confirm publish ...
+
+# Revoke immediately — the allow-list must return to { main } before leaving the session.
+# Quote the expansion so the shell never interprets the id as a redirection token.
+gh api --method DELETE \
+  "repos/armelhbobdad/bmad-module-skill-forge/environments/release/deployment-branch-policies/$POLICY_ID"
+```
+
+Leaving a feature branch on the allow-list is an unguarded hole — any later `workflow_dispatch` from that branch would be able to reach the publish path. Treat the revoke as the last step of the validation, not a follow-up.
+
+## npm Trusted Publisher
+
+The future `release.yaml` workflow (Story 3.1) publishes to npm via **OIDC trusted publishing** — no `NPM_TOKEN` is consulted during the publish step, and every published version carries an auto-attached SLSA Build Level 2 provenance attestation. For this to work, the npm package `bmad-module-skill-forge` has a trusted-publisher entry on npmjs.com that binds on four fields exactly matching what the workflow asserts at run time. A mismatch on any field causes an opaque `404` at publish time — the error ("npm could not match your workflow run") surfaces the failure class but does not name which of the four fields is wrong.
+
+**Registered:** 2026-04-20 by `armelhbobdad`.
+
+| Field             | Value                     |
+| ----------------- | ------------------------- |
+| Publisher type    | `GitHub Actions`          |
+| Organization/user | `armelhbobdad`            |
+| Repository        | `bmad-module-skill-forge` |
+| Workflow filename | `release.yaml`            |
+| Environment       | `release`                 |
+
+**Inspect current state:** visit the [npm package settings for `bmad-module-skill-forge`](https://www.npmjs.com/package/bmad-module-skill-forge) → **Settings** tab → **Trusted Publisher** section (npm UI as of 2026-04-20; if the tab is reorganised later, the section still lives on the package Settings page). Modification requires 2FA re-entry on the maintainer account. No CLI or public API for programmatic inspection of Trusted Publisher state exists as of 2026-04-20 — drift detection is UI-only until npm exposes one.
+
+**Case-sensitive.** All four fields above use the exact lowercase forms shown; npm's matcher is an exact-string comparison. Do not capitalize on re-registration even if GitHub's UI surfaces a display-form with capitals.
+
+**Rename coupling — the four fields are load-bearing.** Renaming OR deleting the `release` GitHub environment (see § Release Environment), renaming or moving `release.yaml` within `.github/workflows/`, or flipping the extension between `.yaml` and `.yml` each require matching updates in the same PR to: (a) the npm-side Trusted Publisher, (b) the Registered table above, and (c) the `## Release Process` enumeration in `README.md` (which names both `release` and the Trusted Publisher). Skipping any of these produces an opaque `404` on the next publish — the error names the failure class, not the specific field.
+
+**Pre-registration inversion.** This entry was registered **before** `release.yaml` was authored (Story 3.1). The first live validator of the full OIDC chain is Story 3.2's alpha cut. If that cut's publish step 404s, open a **three-way comparison**: (1) the npm Settings tab, (2) the workflow YAML's `name` / `on` / `jobs.<id>.environment` lines, and (3) the Registered table above. The table is the ground truth because it captured the values at npm-save time — compare both the npm record and the workflow header against the table, never the workflow against itself (verifying the workflow against its own header will silently confirm a typo).
+
+**`NPM_TOKEN` is a legacy residual, not a safety net.** The token remains at repo-level secrets for two reasons: (a) the legacy `publish.yaml` still uses it until Story 3.3 retires that path, and (b) Story 6.3 deletes the secret entirely post-v1.0.0. Treat its continued presence as attack surface to minimize, not defence-in-depth — a repo-scope token is reachable from any workflow with `secrets.*` access. The token does NOT sit "behind" OIDC: `release.yaml` does not yet exist, so there is no OIDC path for it to be a fallback to. If a future OIDC incident forces a last-resort token-based re-publish, document the flip in the commit body and revert as soon as OIDC is restored.
+
+**Fixing a bad registration.** The npm UI exposes both **Edit** and **Delete** on an existing Trusted Publisher entry (observed 2026-04-20). Prefer edit for a single-field typo; prefer delete-and-re-add if multiple fields are wrong or the edit form ever feels ambiguous. **Pre-Story 3.2**: there is no destructive side effect because no publish is attempted yet, and delete-and-re-add keeps the audit trail cleaner. **Post-Story 3.2**: a publish that fires during the delete-and-re-add window will 404 — gate any delete-and-re-add behind a manual publish freeze (pause any active `release.yaml` runs, confirm no tags are in-flight) before touching the entry.
+
+<!-- Rollback Playbook — added in Story 4.1 -->
+
+## 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._