bmad-module-skill-forge 1.4.1 → 1.5.1

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

@@ -1,9 +1,11 @@
 ---
-nextStepFile: './step-06-validate.md'
+nextStepFile: 'validate.md'
 skillSectionsData: 'assets/skill-sections.md'
 assemblyRulesData: 'assets/compile-assembly-rules.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 5: Compile
 
 ## STEP GOAL:
@@ -14,14 +16,12 @@ To assemble the complete skill content from the extraction inventory and enrichm
 
 - Focus only on assembling content from extraction inventory + enrichment
 - Do not include any content without a provenance citation
-- Write all compiled artifacts to the staging directory `_bmad-output/{skill-name}/`. Do not write to `skills/` or `forge-data/` — step-07 promotes staged artifacts to their final versioned locations.
+- Write all compiled artifacts to the staging directory `_bmad-output/{skill-name}/`. Do not write to `skills/` or `forge-data/` — step 7 promotes staged artifacts to their final versioned locations.
 - Do not fabricate examples not found in source tests or docs
 - Seed `<!-- [MANUAL] -->` markers for future update-skill compatibility
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Load Data Files
 
 Load `{skillSectionsData}` and `{assemblyRulesData}` completely. These define the agentskills.io-compliant format and detailed assembly rules for all output artifacts.
@@ -37,7 +37,7 @@ Create `_bmad-output/{skill-name}/` (and `_bmad-output/{skill-name}/references/`
 - `provenance-map.json`
 - `evidence-report.md`
 
-This is the `<staging-skill-dir>` referenced by step-06 (`npx skill-check check`, `npx -y tessl skill review`). Step-07 reads from the in-context copies (resynced by step-06 after any `--fix` modifications) and writes to the final versioned layout.
+This is the `<staging-skill-dir>` referenced by step 6 (`npx skill-check check`, `npx -y tessl skill review`). Step-07 reads from the in-context copies (resynced by step 6 after any `--fix` modifications) and writes to the final versioned layout.
 
 ### 1b. Signature Fidelity Rule
 
@@ -70,7 +70,7 @@ Assemble each section in order using the assembly rules data file (`{assemblyRul
 
 Record the count of substitutions in context as `description_sanitizations: {count}` for the evidence report.
 
-**Rationale:** The LTS-stable guarantee is that no angle-bracket character reaches step-06 validation in the description field. The assembly rules in `{assemblyRulesData}` define this as a drafting rule; this step makes it an enforced pass so authors and reviewers don't have to remember it. If the rule is ever bypassed (e.g., by a downstream tool rewriting the description), step-06 §6 provides a recovery path — see `description-xml-tags-guarded-upstream` in `assets/tessl-dismissal-rules.md`.
+**Rationale:** The LTS-stable guarantee is that no angle-bracket character reaches step 6 validation in the description field. The assembly rules in `{assemblyRulesData}` define this as a drafting rule; this step makes it an enforced pass so authors and reviewers don't have to remember it. If the rule is ever bypassed (e.g., by a downstream tool rewriting the description), step 6 §6 provides a recovery path — see `description-xml-tags-guarded-upstream` in `assets/tessl-dismissal-rules.md`.
 
 ### 3. Build context-snippet.md Content
 
@@ -87,7 +87,7 @@ Vercel-aligned indexed format for CLAUDE.md managed section (~80-120 tokens):
 
 **Derivation rules:**
 
-- **version**: From source detection (reconciled in step-03), not brief default
+- **version**: From source detection (reconciled in step 3), not brief default
 - **api**: Top 10 exports from extraction inventory, append `()` to function names
 - **key-types**: Inline summary of most important enum/type values from Key Types section
 - **gotchas**: Derived from T2-future annotations (breaking changes), async requirements, version-specific behavior changes. If no gotchas available, omit the gotchas line.
@@ -102,7 +102,7 @@ Following the structure from the skill-sections data file:
 - Set `source_ref` from resolved source ref (tag name, branch, or `HEAD`; null if unavailable)
 - Set `stats` from extraction aggregate counts:
   - `exports_documented`: count of exports with documentation in the assembled SKILL.md
-  - `exports_public_api`: count of exports from public entry points (`__init__.py`, `index.ts`, `lib.rs`, or equivalent) — derive this from step-03's entry-point validation (section 4b), NOT from the provenance-map entry count (which may be incomplete if extraction patterns missed some export types)
+  - `exports_public_api`: count of exports from public entry points (`__init__.py`, `index.ts`, `lib.rs`, or equivalent) — derive this from step 3's entry-point validation (section 4b), NOT from the provenance-map entry count (which may be incomplete if extraction patterns missed some export types)
   - `exports_internal`: count of all other non-underscore-prefixed exports (internal modules, helpers, adapters)
   - `exports_total`: `exports_public_api` + `exports_internal`
   - `public_api_coverage`: `exports_documented / exports_public_api` (1.0 when all public API exports are documented; `null` if `exports_public_api` is 0)
@@ -131,7 +131,7 @@ Following the structure from the skill-sections data file:
   2. `mcp__plugin_qmd-plugin_qmd__status` → parse version if exposed in status output
   3. `"unknown"` (final fallback — add a warning to the evidence report)
   Note: QMD is a Bun/Node package (`@tobilu/qmd`). Install via `bun install -g @tobilu/qmd`.
-- Store `commit_short` = first 8 characters of `source_commit` (or `"unknown"` if unavailable) for use in step-08 report.
+- Store `commit_short` = first 8 characters of `source_commit` (or `"unknown"` if unavailable) for use in step 8 report.
 - If `scripts_inventory` is non-empty, populate `scripts[]` array and set `stats.scripts_count`. If `assets_inventory` is non-empty, populate `assets[]` array and set `stats.assets_count`. Omit these fields entirely when inventories are empty.
 
 ### 5. Build references/ Content
@@ -150,19 +150,19 @@ One entry per extracted export: export_name, export_type, params[] (typed string
 
 **File entries** — emit one `file_entries[]` row per tracked non-code file when any of these inventories are non-empty:
 
-- `scripts_inventory` → `file_type: "script"`, `extraction_method: "file-copy"`, stored in `{skill_package}/scripts/` by step-07
-- `assets_inventory` → `file_type: "asset"`, `extraction_method: "file-copy"`, stored in `{skill_package}/assets/` by step-07
-- `promoted_docs` (from step-03 §2a) → `file_type: "doc"`, `extraction_method: "promoted-authoritative"`, **NOT** copied into the skill package by step-07. The source file stays at its original path; only the provenance tracking entry is written. `content_hash` was pre-computed by §2a.
+- `scripts_inventory` → `file_type: "script"`, `extraction_method: "file-copy"`, stored in `{skill_package}/scripts/` by step 7
+- `assets_inventory` → `file_type: "asset"`, `extraction_method: "file-copy"`, stored in `{skill_package}/assets/` by step 7
+- `promoted_docs` (from step 3 §2a) → `file_type: "doc"`, `extraction_method: "promoted-authoritative"`, **NOT** copied into the skill package by step 7. The source file stays at its original path; only the provenance tracking entry is written. `content_hash` was pre-computed by §2a.
 
 Each `file_entries[]` row has the same shape regardless of `file_type`: `{file_name, file_type, source_file, content_hash, confidence, extraction_method}`. See `{skillSectionsData}` for full schema and the canonical list of `file_type` values.
 
 ### 7. Build evidence-report.md Content
 
-Compilation audit trail: generation date, forge tier, source info, tool versions, extraction summary (files/exports/confidence), warnings. For validation-specific fields (Schema, Body, Security, Content Quality, tessl, Metadata), insert the placeholder text `[PENDING — populated by step-06]`. Step-06 will replace these placeholders with actual results. See `{skillSectionsData}` for full template. Use the same `{skf_version}` value resolved in section 4 when populating the Tool Versions block.
+Compilation audit trail: generation date, forge tier, source info, tool versions, extraction summary (files/exports/confidence), warnings. For validation-specific fields (Schema, Body, Security, Content Quality, tessl, Metadata), insert the placeholder text `[PENDING — populated by step 6]`. Step-06 will replace these placeholders with actual results. See `{skillSectionsData}` for full template. Use the same `{skf_version}` value resolved in section 4 when populating the Tool Versions block.
 
-**Frontmatter — pinned fields (MANDATORY):** emit YAML frontmatter at the top of `evidence-report.md` with at minimum `skill_name`, `generated`, `forge_tier`, and `t2_future_count`. Compute `t2_future_count` as the count of forward-looking (T2-future) temporal annotations in the enrichment data produced by step-04 (`qmd query` + temporal classification). **Emit `t2_future_count: 0` when no T2-future annotations exist** — omission is indistinguishable from "no data" for downstream consumers and would silently flip the skf-test-skill §2b/§5b migration-section gate into Case 2/3 for a Case-1 skill. This frontmatter is the authoritative detection contract — `migration-section-rules.md` Case Rules parse it deterministically rather than grepping prose.
+**Frontmatter — pinned fields (MANDATORY):** emit YAML frontmatter at the top of `evidence-report.md` with at minimum `skill_name`, `generated`, `forge_tier`, and `t2_future_count`. Compute `t2_future_count` as the count of forward-looking (T2-future) temporal annotations in the enrichment data produced by step 4 (`qmd query` + temporal classification). **Emit `t2_future_count: 0` when no T2-future annotations exist** — omission is indistinguishable from "no data" for downstream consumers and would silently flip the skf-test-skill §2b/§5b migration-section gate into Case 2/3 for a Case-1 skill. This frontmatter is the authoritative detection contract — `migration-section-rules.md` Case Rules parse it deterministically rather than grepping prose.
 
-**Auto-Decisions section (headless buffer flush):** read the in-context `headless_decisions[]` list (populated by step-01 tier-override handling, step-02 ecosystem gate, and any future step that auto-resolves a gate under `{headless_mode}`). Emit an `## Auto-Decisions` section with one row per entry:
+**Auto-Decisions section (headless buffer flush):** read the in-context `headless_decisions[]` list (populated by step 1 tier-override handling, step 2 ecosystem gate, and any future step that auto-resolves a gate under `{headless_mode}`). Emit an `## Auto-Decisions` section with one row per entry:
 
 ```
 ## Auto-Decisions
@@ -188,5 +188,5 @@ After all content is assembled in context and written to the staging directory,
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN all 6 content artifacts (SKILL.md, context-snippet.md, metadata.json, references/, provenance-map.json, evidence-report.md) are assembled in context AND written to the staging directory `_bmad-output/{skill-name}/` will you proceed to load `{nextStepFile}` for spec validation. Note: extraction-rules.yaml is generated by step-07 from extraction data, not assembled here.
+ONLY WHEN all 6 content artifacts (SKILL.md, context-snippet.md, metadata.json, references/, provenance-map.json, evidence-report.md) are assembled in context AND written to the staging directory `_bmad-output/{skill-name}/` will you proceed to load `{nextStepFile}` for spec validation. Note: extraction-rules.yaml is generated by step 7 from extraction data, not assembled here.
 

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

@@ -1,13 +1,15 @@
 ---
-returnToStep: './step-03-extract.md'
+returnToStep: 'extract.md'
 extractionPatternsData: 'references/extraction-patterns.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 3d: Component Library Extraction
 
 ## STEP GOAL:
 
-When `scope.type: "component-library"`, perform specialized extraction that treats the component registry as the primary API surface and props interfaces as API contracts. This step replaces the standard AST extraction flow (step-03 sections 4-4c) and returns control to step-03 section 5 (Build Extraction Inventory).
+When `scope.type: "component-library"`, perform specialized extraction that treats the component registry as the primary API surface and props interfaces as API contracts. This step replaces the standard AST extraction flow (step 3 sections 4-4c) and returns control to step 3 section 5 (Build Extraction Inventory).
 
 ## Rules
 
@@ -17,15 +19,13 @@ When `scope.type: "component-library"`, perform specialized extraction that trea
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
-**Prerequisite — §2a already ran.** Step-03 executes `§2a Discovered Authoritative Files Protocol` before delegating to this file. Any promoted authoritative files (`llms.txt`, `AGENTS.md`, etc.) are tracked in the `promoted_docs[]` context list and will be written to `file_entries[]` with `file_type: "doc"` by step-05 §6 — they do NOT appear in the filtered file list that was passed into this step, so Phase 1 demo exclusion below only operates on code files. No special handling is required in this file for promoted docs. See step-03 §2a for the full flow.
+**Prerequisite — §2a already ran.** Step-03 executes `§2a Discovered Authoritative Files Protocol` before delegating to this file. Any promoted authoritative files (`llms.txt`, `AGENTS.md`, etc.) are tracked in the `promoted_docs[]` context list and will be written to `file_entries[]` with `file_type: "doc"` by step 5 §6 — they do NOT appear in the filtered file list that was passed into this step, so Phase 1 demo exclusion below only operates on code files. No special handling is required in this file for promoted docs. See step 3 §2a for the full flow.
 
 ### Phase 1: Demo/Example Exclusion
 
 Before extraction, identify and exclude demo/example files to avoid inflating export counts.
 
-**Note:** For remote sources, the file list from step-03 section 2 was built from the API tree. When scanning for demo directories, scan the local workspace/clone path (`remote_clone_path`) instead of the API-derived file list.
+**Note:** For remote sources, the file list from step 3 section 2 was built from the API tree. When scanning for demo directories, scan the local workspace/clone path (`remote_clone_path`) instead of the API-derived file list.
 
 **If `scope.demo_patterns` is specified in the brief:** Use those patterns directly.
 
@@ -42,7 +42,7 @@ Before extraction, identify and exclude demo/example files to avoid inflating ex
 
 Confirm exclusion? [Y/n] Or adjust patterns:"
 
-**GATE [default: Y]** — if `{headless_mode}` is true: auto-confirm the auto-detected exclusion patterns, log "headless: auto-confirm demo/example exclusion ({N} files, {M} directories)", and append `{step: "step-03d-component-extraction", gate: "demo-exclusion", decision: "Y", value: "{N} files / {M} dirs", rationale: "headless mode — auto-detected demo patterns accepted", timestamp: {ISO}}` to `headless_decisions[]` for evidence-report assembly in step-05 §7. Then proceed without waiting.
+**GATE [default: Y]** — if `{headless_mode}` is true: auto-confirm the auto-detected exclusion patterns, log "headless: auto-confirm demo/example exclusion ({N} files, {M} directories)", and append `{step: "component-extraction", gate: "demo-exclusion", decision: "Y", value: "{N} files / {M} dirs", rationale: "headless mode — auto-detected demo patterns accepted", timestamp: {ISO}}` to `headless_decisions[]` for evidence-report assembly in step 5 §7. Then proceed without waiting.
 
 Wait for user response (interactive only). Apply confirmed patterns to the exclude list. Record `demo_files_excluded: {count}` in context.
 
@@ -85,7 +85,7 @@ Sample entries:
 
 Is this the component registry? [Y/n] Or provide the correct path:"
 
-**GATE [default: Y]** — if `{headless_mode}` is true AND `score >= 7` (high-confidence candidate): auto-confirm the registry candidate, log "headless: auto-confirm registry candidate `{path}` (score {score}/9)", and append `{step: "step-03d-component-extraction", gate: "registry-confirm", decision: "Y", value: "{path} score={score}/9", rationale: "headless mode — high-confidence registry candidate auto-accepted", timestamp: {ISO}}` to `headless_decisions[]`. If `score < 7` in headless mode, auto-reject the candidate (treat as "no registry found"), log "headless: auto-reject low-confidence registry candidate (score {score}/9) — below auto-accept threshold 7", record the decision, and fall through to the "no registry found" branch below. Confidence threshold 7 matches the minimum score the heuristic considers "probable enough to risk" without human eyes.
+**GATE [default: Y]** — if `{headless_mode}` is true AND `score >= 7` (high-confidence candidate): auto-confirm the registry candidate, log "headless: auto-confirm registry candidate `{path}` (score {score}/9)", and append `{step: "component-extraction", gate: "registry-confirm", decision: "Y", value: "{path} score={score}/9", rationale: "headless mode — high-confidence registry candidate auto-accepted", timestamp: {ISO}}` to `headless_decisions[]`. If `score < 7` in headless mode, auto-reject the candidate (treat as "no registry found"), log "headless: auto-reject low-confidence registry candidate (score {score}/9) — below auto-accept threshold 7", record the decision, and fall through to the "no registry found" branch below. Confidence threshold 7 matches the minimum score the heuristic considers "probable enough to risk" without human eyes.
 
 Wait for user response (interactive only).
 
@@ -95,7 +95,7 @@ Wait for user response (interactive only).
 - **[P]** Provide the registry file path
 - **[S]** Skip registry — proceed with standard props-first extraction only"
 
-**GATE [default: S]** — if `{headless_mode}` is true: auto-select [S] Skip (props-first extraction without registry), log "headless: no registry detected, auto-skip to props-first extraction (no path was provided in brief.scope.registry_path)", and append `{step: "step-03d-component-extraction", gate: "provide-or-skip-registry", decision: "S", rationale: "headless mode — no human to provide registry path", timestamp: {ISO}}` to `headless_decisions[]`. The default is `[S]` rather than `[P]` because providing a path requires user input that headless cannot supply; skipping degrades gracefully to a smaller but valid extraction.
+**GATE [default: S]** — if `{headless_mode}` is true: auto-select [S] Skip (props-first extraction without registry), log "headless: no registry detected, auto-skip to props-first extraction (no path was provided in brief.scope.registry_path)", and append `{step: "component-extraction", gate: "provide-or-skip-registry", decision: "S", rationale: "headless mode — no human to provide registry path", timestamp: {ISO}}` to `headless_decisions[]`. The default is `[S]` rather than `[P]` because providing a path requires user input that headless cannot supply; skipping degrades gracefully to a smaller but valid extraction.
 
 Wait for user response (interactive only).
 
@@ -204,7 +204,7 @@ Display: "**Variant consolidation: {unique} unique components across {variant_co
 
 ### Phase 6: Build Component Extraction Results
 
-Compile all extracted data into the format expected by step-03 section 5:
+Compile all extracted data into the format expected by step 3 section 5:
 
 **Per-export entry (for Props interfaces — primary API):**
 
@@ -237,15 +237,15 @@ Compile all extracted data into the format expected by step-03 section 5:
 - `demo_files_excluded`: count from Phase 1
 - `design_variants`: map of variant name → component count (if variants exist)
 
-**Store `component_catalog[]` in context** — this is consumed by step-05 for the Component Catalog section.
+**Store `component_catalog[]` in context** — this is consumed by step 5 for the Component Catalog section.
 
 Display: "**Component extraction complete.** Returning to main extraction flow."
 
 ## RETURN PROTOCOL
 
-After Phase 6 completes, return control to step-03 section 5 (Build Extraction Inventory). The extraction results from this step are merged into the standard extraction inventory format. Step-03 continues with its normal Gate 2 summary and menu.
+After Phase 6 completes, return control to step 3 section 5 (Build Extraction Inventory). The extraction results from this step are merged into the standard extraction inventory format. Step-03 continues with its normal Gate 2 summary and menu.
 
-Do NOT load `{returnToStep}` — the calling step (step-03) will continue from where it delegated.
+Do NOT load `{returnToStep}` — the calling step (step 3) will continue from where it delegated.
 
 ---
 
@@ -259,8 +259,8 @@ Do NOT load `{returnToStep}` — the calling step (step-03) will continue from w
 - Components linked to Props via 3-level fallback chain
 - Variant consolidation produced deduplicated counts (if applicable)
 - All extracted items have provenance citations
-- Results compatible with step-03 section 5 inventory format
-- component_catalog stored in context for step-05
+- Results compatible with step 3 section 5 inventory format
+- component_catalog stored in context for step 5
 
 ### FAILURE:
 
@@ -270,6 +270,6 @@ Do NOT load `{returnToStep}` — the calling step (step-03) will continue from w
 - Documenting component function signatures instead of Props
 - Including hallucinated component data not in source
 - Variant deduplication based on filenames instead of registry IDs
-- Not returning control to step-03 after completion
+- Not returning control to step 3 after completion
 
 **Master Rule:** Zero hallucination — every extraction must trace to source code. The component registry is the source of truth for the API surface.

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

@@ -1,7 +1,9 @@
 ---
-nextStepFile: './sub/step-02b-ccc-discover.md'
+nextStepFile: 'sub/ccc-discover.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 2: Ecosystem Check
 
 ## STEP GOAL:
@@ -16,8 +18,6 @@ To search the agentskills.io ecosystem for an existing official skill matching t
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Check Ecosystem for Existing Skill
 
 **Note:** Ecosystem lookup requires the agentskills.io registry API, which is not yet available. The `skill-check` CLI validates local skills but does not query a remote registry.
@@ -70,7 +70,7 @@ Display: "**Ecosystem match found — Select an Option:** [P] Proceed with compi
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
-- **GATE [default: P]** — If `{headless_mode}` and match found: auto-proceed with [P] Proceed, log: "headless: ecosystem match found, auto-proceeding", AND append an entry to the in-context `headless_decisions[]` list: `{step: "step-02-ecosystem-check", gate: "ecosystem-match", decision: "P", rationale: "headless mode — match found, auto-proceed with user's own compilation", timestamp: {ISO}}`. Step-05 §7 (evidence-report assembly) reads `headless_decisions[]` and emits an "Auto-Decisions" section into evidence-report.md.
+- **GATE [default: P]** — If `{headless_mode}` and match found: auto-proceed with [P] Proceed, log: "headless: ecosystem match found, auto-proceeding", AND append an entry to the in-context `headless_decisions[]` list: `{step: "ecosystem-check", gate: "ecosystem-match", decision: "P", rationale: "headless mode — match found, auto-proceed with user's own compilation", timestamp: {ISO}}`. Step-05 §7 (evidence-report assembly) reads `headless_decisions[]` and emits an "Auto-Decisions" section into evidence-report.md.
 - This menu ONLY appears when an ecosystem match is found
 - If no match, timeout, or tool unavailable — auto-proceed with no menu
 

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

@@ -1,7 +1,9 @@
 ---
-nextStepFile: './step-05-compile.md'
+nextStepFile: 'compile.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 4: Enrich
 
 ## STEP GOAL:
@@ -17,8 +19,6 @@ To enrich the extraction inventory with temporal context from QMD knowledge sear
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Check Tier Eligibility
 
 **If tier is Quick, Forge, or Forge+:**

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):**
 
@@ -400,6 +400,8 @@ When using ast-grep for extraction, be aware of these documented limitations:
 
 7. **Python class patterns with bases/colon return zero (ast-grep 0.42.x):** The patterns `class $NAME($$$BASES)` and `class $NAME($$$BASES):` return zero matches on real Python sources with ast-grep 0.42.0, even on files containing dozens of subclassed public classes. `find_code_by_rule` also rejects the bare inline rule without `kind` as `Rule must specify a set of AST kinds to match. Try adding \`kind\` rule.` **Workaround:** Use the minimal `class $NAME` pattern with `kind: class_definition` (YAML) or `ast-grep run -p 'class $NAME' -l python --json=stream` (CLI), then post-filter names via the `^[^_]` regex. The `^[^_]` constraint enforces the "public" filter since ast-grep's base-match rule is what's broken, not the name-match rule. See the Python — public classes recipe above.
 
+8. **Rust `pub fn` any-pattern returns zero; bare `pub fn $NAME` over-captures (ast-grep 0.42.x):** The `rust-public-functions` recipe's `any:` of `pub fn $NAME($$$PARAMS) -> $RET` / `pub fn $NAME($$$PARAMS)` returns "No matches found" on real Rust sources with ast-grep 0.42.2, even on crates containing 200+ public functions. Dropping to the bare `pub fn $NAME` pattern matches, but over-captures restricted-visibility functions such as `pub(crate) fn` / `pub(super) fn`, which are **not** public API. **Workaround:** Prefer a visibility-constrained source grep — `rg '^\s*pub fn ' <src>` filtered to exclude lines beginning `pub(` — cross-checked against the AN-verified public surface, at T1-low confidence. Never silently accept zero results for Rust public functions, and never treat a bare `pub fn $NAME` match set as the public API without stripping `pub(...)`-restricted items. See the Rust — public functions recipe above.
+
 ### Component Library Demo/Example Auto-Exclusion
 
 When `scope.type: "component-library"`, auto-detect and propose demo/example exclusions before extraction begins. **User confirmation is required before applying** — some `examples/` directories contain API-level code.