bmad-module-skill-forge 0.7.2 → 0.7.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",

package/src/knowledge/qmd-registry.md

@@ -127,7 +127,7 @@ These registries are orthogonal — they never reference each other, and their j
 
 ```
 qmd collection remove {name}-extraction   (if exists)
-qmd collection add skills/{name} --name {name}-extraction --mask "**/*"
+qmd collection add {project-root}/skills/{name} --name {name}-extraction --mask "**/*"
 qmd embed
 ```
 

package/src/workflows/analyze-source/data/skill-brief-schema.md

@@ -9,7 +9,7 @@ Defines the output contract for skill-brief.yaml files generated by analyze-sour
 | Field | Type | Constraint | Description |
 |-------|------|------------|-------------|
 | name | string | kebab-case `[a-z0-9-]+` | Unique skill identifier |
-| version | string | Semantic `X.Y.Z` | Auto-detect from source (see Version Detection below), fall back to `1.0.0` |
+| version | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | Auto-detect from source (see Version Detection below), fall back to `1.0.0` |
 | source_repo | string | GitHub URL or local path | Repository or project root (optional when `source_type: "docs-only"`) |
 | language | string | Recognized language | Primary programming language |
 | scope | object | See Scope Object below | Boundary definition |
@@ -49,6 +49,8 @@ If detection succeeds, use the detected version. If it fails or returns a non-se
 
 The create-skill workflow (step-03-extract) also performs version reconciliation at extraction time — if the source version has changed since the brief was created, the extraction step warns and uses the source version.
 
+**Pre-release handling:** If the detected version contains a pre-release tag (e.g., `1.0.0-beta.0`, `2.0.0-rc.1`), preserve it as-is. Pre-release tags are valid semver and must not be stripped. When comparing versions during reconciliation, use semver-aware comparison that respects pre-release ordering.
+
 ## Scope Object
 
 ```yaml

package/src/workflows/analyze-source/steps-c/step-05-recommend.md

@@ -5,8 +5,8 @@ description: 'Present unit recommendations with rationale for user confirmation
 nextStepFile: './step-06-generate-briefs.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 schemaFile: '../data/skill-brief-schema.md'
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationSkill: '/bmad-advanced-elicitation'
+partyModeSkill: '/bmad-party-mode'
 ---
 
 # Step 5: Recommend
@@ -193,8 +193,8 @@ Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [D] Disc
 
 #### Menu Handling Logic:
 
-- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
-- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
+- IF A: Invoke {advancedElicitationSkill}, and when finished redisplay the menu
+- IF P: Invoke {partyModeSkill}, and when finished redisplay the menu
 - IF D: Accept a new repo path/URL from the user. Run a lightweight scan + classify (subset of steps 02-03) for the new source only. Merge new units into the existing report and update `project_paths[]` in frontmatter. Run export mapping for the new units (same logic as step 04 section 2). Generate recommendation cards for the new units and present them for confirmation. Then redisplay this menu.
 - IF C: Save recommendations to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
 - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#8-present-menu-options)

package/src/workflows/brief-skill/data/skill-brief-schema.md

@@ -5,7 +5,7 @@
 | Field | Type | Constraint | Description |
 |-------|------|------------|-------------|
 | name | string | kebab-case `[a-z0-9-]+` | Unique skill identifier |
-| version | string | Semantic `X.Y.Z` | Auto-detect from source (see Version Detection below), fall back to `1.0.0` |
+| version | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | Auto-detect from source (see Version Detection below), fall back to `1.0.0` |
 | source_repo | string | GitHub URL or local path | Repository or project root (optional when `source_type: "docs-only"`) |
 | language | string | Recognized language | Primary programming language |
 | scope | object | See Scope Object below | Boundary definition |
@@ -45,6 +45,8 @@ If detection succeeds, use the detected version. If it fails or returns a non-se
 
 The create-skill workflow (step-03-extract) also performs version reconciliation at extraction time — if the source version has changed since the brief was created, the extraction step warns and uses the source version.
 
+**Pre-release handling:** If the detected version contains a pre-release tag (e.g., `1.0.0-beta.0`, `2.0.0-rc.1`), preserve it as-is. Pre-release tags are valid semver and must not be stripped. When comparing versions during reconciliation, use semver-aware comparison that respects pre-release ordering.
+
 ## Scope Object Structure
 
 ```yaml

package/src/workflows/brief-skill/steps-c/step-02-analyze-target.md

@@ -60,6 +60,12 @@ To analyze the target repository by resolving its location, reading its structur
 **For GitHub URLs:**
 - Use `gh api repos/{owner}/{repo}` to verify the repository exists
 - Use `gh api repos/{owner}/{repo}/git/trees/HEAD?recursive=1` to get the file tree
+
+**Truncation detection:** After receiving the tree response, check the `truncated` field in the JSON output. If `truncated: true`:
+- Display: "Note: GitHub API returned a truncated tree response ({count} items). Full analysis may require a local clone."
+- Record in analysis summary: "Tree listing is partial — some files may not appear in the analysis."
+- For very large repos (>1000 files in tree response): suggest local clone for complete analysis.
+
 - If inaccessible: **HALT** — "**Error:** Cannot access repository at {url}. Please verify the URL is correct and you have access. If private, ensure `gh auth` is configured."
 
 **For local paths:**
@@ -133,6 +139,8 @@ Based on detected language, identify public API surface:
 
 **Semantic Signals (Forge+ and Deep with ccc only):**
 
+**Remote source guard:** If the target source was resolved via GitHub API (remote URL, not a local file path), skip this CCC subsection — CCC requires a local source index and cannot operate on remote-only sources. Note: "CCC semantic discovery skipped — target is remote. CCC will be available during create-skill if the source is cloned locally."
+
 If `tools.ccc` is true in forge-tier.yaml, supplement the module listing with a semantic discovery pass:
 
 **CCC Semantic Discovery:**

package/src/workflows/brief-skill/steps-c/step-03-scope-definition.md

@@ -4,8 +4,8 @@ description: 'Collaboratively define skill scope boundaries using analysis findi
 
 nextStepFile: './step-04-confirm-brief.md'
 scopeTemplatesFile: '../data/scope-templates.md'
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationSkill: '/bmad-advanced-elicitation'
+partyModeSkill: '/bmad-party-mode'
 ---
 
 # Step 3: Scope Definition
@@ -90,7 +90,7 @@ Wait for confirmation. Then skip to section 5 (Summarize Scope Decisions) with:
 
 **If `source_type: "source"` (default):** Continue to scope templates below.
 
-### 2c. Confirm Supplemental Documentation (if doc_urls collected)
+### 2b. Confirm Supplemental Documentation (if doc_urls collected)
 
 **If `source_type: "source"` AND supplemental `doc_urls` were collected in step 01:**
 
@@ -104,7 +104,7 @@ Wait for confirmation. Record any changes to `doc_urls`.
 
 **If no supplemental doc_urls were collected:** Skip this subsection.
 
-### 2b. Offer Scope Templates
+### 2c. Offer Scope Templates
 
 Load `{scopeTemplatesFile}` for the scope type options ([F], [M], [P]) and their descriptions.
 
@@ -167,8 +167,8 @@ Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Conti
 
 #### Menu Handling Logic:
 
-- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
-- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
+- IF A: Invoke {advancedElicitationSkill}, and when finished redisplay the menu
+- IF P: Invoke {partyModeSkill}, and when finished redisplay the menu
 - IF C: Load, read entire file, then execute {nextStepFile}
 - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options)
 

package/src/workflows/brief-skill/steps-c/step-04-confirm-brief.md

@@ -5,8 +5,8 @@ description: 'Present complete skill brief for user review and confirmation befo
 nextStepFile: './step-05-write-brief.md'
 reviseStepFile: './step-03-scope-definition.md'
 briefSchemaFile: '../data/skill-brief-schema.md'
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationSkill: '/bmad-advanced-elicitation'
+partyModeSkill: '/bmad-party-mode'
 ---
 
 # Step 4: Confirm Brief
@@ -165,8 +165,8 @@ Display: **Select an Option:** [R] Revise Scope [A] Advanced Elicitation [P] Par
 #### Menu Handling Logic:
 
 - IF R: Load, read entire file, then execute {reviseStepFile} to re-enter scope definition
-- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
-- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
+- IF A: Invoke {advancedElicitationSkill}, and when finished redisplay the menu
+- IF P: Invoke {partyModeSkill}, and when finished redisplay the menu
 - IF C: Load, read entire file, then execute {nextStepFile}
 - IF Any other comments or queries: help user respond, apply any field adjustments, re-present brief if changed, then [Redisplay Menu Options](#6-present-menu-options)
 

package/src/workflows/create-skill/data/compile-assembly-rules.md

@@ -116,6 +116,7 @@ Do NOT repeat Tier 1's name/purpose/key-params table format in Tier 2. Tier 2 is
 4. If Tier 1 alone exceeds 300 lines, reduce Key API Summary and Architecture at a Glance
 5. Tier 1 sections are kept short enough that `split-body` targets the larger Tier 2 sections (`## Full ...` headings) instead
 6. After split-body, SKILL.md must still contain all Tier 1 sections with actionable content
+7. **Signature fidelity:** When populating function entries from the extraction inventory, always use the `params` and `return_type` fields from the provenance-map entry (T1/AST-backed). Do not substitute parameter names, types, or return types from documentation, README examples, or enrichment annotations. T2/T3 sources may enrich descriptions and add usage notes, but structural signature data from AST extraction is authoritative.
 
 ### Reference File Rules
 

package/src/workflows/create-skill/data/extraction-patterns.md

@@ -51,7 +51,7 @@ Structural extraction via ast-grep — verified exports with line-level citation
 - Internal/private functions: excluded (not part of public API)
 
 ### ast-grep Patterns
-- JS/TS: `export function $NAME($$$PARAMS): $RET` / `export const $NAME`
+- JS/TS: `export function $NAME($$$PARAMS): $RET` / `export const $NAME = ($$$PARAMS) => $BODY` / `export const $NAME` / `export class $NAME`
 - Rust: `pub fn $NAME($$$PARAMS) -> $RET`
 - Python: function definitions within `__all__` list
 - Go: capitalized function definitions
@@ -260,6 +260,32 @@ rule:
   pattern: 'export const $NAME = $VALUE'
 ```
 
+**JavaScript/TypeScript — exported arrow functions:**
+
+```yaml
+id: js-exported-arrow-functions
+language: typescript
+rule:
+  pattern: 'export const $NAME = ($$$PARAMS) => $BODY'
+```
+
+> **JS/TS Pattern Merging:** Modern TypeScript codebases often use `export const` exclusively for all exports (arrow functions, objects, constants). Run ALL four JS/TS patterns (functions, arrow functions, constants, classes) and merge results by `$NAME`. Priority when deduplicating: arrow function match > function declaration match > constant match. Arrow function matches capture parameters directly; constant matches require inspecting `$VALUE` to extract signatures.
+
+**JavaScript/TypeScript — exported classes (use `find_code`, not `find_code_by_rule`):**
+
+```yaml
+id: js-exported-classes
+language: typescript
+rule:
+  pattern: 'export class $NAME'
+```
+
+> **Important:** For class patterns, use `find_code()` rather than `find_code_by_rule()`. The `find_code_by_rule` API requires explicit AST `kind` rules for class exports, which adds complexity. The simpler `find_code()` pattern approach works reliably for class detection.
+
+**JavaScript/TypeScript — re-export detection (use `find_code`):**
+
+Use `find_code()` with pattern `export { $$$NAMES } from $SOURCE` for re-export detection. Note: this pattern may produce multiple AST node matches. Post-process results to split comma-separated names from `$$$NAMES`. For complex re-export chains (aliased exports, default re-exports, namespace re-exports), fall back to the Re-Export Tracing protocol in `extraction-patterns-tracing.md`.
+
 **Rust — public functions:**
 
 ```yaml
@@ -277,12 +303,29 @@ rule:
 id: go-exported-functions
 language: go
 rule:
-  pattern: 'func $NAME($$$PARAMS) $RET'
+  any:
+    - pattern: 'func $NAME($$$PARAMS) $RET'
+    - pattern: 'func $NAME($$$PARAMS)'
 constraints:
   NAME:
     regex: '^[A-Z]'
 ```
 
+### Known ast-grep Limitations
+
+When using ast-grep for extraction, be aware of these documented limitations:
+
+1. **`find_code_by_rule` requires explicit `kind` for class exports:** The `export class $NAME` pattern needs a `kind` rule specifying the tree-sitter node type when used with `find_code_by_rule`. Use the simpler `find_code()` API instead for class detection.
+
+2. **Re-export patterns produce multiple AST nodes:** `export { A, B, C } from './module'` decomposes into multiple metavariable bindings for `$$$NAMES`. Results require post-processing to split comma-separated names.
+
+3. **Default anonymous exports capture no name:** `export default function $NAME` works, but `export default $EXPR` (anonymous default export) captures no name in `$NAME`. Fall back to source reading (T1-low) for anonymous defaults.
+
+4. **Fallback protocol:** If an ast-grep pattern returns errors or zero results when results are expected:
+   - First: retry with `find_code()` using a simpler pattern (drop type annotations, use broader match)
+   - Second: if `find_code()` also fails, fall back to source reading for that pattern category (T1-low confidence)
+   - Never silently accept zero results for a pattern category that the source language commonly uses
+
 ### Re-Export Tracing and Script/Asset Extraction
 
 See `extraction-patterns-tracing.md` for:

package/src/workflows/create-skill/data/skill-sections.md

@@ -199,7 +199,8 @@ Each reference file includes:
       "source_line": 42,
       "confidence": "T1",
       "extraction_method": "ast-grep",
-      "ast_node_type": "export_function_declaration"
+      "ast_node_type": "export_function_declaration",
+      "signature_source": "T1"
     }
   ],
   "file_entries": [

package/src/workflows/create-skill/steps-c/step-02b-ccc-discover.md

@@ -47,7 +47,7 @@ For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed
 
 - Available: tier, tools.ccc, ccc_index from forge-tier.yaml (loaded in step-01)
 - Available: brief_data (name, scope, description) from step-01
-- Available: source_root (resolved source path) from step-01
+- Available: source_root (resolved source path) from step-01 — note: for remote sources, `source_root` may not be a local path until step-03 performs the ephemeral clone
 - Focus: Semantic discovery only — no extraction, no compilation
 - Dependencies: step-02 must have completed
 
@@ -67,6 +67,8 @@ Check `tools.ccc` from forge-tier.yaml. If `tools.ccc` is false, set `{ccc_disco
 
 If `tools.ccc` is true, continue to section 2.
 
+**Remote source guard:** If `source_root` is a remote URL (GitHub repository not yet cloned locally — ephemeral clone happens in step-03), CCC cannot operate. Set `{ccc_discovery: []}` and display: "CCC discovery skipped — remote source not yet available locally. CCC requires a local source index." Auto-proceed to the step completion / next step section.
+
 ### 2. Check CCC Index State
 
 Read `ccc_index` from forge-tier.yaml:

package/src/workflows/create-skill/steps-c/step-03b-fetch-temporal.md

@@ -172,7 +172,7 @@ If a `{skill-name}-temporal` collection already exists, remove and recreate for
 
 ```bash
 qmd collection remove {skill-name}-temporal
-qmd collection add _bmad-output/{skill-name}-temporal/ --name {skill-name}-temporal --mask "*.md"
+qmd collection add {project-root}/_bmad-output/{skill-name}-temporal/ --name {skill-name}-temporal --mask "*.md"
 qmd embed
 ```
 
@@ -193,7 +193,7 @@ If an entry with `name: "{skill-name}-temporal"` already exists in `qmd_collecti
 **Clean up** the staging directory after successful indexing:
 
 ```bash
-rm -rf _bmad-output/{skill-name}-temporal/
+rm -rf {project-root}/_bmad-output/{skill-name}-temporal/
 ```
 
 **Error handling:**

package/src/workflows/create-skill/steps-c/step-03c-fetch-docs.md

@@ -153,7 +153,7 @@ Parse the successfully fetched markdown for:
 **If tier is Deep and at least one URL was fetched successfully:**
 
 1. Write fetched markdown files to a staging directory: `_bmad-output/{skill-name}-docs/`
-2. Index into QMD: `qmd collection add _bmad-output/{skill-name}-docs/ --name {skill-name}-docs --mask "*.md"`
+2. Index into QMD: `qmd collection add {project-root}/_bmad-output/{skill-name}-docs/ --name {skill-name}-docs --mask "*.md"`
 3. Generate embeddings: `qmd embed` (required for `vector_search` and `deep_search`)
 4. Register in forge-tier.yaml `qmd_collections` array:
 
@@ -165,7 +165,7 @@ Parse the successfully fetched markdown for:
   created_at: "{current ISO date}"
 ```
 
-5. Clean up staging directory after indexing: `rm -rf _bmad-output/{skill-name}-docs/`
+5. Clean up staging directory after indexing: `rm -rf {project-root}/_bmad-output/{skill-name}-docs/`
 
 **If QMD indexing fails:** Warn: "QMD indexing of fetched docs failed. T3 items are still in the extraction inventory — enrichment will proceed without QMD-indexed docs." Continue.
 

package/src/workflows/create-skill/steps-c/step-05-compile.md

@@ -59,6 +59,17 @@ To assemble the complete skill content from the extraction inventory and enrichm
 
 Load `{skillSectionsData}` and `{assemblyRulesData}` completely. These define the agentskills.io-compliant format and detailed assembly rules for all output artifacts.
 
+### 1b. Signature Fidelity Rule
+
+**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.
+- **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.
+
 ### 2. Build SKILL.md Content
 
 Assemble each section in order using the assembly rules data file (`{assemblyRulesData}`). The data file specifies frontmatter format, Tier 1 section details (Sections 1-8, including conditional Section 7b for scripts/assets), Tier 2 section details (Sections 9-11), and assembly ordering rules. Follow it exactly. Assemble Section 7b (Scripts & Assets) only if `scripts_inventory` or `assets_inventory` is non-empty.
@@ -92,7 +103,7 @@ Following the structure from the skill-sections data file:
 - Set `source_commit` from resolved source (if available)
 - 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)
+  - `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_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)
@@ -121,7 +132,7 @@ Group functions logically by module, file, or functional area.
 
 ### 6. Build provenance-map.json Content
 
-One entry per extracted export: export_name, export_type, params[] (typed strings), return_type, source_file, source_line, confidence tier (T1/T1-low/T2), extraction_method, ast_node_type. If `scripts_inventory` or `assets_inventory` is non-empty, add `file_entries[]` with file_name, file_type, source_file, content_hash, confidence, extraction_method. See `{skillSectionsData}` for full schema.
+One entry per extracted export: export_name, export_type, params[] (typed strings), return_type, source_file, source_line, confidence tier (T1/T1-low/T2), extraction_method, ast_node_type, signature_source ("T1"|"T1-low"|"T2"|"T3" — indicates which tier contributed the structural signature). If `scripts_inventory` or `assets_inventory` is non-empty, add `file_entries[]` with file_name, file_type, source_file, content_hash, confidence, extraction_method. See `{skillSectionsData}` for full schema.
 
 ### 7. Build evidence-report.md Content
 

package/src/workflows/create-skill/steps-c/step-06-validate.md

@@ -76,6 +76,8 @@ This performs frontmatter validation, description quality checks, body limit enf
 
 **Context sync after --fix:** If `fixed[]` is non-empty (i.e., `--fix` modified files on disk), re-read the modified SKILL.md to update the in-context copy. Verify the re-read content matches expectations before proceeding. This prevents silent divergence between the in-context SKILL.md and the on-disk version that step-07 will use for artifact generation.
 
+**Description preservation after --fix:** After re-reading the modified SKILL.md, compare the frontmatter `description` field against the original step-05 compiled description. If `--fix` replaced the description with a generic or truncated version, restore the original description to the on-disk file and update the in-context copy. The step-05 compiled description is authoritative — auto-fix tools must not replace trigger-optimized descriptions.
+
 **Note:** `skill-check` may return non-zero exit code even when `errorCount` is 0. Always rely on parsed JSON, not the shell exit code.
 
 - **Score ≥ 70:** Record "Schema: PASS (score: {score}/100)" in evidence-report
@@ -101,15 +103,17 @@ If fails: auto-fix (deterministic), re-validate once, record result. If passes:
 
 **If step 2 reported `body.max_lines` failure:**
 
-**Preferred approach — selective split:** Rather than a full `split-body`, identify which Tier 2 section(s) are largest (usually `## Full API Reference`) and manually extract only those to `references/`. Keep all Tier 1 content and smaller Tier 2 sections inline. This preserves agent accuracy — inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval (per Vercel research). The rationale: inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval (per Vercel research).
+**Description preservation:** Before any split operation, capture the current SKILL.md frontmatter `description` field. After the split completes, verify the `description` was not modified. If it was replaced with a generic placeholder, restore the original immediately.
 
-**If manual selective split is not feasible**, fall back to the automated full split:
+**Mandatory approach — selective split:** Identify Tier 2 sections by their `## Full` heading prefix (e.g., `## Full API Reference`, `## Full Type Definitions`, `## Full Integration Patterns`). Extract ONLY those sections to `references/`, starting with the largest. Keep ALL Tier 1 content and any smaller sections inline. Inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval (per Vercel research).
 
-```bash
-npx skill-check split-body <staging-skill-dir> --write
-```
+**FORBIDDEN:** Running `npx skill-check split-body --write` without prior selective extraction. The `split-body --write` command extracts ALL `##` sections top-to-bottom, destroying Tier 1 inline content that the two-tier design depends on. This command is a LAST RESORT only after selective split has been attempted and proven insufficient.
+
+**If selective split alone does not bring body under the limit** (rare — typically only occurs when Tier 1 itself exceeds 300 lines): reduce Tier 1 Key API Summary and Architecture at a Glance sections to fit within limits. Do NOT fall back to automated `split-body --write` to solve a Tier 1 sizing problem.
+
+**Tier 1 preservation check:** After ANY split operation, verify that ALL of the following sections remain inline in SKILL.md (not moved to references/): Overview, Quick Start, Common Workflows, Key API Summary, Migration & Deprecation Warnings (if present), Key Types, Architecture at a Glance, CLI (if present), Scripts & Assets (if present), Manual Sections. If any Tier 1 section was moved to references/, restore it immediately and re-split targeting only Tier 2 sections.
 
-After any split (selective or full), verify that context snippet section anchors (`#quick-start`, `#key-types`) still resolve to headings in SKILL.md.
+**Anchor validation and remediation:** After any split, verify that context-snippet section anchors (`#quick-start`, `#key-types`) still resolve to headings in SKILL.md. If an anchor no longer resolves (section was split out), restore that section to SKILL.md inline content — the context-snippet must always reference sections that exist in the main file.
 
 Then re-validate: `npx skill-check check <staging-skill-dir> --format json --no-security-scan`
 

package/src/workflows/test-skill/data/source-access-protocol.md

@@ -21,9 +21,15 @@ Before analysis, determine source access level. Walk through these states in ord
 Check if `{source_path}` (from metadata.json `source_root`) exists on disk. If yes → full analysis at detected tier (AST + signatures). Set `analysis_confidence: full`.
 
 **State 2 — Local absent, provenance-map exists:**
-Check `{forge_data_folder}/{skill_name}/provenance-map.json`. If present, use it as the baseline export inventory — each entry contains structured fields: `export_name`, `export_type`, `params[]`, `return_type`, `source_file`, `source_line`, `confidence`, and `ast_node_type`. Cross-reference against SKILL.md documented exports for name-matching and param-by-param coverage. Signature verification compares SKILL.md's documented params/return types against provenance-map entries directly. If remote reading tools are available (zread, deepwiki, gh API, or similar), supplement by reading the entry point file for live signature verification. Set `analysis_confidence: provenance-map`.
+Check `{forge_data_folder}/{skill_name}/provenance-map.json`. If present AND contains at least 1 entry, use it as the baseline export inventory — each entry contains structured fields: `export_name`, `export_type`, `params[]`, `return_type`, `source_file`, `source_line`, `confidence`, and `ast_node_type`. Cross-reference against SKILL.md documented exports for name-matching and param-by-param coverage. Signature verification compares SKILL.md's documented params/return types against provenance-map entries directly.
 
-**State 2 limitations:** Signature verification at State 2 is **string comparison only**, not semantic. Provenance-map stores parameters as flat string arrays (e.g., `["data: Union[BinaryIO, list, str]"]`), so `str` vs `String` or `list` vs `List[Any]` would be treated as mismatches even when semantically equivalent. For full type-aware verification (handling type aliases, generic equivalence), State 1 (local source) with AST re-parsing is required. When the SKILL.md was compiled from the same provenance-map (typical for create-then-test flows), strings match exactly and this limitation has no practical effect.
+**Cross-reference with metadata.json:** After loading provenance-map entries, compare the entry count against `metadata.json`'s `exports[]` array length and `stats.exports_public_api` count. If metadata reports more exports than provenance-map entries:
+- Compute `gap = metadata.exports.length - provenance_map.entries.length`
+- Report: "Provenance-map contains {pmap_count} entries but metadata.json lists {meta_count} exports ({gap} gap). Coverage denominator uses the union."
+- Build the coverage denominator from the **union** of provenance-map entry names and metadata.json `exports[]` names. Exports present in metadata but absent from provenance-map are counted as "missing documentation" in the coverage calculation.
+- If metadata.json is unavailable or has no `exports[]` array, use provenance-map count alone with a note: "Coverage denominator is provenance-map only — may undercount if extraction was incomplete." If remote reading tools are available (zread, deepwiki, gh API, or similar), supplement by reading the entry point file for live signature verification. Set `analysis_confidence: provenance-map`.
+
+**State 2 limitations:** Signature verification at State 2 is **string comparison only**, not semantic. Provenance-map stores parameters as flat string arrays (e.g., `["data: Union[BinaryIO, list, str]"]`), so `str` vs `String` or `list` vs `List[Any]` would be treated as mismatches even when semantically equivalent. For full type-aware verification (handling type aliases, generic equivalence), State 1 (local source) with AST re-parsing is required. When the SKILL.md was compiled from the same provenance-map (typical for create-then-test flows), most strings will match. However, enrichment (step-04) and doc-fetching (step-03c) during compilation may alter parameter descriptions, add type annotations, or normalize signatures, causing mismatches even in create-then-test flows. Expect some string-level mismatches and treat them as compilation artifacts, not source drift signals, until signature fidelity is enforced by step-05's Signature Fidelity Rule (see `signature_source` field in provenance-map entries).
 
 **State 3 — No provenance-map, metadata exports exist (quick-skill path):**
 If no provenance-map.json exists (typical for quick-skill output), fall back to `metadata.json`'s `exports[]` array for the export name list. Coverage check becomes a self-consistency comparison: are all names in `exports[]` documented in SKILL.md with description, parameters, and return type? Signatures cannot be verified. If remote reading tools are available, supplement by reading the entry point for live export comparison. Set `analysis_confidence: metadata-only`.

package/src/workflows/test-skill/steps-c/step-03-coverage-check.md

@@ -185,6 +185,8 @@ Load `{scoringRulesFile}` to determine category scores:
 - **Signature Accuracy:** (matching_signatures / total_documented) * 100 (Forge/Deep only, "N/A" for Quick)
 - **Type Coverage:** (documented_types / total_types) * 100 (Forge/Deep only, "N/A" for Quick)
 
+**State 2 denominator validation:** When using provenance-map as the baseline (State 2), cross-reference the provenance-map entry count against `metadata.json`'s `exports[]` array before computing Export Coverage. If they diverge, use the union as the denominator per the source-access-protocol rules. Log the gap size if any.
+
 ### 5. Append Coverage Analysis to Output
 
 Append the **Coverage Analysis** section to `{outputFile}`: