bmad-module-skill-forge 0.6.0 → 0.7.0

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-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/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.
 
 ---
 

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,6 +111,8 @@ 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)`
 - If branch not specified, detect default branch
@@ -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-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.
 
@@ -126,24 +126,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 +149,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 +209,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..."
 

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
 

package/src/workflows/create-skill/steps-c/step-07-generate-artifacts.md

@@ -9,7 +9,7 @@ forgeTierConfig: '{sidecar_path}/forge-tier.yaml'
 
 ## STEP GOAL:
 
-To write all compiled content to disk — 4 deliverable files to `skills/{name}/` and 3 workspace artifacts to `forge-data/{name}/`, creating directories as needed.
+To write all compiled content to disk — 4 deliverable files to `{skills_output_folder}/{name}/` and 3 workspace artifacts to `{forge_data_folder}/{name}/`, creating directories as needed.
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
@@ -30,7 +30,7 @@ To write all compiled content to disk — 4 deliverable files to `skills/{name}/
 
 - 🎯 Focus ONLY on writing files from the compiled content in context
 - 🚫 FORBIDDEN to modify content during writing — write exactly what was compiled
-- 🚫 FORBIDDEN to skip any artifact — all 7 files must be written
+- 🚫 FORBIDDEN to skip any artifact — all base artifact types must be written (4 deliverables + 3 workspace files + N reference files)
 - 💬 Report each file written with its path
 - 📁 Create directories before writing files
 
@@ -54,65 +54,66 @@ To write all compiled content to disk — 4 deliverable files to `skills/{name}/
 
 ### 1. Create Directory Structure
 
-Create the following directories at `{project-root}/`:
+Create the following directories:
 
 ```
-skills/{name}/
-skills/{name}/references/
-forge-data/{name}/
+{skills_output_folder}/{name}/
+{skills_output_folder}/{name}/references/
+{forge_data_folder}/{name}/
 ```
 
-If `scripts_inventory` is non-empty, also create: `skills/{name}/scripts/`
-If `assets_inventory` is non-empty, also create: `skills/{name}/assets/`
+If `scripts_inventory` is non-empty, also create: `{skills_output_folder}/{name}/scripts/`
+If `assets_inventory` is non-empty, also create: `{skills_output_folder}/{name}/assets/`
 
 Where `{name}` is the skill name from the brief (kebab-case).
 
 If directories already exist, do not error — proceed with file writing (overwrites existing files).
 
-### 2. Write Deliverables to skills/{name}/
+### 2. Write Deliverables to {skills_output_folder}/{name}/
 
 Write these 4 files from the compiled content:
 
-**File 1:** `skills/{name}/SKILL.md`
+**File 1:** `{skills_output_folder}/{name}/SKILL.md`
 - The complete compiled skill document
 - agentskills.io-compliant format with all sections
 - [MANUAL] markers seeded
 
-**File 2:** `skills/{name}/context-snippet.md`
+**File 2:** `{skills_output_folder}/{name}/context-snippet.md`
 - Compressed 2-line format for CLAUDE.md integration
 
-**File 3:** `skills/{name}/metadata.json`
+**File 3:** `{skills_output_folder}/{name}/metadata.json`
 - Machine-readable birth certificate with stats and provenance
 
-**File 4:** `skills/{name}/references/*.md`
+**File 4:** `{skills_output_folder}/{name}/references/*.md`
 - One file per function group or type
 - Progressive disclosure detail files
 
-**Files 4b (conditional):** `skills/{name}/scripts/*`
+**Files 4b (conditional):** `{skills_output_folder}/{name}/scripts/*`
 - One file per detected script, copied from source with content preserved
 - Only created when `scripts_inventory` is non-empty
 
-**Files 4c (conditional):** `skills/{name}/assets/*`
+**Files 4c (conditional):** `{skills_output_folder}/{name}/assets/*`
 - One file per detected asset, copied from source with content preserved
 - Only created when `assets_inventory` is non-empty
 
-### 3. Write Workspace Artifacts to forge-data/{name}/
+### 3. Write Workspace Artifacts to {forge_data_folder}/{name}/
 
 Write these 3 files from the compiled content:
 
-**File 5:** `forge-data/{name}/provenance-map.json`
+**File 5:** `{forge_data_folder}/{name}/provenance-map.json`
 - Per-claim source map with AST bindings and confidence tiers
 
-**File 6:** `forge-data/{name}/evidence-report.md`
+**File 6:** `{forge_data_folder}/{name}/evidence-report.md`
 - Build artifact with extraction summary, validation results, warnings
 
-**File 7:** `forge-data/{name}/extraction-rules.yaml`
+**File 7:** `{forge_data_folder}/{name}/extraction-rules.yaml`
 - Language and ast-grep schema used for this extraction (for reproducibility)
 
 ### 4. Verify Write Completion
 
 After all files are written, verify:
-- All 7 base files exist at their expected paths, plus scripts/ and assets/ files when inventories are non-empty
+- All 4 deliverable artifact types exist (SKILL.md, context-snippet.md, metadata.json, at least one file in references/), all 3 workspace artifacts exist (provenance-map.json, evidence-report.md, extraction-rules.yaml), plus scripts/ and assets/ files when inventories are non-empty
+- Store `ref_count` = count of files written to `references/` for use in step-08 report
 - List each file with its path and size
 
 **If any write failed:**
@@ -123,7 +124,7 @@ Display brief confirmation:
 
 "**Artifacts generated.**
 
-**Deliverables (skills/{name}/):**
+**Deliverables ({skills_output_folder}/{name}/):**
 - SKILL.md
 - context-snippet.md
 - metadata.json
@@ -131,7 +132,7 @@ Display brief confirmation:
 {if assets: - assets/ ({assets_count} files)}
 - references/ ({reference_count} files)
 
-**Workspace (forge-data/{name}/):**
+**Workspace ({forge_data_folder}/{name}/):**
 - provenance-map.json
 - evidence-report.md
 - extraction-rules.yaml
@@ -144,23 +145,13 @@ Proceeding to compilation report..."
 
 Index the generated skill artifacts into a QMD collection so that audit-skill and update-skill can perform high-signal searches against curated extraction data instead of raw source files.
 
-**Collection creation:**
-
-Create a QMD collection from both artifact directories:
-```bash
-qmd collection add {project-root}/skills/{name} --name {name}-extraction --mask "**/*"
-qmd embed
-```
-
-If collection already exists (re-run): remove and recreate for atomic replace:
+**Collection creation:** Create (or replace) a QMD collection from the skill artifacts:
 ```bash
-qmd collection remove {name}-extraction
-qmd collection add {project-root}/skills/{name} --name {name}-extraction --mask "**/*"
-qmd embed
+qmd collection remove {name}-extraction 2>/dev/null  # no-op if new
+qmd collection add {skills_output_folder}/{name} --name {name}-extraction --mask "**/*"
+qmd embed  # generates vector embeddings for vector_search/deep_search
 ```
 
-**Note:** `qmd embed` generates vector embeddings required for `vector_search` and `deep_search`. Without it, only BM25 keyword `search` works.
-
 **Registry update:**
 
 Read `{forgeTierConfig}` and update the `qmd_collections` array.
@@ -197,7 +188,7 @@ Dispatch to ccc CLI (`ccc index {source_root}`) or ccc MCP tool — `ccc_bridge.
 
 Read `{forgeTierConfig}` and update the `ccc_index_registry` array.
 
-Deduplicate by `source_repo` (the canonical upstream URL from brief_data) combined with `skill_name` — NOT by local `path`, which may be an ephemeral clone path that changes on every run for remote repos. If an entry with matching `source_repo` + `skill_name` already exists, replace it. Otherwise, append:
+Deduplicate by `source_repo` + `skill_name` (NOT local `path`, which may be ephemeral). Replace existing match or append:
 
 ```yaml
   - source_repo: "{brief.source_repo}"
@@ -209,11 +200,9 @@ Deduplicate by `source_repo` (the canonical upstream URL from brief_data) combin
 
 Write the updated forge-tier.yaml.
 
-**Error handling:**
-- If ccc indexing fails: log the error, continue. Do NOT fail the workflow.
-- If forge-tier.yaml update fails: log the error, continue.
+**Error handling:** If ccc indexing or registry update fails, log and continue — do NOT fail the workflow.
 
-**IF `tools.ccc` is false:** Skip this section silently. No messaging.
+**IF `tools.ccc` is false:** Skip this section silently.
 
 ### 6. Menu Handling Logic
 
@@ -239,9 +228,9 @@ ONLY WHEN all 7 artifact files are written and verified will you proceed to load
 
 ### ✅ SUCCESS:
 
-- Directory structure created (skills/{name}/, forge-data/{name}/)
-- All 4 deliverable files written to skills/{name}/
-- All 3 workspace artifact files written to forge-data/{name}/
+- Directory structure created ({skills_output_folder}/{name}/, {forge_data_folder}/{name}/)
+- All 4 deliverable files written to {skills_output_folder}/{name}/
+- All 3 workspace artifact files written to {forge_data_folder}/{name}/
 - Write completion verified — all 7 files exist
 - Deep tier: QMD collection `{name}-extraction` created/updated and registered in forge-tier.yaml
 - Non-Deep tier: QMD indexing skipped silently