bmad-module-skill-forge 2.0.0 → 2.0.1

package/src/skf-create-skill/assets/skill-sections.md

@@ -2,25 +2,9 @@
 
 ## agentskills.io Compliant Format
 
-### Frontmatter (Required — agentskills.io Compliance)
+### Frontmatter
 
-```yaml
----
-name: {skill-name}
-description: >
-  {Trigger-optimized description of what the skill does and when to use it.
-  Include specific keywords for agent discovery.
-  Mention what NOT to use it for if applicable.
-  1-1024 characters.}
----
-```
-
-**Frontmatter rules (agentskills.io specification):**
-
-- `name`: 1-64 characters, lowercase alphanumeric + hyphens only, must match parent directory name. Prefer gerund form (`processing-pdfs`, `analyzing-spreadsheets`) for clarity; noun phrases and action-oriented forms are acceptable alternatives.
-- `description`: 1-1024 characters, trigger-optimized for agent matching. MUST use third-person voice ("Processes..." not "I can..." or "You can...") AND include a trigger phrase ("Use when ...", "Triggers on ...", "Reach for this when ..."). When using "Use when ", follow with a gerund (`Use when building/processing/analyzing X…`) or noun-phrase clause — never a bare indicative verb, since `skill-check --fix` will prepend a literal "Use when " to descriptions missing the phrase. See `skf-brief-skill/assets/description-voice-examples.md`.
-- Only 6 fields permitted: `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`
-- `version` and `author` belong in metadata.json, NOT in frontmatter
+The authoritative frontmatter contract — permitted fields, the `name`/`description` rules, the trigger-phrase/voice requirements, and the no-angle-brackets rule — is owned by `assets/compile-assembly-rules.md` (## Frontmatter). This catalog does not restate it (both files load together at compile.md §1).
 
 ### Two-Tier Section Structure
 
@@ -49,91 +33,16 @@ SKILL.md uses a two-tier structure to ensure actionable content survives `split-
 | 10 | **Full Type Definitions** | All types, interfaces, enums with full field details |
 | 11 | **Full Integration Patterns** | Co-import patterns, adapter details, pipeline internals (Forge/Deep only) |
 
-#### Assembly Rules
+#### Section Conditionality
 
-- Tier 1 sections are assembled first — they form the standalone body
-- Tier 2 sections are assembled after — they are progressive disclosure detail
-- Tier 1 sections are kept short enough that `split-body` targets the larger Tier 2 sections (`## Full` headings) into `references/`
-- After split-body, SKILL.md retains all Tier 1 content — actionable without loading references
-- An agent loading only SKILL.md (no references) must get enough to act
 - **Section 4b (Migration & Deprecation Warnings)** is conditional: only emitted for Deep tier when T2-future annotations exist. Quick/Forge/Forge+ tiers and Deep tiers without T2-future annotations omit it entirely (no empty section). Parsers and validators must treat this section as optional.
 - **Section 7b (Scripts & Assets)** is conditional: only emitted when `scripts_inventory` or `assets_inventory` is non-empty. Omitted entirely when no scripts or assets are detected. Parsers and validators must treat this section as optional.
 
-### Component Library Section Overrides
-
-When `scope.type: "component-library"`, these section formats replace their standard counterparts. All other sections (Overview, Common Workflows, Architecture, CLI, Manual Sections, etc.) use the standard format.
-
-#### Section 4 — Component Catalog (replaces Key API Summary)
-
-```markdown
-## Component Catalog
-
-| Category | Count | Key Components |
-|----------|-------|---------------|
-| {category} | {count} | {ComponentA}, {ComponentB}, {ComponentC}, ... |
-
-**Design system variants:** {primary} (primary), {variant2}, {variant3}
-**Total components:** {unique_count} | **With {variant1}:** {count1} | **With {variant2}:** {count2}
-```
-
-- Source: `component_catalog[]` from step 3d extraction
-- Group by `category` field from registry
-- Show top 3-5 component names per category
-- Cite registry file: `[SRC:{registry_file}:L1]`
-- Budget: ~20 lines (same as standard Section 4)
-
-#### Section 5 — Key Props (replaces Key Types)
-
-```markdown
-## Key Types
-
-### {ComponentName}Props
-
-| Prop | Type | Default | Required |
-|------|------|---------|----------|
-| {propName} | {type} | {default or —} | {yes/no} |
-
-{Repeat for top 5 Props interfaces}
-```
-
-- Show only the 5 most-used Props interfaces (by component count or documentation prominence)
-- Full Props details for all components go in Tier 2 reference
-- Budget: ~20 lines (same as standard Section 5)
-
-#### Tier 2 — Props Reference (replaces Full API Reference)
-
-```markdown
-## Full API Reference
-
-### {ComponentName}
+Assembly ordering, the under-300-line Tier-1 budget, and split-body targeting are owned by `assets/compile-assembly-rules.md` (### Assembly Rules).
 
-**Install:** `npx {cli} add {component-id}`
-**Available in:** {variant list}
-**Props:** `{ComponentName}Props`
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| {prop} | {type} | {default} | {description from JSDoc or —} |
-
-**Provenance:** `[AST:{file}:L{line}]`
-```
-
-- Organize by component, not by function
-- Each component shows: install command, variant availability, full props table
-- Include JSDoc descriptions for props when available
-- Standard provenance citations apply
-
-#### context-snippet.md — Component Library Format
+### Component Library Section Overrides
 
-```markdown
-[{name} v{version}]|root: skills/{name}/
-|IMPORTANT: {name} v{version} — read SKILL.md before writing {name} code. Do NOT rely on training data.
-|install: npx {cli} add <component-id>
-|catalog:{SKILL.md#component-catalog} — {N} components: {category(count), ...}
-|variants: {variant list} — {provider wrapping note if applicable}
-|key-props:{SKILL.md#key-types} — {top props interfaces with key fields}
-|gotchas: {detected gotchas}
-```
+The `component-library` section formats — Component Catalog (§4), Key Props (§5), the Props Reference Tier 2 layout, and the component-library `context-snippet.md` format — are owned by `assets/compile-assembly-rules.md` (### Component Library Assembly Overrides), alongside the `reference-app` and whole-language override sets. This catalog does not restate them (both files load together at compile.md §1).
 
 ### Provenance Citation Format
 
@@ -181,7 +90,7 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
 - **Token budget:** ~80-120 tokens per skill (justified by Vercel's finding that indexed format maintains performance at 80% compression)
 - **T1-now content only** — no T2 annotations in the snippet
 - **Section anchors** (`#quick-start`, `#key-types`) must match actual SKILL.md heading slugs
-- **Version** comes from source detection (per issue #32), not brief default
+- **Version** comes from source detection, not brief default
 
 ---
 
@@ -321,7 +230,7 @@ Each reference file includes:
 
 - `provenance_version`: Schema version. `"2.0"` enables unified single/stack support. Audit reads both v1 (no version field) and v2.
 - `source_library`: Identifies which library an export belongs to. For single skills, defaults to the skill/package name. For stack skills, identifies the constituent library.
-- `integrations`: Stack-only. Describes cross-library integration patterns with their own schema — NOT shoehorned into entries.
+- `integrations`: Stack-only. Describes cross-library integration patterns with their own schema — not shoehorned into entries.
 - `constituents`: Stack-only (compose-mode). Tracks the compose-time snapshot of each source skill for staleness detection. `metadata_hash` enables audit to detect constituent drift without re-reading all constituent files.
 - `file_entries` remains optional — omit when no scripts, assets, or promoted docs exist.
 - Single skills omit `integrations` and `constituents` arrays entirely (not empty arrays).
@@ -393,6 +302,6 @@ t2_future_count: {N}
 - {any warnings from extraction or validation}
 ```
 
-**Frontmatter — pinned detection contract:** the `t2_future_count` field is the authoritative forward-looking-annotation count for downstream gate checks (e.g. skf-test-skill §2b migration-section rule). Emit **always**, even when 0 — omission is indistinguishable from "no T2-future data" and silently flips the gate into Case 2/3 for a Case-1 skill. `generated` and `forge_tier` mirror the narrative header for consumers that read only the frontmatter. Downstream gate rules MUST parse `t2_future_count` from frontmatter, not grep prose — prose drift (heading renames, alternate phrasings like "forward-looking annotations") silently breaks the detection.
+**Frontmatter — pinned detection contract:** the `t2_future_count` field is the authoritative forward-looking-annotation count for downstream gate checks (e.g. skf-test-skill §2b migration-section rule). Emit **always**, even when 0 — omission is indistinguishable from "no T2-future data" and silently flips the gate into Case 2/3 for a Case-1 skill. `generated` and `forge_tier` mirror the narrative header for consumers that read only the frontmatter. Downstream gate rules parse `t2_future_count` from frontmatter, not prose — prose drift (heading renames, alternate phrasings like "forward-looking annotations") silently breaks grep-based detection.
 
 **Description Guard slot:** populated by step 6 §0 (create-skill) and §0 (update-skill) when the guard protocol fires. `Restored: true` indicates that an external tool (typically `skill-check --fix` or `split-body`) rewrote the frontmatter `description` and the guard restored the pre-tool value. When `Restored: false`, leave `Triggering tool`, `Original description preserved`, and `Notes` as `—`. When `Restored: true`, fill all four fields: tool name, whether the original was successfully written back, and a one-sentence note describing what the tool had changed (e.g., "replaced with generic summary", "truncated at 80 chars", "angle-bracket tokens re-introduced"). Downstream test-skill assertions can grep for `Restored: true` to detect unintended tool rewrites without parsing free-form warning prose.

package/src/skf-create-skill/assets/tessl-dismissal-rules.md

@@ -1,8 +1,6 @@
 # tessl Dismissal Rules
 
-This file is the **single source of truth** for tessl review findings that Skill Forge expects and must dismiss. Step-06 §6 loads this file, parses the `tessl skill review` JSON output, and cross-references each finding against the rules below. Matches are dismissed with their rationale logged to the evidence report; non-matches surface to the user via §6b.
-
-**Why this file exists:** Previously, expected tessl behavior was enumerated as prose in step 6 itself. Each time tessl evolved a scorer or added a new rule, step 6 had to be manually patched and the prose re-read by every execution. This file moves the expected behavior into a structured list with stable rule IDs, rationales, and match criteria — one place to update when tessl changes, one place to audit what SKF expects.
+This file is the **single source of truth** for tessl review findings that Skill Forge expects and must dismiss. Step-06 §6 loads this file, parses the `tessl skill review` JSON output, and cross-references each finding against the rules below. Matches are dismissed with their rationale logged to the evidence report; non-matches surface to the user via §6b. Never embed dismissal logic in step files — update the rules here first and reference them from step 6.
 
 ---
 
@@ -17,7 +15,7 @@ When parsing tessl output, check these fields against the thresholds below. Viol
 | `description_score` (LLM judge %) | `>= 60` | warn | The judge's 0–100 discoverability score, composed of `trigger_term_quality`, `specificity`, `completeness`, and `distinctiveness` sub-scores. A value below 100 while the deterministic `description_field` validator PASSES is a soft discoverability hint (e.g. jargon density), **not** a sanitizer bypass — record a warning and continue. Never halt on the judge percentage alone; the authored brief is the source of truth for the description. |
 | `content_score` | `>= 60` | warn | Two-tier design deliberately duplicates key API data across Tier 1 and Tier 2. Conciseness scorer penalizes this. 60 is the acceptable floor. |
 
-**Recovery is gated on the deterministic validator, not the judge percentage.** If tessl emits a `findings[]` entry with rule ID `description_field` (angle-bracket / XML-tag rejection), **attempt recovery first** per rule `description-xml-tags-guarded-upstream` below: re-apply step 5 §2a's `<` → `{` / `>` → `}` substitution in place on the staging SKILL.md frontmatter `description`, then re-run `npx -y tessl skill review <staging-skill-dir>` once. If the re-run clears the `description_field` finding, log `description-recovery: applied ({count} substitutions)` in the evidence report and proceed to normal suggestion handling. If recovery fails, halt with: "Description sanitization recovery failed — step 5 §2a's `<`/`>` → `{`/`}` replacement did not resolve the tessl finding. Investigate the staging SKILL.md frontmatter for non-angle-bracket content that tessl is still rejecting, and patch §2a accordingly. Do not edit the description manually." Do NOT proceed to §6b user prompt on an unrecovered failure.
+**Recovery is gated on the deterministic validator, not the judge percentage.** If tessl emits a `findings[]` entry with rule ID `description_field` (angle-bracket / XML-tag rejection), **attempt recovery first** per rule `description-xml-tags-guarded-upstream` below: re-apply step 5 §2a's `<` → `{` / `>` → `}` substitution in place on the staging SKILL.md frontmatter `description`, then re-run `npx -y tessl skill review <staging-skill-dir>` once. If the re-run clears the `description_field` finding, log `description-recovery: applied ({count} substitutions)` in the evidence report and proceed to normal suggestion handling. If recovery fails, halt with: "Description sanitization recovery failed — step 5 §2a's `<`/`>` → `{`/`}` replacement did not resolve the tessl finding. Investigate the staging SKILL.md frontmatter for non-angle-bracket content that tessl is still rejecting, and patch §2a accordingly. Do not edit the description manually." Do not proceed to §6b user prompt on an unrecovered failure.
 
 A `description_score` (LLM judge %) below 100 **without** an accompanying `description_field` finding is **not** a recovery trigger and **not** a halt condition: record `description_judge_score: {n}% (deterministic description_field validator PASSED)` as a warning in the evidence report and continue to suggestion handling. The recover-then-halt path is reserved for the deterministic validator.
 
@@ -25,7 +23,7 @@ A `description_score` (LLM judge %) below 100 **without** an accompanying `descr
 
 ## Suggestion Dismissal Rules
 
-Each rule below describes a tessl suggestion that Skill Forge expects and dismisses automatically. For each `judge_suggestion` in tessl output, check it against these rules in order. If any rule matches, record the dismissal in the evidence report (`rule_id`, `rationale`) and do NOT apply the suggestion. If no rule matches, the suggestion is novel and must surface to the user in §6b.
+Each rule below describes a tessl suggestion that Skill Forge expects and dismisses automatically. For each `judge_suggestion` in tessl output, check it against these rules in order. If any rule matches, record the dismissal in the evidence report (`rule_id`, `rationale`) and do not apply the suggestion. If no rule matches, the suggestion is novel and must surface to the user in §6b.
 
 ### Rule: `remove-manual-markers`
 
@@ -105,11 +103,4 @@ The recovery path makes the skill shippable when a downstream tool (`skill-check
 
 ## Evolving This List
 
-When tessl introduces new rules, changes scorer behavior, or SKF design decisions change:
-
-1. **Add a new rule section** above with `Rule:`, `Scorer:`, `Match criteria`, `Rationale`, `Action`.
-2. **Link the rationale** to the concrete SKF design principle it protects (two-tier design, MANUAL markers, sanitization, split-body preservation, etc.). A rationale without a design-principle link is a smell.
-3. **Keep score thresholds above current production floors.** Do not lower them to suppress real regressions.
-4. **Never embed dismissal logic in step files.** If step 6 needs updated behavior, update this file first and reference it from step 6.
-
-This file is load-bearing: step 6 §6 has no other source of truth for expected tessl behavior.
+When tessl changes or an SKF design decision shifts, add a new rule section above (`Rule:` / `Scorer:` / `Match criteria` / `Rationale` / `Action`), link each rationale to the concrete SKF design principle it protects (two-tier design, MANUAL markers, sanitization, split-body preservation — a rationale without such a link is a smell), and keep score thresholds at or above current production floors — never lower them to suppress real regressions.

package/src/skf-create-skill/customize.toml

@@ -1,6 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-create-skill.
+# Team overrides:     _bmad/custom/skf-create-skill.toml (under {project-root})
+# Personal overrides: _bmad/custom/skf-create-skill.user.toml (under {project-root})
 
 [workflow]
 
@@ -33,3 +35,14 @@ activation_steps_append = []
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
+
+# Pipeline-integration hook invoked after the final report (step 8) and the
+# result JSON / metadata.json are finalized. The command is called as:
+#   <on_complete> --result-path=<{forge_version}/create-skill-result-latest.json>
+# Useful for Slack notifications, dashboard ingest, CI hooks, or chaining a
+# downstream skill (TS test-skill, EX export). Failures are logged to
+# workflow_warnings[] but never fail the workflow.
+#
+# Empty string = no-op (default).
+
+on_complete = ""

package/src/skf-create-skill/references/authoritative-files-protocol.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Carved from `extract.md §2a`. Loaded on demand when step 3's `### 2a. Discovered Authoritative Files Protocol` sub-step runs.
+Loaded on demand when step 3's `### 2a. Discovered Authoritative Files Protocol` sub-step runs.
 
 **Skip this protocol entirely if `source_type: "docs-only"`** — there is no source tree to scan.
 
@@ -59,7 +59,7 @@ This protocol detects such files, prompts the user, and records the decision in
    - **`pre_decided[]` with `prior_action: "skipped"`** — user previously declined. Do nothing. Move on.
    - **`unresolved[]`** — proceed to step 3 below (user prompt).
 
-3. **Prompt.** Present each `unresolved[]` candidate to the user. Use the helper's `preview`, `size_bytes`, `line_count`, and `excluded_by_pattern` fields verbatim — they replace what the LLM previously had to compute itself:
+3. **Prompt.** Present each `unresolved[]` candidate to the user. Use the helper's `preview`, `size_bytes`, `line_count`, and `excluded_by_pattern` fields verbatim so the prompt reports facts rather than recomputing them:
 
    ```
    **Discovered authoritative file excluded by brief scope**
@@ -84,7 +84,7 @@ This protocol detects such files, prompts the user, and records the decision in
 5. **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.
+     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 7) 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:
@@ -105,7 +105,7 @@ This protocol detects such files, prompts the user, and records the decision in
      5. Display: "**Promoted `{path}`** — tracked as documentation file, amendment recorded."
 
    - **[S] Skip:**
-     1. Do NOT modify `scope.include` or `scope.exclude`.
+     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."
@@ -124,11 +124,11 @@ This protocol detects such files, prompts the user, and records the decision in
 
 ## How promoted docs reach the provenance map
 
-Promoted docs do NOT flow through §4 code extraction. Instead:
+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.
+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).
 
@@ -137,6 +137,6 @@ Promoted docs do NOT flow through §4 code extraction. Instead:
 Zero code changes required in consumer workflows:
 
 - **`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.
+- **`skf-audit-skill`** 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 5 §6; it is not persisted — the persisted form is the `file_entries[]` list in provenance-map.json.

package/src/skf-create-skill/references/compile.md

@@ -2,6 +2,14 @@
 nextStepFile: 'step-doc-sources.md'
 skillSectionsData: 'assets/skill-sections.md'
 assemblyRulesData: 'assets/compile-assembly-rules.md'
+# Resolve `{renderMetadataStatsHelper}` by probing `{renderMetadataStatsProbeOrder}`
+# in order (installed SKF module path first, src/ dev-checkout fallback); first
+# existing path wins. HALT if neither resolves — the metadata `stats` block and
+# `confidence_distribution` are computed values that must not be hand-binned
+# (the historical 147 ≠ 59 miscount lived exactly here).
+renderMetadataStatsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-render-metadata-stats.py'
+  - '{project-root}/src/shared/scripts/skf-render-metadata-stats.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -44,11 +52,11 @@ This is the `<staging-skill-dir>` referenced by step 6 (`npx skill-check check`,
 **When assembling function signatures, parameter lists, and return types in any SKILL.md section or reference file:**
 
 - **T1 provenance-map entries (AST-extracted) are authoritative** for: function name, parameter names, parameter types, parameter order, return type, and optionality markers (e.g., `?`, `Optional`, `= default`).
-- **T2 (QMD-enriched) and T3 (doc-derived) sources may ADD** contextual descriptions, usage notes, behavioral documentation, and examples to function entries, but **MUST NOT REPLACE** structural signature data from T1 entries.
+- **T2 (QMD-enriched) and T3 (doc-derived) sources may add** contextual descriptions, usage notes, behavioral documentation, and examples to function entries, but must not replace structural signature data from T1 entries.
 - **On conflict:** If a T2/T3 source provides a different signature than the T1 extraction for the same export (e.g., different parameter count, different types, missing `Partial<>` wrapper), keep the T1 signature and log a warning in the evidence report: "Signature conflict for `{export_name}`: T1 shows `{t1_signature}`, T2/T3 shows `{other_signature}`. T1 used as authoritative."
 - **`signature_source` field:** Record `signature_source: "T1" | "T1-low" | "T2" | "T3"` in each provenance-map entry to indicate the highest-confidence tier that contributed the structural signature data (params, return_type). This enables test-skill to verify signature provenance.
 
-This rule applies to ALL sections including Tier 1 Key API Summary, Tier 2 Full API Reference, and Section 4b Migration & Deprecation Warnings.
+This rule applies to every section including Tier 1 Key API Summary, Tier 2 Full API Reference, and Section 4b Migration & Deprecation Warnings.
 
 ### 2. Build SKILL.md Content
 
@@ -62,17 +70,11 @@ Assemble each section in order using the assembly rules data file (`{assemblyRul
 
 **Why unconditional?** Both `skill-check`'s `description_field` validator and `tessl`'s deterministic description check parse the frontmatter `description` as a raw string — they reject any `<` or `>` regardless of whether the content is inside a backtick span or a generic expression. The previous rule exempted backticked content on the assumption that backticks protect from XML-tag parsing, but that assumption is false for these validators: a backticked TypeScript generic like `` `Meta<typeof X>` `` still fails tessl's check because tessl reads the raw string before markdown parsing. Unconditional replacement guarantees no angle brackets reach either validator.
 
-**Coverage examples** (all handled by the same `<`/`>` → `{`/`}` replacement):
-
-- Standalone placeholders: `<name>` → `{name}`, `<component-id>` → `{component-id}` — curly braces are the standard placeholder notation in prose and render cleanly.
-- Backticked TypeScript / C++ / Rust generics: `` `Meta<typeof X>` `` → `` `Meta{typeof X}` ``, `` `Array<T>` `` → `` `Array{T}` ``, `` `Vec<u8>` `` → `` `Vec{u8}` `` — readable approximations that preserve the author's intent for code-ish fragments.
-- Any other angle-bracket content, whether inside backticks or bare, is also rewritten.
-
 **Scope:** This rule applies **only** to the frontmatter `description` field. Body content, code examples, reference files, and assembly-rule documents retain their original angle brackets — they are parsed through the markdown AST where backticks do protect content.
 
 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 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`.
+If a downstream tool re-introduces angle brackets into the description, step 6 §6 recovers via `description-xml-tags-guarded-upstream` in `assets/tessl-dismissal-rules.md`.
 
 ### 3. Build context-snippet.md Content
 
@@ -102,23 +104,30 @@ Following the structure from the skill-sections data file:
 - Set `generation_date` to current ISO-8601 timestamp
 - Set `source_commit` from resolved source (if available)
 - Set `source_ref` from resolved source ref (tag name, branch, or `HEAD`; null if unavailable)
-- Set `scope_type` from the brief's `scope.type` value verbatim (`full-library`, `specific-modules`, `public-api`, `component-library`, `reference-app`, or `docs-only`). **Always emit this field.** `skf-test-skill` keys reference-app handling on `metadata.json.scope_type == "reference-app"` — both the scoring redistribution (Signature Accuracy / Type Coverage marked N/A) and the coverage-check §4b count-coherence skip. Omitting it silently mis-scores a reference-app skill as a library (zero-export barrel HALT or false metadata-drift findings), which is why it previously had to be hand-added during test-skill. The value is informational for the other scope types (consumers only branch on `reference-app`), but emit it for all so the producer/consumer contract holds.
-- 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 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)
+- Set `scope_type` from the brief's `scope.type` value verbatim (`full-library`, `specific-modules`, `public-api`, `component-library`, `reference-app`, or `docs-only`). **Always emit this field.** `skf-test-skill` keys reference-app handling on `metadata.json.scope_type == "reference-app"` — both the scoring redistribution (Signature Accuracy / Type Coverage marked N/A) and the coverage-check §4b count-coherence skip. Omitting it silently mis-scores a reference-app skill as a library (zero-export barrel HALT or false metadata-drift findings). The value is informational for the other scope types (consumers only branch on `reference-app`), but emit it for all so the producer/consumer contract holds.
+- **Compute the `stats` block and `confidence_distribution` deterministically** with `{renderMetadataStatsHelper}` (resolve from `{renderMetadataStatsProbeOrder}`; first existing path wins). The helper owns all the arithmetic — binning each provenance entry once by its `signature_source` tier, summing the bins, and computing every coverage ratio — and returns the finished `stats` + `confidence_distribution` objects to write into `metadata.json` verbatim. Run `uv run {renderMetadataStatsHelper} --help` for the full contract. You supply only the judgment payload below.
+
+  **Judgment payload (what you decide — passed as JSON on stdin):**
+  - `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)
-  - `total_coverage`: `exports_documented / exports_total` (may be low for large codebases — this is expected; `null` if `exports_total` is 0)
-  - `effective_denominator` (**optional** — emit only for stratified-scope monorepo packages): the count of public exports from files matched by the brief's authoring-surface globs, filtered by `scope.exclude`, resolved against `source_path`. **Prefer `scope.tier_a_include` when the brief supplies it** — that narrow list represents the authoring surface the brief intends to document; resolve its globs across `source_path` and count the union of **named exports** — items reachable from the language's public entry-point barrel (`lib.rs` `pub use`, `index.ts` / `index.js` re-exports, `__init__.py` exports), where a type counts **once** with its methods and impl-block members rolling up under it (count a `pub fn` only when it is a free function reachable from the barrel, never a method on an already-counted type). **Otherwise use `scope.include`** — the coarse list. This counting unit matches what `skf-test-skill` re-derives on the consumer side (`coverage-check.md` §2c excludes `kind: "method"` from `documented_set`), so the producer- and test-side denominators stay aligned; without it, a type-heavy API (a few handle types carrying hundreds of methods) inflates the denominator by an order of magnitude and auto-fails the coverage gate. This is the coverage denominator `skf-test-skill` uses when the package is a curated subset of a multi-package repository, so it must match the brief's authoring intent. Compute when ALL of the following hold:
+  - `scripts` / `assets`: the `scripts_inventory` / `assets_inventory` arrays (or `[]` when empty) — the helper sets `stats.scripts_count` / `stats.assets_count` from their lengths
+  - `effective_denominator` (**optional** — include in the helper's judgment payload only for stratified-scope monorepo packages): the count of public exports from files matched by the brief's authoring-surface globs, filtered by `scope.exclude`, resolved against `source_path`. **Prefer `scope.tier_a_include` when the brief supplies it** — that narrow list represents the authoring surface the brief intends to document; resolve its globs across `source_path` and count the union of **named exports** — items reachable from the language's public entry-point barrel (`lib.rs` `pub use`, `index.ts` / `index.js` re-exports, `__init__.py` exports), where a type counts **once** with its methods and impl-block members rolling up under it (count a `pub fn` only when it is a free function reachable from the barrel, never a method on an already-counted type). **Otherwise use `scope.include`** — the coarse list. This counting unit matches what `skf-test-skill` re-derives on the consumer side (`coverage-check.md` §2c excludes `kind: "method"` from `documented_set`), so the producer- and test-side denominators stay aligned; without it, a type-heavy API (a few handle types carrying hundreds of methods) inflates the denominator by an order of magnitude and auto-fails the coverage gate. This is the coverage denominator `skf-test-skill` uses when the package is a curated subset of a multi-package repository, so it must match the brief's authoring intent. Compute when ALL of the following hold:
     1. The source is a monorepo (detected via `packages/` layout, `workspaces` field in root `package.json`, `lerna.json`, `rush.json`, `nx.json`, or Cargo `[workspace]`).
     2. `scope.type` is not `full-library` (and not `reference-app` — see carve-out below), AND the resolved include list (`tier_a_include` if present, else `scope.include`) lists a curated file/directory subset rather than the full workspace.
     3. `scope.notes` is present and documents the stratification strategy (e.g., a tiered A/B/C plan) — this serves as the intent marker confirming the subset is by design.
 
-    Otherwise omit the field entirely — when absent, `skf-test-skill` falls back to `exports_public_api`. See `skf-test-skill` `references/source-access-protocol.md` §Source API Surface Definition ("Stratified-scope monorepo packages") for the test-side consumption rules.
+    Otherwise omit it from the payload entirely — when absent, `skf-test-skill` falls back to `exports_public_api`. See `skf-test-skill` `references/source-access-protocol.md` §Source API Surface Definition ("Stratified-scope monorepo packages") for the test-side consumption rules.
 
     **Reference-app carve-out:** never emit `effective_denominator` for `scope.type: "reference-app"`, even when the three conditions above are literally satisfied (a reference-app-in-monorepo matches all of them). A reference app's coverage basis is `pattern_surfaces_documented`, not library exports — see the Reference-App stats semantics in `assets/compile-assembly-rules.md`.
-- Set `confidence_distribution` by binning **each documented export exactly once** by its provenance-map `signature_source` tier (`T1` → `t1`, `T1-low` → `t1_low`, `T2` → `t2`, `T3` → `t3`) — the four bins MUST sum to `stats.exports_documented`. Do NOT add T2 annotation counts or T3 doc-item counts on top of the per-export bins; those are enrichment totals and belong in the evidence report's Extraction Summary, not in the distribution. `skf-test-skill` coverage-check §4b enforces this sum as an internal-consistency defect. Carve-outs (mirroring that consumer): a **stack** skill bins the cited constituents (sums to the constituent count, not `exports_documented`); a **reference-app** bins per-citation provenance entries (sums to the citation count, not `pattern_surfaces_documented`)
+- **Shape:** pass `--shape reference-app` or `--shape stack` when the matching assembly-rules override applies (default `library`). For a reference app, also put `pattern_surfaces_documented` (the Pattern Surface row count) in the payload — the helper uses it as `exports_documented`, emits `stats.pattern_surfaces_documented`, and refuses to emit `effective_denominator`; the distribution then sums to the per-citation count, not to `exports_documented`. For a stack, put the own-barrel `exports_documented` (usually `0`) in the payload; the distribution sums to the cited-constituent count.
+- **Invoke** — stage `provenance-map.json` (§6) first, since the helper reads its `entries[]`:
+
+  ```bash
+  echo '{"exports_public_api": {N}, "exports_internal": {M}, "scripts": {scripts_inventory-or-[]}, "assets": {assets_inventory-or-[]}}' \
+    | uv run {renderMetadataStatsHelper} <staging-skill-dir>/provenance-map.json
+  ```
+
+  Write the returned `stats` and `confidence_distribution` verbatim. The helper derives `exports_documented` (the documented-export count = provenance `entries[]` count), `exports_total` = `exports_public_api` + `exports_internal`, `public_api_coverage` = documented / public_api (`null` if public_api is 0), `total_coverage` = documented / total (`null` if total is 0), and bins `confidence_distribution.{t1, t1_low, t2, t3}` by each entry's `signature_source` — **each entry counted exactly once**, so the four bins provably sum to the documented-export count. This structurally prevents the recurring miscount where binning ~8 T2 annotations + ~80 T3 doc items on top of 59 exports produced a distribution summing to 147 ≠ 59 (`skf-test-skill` coverage-check §4b flags that sum as an internal-consistency defect). If the helper reports `coherence.ok: false`, some provenance entries carry a missing/unrecognized `signature_source` (or a file-entry count disagrees) — fix the provenance map, do not hand-edit the stats.
 - Set `description` from the SKILL.md frontmatter `description` field (already assembled in section 2)
 - Set `language` from source analysis (e.g., `"typescript"`, `"python"`) — use the primary language of the entry point file
 - Set `ast_node_count` from extraction stats if ast-grep was used (Forge/Deep tier), otherwise omit
@@ -138,7 +147,7 @@ Following the structure from the skill-sections data file:
   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 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.
+- If `scripts_inventory` is non-empty, populate the `scripts[]` array (per-file `{file, purpose, source_file, confidence}` rows). If `assets_inventory` is non-empty, populate the `assets[]` array. Omit the `scripts[]` / `assets[]` arrays entirely when their inventory is empty — `stats.scripts_count` / `stats.assets_count` were already set by `{renderMetadataStatsHelper}` from the `scripts` / `assets` payload you passed it (0 when empty).
 
 ### 5. Build references/ Content
 
@@ -158,7 +167,7 @@ One entry per extracted export: export_name, export_type, params[] (typed string
 
 - `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.
+- `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.
 
@@ -166,33 +175,11 @@ Each `file_entries[]` row has the same shape regardless of `file_type`: `{file_n
 
 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 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 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
-
-| Step | Gate | Decision | Rationale | Timestamp |
-|------|------|----------|-----------|-----------|
-| {step} | {gate} | {decision}{value?} | {rationale} | {timestamp} |
-```
-
-If `headless_decisions[]` is empty, emit the section header with a single line: `No auto-decisions — workflow ran interactively (or all gates had no match to auto-resolve).` This guarantees the section is always present so reviewers can tell "zero auto-decisions" apart from "section missing".
-
-### 8. Menu Handling Logic
-
-**Auto-proceed step — no user interaction.**
-
-After all content is assembled in context and written to the staging directory, immediately load, read entire file, then execute `{nextStepFile}`.
-
-#### EXECUTION RULES:
+**Frontmatter — pinned fields:** 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.
 
-- This is an auto-proceed assembly step with no user choices
-- All content must be both in context and in `_bmad-output/{skill-name}/` — no final files in `skills/` or `forge-data/` yet
-- Proceed directly to validation after assembly is complete
+**Auto-Decisions section (render from the durable sink):** render the `## Auto-Decisions` section into `evidence-report.md` from the **union of the on-disk auto-decision sink** (`{sidecar_path}/auto-decisions.jsonl`, established at step 1 §3 and appended to on every gate landing) **and the in-context `headless_decisions[]` buffer** — read the sink's JSON lines, union them with the buffer keyed on `step`+`gate` so nothing is duplicated or dropped, and emit one row per entry in the table format documented in step 6 §8. The sink is authoritative: on a long component-library run the in-context buffer may have compacted across the token-heavy step 3→5 extraction window, but the sink carries every decision written as it landed (step 1 tier-override, step 2 ecosystem gate, step 3 zero-exports, step 3d component-extraction gates). This step is the first point `evidence-report.md` is written to disk (staging dir, §8 below). Exactly one gate can still fire after this step — step 6 §6b (the tessl-suggestions gate) — and step 6 §8 re-reconciles idempotently. If the union is empty (no decision has fired), emit the section with the single line `No auto-decisions — workflow ran interactively (or all gates had no match to auto-resolve).` — step 6 §8 replaces that line if a later decision lands.
 
-## CRITICAL STEP COMPLETION NOTE
+### 8. Auto-Proceed
 
-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.
+No user interaction. Once all content is assembled in context and written to the staging directory `_bmad-output/{skill-name}/` (no final files in `skills/` or `forge-data/` yet), load `{nextStepFile}`, read it fully, then execute it. `extraction-rules.yaml` is generated by step 7 from extraction data — do not create it here.
 

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

@@ -19,7 +19,7 @@ When `scope.type: "component-library"`, perform specialized extraction that trea
 
 ## MANDATORY SEQUENCE
 
-**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.
+**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
 
@@ -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: "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.
+**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[]` and, the moment it lands, append the same object as a JSON line to the durable audit sink `{sidecar_path}/auto-decisions.jsonl` (the on-landing append established at step 1 §3) — the sink feeds the evidence-report `## Auto-Decisions` table at step 5 §7 and step 6 §8. 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: "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[]` and, the moment it lands, append the same object as a JSON line to the durable audit sink `{sidecar_path}/auto-decisions.jsonl` (the on-landing append established at step 1 §3). 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 the same way (buffer + sink, `decision: "reject-low-score"`), 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: "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[]` and, the moment it lands, append the same object as a JSON line to the durable audit sink `{sidecar_path}/auto-decisions.jsonl` (the on-landing append established at step 1 §3). 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).
 
@@ -160,7 +160,7 @@ constraints:
 
 Also run `export const $NAME` patterns for arrow function components.
 
-For each component export: record name, source file, line number. Do NOT document the function signature in detail (it's always `(props: XProps) => JSX.Element`).
+For each component export: record name, source file, line number. Do not document the function signature in detail (it's always `(props: XProps) => JSX.Element`).
 
 **Step 3 — Link Props to Components:**
 
@@ -185,7 +185,7 @@ Extract non-Props type exports using standard AST patterns (same as Forge tier):
 
 When multiple design system variants exist:
 
-1. **Group components by registry `id`** (NOT by filename — registry is source of truth):
+1. **Group components by registry `id`** (not by filename — registry is source of truth):
    - For each `id` in `component_catalog[]`, collect all variant paths from `available_in[]` and `code_paths[]`
 
 2. **Select canonical props definition:**
@@ -243,33 +243,6 @@ Display: "**Component extraction complete.** Returning to main extraction flow."
 
 ## RETURN PROTOCOL
 
-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.
+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 confirmation.
 
-Do NOT load `{returnToStep}` — the calling step (step 3) will continue from where it delegated.
-
----
-
-## SYSTEM SUCCESS/FAILURE METRICS
-
-### SUCCESS:
-
-- Demo/example files detected and excluded with user confirmation
-- Registry detected (or user provided path) and parsed into component_catalog
-- Props interfaces extracted as primary API contracts
-- 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 3 section 5 inventory format
-- component_catalog stored in context for step 5
-
-### FAILURE:
-
-- Excluding demo files without user confirmation
-- Accepting a registry candidate without user confirmation
-- Not extracting Props interfaces as primary API surface
-- 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 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.
+Do not load `{returnToStep}` — the calling step (step 3) continues from where it delegated.

package/src/skf-create-skill/references/ecosystem-check.md

@@ -29,7 +29,7 @@ Query the ecosystem using the skill name from the brief:
 - Enforce 5-second timeout — if the query does not return within 5 seconds, treat as no match. Rationale: ecosystem check is an opportunistic advisory; a slow or degraded registry must not stall the compilation pipeline, and 5s is well beyond any healthy registry's p99 latency.
 - Cache results for 24 hours (if re-running same skill). Rationale: the agentskills.io registry publishes new official skills in daily batches; a 24-hour TTL balances freshness against redundant network calls during iterative brief refinement.
 
-**If registry API is NOT available (current default):**
+**If registry API is not available (current default):**
 
 Skip completely and silently. Do not output any message about API unavailability or the ecosystem check being skipped. Emit zero text to the console. Proceed exactly as if no match was found.
 
@@ -59,32 +59,16 @@ Auto-proceed silently to next step. Do not display any message about the ecosyst
 
 Auto-proceed silently. Log a note in context: "Ecosystem check skipped (timeout/error) — proceeding with compilation."
 
-### 3. Menu Handling Logic
+### 3. Gate — Ecosystem Match (conditional)
 
-**Conditional menu — only displayed if a match was found.**
+This gate fires only when §2 found a match; on no match, timeout, or unavailable tool the step already auto-proceeded to `{nextStepFile}` with no menu.
 
-#### If Match Found — Present MENU OPTIONS:
+**GATE [default: P]** — under `{headless_mode}` with a match, auto-proceed as [P], log "headless: ecosystem match found, auto-proceeding", and append `{step: "ecosystem-check", gate: "ecosystem-match", decision: "P", rationale: "headless mode — match found, auto-proceed with user's own compilation", timestamp: {ISO}}` to `headless_decisions[]` and, the moment it lands, append the same object as a JSON line to the durable audit sink `{sidecar_path}/auto-decisions.jsonl` (the on-landing append established at step 1 §3) — the sink feeds the evidence-report `## Auto-Decisions` table at step 5 §7 and step 6 §8.
 
-Display: "**Ecosystem match found — Select an Option:** [P] Proceed with compilation [I] Install existing [A] Abort"
+Interactively, halt and wait for the user's choice on the §2 menu:
 
-#### 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: "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
-
-#### Menu Handling Logic:
-
-- IF P: Note user's decision to proceed despite existing skill. Immediately load, read entire file, then execute `{nextStepFile}`
-- IF I: Display: "Install the existing skill using: `[SF] Setup Forge → install {matched_skill_name}`" then halt workflow. Do not proceed to extraction.
-- IF A: Display: "Compilation aborted. Return to Ferris menu to select another action." then halt workflow.
-- IF no match/timeout/error: Auto-proceed — immediately load, read entire file, then execute `{nextStepFile}`
-- IF Any other comments or queries: help user respond then redisplay the menu
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the ecosystem check is complete (match evaluated, user decision made if applicable) will you proceed to load `{nextStepFile}` for source extraction.
-
-If no match is found, this step auto-proceeds with no user interaction.
+- **P** — proceed despite the existing skill; load `{nextStepFile}`, read it fully, then execute it.
+- **I** — display "Install the existing skill using: `[SF] Setup Forge → install {matched_skill_name}`", then halt (no extraction).
+- **A** — display "Compilation aborted. Return to Ferris menu to select another action.", then halt.
+- Any other question — answer it, then redisplay the menu.