bmad-module-skill-forge 0.7.1 → 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.1",
+  "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

@@ -40,8 +40,13 @@ qmd_collections:
     source_workflow: "brief-skill"
     skill_name: "my-lib"
     created_at: "2026-03-14"
+    # status: "pending"    # Optional — see below
 ```
 
+**Optional field: `status`**
+
+The `status` field is only present when QMD embed verification fails during collection creation. When `status: "pending"` is set, the collection exists in QMD but vector embeddings may be incomplete — only BM25 keyword `search` is reliable. `vector_search` and `deep_search` may return no results until re-embedded. Collections without a `status` field are fully operational. The setup-forge janitor should flag `"pending"` collections for re-embedding.
+
 ### Collection Types
 
 | Type | Producer | Content | Primary Consumers |
@@ -122,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
@@ -106,6 +108,21 @@ Scope: {scope.type}
   Exclude: {scope.exclude patterns, one per line}
   Notes:   {scope.notes}
 
+{If source_type is "docs-only":}
+Source Type: docs-only
+Doc URLs:
+  {doc_urls, one per line with labels}
+
+{If source_type is "source" AND supplemental doc_urls collected:}
+Supplemental Docs:
+  {doc_urls, one per line with labels}
+
+{If scripts_intent or assets_intent was explicitly set (not default "detect"):}
+Scripts:    {scripts_intent}
+Assets:     {assets_intent}
+
+Source Authority: {source_authority}
+
 Version:    {version}
 Created:    {created}
 Created by: {created_by}

package/src/workflows/brief-skill/steps-c/step-01-gather-intent.md

@@ -82,6 +82,9 @@ We'll work through this together:
 3. **Then:** Define scope boundaries
 4. **Finally:** Confirm and write the brief
 
+{If tier override was applied:}
+**Your forge tier:** {override tier} (overridden from {original tier}) — this determines what compilation capabilities are available.
+{Else:}
 **Your forge tier:** {detected tier} — this determines what compilation capabilities are available.
 
 Let's get started."
@@ -110,6 +113,14 @@ Wait for user response.
 - Optionally ask: "Are there any documentation URLs you'd like to include for supplemental context? (These will be fetched as T3 external references.)"
 - If yes: collect doc URLs into `doc_urls`
 
+**Source authority (for all source-type skills):**
+"**Are you the maintainer of this library, or creating a community skill?**"
+- If maintainer: set `source_authority: "official"`
+- If community user: set `source_authority: "community"` (default)
+- If internal/proprietary: set `source_authority: "internal"`
+
+Default to `"community"` if user does not specify or skips. For `docs-only` skills, `source_authority` is always forced to `"community"`.
+
 Confirm the target.
 
 ### 4. Gather User Intent
@@ -154,6 +165,10 @@ Wait for confirmation or alternative.
 - **Intent:** {user's intent summary}
 - **Scope hints:** {any hints, or "None — we'll define scope after analysis"}
 - **Skill name:** {confirmed name}
+- **Source type:** {source or docs-only}
+- **Source authority:** {official/community/internal}
+{If doc_urls collected:}
+- **Doc URLs:** {count} supplemental documentation URLs
 - **Forge tier:** {tier}
 
 Ready to analyze the target repository?"
@@ -187,6 +202,7 @@ ONLY WHEN C is selected and target repository is confirmed will you load and rea
 - User intent captured with enough context for scoping
 - Skill name derived and confirmed
 - Scope hints noted (if provided)
+- Source type and source authority captured
 - User ready to proceed to analysis
 
 ### ❌ SYSTEM FAILURE:

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,9 +139,16 @@ 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:
 
-Run `ccc_bridge.search("{repo_name} public API exports modules", source_path, top_k=10)` — **Tool resolution:** `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search` CLI. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+**CCC Semantic Discovery:**
+- **Claude Code:** Use `/ccc search "{repo_name} public API exports modules" {source_path}`
+- **Cursor:** Use `ccc` MCP server `search` tool with query `"{repo_name} public API exports modules"` and path `{source_path}`
+- **CLI fallback:** `ccc search "{repo_name} public API exports modules" --path {source_path} --limit 10`
+
+See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md) for full bridge-to-tool mapping.
 
 If results are returned, display:
 
@@ -146,6 +159,22 @@ This supplements — never replaces — the explicit module list above. CCC may
 
 If CCC is unavailable or returns no results: skip this subsection silently.
 
+### 4b. Detect Source Version
+
+Attempt to auto-detect the source version using the rules from the skill-brief-schema.md Version Detection section:
+
+**For Python:** Check `pyproject.toml` `[project] version` (static) → if `dynamic = ["version"]`, check `__init__.py` for `__version__` → `_version.py` if exists → `setup.py` `version=` → `git describe --tags --abbrev=0`
+**For JavaScript/TypeScript:** Check `package.json` `"version"` field
+**For Rust:** Check `Cargo.toml` `[package] version` (static) → if `version = { workspace = true }`, resolve from workspace root `Cargo.toml` → `git describe --tags --abbrev=0`
+**For Go:** Check `go.mod` or `git describe --tags --abbrev=0`
+
+**For GitHub repos:** Use `gh api repos/{owner}/{repo}/contents/{file}` to read version files (decode base64 content).
+**For local repos:** Read the file directly.
+
+Display: "**Detected version:** {version or 'Not detected — will default to 1.0.0'}"
+
+If detection fails or returns a non-semver value: note that version will default to `"1.0.0"` and the user can override in step 04.
+
 ### 5. Report Analysis Summary
 
 Present the complete analysis:
@@ -169,6 +198,7 @@ Present the complete analysis:
 - Tests: {found/not found — location}
 - Docs: {found/not found — location}
 - Config: {list of config files found}
+- Version: {detected version or "Not detected — defaulting to 1.0.0"}
 
 ---
 
@@ -179,16 +209,21 @@ Moving to scope definition where you'll choose what to include and exclude."
 
 ### 6. Auto-Proceed to Scope Definition
 
-Display: "**Proceeding to scope definition...**"
+Display: "**Proceeding to scope definition...**
+
+Review the analysis above. If anything looks wrong, let me know now — otherwise I'll proceed to scope definition."
+
+Pause briefly for user input. If the user provides corrections or asks questions, address them and re-present any updated analysis findings. Then proceed.
 
 #### Menu Handling Logic:
 
-- After analysis report is presented to user, immediately load, read entire file, then execute {nextStepFile}
+- After analysis report is presented to user and any corrections addressed, load, read entire file, then execute {nextStepFile}
 
 #### EXECUTION RULES:
 
-- This is an auto-proceed step — analysis is factual reporting with no user choices
-- Proceed directly to step 03 after presenting the analysis summary
+- This is a soft auto-proceed step — present the pause prompt, wait briefly for user input
+- If user provides corrections: address them, then proceed
+- If no user input after a brief pause: proceed directly to step 03
 
 ## CRITICAL STEP COMPLETION NOTE
 
@@ -204,8 +239,9 @@ ONLY WHEN the analysis is complete and the summary has been presented to the use
 - Repository structure listed clearly
 - Primary language detected with confidence level
 - Top-level modules and exports identified
+- Source version detected (or default noted)
 - Analysis summary presented factually
-- Auto-proceeded to scope definition
+- Auto-proceeded to scope definition (with pause for corrections)
 
 ### ❌ SYSTEM FAILURE:
 

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,21 @@ Wait for confirmation. Then skip to section 5 (Summarize Scope Decisions) with:
 
 **If `source_type: "source"` (default):** Continue to scope templates below.
 
-### 2b. Offer Scope Templates
+### 2b. Confirm Supplemental Documentation (if doc_urls collected)
+
+**If `source_type: "source"` AND supplemental `doc_urls` were collected in step 01:**
+
+"**Supplemental documentation URLs:**
+{numbered list of collected doc_urls with labels}
+
+These will be included as T3 external references in the skill brief.
+Add, remove, or confirm these URLs."
+
+Wait for confirmation. Record any changes to `doc_urls`.
+
+**If no supplemental doc_urls were collected:** Skip this subsection.
+
+### 2c. Offer Scope Templates
 
 Load `{scopeTemplatesFile}` for the scope type options ([F], [M], [P]) and their descriptions.
 
@@ -153,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
@@ -78,6 +78,11 @@ Compile all gathered data from steps 01-03 into the complete brief:
 - **scope.include:** {include patterns from step 03}
 - **scope.exclude:** {exclude patterns from step 03}
 - **scope.notes:** {any scope notes from step 03}
+- **source_type:** {source or docs-only, from step 01}
+- **doc_urls:** {collected documentation URLs with labels, from steps 01/03 — include if source_type is "docs-only" or supplemental URLs were collected}
+- **scripts_intent:** {detect/none/description from step 03, or "detect" if not explicitly set}
+- **assets_intent:** {detect/none/description from step 03, or "detect" if not explicitly set}
+- **source_authority:** {official/community/internal from step 01 — default "community"}
 
 ### 3. Present Brief for Review
 
@@ -101,6 +106,21 @@ Scope: {scope.type}
   Exclude: {scope.exclude patterns, one per line}
   Notes:   {scope.notes}
 
+{If source_type is "docs-only":}
+Source Type: docs-only
+Doc URLs:
+  {doc_urls, one per line with labels}
+
+{If source_type is "source" AND supplemental doc_urls collected:}
+Supplemental Docs:
+  {doc_urls, one per line with labels}
+
+{If scripts_intent or assets_intent was explicitly set (not default "detect"):}
+Scripts:    {scripts_intent}
+Assets:     {assets_intent}
+
+Source Authority: {source_authority}
+
 Version:    {version}
 Created:    {created}
 Created by: {created_by}
@@ -145,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/brief-skill/steps-c/step-05-write-brief.md

@@ -87,19 +87,36 @@ scope:
   exclude:
     - "{approved exclude patterns}"
   notes: "{approved scope notes or empty string}"
-# Include doc_urls when source_type is "docs-only" or when supplemental doc URLs were provided
-# doc_urls:
-#   - url: "{documentation URL}"
-#     label: "{page label}"
-# scripts_intent: detect         # Optional: detect | none | description of expected scripts
-# assets_intent: detect          # Optional: detect | none | description of expected assets
-# source_authority: community    # Optional: official | community | internal
 ---
 ```
 
-**If `source_type: "docs-only"`:** Include `doc_urls` array (required). `source_repo` may be set to the doc site URL for reference or omitted. `source_authority` must be `community`.
+**Conditional optional field inclusion:**
 
-**If `doc_urls` were collected during scope definition (supplemental mode):** Include the `doc_urls` array even when `source_type: "source"`.
+**If `source_type: "docs-only"` OR supplemental `doc_urls` were collected:**
+Include the `doc_urls` array (uncommented) in the generated YAML:
+```yaml
+doc_urls:
+  - url: "{documentation URL}"
+    label: "{page label}"
+```
+When `source_type: "docs-only"`: `doc_urls` is required (at least one entry), `source_repo` may be set to the doc site URL for reference or omitted.
+
+**If `scripts_intent` was collected and is not the default `"detect"`:**
+Include the `scripts_intent` field (uncommented):
+```yaml
+scripts_intent: "{none or description}"
+```
+
+**If `assets_intent` was collected and is not the default `"detect"`:**
+Include the `assets_intent` field (uncommented):
+```yaml
+assets_intent: "{none or description}"
+```
+
+**Always include** `source_authority` (default: `"community"`, forced to `"community"` when `source_type: "docs-only"`):
+```yaml
+source_authority: "{official|community|internal}"
+```
 
 ### 4. Write the File
 
@@ -128,6 +145,13 @@ qmd collection add {forge_data_folder}/{skill-name} --name {skill-name}-brief --
 qmd embed
 ```
 
+**Embed verification:**
+
+After `qmd embed` completes, verify the collection was embedded:
+- Run `qmd status` or `qmd collection list` and confirm `{skill-name}-brief` shows document count > 0
+- If verification succeeds: proceed to registry update normally
+- If verification fails: log warning "QMD embed verification failed for {skill-name}-brief — collection may not be searchable yet", still proceed to registry update but add `status: "pending"` field to the registry entry
+
 **Registry update:**
 
 Read `{sidecar_path}/forge-tier.yaml` and update the `qmd_collections` array.
@@ -140,6 +164,7 @@ If an entry with `name: "{skill-name}-brief"` already exists, replace it. Otherw
     source_workflow: "brief-skill"
     skill_name: "{skill-name}"
     created_at: "{current ISO date}"
+    # status: "pending"    # Added only when embed verification fails
 ```
 
 Write the updated forge-tier.yaml.

package/src/workflows/brief-skill/workflow.md

@@ -51,7 +51,7 @@ installed_path: '{project-root}/_bmad/skf/workflows/skillforge/brief-skill'
 
 Load and read full config from {project-root}/_bmad/skf/config.yaml and resolve:
 
-- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `forge_data_folder`, `sidecar_path`
+- `project_name`, `output_folder`, `user_name`, `communication_language`, `forge_data_folder`, `sidecar_path`
 
 ### 2. First Step Execution
 

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
@@ -168,12 +168,19 @@ find_code_by_rule(
 
 When MCP tools are unavailable or the repo exceeds 500 files in scope, use `--json=stream` (NEVER `--json` or `--json=pretty`) with line-by-line Python processing:
 
+**Head cap selection:** The `| head -N` cap at the end of the pipeline controls how many exports are captured. Select `N` based on scope and tier:
+- **Default (Quick/Forge, any scope):** `N = 200`
+- **Forge+/Deep with `scope.type: "full-library"`:** `N = 500`
+
+For full-library skills at higher tiers, the larger cap prevents silently dropping internal module exports that maintainers need. The cap is applied AFTER exclude-pattern filtering, so useful results are not wasted on excluded files.
+
 ```bash
 # Note: use $$$ for variadic params in ast-grep patterns (e.g., 'def $NAME($$$PARAMS)')
 # {exclude_patterns} = Python list from brief's scope.exclude, e.g. ['tests/**', '**/test_*']
 # If scope.exclude is absent or empty in the brief, inject [] as the default.
 # Patterns are matched against the full file path as emitted by ast-grep.
 # Ensure paths are relative to the same root as the patterns (strip ./ prefix if needed).
+# {HEAD_CAP} = 200 (default) or 500 (Forge+/Deep full-library) — see head cap selection above.
 ast-grep -p '{pattern}' -l {language} --json=stream {path} | python3 -c "
 import sys, json, fnmatch, signal
 signal.signal(signal.SIGPIPE, signal.SIG_DFL)
@@ -193,7 +200,7 @@ for line in sys.stdin:
             sig = m.get('text','').split(chr(10))[0].strip()
             print(f'[AST:{f}:L{ln}] {sig}')
     except: pass
-" | head -200
+" | head -{HEAD_CAP}
 ```
 
 **Critical constraints:**
@@ -201,7 +208,7 @@ for line in sys.stdin:
 - ALWAYS use `--json=stream` — never `--json` (loads entire array into memory)
 - ALWAYS process line-by-line (`for line in sys.stdin`) — never `json.load(sys.stdin)`
 - ALWAYS cap output with `| head -N` as a safety valve
-- For repos > 500 files, process in directory batches of 20-50 files each
+- For repos > 500 files, process in directory batches of 20-50 files each: split by top-level source directory, run the CLI streaming template per batch with the same head cap, then merge results and deduplicate by export name (keep the first occurrence if duplicates exist across batches)
 
 ### YAML Rule Recipes by Language
 
@@ -253,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
@@ -270,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/data/source-resolution-protocols.md

@@ -102,7 +102,7 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
 
    After checkout, apply the original glob `include_patterns` as file-level filters when building the extraction file list — sparse-checkout gets the right directories, glob filtering narrows to the exact files. When `--no-cone` mode was used, most exclude filtering is already done at the git level, but apply `exclude_patterns` as a final pass to catch any edge cases where gitignore pattern matching diverges from the brief's glob semantics. Always-included root files (see above) are exempt from post-checkout filtering.
 
-3. **If clone succeeds:** Update the working source path to `{temp_path}` for all subsequent AST operations in this step. Proceed with the **Forge/Deep Tier** extraction strategy below. Mark `ephemeral_clone_active = true` for cleanup.
+3. **If clone succeeds:** Update the working source path to `{temp_path}` for all subsequent AST operations in this step. Capture the source commit: `git -C {temp_path} rev-parse HEAD` — store as `source_commit` in context. Proceed with the **Forge/Deep Tier** extraction strategy below. Mark `ephemeral_clone_active = true` for cleanup.
 
 4. **If clone fails (network error, auth failure, timeout):**
 
@@ -116,6 +116,20 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
 
 ---
 
+## Source Commit Capture (all tiers, source mode only)
+
+**If `source_type: "docs-only"`:** skip — set `source_commit: null`.
+
+After the source path is accessible, capture the current commit hash for provenance tracking:
+
+- **Local path:** `git -C {source_root} rev-parse HEAD` — if the path is a git repo
+- **Ephemeral clone (Forge/Deep):** already captured during clone (step 3 above)
+- **Quick tier (remote, no clone):** `gh api repos/{owner}/{repo}/commits/{branch} --jq '.sha'`
+
+Store the result as `source_commit` in context. If capture fails (not a git repo, API unavailable), set `source_commit: null` — this is not an error.
+
+---
+
 ## Version Reconciliation (all tiers, source mode only)
 
 **If `source_type: "docs-only"`:** skip this section — no source files exist to reconcile.

package/src/workflows/create-skill/steps-c/step-01-load-brief.md

@@ -111,16 +111,16 @@ Halt with specific error: "Brief validation failed: missing required field `{fie
 
 ### 4. Resolve Source Code Location
 
-**If `source_type: "docs-only"`:** Skip source resolution. Set `source_location: null` in context. Proceed directly to section 5 (Report Initialization) — docs-only skills have no source to resolve.
+**If `source_type: "docs-only"`:** Skip source resolution. Set `source_root: null` in context. Proceed directly to section 5 (Report Initialization) — docs-only skills have no source to resolve.
 
 **If source_repo is a GitHub URL or owner/repo format:**
 - Verify repository exists via `gh_bridge.list_tree(owner, repo, branch)` — **Tool resolution:** `gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1` or direct file listing if local; see [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - If branch not specified, detect default branch
-- Store resolved: owner, repo, branch, file tree
+- Store resolved: owner, repo, branch, file tree — note: `source_root` for remote repos is set to the ephemeral clone path during extraction (step-03)
 
 **If source_repo is a local path:**
 - Verify path exists and contains source files
-- Store resolved: local path, file listing
+- Store resolved: local path as `source_root`, file listing
 
 **If source cannot be resolved:**
 Halt with: "Source not found: `{source_repo}`. Verify the repository exists and is accessible."
@@ -170,7 +170,7 @@ ONLY WHEN forge-tier.yaml is loaded, skill-brief.yaml is validated, and source c
 
 - Forge tier loaded from sidecar with tool availability
 - Skill brief loaded and all required fields validated
-- Source code location resolved and accessible (or `source_location: null` confirmed for docs-only skills)
+- Source code location resolved and accessible (or `source_root: null` confirmed for docs-only skills)
 - Initialization summary displayed with tier and capabilities
 - Auto-proceeded to step-02
 

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,11 +67,13 @@ 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:
 
-- If `ccc_index.status` is `"fresh"`: continue to section 3.
+- If `ccc_index.status` is `"fresh"` or `"created"`: continue to section 3.
 - If `ccc_index.status` is `"stale"`: display brief note — "CCC index is stale — discovery results may miss recent changes." Continue to section 3.
 - If `ccc_index.status` is `"none"` or `"failed"`: attempt lazy indexing via `ccc_bridge.ensure_index(source_root)`. If indexing succeeds, continue to section 3. If indexing fails, set `{ccc_discovery: []}` and auto-proceed to section 5.
 

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

@@ -46,7 +46,7 @@ To extract all public exports, function signatures, type definitions, and co-imp
 
 ## CONTEXT BOUNDARIES:
 
-- Available: brief_data, tier, source_location, file_tree from step-01; ecosystem check outcome from step-02 (proceed/halt decision — no named variable stored)
+- Available: brief_data, tier, source_root, file_tree from step-01; ecosystem check outcome from step-02 (proceed/halt decision — no named variable stored)
 - Focus: Source code extraction and inventory building
 - Limits: Do NOT compile, assemble, or write any output
 - Dependencies: Source code must be accessible (resolved in step-01)

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

@@ -57,11 +57,26 @@ To fetch temporal context (issues, PRs, changelogs, release notes) from the sour
 Evaluate the following conditions sequentially. **If ANY condition fails, skip silently to section 5 (auto-proceed) with no output:**
 
 1. **Tier is Deep:** If tier is Quick, Forge, or Forge+, skip silently.
-2. **Source is GitHub:** Verify `source_repo` is a GitHub URL (`https://github.com/...`) or `owner/repo` format. If the source is a local path, a non-GitHub URL, or any other format, skip silently.
+2. **Source is GitHub:** Verify `source_repo` is a GitHub URL (`https://github.com/...`) or `owner/repo` format. If the source is a local path, a non-GitHub URL, or any other format, attempt GitHub remote detection (section 1b) before skipping.
 3. **`gh` CLI is available:** Run `gh auth status` to verify the CLI is installed and authenticated. If it fails, skip silently.
 
 All three conditions must pass to proceed to section 2.
 
+### 1b. GitHub Remote Detection for Local Sources
+
+**Only runs when condition 2 above fails because `source_repo` is a local path.**
+
+Local repositories that are clones of GitHub repos contain temporal context (issues, PRs, releases) accessible via `gh`. Detect this automatically:
+
+1. Check if the local path is a git repository: `git -C {source_repo} rev-parse --is-inside-work-tree`
+2. If not a git repo: skip silently to section 5 (current behavior).
+3. Extract the origin remote: `git -C {source_repo} remote get-url origin`
+4. If the remote URL contains `github.com`:
+   - Extract `owner/repo` from the remote URL (strip `.git` suffix, handle both HTTPS and SSH formats)
+   - Log: "**Local source with GitHub remote detected:** {owner}/{repo} — fetching temporal context."
+   - Use the extracted `owner/repo` for all `gh` API calls in sections 3-4. Continue to condition 3 (gh CLI check).
+5. If no remote, or remote is not GitHub: skip silently to section 5 (current behavior).
+
 ### 2. Check Cache (Skip If Fresh)
 
 Read `forge-tier.yaml` from the sidecar path.
@@ -157,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
 ```
 
@@ -178,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

@@ -85,14 +85,20 @@ Content fetched from external URLs is classified as **T3** (external, untrusted)
 
 After fetching a URL, apply the following heuristic to detect documentation root pages that contain no useful API content. This is common with modern documentation sites (Mintlify, Docusaurus, ReadTheDocs, GitBook) that render API content on subpages.
 
-**Root page detection heuristic — apply only when the URL path ends in `/`, `/index`, `/index.html`, has no path component (bare domain), or has 1 path segment (e.g., `/docs`). For deeper URL paths (2+ segments like `/api/reference`), skip this heuristic and keep the content as-is.**
+**Root page detection — apply only when the URL path ends in `/`, `/index`, `/index.html`, has no path component (bare domain), or has 1 path segment (e.g., `/docs`). For deeper URL paths (2+ segments like `/api/reference`), skip this heuristic and keep the content as-is.**
 
-**A page is classified as a root if BOTH conditions are true:**
+Subpage discovery is triggered if **either** of the following independent triggers fires:
+
+**Trigger 1 — Content-based (both conditions must be true):**
 
 1. **Zero API content indicators:** The fetched markdown contains none of: fenced code blocks (`` ``` ``), parameter tables (`|---|`), or function signature patterns (`def `, `function `, `fn `, `func `, `export `).
 2. **High link density:** More than 70% of non-empty lines are markdown links (matching `[text](url)` with no other substantive content on the line).
 
-If only one condition is true, treat the page as having partial content — keep it as-is and do NOT trigger subpage discovery.
+**Trigger 2 — URL-based (independent of content analysis):**
+
+The URL matches the path criteria above (ends in `/`, bare domain, or 1 segment) AND the fetched content is under **2000 words**. Short content on root-like URLs almost certainly indicates a navigation hub or landing page, even if it contains introductory code examples that would prevent Trigger 1 from firing. This handles modern doc sites (Mintlify, Docusaurus, GitBook) that include hero sections with code snippets on their root pages.
+
+If neither trigger fires, keep the page content as-is and do NOT trigger subpage discovery.
 
 **If a root URL with minimal content is detected:**
 
@@ -147,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:
 
@@ -159,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)
@@ -100,7 +111,12 @@ Following the structure from the skill-sections data file:
 - 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
-- Set `tool_versions` based on tier and available tools. Resolve `{skf_version}` from the installed module's `package.json` at `{project-root}/_bmad/skf/package.json`. If unresolvable there, fall back to `node -p "require('./node_modules/bmad-module-skill-forge/package.json').version"`. If still unresolvable, use `"unknown"` and add a warning to the evidence report. Never hardcode the version.
+- Set `tool_versions` based on tier and available tools. Resolve `{skf_version}` using this resolution chain (try each in order, use the first that succeeds):
+  1. `{project-root}/_bmad/skf/package.json` → read `.version` field
+  2. `node -p "require('./node_modules/bmad-module-skill-forge/package.json').version"`
+  3. `{project-root}/_bmad/skf/VERSION` → read plain text file (single line containing version string, written by the SKF installer)
+  4. `"unknown"` (final fallback — add a warning to the evidence report)
+  Never hardcode the version.
 - Store `commit_short` = first 8 characters of `source_commit` (or `"unknown"` if unavailable) for use in step-08 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.
 
@@ -116,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/create-skill/steps-c/step-07-generate-artifacts.md

@@ -43,7 +43,7 @@ To write all compiled content to disk — 4 deliverable files to `{skills_output
 
 ## CONTEXT BOUNDARIES:
 
-- Available: All compiled content from step-05, validation results from step-06
+- Available: All compiled content from step-05, validation results from step-06, source_root from step-01 (needed for section 5b CCC registration)
 - Focus: File system operations — create directories, write files
 - Limits: Do NOT modify content during writing
 - Dependencies: All content must be compiled and validated in context

package/src/workflows/quick-skill/steps-c/step-04-compile.md

@@ -145,7 +145,7 @@ Generate metadata.json following the exact structure defined in {skillTemplateDa
   "tool_versions": {
     "ast_grep": null,
     "qmd": null,
-    "skf": "{skf_version}"
+    "skf": "{skf_version}"   // Resolution chain: _bmad/skf/package.json → npm require → _bmad/skf/VERSION → "unknown"
   },
   "stats": {
     "exports_documented": "{number of exports found}",

package/src/workflows/test-skill/data/output-section-formats.md

@@ -17,6 +17,21 @@
 **Structural Issues:** {count}
 ```
 
+## Coherence Analysis — Naive Mode: Reference Consistency (split-body)
+
+Only rendered when `references/` directory exists alongside SKILL.md.
+
+```markdown
+### Reference Consistency (split-body)
+
+| # | Reference File | Export | Issue | SKILL.md Line | Reference Line |
+|---|---------------|--------|-------|---------------|---------------|
+| {per-mismatch rows} |
+
+**Exports Cross-Checked:** {count}
+**Mismatches Found:** {count}
+```
+
 ## Coherence Analysis — Contextual Mode
 
 ```markdown

package/src/workflows/test-skill/data/scoring-rules.md

@@ -42,6 +42,18 @@ tessl evaluates SKILL.md body content only — it does not read `references/*.md
 - Score based on: structural completeness only
 - Weight redistribution: skipped categories' weights (Signature Accuracy 22% + Type Coverage 14%) redistributed proportionally to remaining active categories
 
+### Docs-Only Mode (Quick tier, all [EXT:...] citations)
+
+When `docs_only_mode: true` is set by step-03 (indicating a Quick tier skill where all SKILL.md citations are `[EXT:...]` format with no local source code):
+
+- **Signature Accuracy:** Not scored (no source to compare against)
+- **Type Coverage:** Not scored (no source to compare against)
+- **Weight redistribution:** Same as Quick tier — Signature Accuracy (22%) and Type Coverage (14%) weights redistributed proportionally to remaining active categories
+- **Export Coverage basis:** Documentation completeness rather than source coverage. Score = (documented_items_with_complete_descriptions / total_documented_items) * 100. A "complete" item has: description, parameters (if function/method), and return type (if function/method).
+- **Coherence:** Standard rules for the detected mode (naive or contextual) apply unchanged
+
+This is functionally identical to Quick tier weight redistribution but with a different coverage denominator (self-consistency instead of source comparison).
+
 ### Forge Tier (ast-grep)
 - Export Coverage: AST-backed export comparison
 - Signature Accuracy: AST-verified signature matching

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

@@ -87,6 +87,38 @@ Build the **documented inventory** — a list of everything the SKILL.md claims
 
 **Split-body traversal:** If a `references/` directory exists alongside SKILL.md and SKILL.md's `## Full` headings are absent or stubs (not a stack skill's structural references), extend the documented inventory scan to include all `references/*.md` files. After split-body, Tier 2 content (Full API Reference, Full Type Definitions) lives in reference files — the inventory must reflect the full skill content regardless of where it resides.
 
+### 1b. Cross-Check Split-Body Consistency
+
+**Only execute if a `references/` directory exists alongside SKILL.md** (detected during split-body traversal in Section 1). Skip silently otherwise.
+
+For each function, class, type, or interface that appears in BOTH the SKILL.md body AND any `references/*.md` file, compare the documented signatures:
+
+- **Parameters:** name, type, order, optionality
+- **Return types:** exact type match
+- **Description:** no contradictions (brief vs detailed is acceptable; conflicting semantics is not)
+
+**SKILL.md body is authoritative.** When a mismatch is found, the reference file is the one that needs updating.
+
+Build a split-body consistency findings list:
+
+```json
+{
+  "cross_check_mismatches": [
+    {
+      "export": "formatDate",
+      "skill_md_line": 42,
+      "reference_file": "references/api-reference.md",
+      "reference_line": 18,
+      "issue": "SKILL.md shows (date: Date) => string, reference shows (date: Date, format?: string) => string"
+    }
+  ],
+  "exports_cross_checked": 12,
+  "mismatches_found": 1
+}
+```
+
+Flag each mismatch as **High severity** — signature inconsistency between SKILL.md body and reference files undermines agent trust. These findings feed into the gap report (step-06).
+
 ### 2. Analyze Source Code (Tier-Dependent)
 
 Start from the package entry point (see 0b) and identify the public API surface. Then analyze those exports at the appropriate tier depth.
@@ -153,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}`:
@@ -181,11 +215,13 @@ Append the **Coverage Analysis** section to `{outputFile}`:
 
 ### Category Scores
 
-| Category | Score | Weight | Weighted |
-|----------|-------|--------|----------|
-| Export Coverage | {N}% | {weight}% | {weighted}% |
-| Signature Accuracy | {N}% | {weight}% | {weighted}% |
-| Type Coverage | {N}% | {weight}% | {weighted}% |
+| Category | Score |
+|----------|-------|
+| Export Coverage | {N}% |
+| Signature Accuracy | {N}% or N/A |
+| Type Coverage | {N}% or N/A |
+
+Note: Weight application is deferred to step-05 where all category weights are calculated after external validation availability is known.
 ```
 
 ### 6. Report Coverage Results

package/src/workflows/test-skill/steps-c/step-04-coherence-check.md

@@ -91,7 +91,27 @@ Build a simple structural findings list:
 }
 ```
 
-**After naive coherence → Skip to Section 6 (Append Results)**
+**After naive coherence → Execute Section 2b if gate conditions met, then skip to Section 6 (Append Results)**
+
+### 2b. Migration/Deprecation Verification (Mode-Independent)
+
+**Gate check:** Execute this section ONLY IF both conditions are met:
+1. Forge tier is **Deep** (tool-gated)
+2. `{forge_data_folder}/{skill_name}/evidence-report.md` exists (data-gated)
+
+If either condition fails, skip silently and proceed to Section 6.
+
+**This check runs regardless of naive/contextual mode.** T2-future annotations are a property of the source code and enrichment data, not the skill type.
+
+Check whether SKILL.md contains a "Migration & Deprecation Warnings" section (Section 4b). Then check the skill's `evidence-report.md` (at `{forge_data_folder}/{skill_name}/evidence-report.md`) for T2-future annotation counts.
+
+- **If T2-future annotations > 0 AND Section 4b is absent:** Flag as Medium severity gap: "Migration section missing — T2-future annotations exist but Section 4b is not present in SKILL.md Tier 1."
+- **If T2-future annotations = 0 AND Section 4b is present:** Flag as Medium severity gap: "Migration section unexpected — Section 4b is present but no T2-future annotations were produced."
+- **If evidence-report.md is unavailable:** Skip this check silently. Note: "Section 4b verification skipped — evidence-report.md not found."
+
+Add findings to the coherence analysis results.
+
+**After Section 2b (naive path) → Skip to Section 6 (Append Results)**
 
 ### 3. Contextual Mode: Extract References
 
@@ -121,6 +141,8 @@ DO NOT BE LAZY — For EACH reference found, launch a subprocess that:
 
 If subprocess unavailable, validate each reference in main thread.
 
+4. **Scripts/assets directory check:** If a `scripts/` or `assets/` directory exists alongside SKILL.md, verify that a "Scripts & Assets" section (Section 7b) is present in SKILL.md. This directory-level check applies in both modes (naive mode performs it in Section 2; contextual mode performs it here alongside per-reference validation). Flag absence as Medium severity gap per `{scoringRulesFile}`.
+
 ### 5. Contextual Mode: Check Integration Pattern Completeness
 
 For stack skills, verify integration patterns are complete:
@@ -146,11 +168,19 @@ Build integration completeness findings:
 }
 ```
 
-### 5b. Contextual Mode + Deep Tier: Section 4b Verification
+**Zero integration patterns:** If no integration patterns are documented in SKILL.md (e.g., a contextual-mode skill that uses shared types but has no middleware chains, plugin hooks, or event flows): record `patterns_documented: 0`, `patterns_complete: 0`. The coherence score will use reference validity alone — see `{scoringRulesFile}` Coherence Score Aggregation: "If no integration patterns exist, combined coherence equals reference validity."
 
-**Only execute if forge tier is Deep.** Skip silently for Quick/Forge tiers.
+### 5b. Migration/Deprecation Verification (Contextual Path)
 
-Check whether SKILL.md contains a "Migration & Deprecation Warnings" section (Section 4b). Then check the skill's `evidence-report.md` (at `{forge_data_folder}/{skill_name}/evidence-report.md`) for T2-future annotation counts.
+**This section shares logic with Section 2b.** If you are on the contextual mode path (Sections 3-5), execute the migration check here using the same rules as Section 2b:
+
+**Gate check:** Execute ONLY IF both conditions are met:
+1. Forge tier is **Deep** (tool-gated)
+2. `{forge_data_folder}/{skill_name}/evidence-report.md` exists (data-gated)
+
+If either condition fails, skip silently.
+
+Check whether SKILL.md contains a "Migration & Deprecation Warnings" section (Section 4b). Then check the skill's `evidence-report.md` for T2-future annotation counts.
 
 - **If T2-future annotations > 0 AND Section 4b is absent:** Flag as Medium severity gap: "Migration section missing — T2-future annotations exist but Section 4b is not present in SKILL.md Tier 1."
 - **If T2-future annotations = 0 AND Section 4b is present:** Flag as Medium severity gap: "Migration section unexpected — Section 4b is present but no T2-future annotations were produced."
@@ -158,6 +188,20 @@ Check whether SKILL.md contains a "Migration & Deprecation Warnings" section (Se
 
 Add findings to the coherence analysis results.
 
+### 5c. Calculate Coherence Scores
+
+**Contextual mode only.** Calculate coherence percentages using the formulas defined in `{scoringRulesFile}` — Coherence Score Aggregation section:
+
+```
+reference_validity = (valid_references / total_references) * 100
+integration_completeness = (complete_patterns / total_patterns) * 100
+combined_coherence = (reference_validity * 0.6) + (integration_completeness * 0.4)
+```
+
+**Edge case:** If no integration patterns are documented (patterns_documented = 0), combined coherence equals reference validity alone. Do not divide by zero.
+
+These values fill the `{percentage}%` placeholders in the output template loaded in Section 6.
+
 ### 6. Append Coherence Analysis to Output
 
 Load `{outputFormatsFile}` and use the appropriate Coherence Analysis section format (naive or contextual) to append findings to `{outputFile}`.

package/src/workflows/test-skill/steps-c/step-04b-external-validators.md

@@ -60,7 +60,15 @@ Read {outputFile} frontmatter to get the skill directory path (`skillDir`).
 
 Before running external validators, check if `{forge_data_folder}/{skill_name}/evidence-report.md` contains validation results (a `## Validation Results` section with quality scores).
 
-**Staleness check:** Compare the evidence report's generation date against SKILL.md's last-modified timestamp (or `metadata.json` `generation_date`). If SKILL.md was modified after the evidence report was generated (e.g., after update-skill), the cached results are stale — skip auto-reuse and proceed to section 2 for a fresh run.
+**Staleness check:** Determine whether SKILL.md has changed since the evidence report was generated.
+
+**Primary (git-tracked):** Run `git log -1 --format=%cI -- {skillDir}/SKILL.md` to get the last commit date of SKILL.md. Compare against the evidence report's generation date (from its frontmatter or the `## Validation Results` timestamp). If SKILL.md's last commit is newer, results are stale.
+
+**Secondary (uncommitted changes):** Run `git diff --name-only -- {skillDir}/SKILL.md`. If output is non-empty, SKILL.md has uncommitted changes — treat results as stale regardless of commit dates.
+
+**Fallback (non-git environments):** If git commands fail (not a git repository), fall back to `metadata.json` `generation_date` comparison with a warning: "Staleness check using metadata.json — may be identical to evidence report timestamp. Consider a git-tracked directory for reliable staleness detection."
+
+If SKILL.md was modified after the evidence report was generated (e.g., after update-skill), the cached results are stale — skip auto-reuse and proceed to section 2 for a fresh run.
 
 If recent, non-stale results exist (from a create-skill run that just completed), auto-reuse them — skip re-running validators and use the existing scores. Record: "External validation: reused from create-skill evidence report." Skip to section 5 (append results).
 

package/src/workflows/test-skill/steps-c/step-05-score.md

@@ -64,6 +64,8 @@ Load `{scoringRulesFile}` to get:
 - Tier-dependent scoring adjustments
 - Any custom threshold override from workflow input
 
+**Docs-only mode check:** If the Coverage Analysis section in `{outputFile}` notes docs-only mode (set by step-03 for skills with all `[EXT:...]` citations and no local source), apply Quick-tier weight redistribution: Signature Accuracy and Type Coverage are not scored, their weights (22% + 14%) are redistributed proportionally to remaining active categories. Coverage score is based on documentation completeness rather than source coverage (as calculated by step-03).
+
 ### 2. Read Category Scores from Output
 
 Read `{outputFile}` and extract the category scores calculated in previous steps:

package/tools/cli/lib/installer.js

@@ -185,6 +185,10 @@ class Installer {
         await fs.copy(src, path.join(skfDir, file));
       }
     }
+
+    // Write VERSION file for SKF version resolution in installed projects
+    const packageJson = require('../../../package.json');
+    await fs.writeFile(path.join(skfDir, 'VERSION'), packageJson.version, 'utf8');
   }
 
   /**