bmad-module-skill-forge 1.4.1 → 1.5.1

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
 
@@ -69,11 +61,11 @@ Run the external skill-check tool against the compiled skill staging directory.
 **Flag probe (run once, cache the result for §4 and §5 re-invocations):**
 
 ```bash
-npx skill-check --help 2>/dev/null | grep -- --no-security-scan
+npx skill-check check --help 2>/dev/null | grep -- --no-security-scan
 ```
 
 - If the probe matches `--no-security-scan`: set `{security_scan_flag} = "--no-security-scan"`.
-- Else run a second probe — `npx skill-check --help 2>/dev/null | grep -- --skip-security` — and if it matches, set `{security_scan_flag} = "--skip-security"`.
+- Else run a second probe — `npx skill-check check --help 2>/dev/null | grep -- --skip-security` — and if it matches, set `{security_scan_flag} = "--skip-security"`.
 - If neither flag exists: set `{security_scan_flag} = ""` (empty) AND set `{skill_check_flag_fallback} = true`. Skip §2 and §4 automated flows entirely — fall through to §3 manual frontmatter validation. Record in evidence-report: `skill_check_flag_probe: neither --no-security-scan nor --skip-security supported by installed skill-check; validation performed manually`.
 
 **If a security-scan-disable flag was resolved (probe succeeded):**
@@ -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.

package/src/skf-create-stack-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skf-create-stack-skill
-description: Consolidated project stack skill with integration patterns — code-mode (analyzes manifests) or compose-mode (synthesizes from existing skills + architecture doc). Use when the user requests to "create a stack skill."
+description: Consolidated project stack skill with integration patterns — code-mode (analyzes manifests) or compose-mode (synthesizes from existing skills + architecture doc). Use when the user requests to "create a stack skill", "forge a stack", or "stack this project".
 ---
 
 # Create Stack Skill
@@ -9,46 +9,80 @@ description: Consolidated project stack skill with integration patterns — code
 
 Produces a consolidated stack skill documenting how libraries connect. **Code-mode** analyzes dependency manifests and co-import patterns from actual source code. **Compose-mode** synthesizes from pre-generated individual skills and architecture documents when no codebase exists yet. Every finding must trace to actual code with file:line citations; in compose-mode, inferred integrations are permitted but must be labeled `[inferred from shared domain]`.
 
+## Conventions
+
+- Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
 ## Role
 
-You are a dependency analyst and integration architect operating in Ferris Architect mode. You bring expertise in dependency analysis, cross-library integration patterns, and compositional architecture, while the user brings their project knowledge and scope preferences.
+You are a dependency analyst and integration architect. You bring expertise in dependency analysis, cross-library integration patterns, and compositional architecture, while the user brings their project knowledge and scope preferences.
 
 ## Workflow Rules
 
 These rules apply to every step in this workflow:
 
 - Zero hallucination — all extracted content must trace to actual source code (compose-mode inferences must be labeled)
-- Read each step file completely before taking any action
-- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
 - Only load one step file at a time — never preload future steps
 - If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
 - Always communicate in `{communication_language}`
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
-- **Workflow state contract — `workflow_warnings[]` accumulator (M4):** every step that emits a warning ("log a warning", "record in workflow state for the evidence report", "Warning: ...", etc.) MUST append a structured entry to a single in-memory list named `workflow_warnings[]`. Each entry has the shape `{step: "step-NN", severity: "info|warn|error", code: "<short-slug>", message: "<human text>", context: {<optional fields>}}`. Step-07 surfaces these in `evidence-report.md`; step-08 may add validation findings; step-09 §5 reads the accumulated list and renders the user-facing "Warnings" section. Do not invent a per-step warning channel — there is exactly one accumulator for the whole workflow.
+- Warnings use a single accumulator — see `## Workflow state contract` below for shape and surfacing.
+
+## Workflow state contract
+
+Every step that emits a warning ("log a warning", "record in workflow state for the evidence report", "Warning: ...", etc.) appends a structured entry to a single in-memory list named `workflow_warnings[]`. Each entry has the shape `{step: "step-NN", severity: "info|warn|error", code: "<short-slug>", message: "<human text>", context: {<optional fields>}}`. Step 7 surfaces these in `evidence-report.md`; step 8 may add validation findings; step 9 §5 reads the accumulated list and renders the user-facing "Warnings" section. There is exactly one accumulator for the whole workflow — do not invent per-step channels.
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
-| 1 | Initialize & Mode Detection | steps-c/step-01-init.md | No (confirm) |
-| 2 | Detect Manifests | steps-c/step-02-detect-manifests.md | Yes |
-| 3 | Rank & Confirm Libraries | steps-c/step-03-rank-and-confirm.md | No (confirm) |
-| 4 | Parallel Extract | steps-c/step-04-parallel-extract.md | Yes |
-| 5 | Detect Integrations | steps-c/step-05-detect-integrations.md | Yes |
-| 6 | Compile Stack | steps-c/step-06-compile-stack.md | No (review) |
-| 7 | Generate Output | steps-c/step-07-generate-output.md | Yes |
-| 8 | Validate | steps-c/step-08-validate.md | Yes |
-| 9 | Report | steps-c/step-09-report.md | Yes |
-| 10 | Workflow Health Check | steps-c/step-10-health-check.md | Yes |
+| 1 | Initialize & Mode Detection | references/init.md | No (confirm) |
+| 2 | Detect Manifests | references/detect-manifests.md | Yes |
+| 3 | Rank & Confirm Libraries | references/rank-and-confirm.md | No (confirm) |
+| 4 | Parallel Extract | references/parallel-extract.md | Yes |
+| 5 | Detect Integrations | references/detect-integrations.md | Yes |
+| 6 | Compile Stack | references/compile-stack.md | No (review) |
+| 7 | Generate Output | references/generate-output.md | Yes |
+| 8 | Validate | references/validate.md | Yes |
+| 9 | Report | references/report.md | Yes |
+| 10 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
 | **Inputs** | project_path [required], mode (code/compose) [auto-detected] |
-| **Gates** | step-03: Confirm Gate [C] | step-06: Review Gate [C] |
+| **Gates** | step 3: Confirm Gate [C] | step 6: Review Gate [C] |
 | **Outputs** | SKILL.md (stack), context-snippet.md, metadata.json |
 | **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **Exit codes** | See "Exit Codes" below |
+
+## Exit Codes
+
+Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
+
+| Code | Meaning              | Raised by                                                                                  |
+| ---- | -------------------- | ------------------------------------------------------------------------------------------ |
+| 0    | success              | step 10 (terminal handoff to shared health-check)                                          |
+| 2    | input-missing / input-invalid | step 1 §0 (`config.yaml` missing or malformed); step 2 §2 headless cannot proceed without manifests (S2); step 4 §3 all extractions failed (B7); step 5 §2 feasibility-report `schemaVersion` mismatch; compose-mode-rules `schemaVersion` mismatch |
+| 3    | resolution-failure   | step 1 §1 (`forge-tier.yaml` missing); step 2 §0 compose-mode skill resolution corruption (manifest + symlink both fail); step 2 §0 compose-mode zero qualifying skills (S1/S3) |
+| 4    | write-failure        | step 7 §1 stage-dir / commit-dir failure; step 7 §1 group-dir collision when an existing non-stack skill occupies the target path |
+| 5    | overwrite-cancelled  | step 7 collision when the user declines to replace an existing stack package |
+| 6    | user-cancelled       | any interactive menu in step 3 / step 6 (user selected `[X]` Cancel and exit) |
+
+## Result Contract (Headless)
+
+When `{headless_mode}` is true, step 9 emits a single-line JSON envelope on **stdout** before chaining to step 10, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
+
+```
+SKF_STACK_RESULT_JSON: {"status":"success|error","skill_package":"…|null","skill_name":"…","stack_libraries":["…"],"mode":"code|compose","exit_code":0,"halt_reason":null}
+```
+
+`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `skill_package` is the absolute path to the committed stack-skill directory (or `null` on error before commit). `skill_name` is the stack skill's published name (e.g. `{project_name}-stack`). `stack_libraries` is the array of library names included in the stack (constituent skill names in compose-mode, dependency names in code-mode). `mode` is `"code"` or `"compose"` per the run's resolved mode. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"forge-tier-missing"`, `"config-missing"`, `"no-manifests"`, `"all-extractions-failed"`, `"schema-version-mismatch"`, `"resolution-failure"`, `"write-failure"`, `"overwrite-cancelled"`, `"user-cancelled"`. `exit_code` matches the table above.
 
 ## On Activation
 
@@ -61,4 +95,29 @@ These rules apply to every step in this workflow:
    3. **Preferences fallback.** Otherwise, read `headless_mode` from `{sidecar_path}/preferences.yaml` (`true` or `false`).
    4. **Default:** `false`.
 
-3. Load, read the full file, and then execute `./steps-c/step-01-init.md` to begin the workflow.
+3. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-root} --key workflow
+   ```
+
+   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+
+   - `{skill-root}/customize.toml` — bundled defaults
+   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
+   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+
+   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+
+   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each of the five scalars, if the merged value is empty or absent, use the bundled default:
+
+   - `{stackSkillTemplatePath}` ← `workflow.stack_skill_template_path` if non-empty, else `assets/stack-skill-template.md`
+   - `{integrationPatternsPath}` ← `workflow.integration_patterns_path` if non-empty, else `references/integration-patterns.md`
+   - `{manifestPatternsPath}` ← `workflow.manifest_patterns_path` if non-empty, else `references/manifest-patterns.md`
+   - `{composeModeRulesPath}` ← `workflow.compose_mode_rules_path` if non-empty, else `references/compose-mode-rules.md`
+   - `{provenanceMapSchemaPath}` ← `workflow.provenance_map_schema_path` if non-empty, else `assets/provenance-map-schema.md`
+
+   Stash all five as workflow-context variables. Stage files reference `{stackSkillTemplatePath}` / `{integrationPatternsPath}` / `{manifestPatternsPath}` / `{composeModeRulesPath}` / `{provenanceMapSchemaPath}` directly — no conditional at the usage site. Empty-string overrides cleanly fall through to the bundled default; non-empty values let orgs swap in house-style copies without forking the skill.
+
+4. Load, read the full file, and then execute `references/init.md` to begin the workflow.

package/src/skf-create-stack-skill/assets/provenance-map-schema.md

@@ -0,0 +1,102 @@
+---
+type: static-reference
+---
+
+# provenance-map.json Schema
+
+Canonical schema templates for the workspace `provenance-map.json` artifact written in step 7 §7. Two variants exist — choose by the run's resolved mode:
+
+- **code-mode** — when the workflow analyzed a real codebase with manifest files and AST-extracted exports
+- **compose-mode** — when the workflow synthesized a stack from pre-generated constituent skills + an architecture document
+
+Both variants share the top-level `provenance_version`, `skill_name`, `skill_type`, `generated_at`, `entries[]`, and `integrations[]` shape. They differ in source-anchor fields (`source_repo` / `source_commit` / `source_ref`), in `entries[].extraction_method` values, in `integrations[].detection_method` values, and in compose-mode's additional `constituents[]` array which enables drift detection via metadata-hash comparison.
+
+> **Note:** Per-export entries use the same schema as single skills (see `skill-sections.md`), with `source_library` identifying the originating library. In compose-mode, `constituents[]` enables audit to detect constituent drift via metadata hash comparison.
+
+## Code-mode variant
+
+Used when the workflow ran in code-mode against an actual codebase. `source_repo` and `source_commit` capture the upstream anchor(s); `entries[].extraction_method` records how each export was discovered (`ast_bridge`, `source_reading`, or `qmd_bridge`). `integrations[].detection_method` is `"co-import grep"` because integration pairs are confirmed by co-import file evidence.
+
+```json
+{
+  "provenance_version": "2.0",
+  "skill_name": "{project_name}-stack",
+  "skill_type": "stack",
+  "source_repo": ["{repo_url_1}", "{repo_url_2}"],
+  "source_commit": {"{repo_1}": "{hash_1}", "{repo_2}": "{hash_2}"},
+  "generated_at": "{ISO-8601}",
+  "entries": [
+    {
+      "export_name": "{name}",
+      "export_type": "{type}",
+      "source_library": "{library-name}",
+      "params": [],
+      "return_type": "{type}",
+      "source_file": "{file}",
+      "source_line": 0,
+      "confidence": "T1|T1-low|T2",
+      "extraction_method": "ast_bridge|source_reading|qmd_bridge",
+      "signature_source": "T1|T2|T3"
+    }
+  ],
+  "integrations": [
+    {
+      "libraries": ["{libA}", "{libB}"],
+      "pattern_type": "{type}",
+      "detection_method": "co-import grep",
+      "co_import_files": [{"file": "{path}", "line": 0}],
+      "confidence": "T1|T2"
+    }
+  ]
+}
+```
+
+## Compose-mode variant
+
+Used when the workflow ran in compose-mode against pre-generated constituent skills. Source-anchor fields (`source_repo`, `source_commit`, `source_ref`) are `null` because there is no codebase to anchor against — provenance traces back to the constituent skills instead, captured in the `constituents[]` array. Each entry's `extraction_method` is `"compose-from-skill"`; integrations have `detection_method` of `"architecture_co_mention"` (named in the architecture doc) or `"inferred_from_shared_domain"` (synthesized inference, must carry T2/T3 confidence).
+
+```json
+{
+  "provenance_version": "2.0",
+  "skill_name": "{project_name}-stack",
+  "skill_type": "stack",
+  "source_repo": null,
+  "source_commit": null,
+  "source_ref": null,
+  "generated_at": "{ISO-8601}",
+  "entries": [
+    {
+      "export_name": "{name}",
+      "export_type": "{type}",
+      "source_library": "{library-name}",
+      "params": [],
+      "return_type": "{type}",
+      "source_file": "{from constituent skill}",
+      "source_line": 0,
+      "confidence": "T1|T1-low|T2",
+      "extraction_method": "compose-from-skill",
+      "signature_source": "T1|T2|T3"
+    }
+  ],
+  "integrations": [
+    {
+      "libraries": ["{libA}", "{libB}"],
+      "pattern_type": "{type}",
+      "detection_method": "architecture_co_mention|inferred_from_shared_domain",
+      "co_import_files": [],
+      "confidence": "T2|T3"
+    }
+  ],
+  "constituents": [
+    {
+      "skill_name": "{constituent-skill-name}",
+      "skill_path": "skills/{skill-dir}/",
+      "version": "{version from constituent metadata.json}",
+      "composed_at": "{ISO-8601}",
+      "metadata_hash": "sha256:{hash of constituent metadata.json}"
+    }
+  ]
+}
+```
+
+**Use the `metadata_hash` value already stored in workflow state during step 2 (S13) — do NOT re-read and re-hash at step 7 time. The stored hash captures the state as it was at manifest-detection time, which is the correct provenance anchor.**

package/src/skf-create-stack-skill/assets/stack-skill-template.md

@@ -32,7 +32,7 @@ description: >
 
 | Library | Imports | Key Exports | Confidence | Reference |
 |---------|---------|-------------|------------|-----------|
-| {name} | {count} | {top_exports} | {tier} | [ref](./references/{name}.md) |
+| {name} | {count} | {top_exports} | {tier} | [ref](references/{name}.md) |
 
 ## Per-Library Summaries