bmad-module-skill-forge 2.0.0 → 2.0.1

package/src/skf-create-skill/references/step-auto-shard.md

@@ -1,5 +1,12 @@
 ---
 nextStepFile: 'step-doc-rot.md'
+# Resolve `{shardBodyHelper}` by probing `{shardBodyProbeOrder}` in order
+# (installed SKF module path first, src/ dev-checkout fallback); first existing
+# path wins. HALT if neither resolves — hand line-counting is the least reliable
+# deterministic op and would silently ship an over-budget body or wrongly HALT.
+shardBodyProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-shard-body.py'
+  - '{project-root}/src/shared/scripts/skf-shard-body.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -15,42 +22,66 @@ Proactively reduce oversized SKILL.md bodies to under 400 lines by extracting Ti
 - Auto-proceed step — no user interaction required
 - Graceful skip — if body is under threshold, proceed without modification
 - Only extract Tier 2 sections (identified by `## Full` heading prefix)
-- Tier 1 sections must NEVER be moved to references/
+- Tier 1 sections stay inline — moving one to references/ would break the standalone SKILL.md the two-tier design guarantees
 - Do not modify frontmatter — only body content and references/ directory
 - Do not invoke `npx skill-check split-body` — this step uses direct extraction
 - Do not invoke the Description Guard Protocol — frontmatter is untouched
 
 ## MANDATORY SEQUENCE
 
+### §0. Run the Shard Script (primary path)
+
+The counting, boundary detection, size-sort, file writes, and blockquote replacement described in §1–§5 are fully deterministic and run every invocation — so a script owns them, not the model. Do not count body lines or extract sections by hand when the script ran.
+
+**Resolve `{shardBodyHelper}`** from `{shardBodyProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Run:
+
+```bash
+uv run {shardBodyHelper} <staging-skill-dir>/SKILL.md --budget 400
+```
+
+The script performs everything §1–§5 document — it counts the body between the frontmatter close and EOF, enumerates the `## Full` Tier 2 sections, extracts the largest first to `references/` until the body fits, writes the extracted files and the trimmed SKILL.md through the atomic-write helper, rewrites each section as a cross-reference blockquote, and checks Tier 1 preservation and cross-reference integrity. Read its JSON and set context directly:
+
+- **`action: "skip"`** → the body was already within budget. Log `"auto-shard: skipped (body {body_lines_before} lines)"`, set `auto_shard_triggered: false`, `sections_extracted: []`, `body_lines_before`/`body_lines_after` from the report, then skip to §6.
+- **`action: "shard"`** → set `auto_shard_triggered: true` and copy `sections_extracted`, `body_lines_before`, `body_lines_after` straight from the report.
+- **HALT** if `tier1_preserved` is false: `"Auto-shard removed Tier 1 section(s) {tier1_missing}. Aborting."`
+- **HALT** if `xref_ok` is false: `"Auto-shard cross-references did not resolve. Aborting."`
+- If `under_budget` is false, selective Tier 2 extraction alone could not bring the body under budget (rare — Tier 1 itself exceeds ~300 lines). Apply the §4 editing-judgment trim, then continue.
+
+Log: `"auto-shard: {N} sections extracted, body reduced from {body_lines_before} to {body_lines_after} lines"`, then proceed to §6.
+
+**Manual fallback (only when `uv`/Python is unavailable):** perform §1–§5 by hand as documented below — they describe exactly what the script does.
+
 ### §1. Count Body Lines
 
-Count all lines in the staging SKILL.md between the frontmatter closing `---` and EOF. Exclude trailing blank lines from the count. Store as `body_line_count`.
+The script counts all lines in the staging SKILL.md between the frontmatter closing `---` and EOF, excluding trailing blank lines, and reports the total as `body_lines_before`.
 
 ```
 body_lines_before = body_line_count
 ```
 
-**IF `body_line_count` <= 400:**
+**IF `body_line_count` <= 400:** the script emits `action: "skip"` and writes nothing —
 - Log: `"auto-shard: skipped (body {body_line_count} lines)"`
 - Set context: `auto_shard_triggered: false`, `sections_extracted: []`, `body_lines_before: {body_line_count}`, `body_lines_after: {body_line_count}`
 - Skip to §6 (Auto-Proceed)
 
-**ELSE:** Proceed to §2.
+**ELSE:** the script proceeds to §2.
 
 ### §2. Selective Shard — Tier 2 Extraction
 
-Identify Tier 2 sections by their `## Full` heading prefix:
+The script identifies Tier 2 sections by their `## Full` heading prefix:
 - `## Full API Reference` → `references/full-api-reference.md`
 - `## Full Type Definitions` → `references/full-type-definitions.md`
 - `## Full Integration Patterns` → `references/full-integration-patterns.md`
 
-Sort identified sections by line count descending (extract largest first).
+Sections are sorted by line count descending (largest first).
 
 **FOR EACH Tier 2 section (largest first):**
 
 1. Extract the full section content (from `## Full` heading to the next `##` heading or EOF)
 2. Derive the reference filename from the heading: kebab-case (as shown above)
-3. Write the extracted content (preserving the `##` heading) to `<staging-skill-dir>/references/{filename}`
+3. Write the extracted content (preserving the `##` heading) to `<staging-skill-dir>/references/{filename}` via the atomic-write helper
 4. Replace the extracted section in SKILL.md with a cross-reference blockquote:
    ```markdown
    > See [Full API Reference](references/full-api-reference.md)
@@ -58,44 +89,40 @@ Sort identified sections by line count descending (extract largest first).
 5. Re-count body lines
 6. **IF `body_line_count` <= 400:** stop extracting, proceed to §3
 
-Track: `sections_extracted: [{heading names}]`
+The report's `sections_extracted: [{heading, file, lines}]` records exactly which sections were pulled.
 
 ### §3. Tier 1 Preservation Check
 
-Verify ALL Tier 1 sections remain inline in SKILL.md after extraction. Check for these headings:
+The script verifies ALL Tier 1 sections that were inline before extraction remain inline in SKILL.md afterward. These headings:
 
 - `## Overview`
 - `## Quick Start`
 - `## Common Workflows`
 - `## Key API Summary` (or `## Component Catalog` for component-library scope)
-- `## Migration & Deprecation Warnings` (conditional — only check if it was present before extraction)
+- `## Migration & Deprecation Warnings` (conditional — only checked if it was present before extraction)
 - `## Key Types`
 - `## Architecture at a Glance`
-- `## CLI` (conditional — only check if present before extraction)
-- `## Scripts & Assets` (conditional — only check if present before extraction)
-- `## Manual Sections` (conditional — only check if present before extraction)
+- `## CLI` (conditional — only checked if present before extraction)
+- `## Scripts & Assets` (conditional — only checked if present before extraction)
+- `## Manual Sections` (conditional — only checked if present before extraction)
+
+The result surfaces as `tier1_preserved` (with any pulled headings in `tier1_missing`).
 
-**IF any Tier 1 section is missing after extraction:**
+**IF `tier1_preserved` is false:**
 HALT: `"Auto-shard removed Tier 1 section {name}. Aborting."`
 
 ### §4. Post-Shard Validation
 
-Re-count body lines after all Tier 2 sections have been extracted.
-
-```
-body_lines_after = body_line_count
-```
+The report's `body_lines_after` is the recount after all extraction. `under_budget` is true when the body now fits.
 
-**IF `body_line_count` > 400 after all Tier 2 sections extracted:**
+**IF `under_budget` is false** (body still > 400 after all Tier 2 sections extracted — this is the one genuine editing-judgment step):
 - Trim oversized Tier 1 sections: reduce `## Key API Summary` and `## Architecture at a Glance` content to fit within the 400-line budget
-- Do NOT move any Tier 1 section to references/
-- Re-count and update `body_lines_after`
+- Do not move any Tier 1 section to references/
+- Re-run `{shardBodyHelper}` (or re-count) and update `body_lines_after`
 
 ### §5. Cross-Reference Integrity
 
-**FOR EACH extracted reference file:**
-1. Verify the file exists at `<staging-skill-dir>/references/{filename}`
-2. Verify the cross-reference blockquote in SKILL.md contains a link resolving to the file
+The script verifies, for each extracted reference file, that the file exists at `<staging-skill-dir>/references/{filename}` and that the cross-reference blockquote in SKILL.md links to it — reported as `xref_ok`. HALT if `xref_ok` is false.
 
 Log: `"auto-shard: {N} sections extracted, body reduced from {body_lines_before} to {body_lines_after} lines"`
 

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

@@ -1,5 +1,6 @@
 ---
 nextStepFile: 'validate.md'
+scanDocRotHelper: 'scripts/scan-doc-rot.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -8,7 +9,7 @@ nextStepFile: 'validate.md'
 
 ## STEP GOAL:
 
-Scan feeder artifacts for doc-rot correction indicators and annotate the compiled SKILL.md with `## CORRECTION` blocks. Matching is grep-based and deterministic — no AI judgment is used for detection.
+Scan feeder artifacts for doc-rot correction indicators and annotate the compiled SKILL.md with `## CORRECTION` blocks. Matching is a deterministic substring grep performed by `{scanDocRotHelper}` (`scripts/scan-doc-rot.py`) — no AI judgment is used for detection. The prompt keeps only the genuine judgment the script cannot make: enriching each match's `affected` symbol (§2) and choosing where each `## CORRECTION` block goes (§3).
 
 ## Rules
 
@@ -28,7 +29,7 @@ Identify the feeder artifacts in the **staging directory** for the current skill
 1. **Evidence report:** `_bmad-output/{skill-name}/evidence-report.md`
 2. **Provenance map:** `_bmad-output/{skill-name}/provenance-map.json` — focus on T2/T3 entries with temporal annotations
 3. **Temporal context:** changelogs, migration guides, and issue/PR data fetched by step 3b and enriched by step 4 (available in workflow context)
-4. **Compiled SKILL.md:** the staged `_bmad-output/{skill-name}/SKILL.md` itself — check for `[QMD:...]` or `[DOC:...]` annotations referencing corrections
+4. **Compiled SKILL.md:** the staged `_bmad-output/{skill-name}/SKILL.md` itself — check for `[QMD:...]` or `[DOC:...]` annotations referencing corrections. **Do not treat its own `## Migration & Deprecation Warnings` section (§4b) as a correction source:** compile (step 5 §4b) already authored that section from the same T2-future annotations, so its bullets are already-surfaced corrections — §2 discards matches that land inside it.
 
 For each artifact, attempt to load its content. If an artifact does not exist or is empty, skip it — this is not an error.
 
@@ -36,7 +37,31 @@ Store: `feeder_artifacts_scanned: [{list of artifacts that were loaded}]`
 
 ### §2. Grep for Correction Indicators
 
-Scan each loaded feeder artifact for the following correction patterns. All matches are **case-insensitive substring matches** — no regex interpretation, no semantic analysis.
+The scan is deterministic plumbing — a fixed-table substring grep with one correct answer per input — so it runs in `{scanDocRotHelper}`, **not** in-prompt. Do not hand-grep the feeder artifacts: identical feeders must yield identical `correction_matches`, and only the script guarantees that across multi-KB inputs. Pass the `## Migration & Deprecation Warnings`-bearing compiled SKILL.md (feeder #4) as `--skill-md` and every other loaded feeder as a positional argument:
+
+```bash
+uv run {scanDocRotHelper} \
+  --skill-md _bmad-output/{skill-name}/SKILL.md \
+  _bmad-output/{skill-name}/evidence-report.md \
+  _bmad-output/{skill-name}/provenance-map.json \
+  _bmad-output/{skill-name}-temporal/*.md
+```
+
+(Pass whichever of the §1 feeder paths actually exist — the script skips any that are missing or empty, and reports the loaded set in `scanned`.)
+
+The script emits `{scanned: [...], matches: [...], match_count, excluded_count}` on stdout. Each entry in `matches` is a match record with the deterministic fields the script owns:
+
+- `source`: the feeder artifact path where the match was found
+- `pattern`: the specific pattern string that matched
+- `category`: the category label
+- `context_line`: the line containing the match
+- `line_number`: the 1-indexed line the match sits on
+
+Read `matches` into `correction_matches: [{match records}]`. Then add the one judgment field the script cannot infer:
+
+- `affected`: the function name, API, or section the correction relates to — enrich each record from surrounding context (use the `[QMD:...]`/`[DOC:...]` annotations and nearby symbols); if not identifiable, set to `"unknown"`.
+
+**What the script does (the contract it implements — keep this table and the script's `PATTERN_TABLE` in lockstep):** it matches every feeder line against the following correction patterns. All matches are **case-insensitive substring matches** — no regex interpretation, no semantic analysis.
 
 | Pattern | Category |
 |---------|----------|
@@ -54,16 +79,9 @@ Scan each loaded feeder artifact for the following correction patterns. All matc
 | `migration required` | Migration |
 | `signature changed` | Signature change |
 
-For each match, record:
-- `source`: the feeder artifact path or citation where the match was found
-- `pattern`: the specific pattern string that matched
-- `category`: the category from the table above
-- `context_line`: the line or excerpt containing the match
-- `affected`: the function name, API, or section the correction relates to (extract from surrounding context if identifiable; otherwise set to `"unknown"`)
-
-Store all matches as `correction_matches: [{match records}]`
+**Exclusion — drop already-surfaced §4b corrections (deterministic, no AI judgment, applied inside the script before it emits):** the script discards any match whose `source` is the compiled SKILL.md (feeder #4) **and** whose `context_line` sits inside that file's own `## Migration & Deprecation Warnings` section — i.e. on a line at or after the `## Migration & Deprecation Warnings` heading and before the next `##` heading (`excluded_count` reports how many it dropped). Compile (step 5 §4b) authored that section from the same T2-future annotations, so re-emitting its bullets as `## CORRECTION` blocks in §3 would duplicate already-surfaced content verbatim. This is a positional heading-boundary check on text already loaded, not a semantic assessment. Set `feeder_artifacts_scanned` from the script's `scanned` list.
 
-**IF `correction_matches` is empty:**
+**IF `correction_matches` is empty** (the script returned `match_count: 0`, or the run had no feeder files to pass)**:**
 - Log: `"doc-rot: skipped (no correction indicators found in feeder artifacts)"`
 - Set context: `doc_rot_triggered: false`, `corrections_added: 0`
 - Skip to §5 (Auto-Proceed)

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

@@ -94,10 +94,10 @@ Map each detection result to the `doc_sources` schema:
 Field mapping from `skf-detect-docs.py` output:
 - `url` ← `url` (direct copy)
 - `detected_via` ← `detected_via` (direct copy; or `"readme_always"` for the mandatory README entry)
-- `content_hash` ← `content_hash` (direct copy, already in `sha256:{hexdigest}` format from story 1.2)
+- `content_hash` ← `content_hash` (direct copy, already in `sha256:{hexdigest}` format)
 - `recorded_at` ← generated at step execution time (ISO-8601 with timezone)
 
-Note: `content_type` from detect-docs output is NOT carried into `doc_sources`.
+Note: `content_type` from detect-docs output is not carried into `doc_sources`.
 
 ### 5. Update metadata.json
 

package/src/skf-create-skill/references/sub/ccc-discover.md

@@ -82,7 +82,7 @@ Set `{ccc_discovery: []}` in context.
 
 Display: "CCC discovery unavailable — proceeding with standard extraction."
 
-Do NOT halt. This is not an error.
+Do not halt. This is not an error.
 
 **If search returns empty results:**
 
@@ -92,16 +92,5 @@ No message needed — empty results are normal for small or highly focused libra
 
 ### 5. Auto-Proceed
 
-Immediately load, read entire file, then execute `{nextStepFile}`.
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed step with no user choices
-- Quick/Forge tiers skip directly with no output
-- Forge+/Deep with ccc displays brief discovery summary then auto-proceeds
-- CCC failures do not halt — degrade and proceed
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN discovery is complete (Forge+/Deep with ccc) or the step is skipped (Quick/Forge or ccc unavailable) will you proceed to load `{nextStepFile}` for AST extraction.
+No user interaction. Load `{nextStepFile}`, read it fully, then execute it. CCC failures degrade and proceed — they never halt.
 

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

@@ -86,7 +86,7 @@ Subpage discovery is triggered if **either** of the following independent trigge
 
 The URL matches the path criteria above (ends in `/`, bare domain, or 1 segment) AND the fetched content is under **2000 words**. Short content on root-like URLs almost certainly indicates a navigation hub or landing page, even if it contains introductory code examples that would prevent Trigger 1 from firing. This handles modern doc sites (Mintlify, Docusaurus, GitBook) that include hero sections with code snippets on their root pages.
 
-If neither trigger fires, keep the page content as-is and do NOT trigger subpage discovery.
+If neither trigger fires, keep the page content as-is and do not trigger subpage discovery.
 
 **If a root URL with minimal content is detected:**
 
@@ -136,16 +136,16 @@ Parse the successfully fetched markdown for:
 
 **No hallucination:** If information cannot be found in the fetched content, exclude it. Do not infer or fabricate API details.
 
-**Whole-language references — retain prose, do NOT shred (`whole_language_reference: true`):** For a whole-language reference the registry-sourced corpora (the guide/Book, the standard/library docs) ARE the product, not the compiler's internal exports. Reducing that prose to per-export signature items and then discarding it under the §5 "T3 never overrides T1" rule (the compiler's AST already owns names like `Vec`, `Option`, `HashMap`) would gut exactly the content the skill exists to teach. So for these briefs, skip §4a below for the registry corpora.
+**Whole-language references — retain prose, do not shred (`whole_language_reference: true`):** For a whole-language reference the registry-sourced corpora (the guide/Book, the standard/library docs) ARE the product, not the compiler's internal exports. Reducing that prose to per-export signature items and then discarding it under the §5 "T3 never overrides T1" rule (the compiler's AST already owns names like `Vec`, `Option`, `HashMap`) would gut exactly the content the skill exists to teach. So for these briefs, skip §4a below for the registry corpora.
 
 ### 4a. Retain the Language Guide (whole-language references only)
 
 **Skip this section entirely unless `whole_language_reference: true`.** When it is true, for each `doc_urls` entry whose `source` is `language-registry`:
 
-- Do NOT reduce its fetched markdown to per-export items. Instead retain the cleaned prose as a Language-Guide entry `{url, label, prose}`, where `prose` is the substantive body (narrative, idioms, usage examples, conceptual reference) lightly trimmed of navigation/boilerplate, each block cited `[EXT:{url}]`.
+- Do not reduce its fetched markdown to per-export items. Instead retain the cleaned prose as a Language-Guide entry `{url, label, prose}`, where `prose` is the substantive body (narrative, idioms, usage examples, conceptual reference) lightly trimmed of navigation/boilerplate, each block cited `[EXT:{url}]`.
 - Collect these into a `language_guide[]` context artifact, in `doc_urls` order.
 
-This artifact is a **distinct** carrier — it is NOT merged into the extraction inventory and is NOT subject to the §5 conflict rule, so the canonical prose survives intact into step 5 (compile), which foregrounds it as the skill's Language Guide. Non-registry docs (README-detected, homepage, Pages, docs-folder) still flow through §4's normal per-export extraction and the §5 merge unchanged.
+This artifact is a **distinct** carrier — it is not merged into the extraction inventory and is not subject to the §5 conflict rule, so the canonical prose survives intact into step 5 (compile), which foregrounds it as the skill's Language Guide. Non-registry docs (README-detected, homepage, Pages, docs-folder) still flow through §4's normal per-export extraction and the §5 merge unchanged.
 
 **If a registry corpus could not be fetched** (network failure), record it in `language_guide[]` as `{url, label, prose: null}` and warn — step 5 surfaces the gap rather than emitting a thin guide silently.
 
@@ -156,9 +156,9 @@ This artifact is a **distinct** carrier — it is NOT merged into the extraction
 - **`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.
+**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.
 
-**Language-Guide carve-out:** the `language_guide[]` artifact from §4a (whole-language references) is NOT part of the export inventory and is therefore NOT subject to this conflict rule — it carries no export key, so it cannot collide with a T1 compiler export and can never be pruned. It is passed separately into step 5, which renders it as the foregrounded Language Guide section. Only the per-export T3 items participate in the T1/T2/T3 merge.
+**Language-Guide carve-out:** the `language_guide[]` artifact from §4a (whole-language references) is not part of the export inventory and is therefore not subject to this conflict rule — it carries no export key, so it cannot collide with a T1 compiler export and can never be pruned. It is passed separately into step 5, which renders it as the foregrounded Language Guide section. Only the per-export T3 items participate in the T1/T2/T3 merge.
 
 **Edge case — T1-zero supplemental mode:** If T1 extraction produced zero results and `doc_urls` are present in supplemental mode, T3 items should be used as the primary inventory since no T1 data exists to conflict with.
 
@@ -202,48 +202,6 @@ Display:
 
 Proceeding to enrichment..."
 
-### 7. Menu Handling Logic
+### 7. Auto-Proceed
 
-**Auto-proceed step — no user interaction.**
-
-After documentation fetch is complete (or skipped for any reason), immediately load, read entire file, then execute `{nextStepFile}`.
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed step with no user choices
-- No `doc_urls` in brief: skip directly to next step with no output
-- No web fetching available: skip with warning then auto-proceed
-- All URLs failed: skip with warning then auto-proceed
-- Successful fetch: display report then auto-proceed
-- All failures degrade gracefully — skip and auto-proceed
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN documentation is fetched and T3 items are merged into the extraction inventory (or the step is skipped due to no `doc_urls`, no web tools, or fetch failures) will you proceed to load `{nextStepFile}` for enrichment.
-
----
-
-## SYSTEM SUCCESS/FAILURE METRICS
-
-### SUCCESS:
-
-- No `doc_urls` in brief: skipped silently, auto-proceeded
-- `doc_urls` present: each URL fetched using whatever web tool is available
-- Root URLs with minimal content: subpage discovery attempted, relevant subpages fetched
-- Individual fetch failures handled gracefully (skip and continue)
-- All extracted content cited as T3 with `[EXT:{url}]` provenance
-- 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 4
-
-### SYSTEM FAILURE:
-
-- Halting the workflow because web fetching is unavailable or a URL fails
-- Including fetched content without `[EXT:{url}]` citations
-- 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 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.
+No user interaction. After the fetch completes or is skipped for any reason, load `{nextStepFile}`, read it fully, then execute it.

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

@@ -123,7 +123,7 @@ Per-call rationale:
    rm -f "$ERR_FILE"
    ```
 
-   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."
+   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."
 
    **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.
 
@@ -197,7 +197,7 @@ else
 fi
 ```
 
-**Rollback rule:** if the `qmd collection add` step fails (non-zero exit, network error, parse error) AND the prior `remove` succeeded, the canonical registry entry in `forge-tier.yaml` MUST be removed to match QMD's actual state. A dangling registry entry that points at a non-existent QMD collection poisons subsequent cache-hit checks in §2. Emit a warning in evidence-report and skip the embed — enrichment degrades to no-QMD for this run.
+**Rollback rule:** if the `qmd collection add` step fails (non-zero exit, network error, parse error) after the prior `remove` succeeded, remove the canonical registry entry in `forge-tier.yaml` to match QMD's actual state. A dangling registry entry that points at a non-existent QMD collection poisons subsequent cache-hit checks in §2. Emit a warning in evidence-report and skip the embed — enrichment degrades to no-QMD for this run.
 
 **Scope the embed:** Always pass `--collection {skill-name}-temporal` to `qmd embed`. An unscoped `qmd embed` re-embeds every collection in the QMD store, which can take minutes per run in batch mode and generates wasteful GPU/API cost. If the installed `qmd` CLI does not accept `--collection` (older upstream versions), gate the embed behind a per-skill check: if a previous `{skill-name}-temporal` entry already exists in `qmd_collections` and its `created_at` is within 24 hours, skip the embed entirely and warn "qmd embed skipped — upstream qmd lacks --collection scope; re-embedding all collections would be wasteful in batch mode". Log the skip in the evidence report.
 
@@ -231,7 +231,7 @@ rm -rf {project-root}/_bmad-output/{skill-name}-temporal/
 
 **Error handling:**
 
-- If QMD indexing fails: log the error, note that temporal enrichment will be unavailable. Do NOT fail the workflow.
+- If QMD indexing fails: log the error, note that temporal enrichment will be unavailable. Do not fail the workflow.
 - If registry update fails: log the error, continue. The collection may exist in QMD even if the registry entry failed.
 - If cleanup fails: log a warning and continue.
 
@@ -239,22 +239,7 @@ Display brief confirmation:
 
 "**Temporal context indexed.** Collection `{skill-name}-temporal` created ({file_count} files: {list files}). Proceeding to enrichment..."
 
-### 5. Menu Handling Logic
+### 5. Auto-Proceed
 
-**Auto-proceed step — no user interaction.**
-
-After temporal context is fetched and indexed (or skipped for any reason), immediately load, read entire file, then execute `{nextStepFile}`.
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed step with no user choices
-- Quick/Forge/Forge+ tiers skip directly to next step with no output
-- Non-GitHub sources skip directly to next step with no output
-- Cached collections (< 7 days old) skip with brief cache-hit message
-- Deep tier with fresh fetch displays brief confirmation then auto-proceeds
-- All failures degrade gracefully — skip and auto-proceed
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN temporal context is indexed into QMD (or the step is skipped due to eligibility, cache, or failure) will you proceed to load `{nextStepFile}` for documentation fetch.
+No user interaction. After temporal context is fetched and indexed (or skipped for any reason — non-Deep tier, non-GitHub source, cache hit, or any failure), load `{nextStepFile}`, read it fully, then execute it.
 

package/src/skf-create-skill/references/tier-degradation-rules.md

@@ -8,7 +8,7 @@ When `source_repo` is a remote URL (GitHub URL or owner/repo format) and the tie
 
 **Workspace-first clone strategy (preferred):**
 
-1. Check `git` availability (`git --version`). `git` is effectively guaranteed at Deep tier (via `gh` dependency) but NOT guaranteed at Forge tier.
+1. Check `git` availability (`git --version`). `git` is effectively guaranteed at Deep tier (via `gh` dependency) but not guaranteed at Forge tier.
 2. If `git` is available: check for an existing workspace checkout at `{workspace_root}/repos/{host}/{owner}/{repo}/`. If found, `git fetch` to update. If not found, clone into the workspace path with `--depth 1 --single-branch`. See `source-resolution-protocols.md` for the full workspace resolution algorithm.
 3. The workspace uses a full checkout (no sparse-checkout). Brief `include_patterns` and `exclude_patterns` are applied as file-level filters at extraction time, not at the git level. This allows a single workspace checkout to serve multiple briefs with different scope filters.
 4. For update-skill: `changed_files_from_manifest` scoping is applied as file-level filters at extraction time on the full workspace checkout.
@@ -18,21 +18,19 @@ When `source_repo` is a remote URL (GitHub URL or owner/repo format) and the tie
 
 **Fallback (clone fails or `git` unavailable):**
 
-- The extraction step MUST warn the user explicitly before degrading
-- **create-skill:** Warning must include actionable guidance — clone locally and update `source_repo` in the brief to the local path
-- **update-skill:** Warning must include actionable guidance — clone locally, re-run [CS] Create Skill with the local path to regenerate provenance data, then re-run the update
+- The extraction step warns the user explicitly before degrading — a silent drop from AST (T1) to source reading (T1-low) would leave them trusting a lower-confidence result without knowing it changed
+- **create-skill:** the warning includes actionable guidance — clone locally and update `source_repo` in the brief to the local path
+- **update-skill:** the warning includes actionable guidance — clone locally, re-run [CS] Create Skill with the local path to regenerate provenance data, then re-run the update
 - Extraction proceeds using Quick tier strategy (source reading via gh_bridge — resolved as `gh api` commands or direct file I/O; see `knowledge/tool-resolution.md`)
 - All results labeled T1-low with `[SRC:...]` citations
 - The degradation reason is recorded in the evidence report
 
-Silent degradation is **forbidden**. The user must always know when AST extraction was skipped and why.
-
 ## AST Tool Unavailable at Forge/Deep Tier
 
 When the tier is Forge or Deep but ast-grep is not functional:
 
-- The extraction step MUST warn the user explicitly before degrading
-- Warning must include actionable guidance: run [SF] Setup Forge to detect tools
+- The extraction step warns the user explicitly before degrading
+- The warning includes actionable guidance: run [SF] Setup Forge to detect tools
 - Extraction proceeds using Quick tier strategy
 - All results labeled T1-low
 - The degradation reason is recorded in the evidence report