bmad-module-skill-forge 0.7.0 → 0.7.2

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)`
+- 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,10 +71,12 @@ 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.
 
+**Tool resolution for ccc_bridge.ensure_index:** Use `/ccc` skill indexing (Claude Code), ccc MCP server (Cursor), or `ccc init` + `ccc index {source_root}` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 ### 3. Construct Semantic Query
 
 Build the discovery query from the brief data:
@@ -91,6 +93,8 @@ Where:
 
 Run `ccc_bridge.search(query, source_root, top_k=20)`:
 
+**Tool resolution for ccc_bridge.search:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search "{query}" --path {source_root} --top 20` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 **If search succeeds:**
 
 Store results as `{ccc_discovery: [{file, score, snippet}]}` in context.

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)
@@ -92,6 +92,8 @@ Load `{sourceResolutionData}` completely. Follow the **Remote Source Resolution*
 5. Infer types from JSDoc, docstrings, type annotations
 6. Confidence: All results T1-low — `[SRC:{file}:L{line}]`
 
+**Tool resolution for gh_bridge:** Use `gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1` for list_tree, `gh api repos/{owner}/{repo}/contents/{path}` for read_file. If source is local, use direct file listing/reading instead. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 **Forge/Forge+/Deep Tier (AST available):**
 
 **CCC Discovery Integration (Forge+ and Deep with ccc only):**
@@ -115,6 +117,8 @@ If `{ccc_discovery}` is empty or not in context: proceed with existing file orde
 5. Build extraction rules YAML data for reproducibility
 6. Confidence: All results T1 — `[AST:{file}:L{line}]`
 
+**Tool resolution for ast_bridge:** Use ast-grep MCP tools (`mcp__ast-grep__find_code`, `mcp__ast-grep__find_code_by_rule`) as specified in the AST Extraction Protocol above, or `ast-grep` CLI. For `detect_co_imports`, use `find_code_by_rule` with a co-import YAML rule scoped to the libraries list. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 **If AST tool is unavailable at Forge/Deep tier** (see `{tierDegradationRulesData}` for full rules):
 
 ⚠️ **Warn the user explicitly:** "AST tools are unavailable — extraction will use source reading (T1-low). Run [SF] Setup Forge to detect and configure AST tools for T1 confidence."

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-04-enrich.md

@@ -96,6 +96,8 @@ For each function, derive the **module context** from the extraction inventory's
 
 4. **Semantic migration context:** `qmd_bridge.vector_search("{module_context} {function_name} migration deprecated")` — adds semantic matches (synonyms, paraphrases) that BM25 keyword search may miss. Merge results with search #3, deduplicating by document ID. If `vector_search` fails (VRAM, GPU driver, model loading), discard silently — the BM25 results from search #3 provide baseline coverage.
 
+**Tool resolution for qmd_bridge:** Use QMD MCP tools — `mcp__plugin_qmd-plugin_qmd__search` for BM25 search, `mcp__plugin_qmd-plugin_qmd__vector_search` for semantic search (Claude Code). Cursor: qmd MCP server. CLI: `qmd search "{query}"` / `qmd vector_search "{query}"`. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 **For each QMD result:**
 
 - Create a T2 annotation: `[QMD:{collection}:{doc}]`

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/create-stack-skill/data/manifest-patterns.md

@@ -20,6 +20,28 @@
 3. Normalize names across ecosystems (e.g., `@scope/package` → `package`)
 4. Deduplicate across multiple manifests
 
+## Scan Exclusion Patterns
+
+When scanning for manifest files, ALWAYS exclude these directories from glob results:
+
+**Dependency/Vendor Directories:**
+- `node_modules/`
+- `.venv/` / `venv/` / `.env/`
+- `vendor/` (PHP Composer, Go modules)
+- `Pods/` (iOS CocoaPods)
+
+**Build Output Directories:**
+- `dist/` / `build/` / `out/`
+- `target/` (Rust, Java/Maven)
+- `__pycache__/`
+- `.next/` / `.nuxt/` / `.output/`
+
+**Hidden and VCS Directories:**
+- `.git/`
+- Any directory starting with `.` (except project root hidden config files like `.csproj`)
+
+**Monorepo Note:** For monorepo structures (e.g., `packages/*/package.json`), the depth 0-1 scan rule already limits scope. If monorepo manifest detection is needed at deeper levels, these exclusions become critical to prevent scanning dependency trees within each package.
+
 ## Filtering Rules
 
 - Exclude dev-only dependencies unless they appear in production imports
@@ -32,4 +54,4 @@
 For each dependency, count distinct files that import it:
 - Use grep patterns from Import Pattern column
 - Count unique file paths, not total import statements
-- Exclude test files, config files, and build artifacts from count
+- Exclude test files (`*/test/*`, `*_test.*`, `*.spec.*`, `*.test.*`), config files (`*.config.*`, `.eslintrc`, etc.), and build artifacts (`dist/`, `build/`, `node_modules/`, `target/`, `__pycache__/`) from count

package/src/workflows/create-stack-skill/steps-c/step-01-init.md

@@ -84,6 +84,8 @@ Extract:
 - **Forge+:** ast_bridge + ccc_bridge (ccc semantic co-import augmentation) — ccc available for step-05
 - **Deep:** qmd_bridge (QMD temporal enrichment) — required for Deep tier
 
+See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md) for how each bridge name resolves to concrete tools per IDE environment.
+
 Report tool availability. If a tier-required tool is missing, downgrade tier and note:
 
 "**Tier adjusted:** {original_tier} → {adjusted_tier} — {missing_tool} unavailable."

package/src/workflows/create-stack-skill/steps-c/step-02-detect-manifests.md

@@ -99,10 +99,11 @@ Store the explicit list as `raw_dependencies` and skip to [Display Detection Sum
 
 Load `{manifestPatterns}` for supported ecosystem detection patterns.
 
-Scan the project root (depth 0-1) for manifest files:
+Scan the project root (depth 0-1) for manifest files, **excluding directories listed in the Scan Exclusion Patterns section of `{manifestPatterns}`**:
 
 - Search for each supported manifest filename
 - Record: file path, ecosystem type, file size
+- **Apply exclusion patterns** from `{manifestPatterns}` — skip `node_modules/`, `.venv/`, `vendor/`, `dist/`, `build/`, `target/`, `.git/`, and all hidden directories when globbing
 - Note any unusual structures (monorepo with multiple manifests, workspace configurations)
 
 **If no manifest files found:**

package/src/workflows/create-stack-skill/steps-c/step-03-rank-and-confirm.md

@@ -30,7 +30,7 @@ Count import frequency for each dependency across the codebase, rank by usage, a
 - 🎯 Focus on counting imports, ranking, and getting user confirmation
 - 🚫 FORBIDDEN to extract library documentation — that is step 04
 - 💬 Present data clearly so user can make informed scope decisions
-- 🎯 Use subprocess (Pattern 1 grep) for import counting when available
+- 🎯 Use subprocess (Pattern 1 — grep/search): In Claude Code, use the Grep tool or Bash with `rg`. In Cursor, use built-in search. In CLI, use `grep`/`rg` directly. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 
 ## EXECUTION PROTOCOLS:
 
@@ -80,6 +80,8 @@ For each dependency in `raw_dependencies`:
 
 **Launch a subprocess** that runs grep across all source files in the project to count import statements for each library. Return only the counts, not file contents.
 
+**Subprocess resolution:** Use the Grep tool (Claude Code), built-in search (Cursor), or `grep`/`rg` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 Use ecosystem-appropriate import patterns:
 - JavaScript/TypeScript: `import .* from ['"]library`, `require\(['"]library`
 - Python: `import library`, `from library import`

package/src/workflows/create-stack-skill/steps-c/step-04-parallel-extract.md

@@ -27,7 +27,7 @@ For each confirmed dependency, extract key exports, usage patterns, and API surf
 
 ### Step-Specific Rules:
 
-- 🎯 Extract per-library using Pattern 4 (parallel subprocess) when available
+- 🎯 Extract per-library using Pattern 4 (parallel): In Claude Code, use multiple parallel Agent tool calls or `run_in_background: true`. In Cursor, use parallel requests (IDE-dependent). In CLI, use `xargs -P` or background processes. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - 💬 Each subprocess returns structured extraction, not raw file contents
 - 🚫 FORBIDDEN to analyze cross-library integrations — that is step 05
 - ⚙️ If parallel subprocess unavailable, extract libraries sequentially in main thread
@@ -105,14 +105,25 @@ For each library in `confirmed_dependencies`, determine extraction strategy base
 - Confidence: T1 (AST-verified structural extraction)
 
 **Deep Tier (adds to Forge):**
-- Use qmd_bridge for temporal usage evolution
-- Identify deprecated patterns and migration paths
-- Track API changes across project history
-- Confidence: T2 (QMD-enriched temporal context)
+- Perform all Forge tier extractions (T1)
+- Additionally: query existing QMD temporal collections for each library
+- Read the `qmd_collections` registry from `{sidecar_path}/forge-tier.yaml`
+- For each library in `confirmed_dependencies`, search for a registry entry where `skill_name` matches the library name AND `type` is `"temporal"`
+- **If a matching temporal collection exists:**
+  - Query `qmd_bridge.search("{library_name} deprecated OR removed OR breaking change")` for deprecation context
+  - Query `qmd_bridge.search("{library_name} migration OR upgrade")` for migration patterns
+  - Query `qmd_bridge.search("{library_name} version issue OR bug OR workaround")` for version-specific warnings
+  - **Tool resolution for qmd_bridge:** Use QMD MCP tools — `mcp__plugin_qmd-plugin_qmd__search` (Claude Code), qmd MCP server (Cursor), `qmd search "{query}"` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
+  - Classify each result as T2-past (historical) or T2-future (planned changes) per confidence-tiers.md
+  - Append temporal findings to the library's extraction as T2 annotations with `[QMD:{collection}:{doc}]` citations
+- **If no matching temporal collection found:**
+  - Log: "No temporal collection for {library_name}. T2 enrichment skipped."
+  - Continue with T1/T1-low extraction only
+- Confidence: T1 for structural (AST), T2 for temporal annotations (QMD-enriched)
 
 ### 2. Launch Parallel Extraction
 
-**Launch subprocesses in parallel** (max_parallel_generation) — one per confirmed library:
+**Launch subprocesses in parallel** (max_parallel_generation: 3–5 concurrent Agent tool calls in Claude Code, IDE-dependent in Cursor, CPU core count in CLI) — one per confirmed library:
 
 Each subprocess:
 1. Reads all files importing the library (from step 03 file lists)
@@ -129,7 +140,13 @@ Each subprocess:
   usage_patterns: ["pattern description with file:line"],
   confidence: "T1|T1-low|T2",
   files_analyzed: count,
-  warnings: []
+  warnings: [],
+  temporal: {
+    deprecated_exports: ["export_name — reason [QMD:collection:doc]"],
+    migration_notes: ["note [QMD:collection:doc]"],
+    version_warnings: ["warning [QMD:collection:doc]"],
+    t2_annotation_count: count
+  }
 }
 ```
 
@@ -161,6 +178,8 @@ For each library extraction:
 
 **Results:** {success_count}/{total_count} libraries extracted
 **Confidence distribution:** T1: {count}, T1-low: {count}, T2: {count}
+{If Deep tier:} **T2 enrichment:** {enriched_count}/{total_count} libraries had temporal collections available
+{If libraries without temporal > 0:} **Tip:** Run [CS] Create Skill at Deep tier for individual libraries to generate temporal collections, then re-run [SS] for full T2 enrichment.
 {If warnings:} **Warnings:** {warning_count} issues noted
 
 **Proceeding to integration detection...**"

package/src/workflows/create-stack-skill/steps-c/step-05-detect-integrations.md

@@ -29,7 +29,7 @@ Analyze co-import patterns between confirmed libraries to identify integration p
 
 ### Step-Specific Rules:
 
-- 🎯 Focus on detecting cross-library patterns using Pattern 1 (grep) subprocess
+- 🎯 Focus on detecting cross-library patterns using Pattern 1 (grep/search): In Claude Code, use the Grep tool or Bash with `rg`. In Cursor, use built-in search. In CLI, use `grep`/`rg` directly. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - 🚫 FORBIDDEN to compile SKILL.md — that is step 06
 - 💬 Integration detection is the core differentiator of stack skills vs individual skills
 - ⚙️ If subprocess unavailable, perform grep operations in main thread
@@ -93,6 +93,8 @@ For each library pair (A, B):
 
 **Launch a subprocess** that greps across all source files to find files importing BOTH library A and library B. Return only file paths and import line numbers.
 
+**Subprocess resolution:** Use the Grep tool (Claude Code), built-in search (Cursor), or `grep`/`rg` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 **Subprocess returns:** `{pair: [A, B], co_import_files: [{path, line_A, line_B}], count: N}`
 
 **If subprocess unavailable:** Intersect the file lists from step 03 import counts for each pair.
@@ -105,6 +107,8 @@ If `tools.ccc` is true AND `ccc_index.status` is `"fresh"` or `"stale"` in forge
 
 For each library pair that has exactly 1 co-import file (below the 2-file threshold), run `ccc_bridge.search("{libA} {libB}", source_root, top_k=10)` to find files where the two libraries interact semantically — even without explicit import co-location. If CCC returns additional files where both libraries appear, add them to the pair's co-import candidate list and re-evaluate against the 2-file threshold.
 
+**Tool resolution for ccc_bridge.search:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search "{libA} {libB}" --path {source_root} --top 10` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 For pairs that already qualify (2+ files), CCC is not needed for detection — but the CCC results may surface additional integration files for richer classification in section 3.
 
 CCC failures: skip augmentation silently, proceed with grep-only results.

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

@@ -86,9 +86,9 @@ The `ccc index` command auto-starts the daemon when needed. Proceed with indexin
 
 Attempt indexing anyway — errors will be caught below.
 
-Run:
+Run (CWD must be `{project-root}`):
 ```bash
-ccc init {project-root}
+ccc init
 ```
 
 **If init fails** (project may already be initialized): continue — this is not an error.
@@ -98,6 +98,8 @@ Then run:
 ccc index
 ```
 
+**Note:** `ccc index` can take several minutes on large codebases (1000+ files). Run with an extended timeout or in background mode. Use `ccc status` to verify completion — check that `Chunks` and `Files` counts are non-zero.
+
 **If succeeds:**
 - Run `ccc status` to get file count
 - Store `{ccc_index_result: "created", ccc_indexed_path: {project-root}, ccc_last_indexed: {current ISO timestamp}, ccc_file_count: {count from status}}`

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/src/workflows/update-skill/steps-c/step-02-detect-changes.md

@@ -35,7 +35,7 @@ Compare current source code state against the provenance map to produce a comple
 - 🎯 Focus ONLY on detecting and classifying changes — do not extract or merge
 - 🚫 FORBIDDEN to modify any files — read-only change detection
 - 🚫 FORBIDDEN to re-extract content — that is step 03
-- 💬 Use subprocess optimization Pattern 4 for parallel comparison when available
+- 💬 Use subprocess Pattern 4 (parallel): In Claude Code, use multiple parallel Agent tool calls or `run_in_background: true`. In Cursor, use parallel requests (IDE-dependent). In CLI, use `xargs -P` or background processes. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - ⚙️ If subprocess unavailable, perform comparison sequentially in main thread
 
 ## EXECUTION PROTOCOLS:

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

@@ -101,6 +101,8 @@ Perform tier-aware extraction on only the changed files identified in step 02, p
 - QMD provides: usage patterns, historical context, related documentation
 - Confidence: T1 for structural, T2 for semantic enrichment
 
+**Tool resolution:** `ast_bridge` → ast-grep MCP tools (`find_code`, `find_code_by_rule`) or `ast-grep` CLI. `qmd_bridge` → QMD MCP tools (`mcp__plugin_qmd-plugin_qmd__search`, `vector_search`) or `qmd` CLI. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 ### 2. Extract Changed Files
 
 DO NOT BE LAZY — For EACH file in the change manifest with status MODIFIED, ADDED, or RENAMED, launch a subprocess that:
@@ -128,7 +130,7 @@ DO NOT BE LAZY — For EACH file in the change manifest with status MODIFIED, AD
 
 Before aggregating extraction results, use CCC to assess semantic significance of changes:
 
-1. Run `ccc_bridge.search("{skill_name}", source_root, top_k=15)` to get the skill's most semantically central files
+1. Run `ccc_bridge.search("{skill_name}", source_root, top_k=15)` — **Tool resolution:** `/ccc` skill search (Claude Code), ccc MCP (Cursor), `ccc search` (CLI) — to get the skill's most semantically central files
 2. Cross-reference the change manifest files with CCC results
 3. Files appearing in BOTH the change manifest AND CCC's top results are **semantically significant changes** — flag them for priority in the merge step
 4. Store `{ccc_significant_changes: [{file, score}]}` in context