bmad-module-skill-forge 2.1.0 → 2.2.0

package/.claude-plugin/marketplace.json

@@ -30,7 +30,7 @@
       "name": "skill-forge",
       "source": "./",
       "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
-      "version": "2.1.0",
+      "version": "2.2.0",
       "author": {
         "name": "Armel"
       },

package/README.md

@@ -1,3 +1,5 @@
+
+
 <div align="center">
 
 <img src="website/public/img/skf-logo-animated.svg" alt="Skill Forge Logo" width="120" />
@@ -75,7 +77,7 @@ You'll be prompted for project name, output folders, and IDE configuration. When
 1. **Set up your environment:** `@Ferris SF` _(Setup Forge)_ — detects your tools and sets your capability tier
 2. **Zero-ceremony path:** `@Ferris forge-auto <repo-or-doc-url>` _(Forge-Auto)_ — one command turns a repo or doc URL into a verified skill (auto-scope, auto-brief, 90% quality gate, export)
 3. **Fast path:** `@Ferris QS <package-name>` _(Quick Skill)_ — creates a verified skill in under a minute
-4. **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
+4. **Full quality path:** `@Ferris forge <your-library>` chains Brief → Create → Test → Export automatically — or run manually: `@Ferris BS` _(Brief Skill)_ → clear session → `@Ferris CS` _(Create Skill)_ for maximum control
 
 For producing **many coordinated skills** across sessions, `@Ferris campaign` _(Campaign)_ orchestrates the whole set with dependency tracking and resume.
 

package/docs/_data/pinned.yaml

@@ -26,7 +26,7 @@
 # Enforced two ways: (1) release.yaml bumps this line in the same commit
 # as package.json + marketplace.json on every release; (2) validate-docs-drift.js
 # cross-checks this value against package.json.version and fails on mismatch.
-skf_version: "2.1.0"
+skf_version: "2.2.0"
 
 # Path to the oh-my-skills repo, resolved relative to this repo's root.
 # Override at runtime with the OMS environment variable if oh-my-skills

package/docs/_internal/RELEASING.md

@@ -189,6 +189,40 @@ The future `release.yaml` workflow (Story 3.1) publishes to npm via **OIDC trust
 
 **Fixing a bad registration.** The npm UI exposes both **Edit** and **Delete** on an existing Trusted Publisher entry (observed 2026-04-20). Prefer edit for a single-field typo; prefer delete-and-re-add if multiple fields are wrong or the edit form ever feels ambiguous. **Pre-Story 3.2**: there is no destructive side effect because no publish is attempted yet, and delete-and-re-add keeps the audit trail cleaner. **Post-Story 3.2**: a publish that fires during the delete-and-re-add window will 404 — gate any delete-and-re-add behind a manual publish freeze (pause any active `release.yaml` runs, confirm no tags are in-flight) before touching the entry.
 
+## Cutting a Release
+
+The dispatch mechanics are worked end-to-end in [§ Cutting v1.0.0 under --tag latest](#cutting-v100-under---tag-latest). That section is a launch-specific record, but its dispatch command, two-gate sequence, and verification block are the same for every cut. The two steps below are general, apply to every cut, and have no other home — both are invisible until they bite, because the default state of each is the harmless one.
+
+### Pre-dispatch — reconcile a non-empty `## [Unreleased]`
+
+The `Restore CHANGELOG preamble` step splits `CHANGELOG.md` at the **first** `## [X.Y.Z]` header and treats everything above it as preamble. The generated block for the new version is therefore inserted _below_ any prose sitting under `## [Unreleased]`, and the workflow neither empties that section nor warns about it. Check before dispatching:
+
+```bash
+sed -n '/^## \[Unreleased\]/,/^## \[[0-9]/p' CHANGELOG.md
+```
+
+If the `## [Unreleased]` header is immediately followed by the first released header, there is nothing to do — that was the state at every cut through v2.0.2, which is why the interaction went unexercised for so long. If it carries prose, those entries describe work that is about to ship, and after the cut they read as unreleased directly above the release containing them.
+
+**Do not hand-edit it before dispatch.** The `## [X.Y.Z]` header the prose belongs under does not exist until the workflow generates it. Reconcile after publish in a normal PR: move the prose under the generated version header and leave the `## [Unreleased]` header in place with an empty body — deleting the header itself breaks the section split the preamble-restore step depends on.
+
+Prefer moving the prose over dropping it in favour of the generated list. Under `conventionalcommits`, `test:` and `chore:` subjects produce no generated entry at all, and one `fix:` subject often stands in for several distinct fixes, so the hand-written text is frequently the only record of both. v2.1.0 is the worked example: five bullets stranded, moved under `## [2.1.0]` in a follow-up PR.
+
+### Post-publish — delete the bot temp branch after an admin-bypass merge
+
+`Auto-merge bot PR` runs `gh pr merge --auto --merge --delete-branch`, so on the auto-merge path the temp branch `release/bot/vX.Y.Z-<run_id>` is removed when the queued merge fires. Clearing gate 2 with the PR merge button instead — admin bypass, the observed pattern for most cuts — merges the PR directly, and the queued `--delete-branch` never runs. The branch stays on origin.
+
+```bash
+# Expect zero once a cut is fully closed out.
+git ls-remote --heads origin 'release/bot/*'
+
+# Delete a leftover only after confirming its commit is reachable from main.
+git fetch origin --quiet
+git merge-base --is-ancestor <temp-branch-sha> origin/main \
+  && git push origin --delete release/bot/vX.Y.Z-<run_id>
+```
+
+The tag anchors on the bot PR's merge commit on `main`, not on the temp branch (see the `Create and push tag` step's main-dispatch path), so deleting the branch after the merge orphans nothing. The reachability check is what distinguishes this from the tag-orphan case in [§ Scenario D](#scenario-d--tag-exists-but-npm-publish-failed); if the commit is _not_ reachable, the merge did not land and the branch is still load-bearing.
+
 <!-- Rollback Playbook — added in Story 4.1 -->
 
 ## Rollback Playbook

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",

package/src/shared/references/description-guard-protocol.md

@@ -63,6 +63,8 @@ Output JSON:
 
 If `restored == true`, also update the in-context copy of `description` to match `guarded_description` so subsequent stages do not work from a stale tool-mutated version. Record `description_guard_restored: true` (with the tool name) in workflow context for the evidence report.
 
+**Empty snapshot refusal.** The helper exits 1 and leaves the file untouched when `--captured-description` is empty or whitespace-only. There is nothing to restore from: either `guarded_description` was lost from context between capture and verify, or the field was already empty before the tool ran. Never retry with the empty value — writing it back would blank the field the guard exists to protect. If the compiled description is still available in context (the in-context SKILL.md copy), re-run `verify-restore` with that value. Otherwise record `description_guard_restored: false` and `description_guard_refused: empty-capture` (with the tool name) in workflow context; the calling stage's evidence-report populator renders that as a fired guard (`Restored: false`, the triggering tool, `Original description preserved: false`, `Notes: guard refused — empty captured snapshot (empty-capture)`) rather than as the all-`—` clean-run state, and the frontmatter validator surfaces the empty field through the normal artifact path.
+
 ## Why Token-Stream Comparison
 
 Token-stream comparison is the documented sweet spot between two failure modes:

package/src/shared/scripts/skf-description-guard.py

@@ -32,6 +32,9 @@ Subcommands:
          "current_description": "..."}
       If not diverged (including whitespace-only differences), emit
         {"diverged": false, "restored": false, "diff_kind": "none"|"whitespace-only"}
+      An empty or whitespace-only --captured-description is refused with
+      exit 1 before the file is read: there is nothing to restore from, and
+      writing it back would blank the very field this guard protects.
 
 Token-stream comparison is the documented sweet spot — catches replaced
 words, truncation, and reintroduced angle-brackets while ignoring cosmetic
@@ -47,7 +50,8 @@ is auto-resolved:
 
 Exit codes:
   0  — operation succeeded (including no-divergence verify)
-  1  — user error (bad args, file missing, frontmatter unparseable)
+  1  — user error (bad args, empty captured description, file missing,
+       frontmatter unparseable)
   2  — operation failure (restore write failed)
 """
 
@@ -173,6 +177,11 @@ def restore_description(skill_md: Path, captured: str) -> None:
     chooses for each scalar — downstream readers parse YAML, so any valid
     YAML emission is acceptable.
     """
+    if not captured.strip():
+        # Defence in depth for library callers: the CLI refuses this earlier,
+        # but no code path may ever write an empty description.
+        raise ValueError("cannot restore: captured description is empty or whitespace-only")
+
     text = skill_md.read_text(encoding="utf-8")
     leading, fm_yaml, body = _split_frontmatter(text)
     if not fm_yaml:
@@ -238,6 +247,18 @@ def _cmd_capture(args: argparse.Namespace) -> int:
 
 
 def _cmd_verify_restore(args: argparse.Namespace) -> int:
+    captured = args.captured_description
+    if not captured.strip():
+        # Restoring an empty snapshot would blank the field the guard exists
+        # to protect. The snapshot was lost from context, or the description
+        # was already empty before the tool ran; either way there is nothing
+        # to restore, so refuse before touching the file.
+        _fail(
+            "--captured-description is empty or whitespace-only; refusing to "
+            "overwrite the on-disk description with an empty value (the capture "
+            "was lost, or the field was already empty before the tool ran)"
+        )
+
     skill_md = Path(args.skill_md)
     if not skill_md.is_file():
         _fail(f"file not found: {skill_md}")
@@ -246,7 +267,6 @@ def _cmd_verify_restore(args: argparse.Namespace) -> int:
     except ValueError as exc:
         _fail(str(exc))
 
-    captured = args.captured_description
     diff_kind = classify_divergence(captured, current)
     diverged = is_diverged(diff_kind)
 

package/src/shared/scripts/skf-detect-docs.py

@@ -74,6 +74,42 @@ Each list is stably sorted by url.  Stored hashes are normalized (leading
 `algo:` prefix stripped) before comparison so a bare-hex writer form still
 matches.  Exit 0 on any well-formed input (never blocks the informational
 audit); exit 2 on malformed args or JSON.
+
+---------------------------------------------------------------------------
+Subcommand: hash-urls
+---------------------------------------------------------------------------
+
+Compile-time `doc_sources[]` for docs-only skills (create-skill step 5a).
+The detect path above needs a GitHub repository; a docs-only brief has none
+— its `source_repo` is the documentation site and its corpus is the brief's
+`doc_urls`.  This subcommand fetches each URL and hashes the raw response
+bytes with the SAME primitive `compare-hashes` uses, so a hash recorded here
+compares byte-for-byte at audit time.  (Hashing the markdown a web-fetch tool
+rendered would not: the audit re-fetches the raw bytes.)
+
+  uv run src/shared/scripts/skf-detect-docs.py hash-urls <source>
+
+Input `<source>`:
+  - a path to a JSON file that is EITHER an array whose items are URL
+    strings or `{url, ...}` objects (the brief's `doc_urls[]` entry shape)
+    OR an object with a `doc_urls` array (the brief block itself), OR
+  - `-` to read that JSON from stdin.
+
+Output (JSON object on stdout):
+  {
+    "doc_sources":  [{"url", "detected_via": "brief_doc_urls",
+                      "content_hash": "sha256:..."|null, "recorded_at"}],
+    "fetch_failed": [{"url", "reason"}],
+    "stats": {"total", "hashed", "fetch_failed", "invalid"}
+  }
+
+URLs keep their input order and are deduplicated on first occurrence; an
+entry without a usable url string is dropped and counted under
+`stats.invalid`.  A URL that cannot be fetched still gets an entry with
+`content_hash: null` — the audit side files it under `skipped_null_hash`
+instead of reporting drift.  `doc_sources` is already in the metadata.json
+schema, and the whole object is valid `compare-hashes` input.  Exit 0 on any
+well-formed input; exit 2 on malformed args or JSON.
 """
 
 from __future__ import annotations
@@ -88,6 +124,7 @@ import subprocess
 import sys
 import urllib.error
 import urllib.request
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
@@ -252,8 +289,10 @@ def _fetch_and_hash(url: str) -> Optional[str]:
             return "sha256:" + hashlib.sha256(content).hexdigest()
         except (OSError, IOError):
             return None
-    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
     try:
+        # Request() itself raises ValueError on a scheme-less or relative URL;
+        # it must sit inside the guard so a bad entry degrades to None.
+        req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
         with urllib.request.urlopen(req, timeout=_FETCH_TIMEOUT) as resp:
             content = resp.read()
         return "sha256:" + hashlib.sha256(content).hexdigest()
@@ -294,7 +333,14 @@ def _fetch_and_hash_reason(url: str) -> Tuple[Optional[str], Optional[str]]:
         except OSError as exc:
             return None, f"local read failed: {exc}"
         return "sha256:" + hashlib.sha256(content).hexdigest(), None
-    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    try:
+        # Request() raises ValueError ("unknown url type") on a scheme-less or
+        # relative URL — a legal brief entry, since the brief schema only
+        # requires a non-empty string. Keep it inside the guard so one bad
+        # entry lands in fetch_failed instead of aborting the whole run.
+        req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    except ValueError as exc:
+        return None, f"invalid URL: {exc}"
     try:
         with urllib.request.urlopen(req, timeout=_FETCH_TIMEOUT) as resp:
             content = resp.read()
@@ -601,16 +647,166 @@ def _cmd_compare_hashes(argv: List[str]) -> int:
     return 0
 
 
+# ---------------------------------------------------------------------------
+# Subcommand: hash-urls — docs-only doc_sources from the brief's doc_urls
+# ---------------------------------------------------------------------------
+
+# `doc_sources[].detected_via` value for entries that come from the brief's
+# `doc_urls` (and the subpages step 3c fetched from them) rather than from
+# repository detection. Listed in skf-create-skill/assets/skill-sections.md.
+BRIEF_DOC_URLS_DETECTED_VIA = "brief_doc_urls"
+
+
+def _load_url_list(raw_text: str, source_label: str) -> List[Any]:
+    """Parse a hash-urls input blob into a list of URL entries.
+
+    Accepts a top-level JSON array whose items are URL strings or objects
+    with a `url` key (the brief's `doc_urls[]` entry shape), or a top-level
+    object with a `doc_urls` array (the brief block itself). An object without
+    `doc_urls` yields an empty list (nothing to hash).
+
+    Raises ValueError on malformed JSON or an unexpected top-level shape.
+    """
+    try:
+        data = json.loads(raw_text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"malformed JSON in {source_label}: {exc}") from exc
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        entries = data.get("doc_urls")
+        if entries is None:
+            return []
+        if not isinstance(entries, list):
+            raise ValueError(f"`doc_urls` in {source_label} is not an array")
+        return entries
+    raise ValueError(
+        f"{source_label} must be a JSON array or an object with a "
+        f"`doc_urls` array; got {type(data).__name__}"
+    )
+
+
+def hash_urls(entries: List[Any], recorded_at: Optional[str] = None) -> Dict[str, Any]:
+    """Fetch and hash each URL into a compile-time `doc_sources[]` entry.
+
+    Byte-symmetric with `compare_doc_hashes`: both go through
+    `_fetch_and_hash_reason`, so a hash recorded here reads as `unchanged` at
+    audit time for unchanged bytes. URLs keep their input order (brief order,
+    then discovered subpages) and are deduplicated on first occurrence. A URL
+    that cannot be fetched still gets an entry with `content_hash: None`, which
+    the audit side skips rather than reporting as drift.
+    """
+    stamp = recorded_at or datetime.now(timezone.utc).isoformat()
+    doc_sources: List[Dict[str, Any]] = []
+    fetch_failed: List[Dict[str, Any]] = []
+    seen: set = set()
+    invalid = 0
+    for entry in entries:
+        url = entry.get("url") if isinstance(entry, dict) else entry
+        if not isinstance(url, str) or not url.strip():
+            invalid += 1
+            continue
+        if url in seen:
+            continue
+        seen.add(url)
+        content_hash, reason = _fetch_and_hash_reason(url)
+        doc_sources.append({
+            "url": url,
+            "detected_via": BRIEF_DOC_URLS_DETECTED_VIA,
+            "content_hash": content_hash,
+            "recorded_at": stamp,
+        })
+        if content_hash is None:
+            fetch_failed.append({"url": url, "reason": reason})
+    return {
+        "doc_sources": doc_sources,
+        "fetch_failed": fetch_failed,
+        "stats": {
+            "total": len(doc_sources),
+            "hashed": len(doc_sources) - len(fetch_failed),
+            "fetch_failed": len(fetch_failed),
+            "invalid": invalid,
+        },
+    }
+
+
+def _cmd_hash_urls(argv: List[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="skf-detect-docs.py hash-urls",
+        description=(
+            "Fetch each documentation URL, hash the response bytes, and emit "
+            "compile-time doc_sources entries (detected_via: brief_doc_urls) "
+            "for a docs-only skill."
+        ),
+    )
+    parser.add_argument(
+        "source",
+        help=(
+            "path to a JSON file (array of URL strings or {url, ...} objects, "
+            "or an object with a doc_urls array such as the brief's block), "
+            "or - to read that JSON from stdin"
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    if args.source == "-":
+        raw = sys.stdin.read()
+        label = "<stdin>"
+    else:
+        path = Path(args.source)
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except OSError as exc:
+            json.dump({"error": f"cannot read {path}: {exc}", "code": "READ_ERROR"}, sys.stderr)
+            sys.stderr.write("\n")
+            return 2
+        label = str(path)
+
+    try:
+        entries = _load_url_list(raw, label)
+    except ValueError as exc:
+        json.dump({"error": str(exc), "code": "INVALID_JSON"}, sys.stderr)
+        sys.stderr.write("\n")
+        return 2
+
+    result = hash_urls(entries)
+    json.dump(result, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+    return 0
+
+
 # ---------------------------------------------------------------------------
 # CLI entry point
 # ---------------------------------------------------------------------------
 
+def _force_utf8(*streams) -> None:
+    """Reconfigure JSON-carrying streams to UTF-8 (issue #465).
+
+    A default Windows console decodes stdio as cp1252, which cannot carry
+    non-ASCII JSON (raw UTF-8 input on stdin for `compare-hashes -` and
+    `hash-urls -`). Preserves each stream's existing error handler —
+    reconfigure(encoding=...) alone would reset it to 'strict', downgrading
+    e.g. an already-UTF-8 stderr on Linux. For stdin this must run before the
+    first read. Skips in-process test doubles without reconfigure().
+    """
+    for stream in streams:
+        if hasattr(stream, "reconfigure"):
+            errors = getattr(stream, "errors", None)
+            if errors is None:
+                stream.reconfigure(encoding="utf-8")
+            else:
+                stream.reconfigure(encoding="utf-8", errors=errors)
+
+
 def main() -> int:
+    _force_utf8(sys.stdin, sys.stdout)
     # Additive subcommand: route `compare-hashes ...` to the doc-drift path
     # before the existing detect parser runs. The default (no subcommand)
     # invocation `--repo-url <url> ...` is unchanged.
     if len(sys.argv) > 1 and sys.argv[1] == "compare-hashes":
         return _cmd_compare_hashes(sys.argv[2:])
+    if len(sys.argv) > 1 and sys.argv[1] == "hash-urls":
+        return _cmd_hash_urls(sys.argv[2:])
 
     parser = argparse.ArgumentParser(
         description="Detect documentation URLs for a GitHub repository.",

package/src/shared/scripts/skf-detect-tools.py

@@ -89,6 +89,7 @@ DETECT_OUTPUT_SCHEMA (v1):
       "previous_ccc_indexed_path":              str|null,
       "previous_ccc_last_indexed":              str|null,
       "previous_ccc_staleness_threshold_hours": int|null,
+      "previous_ccc_file_count":                 int|null,
       # Deterministic CCC-index freshness verdict — computed against
       # --project-root and datetime.now(UTC) captured at detect time, so the
       # ccc-index.md step branches on a boolean instead of doing timestamp math.
@@ -369,6 +370,7 @@ def read_prior_state(prior_state_path) -> dict:
         "previous_ccc_indexed_path": None,
         "previous_ccc_last_indexed": None,
         "previous_ccc_staleness_threshold_hours": None,
+        "previous_ccc_file_count": None,
     }
     if not prior_state_path:
         return empty
@@ -393,6 +395,10 @@ def read_prior_state(prior_state_path) -> dict:
         "previous_ccc_indexed_path": ccc_index.get("indexed_path"),
         "previous_ccc_last_indexed": ccc_index.get("last_indexed"),
         "previous_ccc_staleness_threshold_hours": ccc_index.get("staleness_threshold_hours"),
+        # Surfaced so ccc-index.md's fresh-index branch can carry the count
+        # forward instead of leaving `{ccc_file_count}` unbound (or nulling a
+        # value the index still has) when nothing re-indexes this run.
+        "previous_ccc_file_count": ccc_index.get("file_count"),
     }
 
 

package/src/skf-create-skill/assets/skill-sections.md

@@ -140,7 +140,8 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
   // "scripts": [{ "file": "scripts/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],
   // "assets": [{ "file": "assets/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],
   // doc_sources[] — include ONLY when doc detection ran; omit if detection was skipped entirely
-  // "doc_sources": [{ "url": "https://...", "detected_via": "homepageUrl|readme_link|pages_api|docs_folder|readme_always", "content_hash": "sha256:{hex}|null", "recorded_at": "ISO-8601" }],
+  // "doc_sources": [{ "url": "https://...", "detected_via": "homepageUrl|readme_link|pages_api|docs_folder|readme_always|brief_doc_urls", "content_hash": "sha256:{hex}|null", "recorded_at": "ISO-8601" }],
+  // detected_via "brief_doc_urls" = docs-only skills: the brief's doc_urls (plus subpages step 3c fetched), hashed by `skf-detect-docs.py hash-urls`
   "generated_by": "{quick-skill|create-skill}",
   "dependencies": [],
   "compatibility": "{semver-range}"

package/src/skf-create-skill/references/step-doc-sources.md

@@ -3,7 +3,8 @@ nextStepFile: 'step-auto-shard.md'
 # Resolve `{detectDocsHelper}` by probing `{detectDocsProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
 # path wins. HALT if neither resolves — §2 has no prose fallback for doc-source
-# detection (Pages-API walk, docs/ folder scan, content hashing).
+# detection (Pages-API walk, docs/ folder scan, content hashing), and §2a none
+# for docs-only URL hashing.
 detectDocsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-detect-docs.py'
   - '{project-root}/src/shared/scripts/skf-detect-docs.py'
@@ -15,7 +16,7 @@ detectDocsProbeOrder:
 
 ## STEP GOAL:
 
-Record detected documentation pages and README with content hashes in metadata.json so that downstream audit (analyze-skill) can detect when upstream docs have changed since the skill was compiled.
+Record detected documentation pages and README — or, for a docs-only skill, the brief's documentation URLs — with content hashes in metadata.json so that downstream audit (analyze-skill) can detect when upstream docs have changed since the skill was compiled.
 
 ## Rules
 
@@ -35,7 +36,9 @@ Check if `doc_detection_results` is already populated in the workflow context (s
 
 ### 2. Run Doc Detection (if needed)
 
-Check that `{source_repo}` is available from the skill brief.
+**If `source_type` is `"docs-only"`:** skip detection — `source_repo` is the documentation site, not a GitHub repository, so `{detectDocsHelper} --repo-url` would exit 2 with `INVALID_URL` and leave `doc_sources[]` empty. The brief's `doc_urls` are the doc sources; continue to §2a.
+
+Otherwise check that `{source_repo}` is available from the skill brief.
 
 **If `{source_repo}` is not available:**
 - Set `doc_detection_results` to an empty array `[]`
@@ -62,8 +65,30 @@ Pass `--local-path {source_path}` when a local clone exists from the extraction
 - **Exit 1** (none found): set `doc_detection_results` to empty array `[]`
 - **Exit 2** (error): set `doc_detection_results` to empty array `[]`, add evidence note: `"Doc sources: detection partial — skf-detect-docs.py error (exit 2)"`
 
+### 2a. Docs-Only: Hash the Brief's Documentation URLs
+
+Runs only when `source_type` is `"docs-only"` (§2 routed here). Build the URL list: every `doc_urls[].url` from the brief, in brief order, followed by every subpage URL that step 3c (fetch-docs) actually fetched through subpage discovery — the `[EXT:{url}]` provenance set of the doc-fetch inventory. Include a brief URL even if step 3c could not fetch it; the helper fetches independently of the agent's web tools.
+
+**Resolve `{detectDocsHelper}`** from `{detectDocsProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Pipe the list to the `hash-urls` subcommand. It fetches each URL and hashes the raw response bytes with the same primitive `skf-audit-skill` step 5a (`compare-hashes`) uses, so a hash recorded here compares byte-for-byte at audit time. Do not hash the markdown a web-fetch tool rendered in step 3c — the audit re-fetches raw bytes, and a rendered-markdown hash would report every page as drifted.
+
+```bash
+printf '%s' '["{url-1}", "{url-2}", "..."]' | uv run {detectDocsHelper} hash-urls -
+```
+
+The input may also be the brief's `doc_urls` block verbatim — an array of `{url, label}` objects, or an object with a `doc_urls` array.
+
+**Handle exit codes:**
+- **Exit 0:** parse the JSON object. Set `doc_detection_results` ← its `doc_sources` array — entries are already in the §4 schema (`url`, `detected_via: "brief_doc_urls"`, `content_hash` — `null` for a URL that could not be fetched — and `recorded_at`). Keep `fetch_failed[]` and `stats` for the §5 evidence note.
+- **Exit 2** (malformed input, unreadable file): set `doc_detection_results` to empty array `[]`, add evidence note: `"Doc sources: detection partial — skf-detect-docs.py hash-urls error (exit 2)"`
+
+Skip §3 — a docs-only brief has no repository README to track. Continue at §4.
+
 ### 3. Ensure README Entry
 
+**If `source_type` is `"docs-only"`:** skip this section — `source_repo` is the documentation site, not a repository, so there is no README to track and `{source_repo}/blob/main/README.md` would be a fabricated URL. Continue at §4.
+
 After obtaining detection results, check if any entry has a URL matching `*/README.md` or `*/readme.md`.
 
 **If a README entry already exists** from detection (e.g., `detected_via: "docs_folder"` found a README): keep it as-is.
@@ -99,6 +124,8 @@ Field mapping from `skf-detect-docs.py` output:
 
 Note: `content_type` from detect-docs output is not carried into `doc_sources`.
 
+For a docs-only skill the `hash-urls` output from §2a is already in this shape (`detected_via: "brief_doc_urls"`, `recorded_at` stamped by the helper) — copy its `doc_sources` entries verbatim.
+
 ### 5. Update metadata.json
 
 Read the staging `_bmad-output/{skill-name}/metadata.json` that compile (step 5) wrote.
@@ -117,6 +144,7 @@ Add evidence note summarizing the result:
 - Success: `"Doc sources: {N} detected, README tracked"`
 - Skip: `"Doc sources: detection skipped — {reason}"`
 - Partial: `"Doc sources: detection partial — {N} found, {errors}"`
+- Docs-only: `"Doc sources: {stats.hashed}/{stats.total} brief doc URL(s) hashed, {stats.fetch_failed} fetch failed"`
 
 ### 6. Auto-Proceed
 

package/src/skf-create-skill/references/sub/fetch-docs.md

@@ -28,6 +28,7 @@ Fetch remote documentation from brief-specified URLs using whatever web fetching
 - Tool-agnostic — use whatever web fetching capability is available
 - Do not halt the workflow if web fetching is unavailable or fails
 - Do not override existing T1, T1-low, or T2 extraction data with T3 content
+- Never delete the staging directory of a `docs-only` skill — the fetched pages are its only source corpus
 
 ## MANDATORY SEQUENCE
 
@@ -173,7 +174,7 @@ This artifact is a **distinct** carrier — it is not merged into the extraction
 
 **If tier is Deep and at least one URL was fetched successfully:**
 
-1. Write fetched markdown files to a staging directory: `_bmad-output/{skill-name}-docs/`
+1. Write fetched markdown files to a staging directory: `_bmad-output/{skill-name}-docs/` — clear any previous contents first, so a corpus retained from an earlier docs-only run (step 5 below) does not mix with this run's pages.
 2. Index into QMD with atomic replace + rollback: if a `{skill-name}-docs` collection already exists, run `qmd collection remove {skill-name}-docs` first, then `qmd collection add {project-root}/_bmad-output/{skill-name}-docs/ --name {skill-name}-docs --mask "*.md"`. **If `qmd collection add` fails after a successful `remove`:** remove any matching `{skill-name}-docs` entry from `forge-tier.yaml` → `qmd_collections[]` to keep the registry consistent with QMD's actual state, warn in evidence-report, and skip the embed — docs enrichment degrades gracefully.
 3. Generate embeddings scoped to this collection (only if step 2 `add` succeeded): `qmd embed --collection {skill-name}-docs` (required for semantic `type:'vec'` and HyDE `type:'hyde'` sub-queries within the QMD `query` tool). If the installed `qmd` CLI does not accept `--collection`, gate the embed behind a freshness check: skip re-embedding if the existing `{skill-name}-docs` registry entry is within 24 hours, and log the skip in the evidence report to prevent unbounded batch-mode re-embedding.
 4. Register in forge-tier.yaml `qmd_collections` array — **acquire an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock` for the read-modify-write** (see the locking pattern documented in step 3b §4). Write via `python3 {atomicWriteHelper} write --target {sidecar_path}/forge-tier.yaml`. If `flock` is unavailable, fall back to read-CAS-by-mtime (capture `st_mtime` before, re-check after; refuse to clobber if a concurrent run wrote in between).
@@ -186,7 +187,7 @@ This artifact is a **distinct** carrier — it is not merged into the extraction
   created_at: "{current ISO date}"
 ```
 
-5. Clean up staging directory after indexing: `rm -rf {project-root}/_bmad-output/{skill-name}-docs/`
+5. Clean up the staging directory after indexing — **only when `source_type` is `"source"`**: `rm -rf {project-root}/_bmad-output/{skill-name}-docs/`. Note that this directory is the source path of the `{skill-name}-docs` collection registered in step 4; removing it is accepted for supplemental docs, whose T3 items already live in the extraction inventory. **When `source_type` is `"docs-only"`, keep the directory.** The fetched pages are the skill's only source corpus — there is no code tree — so deleting them would leave the just-registered collection with nothing to refresh from and nothing to verify citations against. Record the retained path in the evidence report.
 
 **If QMD indexing fails:** Warn: "QMD indexing of fetched docs failed. T3 items are still in the extraction inventory — enrichment will proceed without QMD-indexed docs." Continue.
 
@@ -199,6 +200,7 @@ Display:
 **T3 items extracted:** {count}
 **Confidence:** All doc-fetched items are T3 — `[EXT:{url}]` citations applied.
 {If docs-only mode: '**Mode:** Docs-only — all skill content is T3. source_authority: community'}
+{If docs-only mode AND tier is Deep: '**Docs corpus retained:** `_bmad-output/{skill-name}-docs/`{if the `{skill-name}-docs` collection was registered in §5b: ' — source path of QMD collection `{skill-name}-docs`'}'}
 
 Proceeding to enrichment..."
 

package/src/skf-create-skill/references/validate.md

@@ -62,7 +62,7 @@ To validate the compiled SKILL.md content against the agentskills.io specificati
 
 **Used by:** §2 (`skill-check check --fix`), §4 (`split-body`), and any future tool invocation that may modify SKILL.md.
 
-Load `{descriptionGuardProtocol}` for the full prose explanation of the four-phase guard (why it exists, what counts as divergence, why token-stream comparison is the right shape). The deterministic phases are executed via `{descriptionGuardHelper}` — the calling sections (§2 and §4) invoke the helper at the capture and verify-restore points.
+Load `{descriptionGuardProtocol}` for the full prose explanation of the four-phase guard (why it exists, what counts as divergence, why token-stream comparison is the right shape). The deterministic phases are executed via `{descriptionGuardHelper}` — the calling sections (§2 and §4) invoke the helper at the capture and verify-restore points. `verify-restore` refuses an empty `--captured-description` (exit 1, file untouched); when that happens, follow the protocol's empty-snapshot rule instead of re-running with the empty value.
 
 **This skill's post-restore re-validation hook:** after `{descriptionGuardHelper}` reports `restored: true`, resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}` (first existing path wins), run `uv run {frontmatterValidator} <staging-skill-dir>/SKILL.md` and capture `schema_revalidation_result` in context. If the validator exits non-zero OR reports failure for the `description` field, flip the Schema result back to `FAIL` in the evidence report (overriding any prior PASS/WARN from §2), record `description_guard_revalidation: FAIL` with the validator's diagnostic message, and continue — do not halt (step 9 health-check and result contract still need to run so the failure is surfaced through the normal artifact path).
 
@@ -320,7 +320,7 @@ If the sink, the on-disk rows, and `headless_decisions[]` are all empty, keep th
 - `Original description preserved`: `true` if the restore succeeded (on-disk now matches the pre-tool snapshot), `false` if restoration itself failed (rare — treat as a halt condition in a future version).
 - `Notes`: a one-sentence description of what the tool had changed. Typical values: `"replaced with generic summary"`, `"truncated at N chars"`, `"angle-bracket tokens re-introduced"`, `"field deleted entirely"`. If `Restored: false`, use `—`.
 
-When `Restored: false`, the three follow-up fields are all `—` — this is the clean-run expected state.
+When `Restored: false`, the three follow-up fields are all `—` — this is the clean-run expected state — with one exception: when `description_guard_refused == "empty-capture"` (the protocol's empty-snapshot rule — `verify-restore` exited 1 and no in-context copy allowed a re-run), the guard did fire and must not render as a clean run. Set `Restored: false`, `Triggering tool` to the recorded tool name, `Original description preserved: false`, and `Notes: guard refused — empty captured snapshot (empty-capture)`.
 
 ### 9. Auto-Proceed
 

package/src/skf-setup/references/ccc-index.md

@@ -25,6 +25,7 @@ For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed
 - Do not display skip messages for Quick/Forge tiers
 - Do not fail the workflow if ccc indexing fails
 - The script owns exclusion-pattern validation — do not reimplement it in prose
+- Every branch that leaves this step binds all four of `ccc_index_result`, `ccc_indexed_path`, `ccc_last_indexed`, and `ccc_file_count` — step 2 interpolates each bare into the `write-tools` JSON payload, so an unbound flag would emit its literal placeholder and fail the forge-tier.yaml write
 
 ## MANDATORY SEQUENCE
 
@@ -32,9 +33,9 @@ For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed
 
 Read `{ccc}` and `{ccc_skip_index}` from context.
 
-**If `{ccc}` is false:** Set `{ccc_index_result: "none", ccc_indexed_path: null, ccc_last_indexed: null, ccc_exclude_patterns: [], ccc_exclusion_warnings: [], settings_yml_written: false, settings_yml_patterns_added: 0}`. Proceed directly to section 5 (Auto-Proceed) — no output, no messaging.
+**If `{ccc}` is false:** Set `{ccc_index_result: "none", ccc_indexed_path: null, ccc_last_indexed: null, ccc_file_count: null, ccc_exclude_patterns: [], ccc_exclusion_warnings: [], settings_yml_written: false, settings_yml_patterns_added: 0}`. Proceed directly to section 5 (Auto-Proceed) — no output, no messaging.
 
-**If `{ccc}` is true AND `{ccc_skip_index}` is true:** Run the exclusion-merge (section 3) so settings.yml stays current, then set `{ccc_index_result: "skipped", ccc_indexed_path: null, ccc_last_indexed: null}` and proceed to section 5 (Auto-Proceed) — do not run `ccc init` or `ccc index`. The envelope's `ccc_index.status` will be `"skipped"` so pipelines that plan an out-of-band re-index can distinguish "the operator opted out" from "indexing failed".
+**If `{ccc}` is true AND `{ccc_skip_index}` is true:** Run the exclusion-merge (section 3) so settings.yml stays current, then set `{ccc_index_result: "skipped", ccc_indexed_path: null, ccc_last_indexed: null, ccc_file_count: null}` and proceed to section 5 (Auto-Proceed) — do not run `ccc init` or `ccc index`. The envelope's `ccc_index.status` will be `"skipped"` so pipelines that plan an out-of-band re-index can distinguish "the operator opted out" from "indexing failed".
 
 **If `{ccc}` is true AND `{ccc_skip_index}` is false:** Continue to section 2.
 
@@ -44,7 +45,7 @@ Consume prior CCC state from stage 1's detector output (`prior.*` context flags)
 
 Decide `{needs_reindex}` and `{ccc_index_result}` from `{ccc_index_fresh}`:
 
-- If `{ccc_index_fresh}` is true → index is fresh. Set `{needs_reindex: false}`, `{ccc_index_result: "fresh", ccc_indexed_path: {project-root}, ccc_last_indexed: {previous_ccc_last_indexed}}`. Exclusions still merge in section 3 (which may force a re-index).
+- If `{ccc_index_fresh}` is true → index is fresh. Set `{needs_reindex: false}`, `{ccc_index_result: "fresh", ccc_indexed_path: {project-root}, ccc_last_indexed: {previous_ccc_last_indexed}, ccc_file_count: {previous_ccc_file_count}}` (the count carried over from the prior forge-tier.yaml by step 1 — nothing re-counts on this path). Exclusions still merge in section 3 (which may force a re-index).
 - If `{ccc_index_fresh}` is false (path mismatch, non-fresh status, stale timestamp, or any required prior CCC field null) → `{needs_reindex: true}`.
 
 ### 3. Merge SKF Exclusion Patterns
@@ -111,7 +112,7 @@ ccc index
 
 **If fails:**
 
-- Store `{ccc_index_result: "failed", ccc_indexed_path: null, ccc_last_indexed: null, ccc_indexing_failed_reason: {error}}` (the failed-reason flag flows into step 4's envelope warnings)
+- Store `{ccc_index_result: "failed", ccc_indexed_path: null, ccc_last_indexed: null, ccc_file_count: null, ccc_indexing_failed_reason: {error}}` (the failed-reason flag flows into step 4's envelope warnings)
 - Display: "CCC indexing failed: {error}. Extraction will use direct AST scanning — semantic pre-ranking unavailable this session."
 - Continue — this is not a workflow error
 

package/src/skf-setup/references/detect-and-tier.md

@@ -100,6 +100,7 @@ From `prior` (populated by `--prior-state-from`; all fields null/empty on first
 - `{previous_ccc_indexed_path}` ← `prior.previous_ccc_indexed_path`
 - `{previous_ccc_last_indexed}` ← `prior.previous_ccc_last_indexed`
 - `{previous_ccc_staleness_threshold_hours}` ← `prior.previous_ccc_staleness_threshold_hours`
+- `{previous_ccc_file_count}` ← `prior.previous_ccc_file_count` (integer or null; step 1b carries it forward on the fresh-index path so `forge-tier.yaml` keeps its `file_count` across re-runs that do not re-index)
 - `{ccc_index_fresh}` ← `prior.ccc_index_fresh` (boolean; the script's deterministic freshness verdict — prior index covers this project AND status was fresh/created AND `last_indexed` is within the staleness threshold of now. Step 1b branches on this directly instead of doing timestamp math.)
 
 From `deltas` (computed by the script from current tools + prior; eliminates LLM-side set arithmetic in the report banner):

package/src/skf-update-skill/references/write.md

@@ -65,7 +65,7 @@ Verify the merged SKILL.md that step 4 section 6b wrote to disk, then write the
 
 **Used by:** §7 (`skill-check check --fix` and `skill-check split-body --write`), and any future tool invocation that may modify SKILL.md's frontmatter on disk.
 
-Load `{descriptionGuardProtocol}` for the full prose explanation of the four-phase guard (why it exists, what counts as divergence, why token-stream comparison is the right shape). The deterministic phases are executed via `{descriptionGuardHelper}` — §7 invokes the helper at the capture and verify-restore points around every `skill-check` call.
+Load `{descriptionGuardProtocol}` for the full prose explanation of the four-phase guard (why it exists, what counts as divergence, why token-stream comparison is the right shape). The deterministic phases are executed via `{descriptionGuardHelper}` — §7 invokes the helper at the capture and verify-restore points around every `skill-check` call. `verify-restore` refuses an empty `--captured-description` (exit 1, file untouched); when that happens, follow the protocol's empty-snapshot rule instead of re-running with the empty value.
 
 Update-skill does not run the optional post-restore frontmatter re-validation today — the post-write checks in §1 catch downstream issues, and a `restored: true` outcome is already surfaced through the evidence report (§4).
 
@@ -203,7 +203,7 @@ Append update operation section to `{forge_version}/evidence-report.md` (create
 - Notes: {one-sentence detail or —}
 ```
 
-**Description Guard population** (used by §7 Post-Write Validation when the §0 protocol fires): fill all four fields from context when `description_guard_restored == true` (triggering tool, whether restore succeeded, what changed). When `Restored: false`, the other three fields are `—` — this is the clean-run expected state. Same field semantics and populator logic as create-skill step 6 §8.
+**Description Guard population** (used by §7 Post-Write Validation when the §0 protocol fires): fill all four fields from context when `description_guard_restored == true` (triggering tool, whether restore succeeded, what changed). When `Restored: false`, the other three fields are `—` — this is the clean-run expected state — except when `description_guard_refused == "empty-capture"` (the §0 protocol's empty-snapshot rule): then set `Triggering tool` to the recorded tool name, `Original description preserved: false`, and `Notes: guard refused — empty captured snapshot (empty-capture)`, so a refused restore is distinguishable from a run where the guard never fired. Same field semantics and populator logic as create-skill step 6 §8.
 
 **Context Snippet population** (used by §5 after the staleness check runs): §4 writes the sub-block with placeholders; §5 updates the on-disk evidence report in place after deciding whether to regenerate. Set `Regenerated: true` and populate `Triggers fired` with any combination of `headline-exports`, `version`, `gotchas` when at least one trigger fired. Set `Regenerated: false` and `Triggers fired: —` when none fired (the gap-driven / internals-only outcome). Always fill `Notes` with a one-sentence reason (e.g., `"Gap-driven repair — no snippet surface changed"`, `"Version bumped 0.1.0 → 0.2.0; headline exports re-ranked"`).