bmad-module-skill-forge 0.2.0 → 0.3.0

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/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,8 @@ 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'
+remoteSourceResolutionData: '../data/remote-source-resolution.md'
 ---
 
 # Step 3: Re-Extract Changed Exports
@@ -55,7 +57,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 +84,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 +116,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 +183,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

package/src/workflows/update-skill/steps-c/step-05-validate.md

@@ -54,64 +54,76 @@ Validate the merged skill content against the agentskills.io specification, veri
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
 
-### 1. Launch Parallel Validation Checks
+### 1. Check Tool Availability and Validation Timing
+
+Run: `npx skill-check -h`
+
+- If succeeds: skill-check is available for Checks A, E, F below
+- If fails: Use manual fallback paths in those checks
+
+**Important:** Do not assume availability — empirical check required.
+
+**Validation timing note:** Step-04 produces an edit plan, not written files. Checks that require files on disk (skill-check Checks A, E, F) will be **deferred to post-write** — step-06 runs them after writing files. Structural checks (B, C, D) validate the planned merge content and run here.
+
+### 2. Launch Parallel Validation Checks
 
 Launch subprocesses in parallel for each validation category, aggregating results when complete:
 
-**Check A — Spec Compliance:**
-- Validate merged SKILL.md structure against agentskills.io specification (via skills_ref if available)
-- Verify required sections present: exports, usage patterns, conventions
-- Verify export entries have: name, type, signature, file:line reference
-- Flag missing or incomplete sections
+**Check A — Spec Compliance (via skill-check):**
+
+**If available**, run: `npx skill-check check <skill-dir> --fix --format json --no-security-scan`
+
+Parse JSON output for quality score (0-100), auto-fixed issues, and remaining diagnostics. If `body.max_lines` reported, run: `npx skill-check split-body <skill-dir> --write`
+
+**If unavailable**, perform manual check: validate merged SKILL.md structure, verify required sections (exports, usage patterns, conventions), verify export entries have name/type/signature/file:line reference, flag missing sections.
 
 **Check B — [MANUAL] Section Integrity:**
 - Compare [MANUAL] inventory from step 01 against merged content
-- Verify every [MANUAL] block from inventory exists in merged result
-- Verify [MANUAL] content is byte-identical (zero modification)
-- Flag any [MANUAL] blocks that were moved, truncated, or missing
+- Verify every [MANUAL] block exists in merged result, byte-identical (zero modification)
+- Flag any [MANUAL] blocks moved, truncated, or missing
 
 **Check C — Confidence Tier Consistency:**
 - Verify all re-extracted exports have confidence labels (T1/T1-low/T2)
-- Verify tier labels match forge tier capabilities:
-  - Quick tier: only T1-low allowed
-  - Forge tier: T1 expected (T1-low for degraded operations)
-  - Deep tier: T1 + T2 expected
+- Verify tier labels match forge tier: Quick=T1-low only, Forge=T1 (T1-low for degraded), Deep=T1+T2
 - Flag mismatched or missing tier labels
 
 **Check D — Provenance Completeness:**
-- Verify every export in merged SKILL.md has a provenance map entry
-- Verify file:line references point to actual source locations
+- Verify every export has a provenance map entry with valid file:line references
 - Verify no stale references to old file paths or line numbers
 - Flag orphaned provenance entries (export removed but provenance remains)
 
-### 2. Aggregate Validation Results
+**Check E — Diff Comparison (via skill-check):**
+
+**If available** and previous skill version exists: `npx skill-check diff <original-skill-dir> <updated-skill-dir>`
+
+Shows diagnostic changes between original and updated skill. Record diff results as informational context.
+
+**If unavailable or no previous version:** Skip with note.
+
+**Check F — Security Scan:**
+
+**If available**, run: `npx skill-check check <skill-dir> --format json` (security scan enabled by default).
+
+Record security findings as advisory warnings — they do not block the update.
+
+**If unavailable:** Skip with note: "Security scan skipped — skill-check tool unavailable"
+
+### 3. Aggregate Validation Results
 
 Compile results from all checks:
 
 ```
 Validation Results:
-  spec_compliance:
-    status: PASS|WARN|FAIL
-    findings: [{severity, description, location}]
-
-  manual_integrity:
-    status: PASS|WARN|FAIL
-    sections_verified: [count]
-    sections_intact: [count]
-    findings: [{severity, description, section_name}]
-
-  confidence_consistency:
-    status: PASS|WARN|FAIL
-    exports_checked: [count]
-    findings: [{severity, description, export_name, expected_tier, actual_tier}]
-
-  provenance_completeness:
-    status: PASS|WARN|FAIL
-    entries_checked: [count]
-    findings: [{severity, description, export_name}]
+  spec_compliance: {status: PASS|WARN|FAIL, findings: [{severity, description, location}]}
+  manual_integrity: {status, sections_verified, sections_intact, findings}
+  confidence_consistency: {status, exports_checked, findings}
+  provenance_completeness: {status, entries_checked, findings}
+  diff_comparison: {status: PASS|SKIP, new_issues, fixed_issues, unchanged}
+  security_scan: {status: PASS|WARN|SKIP, findings}
+  quality_score: [0-100]  # from skill-check, if available
 ```
 
-### 3. For Stack Skills — Validate Reference Files
+### 4. For Stack Skills — Validate Reference Files
 
 **ONLY if skill_type == "stack":**
 
@@ -121,43 +133,28 @@ Repeat checks A-D for each reference file:
 
 **If skill_type != "stack":** Skip with notice.
 
-### 4. Display Validation Summary
+### 5. Display Validation Summary
 
 "**Validation Results:**
 
 | Check | Status | Findings |
 |-------|--------|----------|
-| Spec Compliance | {PASS/WARN/FAIL} | {count} findings |
+| Spec Compliance | {PASS/WARN/FAIL} | {count} findings (quality score: {score}/100) |
 | [MANUAL] Integrity | {PASS/WARN/FAIL} | {count} findings |
 | Confidence Tiers | {PASS/WARN/FAIL} | {count} findings |
 | Provenance | {PASS/WARN/FAIL} | {count} findings |
+| Diff Comparison | {PASS/SKIP} | {new} new, {fixed} fixed |
+| Security Scan | {PASS/WARN/SKIP} | {count} findings |
 
 **Overall: {ALL_PASS / WARNINGS_FOUND / FAILURES_FOUND}**"
 
-**If WARNINGS or FAILURES found:**
-
-List each finding with severity and description:
+**If findings exist:** List each with severity, description, and location. Add: "Validation is advisory. Findings do not block the update."
 
-"**Findings:**
-1. [{severity}] {description} — {location}
-2. [{severity}] {description} — {location}
-..."
-
-"**Note:** Validation is advisory. These findings are reported for your awareness but do not block the update. You may choose to address them after the update completes."
-
-### 5. Present MENU OPTIONS
+### 6. Present MENU OPTIONS
 
 Display: "**Proceeding to write updated files...**"
 
-#### Menu Handling Logic:
-
-- After validation summary is displayed, immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed validation step with no user choices
-- Validation is advisory — findings are informational, not blocking
-- Proceed directly to next step after summary display
+After validation summary is displayed, immediately load, read entire file, then execute {nextStepFile}. This is an auto-proceed step — validation is advisory, not blocking.
 
 ## CRITICAL STEP COMPLETION NOTE
 
@@ -169,19 +166,18 @@ ONLY WHEN all validation checks have completed and findings are displayed will y
 
 ### ✅ SUCCESS:
 
-- All four validation checks executed (spec, [MANUAL], confidence, provenance)
+- All six checks executed (spec, [MANUAL], confidence, provenance, diff, security)
+- `npx skill-check check --fix` and `diff` executed if available (or fallbacks used)
+- Quality score captured; auto-fix applied for deterministic issues
 - Stack skill reference files validated if applicable
-- Findings reported with severity and specific locations
-- [MANUAL] integrity verified with byte-level comparison
-- Validation results displayed clearly
+- Findings reported with severity and specific locations; [MANUAL] integrity verified
 - Auto-proceeds regardless of findings (advisory mode)
 
 ### ❌ SYSTEM FAILURE:
 
-- Skipping any of the four validation checks
-- Blocking the workflow on validation warnings
-- Not verifying [MANUAL] section integrity
-- Hallucinating validation findings not backed by actual comparison
-- Modifying merged content during validation
+- Skipping any of the six checks; blocking on validation warnings
+- Not verifying [MANUAL] integrity; hallucinating findings not backed by comparison
+- Modifying merged content during validation (except via skill-check --fix)
+- Not recording quality score when skill-check is available
 
 **Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.