bmad-module-skill-forge 0.2.0 → 0.4.0

package/src/workflows/test-skill/steps-c/step-05-score.md

@@ -3,15 +3,16 @@ name: 'step-05-score'
 description: 'Calculate completeness score from coverage and coherence findings'
 
 nextStepFile: './step-06-report.md'
-outputFile: '{output_folder}/test-report-{skill_name}.md'
+outputFile: '{forge_data_folder}/{skill_name}/test-report-{skill_name}.md'
 scoringRulesFile: '../data/scoring-rules.md'
+sourceAccessProtocol: '../data/{sourceAccessProtocol}'
 ---
 
 # Step 5: Score
 
 ## STEP GOAL:
 
-Calculate the overall completeness score by aggregating coverage and coherence category scores with the appropriate weight distribution (naive or contextual), apply the pass/fail threshold, and determine the test result.
+Calculate the overall completeness score by aggregating coverage, coherence, and external validation category scores with the appropriate weight distribution (naive or contextual), apply the pass/fail threshold, and determine the test result.
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
@@ -46,10 +47,10 @@ Calculate the overall completeness score by aggregating coverage and coherence c
 
 ## CONTEXT BOUNDARIES:
 
-- Available: Coverage Analysis (step 03) and Coherence Analysis (step 04) in {outputFile}
+- Available: Coverage Analysis (step 03), Coherence Analysis (step 04), and External Validation (step 04b) in {outputFile}
 - Focus: Score calculation and pass/fail determination only
 - Limits: Do NOT generate gap remediation — that's step 06
-- Dependencies: steps 03 and 04 must have appended their analysis sections
+- Dependencies: steps 03, 04, and 04b must have appended their analysis sections
 
 ## MANDATORY SEQUENCE
 
@@ -76,33 +77,15 @@ Read `{outputFile}` and extract the category scores calculated in previous steps
 - Combined Coherence: {percentage}% (contextual mode only)
 - Or: not scored (naive mode — weight redistributed)
 
+**From External Validation (step 04b):**
+- External Validation Score: {percentage}% (combined skill-check + tessl average)
+- Or: N/A (if neither tool was available — weight redistributed to other categories)
+
 ### 3. Apply Weight Distribution
 
 **Read testMode from {outputFile} frontmatter.**
 
-**IF naive mode — use redistributed weights:**
-
-| Category | Score | Weight | Weighted |
-|----------|-------|--------|----------|
-| Export Coverage | {N}% | 50% | {N * 0.50}% |
-| Signature Accuracy | {N}% | 30% | {N * 0.30}% |
-| Type Coverage | {N}% | 20% | {N * 0.20}% |
-| **Total** | | **100%** | **{sum}%** |
-
-**IF contextual mode — use full weights:**
-
-| Category | Score | Weight | Weighted |
-|----------|-------|--------|----------|
-| Export Coverage | {N}% | 40% | {N * 0.40}% |
-| Signature Accuracy | {N}% | 25% | {N * 0.25}% |
-| Type Coverage | {N}% | 15% | {N * 0.15}% |
-| Coherence | {N}% | 20% | {N * 0.20}% |
-| **Total** | | **100%** | **{sum}%** |
-
-**Quick tier adjustment:**
-If Signature Accuracy and Type Coverage are N/A (Quick tier, no AST):
-- Naive: Export Coverage gets 100% weight
-- Contextual: Export Coverage 60%, Coherence 40%
+Apply the weight distribution from `{scoringRulesFile}` for the detected mode (naive or contextual). The scoring rules define category weights, external validation redistribution when unavailable, and Quick tier adjustments. Calculate the weighted score for each category and sum for the total.
 
 ### 4. Determine Pass/Fail
 
@@ -139,6 +122,7 @@ Append the **Completeness Score** section to `{outputFile}`:
 | Signature Accuracy | {N}% | {W}% | {WS}% |
 | Type Coverage | {N}% | {W}% | {WS}% |
 | Coherence | {N}% | {W}% | {WS}% |
+| External Validation | {N}% | {W}% | {WS}% |
 | **Total** | | **100%** | **{total}%** |
 
 ### Result
@@ -149,6 +133,18 @@ Append the **Completeness Score** section to `{outputFile}`:
 
 **Weight Distribution:** {naive (redistributed) | contextual (full)}
 **Tier Adjustment:** {none | Quick tier — signature and type coverage not scored}
+**External Validators:** {both available | skill-check only | tessl only | none — weight redistributed}
+**Analysis Confidence:** {full | provenance-map | metadata-only | remote-only | docs-only}
+```
+
+If `analysis_confidence` is not `full`, append a degradation notice. **The notice must be confidence-aware** — see the degradation notice rules in `{sourceAccessProtocol}`:
+
+```markdown
+### Access Degradation Notice
+
+**Resolved via:** {analysis_confidence} {confidence breakdown if provenance-map, e.g., "(T1 AST-verified at compilation time)" or "(12 T1, 3 T1-low)"}
+**Impact:** {describe limitation — e.g., "Signature checks limited to name-matching. Source file:line citations from provenance-map, not live AST." — or "Provenance data is at highest confidence; no limitation." for all-T1 provenance-map}
+**Recommendation:** {confidence-dependent — see {sourceAccessProtocol} degradation notice rules. Do NOT recommend local clone when provenance-map entries are already T1.}
 ```
 
 ### 7. Update Output Frontmatter
@@ -157,6 +153,7 @@ Update `{outputFile}` frontmatter:
 - `testResult: '{pass|fail}'`
 - `score: '{total}%'`
 - `threshold: '{threshold}%'`
+- `analysisConfidence: '{analysis_confidence}'`
 - `nextWorkflow: '{export-skill|update-skill}'`
 - Append `'step-05-score'` to `stepsCompleted`
 
@@ -172,6 +169,7 @@ Update `{outputFile}` frontmatter:
 | Signature Accuracy | {N}% | {WS}% |
 | Type Coverage | {N}% | {WS}% |
 | Coherence | {N}% | {WS}% |
+| External Validation | {N}% | {WS}% |
 
 **Threshold:** {threshold}%
 **Recommendation:** {export-skill if pass | update-skill if fail}

package/src/workflows/test-skill/steps-c/step-06-report.md

@@ -2,7 +2,7 @@
 name: 'step-06-report'
 description: 'Generate gap report with remediation suggestions and finalize test report'
 
-outputFile: '{output_folder}/test-report-{skill_name}.md'
+outputFile: '{forge_data_folder}/{skill_name}/test-report-{skill_name}.md'
 scoringRulesFile: '../data/scoring-rules.md'
 outputFormatsFile: '../data/output-section-formats.md'
 ---
@@ -17,7 +17,7 @@ Generate a detailed gap report listing every issue found during coverage and coh
 
 ### Universal Rules:
 
-- 🛑 NEVER fabricate gaps — every item must trace to findings from steps 03 and 04
+- 🛑 NEVER fabricate gaps — every item must trace to findings from steps 03, 04, and 04b
 - 📖 CRITICAL: Read the complete step file before taking any action
 - ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
 - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
@@ -69,6 +69,10 @@ Read `{outputFile}` and extract every issue found across all analysis sections:
 - Incomplete integration patterns (contextual mode)
 - Structural issues (naive mode — missing sections, broken examples)
 
+**From External Validation (step 04b):**
+- skill-check diagnostics (unresolved errors and warnings)
+- tessl judge suggestions (content quality and actionability improvements)
+
 ### 2. Load Severity Rules
 
 Load `{scoringRulesFile}` for gap severity classification:
@@ -78,6 +82,7 @@ Load `{scoringRulesFile}` for gap severity classification:
 | **Critical** | Missing exported function/class documentation |
 | **High** | Signature mismatch between source and SKILL.md |
 | **Medium** | Missing type or interface documentation |
+| **Medium** | Migration section present/absent mismatch with T2-future annotation data (Deep tier) |
 | **Low** | Missing optional metadata or examples |
 | **Info** | Style suggestions, non-blocking observations |
 
@@ -96,7 +101,7 @@ If no gaps found, append a clean pass message recommending **export-skill** work
 ### 5. Finalize Output Document
 
 Update `{outputFile}` frontmatter:
-- Set `stepsCompleted` to `['step-01-init', 'step-02-detect-mode', 'step-03-coverage-check', 'step-04-coherence-check', 'step-05-score', 'step-06-report']`
+- Set `stepsCompleted` to `['step-01-init', 'step-02-detect-mode', 'step-03-coverage-check', 'step-04-coherence-check', 'step-04b-external-validators', 'step-05-score', 'step-06-report']`
 
 ### 6. Present Final Report
 
@@ -154,7 +159,7 @@ This is the final step of the test-skill workflow. When the user selects C, the
 
 ### ✅ SUCCESS:
 
-- Every gap traces to a finding from steps 03 or 04 (zero fabrication)
+- Every gap traces to a finding from steps 03, 04, or 04b (zero fabrication)
 - Gaps classified by severity using scoring rules
 - Gaps ordered by severity (Critical first)
 - Every gap has a specific, actionable remediation suggestion

package/src/workflows/test-skill/templates/test-report-template.md

@@ -1,11 +1,12 @@
 ---
 workflowType: 'test-skill'
 skillName: ''
+skillDir: ''
 testMode: ''
 forgeTier: ''
 testResult: ''
 score: ''
-threshold: ''
+analysisConfidence: ''
 testDate: ''
 stepsCompleted: []
 nextWorkflow: ''

package/src/workflows/test-skill/validation-report.md

@@ -247,7 +247,7 @@ Each step has explicit CONTEXT BOUNDARIES with FORBIDDEN markers preventing scop
 
 ### Error Handling: Good
 
-- step-01: Three-tier handling (hard stop for missing SKILL.md, warning for missing metadata.json, graceful default for missing forge-tier.yaml)
+- step-01: Three-tier handling (hard stop for missing SKILL.md, warning for missing metadata.json, graceful default for missing forge-tier.yaml). Checks `preferences.yaml` for `tier_override` after loading forge tier.
 - step-03/04: Subprocess fallback rules at multiple locations
 - step-06: Zero-gaps clean pass path
 

package/src/workflows/test-skill/workflow-plan-test-skill.md

@@ -202,6 +202,7 @@ Cognitive completeness verification — Verifies that a skill is complete enough
 | 02 | detect-mode | Middle (Simple) | Auto-proceed | Determine naive vs contextual from skill metadata |
 | 03 | coverage-check | Validation Sequence | Auto-proceed | Compare documented exports against source API surface |
 | 04 | coherence-check | Validation Sequence (conditional) | Auto-proceed | Validate references/coherence (contextual=full, naive=simplified) |
+| 04b | external-validators | Middle (Simple) | Auto-proceed | Run external validation tools (skill-check, tessl) and capture scores |
 | 05 | score | Middle (Simple) | Auto-proceed | Calculate completeness score from findings |
 | 06 | report | Final Step | C only | Generate gap report, finalize document, recommend next workflow |
 
@@ -210,7 +211,8 @@ Cognitive completeness verification — Verifies that a skill is complete enough
 ```
 User provides skill path → [01] init (auto) → [02] detect-mode (auto) →
 [03] coverage-check (auto) → [04] coherence-check (auto) →
-[05] score (auto) → [06] report → [C] finalize
+[04b] external-validators (auto) → [05] score (auto) →
+[06] report → [C] finalize
 ```
 
 ### Data Flow
@@ -219,7 +221,8 @@ User provides skill path → [01] init (auto) → [02] detect-mode (auto) →
 - Step 02: reads metadata type → sets {testMode} naive|contextual → appends Test Summary
 - Step 03: reads SKILL.md exports + source files → subprocess AST analysis → appends Coverage Analysis
 - Step 04: reads SKILL.md references → conditional depth by mode → appends Coherence Analysis
-- Step 05: reads coverage + coherence findings → calculates score → appends Completeness Score
+- Step 04b: runs skill-check and tessl against skill directory → captures external scores → appends External Validation
+- Step 05: reads coverage + coherence + external validation findings → calculates score → appends Completeness Score
 - Step 06: reads all findings → generates remediation per gap → appends Gap Report → finalizes
 
 ### Subprocess Optimization
@@ -246,6 +249,7 @@ test-skill/
 │   ├── step-02-detect-mode.md
 │   ├── step-03-coverage-check.md
 │   ├── step-04-coherence-check.md
+│   ├── step-04b-external-validators.md
 │   ├── step-05-score.md
 │   └── step-06-report.md
 └── templates/
@@ -261,7 +265,7 @@ Ferris (Audit mode): methodical, precise, evidence-based. Zero hallucination —
 - **Previous:** create-skill (required — SKILL.md must exist)
 - **Next:** export-skill (if pass) or update-skill (if fail)
 - **Input contract:** `{skills_output_folder}/{name}/SKILL.md` + `metadata.json` + `{sidecar_path}/forge-tier.yaml`
-- **Output contract:** `{output_folder}/test-report-{skill_name}.md` with frontmatter: workflowType, testResult, score, nextWorkflow
+- **Output contract:** `{forge_data_folder}/{skill_name}/test-report-{skill_name}.md` with frontmatter: workflowType, testResult, score, nextWorkflow
 
 ### Output Template (Structured)
 

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

@@ -49,7 +49,7 @@ installed_path: '{project-root}/_bmad/skf/workflows/test-skill'
 
 Load and read full config from {project-root}/_bmad/skf/config.yaml and resolve:
 
-- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
+- `project_name`, `user_name`, `communication_language`, `document_output_language`
 - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
 
 ### 2. First Step Execution

package/src/workflows/update-skill/data/remote-source-resolution.md

@@ -0,0 +1,43 @@
+# Remote Source Resolution (Forge/Deep Tier)
+
+If `source_root` is a local path: proceed with the tier-appropriate strategy as normal.
+
+If `source_root` (from metadata.json) is a remote URL (GitHub URL or owner/repo format) AND tier is Forge or Deep:
+
+1. **Check `git` availability:** Verify `git` is functional (`git --version`). If `git` is not available, skip to the fallback warning below.
+
+2. **Ephemeral sparse clone:** Clone only the changed files from the change manifest to a system temp path. Note: at this point in the flow, `{source_root}` is known to be a remote URL (the local-path case was already handled above).
+
+   ```
+   temp_path = {system_temp}/skf-ephemeral-{skill-name}-{timestamp}/
+   git clone --depth 1 --single-branch --filter=blob:none --sparse {source_root} {temp_path}
+   git -C {temp_path} sparse-checkout set --skip-checks {changed_files_from_manifest}
+   ```
+
+   **Note:** `--skip-checks` is required because `changed_files_from_manifest` contains individual file paths (e.g., `src/core/parser.py`), not directories. Without this flag, `git sparse-checkout set` rejects non-directory entries.
+
+   No `--branch` flag is used — the clone targets the remote's default branch, which must match the branch used during the original [CS] Create Skill run. This scopes the clone to only the files identified in step-02's change manifest, avoiding a full repository download.
+
+3. **If clone succeeds:** Update the working source path to `{temp_path}` for all subsequent AST operations in this step. Proceed with the **Forge tier** extraction strategy below. Mark `ephemeral_clone_active = true` for cleanup.
+
+4. **If clone fails (network error, auth failure, timeout):**
+
+   Warning message: "Ephemeral clone of `{source_root}` failed: {error}. Degrading to source reading (T1-low) for this run. For T1 (AST-verified) confidence, clone the repository locally and re-run [CS] Create Skill with the local path, then re-run this update."
+
+   Override the extraction strategy to Quick tier for this run. Note the degradation reason in context for the evidence report.
+
+## Ephemeral Clone Cleanup
+
+After extraction is complete for all files in scope (whether successful or partially failed), before presenting the extraction summary, if `ephemeral_clone_active`, delete the `{temp_path}` directory. Log: "Ephemeral source clone cleaned up." This ensures cleanup runs even if some extractions failed, as long as the step itself is still executing.
+
+## Version Reconciliation
+
+After the source path is accessible, check whether the source version has changed since the original skill was created. Look for the version file matching the detected language (e.g., `pyproject.toml`, `package.json`, `Cargo.toml`). If the source version differs from the current `metadata.json` version, record `source_version_detected` in context for step-06 to use when updating `metadata.json`. No warning needed here — step-06 handles the version update.
+
+## AST Tool Unavailability (Local Source)
+
+If AST tool is unavailable at Forge/Deep tier with local source:
+
+Warning message: "AST tools are unavailable — extraction will use source reading (T1-low). Run [SF] Setup Forge to detect and configure AST tools for T1 confidence."
+
+Degrade to Quick tier extraction. Note the degradation reason in context for the evidence report.

package/src/workflows/update-skill/data/tier-degradation-rules.md

@@ -0,0 +1,46 @@
+# Tier Degradation Rules
+
+## Remote Source at Forge/Deep Tier
+
+When `source_repo` is a remote URL (GitHub URL or owner/repo format) and the tier is Forge or Deep:
+
+- **ast-grep requires local files** — it cannot operate on remote URLs
+
+**Ephemeral clone strategy (preferred):**
+
+1. Check `git` availability (`git --version`). `git` is effectively guaranteed at Deep tier (via `gh` dependency) but NOT guaranteed at Forge tier.
+2. If `git` is available: perform an ephemeral shallow clone to a system temp path (`{system_temp}/skf-ephemeral-{skill-name}-{timestamp}/`).
+3. For create-skill: use `--depth 1 --single-branch --filter=blob:none`; if `include_patterns` are specified, apply mode selection: if `exclude_patterns` are absent, use cone mode (convert include_patterns to directory roots; use `--skip-checks` for individual file paths); if `exclude_patterns` are present, use `--no-cone` mode (pass gitignore-style patterns with `!`-prefixed excludes — includes first, then negations). See source-resolution-protocols.md for the full conversion rules.
+4. For update-skill: use sparse-checkout with `--skip-checks` scoped to the changed files from the change manifest only (file paths require `--skip-checks`). No `--branch` flag — uses the remote default branch (must match the branch used during original create-skill run).
+5. If clone succeeds: use the local clone path for AST extraction. All results are T1 with `[AST:...]` citations.
+6. Cleanup: delete the temp directory after extraction inventory is built and all data is in context. The clone never persists beyond the extraction step.
+
+**Fallback (clone fails or `git` unavailable):**
+
+- The extraction step MUST warn the user explicitly before degrading
+- **create-skill:** Warning must include actionable guidance — clone locally and update `source_repo` in the brief to the local path
+- **update-skill:** Warning must include actionable guidance — clone locally, re-run [CS] Create Skill with the local path to regenerate provenance data, then re-run the update
+- Extraction proceeds using Quick tier strategy (source reading via gh_bridge)
+- All results labeled T1-low with `[SRC:...]` citations
+- The degradation reason is recorded in the evidence report
+
+Silent degradation is **forbidden**. The user must always know when AST extraction was skipped and why.
+
+## AST Tool Unavailable at Forge/Deep Tier
+
+When the tier is Forge or Deep but ast-grep is not functional:
+
+- The extraction step MUST warn the user explicitly before degrading
+- Warning must include actionable guidance: run [SF] Setup Forge to detect tools
+- Extraction proceeds using Quick tier strategy
+- All results labeled T1-low
+- The degradation reason is recorded in the evidence report
+
+## Per-File AST Failure
+
+When ast-grep fails on an individual file (parse error, unsupported syntax):
+
+- Fall back to source reading for **that file only**
+- Other files continue with AST extraction
+- The affected file's results are labeled T1-low; unaffected files retain T1
+- Log a warning noting which file degraded and why

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

@@ -62,11 +62,15 @@ Load the existing skill and all its provenance data, detect whether this is an i
 Provide either:
 - A skill name (resolves to `{skills_output_folder}/{name}/`)
 - A full path to the skill folder
+- A skill name with `--from-test-report` to use the test report's gap findings instead of source drift detection
 
 **Skill:** {user provides path or name}"
 
 Resolve the path to an absolute skill folder location.
 
+**If `--from-test-report` was provided (or user references a test report):**
+Search for the test report at `{forge_data_folder}/{skill_name}/test-report-{skill_name}.md`. If found, set `test_report_path` in context and `update_mode: gap-driven`. If not found, warn and continue with normal source drift mode.
+
 ### 2. Validate Required Artifacts
 
 **Check SKILL.md exists:**
@@ -75,19 +79,21 @@ Resolve the path to an absolute skill folder location.
 
 **Check metadata.json exists:**
 - Load `{resolved_skill_path}/metadata.json`
-- Extract: `skill_name`, `skill_type` (individual or stack), `version`, `created`, `forge_tier`, `source_root`
+- Extract: `name`, `skill_type` (single or stack), `version`, `generation_date`, `confidence_tier`, `source_root`
 - If missing: **ABORT** — "No metadata.json found. This skill may have been created manually. Run create-skill to generate provenance data."
 
 **Detect skill type from metadata:**
 - If `skill_type == "stack"`: flag as stack skill (multi-file update mode)
-- If `skill_type == "individual"` or absent: flag as individual skill
+- If `skill_type == "single"` or absent: flag as single skill
 
 ### 3. Load Forge Tier Configuration
 
-**Load `sidecar/forge-tier.yaml`:**
-- Extract: `forge_tier` (Quick, Forge, or Deep), available tools
+**Load `{sidecar_path}/forge-tier.yaml`:**
+- Extract: `tier` (Quick, Forge, or Deep), available tools
 - If missing: **ABORT** — "No forge-tier.yaml found. Run setup-forge first to detect available tools."
 
+**Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, or Deep), use it instead of the detected tier.
+
 **Determine analysis capabilities:**
 - **Quick:** text pattern matching only → T1-low confidence
 - **Forge:** AST structural extraction → T1 confidence
@@ -146,7 +152,7 @@ Please provide the current source code path:
 | Property | Value |
 |----------|-------|
 | **Skill** | {skill_name} |
-| **Type** | {individual/stack} |
+| **Type** | {single/stack} |
 | **Version** | {version} |
 | **Created** | {created date} |
 | **Source** | {source_root} |
@@ -154,7 +160,7 @@ Please provide the current source code path:
 | **Provenance Age** | {days} days since last extraction |
 | **Exports** | {export_count} tracked exports |
 | **[MANUAL] Sections** | {manual_count} preserved sections |
-| **Mode** | {normal/degraded} |
+| **Mode** | {normal/degraded/gap-driven} |
 
 **Analysis plan:** {tier_description}
 - {Quick: text pattern diff → T1-low findings}
@@ -188,7 +194,7 @@ ONLY WHEN [C] is selected and baseline has been established with all required ar
 ### ✅ SUCCESS:
 
 - SKILL.md loaded and validated
-- metadata.json loaded with skill_name, skill_type, version, source_root
+- metadata.json loaded with name, skill_type, version, source_root
 - Forge tier loaded from sidecar/forge-tier.yaml
 - Provenance map loaded (or degraded mode confirmed)
 - [MANUAL] sections inventoried across all output files

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

@@ -56,6 +56,32 @@ Compare current source code state against the provenance map to produce a comple
 
 **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:

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

@@ -3,6 +3,9 @@ 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'
+tierDegradationRulesData: '../data/tier-degradation-rules.md'
+remoteSourceResolutionData: '../data/remote-source-resolution.md'
 ---
 
 # Step 3: Re-Extract Changed Exports
@@ -55,7 +58,26 @@ Perform tier-aware extraction on only the changed files identified in step 02, p
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
 
-### 1. Determine Extraction Strategy by Tier
+### 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 check (before ephemeral clone):** If MCP source-reading tools are available (zread, deepwiki, gh API, or similar) and `source_repo` is set in metadata.json, use MCP tools to fetch only the changed files from the change manifest. This avoids ephemeral clone overhead entirely. MCP provides full source file content equivalent to a local read. If the fetched content is written to a temp file and analyzed with ast-grep, label confidence as T1. If AST is unavailable (the common case for MCP-fetched content), use pattern-based extraction and label confidence as T1-low.
+
+**If MCP unavailable:** Load and follow `{remoteSourceResolutionData}` for ephemeral clone setup, version reconciliation, and AST tool unavailability handling.
 
 **Quick tier (text pattern matching):**
 - Extract function/class/type names via regex patterns
@@ -63,7 +85,9 @@ Perform tier-aware extraction on only the changed files identified in step 02, p
 - Confidence: T1-low (pattern-matched, not AST-verified)
 
 **Forge tier (AST structural extraction):**
-- Use ast_bridge for full 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)
@@ -93,15 +117,26 @@ DO NOT BE LAZY — For EACH file in the change manifest with status MODIFIED, AD
 
 **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 `{extractionPatternsData}` to trace unresolved symbols to their actual definition files.
+
 ### 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 QMD collection for semantic context related to the 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
@@ -149,14 +184,8 @@ Extraction Results:
 
 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
 

package/src/workflows/update-skill/steps-c/step-04-merge.md

@@ -35,7 +35,7 @@ Merge freshly extracted export data into the existing SKILL.md content while pre
 
 - 🎯 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
+- 🚫 FORBIDDEN to write files — merge produces an edit plan for step 06 to execute
 - 💬 If [MANUAL] conflicts detected: HALT and present to user for resolution
 - 💬 If clean merge: auto-proceed without user interaction
 
@@ -50,7 +50,7 @@ Merge freshly extracted export data into the existing SKILL.md content while pre
 
 - 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
+- Limits: merge planning only — no file writes (step 06 executes the edit plan)
 - Dependencies: step 03 must have produced extraction results
 
 ## MANDATORY SEQUENCE
@@ -222,7 +222,7 @@ ONLY WHEN all merge operations are complete and any [MANUAL] conflicts have been
 
 - 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)
+- Writing files during merge planning (edits are executed in step 06)
 - Applying merge out of priority order
 - Not detecting orphaned [MANUAL] blocks on deleted exports
 - Not handling stack skill multi-file merge