bmad-module-skill-forge 0.5.0 → 0.7.0

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

@@ -69,13 +69,9 @@ Run: `npx skill-check -h`
 
 Launch subprocesses in parallel for each validation category, aggregating results when complete:
 
-**Check A — Spec Compliance (via skill-check):**
+**Check A — Spec Compliance (deferred to post-write):**
 
-**If available**, run: `npx skill-check check <skill-dir> --fix --format json --no-security-scan`
-
-Parse JSON output for quality score (0-100), auto-fixed issues, and remaining diagnostics. If `body.max_lines` reported, prefer selective split: extract only the largest Tier 2 section(s) to `references/`, keeping all Tier 1 content inline (see `knowledge/split-body-strategy.md`). Fall back to `npx skill-check split-body <skill-dir> --write` only if selective split is not feasible. After any split, verify `#quick-start` and `#key-types` anchors still resolve in SKILL.md.
-
-**If unavailable**, perform manual check: validate merged SKILL.md structure, verify required sections (exports, usage patterns, conventions), verify export entries have name/type/signature/file:line reference, flag missing sections.
+Skill-check requires written files on disk. This check is deferred to step-06 section 7. Perform manual structural check only: verify merged SKILL.md has required sections (exports, usage patterns, conventions), verify export entries have name/type/signature/file:line reference, flag missing sections.
 
 **Check B — [MANUAL] Section Integrity:**
 - Compare [MANUAL] inventory from step 01 against merged content
@@ -84,7 +80,7 @@ Parse JSON output for quality score (0-100), auto-fixed issues, and remaining di
 
 **Check C — Confidence Tier Consistency:**
 - Verify all re-extracted exports have confidence labels (T1/T1-low/T2)
-- Verify tier labels match forge tier: Quick=T1-low only, Forge=T1 (T1-low for degraded), Deep=T1+T2
+- Verify tier labels match forge tier: Quick=T1-low only, Forge=T1 (T1-low for degraded), Forge+=T1 (same as Forge, CCC improves coverage not confidence), Deep=T1+T2
 - Flag mismatched or missing tier labels
 
 **Check D — Provenance Completeness:**
@@ -166,9 +162,9 @@ ONLY WHEN all validation checks have completed and findings are displayed will y
 
 ### ✅ SUCCESS:
 
-- All six checks executed (spec, [MANUAL], confidence, provenance, diff, security)
-- `npx skill-check check --fix` and `diff` executed if available (or fallbacks used)
-- Quality score captured; auto-fix applied for deterministic issues
+- All six checks executed (spec-manual, [MANUAL], confidence, provenance, diff, security)
+- Checks A (spec compliance via skill-check), E (diff), and F (security scan) deferred to post-write in step-06
+- Manual structural check performed for spec compliance in this step
 - Stack skill reference files validated if applicable
 - Findings reported with severity and specific locations; [MANUAL] integrity verified
 - Auto-proceeds regardless of findings (advisory mode)
@@ -177,7 +173,7 @@ ONLY WHEN all validation checks have completed and findings are displayed will y
 
 - Skipping any of the six checks; blocking on validation warnings
 - Not verifying [MANUAL] integrity; hallucinating findings not backed by comparison
-- Modifying merged content during validation (except via skill-check --fix)
+- Modifying merged content during validation (validation is read-only in this step)
 - 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/update-skill/steps-c/step-06-write.md

@@ -74,7 +74,9 @@ Update `{skills_output_folder}/{skill_name}/metadata.json`:
   - `exports_total`: `exports_public_api` + `exports_internal`
   - `public_api_coverage`: `exports_documented / exports_public_api` (`null` if `exports_public_api` is 0)
   - `total_coverage`: `exports_documented / exports_total` (`null` if `exports_total` is 0)
-  - `confidence_t1`, `confidence_t2`, `confidence_t3`: update counts from re-extraction results
+- Update `confidence_distribution` from re-extraction results:
+  - `confidence_distribution.t1`, `confidence_distribution.t1_low`, `confidence_distribution.t2`, `confidence_distribution.t3`: update counts from re-extraction results
+  - `scripts_count`, `assets_count`: update from re-extraction results if scripts/assets changed
 - For stack skills: update `library_count`, `integration_count` if changed
 
 ### 3. Write Updated provenance-map.json
@@ -115,7 +117,7 @@ Write to `{forge_data_folder}/{skill_name}/provenance-map.json`:
 
 ### 4. Write Updated evidence-report.md
 
-Append update operation section to `{forge_data_folder}/{skill_name}/evidence-report.md`:
+Append update operation section to `{forge_data_folder}/{skill_name}/evidence-report.md` (create the file with a standard header if it does not yet exist):
 
 ```markdown
 ## Update Operation — {current_date}
@@ -154,7 +156,7 @@ For each affected reference file from the merge:
 - Regenerate `context-snippet.md` with updated export summaries
 - Verify [MANUAL] sections preserved in each reference file
 
-**If skill_type != "stack":** Skip with notice.
+**If skill_type != "stack":** Skip reference file updates. However, if exports changed (added, removed, or renamed), warn: "⚠️ `context-snippet.md` was NOT updated — exports have changed. Run **[EX] Export Skill** to regenerate the context snippet and update CLAUDE.md/AGENTS.md."
 
 ### 6. Verify All Writes
 
@@ -182,7 +184,8 @@ External tool checks deferred from step-05 now run against the written files:
 
 **If skill-check available:**
 - Run: `npx skill-check check {skills_output_folder}/{skill_name} --fix --format json --no-security-scan`
-- If `body.max_lines` reported, prefer selective split (see `knowledge/split-body-strategy.md`). Fall back to `npx skill-check split-body {skills_output_folder}/{skill_name} --write` if not feasible. Verify anchors resolve after split.
+- **Context sync after --fix:** If `fixed[]` is non-empty (i.e., `--fix` modified files on disk), re-read the modified SKILL.md to update the in-context copy. This prevents silent divergence between the in-context SKILL.md and the on-disk version that step-07-report will reference.
+- If `body.max_lines` reported, prefer selective split — extract only the largest Tier 2 section(s) to `references/`, keeping Tier 1 inline (inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval). Fall back to `npx skill-check split-body {skills_output_folder}/{skill_name} --write` if not feasible. Verify anchors resolve after split.
 - Run: `npx skill-check diff` if original version was preserved
 - Run: `npx skill-check check {skills_output_folder}/{skill_name} --format json` for security scan
 

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

@@ -2,7 +2,7 @@
 name: update-skill
 description: Smart regeneration preserving [MANUAL] sections. Detects individual vs stack internally.
 web_bundle: true
-installed_path: '{project-root}/_bmad/skf/workflows/update-skill'
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/update-skill'
 ---
 
 # Update Skill

package/src/workflows/verify-stack/data/coverage-patterns.md

@@ -0,0 +1,45 @@
+# Coverage Patterns
+
+## Purpose
+
+Rules for detecting technology/library references in architecture and PRD documents, and matching them against generated skills.
+
+---
+
+## Technology Detection in Documents
+
+### Direct Name Matching
+
+Search the architecture document for exact mentions of:
+1. Library names from generated skills (case-insensitive)
+2. Common aliases (e.g., "React" also matches "ReactJS", "react.js")
+3. Framework names that encompass libraries (e.g., "Tauri" encompasses the Tauri ecosystem)
+
+### Section-Based Detection
+
+Parse document section headers for technology groupings:
+- `## Desktop App` → technologies listed under this section
+- `## Backend Core` → technologies in backend layer
+- `## AI Layer` → AI-related technologies
+
+**Mermaid Diagram Handling:** Do NOT parse Mermaid diagram syntax (`graph`, `flowchart`, `sequenceDiagram`, etc.) for technology detection. Only use prose text (headings, paragraphs, lists, tables) for detection. If the architecture document appears to list technologies exclusively inside Mermaid diagrams, note this in the coverage results as a detection limitation and recommend the user add prose-based technology listings.
+
+### Coverage Verdict
+
+| Verdict | Meaning |
+|---------|---------|
+| **Covered** | A generated skill exists in `skills/` for this technology |
+| **Missing** | Technology is referenced in architecture doc but no skill exists |
+| **Extra** | A skill exists but the technology is not referenced in the architecture doc (informational, not an error) |
+
+## Output Format
+
+When presenting coverage results, use the following structure:
+
+```
+| Technology | Source Section | Skill Match | Verdict |
+|------------|---------------|-------------|---------|
+| {tech_name} | {section_heading} | {skill_name or '—'} | Covered / Missing |
+```
+
+Include a summary line: `Coverage: {covered_count}/{total_count} ({percentage}%)`

package/src/workflows/verify-stack/data/feasibility-report-template.md

@@ -0,0 +1,63 @@
+---
+workflowType: 'verify-stack'
+project_name: ''
+architecture_doc: ''
+prd_doc: ''
+date: ''
+overall_verdict: ''
+stepsCompleted: []
+skills_analyzed: 0
+coverage_percentage: 0
+integrations_verified: 0
+integrations_plausible: 0
+integrations_risky: 0
+integrations_blocked: 0
+requirements_fulfilled: null
+requirements_partial: null
+requirements_not_addressed: null
+requirements_pass: ''
+recommendation_count: 0
+prd_available: false
+previous_report: ''
+delta_improved: null
+delta_regressed: null
+delta_new: null
+delta_unchanged: null
+---
+
+# Stack Feasibility Report: {project_name}
+
+**Verification Date:** {date}
+**Architecture Document:** {architecture_doc}
+**PRD Document:** {prd_doc}
+**Skills Analyzed:** {skills_analyzed}
+
+## Overall Verdict
+
+{FEASIBLE / CONDITIONALLY FEASIBLE / NOT FEASIBLE}
+
+{1-2 sentence summary}
+
+---
+
+## Coverage Matrix
+
+<!-- Appended by step-02-coverage -->
+
+---
+
+## Integration Verdicts
+
+<!-- Appended by step-03-integrations -->
+
+---
+
+## Requirements Coverage
+
+<!-- Appended by step-04-requirements (if PRD provided) -->
+
+---
+
+## Synthesis & Recommendations
+
+<!-- Appended by step-05-synthesize -->

package/src/workflows/verify-stack/data/integration-verification-rules.md

@@ -0,0 +1,73 @@
+# Integration Verification Rules
+
+## Purpose
+
+Rules for cross-referencing API surfaces between two skills to determine integration feasibility.
+
+---
+
+## Verdict Definitions
+
+| Verdict | Meaning | Required Evidence |
+|---------|---------|-------------------|
+| **Verified** | APIs demonstrably connect — matching types, documented bridge, or shared protocol | At least one export from Skill A is consumable by an API in Skill B (or vice versa) with compatible types |
+| **Plausible** | Compatible types or protocols but no documented integration path | Both libraries operate in compatible domains with compatible data formats, but no direct API bridge is evident |
+| **Risky** | Type mismatch, protocol gap, or language boundary requiring a bridge | A clear gap exists (e.g., TypeScript↔Rust FFI needed) but a workaround is architecturally feasible |
+| **Blocked** | Fundamental incompatibility — no feasible integration path even with a bridge or adapter layer | The two libraries cannot exchange data in any documented way; requires replacing one of the libraries |
+
+---
+
+## Cross-Reference Protocol
+
+For each integration pair (Library A ↔ Library B):
+
+### 1. Language Boundary Check
+
+| A Language | B Language | Assessment |
+|-----------|-----------|------------|
+| Same language | Same language | No boundary — direct API calls possible |
+| TypeScript ↔ Rust | Requires FFI, IPC, or WebSocket bridge | Check if a bridge library exists in the stack (e.g., Tauri provides JS↔Rust IPC) |
+| TypeScript ↔ Python | Requires REST/gRPC/WebSocket bridge | Typically not direct |
+| Any ↔ C/C++ | FFI available in most languages | Check for bindings |
+
+### 2. Protocol Compatibility Check
+
+| A Protocol | B Protocol | Assessment |
+|-----------|-----------|------------|
+| In-process (same runtime) | In-process | Direct — function calls |
+| HTTP/REST | HTTP/REST | Network bridge — compatible if API endpoints match |
+| WebSocket | WebSocket | Real-time bridge — check message format compatibility |
+| Shared filesystem | Shared filesystem | Async — check format compatibility |
+| Embedded database | Embedded database | May conflict on lock files — check for multi-writer support |
+
+### 3. Type Compatibility Check
+
+- Extract the primary data types each library produces/consumes from the skill's export list
+- Check: does Library A export a type that Library B accepts as input?
+- Common patterns: JSON serialization (universal bridge), binary formats (check codec), shared schemas (strong compatibility)
+
+### 4. Documentation Cross-Reference
+
+- Search Skill A's content for mentions of Library B's name
+- Search Skill B's content for mentions of Library A's name
+- If either mentions the other: strong evidence of documented integration
+- Check if either library's README lists the other as a companion/integration
+
+---
+
+## Verdict Evidence Format
+
+Each verdict MUST include:
+
+```
+**{Library A} ↔ {Library B}: {VERDICT}**
+
+Evidence:
+- A exports: `{function_name}({params}) → {return_type}` [from skill: {skill_name}]
+- B accepts: `{function_name}({params})` [from skill: {skill_name}]
+- Compatibility: {explanation}
+- Language boundary: {same | bridge required via {mechanism}}
+
+{If RISKY or BLOCKED:}
+Recommendation: {actionable next step}
+```

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

@@ -0,0 +1,174 @@
+---
+name: 'step-01-init'
+description: 'Load generated skills from skills folder, accept architecture doc path and optional PRD path, validate all inputs exist'
+
+nextStepFile: './step-02-coverage.md'
+reportTemplate: '../data/feasibility-report-template.md'
+outputFile: '{forge_data_folder}/feasibility-report-{project_name}.md'
+---
+
+# Step 1: Initialize Verification
+
+## STEP GOAL:
+
+Load all generated skills from the skills output folder, accept the architecture document path (required) and optional PRD/vision document path from the user, validate that all inputs exist and are readable, create the feasibility report document, and present an initialization summary before auto-proceeding.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a stack verification analyst operating in Ferris Audit mode
+- ✅ Execute with prescriptive precision — every loaded skill must be validated against actual files
+- ✅ You enforce the zero-hallucination principle: only report skills that physically exist on disk
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on loading inputs, scanning skills, and creating the report skeleton
+- 🚫 FORBIDDEN to perform any coverage analysis or integration checking
+- 🚫 Auto-proceed init step — no user confirmation needed. Halts only on validation errors
+- 💬 Present a clear initialization summary so downstream steps have validated inputs
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Collect and validate all input documents and skill artifacts
+- 💾 Create feasibility report from {reportTemplate} with populated frontmatter
+- 📖 Auto-proceed to next step after successful initialization
+- 🚫 HALT with actionable error if minimum requirements not met
+
+## CONTEXT BOUNDARIES:
+
+- This is the first step — no prior workflow state exists
+- Requires skills to have been generated by create-skill or quick-skill workflows
+- User provides architecture document path (required) and optional PRD/vision document path
+- No dependency on setup-forge or forge-tier — this workflow operates on skill content only
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Accept Input Documents
+
+"**Verify Stack — Feasibility Analysis**
+
+Please provide the following:
+1. **Architecture document path** (REQUIRED) — your project's architecture doc
+2. **PRD or vision document path** (OPTIONAL) — for requirements coverage analysis
+3. **Previous feasibility report path** (OPTIONAL) — for delta comparison with a prior run (provide a backup copy)"
+
+Wait for user input.
+
+**Validate architecture document:**
+- Confirm the file exists and is readable
+- If missing or unreadable → "Architecture document not found at `{path}`. Provide a valid path."
+- HALT until a valid architecture document is provided
+
+**Validate PRD document (if provided):**
+- Confirm the file exists and is readable
+- If missing → "PRD document not found at `{path}`. Proceeding without PRD — requirements pass will be skipped."
+- Store PRD availability as `prd_available: true|false`
+
+**Validate previous report (if provided):**
+- Confirm the file exists and is readable
+- **Collision check:** Resolve both the provided path and `{outputFile}` to their absolute form before comparing (do not rely on string equality alone). If they resolve to the same location, warn: "The previous report path points to the same location as the new report. This file will be overwritten during this run. Provide a path to a backup copy, or leave empty to skip delta comparison." HALT until resolved.
+- If missing → "Previous report not found at `{path}`. Proceeding without delta comparison."
+- Store as `previous_report: {path}` (or empty string if not provided)
+
+### 2. Scan Skills Folder
+
+Read the `{skills_output_folder}` directory.
+
+For each subdirectory, check for the presence of `SKILL.md` and `metadata.json`.
+
+**For each valid skill directory, extract from metadata.json:**
+- `name` — skill name
+- `language` — primary language
+- `confidence_tier` — Quick, Forge, Forge+, or Deep
+- `exports_documented` — read from `stats.exports_documented` in metadata.json (count of documented exports)
+- `source_repo` or `source_root` — original source repository
+
+**Build a skill inventory** as an internal list of all loaded skills with the fields above.
+
+**If a subdirectory lacks SKILL.md or metadata.json:**
+- Log: "Skipping `{dir_name}` — missing SKILL.md or metadata.json"
+- Do not include in inventory
+
+### 3. Validate Minimum Requirements
+
+**Check skill count:**
+- At least 2 valid skills must exist (a stack requires multiple libraries)
+- If fewer than 2 → "**Cannot proceed.** Only {count} skill(s) found in `{skills_output_folder}`. A stack requires at least 2 skills. Generate more skills with [CS] Create Skill or [QS] Quick Skill, then re-run [VS]."
+- HALT workflow
+
+**Check forge_data_folder:**
+- Verify `forge_data_folder` was resolved from config.yaml and is non-empty
+- If undefined or empty → "**Cannot proceed.** `forge_data_folder` is not configured in config.yaml. Re-run [SF] Setup Forge to initialize."
+- HALT workflow
+
+**Check architecture document:**
+- Confirm it was loaded successfully in section 1
+- If not → HALT with error (should not reach here if section 1 validation passed)
+
+### 4. Create Feasibility Report
+
+Load `{reportTemplate}` and create the output file at `{outputFile}`.
+
+**Populate frontmatter:**
+- `project_name`, `date`, `architecture_doc`, `prd_doc` (or "none")
+- `prd_available: true|false` (from section 1 validation)
+- `previous_report: {path}` (or empty string if not provided)
+- `skills_analyzed: {count}`
+- `overall_verdict: "pending"`
+- `stepsCompleted: ['step-01-init']`
+
+### 5. Display Initialization Summary
+
+"**Stack Verification Initialized**
+
+| Field | Value |
+|-------|-------|
+| **Skills Loaded** | {count} |
+| **Architecture Doc** | {architecture_doc} |
+| **PRD Document** | {prd_doc or 'Not provided — requirements pass will be skipped'} |
+| **Previous Report** | {previous_report or 'Not provided — no delta comparison'} |
+
+**Skill Inventory:**
+
+| Skill | Language | Tier | Exports |
+|-------|----------|------|---------|
+| {skill_name} | {language} | {confidence_tier} | {exports_documented} |
+
+**Proceeding to coverage analysis...**"
+
+### 6. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Architecture document loaded and validated
+- PRD document loaded or absence recorded
+- Skills folder scanned with SKILL.md and metadata.json validation per skill
+- At least 2 valid skills in inventory
+- Feasibility report created from template with populated frontmatter
+- Initialization summary displayed with skill inventory table
+- Auto-proceeded to step 02
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with fewer than 2 skills
+- Proceeding without a valid architecture document
+- Not validating SKILL.md and metadata.json existence per skill directory
+- Performing coverage or integration analysis in this step
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** This step validates inputs and initializes state. No analysis, no comparison, no verdicts.

package/src/workflows/verify-stack/steps-c/step-02-coverage.md

@@ -0,0 +1,181 @@
+---
+name: 'step-02-coverage'
+description: 'Pass 1 — check that a generated skill exists for every technology referenced in the architecture document'
+
+nextStepFile: './step-03-integrations.md'
+coveragePatternsData: '../data/coverage-patterns.md'
+outputFile: '{forge_data_folder}/feasibility-report-{project_name}.md'
+---
+
+# Step 2: Technology Coverage Analysis
+
+## STEP GOAL:
+
+Verify that a generated skill exists for every technology, library, or framework referenced in the architecture document. Produce a coverage matrix showing which technologies are covered and which are missing. Detect extra skills not referenced in the architecture.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a stack verification analyst performing coverage analysis
+- ✅ Every technology reference must trace to actual text in the architecture document
+- ✅ Matching must be precise — do not guess or infer technologies not explicitly mentioned
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on technology-to-skill coverage mapping
+- 🚫 FORBIDDEN to analyze API surfaces or integration compatibility — that is Step 03
+- 🚫 FORBIDDEN to evaluate requirements — that is Step 04
+- 💬 Coverage verdicts must be binary: Covered or Missing — no ambiguity
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Extract technology references from architecture document using {coveragePatternsData}
+- 💾 Build and display coverage matrix with Covered/Missing verdicts
+- 📖 Append Coverage Matrix section to {outputFile}
+- 🚫 Only coverage mapping — no integration analysis, no requirements checking
+
+## CONTEXT BOUNDARIES:
+
+- Available: Architecture document content, skill inventory from Step 01, coverage patterns data
+- Focus: Technology-to-skill matching only
+- Limits: Do not read SKILL.md in detail — use metadata.json for name and source_repo matching only
+- Dependencies: Step 01 must have loaded skill inventory and validated architecture document
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Load Coverage Patterns
+
+Load `{coveragePatternsData}` for detection rules.
+
+Extract: technology name patterns, section heading indicators, common aliases, and framework-to-library mappings.
+
+### 2. Extract Technology References
+
+Parse the architecture document for technology, library, and framework names.
+
+**Detection methods (apply in order):**
+
+**Section-based detection:**
+- Identify section headings that indicate technology listings (e.g., "Tech Stack", "Dependencies", "Technologies", "Libraries", layer-specific headings)
+- Extract technology names listed under these headings
+
+**Direct name matching:**
+- Scan the full document for names that match loaded skill names (case-insensitive)
+- Apply alias resolution from {coveragePatternsData} (e.g., "React" matches "react", "PostgreSQL" matches "postgres")
+
+**Contextual detection:**
+- Identify technology names mentioned in prose alongside architectural descriptions
+- Look for version-pinned references (e.g., "Express v4", "Tailwind CSS 3.x")
+
+**Build a deduplicated list** of all referenced technologies with the document section where each was found.
+
+### 3. Cross-Reference Against Skills
+
+For each referenced technology in the list:
+
+**Check if a matching skill exists** in the skill inventory from Step 01.
+- Match by skill name (case-insensitive)
+- Match by alias from {coveragePatternsData}
+- Match by `source_repo` or `source_root` field in metadata.json if skill name differs from technology name
+
+**Assign verdict:**
+- **Covered** — a matching skill exists in the inventory
+- **Missing** — no matching skill found
+
+Build the coverage matrix as a structured table.
+
+### 4. Detect Extra Skills
+
+Check if any skills in the inventory are NOT referenced in the architecture document.
+
+**For each extra skill:**
+- Mark as **Extra** (informational — not an error)
+- Note: "Skill `{skill_name}` exists but is not referenced in the architecture document"
+
+Extra skills are informational only. They do not affect the coverage verdict.
+
+### 5. Display Coverage Results
+
+"**Pass 1: Technology Coverage**
+
+| Technology | Source Section | Skill Match | Verdict |
+|------------|---------------|-------------|---------|
+| {tech_name} | {section_heading} | {skill_name or '—'} | {Covered / Missing} |
+
+**Coverage: {covered_count}/{total_count} ({percentage}%)**
+
+{IF 100% coverage AND no Extra skills:}
+**All referenced technologies have a matching skill. No extra skills detected.**
+
+{IF any Missing:}
+**Missing Skills — Action Required:**
+{For each missing technology:}
+- `{tech_name}` → Run **[CS] Create Skill** or **[QS] Quick Skill** for `{tech_name}`, then re-run **[VS]**
+
+{IF any Extra:}
+**Extra Skills (informational):**
+{For each extra skill:}
+- `{skill_name}` — not referenced in architecture document"
+
+### 6. Append to Report
+
+Write the **Coverage Matrix** section to `{outputFile}`:
+- Include the full coverage table
+- Include coverage percentage
+- Include missing skill recommendations
+- Include extra skills list
+- Update frontmatter: append `'step-02-coverage'` to `stepsCompleted`, set `coverage_percentage`
+
+### 7. Auto-Proceed to Next Step
+
+{IF coverage_percentage is 0%:}
+"**⚠️ 0% coverage — no matching skills found for any referenced technology.** All subsequent analysis (integration, requirements) will be vacuous and produce empty tables.
+
+**Recommended:** Generate skills with [CS] or [QS] for your architecture technologies, then re-run [VS].
+
+**Select:** [X] Halt workflow (recommended) | [C] Continue anyway"
+
+- IF X: "**Workflow halted.** Generate skills and re-run [VS] when ready." — END workflow
+- IF C: "**Continuing with 0% coverage — results will be limited.**"
+
+  Load, read the full file and then execute `{nextStepFile}`.
+
+{IF coverage_percentage is NOT 0%:}
+"**Proceeding to integration analysis...**"
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Coverage patterns loaded from {coveragePatternsData}
+- All technology references extracted from architecture document with section citations
+- Every referenced technology cross-referenced against skill inventory
+- Coverage matrix displayed with binary Covered/Missing verdicts
+- Extra skills detected and reported as informational
+- Missing skills have actionable recommendations (run [CS] or [QS])
+- Coverage Matrix section appended to {outputFile}
+- Auto-proceeded to step 03
+
+### ❌ SYSTEM FAILURE:
+
+- Inventing technologies not mentioned in the architecture document
+- Ambiguous verdicts (anything other than Covered or Missing)
+- Analyzing API surfaces or skill content in detail (that is Step 03)
+- Not providing actionable recommendations for missing skills
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.