bmad-module-skill-forge 1.4.1 → 1.5.0

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

@@ -1,18 +1,38 @@
 ---
-nextStepFile: './sub/step-03b-fetch-temporal.md'
-componentExtractionStepFile: './step-03d-component-extraction.md'
+nextStepFile: 'sub/fetch-temporal.md'
+componentExtractionStepFile: 'component-extraction.md'
 extractionPatternsData: 'references/extraction-patterns.md'
 extractionPatternsTracingData: 'references/extraction-patterns-tracing.md'
 tierDegradationRulesData: 'references/tier-degradation-rules.md'
 sourceResolutionData: 'references/source-resolution-protocols.md'
+authoritativeFilesProtocol: 'references/authoritative-files-protocol.md'
 # Probe installed SKF module path first, src/ dev-checkout fallback. At first
 # use below, resolve `{atomicWriteHelper}` to the first existing path; HALT if
 # neither candidate exists — losing atomic-write guarantees is not an option.
 atomicWriteProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+# Resolve `{detectScriptsAssetsHelper}` to the first existing path; HALT if
+# neither candidate exists. §4c relies on the helper for deterministic
+# script/asset detection (file walk, SHA-256 hashing, header-comment purpose
+# extraction); falling back to prose-driven detection would lose hash stability.
+detectScriptsAssetsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-scripts-assets.py'
+  - '{project-root}/src/shared/scripts/skf-detect-scripts-assets.py'
+# Resolve `{resolveAuthoritativeFilesHelper}` to the first existing path;
+# HALT if neither exists. §2a uses it to scan the source tree for
+# authoritative AI documentation files, classify each against scope
+# filters + amendments, and load previews + content hashes — all five
+# deterministic phases in one call. Falling back to prose-driven file
+# walking + glob matching + hashing would let the LLM drift on the
+# heuristic list and miss auth-doc files at deeper directory depths.
+resolveAuthoritativeFilesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-resolve-authoritative-files.py'
+  - '{project-root}/src/shared/scripts/skf-resolve-authoritative-files.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 3: Extract
 
 ## STEP GOAL:
@@ -27,8 +47,6 @@ To extract all public exports, function signatures, type definitions, and co-imp
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Load Extraction Patterns
 
 Load `{extractionPatternsData}` completely. Identify the strategy for the current forge tier.
@@ -41,115 +59,15 @@ From the brief, apply scope and pattern filters:
 - `scope.include` — file globs to include
 - `scope.exclude` — file globs to exclude
 
-Build the filtered file list from the source tree resolved in step-01. Record the result: "**Filtered file count: {N} files in scope**" — this count is the input to the AST Extraction Protocol decision tree in the extraction patterns data file.
+Build the filtered file list from the source tree resolved in step 1. Record the result: "**Filtered file count: {N} files in scope**" — this count is the input to the AST Extraction Protocol decision tree in the extraction patterns data file.
 
 ### 2a. Discovered Authoritative Files Protocol
 
 **Skip this section entirely if `source_type: "docs-only"`** — there is no source tree to scan.
 
-Before resolving source access for extraction, scan the source tree for **authoritative AI documentation files** that the brief's scope filters excluded. Project authors increasingly add files specifically written to steer AI assistants (`llms.txt`, `AGENTS.md`, `.cursorrules`, etc.), and these files often contain the **canonical** install command, quick-start, or architecture summary — information that nowhere else in the source tree provides. A brief authored from a scan of `src/**` will frequently exclude these files without the author realizing they exist.
-
-This protocol detects such files, prompts the user, and records the decision in the brief so future runs (re-create, update, audit) honor it.
-
-**Heuristic scan list (case-insensitive basename match, any directory depth):**
-
-- `llms.txt`, `llms-full.txt`
-- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `COPILOT.md`
-- `.cursorrules`, `.windsurfrules`, `.clinerules`
-
-**Procedure:**
-
-1. **Walk the source tree** resolved in step-01 (NOT the filtered file list from §2 — we want files the brief excluded too). Match file basenames against the heuristic list case-insensitively.
-
-2. **Diff against filtered list.** For each match, check whether the path is already present in §2's filtered file list:
-   - **Already in scope (matched by `scope.include`):** **remove the path from the filtered file list** and add it directly to `promoted_docs[]` with `{path, heuristic, size_bytes, line_count, content_hash}`. No prompt — the user or a prior amendment already said it belongs in scope, but authoritative docs must never reach §4 code extraction. This is both the "already promoted from a prior run" case and the "user manually added to scope.include" case.
-   - **Excluded by brief patterns:** this is a **candidate** for the prompt at step 5.
-
-3. **Check existing amendments.** Before prompting, consult `brief.scope.amendments[]` (see `src/skf-brief-skill/assets/skill-brief-schema.md` for the schema). If any amendment entry has `path == candidate.path`, the decision is already recorded:
-   - `action: "promoted"` → the file should already be in `scope.include` (amendments are write-through). No prompt. **Still populate `promoted_docs[]`** for this path — compute its content hash and add a `{path, heuristic, size_bytes, line_count, content_hash}` entry so step-05 §6 writes the `file_entries[]` row. This is the deterministic replay path for re-runs.
-   - `action: "skipped"` → user previously declined. No prompt. Do not add to `promoted_docs[]`. Move on.
-
-4. **Load preview.** For each unresolved candidate, read the first 20 lines of the file. Record the line count and file size in bytes.
-
-5. **Prompt.** Present each candidate to the user:
-
-   ```
-   **Discovered authoritative file excluded by brief scope**
-
-   Path: {relative_path_from_source_root}
-   Size: {line_count} lines, {bytes} bytes
-   Matched heuristic: {basename}
-   Excluded by pattern: {matching_exclude_pattern or "not matched by any scope.include"}
-
-   First 20 lines:
-   {inline preview}
-
-   This file is typically authored for AI assistants and may contain canonical usage information not present elsewhere in the source. How should extraction handle it?
-
-   [P] Promote — include in this extraction run AND amend brief for future runs
-   [S] Skip    — honor the brief exclusion AND record skip in amendments (no re-prompt)
-   [U] Update  — halt this run and return to skf-brief-skill to refine scope
-   ```
-
-6. **Headless mode (`{headless_mode}` is true):** auto-select `[S] Skip` for every candidate. Record amendment entries with `action: "skipped"` and `reason: "headless: no user to prompt"`. A non-interactive run must never silently promote files into scope — the decision requires a human.
-
-7. **Apply decision:**
-
-   - **[P] Promote:**
-     1. **Do NOT add the path to the filtered file list from §2.** Authoritative documentation files are not code — they must not go through the AST extraction pipeline in §4, which would silently produce no exports (ghost entries). Instead, add the path to a new in-context list `promoted_docs[]` with `{path, heuristic, size_bytes, line_count, content_hash}`. Compute the SHA-256 content hash of the file now.
-     2. Append to `brief.scope.include`: add the exact `candidate.path` as a literal glob (no wildcards — the amendment targets this specific file). This write ensures that a re-run of `skf-create-skill` against the amended brief sees the path in scope and skips re-prompting.
-     3. Append to `brief.scope.amendments[]` a new entry with `action: "promoted"`, `path: candidate.path`, `reason: {user-provided one-sentence reason or auto-generated "authoritative AI docs — matched heuristic {basename}"}`, `heuristic: {basename}`, `date: {today ISO}`, `workflow: "skf-create-skill"`.
-     4. **Write the amended brief back to disk immediately** at `{forge_data_folder}/{skill_name}/skill-brief.yaml`. Immediate write (not deferred to step-07) ensures a crashed run still leaves the amendment recorded. Preserve all other brief fields and formatting. **Use atomic write + backup:** before writing, copy the original brief to `{forge_data_folder}/{skill_name}/skill-brief.yaml.bak` (overwriting any prior `.bak` — the most recent pre-amendment snapshot is the useful one). Then pipe the amended YAML through the shared atomic writer so a crash mid-write cannot corrupt the brief:
-
-        ```bash
-        # 1. Backup
-        cp {forge_data_folder}/{skill_name}/skill-brief.yaml \
-           {forge_data_folder}/{skill_name}/skill-brief.yaml.bak
-
-        # 2. Atomic write (stdin → tmp → fsync → rename)
-        cat <<'AMENDED_YAML' | python3 {atomicWriteHelper} write \
-            --target {forge_data_folder}/{skill_name}/skill-brief.yaml
-        {amended brief YAML}
-        AMENDED_YAML
-        ```
-
-        The helper stages into `{brief}.skf-tmp`, fsyncs, then `os.replace()`s — readers never see a half-written brief.
-     5. Display: "**Promoted `{path}`** — tracked as documentation file, amendment recorded."
-
-   - **[S] Skip:**
-     1. Do NOT modify `scope.include` or `scope.exclude`.
-     2. Append to `brief.scope.amendments[]` a new entry with `action: "skipped"`, `path: candidate.path`, `reason: {user-provided reason or auto-generated "user declined promotion at create-skill §2a"}`, `heuristic: {basename}`, `date: {today ISO}`, `workflow: "skf-create-skill"`.
-     3. **Write the amended brief back to disk** so future runs do not re-prompt. Use the same backup-then-atomic-write pattern as the [P] Promote path (copy to `skill-brief.yaml.bak` first, then pipe through `skf-atomic-write.py write --target {brief_path}`).
-     4. Display: "**Skipped `{path}`** — decision recorded in amendments."
-
-   - **[U] Update:**
-     1. Halt the workflow immediately.
-     2. Display: "**Halting create-skill.** Re-run `skf-brief-skill` to refine the scope filters for `{skill_name}`, then re-run `skf-create-skill`. Decisions for previously prompted candidates were already persisted to the brief; the current candidate was not written."
-     3. Exit with status `halted-for-brief-refinement`.
-
-8. **Summary.** After all candidates are resolved (or none were found), display a one-line summary:
+Load `{authoritativeFilesProtocol}` and execute it. The full protocol (heuristic scan list, helper invocation, classification dispatch, prompt flow, P/S/U decision-apply, summary, provenance-map handoff, downstream consumption) lives there. This stub exists so the inline `### 2a` heading stays present in `extract.md`'s table of contents while keeping the body lean.
 
-   - `"Authoritative files scan: {N} candidates, {P} promoted, {S} skipped, {A} pre-decided from amendments."`
-   - If N = 0: `"Authoritative files scan: no candidates."`
-
-**Record for evidence report:** `authoritative_files_scan: {candidates: N, promoted: P, skipped: S, pre_decided: A, decisions: [{path, action, heuristic, reason}]}` — step-07 includes this in `evidence-report.md`.
-
-**How promoted docs reach the provenance map:**
-
-Promoted docs do NOT flow through §4 code extraction. Instead:
-
-1. §2a populates the in-context `promoted_docs[]` list with content hashes.
-2. **Step-05 §6** (provenance-map assembly) reads `promoted_docs[]` and emits one `file_entries[]` entry per promoted doc with `file_type: "doc"`, `extraction_method: "promoted-authoritative"`, `confidence: "T1-low"`, and the pre-computed `content_hash`.
-3. **Step-07 §2** does NOT copy doc files into the skill package (unlike scripts and assets). The source file remains at its original path; only the provenance map tracks it. Future audit and update workflows compare against this tracking entry via content hash — no file copy is required because the intent is drift detection on the *source*, not bundling documentation into the skill output.
-
-**Re-running `skf-create-skill`** reads the amended brief. Files with `action: "promoted"` amendments already appear in `scope.include`, but §2a still runs — it detects the file is in scope AND has an existing amendment, and takes the "pre-decided" silent path. The `promoted_docs[]` list is rebuilt on each run by scanning amendments with `action: "promoted"` (this is the deterministic replay path).
-
-**Downstream workflow consumption** (zero code changes required):
-
-- **`skf-update-skill`** reads `provenance-map.json`. Promoted docs appear as `file_entries[]` entries. Update-skill Category D (script/asset file changes) iterates `file_entries` and compares content hashes — this works identically for `file_type: "doc"` entries, giving drift detection for free.
-- **`skf-audit-skill`** (after the bounded re-index fix) scans files from `provenance-map.json`. The re-index builds its list from `entries[].source_file ∪ file_entries[].source_file`, so promoted doc paths are naturally included in the audit scan.
-
-The brief is the single source of truth for authored scope intent. The provenance map is the single source of truth for extracted state. `scope.amendments[]` is the bridge that records when those two intentionally diverged. `promoted_docs[]` is the in-memory handoff from §2a to step-05 §6; it is not persisted — the persisted form is the `file_entries[]` list in provenance-map.json.
+Briefly: scan the source tree for authoritative AI documentation files (`llms.txt`, `AGENTS.md`, `.cursorrules`, etc.) that the brief's scope filters may have excluded. The `{resolveAuthoritativeFilesHelper}` helper does the deterministic work (walk, scope diff, amendment reconcile, preview load, hashing); the LLM applies the resulting `unresolved[]` prompt loop. Promoted decisions are persisted to the brief immediately so re-runs replay deterministically.
 
 ### 2b. Resolve Source Access
 
@@ -167,7 +85,7 @@ This ensures source code is accessible regardless of which extraction path is ta
 
 If ALL of these conditions are true:
 - `tools.ccc` is true in forge-tier.yaml
-- `{ccc_discovery}` is empty (step-02b deferred because source was remote)
+- `{ccc_discovery}` is empty (step 2b deferred because source was remote)
 - `remote_clone_path` is set (source resolution succeeded for a remote URL)
 - Tier is Forge+ or Deep
 
@@ -204,7 +122,7 @@ Then run CCC indexing and discovery on the resolved clone (workspace or ephemera
 
 **CCC Discovery Integration (Forge+ and Deep with ccc only):**
 
-If `{ccc_discovery}` is in context and non-empty (populated by step-02b or deferred discovery above):
+If `{ccc_discovery}` is in context and non-empty (populated by step 2b or deferred discovery above):
 - Sort the filtered file list by CCC relevance score: files appearing in `{ccc_discovery}` results move to the front of the extraction queue, sorted by their relevance score descending
 - Files NOT in CCC results remain in the queue after ranked files — they are not excluded, only deprioritized
 - Display: "**CCC discovery: {N} files pre-ranked by semantic relevance** — extraction will prioritize these first."
@@ -227,9 +145,9 @@ Load and execute `{componentExtractionStepFile}` completely. When that step comp
 
 **If `source_type: "docs-only"` in the brief data:**
 
-"**Docs-only mode:** No source code to extract. Documentation content will be fetched from `doc_urls` in step-03c."
+"**Docs-only mode:** No source code to extract. Documentation content will be fetched from `doc_urls` in step 3c."
 
-Build an empty extraction inventory with zero exports. **Set `top_exports = []` explicitly in context** — downstream steps (notably §3b targeted searches and step-04 enrichment fan-out) must see an empty list rather than an undefined/missing field so they can short-circuit deterministically. Set `extraction_mode: "docs-only"` in context. Auto-proceed through Gate 2 (section 6) — display the empty inventory and note that T3 content will be produced by the doc-fetcher step.
+Build an empty extraction inventory with zero exports. **Set `top_exports = []` explicitly in context** — downstream steps (notably §3b targeted searches and step 4 enrichment fan-out) must see an empty list rather than an undefined/missing field so they can short-circuit deterministically. Set `extraction_mode: "docs-only"` in context. Auto-proceed through Gate 2 (section 6) — display the empty inventory and note that T3 content will be produced by the doc-fetcher step.
 
 **If `source_type: "source"` (default):** Continue with extraction below.
 
@@ -250,7 +168,7 @@ Source resolution, version reconciliation, and CCC discovery were completed in s
 
 **Forge/Forge+/Deep Tier (AST available):**
 
-⚠️ **CRITICAL:** Before executing AST extraction, load the **AST Extraction Protocol** section from `{extractionPatternsData}`. Follow the decision tree based on the file count from step-01's file tree. This determines whether to use the MCP tool, scoped YAML rules, or CLI streaming. Never use `ast-grep --json` (without `=stream`) — it loads the entire result set into memory and will fail on large codebases. Always use the explicit `run` subcommand with streaming: `ast-grep run -p '{pattern}' --json=stream`.
+⚠️ **CRITICAL:** Before executing AST extraction, load the **AST Extraction Protocol** section from `{extractionPatternsData}`. Follow the decision tree based on the file count from step 1's file tree. This determines whether to use the MCP tool, scoped YAML rules, or CLI streaming. Never use `ast-grep --json` (without `=stream`) — it loads the entire result set into memory and will fail on large codebases. Always use the explicit `run` subcommand with streaming: `ast-grep run -p '{pattern}' --json=stream`.
 
 1. Detect language from brief or file extensions
 2. Follow the AST Extraction Protocol decision tree from `{extractionPatternsData}`:
@@ -295,15 +213,29 @@ Use the entry point as the authoritative source for `metadata.json`'s `exports[]
 
 **Default resolution:** If `scripts_intent` is absent from the brief, treat as `"detect"` (auto-detection). If `assets_intent` is absent, treat as `"detect"`. Only an explicit `"none"` value disables detection.
 
-**If `scripts_intent` is `"none"` AND `assets_intent` is `"none"`:** Skip this section entirely. **If only one is `"none"`:** Skip that category only, proceed with the other.
+Invoke the deterministic detector — it implements the heuristics from `{extractionPatternsTracingData}` (directory conventions, shebang signals, `package.json` `bin` entry-points, asset filename patterns, binary-extension exclusion, generated-path pruning) so this stage doesn't re-derive them per-run:
+
+```bash
+uv run {detectScriptsAssetsHelper} detect <source-root> \
+    --scripts-intent <scripts_intent> \
+    --assets-intent <assets_intent> \
+    [--scope-include "<glob1>,<glob2>,..."] \
+    [--max-lines 500]
+```
 
-After export extraction, scan the source for scripts and assets using the detection patterns in `{extractionPatternsTracingData}`:
+The helper emits JSON on stdout:
 
-1. Scan source tree for directories/files matching detection heuristics (scripts/, bin/, tools/, cli/ for scripts; assets/, templates/, schemas/, configs/, examples/ for assets)
-2. For each candidate: verify existence, check size (flag >500 lines), exclude binaries, compute SHA-256 hash
-3. Extract purpose from header comments, shebang, README references, or schema fields. Record: file_path, purpose, source_path, language/type, content_hash, confidence (T1-low)
+```json
+{
+  "scripts_inventory": [ {name, source_file, purpose, language, content_hash, confidence, lines, size_flag}, ... ],
+  "assets_inventory":  [ {name, source_file, purpose, type,     content_hash, confidence, lines, size_flag}, ... ],
+  "scripts_skipped": <bool>,
+  "assets_skipped":  <bool>,
+  "stats": { "scripts_found": N, "assets_found": M, "files_scanned": K }
+}
+```
 
-Add results to `scripts_inventory[]` and `assets_inventory[]` alongside the existing export inventory.
+Merge `scripts_inventory[]` and `assets_inventory[]` into the running extraction inventory verbatim — entries already carry `confidence: "T1-low"` and `content_hash` (sha256:...). Records with `size_flag: "oversized"` should be surfaced in §6 (Extraction Summary) so the user can confirm before bundling. If both `scripts_skipped` and `assets_skipped` are true, the helper performs no walk and §4c is effectively a no-op.
 
 ### 5. Build Extraction Inventory
 
@@ -323,7 +255,7 @@ Compile all extracted data into a structured inventory:
 - Total exports found
 - Exports by type (functions, types/interfaces, constants)
 - Confidence breakdown (T1 count, T1-low count)
-- `top_exports[]` — sorted list of the top 10-20 public API function names by prominence (import frequency or documentation position). This named field is consumed by step-03b for targeted temporal fetching and cache fingerprinting.
+- `top_exports[]` — sorted list of the top 10-20 public API function names by prominence (import frequency or documentation position). This named field is consumed by step 3b for targeted temporal fetching and cache fingerprinting.
 
 **Script/asset counts (when detected):**
 - `scripts_found`: count of scripts detected
@@ -335,7 +267,7 @@ Compile all extracted data into a structured inventory:
 
 ### 6. Present Extraction Summary (Gate 2)
 
-**Docs-only note:** If `docs_only_mode` is active (`extraction_mode: "docs-only"`), display a brief note explaining that T3 content will be added by the doc-fetcher step (step-03c), then auto-proceed past this gate. Example: "Docs-only mode: extraction inventory is empty. Documentation content will be fetched from `doc_urls` in step-03c. Auto-proceeding."
+**Docs-only note:** If `docs_only_mode` is active (`extraction_mode: "docs-only"`), display a brief note explaining that T3 content will be added by the doc-fetcher step (step 3c), then auto-proceed past this gate. Example: "Docs-only mode: extraction inventory is empty. Documentation content will be fetched from `doc_urls` in step 3c. Auto-proceeding."
 
 Display the extraction findings for user confirmation:
 

package/src/skf-create-skill/references/extraction-patterns.md

@@ -30,7 +30,7 @@ Structural extraction via ast-grep — verified exports with line-level citation
 
 > **Note:** `ast_bridge.*`, `qmd_bridge.*`, and `ccc_bridge.*` references below are **conceptual interfaces**, not callable functions. Resolve them as follows:
 > - `ast_bridge.*` → ast-grep MCP tools (`mcp__ast-grep__find_code`, `mcp__ast-grep__find_code_by_rule`) or `ast-grep` CLI
-> - `qmd_bridge.*` → QMD MCP `query` tool (`mcp__plugin_qmd-plugin_qmd__query`) taking `searches=[{type:'lex'|'vec'|'hyde', query, intent}]`, or `qmd` CLI (`qmd search` / `qmd vector-search`). The legacy `vector_search` MCP tool has been removed; if a client surfaces a tool-not-found error, degrade gracefully per the QMD step-04 tool-probe note — do not retry the stale name.
+> - `qmd_bridge.*` → QMD MCP `query` tool (`mcp__plugin_qmd-plugin_qmd__query`) taking `searches=[{type:'lex'|'vec'|'hyde', query, intent}]`, or `qmd` CLI (`qmd search` / `qmd vector-search`). The legacy `vector_search` MCP tool has been removed; if a client surfaces a tool-not-found error, degrade gracefully per the QMD step 4 tool-probe note — do not retry the stale name.
 > - `ccc_bridge.*` → `/ccc` skill (Claude Code), ccc MCP server (Cursor), or `ccc` CLI
 > - `gh_bridge.*` → `gh api` commands or direct file I/O for local sources
 >
@@ -64,10 +64,10 @@ Identical extraction to Forge tier. CCC adds an upstream semantic discovery step
 
 ### When CCC Pre-Discovery Applies
 
-CCC pre-discovery runs in step-02b-ccc-discover (before this extraction step) when ALL of the following are true:
+CCC pre-discovery runs in ccc-discover (before this extraction step) when ALL of the following are true:
 - Tier is Forge+ or Deep
 - `tools.ccc: true` in forge-tier.yaml
-- `ccc_index.status` is `"fresh"`, `"stale"`, `"created"`, or `"none"`/`"failed"` (step-02b attempts lazy indexing for the latter two)
+- `ccc_index.status` is `"fresh"`, `"stale"`, `"created"`, or `"none"`/`"failed"` (step 2b attempts lazy indexing for the latter two)
 
 The discovery step stores `{ccc_discovery: [{file, score, snippet}]}` in context. This extraction step consumes those results to pre-rank the file list.
 
@@ -96,16 +96,16 @@ CCC pre-discovery failures (ccc unavailable, command error, empty results) alway
 
 ## Deep Tier (AST + QMD)
 
-Same extraction as Forge tier. Deep tier adds enrichment in step-04, not extraction.
+Same extraction as Forge tier. Deep tier adds enrichment in step 4, not extraction.
 
 ### Strategy
 - Identical to Forge tier extraction
-- QMD enrichment happens in the next step (step-04-enrich)
+- QMD enrichment happens in the next step (enrich)
 - Extraction results carry forward unchanged
 
 ### Confidence
 - Extraction: same as Forge (T1)
-- Enrichment annotations added in step-04: T2
+- Enrichment annotations added in step 4: T2
 
 ---
 
@@ -113,7 +113,7 @@ Same extraction as Forge tier. Deep tier adds enrichment in step-04, not extract
 
 When AST tools are available (Forge/Deep tier), follow this deterministic protocol to prevent output overflow on large codebases.
 
-**"Files in scope"** = files remaining after applying `include_patterns` and `exclude_patterns` from the brief, filtered by the target language extension. This is NOT the total repository file count from step-01's tree listing. Use the filtered count from step-03 section 2 as the decision tree input.
+**"Files in scope"** = files remaining after applying `include_patterns` and `exclude_patterns` from the brief, filtered by the target language extension. This is NOT the total repository file count from step 1's tree listing. Use the filtered count from step 3 section 2 as the decision tree input.
 
 ### Decision Tree
 
@@ -320,7 +320,7 @@ constraints:
 
 ### Component Library YAML Rule Recipes
 
-These patterns are used by `step-03d-component-extraction.md` when `scope.type: "component-library"`. They prioritize Props interfaces and PascalCase component exports.
+These patterns are used by `component-extraction.md` when `scope.type: "component-library"`. They prioritize Props interfaces and PascalCase component exports.
 
 **React/TypeScript — Props interfaces (primary API contracts):**
 

package/src/skf-create-skill/{steps-c/step-07-generate-artifacts.md → references/generate-artifacts.md}

@@ -1,5 +1,5 @@
 ---
-nextStepFile: './step-08-report.md'
+nextStepFile: 'report.md'
 forgeTierConfig: '{sidecar_path}/forge-tier.yaml'
 # Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
@@ -10,6 +10,8 @@ atomicWriteProbeOrder:
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 7: Generate Artifacts
 
 ## STEP GOAL:
@@ -24,8 +26,6 @@ To write all compiled content to disk — 4 deliverable files to `{skill_package
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Create Directory Structure
 
 Resolve `{version}` from the skill brief's `version` field. Create the following directories:
@@ -71,7 +71,7 @@ Write these 4 files from the compiled content:
 - One file per detected asset, copied from source with content preserved
 - Only created when `assets_inventory` is non-empty
 
-**Note on `file_type: "doc"` entries** (promoted authoritative docs from step-03 §2a):
+**Note on `file_type: "doc"` entries** (promoted authoritative docs from step 3 §2a):
 
 Promoted docs are tracked in `file_entries[]` with `file_type: "doc"` for drift detection but are **NOT** copied into the skill package. The source file remains at its original location outside `{skill_package}`. Step-07 must skip any `file_entries[]` row where `file_type == "doc"` when iterating for file copy — these entries exist only for provenance tracking, not bundling. Step-07 verification (§5) also does not check for doc files in the skill package.
 
@@ -87,7 +87,7 @@ Write these 3 files from the compiled content:
 
 **File 7:** `{forge_version}/extraction-rules.yaml`
 - Language and ast-grep schema used for this extraction (for reproducibility)
-- Note: This file is generated here from extraction data collected during steps 3-4, not assembled in step-05
+- Note: This file is generated here from extraction data collected during steps 3-4, not assembled in step 5
 
 ### 4. Create Active Symlink (atomic flip)
 
@@ -108,16 +108,16 @@ The helper returns non-zero (exit 2) if `{skill_group}/active` already exists as
 After all files are written, verify:
 - All 4 deliverable artifact types exist (SKILL.md, context-snippet.md, metadata.json, **and** either at least one file in `references/` **or** `references/` is empty AND Tier-2 content is inline in SKILL.md — see "Empty `references/` exception" below), all 3 workspace artifacts exist (provenance-map.json, evidence-report.md, extraction-rules.yaml), plus scripts/ and assets/ files when inventories are non-empty
 - The `active` symlink at `{skill_group}/active` resolves to `{version}`
-- Store `ref_count` = count of files written to `references/` for use in step-08 report
+- Store `ref_count` = count of files written to `references/` for use in step 8 report
 - List each file with its path and size
 
-**Empty `references/` exception (Tier-2 inline):** `ref_count == 0` is a valid completion state when step-06 kept Tier-2 content inline in SKILL.md — e.g., the body was already under the size limit, or `skill-check` was unavailable and the manual fallback (step-06 §3) skipped the split. In that case, append a single line to `{forge_version}/evidence-report.md` recording the inline state so downstream tooling and audits can distinguish "inline by design" from "split-body skipped due to error":
+**Empty `references/` exception (Tier-2 inline):** `ref_count == 0` is a valid completion state when step 6 kept Tier-2 content inline in SKILL.md — e.g., the body was already under the size limit, or `skill-check` was unavailable and the manual fallback (step 6 §3) skipped the split. In that case, append a single line to `{forge_version}/evidence-report.md` recording the inline state so downstream tooling and audits can distinguish "inline by design" from "split-body skipped due to error":
 
 ```
-ref_count: 0  # Tier-2 kept inline in SKILL.md (no split performed in step-06)
+ref_count: 0  # Tier-2 kept inline in SKILL.md (no split performed in step 6)
 ```
 
-When `ref_count > 0` is expected (because step-06 ran a split) but no files were written, halt with: "Split-body produced zero reference files. Investigate step-06 output before retrying — empty `references/` after a split is never a valid state."
+When `ref_count > 0` is expected (because step 6 ran a split) but no files were written, halt with: "Split-body produced zero reference files. Investigate step 6 output before retrying — empty `references/` after a split is never a valid state."
 
 **If any write failed:**
 Halt with: "Artifact generation failed: could not write `{file_path}`. Check permissions and disk space."
@@ -159,7 +159,7 @@ qmd embed --collection {name}-extraction  # generates vector embeddings for sema
 
 **Registry update:**
 
-Read `{forgeTierConfig}` and update the `qmd_collections` array **under an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock`** (see step-03b §4 for the full pattern — acquire lock → read → modify → atomic write via `skf-atomic-write.py write` → release). If `flock` is unavailable, fall back to read-CAS-by-mtime.
+Read `{forgeTierConfig}` and update the `qmd_collections` array **under an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock`** (see step 3b §4 for the full pattern — acquire lock → read → modify → atomic write via `skf-atomic-write.py write` → release). If `flock` is unavailable, fall back to read-CAS-by-mtime.
 
 If an entry with `name: "{name}-extraction"` already exists, replace it. Otherwise, append:
 
@@ -187,7 +187,7 @@ Ensure the source path used for extraction is indexed by ccc and registered in t
 
 **Index verification:**
 
-Dispatch to ccc CLI (`ccc index {source_root}`) or ccc MCP tool — `ccc_bridge.ensure_index` is a conceptual interface, not a callable function. This is a no-op if the source was already indexed during setup or step-02b.
+Dispatch to ccc CLI (`ccc index {source_root}`) or ccc MCP tool — `ccc_bridge.ensure_index` is a conceptual interface, not a callable function. This is a no-op if the source was already indexed during setup or step 2b.
 
 **Registry update:**
 

package/src/skf-create-skill/{steps-c/step-09-health-check.md → references/health-check.md}

@@ -5,6 +5,8 @@
 nextStepFile: 'shared/health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 9: Workflow Health Check
 
 ## STEP GOAL:
@@ -13,9 +15,9 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 
 ## Rules
 
-- No user-facing reports, file writes, or result contracts in this step — those belong in step-08
+- No user-facing reports, file writes, or result contracts in this step — those belong in step 8
 - Delegate directly to `{nextStepFile}` with no additional commentary
-- In batch mode, this step is only reached after the final brief — step-08 loops back to step-01-load-brief for remaining briefs and skips chaining here
+- In batch mode, this step is only reached after the final brief — step 8 loops back to load-brief for remaining briefs and skips chaining here
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`
 
 ## MANDATORY SEQUENCE

package/src/skf-create-skill/{steps-c/step-01-load-brief.md → references/load-brief.md}

@@ -1,9 +1,19 @@
 ---
-nextStepFile: './step-02-ecosystem-check.md'
+nextStepFile: 'ecosystem-check.md'
 forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 preferencesFile: '{sidecar_path}/preferences.yaml'
+# Resolve `{validateBriefSchemaHelper}` to the first existing path; HALT if
+# neither candidate exists. §3 relies on the helper for deterministic
+# schema-conformance checks (required fields, regex patterns, enum
+# membership, docs-only conditional rules) so this stage does not re-run
+# those checks in prose.
+validateBriefSchemaProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-schema.py'
+  - '{project-root}/src/shared/scripts/skf-validate-brief-schema.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 1: Load Brief
 
 ## STEP GOAL:
@@ -17,8 +27,6 @@ To load and validate the skill-brief.yaml compilation config, resolve the source
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Load Forge Tier
 
 Load `{forgeTierFile}` completely.
@@ -30,14 +38,14 @@ Halt with: "Forge halted: No forge configuration found. Run [SF] Setup Forge fir
 Extract and report:
 - `tier`: Quick, Forge, Forge+, or Deep
 - `tools`: which tools are available (gh, ast-grep, ccc, qmd)
-- `ccc_index`: ccc index state (status, indexed_path, last_indexed) — needed by step-02b
+- `ccc_index`: ccc index state (status, indexed_path, last_indexed) — needed by step 2b
 
 **Apply tier override:** Read `{preferencesFile}`. If `tier_override` is set and is one of the exact valid tier values (`Quick`, `Forge`, `Forge+`, `Deep`), use it instead of the detected tier. **If `tier_override` is set but is NOT one of those four values:** log a warning — "Unknown tier_override `{value}` in preferences.yaml; falling back to detected tier `{detected_tier}`. Valid values: Quick, Forge, Forge+, Deep." — and use the detected tier. Never silently apply an unknown override value, and never map it heuristically to a tier.
 
 **Record the decision:** append an entry to the in-context `headless_decisions[]` buffer (initialize to `[]` at the start of this step if absent) whenever a non-interactive choice is made automatically — both the valid-override path AND the rejected-override path:
 
-- Valid override applied: `{step: "step-01-load-brief", gate: "tier-override", decision: "apply", value: "{tier_override}", rationale: "explicit preferences.yaml tier_override", timestamp: {ISO}}`
-- Invalid override rejected: `{step: "step-01-load-brief", gate: "tier-override", decision: "reject-invalid", value: "{tier_override}", fallback: "{detected_tier}", rationale: "tier_override not in {Quick,Forge,Forge+,Deep}", timestamp: {ISO}}`
+- Valid override applied: `{step: "load-brief", gate: "tier-override", decision: "apply", value: "{tier_override}", rationale: "explicit preferences.yaml tier_override", timestamp: {ISO}}`
+- Invalid override rejected: `{step: "load-brief", gate: "tier-override", decision: "reject-invalid", value: "{tier_override}", fallback: "{detected_tier}", rationale: "tier_override not in {Quick,Forge,Forge+,Deep}", timestamp: {ISO}}`
 
 Step-05 §7 reads `headless_decisions[]` and emits an "Auto-Decisions" section into `evidence-report.md` so reviewers can audit every silent choice the workflow made.
 
@@ -53,7 +61,7 @@ Step-05 §7 reads `headless_decisions[]` and emits an "Auto-Decisions" section i
   - If `batch_active: true`: validate the checkpoint before trusting it. Both conditions below MUST hold:
     1. `0 <= current_index < len(brief_list)` — the index points inside the recorded list.
     2. `os.path.exists(brief_list[current_index])` — the brief file is still on disk.
-    If both hold, load the brief at `brief_list[current_index]` (resuming a batch loop from step-08). If **either** check fails, the checkpoint is stale (briefs renamed, moved, or deleted between runs; index off the end after a partial failure). Log a warning — "Stale batch checkpoint — current_index={i}, brief_list length={n}, brief_exists={bool}. Resetting and re-discovering." — then set `batch_active: false` in `batch-state.yaml` and fall through to the no-checkpoint branch below.
+    If both hold, load the brief at `brief_list[current_index]` (resuming a batch loop from step 8). If **either** check fails, the checkpoint is stale (briefs renamed, moved, or deleted between runs; index off the end after a partial failure). Log a warning — "Stale batch checkpoint — current_index={i}, brief_list length={n}, brief_exists={bool}. Resetting and re-discovering." — then set `batch_active: false` in `batch-state.yaml` and fall through to the no-checkpoint branch below.
   - If no checkpoint exists or `batch_active` is false: search specified directory for all `skill-brief.yaml` files, list discovered briefs with skill names, store list for batch loop processing, and load the FIRST brief
 
 **If no brief found:**
@@ -61,35 +69,35 @@ Halt with: "No skill brief found. Run [BS] Brief Skill to create one, or use [QS
 
 ### 3. Validate Brief Structure
 
-Check that the loaded skill-brief.yaml contains required fields:
+Run the deterministic schema validator — it checks required fields, regex patterns (`name`, `version`), enum membership (`source_type`, `source_authority`, `forge_tier`, `scope.type`), type correctness, the docs-only conditional rule (`doc_urls` ≥ 1 when `source_type == "docs-only"`), and the version-non-empty-or-whitespace rule:
+
+```bash
+uv run {validateBriefSchemaHelper} <path-to-skill-brief.yaml>
+```
+
+The helper emits:
 
-**Required fields:**
-- `name` — skill identifier (kebab-case)
-- `version` — source version to compile against
-- `source_repo` — GitHub owner/repo or local path (**optional when `source_type: "docs-only"`**)
-- `language` — primary source language
-- `scope` — what to extract. Accepts either a string (simple scope description, e.g., "all public exports") or an object with sub-fields: `type` (e.g., `"component-library"`), `include`, `exclude`, `notes`, and optionally `demo_patterns`, `registry_path`, `ui_variants` for component libraries
+```json
+{
+  "valid": <bool>,
+  "errors":   [{"field": "...", "message": "Brief validation failed: ..."}, ...],
+  "warnings": [{"field": "...", "message": "..."}, ...],
+  "halt_reason": "brief-missing" | "brief-malformed" | "brief-invalid" | null,
+  "brief": { ...parsed YAML when loadable... }
+}
+```
 
-**Optional fields:**
-- `source_type` — `"source"` (default) or `"docs-only"` (external documentation only)
-- `doc_urls` — array of `{url, label}` documentation URLs (required when `source_type: "docs-only"`)
-- `source_branch` — branch to use (default: main/master)
-- `source_authority` — official/community/internal (default: community; forced to `community` for docs-only)
-- `target_version` — specific version to compile against (triggers **explicit** tag resolution for remote repos; see source-resolution-protocols.md). When absent, the workflow falls back to **implicit** tag resolution from `brief.version` for remote sources — see below.
-- `include_patterns` — file glob patterns to include
-- `exclude_patterns` — file glob patterns to exclude
-- `description` — human description of the skill
-- `scripts_intent` — `"none"` to skip scripts detection, omit for default auto-detection
-- `assets_intent` — `"none"` to skip assets detection, omit for default auto-detection
+**If `valid` is false:** HALT and display the first error's `message` field verbatim — the helper already formats messages in the "Brief validation failed: ..." form the user expects. For halt-reasons:
 
-**Docs-only validation:** When `source_type: "docs-only"`, `source_repo` is not required but `doc_urls` must have at least one entry. `source_authority` is forced to `community`.
+- `brief-missing` — the brief path doesn't exist. Display the helper's message (it includes the `Run [BS] Brief Skill` redirect).
+- `brief-malformed` — the YAML failed to parse. Display the helper's message.
+- `brief-invalid` — schema or conditional-rule violation. Display the first `errors[].message`. Multiple errors may appear; the user typically fixes one source and re-runs.
 
-**If required fields missing:**
-Halt with specific error: "Brief validation failed: missing required field `{field}`. Update your skill-brief.yaml and re-run."
+**If `valid` is true:** continue with `brief` (the parsed object) for downstream sections. Surface any `warnings[]` to the user but do not halt.
 
-**Name format check (run after required-field check, before any path creation):** validate `brief.name` against the regex `^[a-z0-9][a-z0-9-]{0,63}$` — 1-64 characters, lowercase alphanumeric plus hyphens, must start with a letter or digit, no leading hyphen, no uppercase, no underscores, no slashes. This matches the agentskills.io skill-name rule and the directory-name constraint that `skill-check`'s `frontmatter.name_matches_directory` rule will later enforce. If validation fails, halt BEFORE any directory is created or any path is resolved: "Brief validation failed: `name` field `{value}` does not match required pattern `^[a-z0-9][a-z0-9-]{0,63}$`. Skill names must be 1-64 chars, lowercase alphanumeric plus hyphens, no leading hyphen, no underscores, no slashes. Update your skill-brief.yaml and re-run."
+**Field reference (for human readers):**
 
-**Version non-empty check:** reject `brief.version` if absent, empty, or whitespace-only (`version.strip() == ""`). Halt: "Brief validation failed: `version` field is required and must be non-empty. Update your skill-brief.yaml and re-run." This guards downstream directory resolution — an empty version would later create paths like `{skills_output_folder}/{name}//` with a stray double-slash, which is a nightmare to clean up.
+The complete contract — required fields, optional fields, types, and rules — lives in `src/shared/scripts/schemas/skill-brief.v1.json` and the prose mirror at `src/skf-brief-skill/assets/skill-brief-schema.md`. Read those if you need to explain a specific field; do NOT restate the rules here.
 
 ### 4. Resolve Source Code Location
 
@@ -98,8 +106,8 @@ Halt with specific error: "Brief validation failed: missing required field `{fie
 **If source_repo is a GitHub URL or owner/repo format:**
 - Verify repository exists via `gh_bridge.list_tree(owner, repo, branch)` — **Tool resolution:** `gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1` or direct file listing if local; see `knowledge/tool-resolution.md`
 - If branch not specified, detect default branch
-- Store resolved: owner, repo, branch, file tree — note: `source_root` for remote repos is initially set to the remote URL (for detection and API access purposes) and then updated to the local workspace/clone path during step-03 source resolution
-- **Version-to-tag pinning intent:** If `brief.target_version` is absent but `brief.version` is present, record the intent to apply **implicit tag resolution** from `brief.version` when step-03 resolves the source. Do not resolve the tag here — tag resolution runs in step-03 alongside the clone. This step only notes the pinning intent so step-03 knows to attempt it. See `references/source-resolution-protocols.md` → "Implicit Tag Resolution".
+- Store resolved: owner, repo, branch, file tree — note: `source_root` for remote repos is initially set to the remote URL (for detection and API access purposes) and then updated to the local workspace/clone path during step 3 source resolution
+- **Version-to-tag pinning intent:** If `brief.target_version` is absent but `brief.version` is present, record the intent to apply **implicit tag resolution** from `brief.version` when step 3 resolves the source. Do not resolve the tag here — tag resolution runs in step 3 alongside the clone. This step only notes the pinning intent so step 3 knows to attempt it. See `references/source-resolution-protocols.md` → "Implicit Tag Resolution".
 
 **If source_repo is a local path:**
 - Verify path exists and contains source files

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

@@ -1,5 +1,5 @@
 ---
-nextStepFile: './step-09-health-check.md'
+nextStepFile: 'health-check.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 8: Report
 
 ## STEP GOAL:
@@ -22,8 +24,6 @@ To display the final compilation summary — skill name, version, source, export
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Display Forge Completion Banner
 
 "**Skill forged: {name} v{version} — {export_count} functions, {primary_confidence} confidence.**"
@@ -107,9 +107,9 @@ completed: [{list of completed skill names}]
 last_updated: {ISO timestamp}
 ```
 
-**Before writing:** validate the same two invariants that step-01 re-checks on resume — `0 <= current_index < len(brief_list)` AND `os.path.exists(brief_list[current_index])`. If either fails (e.g., the next brief file was deleted mid-batch, or arithmetic pushed the index off the end), set `batch_active: false` and write `batch_halt_reason: "invalid checkpoint at write time — index or file missing"` instead of the active record. The next run will re-discover rather than resume a broken index.
+**Before writing:** validate the same two invariants that step 1 re-checks on resume — `0 <= current_index < len(brief_list)` AND `os.path.exists(brief_list[current_index])`. If either fails (e.g., the next brief file was deleted mid-batch, or arithmetic pushed the index off the end), set `batch_active: false` and write `batch_halt_reason: "invalid checkpoint at write time — index or file missing"` instead of the active record. The next run will re-discover rather than resume a broken index.
 
-Then load and execute `steps-c/step-01-load-brief.md` for the next brief. Step-01 detects an active batch via `batch-state.yaml` and loads the brief at `current_index` only after re-validating the same invariants (belt and braces — the checkpoint may have been edited between runs).
+Then load and execute `references/load-brief.md` for the next brief. Step-01 detects an active batch via `batch-state.yaml` and loads the brief at `current_index` only after re-validating the same invariants (belt and braces — the checkpoint may have been edited between runs).
 
 **If all batch briefs complete:**
 
@@ -135,11 +135,11 @@ End workflow. No further steps.
 
 ONLY WHEN the compilation report, warnings (if any), recommended next steps, and result contract have been handled will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the report reads as final.
 
-**If batch mode with remaining briefs:** Skip the health-check chain — load and execute `steps-c/step-01-load-brief.md` for the next brief instead. The health check runs only after the final brief in the batch.
+**If batch mode with remaining briefs:** Skip the health-check chain — load and execute `references/load-brief.md` for the next brief instead. The health check runs only after the final brief in the batch.
 
 ## CRITICAL STEP COMPLETION NOTE
 
-This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md` (unless batch mode loops back to step-01). After the health check completes, the create-skill workflow is fully done.
+This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md` (unless batch mode loops back to step 1). After the health check completes, the create-skill workflow is fully done.
 
-For batch mode: load and execute `steps-c/step-01-load-brief.md` for remaining briefs via sidecar checkpoint. Health check runs only after the last brief.
+For batch mode: load and execute `references/load-brief.md` for remaining briefs via sidecar checkpoint. Health check runs only after the last brief.