bmad-module-skill-forge 0.7.0 → 0.7.2

package/docs/how-it-works.md

@@ -332,6 +332,8 @@ Export injects a managed section between markers:
 | **`qmd_bridge`** | QMD (local search) | BM25 keyword search, vector semantic search, collection indexing |
 | **`doc_fetcher`** | Environment web tools | Remote documentation fetching for T3-confidence content. Tool-agnostic — uses whatever web fetching is available (Firecrawl, WebFetch, curl, etc.). Output quarantined as T3. |
 
+Bridge names are **conceptual interfaces** used throughout workflow steps. Each bridge resolves to concrete MCP tools, CLI commands, or fallback behavior depending on the IDE environment. See [`src/knowledge/tool-resolution.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/knowledge/tool-resolution.md) for the complete resolution table.
+
 ### Conflict Resolution
 
 When tools disagree, higher priority wins for instructions. Lower priority is preserved as annotations:

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.7.0",
+  "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/ccc-bridge.md

@@ -2,7 +2,7 @@
 
 ## Principle
 
-`ccc_bridge.*` references in workflow steps are **conceptual interfaces**, not callable functions. They describe a semantic code discovery operation to perform. Use the `ccc` MCP server tools (when available) or `ccc` CLI commands to execute these operations. See the TOOL/SUBPROCESS FALLBACK rule — if ccc is unavailable, the calling step falls back to direct ast-grep or source reading without ccc pre-discovery.
+`ccc_bridge.*` references in workflow steps are **conceptual interfaces**, not callable functions. They describe a semantic code discovery operation to perform. Use the `ccc` MCP server tools (when available) or `ccc` CLI commands to execute these operations. See the TOOL/SUBPROCESS FALLBACK rule — if ccc is unavailable, the calling step falls back to direct ast-grep or source reading without ccc pre-discovery. For the complete bridge-to-tool resolution table covering all IDE environments, see [tool-resolution.md](tool-resolution.md).
 
 ## Rationale
 
@@ -103,6 +103,7 @@ To prevent excessive daemon calls, workflow steps cap ccc queries:
 
 ## Related Fragments
 
+- [tool-resolution.md](tool-resolution.md) — canonical bridge-to-tool and subprocess-to-tool mapping per IDE
 - [progressive-capability.md](progressive-capability.md) — Forge+ tier definition and positive framing
 - [confidence-tiers.md](confidence-tiers.md) — why ccc does not create a new confidence tier
 - [qmd-registry.md](qmd-registry.md) — the parallel but separate registry for QMD collections

package/src/knowledge/overview.md

@@ -31,6 +31,7 @@ With knowledge files:
 | [manual-section-integrity.md](manual-section-integrity.md) | \[MANUAL\] marker preservation and merge algorithm                | CS, US, AS, TS, EX                 |
 | [qmd-registry.md](qmd-registry.md)                         | Progressive QMD collection registry and collection gate principle | SF, BS, CS, US, AS                 |
 | [ccc-bridge.md](ccc-bridge.md)                             | ccc_bridge interface, indexing lifecycle, Forge+ discovery-before-extraction | SF, AN, CS, SS, US, AS             |
+| [tool-resolution.md](tool-resolution.md)                   | Bridge-to-tool and subprocess-to-tool mapping per IDE environment | CS, QS, SS, US, AS, AN, BS, RA     |
 | [architecture-verification.md](architecture-verification.md) | Pre-code verification pipeline, integration verdicts, iteration loop | VS, RA, SS                        |
 | [doc-fetcher.md](doc-fetcher.md)                           | T3 external documentation fetching, quarantine rules, tool-agnostic | CS, QS                             |
 | [split-body-strategy.md](split-body-strategy.md)           | Selective vs full split-body, detection pattern, agent accuracy   | CS, QS, US, TS, EX                |

package/src/knowledge/progressive-capability.md

@@ -84,6 +84,8 @@ Deep:   "Full intelligence pipeline — AST verification plus GitHub exploration
 - **Forge+:** Identical extraction to Forge, plus ccc semantic pre-discovery narrows the file set before ast-grep runs. For large codebases, `ccc_bridge.search()` produces a ranked candidate list. ast-grep operates on that list rather than the full tree. All results remain T1 (AST-verified) — ccc is upstream, not in the extraction chain.
 - **Deep:** Identical extraction to Forge, plus QMD enrichment in a separate step. T2 annotations layer on top of the T1 base without replacing it.
 
+*Bridge names (`gh_bridge`, `ast_bridge`, `ccc_bridge`, `qmd_bridge`) are conceptual interfaces. See [tool-resolution.md](tool-resolution.md) for concrete tool resolution per IDE.*
+
 **Key Points:**
 - Extraction quality increases with tier, but every tier produces complete output
 - Forge and Deep share the same extraction core — Deep adds enrichment, not better parsing

package/src/knowledge/qmd-registry.md

@@ -21,7 +21,7 @@ The progressive registry solves all three by indexing **curated workflow artifac
 | Role | Workflow | Responsibility |
 | --- | --- | --- |
 | **Producer** | brief-skill, create-skill | Creates QMD collections from workflow artifacts and registers them in forge-tier.yaml |
-| **Consumer** | audit-skill, update-skill | Reads the registry, discovers collections by skill name and type, queries via qmd_bridge |
+| **Consumer** | audit-skill, update-skill, create-stack-skill | Reads the registry, discovers collections by skill name and type, queries via qmd_bridge (see [tool-resolution.md](tool-resolution.md) for concrete resolution) |
 | **Janitor** | setup-forge | Cross-references live QMD collections against the registry, cleans orphans and stale entries |
 
 ### Registry Schema
@@ -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/knowledge/skf-knowledge-index.csv

@@ -12,3 +12,4 @@ qmd-registry,QMD Collection Registry,"Progressive registry architecture — prod
 doc-fetcher,Doc Fetcher,"T3 external documentation — tool-agnostic URL fetching, quarantine rules, conflict resolution","doc-fetcher,t3,external,documentation,quarantine",extended,knowledge/doc-fetcher.md
 architecture-verification,Architecture Verification,"Pre-code verification pipeline — VS/RA/SS-compose lifecycle, integration verdicts, coverage analysis, iteration loop","architecture,verification,stack,feasibility,integration,vs,ra,ss,compose",core,knowledge/architecture-verification.md
 split-body-strategy,Split-Body Strategy,"Selective split guidance — detection pattern, recommended approach, impact on tessl scores and snippet anchors","split-body,selective-split,references,body-size",core,knowledge/split-body-strategy.md
+tool-resolution,Tool Resolution,"Bridge-to-tool and subprocess-to-tool mapping — ast_bridge, ccc_bridge, qmd_bridge, gh_bridge resolution per IDE, subprocess Pattern 1-4 definitions","bridge,tools,resolution,subprocess,mcp,cli,ide",core,knowledge/tool-resolution.md

package/src/knowledge/tool-resolution.md

@@ -0,0 +1,55 @@
+# Tool Resolution
+
+Bridge names (`ast_bridge`, `ccc_bridge`, `qmd_bridge`, `gh_bridge`) and subprocess patterns (Pattern 1–4) used throughout SKF workflows are **conceptual interfaces**, not callable functions. This document provides the canonical mapping from abstract names to concrete tools per IDE environment.
+
+## Bridge Resolution Table
+
+| Bridge       | Operation                        | Claude Code                                                      | Cursor         | CLI                                                | Fallback                         |
+|--------------|----------------------------------|------------------------------------------------------------------|----------------|----------------------------------------------------|----------------------------------|
+| `ast_bridge` | `scan_definitions()`             | `mcp__ast-grep__find_code` or `mcp__ast-grep__find_code_by_rule` | ast-grep MCP   | `sg run` / `ast-grep -p`                           | Source reading (T1-low)          |
+| `ast_bridge` | `detect_co_imports()`            | `mcp__ast-grep__find_code_by_rule` with co-import YAML rule      | ast-grep MCP   | `ast-grep -p 'import $$$' --json=stream`           | grep-based co-import count       |
+| `ccc_bridge` | `search(query, root, top_k)`     | `/ccc` skill search                                              | ccc MCP server | `ccc search "{query}" --path {root} --top {top_k}` | Skip silently                    |
+| `ccc_bridge` | `ensure_index(root)`             | `/ccc` skill indexing                                            | ccc MCP server | `ccc init` + `ccc index {root}`                    | Skip silently                    |
+| `ccc_bridge` | `status()`                       | `/ccc` skill status                                              | ccc MCP server | `ccc --help` + `ccc doctor`                        | Unavailable = `tools.ccc: false` |
+| `qmd_bridge` | `search(query)`                  | `mcp__plugin_qmd-plugin_qmd__search`                             | qmd MCP server | `qmd search "{query}"`                             | Skip enrichment                  |
+| `qmd_bridge` | `vector_search(query)`           | `mcp__plugin_qmd-plugin_qmd__vector_search`                      | qmd MCP server | `qmd vector_search "{query}"`                      | Use BM25 search only             |
+| `gh_bridge`  | `list_tree(owner, repo, branch)` | `gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1`     | gh CLI         | `gh api ...`                                       | Direct file listing if local     |
+| `gh_bridge`  | `read_file(owner, repo, path)`   | `gh api repos/{owner}/{repo}/contents/{path}`                    | gh CLI         | `gh api ...`                                       | Direct file read if local        |
+
+## Subprocess Pattern Definitions
+
+Workflow steps reference "subprocess" execution with numbered patterns. These map to concrete mechanisms per IDE:
+
+| Pattern                                | Purpose                                               | Claude Code                                                          | Cursor                            | CLI                                |
+|----------------------------------------|-------------------------------------------------------|----------------------------------------------------------------------|-----------------------------------|------------------------------------|
+| **Pattern 1** (grep/search)            | Search across files for imports, co-imports           | Grep tool or Bash with `rg`                                          | Built-in search                   | `grep` / `rg`                      |
+| **Pattern 2** (per-file deep analysis) | Deep analysis of individual files or units            | Agent tool (sequential per unit)                                     | Sequential analysis               | Per-unit script                    |
+| **Pattern 3** (data operations)        | QMD queries, severity classification, data transforms | Main thread (Read + process)                                         | Main thread                       | Script                             |
+| **Pattern 4** (parallel execution)     | Parallel per-library extraction, parallel diffing     | Agent tool with multiple parallel calls or `run_in_background: true` | Parallel requests (IDE-dependent) | `xargs -P` or background processes |
+
+### max_parallel_generation
+
+Referenced by Pattern 4 steps. Defines the maximum concurrent subprocess spawns:
+
+| Environment | Recommended Value                | Notes                                                                 |
+|-------------|----------------------------------|-----------------------------------------------------------------------|
+| Claude Code | 3–5                              | Concurrent Agent tool calls; higher values may cause context pressure |
+| Cursor      | IDE-dependent                    | Follow Cursor's agent concurrency limits                              |
+| CLI         | CPU core count or user-specified | Use `xargs -P {n}` or equivalent                                      |
+
+## Resolution Protocol
+
+When a workflow step references a bridge name or subprocess pattern:
+
+1. **Identify** the bridge name (`ast_bridge`, `ccc_bridge`, etc.) or pattern number (Pattern 1–4)
+2. **Check tool availability** in `{sidecar_path}/forge-tier.yaml` → `tools.*` section
+3. **Resolve** using the tables above — use the first available option in priority order: MCP tool → CLI command → Fallback
+4. **Apply fallback** if no resolution is available — fallbacks are always defined and never block the workflow
+5. **Log degradation** when falling back — note the reason in context for the evidence report
+
+## Related Fragments
+
+- [ccc-bridge.md](ccc-bridge.md) — CCC semantic discovery interface and lifecycle
+- [progressive-capability.md](progressive-capability.md) — Quick/Forge/Forge+/Deep tier philosophy
+- [confidence-tiers.md](confidence-tiers.md) — T1/T1-low/T2/T3 trust model and citation formats
+- [qmd-registry.md](qmd-registry.md) — QMD collection producer/consumer/janitor architecture

package/src/workflows/analyze-source/steps-c/step-04-map-and-detect.md

@@ -33,7 +33,7 @@ To analyze each qualifying unit's export surface and import graph, detect cross-
 
 ### Step-Specific Rules:
 
-- 🎯 Use subprocess optimization (Pattern 2) — per-unit analysis for export mapping
+- 🎯 Use subprocess optimization (Pattern 2 — per-unit deep analysis): In Claude Code, use Agent tool for each unit sequentially. In CLI, use a per-unit script. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - 💬 DO NOT BE LAZY — For EACH qualifying unit, perform thorough export surface analysis
 - 🚫 FORBIDDEN to make recommendations in this step (that's step 05)
 - 📋 Tier-aware depth: Quick (file-level exports), Forge (AST export analysis), Deep (AST + semantic relationships)
@@ -82,7 +82,7 @@ DO NOT BE LAZY — For EACH qualifying unit, launch a subprocess (or analyze in
    - **Quick tier:** Count files by type, identify index/barrel files, list directory structure
    - **Forge tier:** Parse export statements, identify public API surface, count exported functions/classes/types
    - **Forge+ tier:** All Forge analysis plus:
-     - If `tools.ccc` is true: run `ccc_bridge.search("{unit_name} exports public API", top_k=15)` to discover semantically relevant files beyond directory scan
+     - If `tools.ccc` is true: run `ccc_bridge.search("{unit_name} exports public API", top_k=15)` — **Tool resolution:** `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search` CLI; see [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md) — to discover semantically relevant files beyond directory scan
      - Merge CCC-discovered files with scoped file list — files from CCC that are within the unit's directory are added to the analysis queue
      - Record CCC signals in per-unit findings: top 3 CCC-ranked file names (or "—" if no ccc results)
    - **Deep tier:** All Forge analysis plus:

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

@@ -83,7 +83,7 @@ Load `{sidecar_path}/forge-tier.yaml` to detect available tools.
 
 **If found:**
 - Extract tier level: Quick / Forge / Forge+ / Deep
-- Extract available tools: gh_bridge, ast_bridge, qmd_bridge
+- Extract available tools: gh_bridge, ast_bridge, qmd_bridge — see [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md) for concrete tool resolution per IDE
 
 **Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, Forge+, or Deep), use it instead of the detected tier.
 

package/src/workflows/audit-skill/steps-c/step-02-re-index.md

@@ -78,6 +78,8 @@ Based on forge tier detected in Step 01:
 - Query qmd_bridge for temporal context: when exports were added, modification history, usage frequency
 - Confidence labels: T1 for structural, T2 for temporal context
 
+**Tool resolution:** `gh_bridge` → `gh api` commands or direct file I/O if local. `ast_bridge` → ast-grep MCP tools (`find_code`, `find_code_by_rule`) or `ast-grep` CLI. `qmd_bridge` → QMD MCP tools (`search`, `vector_search`) or `qmd` CLI. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 ### 2. Scan Source Files
 
 Identify all source files in the source directory that contain public exports.
@@ -148,7 +150,7 @@ Skip this section. Temporal context requires Deep tier.
 
 For each export in the skill baseline that was NOT found at its recorded file path during re-extraction (potential "deleted" export):
 
-1. Run `ccc_bridge.search("{export_name}", source_root, top_k=5)` to find candidate current locations
+1. Run `ccc_bridge.search("{export_name}", source_root, top_k=5)` — **Tool resolution:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search "{export_name}" --path {source_root} --top 5` (CLI) — to find candidate current locations
 2. If CCC returns files containing the export name:
    - Run ast-grep verification on each candidate file
    - If verified at a new location: reclassify from "deleted" to "moved" with the new file:line reference

package/src/workflows/audit-skill/steps-c/step-03-structural-diff.md

@@ -33,7 +33,7 @@ Compare the original provenance map extractions from create-skill against the cu
 - 🎯 Focus only on structural comparison — added/removed/changed exports
 - 🚫 FORBIDDEN to classify severity — that happens in Step 05
 - 🚫 FORBIDDEN to suggest remediation — that happens in Step 06
-- 💬 Use subprocess Pattern 4 (parallel execution) when available to compare export categories simultaneously
+- 💬 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, compare categories sequentially in main thread
 
 ## EXECUTION PROTOCOLS:
@@ -70,7 +70,7 @@ Normalize both sets for comparison:
 
 ### 2. Detect Added Exports
 
-**Launch subprocess (Pattern 4 — parallel execution):**
+**Launch subprocess (Pattern 4 — parallel execution):** In Claude Code, use multiple parallel Agent tool calls. In CLI, use `xargs -P` or equivalent.
 
 Find exports that exist in current scan but NOT in provenance map.
 

package/src/workflows/audit-skill/steps-c/step-04-semantic-diff.md

@@ -33,7 +33,7 @@ Compare QMD knowledge context between the original skill creation and current st
 - 🎯 Focus only on semantic/meaning-level changes via QMD context
 - 🚫 FORBIDDEN to classify severity — that happens in Step 05
 - 🚫 FORBIDDEN to repeat structural findings from Step 03
-- 💬 Use subprocess Pattern 3 (data operations) when available for QMD queries
+- 💬 Use subprocess Pattern 3 (data operations — main thread Read + process in Claude Code, script in CLI) when available for QMD queries. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - ⚙️ If subprocess unavailable, query QMD in main thread
 - 🔀 CONDITIONAL: Skip entire analysis at Quick/Forge/Forge+ tier — append skip notice only
 

package/src/workflows/audit-skill/steps-c/step-05-severity-classify.md

@@ -34,7 +34,7 @@ Grade every drift finding from Steps 03 and 04 by severity level (CRITICAL/HIGH/
 - 🎯 Focus only on classifying severity of existing findings
 - 🚫 FORBIDDEN to discover new drift items — only classify what Steps 03-04 found
 - 🚫 FORBIDDEN to suggest remediation — that happens in Step 06
-- 💬 Use subprocess Pattern 3 (data operations) to load severity rules and classify
+- 💬 Use subprocess Pattern 3 (data operations — main thread Read + process in Claude Code, script in CLI) to load severity rules and classify. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - ⚙️ If subprocess unavailable, load rules and classify in main thread
 
 ## EXECUTION PROTOCOLS:

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)`.
+**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

@@ -28,7 +28,13 @@ Source reading via gh_bridge — infer exports from file structure and content.
 
 Structural extraction via ast-grep — verified exports with line-level citations.
 
-> **Note:** `ast_bridge.*`, `qmd_bridge.*`, and `ccc_bridge.*` references below are **conceptual interfaces**, not callable functions. They describe the operation to perform. Use ast-grep (MCP tool or CLI) for `ast_bridge.*` operations, QMD (MCP tool or CLI) for `qmd_bridge.*` operations, and ccc CLI or MCP for `ccc_bridge.*` operations. See the AST Extraction Protocol section below and the TOOL/SUBPROCESS FALLBACK rule for dispatch details.
+> **Note:** `ast_bridge.*`, `qmd_bridge.*`, and `ccc_bridge.*` references below are **conceptual interfaces**, not callable functions. Resolve them as follows:
+> - `ast_bridge.*` → ast-grep MCP tools (`mcp__ast-grep__find_code`, `mcp__ast-grep__find_code_by_rule`) or `ast-grep` CLI
+> - `qmd_bridge.*` → QMD MCP tools (`mcp__plugin_qmd-plugin_qmd__search`, `vector_search`) or `qmd` CLI
+> - `ccc_bridge.*` → `/ccc` skill (Claude Code), ccc MCP server (Cursor), or `ccc` CLI
+> - `gh_bridge.*` → `gh api` commands or direct file I/O for local sources
+>
+> See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md) for the complete resolution table. Also see the AST Extraction Protocol section below and the TOOL/SUBPROCESS FALLBACK rule for dispatch details.
 
 ### Strategy
 
@@ -162,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)
@@ -187,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:**
@@ -195,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.
@@ -135,4 +149,4 @@ Update the working version in context to the source version. Record the mismatch
 
 **If no version file is found or version cannot be extracted:** keep `brief.version` as-is. No warning needed.
 
-**If source is remote and accessed via Quick tier (gh_bridge, no local files):** attempt to read the version file via `gh_bridge.read_file(owner, repo, "{version_file}")` for the primary version file of the detected language. If the read fails, keep `brief.version`.
+**If source is remote and accessed via Quick tier (gh_bridge, no local files):** attempt to read the version file via `gh_bridge.read_file(owner, repo, "{version_file}")` — resolved as `gh api repos/{owner}/{repo}/contents/{version_file}` or direct file read if local (see [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)) — for the primary version file of the detected language. If the read fails, keep `brief.version`.

package/src/workflows/create-skill/data/tier-degradation-rules.md

@@ -20,7 +20,7 @@ When `source_repo` is a remote URL (GitHub URL or owner/repo format) and the tie
 - The extraction step MUST warn the user explicitly before degrading
 - **create-skill:** Warning must include actionable guidance — clone locally and update `source_repo` in the brief to the local path
 - **update-skill:** Warning must include actionable guidance — clone locally, re-run [CS] Create Skill with the local path to regenerate provenance data, then re-run the update
-- Extraction proceeds using Quick tier strategy (source reading via gh_bridge)
+- Extraction proceeds using Quick tier strategy (source reading via gh_bridge — resolved as `gh api` commands or direct file I/O; see [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md))
 - All results labeled T1-low with `[SRC:...]` citations
 - The degradation reason is recorded in the evidence report