bmad-module-skill-forge 0.7.2 → 0.7.4

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.4",
   "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/ccc-bridge.md

@@ -77,6 +77,36 @@ The ccc search is invisible in the output artifact. A Forge+ skill's citations a
 - A stale index still produces useful results — the workflow proceeds with the stale index and notes the staleness
 - setup-forge is the designated refresh authority
 
+### Exclusion Patterns
+
+CCC stores its configuration at `{project-root}/.cocoindex_code/settings.yml`. This file contains `exclude_patterns` and `include_patterns` arrays in glob format. `ccc init` creates the file with sensible defaults (excludes `node_modules`, `__pycache__`, hidden dirs, etc.).
+
+**SKF infrastructure exclusions:** setup-forge step-01b appends SKF-specific exclusion patterns after `ccc init` creates the default config. These patterns prevent indexing of framework and output directories that have zero value for source extraction:
+
+| Pattern | Purpose |
+|---------|---------|
+| `**/_bmad` | SKF framework module (workflow instructions, agents, knowledge) |
+| `**/_bmad-output` | Build output artifacts (TODO files, reports) |
+| `**/.claude` | Claude Code configuration |
+| `**/_skf-learn` | SKF learning materials |
+| `**/{skills_output_folder}` | Generated skill files (from manifest, default: `skills`) |
+| `**/{forge_data_folder}` | Compilation workspace (from manifest, default: `forge-data`) |
+
+The `skills_output_folder` and `forge_data_folder` values are read from `_bmad/_config/skf-manifest.yaml` when available, falling back to the defaults `skills` and `forge-data`. Patterns are appended only if not already present — user customizations to `settings.yml` are preserved.
+
+The configured exclusion patterns are stored in `ccc_index.exclude_patterns` in forge-tier.yaml for reference.
+
+### Deferred Discovery (Remote Sources)
+
+For remote repository sources (GitHub URLs), CCC cannot operate during step-02b because no local code exists yet. The ephemeral clone happens in step-03. To provide CCC pre-ranking for remote sources:
+
+1. **step-02b:** Detects remote source, sets `{ccc_discovery: []}`, displays deferred message
+2. **step-03:** After ephemeral clone succeeds, detects the deferred scenario (`tools.ccc == true AND {ccc_discovery} is empty AND ephemeral_clone_active == true AND tier is Forge+/Deep`)
+3. **step-03:** Runs `ccc init {temp_path}` + `ccc index` on the ephemeral clone (extended timeout or background mode, verified via `ccc status`)
+4. **step-03:** Executes CCC search and populates `{ccc_discovery}` before AST extraction begins
+
+The ephemeral clone index is not registered in `ccc_index_registry` — the clone is deleted after extraction and the CCC daemon's own GC handles orphaned indexes.
+
 ### Relationship to QMD Registry
 
 ccc_index and qmd_collections are **orthogonal**:
@@ -100,6 +130,8 @@ To prevent excessive daemon calls, workflow steps cap ccc queries:
 - Running ccc_bridge.ensure_index() without checking ccc_index.status first — unnecessary re-indexing
 - Passing ccc results directly to the extraction inventory — they are candidates, not extractions
 - Listing ccc as "unavailable" in reports for Quick/Forge tiers — ccc is a Forge+ capability, not something Quick/Forge tiers are missing
+- Indexing without configuring SKF exclusions — framework and output directories pollute search results
+- Skipping CCC discovery for remote sources without deferring to step-03 — remote repos deserve the same pre-ranking as local sources
 
 ## Related Fragments
 

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 discovery will run automatically during create-skill after the source is cloned."
+
 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
 
@@ -65,7 +65,11 @@ Set `{ccc_discovery: []}` in context. Auto-proceed silently. Display no message.
 
 Check `tools.ccc` from forge-tier.yaml. If `tools.ccc` is false, set `{ccc_discovery: []}` in context and auto-proceed to section 5.
 
-If `tools.ccc` is true, continue to section 2.
+If `tools.ccc` is true, check the remote source guard **before** proceeding 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 yet. Set `{ccc_discovery: []}` and display: "CCC discovery deferred — remote source will be indexed after ephemeral clone in step-03." Auto-proceed to section 5 (step completion). Step-03 will detect the deferred scenario and run CCC discovery on the ephemeral clone before AST extraction begins.
+
+If `source_root` is a local path, continue to section 2.
 
 ### 2. Check CCC Index State
 

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

@@ -96,9 +96,30 @@ Load `{sourceResolutionData}` completely. Follow the **Remote Source Resolution*
 
 **Forge/Forge+/Deep Tier (AST available):**
 
+**Deferred CCC Discovery (Forge+ and Deep — remote sources only):**
+
+If ALL of these conditions are true:
+- `tools.ccc` is true in forge-tier.yaml
+- `{ccc_discovery}` is empty (step-02b deferred because source was remote)
+- `ephemeral_clone_active` is true (clone succeeded in source resolution above)
+- Tier is Forge+ or Deep
+
+Then run CCC indexing and discovery on the ephemeral clone:
+
+1. **Index the clone:** Run `ccc init {temp_path}` then `ccc index` with an extended timeout or in background mode — indexing can take several minutes on large codebases (1000+ files). Use `ccc status` to verify completion — check that `Chunks` and `Files` counts are non-zero. If init fails or indexing fails, set `{ccc_discovery: []}` and continue — this is not an error.
+
+2. **Construct semantic query:** Build from brief data: `"{brief.name} {brief.scope}"`. Truncate to 80 characters — keep the full skill name and trim `brief.scope` from the end. If `brief.scope` is very short (< 10 chars), append terms from `brief.description` to fill the remaining space.
+
+3. **Execute search:** Run `ccc_bridge.search(query, temp_path, top_k=20)`:
+   - **Tool resolution:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search "{query}" --path {temp_path} --top 20` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
+4. **Store results:** If search succeeds, store as `{ccc_discovery: [{file, score, snippet}]}`. Display: "**CCC semantic discovery (post-clone): {N} relevant regions identified across {M} unique files.**"
+
+5. **On failure:** Set `{ccc_discovery: []}`. Display: "CCC post-clone discovery unavailable — proceeding with standard extraction." Do NOT halt.
+
 **CCC Discovery Integration (Forge+ and Deep with ccc only):**
 
-If `{ccc_discovery}` is in context and non-empty (populated by step-02b):
+If `{ccc_discovery}` is in context and non-empty (populated by step-02b or deferred discovery above):
 - Sort the filtered file list by CCC relevance score: files appearing in `{ccc_discovery}` results move to the front of the extraction queue, sorted by their relevance score descending
 - Files NOT in CCC results remain in the queue after ranked files — they are not excluded, only deprioritized
 - Display: "**CCC discovery: {N} files pre-ranked by semantic relevance** — extraction will prioritize these first."

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/setup-forge/steps-c/step-01b-ccc-index.md

@@ -9,7 +9,7 @@ nextStepFile: './step-02-write-config.md'
 
 ## STEP GOAL:
 
-If ccc is available (`{ccc: true}` from step-01), verify that the ccc index exists for the project root. If no index exists, create it. Store index state in context for step-02 to write into forge-tier.yaml.
+If ccc is available (`{ccc: true}` from step-01), configure CCC exclusion patterns for SKF infrastructure directories, verify that the ccc index exists for the project root, and create or refresh it if needed. Store index state and exclusion patterns in context for step-02 to write into forge-tier.yaml.
 
 For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed.
 
@@ -32,7 +32,7 @@ For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed
 - 🎯 Focus only on ccc index verification and creation
 - 🚫 FORBIDDEN to display skip messages for Quick/Forge tiers
 - 🚫 FORBIDDEN to fail the workflow if ccc indexing fails
-- 🚫 FORBIDDEN to re-index if ccc index already exists and is fresh (< staleness threshold)
+- 🚫 FORBIDDEN to re-index if ccc index already exists and is fresh (< staleness threshold) UNLESS new exclusion patterns were applied to settings.yml
 
 ## EXECUTION PROTOCOLS:
 
@@ -56,7 +56,7 @@ For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed
 
 Read `{ccc}` from step-01 context.
 
-**If `{ccc}` is false:** Set `{ccc_index_result: "none", ccc_indexed_path: null, ccc_last_indexed: null}`. Proceed directly to section 4 (Auto-Proceed) — no output, no messaging.
+**If `{ccc}` is false:** Set `{ccc_index_result: "none", ccc_indexed_path: null, ccc_last_indexed: null, ccc_exclude_patterns: []}`. Proceed directly to section 4 (Auto-Proceed) — no output, no messaging.
 
 **If `{ccc}` is true:** Continue to section 2.
 
@@ -64,17 +64,58 @@ Read `{ccc}` from step-01 context.
 
 Read existing forge-tier.yaml at `{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml` (if it exists from a previous run).
 
+Read `staleness_threshold_hours` from `ccc_index.staleness_threshold_hours` in the existing forge-tier.yaml (default: 24 if not present or not a number). Use this value for the freshness check below.
+
 Check the `ccc_index` section:
-- If `ccc_index.indexed_path` matches `{project-root}` AND `ccc_index.status` is `"fresh"`:
-  - Check freshness: if `ccc_index.last_indexed` is within `staleness_threshold_hours` (default 24h) of now → index is fresh
+- If `ccc_index.indexed_path` matches `{project-root}` AND `ccc_index.status` is `"fresh"` or `"created"`:
+  - Check freshness: if `ccc_index.last_indexed` is within `staleness_threshold_hours` of now → index is fresh
   - Store `{ccc_index_result: "fresh", ccc_indexed_path: {project-root}, ccc_last_indexed: {existing timestamp}}`
-  - Proceed to section 4
+  - Set `{needs_reindex: false}` — proceed to section 2b (exclusions must still be configured)
 
 - If `ccc_index.indexed_path` matches `{project-root}` but timestamp is older than threshold:
-  - Note index is stale — proceed to section 3 for re-index (section 3 will overwrite `ccc_index_result` to `"created"` or `"failed"`)
+  - Set `{needs_reindex: true}` — proceed to section 2b then section 3
 
 - If `ccc_index` is missing, has null values, or path doesn't match:
-  - Proceed to section 3 for initial index
+  - Set `{needs_reindex: true}` — proceed to section 2b then section 3
+
+### 2b. Configure CCC Exclusions
+
+SKF infrastructure and output directories must be excluded from the CCC index — they contain workflow instructions, build artifacts, and generated skills that pollute semantic search results with zero extraction value.
+
+**Build the SKF exclusion list:**
+
+1. Read `{project-root}/_bmad/_config/skf-manifest.yaml` to resolve configurable paths:
+   - `skills_output_folder` (default: `skills` if manifest is missing or field is absent)
+   - `forge_data_folder` (default: `forge-data` if manifest is missing or field is absent)
+
+2. Assemble the exclusion patterns using `**/` prefix format (matching `.cocoindex_code/settings.yml` convention — e.g., `**/node_modules`):
+   - `**/_bmad` — SKF framework module (workflows, agents, knowledge files)
+   - `**/_bmad-output` — Build output artifacts
+   - `**/.claude` — Claude Code configuration
+   - `**/_skf-learn` — SKF learning materials
+   - `**/{skills_output_folder}` — Generated skill files (resolved from manifest)
+   - `**/{forge_data_folder}` — Compilation workspace (resolved from manifest)
+
+3. Store `{ccc_exclude_patterns}` in context for step-02 to write into forge-tier.yaml.
+
+**Apply exclusions to settings.yml:**
+
+Check if `{project-root}/.cocoindex_code/settings.yml` exists. Set `{settings_yml_existed: true}` if it does, `{settings_yml_existed: false}` if not.
+
+If `{settings_yml_existed}` is true (from a previous `ccc init` run):
+
+1. Read `settings.yml`
+2. For each pattern in `{ccc_exclude_patterns}`: if the pattern is NOT already present in `exclude_patterns`, append it and set `{exclusions_changed: true}`
+3. If `{exclusions_changed}`: write the updated `settings.yml` back, set `{needs_reindex: true}` (new exclusions require re-indexing), display: "**CCC exclusions configured:** {count} SKF patterns applied to .cocoindex_code/settings.yml"
+4. If no new patterns needed: display nothing (exclusions already configured)
+
+This preserves any existing user customizations and default exclusions while ensuring SKF directories are filtered out.
+
+If `{settings_yml_existed}` is false: the exclusions will be applied after `ccc init` in section 3.
+
+**Flow decision:**
+- If `{needs_reindex}` is true: proceed to section 3
+- If `{needs_reindex}` is false: proceed to section 4 (Auto-Proceed)
 
 ### 3. Create or Refresh CCC Index
 
@@ -93,6 +134,15 @@ ccc init
 
 **If init fails** (project may already be initialized): continue — this is not an error.
 
+**Apply SKF exclusion patterns (if not already applied in section 2b):**
+
+If `{settings_yml_existed}` is false (first-time setup — `ccc init` just created it), apply exclusions now:
+
+1. Read `{project-root}/.cocoindex_code/settings.yml` (created by `ccc init`)
+2. For each pattern in `{ccc_exclude_patterns}`: if the pattern is NOT already present in `exclude_patterns`, append it
+3. Write the updated `settings.yml` back
+4. Display: "**CCC exclusions configured:** {count} SKF patterns applied to .cocoindex_code/settings.yml"
+
 Then run:
 ```bash
 ccc index
@@ -102,8 +152,8 @@ ccc index
 
 **If succeeds:**
 - Run `ccc status` to get file count
-- Store `{ccc_index_result: "created", ccc_indexed_path: {project-root}, ccc_last_indexed: {current ISO timestamp}, ccc_file_count: {count from status}}`
-- Display: "**CCC index created.** {file_count} files indexed for semantic discovery."
+- Store `{ccc_index_result: "created", ccc_indexed_path: {project-root}, ccc_last_indexed: {current ISO timestamp}, ccc_file_count: {count from ccc status}}`
+- Display: "**CCC index created.** {ccc_file_count} files indexed for semantic discovery."
 
 **If fails:**
 - Store `{ccc_index_result: "failed", ccc_indexed_path: null, ccc_last_indexed: null}`
@@ -134,8 +184,8 @@ ONLY WHEN ccc index verification is complete (or step is skipped for ccc unavail
 ### ✅ SUCCESS:
 
 - ccc unavailable: skipped silently with no output, context variables set to null/none
-- ccc available with fresh index: verified freshness, skipped re-index, context variables set
-- ccc available with stale/missing index: index created, context variables set with fresh timestamp
+- ccc available with fresh index: verified freshness, exclusions configured, skipped re-index, context variables set
+- ccc available with stale/missing index: exclusions configured, index created, context variables set with fresh timestamp
 - ccc indexing fails: logged gracefully, workflow continues, context variables set to failed/null
 - Auto-proceeded to step-02
 
@@ -143,8 +193,10 @@ ONLY WHEN ccc index verification is complete (or step is skipped for ccc unavail
 
 - Displaying skip messages when ccc is unavailable
 - Halting the workflow on ccc index failure
-- Re-indexing when index is already fresh and path matches
+- Re-indexing when index is already fresh and path matches (unless exclusion patterns changed)
 - Writing forge-tier.yaml (that is step-02's responsibility)
 - Not storing ccc index context variables for step-02
+- Indexing without configuring SKF exclusion patterns in `.cocoindex_code/settings.yml`
+- Overwriting user customizations in `.cocoindex_code/settings.yml` instead of appending
 
 **Master Rule:** CCC indexing is always best-effort. Failures degrade gracefully. The workflow never halts over ccc issues.

package/src/workflows/setup-forge/steps-c/step-02-write-config.md

@@ -41,7 +41,7 @@ Write the detected tool availability and calculated tier to forge-tier.yaml, cre
 
 ## CONTEXT BOUNDARIES:
 
-- Available: {detected_tools}, {calculated_tier}, {previous_tier} from step-01; {ccc_index_result}, {ccc_indexed_path}, {ccc_last_indexed} from step-01b
+- Available: {detected_tools}, {calculated_tier}, {previous_tier} from step-01; {ccc_index_result}, {ccc_indexed_path}, {ccc_last_indexed}, {ccc_file_count}, {ccc_exclude_patterns} from step-01b
 - Focus: file I/O operations only
 - Limits: do not modify preferences.yaml if it exists
 - Dependencies: step-01 and step-01b must have completed with tool detection and CCC index results
@@ -78,6 +78,8 @@ ccc_index:
   last_indexed: {ccc_last_indexed from step-01b, or ~}
   status: {ccc_index_result from step-01b: "fresh"|"created"|"none"|"failed"}
   staleness_threshold_hours: 24
+  file_count: {ccc_file_count from step-01b, or ~}
+  exclude_patterns: {ccc_exclude_patterns from step-01b, or []}
 
 # CCC index registry (tracks which source paths have been indexed for skill workflows)
 # PRESERVE existing entries on re-runs — see Note below
@@ -88,7 +90,7 @@ ccc_index_registry: {preserved from existing forge-tier.yaml, or [] if first run
 qmd_collections: {preserved from existing forge-tier.yaml, or [] if first run}
 ```
 
-**Note on re-runs:** The `qmd_collections`, `ccc_index_registry` arrays, and `staleness_threshold_hours` value must be preserved across re-runs. Before overwriting forge-tier.yaml, read these existing values and re-inject them into the new write. These values are populated by create-skill workflows or customized by users and must not be reset.
+**Note on re-runs:** The `qmd_collections`, `ccc_index_registry` arrays, and `staleness_threshold_hours` value must be preserved across re-runs. Before overwriting forge-tier.yaml, read these existing values and re-inject them into the new write. These values are populated by create-skill workflows or customized by users and must not be reset. Note: `exclude_patterns` is NOT preserved — it is always written fresh from `{ccc_exclude_patterns}` computed by step-01b.
 
 **This file is ALWAYS overwritten** on every run — it reflects current tool state.
 
@@ -150,7 +152,7 @@ ONLY WHEN forge-tier.yaml has been written successfully and preferences.yaml exi
 
 ### ✅ SUCCESS:
 
-- forge-tier.yaml written with accurate tool booleans (including ccc), tier, timestamp, ccc_index state, and preserved qmd_collections/ccc_index_registry arrays
+- forge-tier.yaml written with accurate tool booleans (including ccc), tier, timestamp, ccc_index state (including exclude_patterns), and preserved qmd_collections/ccc_index_registry arrays
 - preferences.yaml exists (created with defaults on first run, preserved on re-run)
 - forge-data/ directory exists (created or pre-existing)
 - Auto-proceeded to step-03

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}`:

package/src/workflows/update-skill/steps-c/step-03-re-extract.md

@@ -139,6 +139,8 @@ This helps the merge step (section 4) prioritize which changes are most likely t
 
 CCC failures: skip ranking silently, all changes treated equally.
 
+**Note on remote sources:** If `source_root` is an ephemeral clone (remote source), the clone path is not indexed by CCC. The search will return empty results and semantic ranking will be skipped. This is expected — deferred CCC indexing is implemented in create-skill step-03 but not in update-skill. All changes are treated equally for remote sources.
+
 **IF `tools.ccc` is false:** Skip this section silently.
 
 ### 3. Deep Tier QMD Enrichment (Conditional)