bmad-module-skill-forge 0.2.0

package/src/workflows/create-skill/steps-c/step-01-load-brief.md

@@ -0,0 +1,176 @@
+---
+name: 'step-01-load-brief'
+description: 'Load skill-brief.yaml, validate structure, resolve source code location, load forge tier'
+nextStepFile: './step-02-ecosystem-check.md'
+forgeTierFile: '{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml'
+preferencesFile: '{project-root}/_bmad/_memory/forger-sidecar/preferences.yaml'
+---
+
+# Step 1: Load Brief
+
+## STEP GOAL:
+
+To load and validate the skill-brief.yaml compilation config, resolve the source code location, and load the forge tier from sidecar to determine available capabilities for the compilation pipeline.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🎯 ALWAYS follow the exact instructions in the step file
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a 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 compilation engine performing initialization
+- ✅ This is an autonomous init step — no user interaction needed
+- ✅ Load data, validate structure, resolve paths, determine capabilities
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on loading brief, resolving source, and determining tier
+- 🚫 FORBIDDEN to begin extraction or compilation — that's steps 03-05
+- 🚫 FORBIDDEN to write any output files — this step only loads and validates
+- 💬 Report initialization status clearly
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow MANDATORY SEQUENCE exactly
+- 💾 All loaded data remains in context for subsequent steps
+- 📖 Validate brief structure before proceeding
+- 🚫 Halt with actionable error if prerequisites are missing
+
+## CONTEXT BOUNDARIES:
+
+- Available: User's skill name or brief path from Ferris menu invocation
+- Focus: Loading inputs and determining capabilities
+- Limits: Do NOT begin any extraction or compilation work
+- Dependencies: forge-tier.yaml must exist (from setup-forge workflow)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Load Forge Tier
+
+Load `{forgeTierFile}` completely.
+
+**If file does not exist:**
+Halt with: "Forge halted: No forge configuration found. Run [SF] Setup Forge first to detect tools and set your tier."
+
+**If file exists:**
+Extract and report:
+- `tier`: Quick, Forge, or Deep
+- `tools`: which tools are available (gh, ast-grep, qmd)
+- `tier_override`: if set, use override tier instead of detected
+
+Check for `tier_override` in `{preferencesFile}`. If `tier_override` is set and differs from detected tier, use the override value.
+
+### 2. Discover Skill Brief
+
+**If user provided a specific brief path or skill name:**
+- Search `{project-root}/forge-data/{skill-name}/skill-brief.yaml`
+- If found, load it completely
+
+**If user invoked with --batch flag:**
+- Search specified directory for all `skill-brief.yaml` files
+- List discovered briefs with skill names
+- Store list for batch loop processing
+- For this run, load the FIRST brief (batch loops back for remaining)
+
+**If no brief found:**
+Halt with: "No skill brief found. Run [BS] Brief Skill to create one, or use [QS] Quick Skill for brief-less generation."
+
+### 3. Validate Brief Structure
+
+Check that the loaded skill-brief.yaml contains required fields:
+
+**Required fields:**
+- `name` — skill identifier (kebab-case)
+- `version` — source version to compile against
+- `source_repo` — GitHub owner/repo or local path
+- `language` — primary source language
+- `scope` — what to extract (e.g., "all public exports", specific modules)
+
+**Optional fields:**
+- `source_branch` — branch to use (default: main/master)
+- `source_authority` — official/community/internal (default: community)
+- `include_patterns` — file glob patterns to include
+- `exclude_patterns` — file glob patterns to exclude
+- `description` — human description of the skill
+
+**If required fields missing:**
+Halt with specific error: "Brief validation failed: missing required field `{field}`. Update your skill-brief.yaml and re-run."
+
+### 4. Resolve Source Code Location
+
+**If source_repo is a GitHub URL or owner/repo format:**
+- Verify repository exists via `gh_bridge.list_tree(owner, repo, branch)`
+- If branch not specified, detect default branch
+- Store resolved: owner, repo, branch, file tree
+
+**If source_repo is a local path:**
+- Verify path exists and contains source files
+- Store resolved: local path, file listing
+
+**If source cannot be resolved:**
+Halt with: "Source not found: `{source_repo}`. Verify the repository exists and is accessible."
+
+### 5. Report Initialization
+
+Display initialization summary:
+
+"**Forge initialized.**
+
+**Skill:** {name} v{version}
+**Source:** {source_repo} @ {branch}
+**Language:** {language}
+**Scope:** {scope}
+**Tier:** {tier} — {tier_description}
+**Tools:** {available_tools_list}
+
+Proceeding to ecosystem check..."
+
+Where tier_description follows positive capability framing:
+- Quick: "Source reading and spec validation"
+- Forge: "AST-backed structural extraction"
+- Deep: "Full intelligence — structural + contextual + temporal"
+
+### 6. Menu Handling Logic
+
+**Auto-proceed step — no user interaction.**
+
+After initialization is complete and all data is loaded, immediately load, read entire file, then execute `{nextStepFile}`.
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed initialization step with no user choices
+- Proceed directly to next step after successful initialization
+- If any prerequisite check fails, HALT with actionable error — do NOT proceed
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN forge-tier.yaml is loaded, skill-brief.yaml is validated, and source code location is resolved will you proceed to load `{nextStepFile}` for ecosystem check.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Forge tier loaded from sidecar with tool availability
+- Skill brief loaded and all required fields validated
+- Source code location resolved and accessible
+- Initialization summary displayed with tier and capabilities
+- Auto-proceeded to step-02
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding without forge-tier.yaml (missing prerequisite)
+- Proceeding with invalid or incomplete brief
+- Not resolving source code location before proceeding
+- Beginning extraction or compilation work in this step
+- Not displaying initialization summary
+
+**Master Rule:** This step ONLY loads and validates. It does NOT extract, compile, or write files.

package/src/workflows/create-skill/steps-c/step-02-ecosystem-check.md

@@ -0,0 +1,143 @@
+---
+name: 'step-02-ecosystem-check'
+description: 'Check agentskills.io ecosystem for existing official skill before compilation'
+nextStepFile: './step-03-extract.md'
+---
+
+# Step 2: Ecosystem Check
+
+## STEP GOAL:
+
+To search the agentskills.io ecosystem for an existing official skill matching the brief, advise the user if one is found, and allow them to decide whether to proceed with compilation or install the existing skill.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🎯 ALWAYS follow the exact instructions in the step file
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a 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 compilation engine performing ecosystem discovery
+- ✅ This step is advisory — ecosystem check results never block compilation
+- ✅ Tool unavailability is never an error — it's a graceful skip condition
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on ecosystem search and presenting findings
+- 🚫 FORBIDDEN to begin any extraction or compilation work
+- 🚫 FORBIDDEN to halt the workflow if the ecosystem check fails or times out
+- 💬 If a match is found, present it factually — let the user decide
+- ⏱️ Enforce 5-second timeout on ecosystem queries
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow MANDATORY SEQUENCE exactly
+- 💾 All loaded data remains in context for subsequent steps
+- 📖 Ecosystem check is advisory — never blocking
+- 🚫 Do not modify any files — this step only queries and reports
+
+## CONTEXT BOUNDARIES:
+
+- Available: brief_data (name, version, source_repo, language, scope) and tier from step-01
+- Focus: Searching for existing skills in the ecosystem
+- Limits: Do NOT begin extraction, compilation, or file writing
+- Dependencies: skill-brief.yaml must be loaded and validated from step-01
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Check Ecosystem for Existing Skill
+
+**If skills_ref tool is available:**
+
+Query the ecosystem using the skill name from the brief:
+- `skills_ref.check_ecosystem(brief.name)`
+- Enforce 5-second timeout — if the query does not return within 5 seconds, treat as no match
+- Cache results for 24 hours (if re-running same skill)
+
+**If skills_ref tool is NOT available:**
+
+Skip silently. Tool unavailability is not an error. Proceed as if no match was found.
+
+### 2. Evaluate Results
+
+**If match found (official skill exists):**
+
+Present the finding to the user:
+
+"**Ecosystem match found.**
+
+**Existing skill:** {matched_skill_name} v{matched_version}
+**Source:** {matched_source}
+**Authority:** {official/community}
+**Compatibility:** {compatibility_notes}
+
+An existing skill already covers this source. You can:
+- **[P] Proceed** — compile your own version anyway (useful for customization or different scope)
+- **[I] Install** — install the existing skill instead of compiling
+- **[A] Abort** — cancel this compilation"
+
+**If no match found:**
+
+Auto-proceed silently to next step. Do not display any message about the ecosystem check — absence of a match is the expected case.
+
+**If timeout or error:**
+
+Auto-proceed silently. Log a note in context: "Ecosystem check skipped (timeout/error) — proceeding with compilation."
+
+### 3. Menu Handling Logic
+
+**Conditional menu — only displayed if a match was found.**
+
+#### If Match Found — Present MENU OPTIONS:
+
+Display: "**Ecosystem match found — Select an Option:** [P] Proceed with compilation [I] Install existing [A] Abort"
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- This menu ONLY appears when an ecosystem match is found
+- If no match, timeout, or tool unavailable — auto-proceed with no menu
+
+#### Menu Handling Logic:
+
+- IF P: Note user's decision to proceed despite existing skill. Immediately load, read entire file, then execute `{nextStepFile}`
+- IF I: Display: "Install the existing skill using: `[SF] Setup Forge → install {matched_skill_name}`" then halt workflow. Do not proceed to extraction.
+- IF A: Display: "Compilation aborted. Return to Ferris menu to select another action." then halt workflow.
+- IF no match/timeout/error: Auto-proceed — immediately load, read entire file, then execute `{nextStepFile}`
+- IF Any other comments or queries: help user respond then redisplay the menu
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the ecosystem check is complete (match evaluated, user decision made if applicable) will you proceed to load `{nextStepFile}` for source extraction.
+
+If no match is found, this step auto-proceeds with no user interaction.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Ecosystem check attempted (or gracefully skipped if tool unavailable)
+- 5-second timeout enforced on ecosystem queries
+- Match presented factually with clear options if found
+- No-match case auto-proceeds silently
+- User decision respected (Proceed/Install/Abort)
+- Auto-proceeded to step-03 (when no match or user chose Proceed)
+
+### ❌ SYSTEM FAILURE:
+
+- Halting the workflow because ecosystem check failed or timed out
+- Treating tool unavailability as an error
+- Displaying "no match found" messages (absence should be silent)
+- Beginning extraction or compilation work in this step
+- Proceeding without user decision when a match IS found
+- Not enforcing the 5-second timeout
+
+**Master Rule:** This step is advisory. Tool failures and timeouts are silent skips, not errors. Only a confirmed match requires user interaction.

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

@@ -0,0 +1,184 @@
+---
+name: 'step-03-extract'
+description: 'Tier-dependent source code extraction — AST or source reading for exports, signatures, and types'
+nextStepFile: './step-04-enrich.md'
+extractionPatternsData: '../data/extraction-patterns.md'
+---
+
+# Step 3: Extract
+
+## STEP GOAL:
+
+To extract all public exports, function signatures, type definitions, and co-import patterns from the source code using tier-appropriate tools, building a complete extraction inventory with confidence-tiered provenance citations.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🎯 ALWAYS follow the exact instructions in the step file
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a 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 compilation engine performing structural extraction
+- ✅ Zero hallucination tolerance — every extracted item must trace to source code
+- ✅ Confidence tier labeling is mandatory for every extraction result
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on extracting exports, signatures, types from source code
+- 🚫 FORBIDDEN to compile SKILL.md content — that's step-05
+- 🚫 FORBIDDEN to write any output files — extraction stays in context
+- 🚫 FORBIDDEN to include content that cannot be cited to a source location
+- ⚒️ Every extracted item MUST have a provenance citation: `[AST:{file}:L{line}]` or `[SRC:{file}:L{line}]`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow MANDATORY SEQUENCE exactly
+- 💾 Build extraction inventory in context — do not write files
+- 📖 Load extraction patterns data file for tier-specific strategy
+- 🚫 If an export cannot be verified, exclude it — do not guess
+
+## CONTEXT BOUNDARIES:
+
+- Available: brief_data, tier, source_location, file_tree from step-01; ecosystem_status from step-02
+- Focus: Source code extraction and inventory building
+- Limits: Do NOT compile, assemble, or write any output
+- Dependencies: Source code must be accessible (resolved in step-01)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Load Extraction Patterns
+
+Load `{extractionPatternsData}` completely. Identify the strategy for the current forge tier.
+
+### 2. Apply Scope Filters
+
+From the brief, apply scope and pattern filters:
+
+- `scope` — determines what to extract (e.g., "all public exports", specific modules)
+- `include_patterns` — file globs to include (if specified)
+- `exclude_patterns` — file globs to exclude (if specified)
+
+Build the filtered file list from the source tree resolved in step-01.
+
+### 3. Execute Tier-Dependent Extraction
+
+**Quick Tier (No AST tools):**
+
+1. Use `gh_bridge.list_tree(owner, repo, branch)` to map source structure (if remote)
+2. Identify entry points: index files, main exports, public modules
+3. Use `gh_bridge.read_file(owner, repo, path)` to read each entry point
+4. Extract from source text: exported function names, parameter lists, return types
+5. Infer types from JSDoc, docstrings, type annotations
+6. Confidence: All results T1-low — `[SRC:{file}:L{line}]`
+
+**Forge/Deep Tier (AST available):**
+
+1. Detect language from brief or file extensions
+2. Use `ast_bridge.scan_definitions(path, language)` for each file in scope
+3. For each export: extract function name, full signature, parameter types, return type, line number
+4. Use `ast_bridge.detect_co_imports(path, libraries[])` to find integration points
+5. Build extraction rules YAML data for reproducibility
+6. Confidence: All results T1 — `[AST:{file}:L{line}]`
+
+**If AST tool is unavailable at Forge/Deep tier:**
+
+Degrade to Quick tier extraction silently. Note the degradation in context for the evidence report.
+
+**For each file — handle failures gracefully:**
+
+- If a file cannot be read: log warning, skip file, continue with remaining files
+- If AST parsing fails on a file: fall back to source reading for that file, continue
+
+### 4. Build Extraction Inventory
+
+Compile all extracted data into a structured inventory:
+
+**Per-export entry:**
+- Function/type name
+- Full signature with types
+- Parameters (name, type, required/optional)
+- Return type
+- Source file and line number
+- Provenance citation (`[AST:...]` or `[SRC:...]`)
+- Confidence tier (T1 or T1-low)
+
+**Aggregate counts:**
+- Total files scanned
+- Total exports found
+- Exports by type (functions, types/interfaces, constants)
+- Confidence breakdown (T1 count, T1-low count)
+
+**Co-import patterns (Forge/Deep only):**
+- Libraries commonly imported alongside extracted exports
+- Integration point suggestions
+
+### 5. Present Extraction Summary (Gate 2)
+
+Display the extraction findings for user confirmation:
+
+"**Extraction complete.**
+
+**Files scanned:** {file_count}
+**Exports found:** {export_count} ({function_count} functions, {type_count} types, {constant_count} constants)
+**Confidence:** {t1_count} T1 (AST-verified), {t1_low_count} T1-low (source reading)
+**Tier used:** {tier}
+**Co-import patterns:** {pattern_count} detected
+
+**Top exports:**
+{list top 10 exports with signatures}
+
+{warnings if any files skipped or degraded}
+
+Review the extraction summary above. Select an option to continue."
+
+### 6. Present MENU OPTIONS
+
+Display: "**Extraction Summary — Select an Option:** [C] Continue to compilation"
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting the extraction summary
+- This is Gate 2 — user must confirm before compilation proceeds
+- User may ask questions about the extraction results before continuing
+
+#### Menu Handling Logic:
+
+- IF C: Confirm extraction inventory is complete. Immediately load, read entire file, then execute `{nextStepFile}`
+- IF Any other comments or queries: answer questions about the extraction results, then redisplay the menu
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the extraction inventory is built with provenance citations and the user has confirmed the extraction summary will you proceed to load `{nextStepFile}` for QMD enrichment.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Extraction patterns loaded and tier-appropriate strategy applied
+- Scope filters applied from brief
+- All accessible source files in scope scanned
+- Every extracted item has a provenance citation with confidence tier
+- Extraction inventory built with aggregate counts
+- Graceful degradation if AST tools unavailable
+- Gate 2 summary presented with export counts and confidence breakdown
+- User confirmed before proceeding
+
+### ❌ SYSTEM FAILURE:
+
+- Including exports without provenance citations
+- Guessing or hallucinating function signatures not in source
+- Not applying scope/include/exclude filters from the brief
+- Halting on individual file read failures instead of skipping
+- Not presenting Gate 2 summary for user confirmation
+- Beginning compilation or SKILL.md assembly in this step
+- Not reporting confidence tier breakdown
+
+**Master Rule:** Zero hallucination — every extraction must trace to source code. Uncitable content is excluded, not guessed.

package/src/workflows/create-skill/steps-c/step-04-enrich.md

@@ -0,0 +1,152 @@
+---
+name: 'step-04-enrich'
+description: 'QMD knowledge enrichment for extracted functions — Deep tier only, skip for Quick/Forge'
+nextStepFile: './step-05-compile.md'
+---
+
+# Step 4: Enrich
+
+## STEP GOAL:
+
+To enrich the extraction inventory with temporal context from QMD knowledge searches — issues, PRs, changelogs, and migration notes that add T2-confidence annotations to extracted functions. Deep tier only; Quick and Forge tiers skip this step entirely.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🎯 ALWAYS follow the exact instructions in the step file
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a 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 compilation engine performing knowledge enrichment
+- ✅ QMD enrichment adds temporal depth — it never replaces AST extraction
+- ✅ Enrichment failure is graceful degradation, not an error
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on QMD searches to annotate extracted functions
+- 🚫 FORBIDDEN to modify extraction results — enrichment is additive only
+- 🚫 FORBIDDEN to begin compilation — that's step-05
+- 💬 QMD failures degrade gracefully — continue without enrichment
+- ⏱️ Quick and Forge tiers: skip this step entirely, auto-proceed
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow MANDATORY SEQUENCE exactly
+- 💾 Enrichment annotations are added to extraction inventory in context
+- 📖 QMD results become T2-confidence annotations
+- 🚫 Never replace T1 extraction data with QMD findings
+
+## CONTEXT BOUNDARIES:
+
+- Available: extraction_inventory from step-03, brief_data, tier from step-01
+- Focus: Adding temporal context to extracted functions
+- Limits: Do NOT modify extraction results, only annotate them
+- Dependencies: Extraction inventory must exist from step-03
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Check Tier Eligibility
+
+**If tier is Quick or Forge:**
+
+Auto-proceed silently. Display no message. Immediately load, read entire file, then execute `{nextStepFile}`.
+
+**If tier is Deep:**
+
+Continue to step 2.
+
+### 2. QMD Enrichment Searches (Deep Tier Only)
+
+For each major exported function in the extraction inventory, search QMD collections for temporal context:
+
+**Search targets per function:**
+
+1. **Issues/PRs:** `qmd_bridge.search("{function_name}")` — find related discussions, bug reports, feature requests
+2. **Changelog entries:** `qmd_bridge.search("{function_name} changelog")` — find version history, breaking changes
+3. **Migration notes:** `qmd_bridge.vector_search("{function_name} migration deprecated")` — find deprecation or migration context
+
+**For each QMD result:**
+
+- Create a T2 annotation: `[QMD:{collection}:{doc}]`
+- Classify temporal relevance:
+  - **T2-past:** Historical context (why it was built, what it replaced)
+  - **T2-future:** Forward-looking context (planned changes, deprecation warnings)
+
+**Handling QMD failures:**
+
+- If qmd_bridge is unavailable: skip all enrichment, note in context
+- If individual search fails: skip that function's enrichment, continue with others
+- If QMD returns no results for a function: no annotation added (absence is normal)
+
+### 3. Annotate Extraction Inventory
+
+Add enrichment annotations to the extraction inventory without modifying extraction data:
+
+**Per-function enrichment (if found):**
+- Related issues/PRs with summary
+- Changelog history (version changes, breaking changes)
+- Migration/deprecation context
+- T2 provenance citation for each annotation
+
+**Enrichment summary counts:**
+- Functions enriched: {count} of {total}
+- T2 annotations added: {count}
+- T2-past annotations: {count}
+- T2-future annotations: {count}
+
+### 4. Report Enrichment (Deep Tier Only)
+
+Display brief enrichment summary:
+
+"**Enrichment complete.**
+
+**Functions enriched:** {enriched_count} of {total_count}
+**T2 annotations:** {t2_count} ({t2_past} historical, {t2_future} forward-looking)
+
+Proceeding to compilation..."
+
+### 5. Menu Handling Logic
+
+**Auto-proceed step — no user interaction.**
+
+After enrichment is complete (or skipped for non-Deep tiers), immediately load, read entire file, then execute `{nextStepFile}`.
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed step with no user choices
+- Quick/Forge tiers skip directly to next step with no output
+- Deep tier displays brief enrichment summary then auto-proceeds
+- QMD failures do not halt — degrade and proceed
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN enrichment is complete (Deep tier) or the step is skipped (Quick/Forge) will you proceed to load `{nextStepFile}` for SKILL.md compilation.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Quick/Forge tiers: skipped silently with no output, auto-proceeded
+- Deep tier: QMD searches performed per extracted function
+- T2 annotations added with proper provenance citations
+- Extraction data unmodified — enrichment is additive only
+- QMD failures handled gracefully (skip and continue)
+- Auto-proceeded to step-05
+
+### ❌ SYSTEM FAILURE:
+
+- Halting on QMD unavailability or search failures
+- Modifying T1 extraction results with QMD data
+- Displaying skip messages for Quick/Forge tiers (should be silent)
+- Beginning compilation or SKILL.md assembly in this step
+- Not labeling QMD annotations as T2 confidence
+
+**Master Rule:** Enrichment is additive and optional. QMD adds temporal depth but never replaces structural extraction. Failures degrade gracefully.