bmad-module-skill-forge 0.2.0

package/src/workflows/audit-skill/steps-c/step-01-init.md

@@ -0,0 +1,195 @@
+---
+name: 'step-01-init'
+description: 'Load existing skill, provenance map, and detect forge tier for drift analysis'
+
+nextStepFile: './step-02-re-index.md'
+outputFile: '{forge_data_folder}/{skill_name}/drift-report-{timestamp}.md'
+templateFile: '../data/drift-report-template.md'
+---
+
+# Step 1: Initialize Audit
+
+## STEP GOAL:
+
+Load the existing skill artifacts, provenance map, and forge tier configuration to establish the baseline for drift detection. Create the drift report document and present a baseline summary for user confirmation before proceeding with analysis.
+
+## 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 skill auditor operating in Ferris Audit mode
+- ✅ Every finding must trace to actual code with file:line citations
+- ✅ You enforce the zero-hallucination principle: structural truth over semantic guessing
+- ✅ You bring AST analysis expertise, the source code provides ground truth
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on loading skill artifacts and establishing the baseline
+- 🚫 FORBIDDEN to perform any diff or analysis — that happens in later steps
+- 🚫 FORBIDDEN to proceed if skill path is invalid or SKILL.md not found
+- 💬 Present baseline summary clearly so user can confirm before analysis begins
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Discover and load all required input artifacts
+- 💾 Create drift report from {templateFile} with populated frontmatter
+- 📖 Track loaded artifacts in report frontmatter
+- 🚫 Do not proceed to analysis without user confirmation at the gate
+
+## CONTEXT BOUNDARIES:
+
+- Available: User-provided skill path, SKF module config variables
+- Focus: Loading and validating all inputs needed for drift analysis
+- Limits: Do not analyze or compare — only load and baseline
+- Dependencies: setup-forge must be completed (forge-tier.yaml exists), skill must have been created by create-skill (provenance-map.json exists)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Get Skill Path
+
+"**Audit Skill — Drift Detection**
+
+Which skill would you like to audit? Please provide the skill name or path."
+
+**If user provides skill name (not full path):**
+- Resolve to `{skills_output_folder}/{skill_name}/`
+
+**If user provides full path:**
+- Use as provided
+
+**Validate:** Check that `SKILL.md` exists at the resolved path.
+- If missing → "Skill not found at `{resolved_path}`. Check the path and try again."
+- If found → Continue
+
+### 2. Load Forge Tier
+
+Load `{sidecar_path}/forge-tier.yaml` to detect available tools.
+
+**If file missing:**
+- "Setup-forge has not been run. Cannot determine tool availability. Run `[SF] Setup Forge` first."
+- HALT workflow
+
+**If found:**
+- Extract tier level: Quick / Forge / Deep
+- Extract available tools: gh_bridge, ast_bridge, qmd_bridge
+
+### 3. Load Skill Artifacts
+
+Load the following from the skill directory:
+
+**Required:**
+- `SKILL.md` — The skill document to audit
+- `metadata.json` — Skill metadata (version, created date, export count)
+
+**Extract from metadata.json:**
+- `skill_name`, `version`, `created` date, `forge_tier` used during creation
+- `source_root` — Original source code path
+
+### 4. Load Provenance Map
+
+Search for provenance map at `{forge_data_folder}/{skill_name}/provenance-map.json`
+
+**If found:**
+- Load and extract: export list, file mappings, extraction timestamps, confidence tiers
+- Record provenance map age (days since last extraction)
+
+**If missing:**
+- "No provenance map found for `{skill_name}`. This skill may not have been created by create-skill."
+- "**Degraded mode available:** I can perform text-based comparison without provenance data. Findings will have T1-low confidence."
+- "**[D]egraded mode** — proceed with text-diff only"
+- "**[X]** — abort audit"
+- Wait for user selection. If D, set `degraded_mode: true`. If X, halt workflow.
+
+### 5. Resolve Source Path
+
+**If provenance map loaded:**
+- Use `source_root` from provenance map as source code path
+- Verify source path still exists and is accessible
+
+**If degraded mode:**
+- Ask user: "Please provide the path to the current source code."
+
+**Validate:** Confirm source directory exists and contains expected files.
+
+### 6. Create Drift Report
+
+Create `{outputFile}` from `{templateFile}`:
+
+- Populate frontmatter: skill_name, skill_path, source_path, forge_tier, date, user_name
+- Set `stepsCompleted: ['step-01-init']`
+- Fill Audit Summary skeleton with loaded baseline data
+
+### 7. Present Baseline Summary (User Gate)
+
+"**Audit Baseline Loaded**
+
+| Field | Value |
+|-------|-------|
+| **Skill** | {skill_name} v{version} |
+| **Created** | {created_date} |
+| **Source** | {source_path} |
+| **Forge Tier** | {current_tier} (created at {original_tier}) |
+| **Provenance Age** | {days} days since last extraction |
+| **Export Count** | {count} exports in provenance map |
+| **Mode** | {normal / degraded} |
+
+**Analysis plan based on tier:**
+- {Quick: text-diff comparison (T1-low confidence)}
+- {Forge: AST structural comparison (T1 confidence)}
+- {Deep: AST structural + QMD semantic comparison (T1 + T2 confidence)}
+
+**Ready to begin drift analysis?**"
+
+### 8. Present MENU OPTIONS
+
+Display: "**Select:** [C] Continue to Analysis"
+
+#### Menu Handling Logic:
+
+- IF C: Save baseline to {outputFile}, update frontmatter stepsCompleted, then load, read entire file, then execute {nextStepFile}
+- IF Any other: help user, then [Redisplay Menu Options](#8-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN C is selected and the drift report has been created with baseline data populated, will you then load and read fully `{nextStepFile}` to execute and begin source re-indexing.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Skill artifacts loaded (SKILL.md, metadata.json)
+- Forge tier detected from sidecar
+- Provenance map loaded (or degraded mode confirmed)
+- Source path resolved and validated
+- Drift report created from template with populated frontmatter
+- Baseline summary presented to user
+- User confirmed via [C] Continue
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding without valid skill path
+- Not loading provenance map or offering degraded mode
+- Not detecting forge tier
+- Performing analysis in this step (analysis is Steps 02-05)
+- Proceeding without user confirmation at the gate
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/audit-skill/steps-c/step-02-re-index.md

@@ -0,0 +1,191 @@
+---
+name: 'step-02-re-index'
+description: 'Re-scan source code with current tier tools to build fresh extraction snapshot'
+
+nextStepFile: './step-03-structural-diff.md'
+outputFile: '{forge_data_folder}/{skill_name}/drift-report-{timestamp}.md'
+---
+
+# Step 2: Re-Index Source
+
+## STEP GOAL:
+
+Re-scan the source code using the current forge tier tools to build a fresh extraction snapshot. This snapshot will be compared against the original provenance map in Step 03 to detect structural drift.
+
+## 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
+- ⚙️ 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 skill auditor operating in Ferris Audit mode
+- ✅ Every extraction must be precise — file paths, line numbers, signatures
+- ✅ You enforce zero-hallucination: only extract what actually exists in source
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on extracting current source state — do NOT compare yet
+- 🚫 FORBIDDEN to perform any diff or comparison — that happens in Step 03
+- 🚫 FORBIDDEN to skip files or take shortcuts in extraction
+- 💬 Use subprocess Pattern 2 (per-file deep analysis) when available for AST extraction
+- ⚙️ If subprocess unavailable, perform extraction in main thread file by file
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Extract all public exports from source using tier-appropriate tools
+- 💾 Store current extraction as internal state for Step 03
+- 📖 Update {outputFile} frontmatter stepsCompleted when complete
+- 🚫 Do not append analysis sections to drift report — only update frontmatter
+
+## CONTEXT BOUNDARIES:
+
+- Available: Source path, forge tier, tool availability (from Step 01)
+- Focus: Building a complete current-state extraction snapshot
+- Limits: Extract only — no comparison, no judgment, no severity
+- Dependencies: Step 01 must have loaded skill baseline and validated source path
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Determine Extraction Strategy
+
+Based on forge tier detected in Step 01:
+
+**Quick tier (no AST tools):**
+- Read source files via gh_bridge or direct file I/O
+- Extract export names by text pattern matching (function/class/type declarations)
+- Confidence label: T1-low
+
+**Forge tier (ast-grep available):**
+- Use ast_bridge to perform AST extraction per source file
+- Extract: export name, type (function/class/type/const), full signature, file path, line number
+- Confidence label: T1
+
+**Deep tier (ast-grep + QMD available):**
+- Forge extraction (above) PLUS
+- Query qmd_bridge for temporal context: when exports were added, modification history, usage frequency
+- Confidence labels: T1 for structural, T2 for temporal context
+
+### 2. Scan Source Files
+
+Identify all source files in the source directory that contain public exports.
+
+"**Scanning source files...**"
+
+- List all relevant source files (exclude test files, config files, build artifacts)
+- Count files to process
+- Report: "Found {count} source files to extract."
+
+### 3. Extract Current Exports
+
+**DO NOT BE LAZY — For EACH source file, launch a subprocess that:**
+1. Loads the source file
+2. Extracts all public exports using tier-appropriate method
+3. Records: export name, type, signature, file path, line number, confidence tier
+4. Returns structured findings to parent
+
+**If subprocess unavailable:** Perform extraction in main thread, processing each file sequentially.
+
+**Build extraction snapshot:**
+```
+{
+  "extraction_date": "{timestamp}",
+  "forge_tier": "{tier}",
+  "source_root": "{source_path}",
+  "files_scanned": {count},
+  "exports": [
+    {
+      "name": "{export_name}",
+      "type": "function|class|type|const|interface",
+      "signature": "{full signature}",
+      "file": "{relative_path}",
+      "line": {line_number},
+      "confidence": "T1|T1-low|T2"
+    }
+  ]
+}
+```
+
+### 4. Deep Tier Enhancement (Deep Only)
+
+**IF forge tier is Deep:**
+
+Query qmd_bridge for temporal context on each extracted export:
+- When was this export first added?
+- Has it been modified recently?
+- What is its usage frequency across the codebase?
+
+Append temporal metadata to each export in the snapshot.
+
+**IF forge tier is Quick or Forge:**
+Skip this section. Temporal context requires Deep tier.
+
+### 5. Validate Extraction Completeness
+
+"**Extraction complete.**
+
+| Metric | Value |
+|--------|-------|
+| Files scanned | {count} |
+| Exports found | {total_exports} |
+| Functions | {function_count} |
+| Classes | {class_count} |
+| Types/Interfaces | {type_count} |
+| Constants | {const_count} |
+| Confidence | {T1/T1-low/T2} |
+
+**Proceeding to structural comparison...**"
+
+### 6. Update Report and Auto-Proceed
+
+Update {outputFile} frontmatter:
+- Append `'step-02-re-index'` to `stepsCompleted`
+
+### 7. Present MENU OPTIONS
+
+Display: "**Proceeding to structural diff...**"
+
+#### Menu Handling Logic:
+
+- After extraction is complete and frontmatter updated, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed analysis step with no user choices
+- Proceed directly to next step after extraction
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the extraction snapshot is complete with all source files processed will you then load and read fully `{nextStepFile}` to execute and begin structural comparison.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All source files scanned (none skipped)
+- All public exports extracted with file:line references
+- Confidence tier labels applied to every extraction
+- Tier-appropriate tools used (AST for Forge+, text for Quick)
+- Deep tier temporal context added if applicable
+- Extraction snapshot complete and validated
+- Frontmatter stepsCompleted updated
+
+### ❌ SYSTEM FAILURE:
+
+- Skipping source files or being lazy with extraction
+- Not recording file:line references for each export
+- Performing comparison in this step (comparison is Step 03)
+- Missing confidence tier labels
+- Hardcoded paths instead of frontmatter variables
+- Not using subprocess Pattern 2 when available
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/audit-skill/steps-c/step-03-structural-diff.md

@@ -0,0 +1,194 @@
+---
+name: 'step-03-structural-diff'
+description: 'Compare original provenance map extractions against current scan to detect structural drift'
+
+nextStepFile: './step-04-semantic-diff.md'
+outputFile: '{forge_data_folder}/{skill_name}/drift-report-{timestamp}.md'
+---
+
+# Step 3: Structural Diff
+
+## STEP GOAL:
+
+Compare the original provenance map extractions from create-skill against the current re-index snapshot from Step 02 to detect structural drift. Identify added, removed, and changed exports with file:line citations and confidence tier labels.
+
+## 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
+- ⚙️ 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 skill auditor performing structural comparison
+- ✅ Every drift finding must have a file:line citation from either the provenance map or current scan
+- ✅ Zero hallucination — only report drift that is structurally verifiable
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on structural comparison — added/removed/changed exports
+- 🚫 FORBIDDEN to classify severity — that happens in Step 05
+- 🚫 FORBIDDEN to suggest remediation — that happens in Step 06
+- 💬 Use subprocess Pattern 4 (parallel execution) when available to compare export categories simultaneously
+- ⚙️ If subprocess unavailable, compare categories sequentially in main thread
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Compare provenance map exports against current extraction snapshot
+- 💾 Append ## Structural Drift section to {outputFile}
+- 📖 Update {outputFile} frontmatter stepsCompleted when complete
+- 🚫 Only structural findings — no semantic or severity analysis
+
+## CONTEXT BOUNDARIES:
+
+- Available: Provenance map (from Step 01), current extraction snapshot (from Step 02), forge tier
+- Focus: Structural export-level comparison only
+- Limits: Do not classify severity, do not analyze semantics, do not suggest fixes
+- Dependencies: Steps 01 and 02 must be complete
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Prepare Comparison Sets
+
+Load both datasets:
+
+**Baseline (from provenance map):**
+- Export list with names, types, signatures, file paths, line numbers
+
+**Current (from Step 02 extraction):**
+- Export list with names, types, signatures, file paths, line numbers
+
+Normalize both sets for comparison:
+- Match by export name (primary key)
+- Group by file for location-aware comparison
+
+### 2. Detect Added Exports
+
+**Launch subprocess (Pattern 4 — parallel execution):**
+
+Find exports that exist in current scan but NOT in provenance map.
+
+For each added export, record:
+- Export name, type, signature
+- File path and line number (from current scan)
+- Confidence tier (T1 if AST-backed, T1-low if text-based)
+
+**If subprocess unavailable:** Iterate current exports, check against provenance map set.
+
+### 3. Detect Removed Exports
+
+Find exports that exist in provenance map but NOT in current scan.
+
+For each removed export, record:
+- Export name, type, signature (from provenance map)
+- Original file path and line number
+- Confidence tier (T1 if AST-backed, T1-low if text-based)
+
+**Special check:** If export name exists but in a different file, classify as MOVED (not removed).
+
+### 4. Detect Changed Exports
+
+Find exports that exist in BOTH sets but have differences.
+
+Compare:
+- **Signature changes:** Parameter count, parameter types, return type
+- **Type changes:** Function became class, const became function, etc.
+- **Location changes:** Same name/signature but different file or line number (MOVED)
+
+For each changed export, record:
+- Export name
+- Original signature → Current signature
+- Original location → Current location
+- What changed (signature / type / location)
+- Confidence tier
+
+### 5. Compile Structural Drift Section
+
+Append to {outputFile}:
+
+```markdown
+## Structural Drift
+
+**Comparison:** Provenance map ({provenance_date}) vs Current scan ({scan_date})
+**Method:** {Quick: text-diff / Forge: AST structural / Deep: AST structural}
+
+### Added Exports ({count})
+
+| Export | Type | Signature | Location | Confidence |
+|--------|------|-----------|----------|------------|
+| {name} | {type} | {signature} | {file}:{line} | {T1/T1-low} |
+
+### Removed Exports ({count})
+
+| Export | Type | Original Signature | Original Location | Confidence |
+|--------|------|-------------------|-------------------|------------|
+| {name} | {type} | {signature} | {file}:{line} | {T1/T1-low} |
+
+### Changed Exports ({count})
+
+| Export | Change Type | Before | After | Location | Confidence |
+|--------|------------|--------|-------|----------|------------|
+| {name} | {signature/type/location} | {old} | {new} | {file}:{line} | {T1/T1-low} |
+
+### Summary
+
+| Category | Count |
+|----------|-------|
+| Added | {added_count} |
+| Removed | {removed_count} |
+| Changed | {changed_count} |
+| **Total Drift Items** | {total} |
+```
+
+### 6. Update Report and Auto-Proceed
+
+Update {outputFile} frontmatter:
+- Append `'step-03-structural-diff'` to `stepsCompleted`
+
+### 7. Present MENU OPTIONS
+
+Display: "**Structural diff complete. {total} drift items found. Proceeding to semantic diff...**"
+
+#### Menu Handling Logic:
+
+- After structural diff section is appended and frontmatter updated, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed analysis step with no user choices
+- Proceed directly to next step after completion
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the ## Structural Drift section has been appended to {outputFile} with all findings documented will you then load and read fully `{nextStepFile}` to execute and begin semantic diff analysis.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All three categories compared: added, removed, changed
+- Every finding has file:line citation
+- Confidence tier labels on all findings
+- Moved exports distinguished from removed+added
+- Structured table format in drift report
+- Summary counts accurate
+- Frontmatter stepsCompleted updated
+
+### ❌ SYSTEM FAILURE:
+
+- Missing any comparison category (added/removed/changed)
+- Findings without file:line citations
+- Missing confidence tier labels
+- Classifying severity in this step (severity is Step 05)
+- Not detecting moved exports (false removed + false added)
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.