bmad-module-skill-forge 0.6.0 → 0.7.1

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
 
@@ -82,7 +82,7 @@ Continue to section 2.
 ### 2. Query Original Knowledge Context
 
 Launch a subprocess (Pattern 3 — data operations) that:
-1. Loads the QMD collection for the project
+1. Read the `qmd_collections` registry from `{sidecar_path}/forge-tier.yaml`. Find the entry where `skill_name` matches `{skill_name}` AND `type` is `"extraction"`. Use the `name` field from that entry as the collection to query. If no matching entry exists, log: "No QMD extraction collection found for {skill_name}. Semantic diff skipped." → Auto-proceed to {nextStepFile}.
 2. Queries for knowledge context around each export documented in the skill
 3. Retrieves: usage patterns, conventions, architectural context, dependency relationships
 4. Returns structured findings to parent

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/audit-skill/workflow.md

@@ -2,7 +2,7 @@
 name: audit-skill
 description: "Drift detection. Forge tier: structural. Deep tier: full."
 web_bundle: true
-installed_path: '{project-root}/_bmad/skf/workflows/audit-skill'
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/audit-skill'
 ---
 
 # Audit Skill
@@ -57,6 +57,7 @@ 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`
 - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
+- Generate and store `timestamp` as the current date-time in `YYYYMMDD-HHmmss` format. This value is fixed for the entire workflow run and must not be regenerated in subsequent steps.
 
 ### 2. First Step Execution
 

package/src/workflows/brief-skill/data/scope-templates.md

@@ -59,6 +59,16 @@ Prompt: "Which of these would you like to include? (Enter numbers, or 'all'):"
 Exclusions will include all internal implementation files, tests, and utilities.
 Prompt: "Any additional items you'd like to include or exclude?"
 
+### Docs-Only Boundaries
+
+**No source code access.** Scope is defined by the `doc_urls` collected during intent gathering.
+
+- All content derived from external documentation
+- No include/exclude patterns — coverage determined by fetched documentation
+- All extractions labeled T3 (`[EXT:{url}]` citations)
+
+Prompt: "Any additional documentation URLs to include? Or URLs to exclude from the ones collected?"
+
 ## Scripts & Assets Detection (Optional Refinement)
 
 When `scripts_intent` or `assets_intent` is `detect` (default), SKF auto-detects from source directories matching: `scripts/`, `bin/`, `tools/`, `cli/` (for scripts) and `assets/`, `templates/`, `schemas/`, `configs/`, `examples/` (for assets). Detection applies to all scope types except `docs-only`.

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

@@ -2,26 +2,27 @@
 
 ## Required Fields
 
-| Field | Type | Description | Validation |
-|-------|------|-------------|------------|
-| name | string | Kebab-case skill name | Must match `[a-z0-9-]+` |
-| version | string | Semantic version | Must match `X.Y.Z` pattern. Auto-detect from source (see Version Detection below), fall back to "1.0.0" |
-| source_repo | string | GitHub URL or local path | Must be accessible |
-| language | string | Primary programming language | Must be detected or user-specified |
-| scope | object | Inclusion/exclusion boundaries | Must have type + at least one pattern |
-| description | string | What this skill covers | 1-3 sentences |
-| forge_tier | string | Compilation tier | One of: quick, forge, forge+, deep |
-| created | string | Creation date | ISO date format |
-| created_by | string | User who created the brief | From config user_name |
+| Field | Type | Constraint | Description |
+|-------|------|------------|-------------|
+| name | string | kebab-case `[a-z0-9-]+` | Unique skill identifier |
+| version | string | Semantic `X.Y.Z` | Auto-detect from source (see Version Detection below), fall back to `1.0.0` |
+| source_repo | string | GitHub URL or local path | Repository or project root (optional when `source_type: "docs-only"`) |
+| language | string | Recognized language | Primary programming language |
+| scope | object | See Scope Object below | Boundary definition |
+| description | string | 1-3 sentences | What the skill covers |
+| forge_tier | string | `Quick` / `Forge` / `Forge+` / `Deep` | Inherited from forge-tier.yaml (Title Case) |
+| created | string | ISO date `YYYY-MM-DD` | Generation date |
+| created_by | string | user_name from config | Who generated the brief |
 
 ## Optional Fields
 
-| Field | Type | Description | Validation |
-|-------|------|-------------|------------|
-| source_type | string | Source mode: `source` or `docs-only` | Default `source`. When `docs-only`: `source_repo` optional, `doc_urls` required |
-| doc_urls | array | Documentation URLs for T3 content | Each entry: `{url, label}`. Required when `source_type: "docs-only"` |
-| `scripts_intent` | string | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
-| `assets_intent` | string | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/"). |
+| Field | Type | Constraint | Description |
+|-------|------|------------|-------------|
+| source_type | string | `source` or `docs-only` | Default `source`. When `docs-only`: `source_repo` optional, `doc_urls` required |
+| doc_urls | array | `{url, label}` objects | Documentation URLs for T3 content. Required when `source_type: "docs-only"` |
+| `scripts_intent` | string | `detect` / `none` / free-text | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
+| `assets_intent` | string | `detect` / `none` / free-text | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/"). |
+| `source_authority` | string | `official` / `community` / `internal` | Default `community`. Set to `official` only when the skill creator is the library maintainer. Forced to `community` when `source_type: "docs-only"`. |
 
 When `source_type: "docs-only"`:
 - `source_repo` becomes optional (set to doc site URL for reference)
@@ -48,7 +49,7 @@ The create-skill workflow (step-03-extract) also performs version reconciliation
 
 ```yaml
 scope:
-  type: full-library | specific-modules | public-api
+  type: full-library | specific-modules | public-api | docs-only
   include:
     - "src/**/*.ts"           # Glob patterns for included files/directories
   exclude:
@@ -67,7 +68,7 @@ source_type: "source"                    # "source" (default) or "docs-only"
 source_repo: "{github-url-or-local-path}"
 language: "{detected-language}"
 description: "{brief-description}"
-forge_tier: "{quick|forge|forge+|deep}"
+forge_tier: "{Quick|Forge|Forge+|Deep}"
 created: "{date}"
 created_by: "{user_name}"
 scope:
@@ -83,12 +84,13 @@ scope:
 #     label: "API Reference"
 # scripts_intent: detect         # Optional: detect | none | description
 # assets_intent: detect          # Optional: detect | none | description
+# source_authority: community    # Optional: official | community | internal
 ---
 ```
 
 ## Human-Readable Presentation Format
 
-When presenting the brief for confirmation (step 04), display as:
+When presenting the brief for confirmation (brief-skill step 04 only — not applicable to analyze-source batch generation), display as:
 
 ```
 Skill Brief: {name}
@@ -114,8 +116,8 @@ Created by: {created_by}
 1. `name` must be unique within {forge_data_folder}
 2. `source_repo` must be accessible (gh api for GitHub, path exists for local)
 3. `language` must be a recognized programming language
-4. `scope.type` must be one of the three defined types
-5. `scope.include` must have at least one pattern
-6. `forge_tier` must be one of: quick, forge, forge+, deep (must match the tier from forge-tier.yaml, or default to quick)
+4. `scope.type` must be one of the four defined types
+5. `scope.include` must have at least one pattern (exception: `docs-only` scope, where include patterns are optional since no source code is available)
+6. `forge_tier` must be one of: Quick, Forge, Forge+, Deep (Title Case, must match the tier from forge-tier.yaml, or default to Quick)
 7. When `source_type: "docs-only"`: `doc_urls` must have >= 1 entry, `source_repo` becomes optional
 8. Each `doc_urls` entry must have a valid `url` field

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

@@ -68,7 +68,7 @@ Attempt to load `{forgeTierFile}`:
 
 **If not found:**
 - Display: "**Note:** No forge tier configuration found. Defaulting to Quick tier. Run **setup-forge** first for full capabilities."
-- Default to: `forge_tier: quick`
+- Default to: `forge_tier: Quick`
 
 ### 2. Welcome and Explain
 

package/src/workflows/brief-skill/steps-c/step-02-analyze-target.md

@@ -135,7 +135,7 @@ 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)`.
+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).
 
 If results are returned, display:
 

package/src/workflows/brief-skill/steps-c/step-05-write-brief.md

@@ -91,6 +91,9 @@ scope:
 # 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
 ---
 ```
 

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
 

package/src/workflows/create-skill/data/skill-sections.md

@@ -132,6 +132,12 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
     "qmd": "{version-or-null}",
     "skf": "{skf_version}"
   },
+  "confidence_distribution": {
+    "t1": 0,
+    "t1_low": 0,
+    "t2": 0,
+    "t3": 0
+  },
   "stats": {
     "exports_documented": 0,
     "exports_public_api": 0,
@@ -139,18 +145,13 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
     "exports_total": 0,
     "public_api_coverage": 0.0,
     "total_coverage": 0.0,
-    "confidence_t1": 0,
-    "confidence_t2": 0,
-    "confidence_t3": 0,
     "scripts_count": 0,
     "assets_count": 0
   },
-  "scripts": [
-    { "file": "scripts/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }
-  ],
-  "assets": [
-    { "file": "assets/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }
-  ],
+  // scripts[] and assets[] — include ONLY when inventories are non-empty; omit entirely otherwise
+  // "scripts": [{ "file": "scripts/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],
+  // "assets": [{ "file": "assets/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],
+  "generated_by": "{quick-skill|create-skill}",
   "dependencies": [],
   "compatibility": "{semver-range}"
 }
@@ -197,7 +198,7 @@ Each reference file includes:
       "source_file": "src/auth/index.ts",
       "source_line": 42,
       "confidence": "T1",
-      "extraction_method": "ast_bridge.scan_definitions",
+      "extraction_method": "ast-grep",
       "ast_node_type": "export_function_declaration"
     }
   ],
@@ -235,7 +236,7 @@ Each reference file includes:
 ## Extraction Summary
 - Files scanned: {count}
 - Exports found: {count}
-- Confidence: T1={n}, T2={n}, T3={n}
+- Confidence: T1={n}, T1-low={n}, T2={n}, T3={n}
 
 ## Validation Results
 - Schema: {pass/fail}

package/src/workflows/create-skill/data/source-resolution-protocols.md

@@ -112,7 +112,7 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
 
    Proceed with Quick tier extraction strategy below. Note the degradation reason in context for the evidence report.
 
-**Ephemeral clone cleanup:** After extraction is complete for all files in scope (whether successful or partially failed), before presenting the Gate 2 summary (Section 6), if `ephemeral_clone_active`, delete the `{temp_path}` directory. Log: "Ephemeral source clone cleaned up." This ensures cleanup runs even if some extractions failed, as long as the step itself is still executing.
+**Ephemeral clone cleanup:** After extraction is complete for all files in scope (whether successful or partially failed), before presenting the Gate 2 summary (Section 6), if `ephemeral_clone_active`, delete the `{temp_path}` directory. Log: "Ephemeral source clone cleaned up." This ensures cleanup runs even if some extractions failed, as long as the step itself is still executing. **If any error halts the extraction step before Gate 2 is reached**, cleanup must still occur: attempt to delete `{temp_path}` before halting. Log the cleanup attempt regardless of success.
 
 ---
 
@@ -135,4 +135,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
 

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

@@ -2,8 +2,8 @@
 name: 'step-01-load-brief'
 description: 'Load skill-brief.yaml, validate structure, resolve source code location, load forge tier'
 nextStepFile: './step-02-ecosystem-check.md'
-forgeTierFile: '{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml'
-preferencesFile: '{project-root}/_bmad/_memory/forger-sidecar/preferences.yaml'
+forgeTierFile: '{sidecar_path}/forge-tier.yaml'
+preferencesFile: '{sidecar_path}/preferences.yaml'
 ---
 
 # Step 1: Load Brief
@@ -70,14 +70,14 @@ Extract and report:
 ### 2. Discover Skill Brief
 
 **If user provided a specific brief path or skill name:**
-- Search `{project-root}/forge-data/{skill-name}/skill-brief.yaml`
+- If the value looks like a file path (starts with `/`, `./`, `~`, or contains path separators): treat it as a direct file path and load it
+- Otherwise, treat it as a skill name and search `{forge_data_folder}/{skill-name}/skill-brief.yaml`
 - If found, load it completely
 
 **If user invoked with --batch flag:**
-- Search specified directory for all `skill-brief.yaml` files
-- List discovered briefs with skill names
-- Store list for batch loop processing
-- For this run, load the FIRST brief (batch loops back for remaining)
+- Check `{sidecar_path}/batch-state.yaml` for an active batch checkpoint:
+  - If `batch_active: true` and `current_index` is valid: load the brief at `brief_list[current_index]` (resuming a batch loop from step-08)
+  - If no checkpoint exists or `batch_active` is false: search specified directory for all `skill-brief.yaml` files, list discovered briefs with skill names, store list for batch loop processing, and load the FIRST brief
 
 **If no brief found:**
 Halt with: "No skill brief found. Run [BS] Brief Skill to create one, or use [QS] Quick Skill for brief-less generation."
@@ -101,6 +101,8 @@ Check that the loaded skill-brief.yaml contains required fields:
 - `include_patterns` — file glob patterns to include
 - `exclude_patterns` — file glob patterns to exclude
 - `description` — human description of the skill
+- `scripts_intent` — `"none"` to skip scripts detection, omit for default auto-detection
+- `assets_intent` — `"none"` to skip assets detection, omit for default auto-detection
 
 **Docs-only validation:** When `source_type: "docs-only"`, `source_repo` is not required but `doc_urls` must have at least one entry. `source_authority` is forced to `community`.
 
@@ -109,8 +111,10 @@ 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_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
 
@@ -140,7 +144,7 @@ Where tier_description follows positive capability framing:
 - Quick: "Source reading and spec validation"
 - Forge: "AST-backed structural extraction"
 - Forge+: "Semantic-guided precision — ccc pre-ranks files before AST extraction"
-- Deep: "Full intelligence — structural + contextual + temporal"
+- Deep: "Full intelligence — structural + contextual + QMD knowledge synthesis"
 
 ### 6. Menu Handling Logic
 
@@ -166,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
+- Source code location resolved and accessible (or `source_location: 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

@@ -75,6 +75,8 @@ Read `ccc_index` from forge-tier.yaml:
 - 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_status from step-02
+- Available: brief_data, tier, source_location, 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)
@@ -75,7 +75,7 @@ Build the filtered file list from the source tree resolved in step-01. Record th
 
 "**Docs-only mode:** No source code to extract. Documentation content will be fetched from `doc_urls` in step-03c."
 
-Build an empty extraction inventory with zero exports. Set `extraction_mode: "docs-only"` in context. Auto-proceed through Gate 2 (section 5) — display the empty inventory and note that T3 content will be produced by the doc-fetcher step.
+Build an empty extraction inventory with zero exports. Set `extraction_mode: "docs-only"` in context. Auto-proceed through Gate 2 (section 6) — display the empty inventory and note that T3 content will be produced by the doc-fetcher step.
 
 **If `source_type: "source"` (default):** Continue with extraction below.
 
@@ -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."
@@ -126,24 +130,21 @@ Degrade to Quick tier extraction. Note the degradation reason in context for the
 - If a file cannot be read: log warning, skip file, continue with remaining files
 - If AST parsing fails on a file: fall back to source reading for that file, continue
 
-**Re-export tracing (Forge/Deep only):**
-
-After the initial AST scan, check for public exports from the entry point (`__init__.py`, `index.ts`, `lib.rs`) that were NOT found by AST extraction. These are likely module-level re-exports. Follow the **Re-Export Tracing** protocol in `{extractionPatternsTracingData}` to resolve them to their actual definition files. This ensures module re-export patterns (common in Python libraries with clean public APIs) do not create gaps in the extraction inventory.
+**Re-export tracing (Forge/Deep only):** After the initial AST scan, check for unresolved public exports from entry points (`__init__.py`, `index.ts`, `lib.rs`). Follow the **Re-Export Tracing** protocol in `{extractionPatternsTracingData}` to resolve them to their definition files.
 
 ### 4b. Validate Exports Against Package Entry Point
 
 After extraction, validate the collected exports against the package's actual public API surface:
 
-- **Python:** Read `{source_root}/__init__.py` — extract all import statements to build the actual public export list. Compare against AST-extracted exports:
-  - In AST results but not in `__init__.py` → mark as internal (exclude from `metadata.json` exports, keep in provenance-map with a note)
-  - In `__init__.py` but not in AST results → flag as extraction gap (add to inventory, trace via re-export protocol)
-- **TypeScript/JavaScript:** Read `index.ts`/`index.js` — extract named exports. Same comparison logic.
-- **Rust:** Read `lib.rs` — extract `pub use` items. Same comparison logic.
-- **Go:** Scan package-level files for exported (capitalized) identifiers.
+- **Python:** Read `{source_root}/__init__.py` — extract imports to build the public export list. Compare against AST results:
+  - In AST but not entry point → mark as internal (exclude from `metadata.json` exports)
+  - In entry point but not AST → flag as extraction gap (trace via re-export protocol)
+- **TypeScript/JS:** Read `index.ts`/`index.js` — same comparison logic.
+- **Rust:** Read `lib.rs` — extract `pub use` items. Same logic. **Go:** Scan for exported (capitalized) identifiers.
 
-Use the entry point as the authoritative source for `metadata.json`'s `exports[]` array. This prevents internal symbols from inflating the exports list and ensures all public API items are captured.
+Use the entry point as the authoritative source for `metadata.json`'s `exports[]` array.
 
-**If entry point is missing or unreadable:** Skip validation with a warning. Use the AST-extracted list as-is.
+**If entry point is missing or unreadable:** Skip validation with a warning.
 
 ### 4c. Detect and Inventory Scripts/Assets
 
@@ -152,10 +153,8 @@ Use the entry point as the authoritative source for `metadata.json`'s `exports[]
 After export extraction, scan the source for scripts and assets using the detection patterns in `{extractionPatternsTracingData}`:
 
 1. Scan source tree for directories/files matching detection heuristics (scripts/, bin/, tools/, cli/ for scripts; assets/, templates/, schemas/, configs/, examples/ for assets)
-2. For each candidate: verify file exists, check size (flag if >500 lines for user confirmation), exclude binary files
-3. Compute SHA-256 content hash for each included file
-4. Extract purpose from file header comments, shebang, README references, or schema `title`/`description` fields. If no purpose found, use filename.
-5. Record: file_path, purpose, source_path, language (for scripts), type (for assets), content_hash, confidence (T1-low)
+2. For each candidate: verify existence, check size (flag >500 lines), exclude binaries, compute SHA-256 hash
+3. Extract purpose from header comments, shebang, README references, or schema fields. Record: file_path, purpose, source_path, language/type, content_hash, confidence (T1-low)
 
 Add results to `scripts_inventory[]` and `assets_inventory[]` alongside the existing export inventory.
 
@@ -214,8 +213,9 @@ Display: "**Extraction Summary — Select an Option:** [C] Continue to compilati
 
 #### EXECUTION RULES:
 
-- ALWAYS halt and wait for user input after presenting the extraction summary
-- This is Gate 2 — user must confirm before compilation proceeds
+- IF docs-only mode (`extraction_mode: "docs-only"`): Auto-proceed immediately to `{nextStepFile}` — no user interaction required
+- OTHERWISE: ALWAYS halt and wait for user input after presenting the extraction summary
+- This is Gate 2 — user must confirm before compilation proceeds (except docs-only mode)
 - User may ask questions about the extraction results before continuing
 
 #### Menu Handling Logic:

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

@@ -43,7 +43,7 @@ To fetch temporal context (issues, PRs, changelogs, release notes) from the sour
 ## CONTEXT BOUNDARIES:
 
 - Available: brief_data, tier, source_location from step-01; extraction_inventory from step-03
-- **Used from extraction_inventory:** `top_exports[]` — the list of top-level public API function names (typically 10-20). Used for targeted GitHub searches (section 3b).
+- **Used from extraction_inventory:** `top_exports[]` — the list of top-level public API function names (typically 10-20). Used for targeted GitHub searches (section 3b). If `extraction_mode: "docs-only"` or `top_exports` is absent/empty, skip targeted searches silently.
 - Focus: Creating a QMD temporal collection for the source repository
 - Limits: Do NOT modify extraction data, begin enrichment, or compile content
 - Dependencies: Extraction must be complete from step-03
@@ -208,7 +208,7 @@ After temporal context is fetched and indexed (or skipped for any reason), immed
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN temporal context is indexed into QMD (or the step is skipped due to eligibility, cache, or failure) will you proceed to load `{nextStepFile}` for QMD enrichment.
+ONLY WHEN temporal context is indexed into QMD (or the step is skipped due to eligibility, cache, or failure) will you proceed to load `{nextStepFile}` for documentation fetch.
 
 ---
 
@@ -224,7 +224,7 @@ ONLY WHEN temporal context is indexed into QMD (or the step is skipped due to el
 - Collection `{skill-name}-temporal` indexed into QMD
 - Registry entry added/updated in forge-tier.yaml with type `"temporal"`
 - Staging directory cleaned up after indexing
-- Auto-proceeded to step-04
+- Auto-proceeded to step-03c
 
 ### ❌ SYSTEM FAILURE:
 

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

@@ -85,7 +85,9 @@ 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 — a page is a root if BOTH conditions are true:**
+**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.**
+
+**A page is classified as a root if BOTH conditions are 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).

package/src/workflows/create-skill/steps-c/step-04-enrich.md

@@ -70,7 +70,7 @@ Before searching, check which QMD collections are available:
 3. **If no enrichment collections exist** (no `"temporal"` or `"docs"` type collections): report this and auto-proceed. Display:
 
 "**Enrichment: no enrichment collections available.**
-Only brief-type or extraction-type QMD collections found — no temporal context (issues, PRs, changelogs) or docs collections indexed. Enrichment skipped (expected for first-run skill creation). Enrichment becomes available when temporal or docs context is indexed into QMD collections.
+Only brief-type or extraction-type QMD collections found — no temporal context (issues, PRs, changelogs) or docs collections indexed. {IF extraction_mode is 'docs-only' AND T3 items exist in extraction_inventory: 'T3 documentation content is available in extraction inventory — enrichment via QMD is skipped but T3 content will be compiled.'} {ELSE: 'Enrichment skipped (expected for first-run skill creation). Enrichment becomes available when temporal or docs context is indexed into QMD collections.'}
 
 Proceeding to compilation..."
 
@@ -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

@@ -39,7 +39,7 @@ To assemble the complete skill content from the extraction inventory and enrichm
 ## EXECUTION PROTOCOLS:
 
 - 🎯 Follow MANDATORY SEQUENCE exactly
-- 💾 Build all content in context or write to a staging directory (`_bmad-output/{name}/`)
+- 💾 Build all content in context AND write to the staging directory (`_bmad-output/{name}/`) — staging write is mandatory for step-06 validation
 - 📖 Follow agentskills.io section structure from data file
 - 🚫 Do not promote any output files to final `skills/` or `forge-data/` directories — that's step-07
 
@@ -100,7 +100,8 @@ 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 SKF module's `package.json` `version` field (run `node -p "require('./node_modules/bmad-module-skill-forge/package.json').version"` or read the installed module's `package.json`). If unresolvable, fall back to `git describe --tags --abbrev=0` in the SKF module root. Never hardcode the version.
+- 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.
+- 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.
 
 ### 5. Build references/ Content
@@ -119,7 +120,7 @@ One entry per extracted export: export_name, export_type, params[] (typed string
 
 ### 7. Build evidence-report.md Content
 
-Compilation audit trail: generation date, forge tier, source info, tool versions, extraction summary (files/exports/confidence), validation results (populated in step-06), warnings. See `{skillSectionsData}` for full template. Use the same `{skf_version}` value resolved in section 4 when populating the Tool Versions block.
+Compilation audit trail: generation date, forge tier, source info, tool versions, extraction summary (files/exports/confidence), warnings. For validation-specific fields (Schema, Body, Security, Content Quality, tessl, Metadata), insert the placeholder text `[PENDING — populated by step-06]`. Step-06 will replace these placeholders with actual results. See `{skillSectionsData}` for full template. Use the same `{skf_version}` value resolved in section 4 when populating the Tool Versions block.
 
 ### 8. Menu Handling Logic
 

package/src/workflows/create-skill/steps-c/step-06-validate.md

@@ -125,7 +125,7 @@ npx skill-check check <staging-skill-dir> --format json
 
 (Security scan enabled by default when `--no-security-scan` omitted. The scan uses [Snyk Agent Scan](https://github.com/snyk/agent-scan) to check for prompt injection risks, sensitive data exposure, and unsafe tool permissions.)
 
-Record any security warnings in evidence-report. Security findings are advisory — they do not block artifact generation.
+Record any security warnings in evidence-report. Security findings are advisory — they do not block artifact generation. If the full validation re-run produces a different quality score than section 2, update the evidence-report with the newer score.
 
 **If security scan fails due to missing SNYK_TOKEN:**
 
@@ -181,7 +181,7 @@ tessl suggestions:
 Cross-check metadata.json against extraction inventory:
 - `stats.exports_documented` / `stats.exports_public_api` / `stats.exports_internal` / `stats.exports_total` are accurate
 - `stats.public_api_coverage` and `stats.total_coverage` are correctly computed (null when denominator is 0)
-- `confidence_t1`, `confidence_t2`, `confidence_t3` match actual counts
+- `confidence_distribution.t1`, `confidence_distribution.t1_low`, `confidence_distribution.t2`, `confidence_distribution.t3` match actual counts
 - `spec_version` is "1.3"
 - If `scripts[]` or `assets[]` arrays present: verify `stats.scripts_count`/`stats.assets_count` match array lengths; verify `file_entries` count in provenance-map.json matches