bmad-module-skill-forge 0.2.0

package/src/workflows/update-skill/steps-c/step-03-re-extract.md

@@ -0,0 +1,187 @@
+---
+name: 'step-03-re-extract'
+description: 'Tier-aware AST extraction on changed files only, producing fresh exports with confidence tiers'
+
+nextStepFile: './step-04-merge.md'
+---
+
+# Step 3: Re-Extract Changed Exports
+
+## STEP GOAL:
+
+Perform tier-aware extraction on only the changed files identified in step 02, producing fresh export data with confidence tier labels (T1/T1-low/T2) that will be merged into the existing skill in step 04.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ⚙️ 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 precision code analyst operating in Surgeon mode
+- ✅ Zero-hallucination principle: every extracted instruction must include AST file:line citation
+- ✅ Confidence tier labels are MANDATORY on all extracted content
+- ✅ You bring AST-backed structural analysis; the source code provides ground truth
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on extracting changed exports — do not merge or modify existing skill
+- 🚫 FORBIDDEN to extract unchanged files — only files in the change manifest
+- 🚫 FORBIDDEN to modify SKILL.md — extraction produces intermediate data for step 04
+- 💬 DO NOT BE LAZY — For EACH changed file, launch a subprocess for deep AST analysis (Pattern 2)
+- ⚙️ If subprocess unavailable, perform extraction sequentially in main thread
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow MANDATORY SEQUENCE exactly
+- 💾 Produce structured extraction results per changed file
+- 📖 Label every extraction with confidence tier
+- 🚫 FORBIDDEN to hallucinate exports — only extract what exists in source
+
+## CONTEXT BOUNDARIES:
+
+- Available: change manifest from step 02, forge tier from step 01, source files
+- Focus: extraction only — no merge, no write
+- Limits: only changed files from manifest
+- Dependencies: step 02 must have produced change manifest
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Determine Extraction Strategy by Tier
+
+**Quick tier (text pattern matching):**
+- Extract function/class/type names via regex patterns
+- Extract export statements via text matching
+- Confidence: T1-low (pattern-matched, not AST-verified)
+
+**Forge tier (AST structural extraction):**
+- Use ast_bridge for full structural extraction
+- Extract: function signatures, type definitions, class members, exported constants
+- Extract: parameter types, return types, JSDoc/docstring comments
+- Confidence: T1 (AST-verified structural truth)
+
+**Deep tier (AST + QMD semantic enrichment):**
+- Perform all Forge tier extractions (T1)
+- Additionally: launch a subprocess that queries qmd_bridge for temporal context on changed exports, returning T2 evidence per export
+- QMD provides: usage patterns, historical context, related documentation
+- Confidence: T1 for structural, T2 for semantic enrichment
+
+### 2. Extract Changed Files
+
+DO NOT BE LAZY — For EACH file in the change manifest with status MODIFIED, ADDED, or RENAMED, launch a subprocess that:
+
+1. Loads the source file
+2. Performs tier-appropriate extraction (Quick/Forge/Deep)
+3. For each export found:
+   - Record: export name, type (function/class/type/constant), signature
+   - Record: file path, start line, end line
+   - Record: parameters with types (if function/method)
+   - Record: return type (if function/method)
+   - Record: JSDoc/docstring summary (if present)
+   - Label: confidence tier (T1/T1-low/T2)
+4. Returns structured extraction findings to parent
+
+**For DELETED files:** No extraction needed — deletions handled in merge step.
+
+**For MOVED files:** Re-extract at new location to update file:line references.
+
+### 3. Deep Tier QMD Enrichment (Conditional)
+
+**ONLY if forge_tier == Deep:**
+
+Launch a subprocess that loads qmd_bridge and for each changed export:
+1. Queries QMD collection for semantic context related to the export
+2. Searches for usage patterns, documentation references, temporal history
+3. Returns T2 evidence per export (usage frequency, context snippets, related concepts)
+
+**If forge_tier != Deep:** Skip this section with notice: "QMD enrichment skipped (tier: {forge_tier})"
+
+### 4. Compile Extraction Results
+
+Aggregate all subprocess results into structured extraction data:
+
+```
+Extraction Results:
+  files_extracted: [count]
+  exports_extracted: [count]
+  confidence_breakdown:
+    T1: [count]
+    T1-low: [count]
+    T2: [count]
+
+  Per-file extractions:
+    {file_path}:
+      exports:
+        - name: {export_name}
+          type: function|class|type|constant
+          signature: {full signature}
+          location: {file}:{start_line}-{end_line}
+          confidence: T1|T1-low|T2
+          parameters: [{name, type}]
+          return_type: {type}
+          docstring: {summary}
+          qmd_evidence: {if Deep tier}
+```
+
+### 5. Display Extraction Summary and Auto-Proceed
+
+"**Re-Extraction Complete:**
+
+| Metric | Count |
+|--------|-------|
+| Files extracted | {count} |
+| Exports extracted | {count} |
+| T1 (AST-verified) | {count} |
+| T1-low (pattern-matched) | {count} |
+| T2 (QMD-enriched) | {count} |
+
+**Proceeding to merge with existing skill...**"
+
+### 6. Present MENU OPTIONS
+
+Display: "**Proceeding to merge...**"
+
+#### Menu Handling Logic:
+
+- After extraction results are compiled, 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 extraction completes
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN all changed files have been extracted and results compiled will you load {nextStepFile} to begin the merge operation.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Every changed file from manifest extracted with tier-appropriate method
+- All exports labeled with confidence tier (T1/T1-low/T2)
+- AST file:line citations on every extracted export
+- QMD enrichment performed for Deep tier (skipped with notice for Quick/Forge)
+- Extraction results compiled with per-file detail
+- Summary displayed before auto-proceeding
+- No unchanged files extracted
+
+### ❌ SYSTEM FAILURE:
+
+- Extracting unchanged files (wasting resources)
+- Missing confidence tier labels on any export
+- Hallucinating exports not present in source code
+- Skipping QMD enrichment at Deep tier
+- Modifying SKILL.md or any existing artifacts during extraction
+
+**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-04-merge.md

@@ -0,0 +1,230 @@
+---
+name: 'step-04-merge'
+description: 'Merge new extractions into existing skill content, preserving all [MANUAL] sections with conflict resolution'
+
+nextStepFile: './step-05-validate.md'
+manualSectionRulesFile: '../data/manual-section-rules.md'
+mergeConflictRulesFile: '../data/merge-conflict-rules.md'
+---
+
+# Step 4: Merge
+
+## STEP GOAL:
+
+Merge freshly extracted export data into the existing SKILL.md content while preserving all [MANUAL] sections. Detect and resolve conflicts where regenerated content overlaps developer-authored content. For stack skills, merge across all output files.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ⚙️ 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 precision code analyst operating in Surgeon mode
+- ✅ [MANUAL] section preservation is the HIGHEST PRIORITY — zero content loss
+- ✅ Every merge decision must be traceable and reversible
+- ✅ When in doubt about [MANUAL] conflicts, HALT and ask the user
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on merging extractions into existing skill content
+- 🚫 FORBIDDEN to delete or modify [MANUAL] section content
+- 🚫 FORBIDDEN to write files — merge produces in-memory result for step 06
+- 💬 If [MANUAL] conflicts detected: HALT and present to user for resolution
+- 💬 If clean merge: auto-proceed without user interaction
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow MANDATORY SEQUENCE exactly
+- 💾 Load merge rules from data files for conflict resolution
+- 📖 Track every merge operation for evidence report
+- 🚫 FORBIDDEN to auto-resolve [MANUAL] conflicts — user must decide
+
+## CONTEXT BOUNDARIES:
+
+- Available: extraction results from step 03, existing SKILL.md content, [MANUAL] inventory from step 01, change manifest from step 02
+- Focus: content merge and [MANUAL] preservation
+- Limits: in-memory merge only — no file writes
+- Dependencies: step 03 must have produced extraction results
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load Merge Rules
+
+Load {manualSectionRulesFile} for [MANUAL] detection and preservation patterns.
+Load {mergeConflictRulesFile} for change category merge strategies and priority order.
+
+### 2. Extract [MANUAL] Blocks
+
+From the [MANUAL] inventory captured in step 01:
+- Extract every `<!-- [MANUAL:section-name] -->` ... `<!-- [/MANUAL:section-name] -->` block
+- Map each block to its parent section heading
+- Store blocks in a preservation map keyed by section-name
+
+### 3. Apply Merge by Priority Order
+
+Follow the merge priority order from {mergeConflictRulesFile}:
+
+**Priority 1 — Process DELETED exports:**
+- Remove generated content for deleted exports
+- Check if deleted export has attached [MANUAL] blocks
+- If [MANUAL] attached: flag as ORPHAN conflict (do not remove)
+- If no [MANUAL]: remove generated content cleanly
+
+**Priority 2 — Process MOVED exports:**
+- Update file:line citations in generated content
+- Update provenance map file references
+- [MANUAL] blocks unaffected (content unchanged)
+
+**Priority 3 — Process RENAMED exports:**
+- Replace old identifier with new identifier in generated content
+- Check if [MANUAL] blocks reference old identifier name
+- If referenced: flag as STALE_REFERENCE conflict
+
+**Priority 4 — Process MODIFIED exports:**
+- Replace generated content for the export with fresh extraction
+- Preserve [MANUAL] blocks adjacent to the export
+- Check for position conflicts (new content shifts [MANUAL] block)
+- If position conflict: flag as POSITION conflict
+
+**Priority 5 — Process NEW exports:**
+- Append new export content to appropriate section
+- Place before any [MANUAL] blocks at section boundary
+- No conflicts expected (new content, no existing [MANUAL])
+
+### 4. Check for Conflicts
+
+Scan all merge operations for flagged conflicts:
+
+**If ZERO conflicts:**
+- Report clean merge
+- Auto-proceed to step 05
+
+**If conflicts detected:**
+
+Present each conflict to user:
+
+"**[MANUAL] Conflict Resolution Required:**
+
+**Conflict {N} of {total}:** {conflict_type}
+
+{Detailed description of the conflict with before/after context}
+
+**Options:**
+- **[K]eep** — Preserve [MANUAL] content as-is, adjust generated content around it
+- **[R]emove** — Remove the [MANUAL] block (content will be lost)
+- **[E]dit** — Show me both versions, I'll provide the resolution
+
+Select: [K] Keep / [R] Remove / [E] Edit"
+
+Process each conflict with user's decision.
+
+### 5. Stack Skill Merge (Conditional)
+
+**ONLY if skill_type == "stack":**
+
+Apply the same merge process to each stack output file:
+- `references/{library}.md` — merge per-library changes, preserve [MANUAL] blocks
+- `references/integrations/{pair}.md` — merge per-integration-pair
+- `metadata.json` — regenerate completely (no [MANUAL] support)
+- `context-snippet.md` — regenerate completely (no [MANUAL] support)
+
+Report stack file merge status for each file.
+
+**If skill_type != "stack":** Skip with notice: "Individual skill — single file merge."
+
+### 6. Compile Merge Results
+
+Build merge result summary:
+
+```
+Merge Results:
+  exports_updated: [count]
+  exports_added: [count]
+  exports_removed: [count]
+  exports_moved: [count]
+  exports_renamed: [count]
+
+  manual_sections_preserved: [count]
+  manual_conflicts_resolved: [count]
+  manual_orphans_kept: [count]
+  manual_orphans_removed: [count]
+
+  stack_files_merged: [count] (if stack skill)
+```
+
+### 7. Display Merge Summary
+
+"**Merge Complete:**
+
+| Metric | Count |
+|--------|-------|
+| Exports updated | {count} |
+| Exports added | {count} |
+| Exports removed | {count} |
+| [MANUAL] sections preserved | {count} |
+| Conflicts resolved | {count} |"
+
+### 8. Present MENU OPTIONS
+
+**If conflicts were resolved (user interaction occurred):**
+
+Display: "**Merge complete with conflict resolution. Select:** [C] Continue to Validation"
+
+#### Menu Handling Logic:
+
+- IF C: Load, read entire file, then execute {nextStepFile}
+- IF Any other: help user respond, then [Redisplay Menu Options](#8-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after conflict resolution
+- ONLY proceed when user selects 'C'
+
+**If clean merge (no conflicts):**
+
+Display: "**Clean merge — proceeding to validation...**"
+
+#### Clean Merge Menu Handling Logic:
+
+- Immediately load, read entire file, then execute {nextStepFile}
+
+#### Clean Merge EXECUTION RULES:
+
+- This is an auto-proceed path when no conflicts exist
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN all merge operations are complete and any [MANUAL] conflicts have been resolved by the user will you load {nextStepFile} to begin validation.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All [MANUAL] sections preserved with zero content loss
+- Merge applied in correct priority order (delete → move → rename → modify → add)
+- Every conflict presented to user for resolution (no auto-resolution of [MANUAL] conflicts)
+- Stack skill files merged if applicable
+- Merge results compiled with full accounting
+- Clean merges auto-proceed; conflict merges require user [C]
+
+### ❌ SYSTEM FAILURE:
+
+- ANY [MANUAL] content lost or modified without user consent
+- Auto-resolving [MANUAL] conflicts without user input
+- Writing files during merge (merge is in-memory only)
+- Applying merge out of priority order
+- Not detecting orphaned [MANUAL] blocks on deleted exports
+- Not handling stack skill multi-file merge
+
+**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-05-validate.md

@@ -0,0 +1,187 @@
+---
+name: 'step-05-validate'
+description: 'Validate updated skill against spec, verify MANUAL integrity, and check confidence tier consistency'
+
+nextStepFile: './step-06-write.md'
+---
+
+# Step 5: Validate
+
+## STEP GOAL:
+
+Validate the merged skill content against the agentskills.io specification, verify all [MANUAL] sections survived the merge intact, and check confidence tier consistency across all re-extracted content. This is an advisory validation — findings are warnings, not blockers.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ⚙️ 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 precision code analyst operating in Surgeon mode
+- ✅ Validation is advisory — flag issues but do not block the workflow
+- ✅ Every finding must include specific file:line reference
+- ✅ Zero-hallucination principle applies to validation findings too
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on validation — do not fix issues (that's the user's choice)
+- 🚫 FORBIDDEN to modify merged content — validation is read-only
+- 💬 Launch parallel validation checks when subprocess available (Pattern 4)
+- ⚙️ If subprocess unavailable, perform checks sequentially in main thread
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow MANDATORY SEQUENCE exactly
+- 💾 Compile validation findings with severity levels
+- 📖 Track pass/fail for each validation category
+- 🚫 Validation is ADVISORY — do not block on warnings
+
+## CONTEXT BOUNDARIES:
+
+- Available: merged skill content from step 04, extraction results from step 03, [MANUAL] inventory from step 01
+- Focus: quality assurance — spec compliance, [MANUAL] integrity, confidence consistency
+- Limits: read-only — do not modify merged content
+- Dependencies: step 04 must have completed merge (with or without conflict resolution)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Launch Parallel Validation Checks
+
+Launch subprocesses in parallel for each validation category, aggregating results when complete:
+
+**Check A — Spec Compliance:**
+- Validate merged SKILL.md structure against agentskills.io specification (via skills_ref if available)
+- Verify required sections present: exports, usage patterns, conventions
+- Verify export entries have: name, type, signature, file:line reference
+- Flag missing or incomplete sections
+
+**Check B — [MANUAL] Section Integrity:**
+- Compare [MANUAL] inventory from step 01 against merged content
+- Verify every [MANUAL] block from inventory exists in merged result
+- Verify [MANUAL] content is byte-identical (zero modification)
+- Flag any [MANUAL] blocks that were moved, truncated, or missing
+
+**Check C — Confidence Tier Consistency:**
+- Verify all re-extracted exports have confidence labels (T1/T1-low/T2)
+- Verify tier labels match forge tier capabilities:
+  - Quick tier: only T1-low allowed
+  - Forge tier: T1 expected (T1-low for degraded operations)
+  - Deep tier: T1 + T2 expected
+- Flag mismatched or missing tier labels
+
+**Check D — Provenance Completeness:**
+- Verify every export in merged SKILL.md has a provenance map entry
+- Verify file:line references point to actual source locations
+- Verify no stale references to old file paths or line numbers
+- Flag orphaned provenance entries (export removed but provenance remains)
+
+### 2. Aggregate Validation Results
+
+Compile results from all checks:
+
+```
+Validation Results:
+  spec_compliance:
+    status: PASS|WARN|FAIL
+    findings: [{severity, description, location}]
+
+  manual_integrity:
+    status: PASS|WARN|FAIL
+    sections_verified: [count]
+    sections_intact: [count]
+    findings: [{severity, description, section_name}]
+
+  confidence_consistency:
+    status: PASS|WARN|FAIL
+    exports_checked: [count]
+    findings: [{severity, description, export_name, expected_tier, actual_tier}]
+
+  provenance_completeness:
+    status: PASS|WARN|FAIL
+    entries_checked: [count]
+    findings: [{severity, description, export_name}]
+```
+
+### 3. For Stack Skills — Validate Reference Files
+
+**ONLY if skill_type == "stack":**
+
+Repeat checks A-D for each reference file:
+- `references/{library}.md` — spec compliance and [MANUAL] integrity
+- `references/integrations/{pair}.md` — spec compliance and [MANUAL] integrity
+
+**If skill_type != "stack":** Skip with notice.
+
+### 4. Display Validation Summary
+
+"**Validation Results:**
+
+| Check | Status | Findings |
+|-------|--------|----------|
+| Spec Compliance | {PASS/WARN/FAIL} | {count} findings |
+| [MANUAL] Integrity | {PASS/WARN/FAIL} | {count} findings |
+| Confidence Tiers | {PASS/WARN/FAIL} | {count} findings |
+| Provenance | {PASS/WARN/FAIL} | {count} findings |
+
+**Overall: {ALL_PASS / WARNINGS_FOUND / FAILURES_FOUND}**"
+
+**If WARNINGS or FAILURES found:**
+
+List each finding with severity and description:
+
+"**Findings:**
+1. [{severity}] {description} — {location}
+2. [{severity}] {description} — {location}
+..."
+
+"**Note:** Validation is advisory. These findings are reported for your awareness but do not block the update. You may choose to address them after the update completes."
+
+### 5. Present MENU OPTIONS
+
+Display: "**Proceeding to write updated files...**"
+
+#### Menu Handling Logic:
+
+- After validation summary is displayed, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed validation step with no user choices
+- Validation is advisory — findings are informational, not blocking
+- Proceed directly to next step after summary display
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN all validation checks have completed and findings are displayed will you load {nextStepFile} to write the updated files. Validation does NOT block — it informs.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All four validation checks executed (spec, [MANUAL], confidence, provenance)
+- Stack skill reference files validated if applicable
+- Findings reported with severity and specific locations
+- [MANUAL] integrity verified with byte-level comparison
+- Validation results displayed clearly
+- Auto-proceeds regardless of findings (advisory mode)
+
+### ❌ SYSTEM FAILURE:
+
+- Skipping any of the four validation checks
+- Blocking the workflow on validation warnings
+- Not verifying [MANUAL] section integrity
+- Hallucinating validation findings not backed by actual comparison
+- Modifying merged content during validation
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.