bmad-module-skill-forge 0.2.0 → 0.4.0

package/src/workflows/quick-skill/steps-c/step-05-validate.md

@@ -53,7 +53,43 @@ To validate the compiled SKILL.md, context-snippet.md, and metadata.json against
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
 
-### 1. Validate SKILL.md Structure
+### 1. Check Tool Availability
+
+Run: `npx skill-check -h`
+
+- If succeeds (returns usage information): Continue to automated validation (section 2)
+- If fails (command not found or error): Skip to manual fallback in section 2
+
+**Important:** Use the verification command. Do not assume availability — empirical check required.
+
+### 2. Validate SKILL.md via skill-check (if available)
+
+**If `npx skill-check` is available**, run automated validation with auto-fix:
+
+```bash
+npx skill-check check <skill-dir> --fix --format json --no-security-scan
+```
+
+This validates frontmatter, description, body limits, links, and formatting — and auto-fixes deterministic issues (field ordering, slug format, required fields, trailing newlines).
+
+**Parse JSON output** to extract:
+- `qualityScore` — overall score (0-100)
+- `diagnostics[]` — remaining issues after auto-fix
+- `fixed[]` — issues automatically corrected
+
+Record quality score and any remaining diagnostics as validation issues.
+
+**If skill-check is NOT available**, perform manual frontmatter check:
+
+- [ ] **Frontmatter present** — file starts with `---` delimiter and has closing `---`
+- [ ] **`name` field** — present, non-empty, lowercase alphanumeric + hyphens only, 1-64 chars
+- [ ] **`name` matches directory** — frontmatter `name` matches the skill output directory name
+- [ ] **`description` field** — present, non-empty, 1-1024 characters
+- [ ] **No unknown fields** — only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` are permitted
+
+**For each violation, log an issue.** Missing frontmatter or missing required fields are high-severity issues — skills without valid frontmatter will fail `npx skills add` and `npx skill-check check`.
+
+### 3. Validate SKILL.md Body Structure
 
 Check that SKILL.md has these required sections populated:
 
@@ -64,39 +100,58 @@ Check that SKILL.md has these required sections populated:
 
 **For each missing or empty required section, log an issue.**
 
-### 2. Validate Context Snippet Format
+### 4. Validate Context Snippet Format
 
 Check context-snippet.md format compliance:
 
-- [ ] **Two-line format** — first line has skill name and exports, second line has path pointer
-- [ ] **First line** matches pattern: `{name}: {exports list}`
-- [ ] **Second line** matches pattern: `  → {path}/SKILL.md`
-- [ ] **Approximate token count** is ~30 tokens or less
+- [ ] **Vercel-aligned indexed format** — pipe-delimited with version, retrieval instruction, section anchors
+- [ ] **First line** matches pattern: `[{name} v{version}]|root: skills/{name}/`
+- [ ] **Second line** starts with: `|IMPORTANT:`
+- [ ] **Approximate token count** is ~80-120 tokens
 
 **If format is wrong, log an issue.**
 
-### 3. Validate Metadata JSON
+### 5. Validate Metadata JSON
 
 Check metadata.json has required fields:
 
 - [ ] `name` — present, non-empty
-- [ ] `version` — present (should be "0.1.0")
+- [ ] `version` — present (auto-detected or "0.1.0")
 - [ ] `source_authority` — must be "community"
 - [ ] `source_repo` — present, valid GitHub URL
 - [ ] `language` — present, non-empty
 - [ ] `generated_by` — must be "quick-skill"
-- [ ] `generated_date` — present
-- [ ] `exports_count` — present, number
-- [ ] `confidence` — present
+- [ ] `generation_date` — present
+- [ ] `stats.exports_documented` — present, number
+- [ ] `stats.exports_public_api` — present, number
+- [ ] `stats.exports_total` — present, number
+- [ ] `stats.public_api_coverage` — present, number
+- [ ] `stats.total_coverage` — present, number
+- [ ] `confidence_tier` — present
 
 **For each missing or invalid field, log an issue.**
 
-### 4. Report Validation Results
+### 6. Security Scan (if skill-check available)
+
+Run security scan on the compiled skill:
+
+```bash
+npx skill-check check <skill-dir> --format json
+```
+
+(Security scan is enabled by default when `--no-security-scan` is omitted.)
+
+Record any security findings as advisory warnings. Security issues do not block output.
+
+**If skill-check unavailable:** Skip with note in validation results.
+
+### 7. Report Validation Results
 
 "**Validation complete:**
 
-**SKILL.md:** {pass/issues found}
+**SKILL.md:** {pass/issues found} (quality score: {score}/100 if skill-check was available)
 {list any issues}
+{list any auto-fixed issues}
 
 **context-snippet.md:** {pass/issues found}
 {list any issues}
@@ -104,6 +159,9 @@ Check metadata.json has required fields:
 **metadata.json:** {pass/issues found}
 {list any issues}
 
+**Security:** {pass/warn/skipped}
+{list any security findings}
+
 **Overall:** {pass / N issues found}
 
 {If issues found:}
@@ -111,9 +169,9 @@ These issues are advisory for community-tier skills. You can proceed to write ou
 
 **Proceeding to write output...**"
 
-Set `validation_result` with pass/fail status and issues list.
+Set `validation_result` with pass/fail status, quality score, and issues list.
 
-### 5. Auto-Proceed to Write
+### 8. Auto-Proceed to Write
 
 #### Menu Handling Logic:
 
@@ -134,10 +192,14 @@ ONLY WHEN validation checks are complete and results reported will you load and
 
 ### ✅ SUCCESS:
 
+- `npx skill-check check --fix --format json` executed if available (or manual fallback)
+- Quality score (0-100) captured when skill-check available
+- Auto-fix applied via `--fix` for deterministic issues
+- Security scan executed (or skipped with note)
 - All three outputs validated against requirements
 - Issues reported clearly with specific details
 - Community-tier validation applied (not official-tier strictness)
-- validation_result set with pass/fail and issues list
+- validation_result set with pass/fail, quality score, and issues list
 - Auto-proceeding to write step
 
 ### ❌ SYSTEM FAILURE:
@@ -146,5 +208,6 @@ ONLY WHEN validation checks are complete and results reported will you load and
 - Blocking output on validation issues (advisory only)
 - Skipping validation checks
 - Not reporting found issues
+- Not recording quality score when skill-check is available
 
 **Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/quick-skill/validation-report.md

@@ -190,13 +190,13 @@ None.
 ### Document Production
 
 - **Produces documents:** Yes — multi-file output (SKILL.md, context-snippet.md, metadata.json)
-- **Template type:** Structured (SKILL.md sections) + Strict (snippet two-line format, metadata JSON schema)
+- **Template type:** Structured (SKILL.md sections) + Strict (snippet ADR-L v2 format, metadata JSON schema)
 - **Template location:** data/skill-template.md — serves as reference guide for section structure and format specifications
 
 ### Template Assessment
 
 - ✅ data/skill-template.md exists and defines required/optional sections for SKILL.md
-- ✅ Defines ADR-L two-line format for context-snippet.md
+- ✅ Defines ADR-L v2 format for context-snippet.md
 - ✅ Defines JSON schema for metadata.json with required fields
 - ✅ Template type matches design (structured + strict)
 - Note: No templates/ folder — template is in data/ because it's a reference guide, not a progressively-filled document template
@@ -243,7 +243,7 @@ No dedicated steps-v/ folder (create-only lifecycle, by design).
 
 **Inline validation:** step-05-validate.md provides advisory community-tier validation:
 - ✅ Checks SKILL.md required sections
-- ✅ Checks context-snippet.md format (two-line ADR-L)
+- ✅ Checks context-snippet.md format (ADR-L v2)
 - ✅ Checks metadata.json required fields
 - ✅ Reports issues without blocking (advisory)
 - ✅ Auto-proceeds to write step regardless of findings
@@ -449,7 +449,7 @@ None.
 | Input: language hint (optional) | Optional | step-01 accepts, overrides detection | ✅ |
 | Input: scope hint (optional) | Optional | step-01 accepts, step-03 uses for focused reading | ✅ |
 | Output: SKILL.md | Structured sections | step-04 assembles from template, step-06 writes | ✅ |
-| Output: context-snippet.md | ADR-L two-line | step-04 generates, step-05 validates format | ✅ |
+| Output: context-snippet.md | ADR-L v2 | step-04 generates, step-05 validates format | ✅ |
 | Output: metadata.json | Strict JSON schema | step-04 generates, step-05 validates fields | ✅ |
 | Instruction style: prescriptive | Prescriptive pipeline | All steps use mandatory sequences, forbidden rules | ✅ |
 

package/src/workflows/quick-skill/workflow-plan-quick-skill.md

@@ -156,7 +156,7 @@ Document-producing workflow generating three files:
 - Type: multi-file document output
 - Files:
   - `{skills_output_folder}/{name}/SKILL.md` — structured template following agentskills.io spec sections
-  - `{skills_output_folder}/{name}/context-snippet.md` — strict two-line format per ADR-L (~30 tokens)
+  - `{skills_output_folder}/{name}/context-snippet.md` — ADR-L v2 format (~50-80 tokens)
   - `{skills_output_folder}/{name}/metadata.json` — strict JSON with `source_authority: community`
 - Format: structured (SKILL.md), strict (context-snippet.md, metadata.json)
 - Frequency: single run per skill
@@ -165,7 +165,7 @@ Document-producing workflow generating three files:
 - Package/URL successfully resolved to GitHub repo source
 - Public exports documented (best-effort, may be incomplete)
 - Valid SKILL.md with core sections populated
-- context-snippet.md in correct two-line format
+- context-snippet.md in correct ADR-L v2 format
 - metadata.json with `source_authority: community` and required fields
 - No ecosystem duplicate if official skill already exists (user chose to proceed)
 
@@ -277,14 +277,14 @@ quick-skill/
 **Step 04 — compile (Checkpoint):**
 - Load skill-template.md from data/
 - Assemble SKILL.md from extraction_inventory
-- Generate context-snippet.md in two-line format (ADR-L, ~30 tokens)
+- Generate context-snippet.md in ADR-L v2 format (~50-80 tokens)
 - Generate metadata.json with source_authority: community
 - Present compiled SKILL.md for review
 - [C] Continue to validation
 
 **Step 05 — validate (Auto-proceed):**
 - Check SKILL.md has required sections populated
-- Check context-snippet.md format compliance (two-line)
+- Check context-snippet.md format compliance (ADR-L v2)
 - Check metadata.json has required fields
 - Community-tier validation (lighter than official)
 - Report any gaps/issues

package/src/workflows/quick-skill/workflow.md

@@ -9,6 +9,8 @@ installed_path: '{project-root}/_bmad/skf/workflows/quick-skill'
 
 **Goal:** The fastest path to a skill — accept a GitHub URL or package name, resolve to source, extract public API surface, and produce a best-effort SKILL.md with context snippet and metadata. No brief needed.
 
+> **Note:** Quick Skill is tier-unaware by design. It does not load forge-tier.yaml or check preferences.yaml for tier_override. All output is produced at community-tier quality regardless of available tools.
+
 **Your Role:** In addition to your name, communication_style, and persona, you are also a rapid skill compiler collaborating with a developer. This is a partnership, not a client-vendor relationship. You bring source analysis and skill document assembly expertise, while the user brings the target package or repository they want to create a skill for. Work together efficiently — speed is the priority.
 
 ---

package/src/workflows/setup-forge/steps-c/step-01-detect-and-tier.md

@@ -86,7 +86,16 @@ Run: `qmd status`
 - If succeeds and indicates operational: record `{qmd: true}`
 - If fails or indicates not initialized: record `{qmd: false}`
 
-### 6. Calculate Tier
+### 6. Check Optional: Security Scan (SNYK_TOKEN)
+
+Check if the `SNYK_TOKEN` environment variable is set:
+
+- If `SNYK_TOKEN` is non-empty: record `{security_scan: true}`
+- If `SNYK_TOKEN` is empty or unset: record `{security_scan: false}`
+
+This is informational only — security scan availability does NOT affect the tier level. It is recorded in forge-tier.yaml so that create-skill's validation step can report actionable guidance when security scanning is unavailable.
+
+### 7. Calculate Tier
 
 **If `{tier_override}` is set and valid (Quick, Forge, or Deep):**
 - Use `{tier_override}` as `{calculated_tier}`
@@ -99,7 +108,7 @@ Run: `qmd status`
 
 **If `{tier_override}` is set but invalid:** ignore it, use detected tier, flag for warning in report.
 
-### 7. Auto-Proceed
+### 8. Auto-Proceed
 
 "**Proceeding to write configuration...**"
 
@@ -114,7 +123,7 @@ Run: `qmd status`
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN all 3 tools have been verified and the tier has been calculated will you load and read fully `{nextStepFile}` to execute the configuration write step.
+ONLY WHEN all 3 core tools have been verified, optional security scan checked, and the tier calculated will you load and read fully `{nextStepFile}` to execute the configuration write step.
 
 ---
 

package/src/workflows/setup-forge/steps-c/step-02-write-config.md

@@ -63,11 +63,16 @@ tools:
   ast_grep: {true/false from detection}
   gh_cli: {true/false from detection}
   qmd: {true/false from detection}
+  security_scan: {true/false — true when SNYK_TOKEN is set}
 
 # Capability tier (derived from tool availability)
-# Quick = no tools | Forge = ast-grep | Deep = ast-grep + gh + qmd
+# Quick = no tools required | Forge = + ast-grep | Deep = + ast-grep + gh + QMD
 tier: {calculated_tier}
 tier_detected_at: {current ISO timestamp}
+
+# QMD collection registry (populated by create-skill, consumed by audit/update-skill)
+# Each entry tracks a QMD collection created during skill workflows
+qmd_collections: []
 ```
 
 **This file is ALWAYS overwritten** on every run — it reflects current tool state.
@@ -88,6 +93,9 @@ Check if `{project-root}/_bmad/_memory/forger-sidecar/preferences.yaml` exists:
 # Override detected tier (set to Quick, Forge, or Deep to force a tier)
 tier_override: ~
 
+# Passive context injection (set to false to skip snippet generation and CLAUDE.md updates during export)
+passive_context: true
+
 # Skill generation defaults
 default_source_authority: community
 default_confidence_threshold: 0.7
@@ -125,7 +133,7 @@ ONLY WHEN forge-tier.yaml has been written successfully and preferences.yaml exi
 
 ### ✅ SUCCESS:
 
-- forge-tier.yaml written with accurate tool booleans, tier, and timestamp
+- forge-tier.yaml written with accurate tool booleans, tier, timestamp, and empty qmd_collections registry
 - preferences.yaml exists (created with defaults on first run, preserved on re-run)
 - forge-data/ directory exists (created or pre-existing)
 - Auto-proceeded to step-03

package/src/workflows/setup-forge/steps-c/step-03-auto-index.md

@@ -1,15 +1,17 @@
 ---
 name: 'step-03-auto-index'
-description: 'Index current project as QMD collection (Deep tier only)'
+description: 'Verify and clean QMD collections against the forge-tier.yaml registry (Deep tier only)'
 
 nextStepFile: './step-04-report.md'
 ---
 
-# Step 3: Auto-Index Project
+# Step 3: QMD Collection Hygiene
 
 ## STEP GOAL:
 
-If the detected tier is Deep, index the current project as a QMD collection for knowledge search. For Quick and Forge tiers, skip silently and proceed.
+If the detected tier is Deep, verify the health of existing QMD collections by cross-referencing them against the `qmd_collections` registry in `forge-tier.yaml`. Identify orphaned collections (in QMD but not in registry) and stale registry entries (in registry but collection missing from QMD). Prompt the user before removing orphaned collections.
+
+For Quick and Forge tiers, skip silently and proceed.
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
@@ -17,34 +19,37 @@ If the detected tier is Deep, index the current project as a QMD collection for
 
 - 📖 CRITICAL: Read the complete step file before taking any action
 - 🔄 CRITICAL: When loading next step, ensure entire file is read
-- 🎯 Execute all operations autonomously — no user interaction
+- 🎯 Execute all operations autonomously — minimal user interaction (only prompt before deletion)
 
 ### Role Reinforcement:
 
-- ✅ You are a system executor performing conditional indexing
-- ✅ Graceful degradation is paramount — never fail the workflow over indexing
+- ✅ You are a system executor performing QMD collection maintenance
+- ✅ Graceful degradation is paramount — never fail the workflow over hygiene checks
 - ✅ No negative messaging — do not mention what non-Deep tiers are missing
 
 ### Step-Specific Rules:
 
-- 🎯 Focus only on QMD indexing (Deep tier) or graceful skip (other tiers)
+- 🎯 Focus only on verifying and cleaning QMD collections (Deep tier) or graceful skip (other tiers)
 - 🚫 FORBIDDEN to display "missing" or "skipped" messages for non-Deep tiers
-- 🚫 FORBIDDEN to fail the workflow if QMD indexing encounters errors
-- 💬 If indexing fails: log the issue, note that index can be retried, continue
+- 🚫 FORBIDDEN to fail the workflow if QMD hygiene encounters errors
+- 🚫 FORBIDDEN to create new QMD collections — that responsibility belongs to create-skill
+- 🚫 FORBIDDEN to silently delete collections — always prompt user before removal
+- 💬 If hygiene fails: log the issue, note that it can be retried, continue
 
 ## EXECUTION PROTOCOLS:
 
 - 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 QMD indexing operates on the project root directory
+- 💾 QMD hygiene only verifies and cleans — it does NOT index new content
 - 📖 Use {calculated_tier} from step-01 context
-- 🚫 FORBIDDEN to attempt indexing for Quick or Forge tiers
+- 🚫 FORBIDDEN to attempt hygiene for Quick or Forge tiers
 
 ## CONTEXT BOUNDARIES:
 
 - Available: {calculated_tier} from step-01, forge-tier.yaml written in step-02
-- Focus: conditional QMD indexing only
-- Limits: only index if Deep tier
-- Dependencies: step-02 must have completed (forge-tier.yaml exists)
+- Available: {project_name} from workflow config
+- Focus: QMD collection verification and cleanup only
+- Limits: only run if Deep tier
+- Dependencies: step-02 must have completed (forge-tier.yaml exists with qmd_collections registry)
 
 ## MANDATORY SEQUENCE
 
@@ -54,46 +59,105 @@ If the detected tier is Deep, index the current project as a QMD collection for
 
 Read `{calculated_tier}` from context.
 
-**If tier is NOT Deep:** Proceed directly to step 4 — auto-proceed with no output, no messaging.
+**If tier is NOT Deep:** Proceed directly to section 6 (Auto-Proceed) — no output, no messaging.
 
 **If tier IS Deep:** Continue to section 2.
 
-### 2. Index Project with QMD (Deep Tier Only)
+### 2. Load Registry and QMD State
+
+Read the `qmd_collections` array from `{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml`.
+
+List live QMD collections:
+```bash
+qmd collection list
+```
+
+**Store both lists for cross-reference:**
+- `{registry_collections}` — entries from forge-tier.yaml qmd_collections
+- `{live_collections}` — collections currently in QMD
+
+**Error handling:** If `qmd collection list` fails, log the error, store `{hygiene_result: "qmd_unavailable"}`, and proceed to section 6.
+
+### 3. Cross-Reference and Classify
+
+Compare the two lists:
+
+**Healthy** — collection exists in both registry AND QMD:
+- Mark as verified
+- No action needed
+
+**Orphaned** — collection exists in QMD but NOT in registry:
+- These may be leftover from prior auto-indexing or manual indexing
+- Flag for user-prompted removal
+
+**Stale** — entry exists in registry but collection is missing from QMD:
+- The QMD collection was deleted or lost
+- Remove the stale entry from the registry
+
+### 4. Handle Orphaned Collections
+
+**If orphaned collections found:**
+
+Display to user:
+"**QMD Hygiene: Found {count} orphaned collection(s) not tracked in the forge registry:**
+
+{list orphaned collection names}
+
+These collections exist in QMD but are not managed by any skill workflow. They may be from a previous auto-index run or manual creation.
+
+**[R]emove** orphaned collections — clean up QMD
+**[K]eep** orphaned collections — leave them as-is"
+
+**If user selects R (Remove):**
+For each orphaned collection:
+```bash
+qmd collection remove {collection_name}
+```
+Log each removal.
+
+**If user selects K (Keep):**
+Skip removal. Log that orphaned collections were kept.
+
+**If no orphaned collections:** Skip this section silently.
+
+### 5. Handle Stale Registry Entries
+
+**If stale registry entries found:**
+
+Remove stale entries from the `qmd_collections` array in forge-tier.yaml.
 
-Index the current project directory as a QMD collection for knowledge search.
+Display: "**Cleaned {count} stale registry entry/entries** (collection no longer exists in QMD)."
 
-Use the QMD MCP server to create or update a collection for the current project:
-- Collection name: derive from project directory name
-- Source: project root directory
-- Scope: markdown files, source code, documentation
+Update forge-tier.yaml with the cleaned registry.
 
-**Timeout handling:** If indexing takes excessively long on a large project:
-- Log that indexing is in progress but may need more time
-- Note in context that index may be incomplete
-- Do NOT halt or fail the workflow
+**If no stale entries:** Skip this section silently.
 
-**Error handling:** If QMD indexing fails:
-- Log the specific error
-- Note that indexing can be retried by re-running setup-forge
-- The forge-tier.yaml already records `qmd: true` — the tool is available even if indexing failed
-- Continue to step 4
+### 6. Store Hygiene Results and Auto-Proceed
 
-### 3. Auto-Proceed
+Store in context for step-04 reporting:
+```
+{hygiene_result: "completed"|"skipped"|"qmd_unavailable"}
+{hygiene_healthy: count}
+{hygiene_orphaned_removed: count}
+{hygiene_orphaned_kept: count}
+{hygiene_stale_cleaned: count}
+```
 
 "**Proceeding to forge status report...**"
 
 #### Menu Handling Logic:
 
-- After indexing completes (or is skipped for non-Deep tiers), immediately load, read entire file, then execute {nextStepFile}
+- After hygiene completes (or is skipped), immediately load, read entire file, then execute {nextStepFile}
 
 #### EXECUTION RULES:
 
-- This is an auto-proceed step with no user choices
-- Proceed directly to next step after indexing or skip
+- This step has one optional user interaction (orphan removal prompt)
+- If no orphans found, this is an auto-proceed step
+- Proceed directly to next step after hygiene or skip
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN the tier check has been performed (and indexing completed or skipped accordingly) will you load and read fully `{nextStepFile}` to execute the report step.
+ONLY WHEN the hygiene check has been performed (or skipped for non-Deep tiers) will you load and read fully `{nextStepFile}` to execute the report step.
 
 ---
 
@@ -101,16 +165,23 @@ ONLY WHEN the tier check has been performed (and indexing completed or skipped a
 
 ### ✅ SUCCESS:
 
-- Deep tier: QMD indexing attempted, succeeded or degraded gracefully
+- Deep tier: forge-tier.yaml registry cross-referenced with live QMD collections
+- Healthy collections identified and verified
+- Orphaned collections flagged and user prompted before removal
+- Stale registry entries cleaned from forge-tier.yaml
+- Hygiene results stored for step-04 reporting
 - Quick/Forge tier: skipped silently with no negative messaging
-- Workflow continues regardless of indexing outcome
+- Workflow continues regardless of hygiene outcome
 - Auto-proceeded to step-04
 
 ### ❌ SYSTEM FAILURE:
 
-- Attempting QMD indexing for Quick or Forge tiers
+- Creating new QMD collections (that's create-skill's responsibility)
+- Silently deleting collections without user prompt
+- Attempting QMD hygiene for Quick or Forge tiers
 - Displaying "skipped" or "missing" messages for non-Deep tiers
-- Halting the workflow due to QMD indexing failure
+- Halting the workflow due to QMD hygiene failure
+- Indexing project directories (old auto-index behavior — removed)
 - Not proceeding to step-04 after this step
 
-**Master Rule:** This step must NEVER fail the workflow. Deep tier indexing is best-effort. Non-Deep tiers skip silently.
+**Master Rule:** This step ONLY verifies and cleans. It never indexes new content. QMD collection creation is the responsibility of create-skill. Non-Deep tiers skip silently. Always prompt before removing orphaned collections.

package/src/workflows/setup-forge/steps-c/step-04-report.md

@@ -43,6 +43,7 @@ Display the forge status report with positive capability framing, report tier ch
 
 - Available: {detected_tools}, {calculated_tier}, {previous_tier}, {tier_override} from step-01
 - Available: tool version strings from step-01
+- Available: {hygiene_result}, {hygiene_healthy}, {hygiene_orphaned_removed}, {hygiene_orphaned_kept}, {hygiene_stale_cleaned} from step-03
 - Focus: report display only — no file modifications
 - Dependencies: steps 01-03 must have completed
 
@@ -69,6 +70,18 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
   Tools Detected:
   {for each tool that is available, show: tool name — version}
 
+  {if hygiene_result is "completed":}
+  QMD Registry:
+  {hygiene_healthy} collection(s) healthy
+  {if hygiene_orphaned_removed > 0: {hygiene_orphaned_removed} orphaned collection(s) removed}
+  {if hygiene_orphaned_kept > 0: {hygiene_orphaned_kept} orphaned collection(s) kept}
+  {if hygiene_stale_cleaned > 0: {hygiene_stale_cleaned} stale registry entry/entries cleaned}
+  {end if}
+
+  {if hygiene_result is "completed" and hygiene_healthy is 0:}
+  QMD Registry: empty — collections are created automatically when you run [CS] Create Skill.
+  {end if}
+
 {if tier_override is active:}
   Note: Tier override active (set in preferences.yaml)
 

package/src/workflows/setup-forge/workflow.md

@@ -2,6 +2,7 @@
 name: setup-forge
 description: Initialize forge environment, detect tools, set tier, auto-index project
 web_bundle: true
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/setup-forge'
 ---
 
 # Setup Forge

package/src/workflows/test-skill/data/scoring-rules.md

@@ -8,18 +8,24 @@
 
 | Category | Weight | Description |
 |----------|--------|-------------|
-| Export Coverage | 40% | Percentage of source exports documented in SKILL.md |
-| Signature Accuracy | 25% | Documented signatures match actual source signatures |
-| Type Coverage | 15% | Types and interfaces referenced are complete |
-| Coherence (contextual) | 20% | Cross-references valid, integration patterns complete |
+| Export Coverage | 36% | Percentage of source exports documented in SKILL.md |
+| Signature Accuracy | 22% | Documented signatures match actual source signatures |
+| Type Coverage | 14% | Types and interfaces referenced are complete |
+| Coherence (contextual) | 18% | Cross-references valid, integration patterns complete |
 | Coherence (naive) | 0% | Not applicable — weight redistributed to other categories |
+| External Validation | 10% | Average of skill-check quality score + tessl average score (redistributed if unavailable) |
 
 ## Naive Mode Weight Redistribution
 
 When running in naive mode (no coherence category):
-- Export Coverage: 50%
-- Signature Accuracy: 30%
+- Export Coverage: 45%
+- Signature Accuracy: 25%
 - Type Coverage: 20%
+- External Validation: 10%
+
+## External Validation Unavailable
+
+When neither skill-check nor tessl is available, redistribute the 10% external validation weight proportionally to the other active categories. When only one tool is available, use that tool's score as the external validation score.
 
 ## Tier-Dependent Scoring
 
@@ -40,6 +46,7 @@ When running in naive mode (no coherence category):
 - Cross-repository reference verification
 - QMD knowledge enrichment for coherence
 - Full scoring formula with maximum depth
+- **Migration & Deprecation Warnings section:** If T2-future annotations exist in the enrichment data, verify that Section 4b is present in SKILL.md Tier 1 and that each warning traces to a T2 provenance citation. If no T2-future annotations exist, Section 4b should be absent (not empty). Presence/absence mismatch is a Medium severity gap.
 
 ## Score Calculation
 
@@ -70,5 +77,6 @@ If no integration patterns exist, combined coherence equals reference validity.
 | Critical | Missing exported function/class documentation |
 | High | Signature mismatch between source and SKILL.md |
 | Medium | Missing type or interface documentation |
+| Medium | Migration section present/absent mismatch with T2-future annotation data (Deep tier) |
 | Low | Missing optional metadata or examples |
 | Info | Style suggestions, non-blocking observations |