bmad-module-skill-forge 0.7.1 → 0.7.2

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.2",
   "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 |

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

@@ -106,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}

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

@@ -135,7 +135,12 @@ Based on detected language, identify public API surface:
 
 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 +151,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 +190,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 +201,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 +231,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

@@ -90,6 +90,20 @@ 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)
+
+**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.
+
 ### 2b. Offer Scope Templates
 
 Load `{scopeTemplatesFile}` for the scope type options ([F], [M], [P]) and their descriptions.

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

@@ -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}

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/extraction-patterns.md

@@ -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
 

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

@@ -71,7 +71,7 @@ If `tools.ccc` is true, continue to section 2.
 
 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.

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:**
 

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

@@ -100,7 +100,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.
 

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/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.
@@ -181,11 +213,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');
   }
 
   /**