bmad-module-skill-forge 1.4.1 → 1.5.0

package/src/skf-create-skill/references/source-resolution-protocols.md

@@ -43,9 +43,9 @@ When `brief.target_version` is absent but `brief.version` is present AND `source
 3. **Resolution outcomes:**
    - **Single match:** Store the matched tag as `source_ref`. Use it as `{branch}` in all subsequent clone/API commands. Do not warn — this is the expected path.
    - **Multiple matches:** Present the matching tags to the user — "Multiple tags match `brief.version` ({brief.version}): {list}. Which one should I use, or fall back to HEAD?" Wait for selection.
-   - **Zero matches:** ⚠️ Warn: "No git tag found matching `brief.version` ({brief.version}). Falling back to default branch — **extracted code may not match the declared version.** If you intended to pin a specific version, set `target_version` explicitly in the brief." Set `source_ref` to `HEAD` and proceed with default branch. Append `tag_resolution: {status: "fallback-head", requested: "{brief.version}", reason: "no-matching-tag"}` to the in-context evidence-report payload so step-05 §7 surfaces the fallback in the evidence report. This turns the warning into a persistent audit trail a reviewer can grep later, not just a one-shot stderr line.
+   - **Zero matches:** ⚠️ Warn: "No git tag found matching `brief.version` ({brief.version}). Falling back to default branch — **extracted code may not match the declared version.** If you intended to pin a specific version, set `target_version` explicitly in the brief." Set `source_ref` to `HEAD` and proceed with default branch. Append `tag_resolution: {status: "fallback-head", requested: "{brief.version}", reason: "no-matching-tag"}` to the in-context evidence-report payload so step 5 §7 surfaces the fallback in the evidence report. This turns the warning into a persistent audit trail a reviewer can grep later, not just a one-shot stderr line.
 
-4. **Do not halt on zero matches.** Unlike the explicit path, implicit resolution never blocks compilation — `brief.version` is an auto-populated hint, and some repositories simply do not tag releases. The warning is sufficient notice; the evidence report in step-08 will surface the HEAD fallback for reviewers.
+4. **Do not halt on zero matches.** Unlike the explicit path, implicit resolution never blocks compilation — `brief.version` is an auto-populated hint, and some repositories simply do not tag releases. The warning is sufficient notice; the evidence report in step 8 will surface the HEAD fallback for reviewers.
 
 5. **Store `source_ref`** in context exactly as in the explicit path. It flows through to metadata.json and provenance-map.json so downstream workflows (update-skill, audit-skill) can re-clone from the same ref.
 
@@ -65,7 +65,7 @@ Implicit resolution via `brief.version` is **not applied to local sources** —
 
 ## Remote Source Resolution
 
-**Note:** Quick-tier remote sources do not use the workspace/clone protocol described below. Quick tier accesses remote files via the `gh_bridge.read_file` path described in step-03 section 4.
+**Note:** Quick-tier remote sources do not use the workspace/clone protocol described below. Quick tier accesses remote files via the `gh_bridge.read_file` path described in step 3 section 4.
 
 If `source_repo` is a local path: proceed with the tier-appropriate strategy as normal.
 
@@ -84,7 +84,7 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
 
 3. **Workspace check — resolve the source locally:**
 
-   **Concurrency guard:** all of the operations below (fetch, checkout, rev-parse, and the extraction read that follows in step-03) must be wrapped in an exclusive `flock` on `{workspace_repo_path}/.skf-workspace.lock`. Acquire the lock before the workspace-hit check, hold it across fetch + checkout + rev-parse, AND keep holding it through the extraction-time read of the working tree. Two concurrent batch runs that target the same workspace clone but different `source_ref` values would otherwise race — one would `checkout` while the other was reading files mid-extraction, corrupting the inventory. The lock makes the per-workspace-repo unit of work serial. Use `flock -x {lockfile} -c "..."` or `fcntl.flock(LOCK_EX)`. If `flock` is unavailable, log a warning ("Concurrency guard unavailable — concurrent forges against the same workspace repo may produce inconsistent extraction inventories") and proceed.
+   **Concurrency guard:** all of the operations below (fetch, checkout, rev-parse, and the extraction read that follows in step 3) must be wrapped in an exclusive `flock` on `{workspace_repo_path}/.skf-workspace.lock`. Acquire the lock before the workspace-hit check, hold it across fetch + checkout + rev-parse, AND keep holding it through the extraction-time read of the working tree. Two concurrent batch runs that target the same workspace clone but different `source_ref` values would otherwise race — one would `checkout` while the other was reading files mid-extraction, corrupting the inventory. The lock makes the per-workspace-repo unit of work serial. Use `flock -x {lockfile} -c "..."` or `fcntl.flock(LOCK_EX)`. If `flock` is unavailable, log a warning ("Concurrency guard unavailable — concurrent forges against the same workspace repo may produce inconsistent extraction inventories") and proceed.
 
    **If `{workspace_repo_path}/.git/` exists (workspace hit):**
 
@@ -217,7 +217,7 @@ Also store `source_ref` in context (from tag resolution above, or `HEAD` if no t
 
 **If `source_type: "docs-only"`:** skip this section — no source files exist to reconcile.
 
-After the source path is accessible (local path from step-01, or workspace/ephemeral clone from above), check whether the source contains a version identifier and reconcile it with `brief.version`. Look for the first matching version file in the resolved source path:
+After the source path is accessible (local path from step 1, or workspace/ephemeral clone from above), check whether the source contains a version identifier and reconcile it with `brief.version`. Look for the first matching version file in the resolved source path:
 
 - Python: `pyproject.toml` (`[project] version`), `setup.py` (`version=`), `__version__` in `__init__.py`
 - JavaScript/TypeScript: `package.json` (`"version"`). **Monorepo resolution:** When multiple `package.json` files exist (workspace root + packages), resolve version using this priority:
@@ -232,7 +232,7 @@ After the source path is accessible (local path from step-01, or workspace/ephem
 
 ⚠️ Warn the user: "Brief version ({brief.version}) differs from source version ({source_version}). Using source version ({source_version})."
 
-Update the working version in context to the source version. Record the mismatch in context for the evidence report (step-08).
+Update the working version in context to the source version. Record the mismatch in context for the evidence report (step 8).
 
 **If no version file is found or version cannot be extracted:** keep `brief.version` as-is. No warning needed.
 

package/src/skf-create-skill/{steps-c/sub/step-02b-ccc-discover.md → references/sub/ccc-discover.md}

@@ -1,12 +1,14 @@
 ---
-nextStepFile: '../step-03-extract.md'
+nextStepFile: '../extract.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 2b: CCC Semantic Discovery
 
 ## STEP GOAL:
 
-If tier is Forge+ or Deep AND ccc is available, perform a semantic discovery pass over the source code to identify the most relevant files for the skill being created. Store ranked discovery results in context to pre-rank the file extraction queue in step-03.
+If tier is Forge+ or Deep AND ccc is available, perform a semantic discovery pass over the source code to identify the most relevant files for the skill being created. Store ranked discovery results in context to pre-rank the file extraction queue in step 3.
 
 For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed.
 
@@ -18,8 +20,6 @@ For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Check Tier Eligibility
 
 **If tier is Quick or Forge:**
@@ -32,7 +32,7 @@ Check `tools.ccc` from forge-tier.yaml. If `tools.ccc` is false, set `{ccc_disco
 
 If `tools.ccc` is true, check the remote source guard **before** proceeding to section 2:
 
-**Remote source guard:** If `source_root` is a remote URL (GitHub repository — workspace clone or ephemeral clone happens in step-03), CCC cannot operate yet. Set `{ccc_discovery: []}` and display: "CCC discovery deferred — remote source will be indexed after clone in step-03." Auto-proceed to section 5 (step completion). Step-03 will detect the deferred scenario and run CCC discovery on the resolved clone (workspace or ephemeral) before AST extraction begins.
+**Remote source guard:** If `source_root` is a remote URL (GitHub repository — workspace clone or ephemeral clone happens in step 3), CCC cannot operate yet. Set `{ccc_discovery: []}` and display: "CCC discovery deferred — remote source will be indexed after clone in step 3." Auto-proceed to section 5 (step completion). Step-03 will detect the deferred scenario and run CCC discovery on the resolved clone (workspace or ephemeral) before AST extraction begins.
 
 If `source_root` is a local path, continue to section 2.
 

package/src/skf-create-skill/{steps-c/sub/step-03c-fetch-docs.md → references/sub/fetch-docs.md}

@@ -1,5 +1,5 @@
 ---
-nextStepFile: '../step-04-enrich.md'
+nextStepFile: '../enrich.md'
 # Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
 # path wins. HALT if neither resolves.
@@ -8,6 +8,8 @@ atomicWriteProbeOrder:
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 3c: Fetch Remote Documentation
 
 ## STEP GOAL:
@@ -23,13 +25,11 @@ Fetch remote documentation from brief-specified URLs using whatever web fetching
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Check Eligibility
 
 Evaluate the following conditions. **If the condition fails, skip silently to section 7 (auto-proceed) with no output:**
 
-1. **`doc_urls` is present in the brief data:** Check that `doc_urls` contains at least one URL entry from step-01 context. If `doc_urls` is absent or empty, skip silently.
+1. **`doc_urls` is present in the brief data:** Check that `doc_urls` contains at least one URL entry from step 1 context. If `doc_urls` is absent or empty, skip silently.
 
 No tier gate — if `doc_urls` are present, this step runs at Quick, Forge, and Deep tiers alike.
 
@@ -84,12 +84,28 @@ If neither trigger fires, keep the page content as-is and do NOT trigger subpage
 
 2. **Filter discovered URLs by relevance and origin:** Restrict candidates to the same **registrable domain** as the root URL — strip the URL down to its eTLD+1 (e.g., for root `https://docs.example.com/intro`, accept any subdomain of `example.com` such as `api.example.com` or `docs.example.com`, but reject `example.org` or `cdn.partner.io`). Cross-origin links must be discarded before any fetch. The same-registrable-domain rule prevents Mintlify/Docusaurus link clouds from pulling in tracking pixels, doc-site CDNs, or third-party embeds as if they were canonical docs. From the surviving same-domain candidates, select the most relevant pages by searching for API-related terms in the URL path or title (e.g., `api`, `reference`, `quickstart`, `setup`, `config`, `getting-started`, `guide`, `sdk`, `methods`, `functions`). Exclude pages that are clearly non-API content (e.g., `blog`, `changelog`, `pricing`, `about`, `careers`).
 
-3. **Fetch top subpages:** Fetch up to **10** of the most relevant subpages. For each:
+3. **Fetch top subpages (in parallel):** Fetch up to **10** of the most relevant subpages **concurrently** — subpage fetches are independent and network-bound, so wall-clock benefits substantially from parallel execution. Bound concurrency to **4 in flight** at a time to stay polite to documentation hosts (Mintlify/Docusaurus typically allow more, but conservatism here protects against unrecognized rate limits).
+
+   The parallel pattern depends on the fetch tool:
+
+   - **LLM-driven tools** (Firecrawl `firecrawl_scrape`, `WebFetch`, MCP fetch, browser tools): issue up to 4 tool calls **in a single message**. The agent runtime executes parallel tool calls concurrently; collect results from the batch before issuing the next set of up to 4. Repeat until all up-to-10 subpages have been attempted or rate limiting halts the batch.
+   - **Bash-driven tools** (`curl`, `wget`): use `xargs -P 4 -n 1` to fan out from a newline-separated subpage list. Example:
+
+     ```bash
+     printf '%s\n' "${subpages[@]}" | xargs -P 4 -n 1 -I {} bash -c '
+       url="{}"
+       safe=$(echo -n "$url" | sha256sum | cut -c1-12)
+       curl -sSL --max-time 30 "$url" > "{staging}/subpage-$safe.md" \
+         || echo "fetch failed: $url" > "{staging}/subpage-$safe.md"
+     '
+     ```
+
+   For each subpage (regardless of tool):
    - Use the same web fetching tool as the root URL
    - Store with the subpage URL as provenance: `[EXT:{subpage-url}]`
-   - If a subpage fetch fails, skip it and continue
+   - If a subpage fetch fails, skip it and continue with the rest of the batch — do not halt the whole stage
 
-4. **Rate limiting:** If rate limiting (HTTP 429) is encountered during subpage fetching, stop discovery for this root URL. Keep results collected so far. Log: "Subpage discovery stopped due to rate limiting."
+4. **Rate limiting:** If rate limiting (HTTP 429) is encountered during subpage fetching, stop discovery for this root URL. Keep results collected so far. Log: "Subpage discovery stopped due to rate limiting." For the parallel-tool-call pattern, drop any not-yet-issued tool calls from subsequent batches; for the `xargs` pattern, interrupt the pipeline (set `--max-procs 0` is **not** a graceful stop — the simplest stop is to kill the xargs PID and let in-flight writers complete naturally).
 
 **If ALL URLs fail (including any subpage fetches):** Log warning: "No documentation could be fetched. Proceeding without T3 content." Skip to section 7 (auto-proceed).
 
@@ -110,8 +126,8 @@ Parse the successfully fetched markdown for:
 
 **Mode determines merge behavior:**
 
-- **`source_type: "docs-only"`** — The doc-fetch inventory IS the extraction inventory. It replaces the empty inventory from step-03, since there was no source code to extract from.
-- **`source_type: "source"` (supplemental mode)** — Merge T3 items into the existing extraction inventory from step-03.
+- **`source_type: "docs-only"`** — The doc-fetch inventory IS the extraction inventory. It replaces the empty inventory from step 3, since there was no source code to extract from.
+- **`source_type: "source"` (supplemental mode)** — Merge T3 items into the existing extraction inventory from step 3.
 
 **Conflict rule:** T3 items NEVER override existing T1, T1-low, or T2 items for the same export. When an export already has a higher-confidence entry, the T3 item is discarded. T3 has the lowest priority.
 
@@ -131,7 +147,7 @@ Parse the successfully fetched markdown for:
 1. Write fetched markdown files to a staging directory: `_bmad-output/{skill-name}-docs/`
 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-03b §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).
+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).
 
 ```yaml
 - name: "{skill-name}-docs"
@@ -190,7 +206,7 @@ ONLY WHEN documentation is fetched and T3 items are merged into the extraction i
 - Existing T1/T1-low/T2 items never overridden by T3 data
 - Docs-only mode: doc-fetch inventory correctly replaces empty extraction inventory
 - Supplemental mode: T3 items merged into existing inventory respecting conflict rule
-- Auto-proceeded to step-04
+- Auto-proceeded to step 4
 
 ### SYSTEM FAILURE:
 
@@ -199,6 +215,6 @@ ONLY WHEN documentation is fetched and T3 items are merged into the extraction i
 - Overriding existing higher-confidence extractions (T1, T1-low, T2) with T3 data
 - Hardcoding a specific fetching tool instead of being tool-agnostic
 - Hallucinating API details not found in the fetched content
-- Beginning compilation in this step (that is step-05)
+- Beginning compilation in this step (that is step 5)
 
 **Master Rule:** Documentation fetching is best-effort T3 enrichment. Fetch what you can, cite everything as `[EXT:{url}]`, never override higher-confidence data, and move on. Failures degrade gracefully — they never block the skill compilation pipeline.

package/src/skf-create-skill/{steps-c/sub/step-03b-fetch-temporal.md → references/sub/fetch-temporal.md}

@@ -1,5 +1,5 @@
 ---
-nextStepFile: './step-03c-fetch-docs.md'
+nextStepFile: 'fetch-docs.md'
 # Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
 # path wins. HALT if neither resolves.
@@ -8,23 +8,23 @@ atomicWriteProbeOrder:
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 3b: Fetch Temporal Context
 
 ## STEP GOAL:
 
-To fetch temporal context (issues, PRs, changelogs, release notes) from the source repository and index it into a QMD collection for Deep tier enrichment. This ensures step-04 has historical data to search when annotating extracted functions with T2 provenance.
+To fetch temporal context (issues, PRs, changelogs, release notes) from the source repository and index it into a QMD collection for Deep tier enrichment. This ensures step 4 has historical data to search when annotating extracted functions with T2 provenance.
 
 ## Rules
 
 - Deep tier only — Quick, Forge, and Forge+ tiers skip this step entirely and silently
 - GitHub repositories only — other source types degrade gracefully
 - Do not halt the workflow if fetching or indexing fails
-- Do not modify extraction data from step-03 — this step only creates QMD collections
+- Do not modify extraction data from step 3 — this step only creates QMD collections
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Check Eligibility
 
 Evaluate the following conditions sequentially. **If ANY condition fails, skip silently to section 5 (auto-proceed) with no output:**
@@ -69,57 +69,65 @@ Create a staging directory: `_bmad-output/{skill-name}-temporal/`
 
 Resolve the `owner` and `repo` from `source_repo` (e.g., `acme/toolkit` from `https://github.com/acme/toolkit`).
 
-Execute the following fetches, writing output as markdown files to the staging directory. **If any individual fetch fails, log a warning and continue with the others:**
-
-1. **Issues (last 100):** (rationale: 100 is `gh issue list`'s default max-per-page; a single paginated call captures recent activity without extra round trips or rate-limit pressure)
+Execute the four fetches below **in parallel** — they are independent and the network round-trips dominate wall-clock. Background each, then `wait` for the batch. **If any individual fetch fails, log a warning and continue with the others.** The 4-concurrent fan-out is well under GitHub's authenticated REST rate limit (5000/hr); no bounded-concurrency guard is needed for this set.
 
-   ```bash
-   gh issue list -R {owner}/{repo} --state all --limit 100 --json number,title,state,labels,createdAt,closedAt,body | ...
-   ```
+```bash
+mkdir -p {staging}
+# 1. Issues (last 100)
+( gh issue list -R {owner}/{repo} --state all --limit 100 \
+    --json number,title,state,labels,createdAt,closedAt,body \
+    | jq -r '...' > {staging}/issues.md ) &
+# 2. Merged PRs (last 100)
+( gh pr list -R {owner}/{repo} --state merged --limit 100 \
+    --json number,title,mergedAt,labels,body \
+    | jq -r '...' > {staging}/prs.md ) &
+# 3. Release tags only (the per-tag fetch loop runs sequentially below to
+#    preserve append-immediately crash-resume semantics for releases.md)
+( gh release list -R {owner}/{repo} --limit 10 \
+    --json tagName,name,publishedAt > {staging}/.release-tags.json ) &
+# 4. Changelog (404 is silent skip — note `set +e` so the subshell doesn't
+#    propagate `gh api`'s non-zero exit on missing file)
+( set +e
+  gh api repos/{owner}/{repo}/contents/CHANGELOG.md --jq '.content' \
+    | base64 -d > {staging}/changelog.md 2>/dev/null
+  [ -s {staging}/changelog.md ] || rm -f {staging}/changelog.md ) &
+wait
+```
 
-   Write to `{staging}/issues.md` — format as a markdown document with one section per issue (number, title, state, labels, body summary).
+Per-call rationale:
 
-2. **Merged PRs (last 100):** (rationale: same 100-per-page convention as issues — captures the most recent merges in one API call)
+1. **Issues (last 100):** 100 is `gh issue list`'s default max-per-page; one paginated call captures recent activity without extra round trips or rate-limit pressure. Output → `{staging}/issues.md` formatted as a markdown document with one section per issue.
 
-   ```bash
-   gh pr list -R {owner}/{repo} --state merged --limit 100 --json number,title,mergedAt,labels,body | ...
-   ```
+2. **Merged PRs (last 100):** Same 100-per-page convention as issues — captures the most recent merges in one API call. Output → `{staging}/prs.md`.
 
-   Write to `{staging}/prs.md` — format as a markdown document with one section per PR.
+3. **Release tags + per-release fetches (last 10):** Release notes accumulate slowly relative to issues/PRs; the most recent 10 tags cover roughly the last 6-18 months of changelog-relevant history for typical OSS projects, which is enough context for T2-past annotations without fanning out to dozens of `gh release view` calls.
 
-3. **Releases (last 10):** (rationale: release notes accumulate slowly relative to issues/PRs; the most recent 10 tags cover roughly the last 6-18 months of changelog-relevant history for typical OSS projects, which is enough context for T2-past annotations without fanning out to dozens of `gh release view` calls)
+   **Note:** `gh release list --json` does **not** support the `body` field. The parallel block above fetches tags only (Step 1). After `wait`, run **Step 2 sequentially** to preserve the append-immediately crash-resume contract:
 
-   **Note:** `gh release list --json` does **not** support the `body` field. Use a two-step approach: list tags first, then fetch each release individually with `--json` (which IS supported on `gh release view`).
+   If `{staging}/.release-tags.json` is empty (no releases), skip Step 2 and omit the releases section entirely. Otherwise:
 
    ```bash
-   # Step 1: Get release tags (body NOT available here)
-   gh release list -R {owner}/{repo} --limit 10 --json tagName,name,publishedAt
+   # Sequential per-tag loop. Iterate the JSON tag array verbatim so a
+   # crash mid-loop leaves a partial-but-well-formed releases.md on disk.
+   echo "# Releases (partial if interrupted)" > {staging}/releases.md
+   ERR_FILE="{staging}/.gh-release-err"  # per-run stderr capture inside staging
+   jq -r '.[].tagName' {staging}/.release-tags.json | while IFS= read -r tag; do
+     if gh release view "$tag" -R {owner}/{repo} \
+          --json tagName,name,publishedAt,body 2>"$ERR_FILE"; then
+       jq -r '...' >> {staging}/releases.md  # one ## {tag} block per release
+     else
+       echo "## $tag — fetch failed: $(cat "$ERR_FILE")" \
+         >> {staging}/releases.md
+     fi
+   done
+   rm -f "$ERR_FILE"
    ```
 
-   If Step 1 returns an empty array (no releases), skip Step 2 and omit the releases section entirely.
+   Failed individual fetches get a one-line placeholder; the loop continues with remaining tags. If a rate limit (HTTP 429) is hit, stop the release loop, keep the partial `releases.md` file in place (do NOT delete it), and log: "Release fetch stopped at tag {N}/{total} due to rate limiting — partial releases.md retained."
 
-   ```bash
-   # Step 2: For EACH tagName from Step 1, fetch the full release
-   gh release view {tagName} -R {owner}/{repo} --json tagName,name,publishedAt,body
-   ```
+   **Why sequential here when the rest is parallel:** the append-per-release pattern guarantees that a mid-loop abort (rate limit, network drop, user interrupt) leaves a partial but well-formed `releases.md` with every release fetched so far. Parallel writers appending to the same file would need file locking and per-writer ordering — the simpler sequential loop is robust for free, and 10 release fetches contribute only ~5-10s of the total wall-clock.
 
-   Iterate over every `tagName` from Step 1's JSON array. **Append each release to `{staging}/releases.md` immediately after its `gh release view` call returns** — do not buffer the entire loop in memory and write once at the end. The append-per-release pattern guarantees that a mid-loop abort (rate limit, network drop, user interrupt) leaves a partial but well-formed `releases.md` with every release fetched so far, rather than discarding all of them because the loop didn't reach its final write.
-
-   Write an empty `{staging}/releases.md` with a header (`# Releases (partial if interrupted)`) before the loop, then append one `## {tagName} — {name} ({publishedAt})` section per successful fetch. Failed individual fetches get a one-line placeholder: `## {tagName} — fetch failed: {error}`.
-
-   If `gh release view` fails for a specific tag, log a warning and skip that release — continue with remaining tags. If a rate limit (HTTP 429) is hit, stop the release loop, keep the partial `releases.md` file in place (do NOT delete it), and log: "Release fetch stopped at tag {N}/{total} due to rate limiting — partial releases.md retained."
-
-   Format each section as a markdown block with tag, name, date, and body.
-
-4. **Changelog (if exists):**
-
-   Check if `CHANGELOG.md` or `RELEASES.md` exists in the repository root:
-
-   ```bash
-   gh api repos/{owner}/{repo}/contents/CHANGELOG.md --jq '.content' | base64 -d
-   ```
-
-   If found, write to `{staging}/changelog.md`. If not found (404), skip silently.
+4. **Changelog:** `CHANGELOG.md` or `RELEASES.md` at the repository root. The parallel block above writes to `{staging}/changelog.md` only when the file exists; non-existence (404 from `gh api`) leaves no file behind.
 
 #### 3b. Targeted Function Searches (Uses Extraction Inventory)
 
@@ -127,19 +135,42 @@ After the generic fetches above, perform **targeted searches** using the top-lev
 
 **Short-circuit on empty `top_exports`:** If `extraction_inventory.top_exports` is missing or `== []` (docs-only mode, or a source extraction that produced zero public exports), skip this sub-section entirely with a one-line log: "No exports in inventory — skipping targeted function searches." The generic fetches from §3 remain in place and continue to provide baseline temporal context.
 
-**Limit:** Search the top **10 function names** maximum to control API call volume and avoid `gh` rate limiting. (rationale: 10 targeted searches + generic fetches from §3 stays well under GitHub's unauthenticated search rate limit of 10 requests/minute and authenticated 30/minute; matches the `top_exports[]` size emitted by step-03 §5 so every tracked export gets one search.)
+**Limit:** Search the top **10 function names** maximum to control API call volume and avoid `gh` rate limiting. (rationale: 10 targeted searches + generic fetches from §3 stays well under GitHub's unauthenticated search rate limit of 10 requests/minute and authenticated 30/minute; matches the `top_exports[]` size emitted by step 3 §5 so every tracked export gets one search.)
 
 For each function name in `top_exports[]` (up to 10), **sanitize first**: strip every character that is not in `[A-Za-z0-9_]` from `function_name` to produce `safe_name`. This prevents shell injection and `gh` query parser errors when an export name contains punctuation (e.g., `<T>`, `.method`, `::namespace`, quotes). If `safe_name` is empty after sanitization (the original was entirely punctuation — rare but possible for symbol exports), fall back to piping the original name through stdin via `--query-from-file -`-style indirection if your `gh` version supports it; otherwise skip that one entry with a log line — never substitute the unsanitized name back into the shell command.
 
+**Parallel fan-out (bounded concurrency = 5):** sanitized searches are independent and benefit from parallelism. Use `xargs -P 5` so at most 5 `gh search` calls are in flight at once — this stays well under GitHub's authenticated search rate limit (30/min) while saving ~5-8s of wall-clock on a top-10 export list compared to fully sequential.
+
 ```bash
-# safe_name = re.sub(r'[^A-Za-z0-9_]', '', function_name); skip if empty
-# --limit 5: top-5 issues per function keeps signal-to-noise high (most matches
-# below rank 5 are typically keyword coincidences, not targeted discussions) and
-# caps the total response size across 10 function fan-outs at 50 issues.
-gh search issues --repo {owner}/{repo} "{safe_name}" --limit 5 --json number,title,state,body
+# 1. Sanitize and write one safe_name per line; skip empties.
+#    Python is the canonical sanitizer because awk/sed regex semantics
+#    vary across platforms.
+jq -r '.top_exports[]' {extraction_inventory.json} \
+  | python3 -c 'import sys,re
+for line in sys.stdin:
+  s = re.sub(r"[^A-Za-z0-9_]", "", line.strip())
+  if s: print(s)' > {staging}/.safe-names.txt
+
+# 2. Fan out to gh search, 5 in flight. Each writer emits a self-contained
+#    section to its own per-name file; we concatenate after the wait.
+# --limit 5: top-5 issues per function keeps signal-to-noise high and caps
+#    total response size across 10 fan-outs at 50 issues.
+mkdir -p {staging}/targeted
+cat {staging}/.safe-names.txt | xargs -P 5 -I {} bash -c '
+  gh search issues --repo {owner}/{repo} "{}" --limit 5 \
+      --json number,title,state,body 2>/dev/null \
+    | jq -r ". | \"## {}\\n\" + (...)" > {staging}/targeted/{}.md \
+  || echo "## {} — fetch failed" > {staging}/targeted/{}.md
+'
+
+# 3. Concatenate in stable order (alpha by safe_name) into the single
+#    aggregated file the rest of the workflow expects.
+sort {staging}/.safe-names.txt | while IFS= read -r name; do
+  cat "{staging}/targeted/$name.md"
+done > {staging}/targeted-issues.md
 ```
 
-Aggregate all targeted search results into a single file: `{staging}/targeted-issues.md`. Format as a markdown document with one section per function name, listing the matching issues/PRs found.
+Aggregate all targeted search results into a single file: `{staging}/targeted-issues.md`. The per-name temp directory `{staging}/targeted/` can be removed after concat — it exists only to give each parallel writer an isolated output stream.
 
 **If `gh search` is unavailable** (older `gh` CLI versions): skip targeted searches silently. The generic fetches from section 3 still provide baseline temporal context.
 

package/src/skf-create-skill/{steps-c/step-06-validate.md → references/validate.md}

@@ -1,6 +1,7 @@
 ---
-nextStepFile: './step-07-generate-artifacts.md'
+nextStepFile: 'generate-artifacts.md'
 tesslDismissalData: 'assets/tessl-dismissal-rules.md'
+descriptionGuardProtocol: '{project-root}/src/shared/references/description-guard-protocol.md'
 # Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
 # path wins. HALT if neither resolves — losing atomic-write guarantees is not
@@ -8,8 +9,18 @@ tesslDismissalData: 'assets/tessl-dismissal-rules.md'
 atomicWriteProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+# Resolve `{descriptionGuardHelper}` by probing `{descriptionGuardProbeOrder}`
+# in order (installed SKF module path first, src/ dev-checkout fallback);
+# first existing path wins. HALT if neither resolves — letting an external
+# tool's rewrite of the description field stand would silently regress
+# discovery quality.
+descriptionGuardProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-description-guard.py'
+  - '{project-root}/src/shared/scripts/skf-description-guard.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 6: Validate
 
 ## STEP GOAL:
@@ -20,38 +31,19 @@ To validate the compiled SKILL.md content against the agentskills.io specificati
 
 - Focus only on validating compiled content against spec — only fix spec compliance issues
 - Validation and auto-fix modify files in the staging directory
-- `<staging-skill-dir>` resolves to `_bmad-output/{skill-name}/` as created by step-05. The directory name must match the skill's frontmatter `name` field exactly — `skill-check`'s `frontmatter.name_matches_directory` rule rejects any suffix.
+- `<staging-skill-dir>` resolves to `_bmad-output/{skill-name}/` as created by step 5. The directory name must match the skill's frontmatter `name` field exactly — `skill-check`'s `frontmatter.name_matches_directory` rule rejects any suffix.
 - If skill-check unavailable: skip validation, add warning to evidence report
 - Ignore non-zero exit codes from skill-check if JSON output shows 0 errors
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 0. Description Guard Protocol
 
 **Used by:** §2 (`skill-check check --fix`), §4 (`split-body`), and any future tool invocation that may modify SKILL.md.
 
-External validators occasionally rewrite the frontmatter `description` field — `skill-check --fix` may replace it with a generic or truncated version, and `split-body` may touch it during mechanical restructuring. The step-05 §2a compiled description is **authoritative**: it has already been sanitized of angle-bracket tokens and trigger-optimized for agent discovery. Losing it to a tool's well-meaning rewrite breaks discovery quality and re-introduces the angle-bracket failure mode.
-
-To prevent this, any tool invocation that may touch SKILL.md must run inside the following four-phase guard:
-
-1. **Capture.** Before invoking the tool, read the current SKILL.md frontmatter and snapshot the exact `description` value into a local variable (e.g., `guarded_description`). Capture the in-context copy as well.
-2. **Execute.** Run the tool as specified in its section.
-3. **Verify.** After the tool completes, re-read the on-disk SKILL.md and compare its frontmatter `description` against `guarded_description` as **token streams**: split each string on whitespace (`str.split()` — any run of spaces/tabs/newlines collapses) and compare the resulting lists element-by-element. This catches content divergence (missing words, replaced phrases, truncation, angle-bracket re-introduction) while ignoring cosmetic whitespace changes that a tool may apply (trailing newline, re-wrapped quoted strings). Do NOT use a normalized-string equality — a tool that rewrites `"foo  bar"` to `"foo bar"` (collapsed inner run) would trip a naive normalization even though no semantic content changed, and a tool that swapped one word would slip past a looser fuzzy match. Token-stream comparison is the sweet spot.
-4. **Restore on divergence.** If the post-tool description differs from `guarded_description` in any way other than whitespace normalization, write `guarded_description` back to the on-disk SKILL.md frontmatter and update the in-context copy to match. Record `description_guard_restored: true` with the tool name in context for the evidence report.
-5. **Re-validate restored description.** After a restore, run `uv run {project-root}/src/shared/scripts/skf-validate-frontmatter.py <staging-skill-dir>/SKILL.md` against the on-disk file to confirm the restored description still satisfies the frontmatter contract (length limits, forbidden tokens, required fields). The script declares pyyaml in its PEP 723 inline metadata; `uv run` resolves it automatically (per `docs/getting-started.md`'s uv prereq), while bare `python3` would `ModuleNotFoundError` on a fresh interpreter. 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-09 health-check and result contract still need to run so the failure is surfaced through the normal artifact path).
-
-**What counts as divergence:**
+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.
 
-- The description was replaced (different content).
-- The description was truncated (suffix missing).
-- Angle-bracket tokens were re-introduced (should never happen after step-05 §2a, but protect anyway).
-- The field was deleted entirely (extreme tool behavior).
-
-**What does NOT count as divergence:** whitespace-only differences (trailing newline, trimmed spaces) — treat as equivalent.
-
-**Why this is centralized:** previously, §2 and §4 each contained their own capture/verify/restore prose. Duplicated defensive code drifts: a fix in one section doesn't propagate to the other, and adding a new tool invocation in the future requires remembering to copy the pattern. Centralizing the protocol gives step-06 one place to update when external validator behavior changes.
+**This skill's post-restore re-validation hook:** after `{descriptionGuardHelper}` reports `restored: true`, run `uv run {project-root}/src/shared/scripts/skf-validate-frontmatter.py <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).
 
 ### 1. Check Tool Availability
 
@@ -86,7 +78,21 @@ This performs frontmatter validation, description quality checks, body limit enf
 
 **Parse the JSON output** for: `qualityScore` (0-100), `diagnostics[]` (remaining issues), `fixed[]` (auto-corrected issues).
 
-**Description Guard Protocol:** This invocation may modify SKILL.md (especially when `fixed[]` is non-empty). Wrap the `skill-check check --fix` call in the four-phase protocol defined in §0: capture `guarded_description` before the call, execute, verify against the post-tool description, and restore on divergence. If `fixed[]` is non-empty, also re-read the modified SKILL.md to sync the in-context copy before proceeding — this prevents silent divergence between the in-context and on-disk versions that step-07 will use for artifact generation.
+**Description Guard Protocol:** This invocation may modify SKILL.md (especially when `fixed[]` is non-empty). Wrap the `skill-check check --fix` call in the four-phase guard defined in §0 by invoking `{descriptionGuardHelper}` at the capture and verify-restore points:
+
+```bash
+# Phase 1 — capture before the tool call
+uv run {descriptionGuardHelper} capture <staging-skill-dir>/SKILL.md
+# stash the returned `description` as `guarded_description` in workflow context
+
+# Phase 2 — run skill-check (see command block above)
+
+# Phases 3+4 — verify and restore after the tool call
+uv run {descriptionGuardHelper} verify-restore <staging-skill-dir>/SKILL.md \
+    --captured-description "{guarded_description}"
+```
+
+If `restored: true` in the verify-restore output, apply §0's post-restore re-validation hook. If `fixed[]` was non-empty in the skill-check output, also re-read the modified SKILL.md to sync the in-context copy before proceeding — this prevents silent divergence between the in-context and on-disk versions that step 7 will use for artifact generation.
 
 **Note:** `skill-check` may return non-zero exit code even when `errorCount` is 0. Always rely on parsed JSON, not the shell exit code.
 
@@ -113,7 +119,21 @@ If fails: auto-fix (deterministic), re-validate once, record result. If passes:
 
 **If step 2 reported `body.max_lines` failure:**
 
-**Description Guard Protocol:** Split operations may rewrite the frontmatter. Wrap the split invocation in the four-phase protocol defined in §0 to capture `guarded_description` before the call, execute, verify, and restore on divergence.
+**Description Guard Protocol:** Split operations may rewrite the frontmatter. Wrap the split invocation in the four-phase guard defined in §0:
+
+```bash
+# Phase 1 — capture before the split
+uv run {descriptionGuardHelper} capture <staging-skill-dir>/SKILL.md
+# stash returned `description` as `guarded_description`
+
+# Phase 2 — run the split (selective extraction or, last-resort, split-body --write)
+
+# Phases 3+4 — verify and restore after the split
+uv run {descriptionGuardHelper} verify-restore <staging-skill-dir>/SKILL.md \
+    --captured-description "{guarded_description}"
+```
+
+If `restored: true` in the verify-restore output, apply §0's post-restore re-validation hook.
 
 **Mandatory approach — selective split:** Identify Tier 2 sections by their `## Full` heading prefix (e.g., `## Full API Reference`, `## Full Type Definitions`, `## Full Integration Patterns`). Extract ONLY those sections to `references/`, starting with the largest. Keep ALL Tier 1 content and any smaller sections inline. Inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval (per Vercel research).
 
@@ -162,7 +182,7 @@ Parse output for: `description_score`, `content_score`, `review_score`, `validat
 **Apply dismissal rules** in this order:
 
 1. **Check score thresholds** against the "Score Thresholds" table in `{tesslDismissalData}`. Most importantly:
-   - If `description_score < 100`: follow the **recover-then-halt** path defined by the `description-xml-tags-guarded-upstream` rule in `{tesslDismissalData}`. Re-apply step-05 §2a's `<`/`>` → `{`/`}` substitution in place on the staging SKILL.md frontmatter `description`, re-sync the in-context copy, and re-run `npx -y tessl skill review <staging-skill-dir>` once. **Re-run gate:** treat `description_score == 100` on the re-run as the only successful recovery outcome. ANY value strictly less than 100 on the re-run — including 99, intermediate-but-improved scores like 95 (formerly tolerated as "close enough"), or 0 — counts as recovery failure: halt with the original `description-xml-tags-guarded-upstream` failure message from `{tesslDismissalData}`, do NOT proceed to §6b, and do NOT downgrade the recovery to a warning. If the re-run produces `description_score == 100`, log `description-recovery: applied ({count} substitutions)` in the evidence report under "Dismissed tessl suggestions" and continue suggestion iteration against the rerun's `judge_suggestions[]`.
+   - If `description_score < 100`: follow the **recover-then-halt** path defined by the `description-xml-tags-guarded-upstream` rule in `{tesslDismissalData}`. Re-apply step 5 §2a's `<`/`>` → `{`/`}` substitution in place on the staging SKILL.md frontmatter `description`, re-sync the in-context copy, and re-run `npx -y tessl skill review <staging-skill-dir>` once. **Re-run gate:** treat `description_score == 100` on the re-run as the only successful recovery outcome. ANY value strictly less than 100 on the re-run — including 99, intermediate-but-improved scores like 95 (formerly tolerated as "close enough"), or 0 — counts as recovery failure: halt with the original `description-xml-tags-guarded-upstream` failure message from `{tesslDismissalData}`, do NOT proceed to §6b, and do NOT downgrade the recovery to a warning. If the re-run produces `description_score == 100`, log `description-recovery: applied ({count} substitutions)` in the evidence report under "Dismissed tessl suggestions" and continue suggestion iteration against the rerun's `judge_suggestions[]`.
    - If `review_score < 60` or `content_score < 60`: record warnings in the evidence report, continue.
 2. **Iterate `judge_suggestions[]`.** For each suggestion:
    - Cross-reference against the rules in `{tesslDismissalData}` in order.