bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/workflows/update-skill/steps-c/step-02-detect-changes.md

@@ -1,221 +0,0 @@
----
-name: 'step-02-detect-changes'
-description: 'Diff source file timestamps and hashes against provenance map to identify all changes since last extraction'
-
-nextStepFile: './step-03-re-extract.md'
-noChangeReportFile: './step-07-report.md'
----
-
-# Step 2: Detect Changes
-
-## STEP GOAL:
-
-Compare current source code state against the provenance map to produce a complete change manifest identifying every changed, added, deleted, moved, and renamed file and export since last extraction.
-
-## 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 change must be verified against actual source state
-- ✅ Clinical, terse communication — report changes factually with file:line references
-- ✅ You bring provenance-driven analysis; the source code provides ground truth
-
-### Step-Specific Rules:
-
-- 🎯 Focus ONLY on detecting and classifying changes — do not extract or merge
-- 🚫 FORBIDDEN to modify any files — read-only change detection
-- 🚫 FORBIDDEN to re-extract content — that is step 03
-- 💬 Use subprocess Pattern 4 (parallel): In Claude Code, use multiple parallel Agent tool calls or `run_in_background: true`. In Cursor, use parallel requests (IDE-dependent). In CLI, use `xargs -P` or background processes. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
-- ⚙️ If subprocess unavailable, perform comparison sequentially in main thread
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow MANDATORY SEQUENCE exactly
-- 💾 Build change manifest with categorized findings
-- 📖 Track change counts by category for summary
-- 🚫 FORBIDDEN to proceed if source path is inaccessible
-
-## CONTEXT BOUNDARIES:
-
-- Available: loaded baseline from step 01 (SKILL.md, metadata.json, provenance-map.json, forge-tier, source_root)
-- Focus: change detection only — no extraction, no merge
-- Limits: read-only operations on source code
-- Dependencies: step 01 must have loaded all artifacts successfully
-
-## MANDATORY SEQUENCE
-
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
-### 0. Check for Test Report Input (Gap-Driven Mode)
-
-**If `update_mode == "gap-driven"` (set in step-01 via `--from-test-report`):**
-
-Load the test report at `{test_report_path}` and extract findings:
-
-1. Read the **Gap Report** section — each gap entry has severity, category, and description
-2. Read the **Coverage Analysis** section — each per-export row has documented/missing/mismatch status
-3. Translate findings into change manifest format:
-
-| Gap Severity | Gap Type | Change Category |
-|-------------|----------|-----------------|
-| Critical | Missing export documentation | NEW_EXPORT (undocumented public API) |
-| High | Signature mismatch | MODIFIED_EXPORT (signature needs update) |
-| Medium | Missing type/interface docs | NEW_EXPORT (undocumented type) |
-| Medium | Stale documentation | MODIFIED_EXPORT (docs reference removed export) |
-| Low | Missing metadata/examples | metadata update |
-
-4. Build the change manifest from translated gaps — no file-level timestamp comparison needed since source hasn't changed
-5. Set `gap_count` from the total number of translated entries
-6. **Skip to section 5** (Display Change Summary) with the gap-derived manifest
-
-"**Gap-driven update mode.** Translating {gap_count} test report findings into change manifest — source drift detection skipped."
-
-**If normal mode:** Continue with source drift detection below.
-
-### 1. Scan Current Source State
-
-Read the source directory at `{source_root}` and build a current file inventory:
-- For each source file: record path, file size, last modified timestamp
-- Focus on file types relevant to the skill (from provenance map file patterns)
-- Exclude non-source files (node_modules, build artifacts, etc.)
-
-### 2. Compare Against Provenance Map
-
-**If normal mode (provenance map available):**
-
-Launch subprocesses in parallel that compare source state against provenance map across these categories, returning change findings per category:
-
-**Category A — File-level changes:**
-- Files in provenance map but missing from source → DELETED
-- Files in source but not in provenance map → ADDED
-- Files in both but with different timestamps/sizes → MODIFIED
-- Files with same content at different paths → MOVED
-
-**Category B — Export-level changes (for MODIFIED files only):**
-- For each modified file, compare export list against provenance map exports
-- Exports in provenance but not in source → DELETED_EXPORT
-- Exports in source but not in provenance → NEW_EXPORT
-- Exports with changed signatures/types → MODIFIED_EXPORT
-- Exports at different line numbers but same content → MOVED_EXPORT
-
-**Category C — Rename detection:**
-- Cross-reference deleted files/exports with added files/exports
-- If content similarity > 80%: classify as RENAMED instead of deleted+added. **Similarity mechanism by tier:** Quick: compare file size ratio (within 20%) and export name overlap (>70% of exports match by name). Forge and above: use ast-grep to compare export signatures between the deleted and added files. Forge+/Deep: use CCC semantic similarity when available
-
-**Category D — Script/asset file changes:**
-- Compare `file_entries` from provenance-map.json against current source files
-- For each file_entry: compute current SHA-256 content hash, compare against stored hash
-- Files with changed hashes → MODIFIED_FILE
-- Files in provenance but missing from source → DELETED_FILE
-- Files in source matching detection patterns (scripts/, bin/, assets/, templates/) but not in provenance → NEW_FILE
-- Files in `scripts/[MANUAL]/` or `assets/[MANUAL]/` → SKIP (user-authored, preserved)
-
-Aggregate all subprocess results into a unified change manifest.
-
-**If degraded mode (no provenance map):**
-- All source files are treated as MODIFIED
-- All exports will be fully re-extracted in step 03
-- Skip export-level comparison
-
-### 3. Build Change Manifest
-
-Compile the change manifest with structured entries:
-
-```
-Change Manifest:
-  files_changed: [count]
-  files_added: [count]
-  files_deleted: [count]
-  files_moved: [count]
-
-  exports_modified: [count]
-  exports_new: [count]
-  exports_deleted: [count]
-  exports_renamed: [count]
-  exports_moved: [count]
-
-  scripts_modified, scripts_added, scripts_deleted: {counts}
-  assets_modified, assets_added, assets_deleted: {counts}
-
-  Per-file detail:
-    {file_path}:
-      status: MODIFIED|ADDED|DELETED|MOVED
-      exports_affected: [{export_name, change_type, old_line, new_line}]
-```
-
-### 4. Check for No-Change Shortcut
-
-**If zero changes detected across all categories:**
-
-"**No changes detected.** Source code matches provenance map exactly.
-
-The skill `{skill_name}` is current — no update needed.
-
-**Skipping to report step...**"
-
-→ Skip steps 03-06, immediately load {noChangeReportFile} with "no changes" status.
-
-### 5. Display Change Summary and Auto-Proceed
-
-"**Change Detection Complete:**
-
-| Category | Count |
-|----------|-------|
-| Files modified | {count} |
-| Files added | {count} |
-| Files deleted | {count} |
-| Files moved/renamed | {count} |
-| Exports affected | {total_export_changes} |
-
-**Proceeding to re-extraction of {affected_file_count if normal mode, or gap_count if gap-driven mode} changes...**"
-
-### 6. Present MENU OPTIONS
-
-Display: "**Proceeding to re-extraction...**"
-
-#### Menu Handling Logic:
-
-- After change manifest is built, immediately load, read entire file, then execute {nextStepFile}
-- **EXCEPTION:** If no changes detected (section 4), load {noChangeReportFile} instead
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed step with no user choices
-- Proceed directly to next step after change detection completes
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the change manifest is fully built will you load {nextStepFile} to begin re-extraction. If no changes detected, skip to {noChangeReportFile}.
-
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Every file in provenance map compared against current source state
-- Changes categorized correctly (modified, added, deleted, moved, renamed)
-- Export-level changes detected for modified files
-- Change manifest built with per-file detail
-- No-change shortcut correctly routes to report step
-- Summary displayed before auto-proceeding
-
-### ❌ SYSTEM FAILURE:
-
-- Not comparing all files in provenance map
-- Missing category of changes (e.g., not detecting deletions)
-- Modifying any files during detection
-- Not detecting rename patterns (treating as delete+add)
-- Proceeding with empty change manifest when changes exist
-
-**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-03-re-extract.md

@@ -1,256 +0,0 @@
----
-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'
-extractionPatternsData: '../../create-skill/data/extraction-patterns.md'
-extractionPatternsTracingData: '../../create-skill/data/extraction-patterns-tracing.md'
-remoteSourceResolutionData: '../data/remote-source-resolution.md'
-tierDegradationRulesData: '../../create-skill/data/tier-degradation-rules.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. Check for Docs-Only Mode
-
-**If `source_type: "docs-only"` in the original brief or metadata:**
-
-"**Docs-only skill detected.** This skill was generated from external documentation, not source code. Re-extraction will re-fetch the original `doc_urls` to check for updated content."
-
-- Re-fetch each URL from `doc_urls` (from the brief or metadata) using whatever web fetching capability is available
-- Extract updated API information with T3 `[EXT:{url}]` citations
-- Build the updated extraction inventory from fetched content
-- Skip all source code extraction below — proceed directly to the merge step (section 5 or equivalent)
-
-**If `source_type: "source"` (default):** Continue with source extraction below.
-
-### 1b. Determine Extraction Strategy by Tier
-
-**Remote Source Resolution (Forge/Deep only):**
-
-**MCP source access (ordered fallback):** When `source_repo` is set in metadata.json, try each MCP tool in order to fetch only the changed files from the change manifest. This avoids ephemeral clone overhead entirely. Tools are ordered by data freshness — gh API returns live GitHub content and is preferred for update-skill where current file versions are required. zread and deepwiki depend on manual indexing and may return stale data if indexes haven't been refreshed since the changes being extracted.
-
-1. **gh API** — `gh api repos/{owner}/{repo}/contents/{path}` for raw file content
-   - If accessible: fetch file content (base64-decoded), always current
-   - If rate-limited, 404, or inaccessible: log tool and reason, continue to next tool
-2. **zread** — `get_repo_structure` + `read_file` for targeted file access
-   - If repo found: fetch changed files, proceed with extraction
-   - If "repo not found" or error: log tool and reason, continue to next tool
-   - Caveat: indexed data — may be stale if index wasn't refreshed after the target changes
-3. **deepwiki** — `ask_question` for targeted export/signature queries
-   - If repo indexed and returns usable source data: extract from response
-   - If no results or repo not indexed: log tool and reason, continue to next tool
-   - Caveat: returns synthesized content, not raw source — extraction quality varies; index may be stale
-
-**Confidence labeling:** MCP-fetched content written to a temp file and analyzed with ast-grep → T1. MCP-fetched content analyzed with pattern matching (AST unavailable) → T1-low.
-
-**If all MCP tools fail for this repo:** Fall back to ephemeral clone — load and follow `{remoteSourceResolutionData}` for clone setup, version reconciliation, and AST tool unavailability handling.
-
-**If all approaches fail (MCP + ephemeral clone):** Degrade to provenance-map-only analysis (State 2, T1 confidence from compilation-time data). Warn user: "Source access failed for {source_repo}. Analysis limited to provenance-map baseline."
-
-**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):**
-
-⚠️ **CRITICAL:** Load and follow the **AST Extraction Protocol** from `{extractionPatternsData}`. Use the decision tree based on the number of changed files: prefer MCP `find_code()` for small sets, `find_code_by_rule()` with scoped YAML rules for medium sets, and CLI `--json=stream` with line-by-line streaming for large sets. Never use `ast-grep --json` (without `=stream`) — it loads the entire result set into memory and will fail on large codebases.
-
-- Extract: function signatures, type definitions, class members, exported constants
-- Extract: parameter types, return types, JSDoc/docstring comments
-- Confidence: T1 (AST-verified structural truth)
-
-**Tier degradation handling (Forge/Forge+/Deep):** If ast-grep is unavailable or fails on individual files, follow `{tierDegradationRulesData}` for fallback strategy and user notification requirements. Silent degradation is forbidden — the user must always know when AST extraction was skipped.
-
-**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
-
-**Tool resolution:** `ast_bridge` → ast-grep MCP tools (`find_code`, `find_code_by_rule`) or `ast-grep` CLI. `qmd_bridge` → QMD MCP tools (`mcp__plugin_qmd-plugin_qmd__search`, `vector_search`) or `qmd` CLI. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
-
-### 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/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.
-
-**Re-export tracing (Forge/Deep only):** After extracting changed files, check if any public exports from the package entry point (`__init__.py`, `index.ts`, `lib.rs`) are unresolved — particularly when a changed file is part of a module re-export chain. Follow the **Re-Export Tracing** protocol in `{extractionPatternsTracingData}` to trace unresolved symbols to their actual definition files.
-
-### 2b. CCC Semantic Ranking (Forge+ and Deep with ccc)
-
-**IF `tools.ccc` is true in forge-tier.yaml:**
-
-Before aggregating extraction results, use CCC to assess semantic significance of changes:
-
-1. Run `ccc_bridge.search("{skill_name}", source_root, top_k=15)` — **Tool resolution:** `/ccc` skill search (Claude Code), ccc MCP (Cursor), `ccc search` (CLI) — to get the skill's most semantically central files
-2. Cross-reference the change manifest files with CCC results
-3. Files appearing in BOTH the change manifest AND CCC's top results are **semantically significant changes** — flag them for priority in the merge step
-4. Store `{ccc_significant_changes: [{file, score}]}` in context
-
-This helps the merge step (section 4) prioritize which changes are most likely to affect the skill's core content vs. peripheral modifications.
-
-CCC failures: skip ranking silently, all changes treated equally.
-
-**Note on remote sources:** If `source_root` is an ephemeral clone (remote source), the clone path is not indexed by CCC. The search will return empty results and semantic ranking will be skipped. This is expected — deferred CCC indexing is implemented in create-skill step-03 but not in update-skill. All changes are treated equally for remote sources.
-
-**IF `tools.ccc` is false:** Skip this section silently.
-
-### 3. Deep Tier QMD Enrichment (Conditional)
-
-**ONLY if forge_tier == Deep:**
-
-Read the `qmd_collections` registry from `{sidecar_path}/forge-tier.yaml`.
-
-Find the collection entry matching the current skill: look for an entry where `skill_name` matches the skill being updated AND `type` is `"extraction"`.
-
-**If a matching extraction collection is found:**
-Launch a subprocess that loads qmd_bridge and for each changed export:
-1. Queries the `{skill_name}-extraction` 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 no matching collection found in registry:**
-Log: "No QMD extraction collection found for {skill_name}. T2 enrichment skipped. Re-run [CS] Create Skill to generate the collection."
-Continue without T2 enrichment — extraction still produces T1 results.
-
-**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...**"
-
-- After extraction results are compiled, immediately load, read entire file, then execute {nextStepFile}
-- This is an auto-proceed step with no user choices
-
-## 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/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.