bmad-module-skill-forge 0.8.4 → 0.10.0

package/src/workflows/shared/health-check.md

@@ -0,0 +1,231 @@
+---
+name: 'health-check'
+description: 'Workflow self-improvement health check — captures real friction as GitHub issues'
+# No nextStepFile — this is always the terminal step
+healthCheckRepo: '{health_check_repo}'
+localFallbackFolder: '{output_folder}/improvement-queue'
+---
+
+# Health Check: Workflow Self-Improvement
+
+## STEP GOAL:
+
+Reflect on the workflow that just completed. If real friction, bugs, or gaps were encountered in the SKF workflow instructions, capture them as structured findings for the user to review and optionally submit as GitHub issues.
+
+**Zero overhead for clean runs.** If nothing went wrong, say so and exit immediately.
+
+## MANDATORY EXECUTION RULES:
+
+### Universal Rules:
+- Read the complete step file before taking any action
+- Speak in `{communication_language}`
+
+### Role Reinforcement:
+- You are a **self-improvement auditor** — honest, precise, evidence-based
+- You report ONLY what you actually experienced during THIS session
+- You are NOT a creative writer looking for things to say
+
+### Anti-Hallucination Rules:
+- **DO NOT FABRICATE ISSUES.** If the workflow ran smoothly, say so and exit. Inventing issues to appear thorough is a SYSTEM FAILURE.
+- Only report issues you **ACTUALLY encountered** during THIS workflow execution
+- Every finding MUST cite the **specific step file path and section** where the issue occurred
+- If you are unsure whether something was a real issue or your own confusion, DO NOT report it
+- Reporting zero issues is the EXPECTED outcome for a well-designed workflow
+
+---
+
+## MANDATORY SEQUENCE
+
+### 1. Read Workflow Context
+
+From the current session context, identify:
+- **Workflow name** — which workflow just completed
+- **Steps executed** — which step files were loaded and followed
+- **Any friction points** — moments where instructions were unclear, wrong, contradictory, or missing
+
+### 2. Reflect on Execution
+
+Silently review the workflow execution. Ask yourself:
+
+- Did any step instruction lead me astray or cause unnecessary back-and-forth with the user?
+- Was any step ambiguous, causing me to guess rather than follow clear guidance?
+- Did I encounter a scenario the workflow didn't account for?
+- Were any step instructions wrong or contradictory?
+
+**If the answer to ALL of these is "no":**
+
+Display:
+
+"**Health Check: Clean run.** No workflow issues to report.
+
+Workflow complete."
+
+**STOP HERE. Do not proceed further. The workflow is done.**
+
+### 3. Present Findings (Only If Issues Exist)
+
+For each genuine finding, present it in this format:
+
+"**Workflow Health Check — {N} finding(s)**
+
+---
+
+**Finding {i}:**
+
+| Field | Value |
+|-------|-------|
+| **Severity** | `bug` / `friction` / `gap` |
+| **Workflow** | {workflow name} |
+| **Step File** | `src/workflows/{workflow}/{step-file-path}` |
+| **Section** | {the specific section or instruction number} |
+
+**What happened:**
+{Description of the actual issue encountered during execution}
+
+**Evidence:**
+{What specifically went wrong — error, confusion, user friction, missing guidance}
+
+**Suggested improvement:**
+{Concrete, actionable change to the step file or data}
+
+---"
+
+**Severity definitions:**
+- **`bug`** — Step instructions were wrong or contradictory
+- **`friction`** — Step worked but was unclear, ambiguous, or caused unnecessary back-and-forth
+- **`gap`** — A scenario arose that the workflow didn't account for at all
+
+### 4. User Review Gate
+
+After presenting all findings, ask:
+
+"**Submit these findings?**
+
+- **[Y]** Yes — submit all findings
+- **[N]** No — discard all findings
+- **[E]** Edit — let me revise before submitting
+
+_You are the final filter. Reject any finding that doesn't reflect a real issue you observed._"
+
+**HALT and wait for user input.**
+
+#### Menu Handling:
+
+- **IF Y:** Proceed to step 5
+- **IF N:** Display "Findings discarded. Workflow complete." — STOP
+- **IF E:** Let user specify which findings to keep, modify, or remove. Then re-present the revised list and ask again.
+
+### 5. Submit Findings
+
+**Check GitHub CLI availability:**
+
+Run `gh auth status` to determine if the `gh` CLI is authenticated.
+
+#### IF `gh` is available:
+
+For each confirmed finding, create a GitHub issue:
+
+**Command:**
+```
+gh issue create \
+  --repo {healthCheckRepo} \
+  --title "[health-check] [{severity}] {workflow}: {short description}" \
+  --label "health-check,workflow-improvement,{severity}" \
+  --body "{formatted body using issue template structure}"
+```
+
+**Issue body format:**
+```markdown
+## Workflow
+{workflow name}
+
+## Step File
+`{exact step file path relative to src/}`
+
+## Severity
+{bug | friction | gap}
+
+## Finding
+{description of what went wrong}
+
+## Evidence
+{what actually happened during execution}
+
+## Suggested Improvement
+{concrete change to improve the workflow}
+
+## Environment
+- **Date:** {date}
+- **OS:** {detected OS, e.g. macOS 15.2, Ubuntu 24.04, Windows 11}
+- **AI Editor:** {the AI editor or CLI being used, e.g. Claude Code, Cursor, Windsurf}
+- **Model:** {the model executing this workflow, e.g. Claude Opus 4.6, Claude Sonnet 4.6}
+- **Forge Tier:** {if available from sidecar, otherwise "N/A"}
+- **SKF Version:** {read from {project-root}/_bmad/skf/VERSION, otherwise "N/A"}
+```
+
+After creating all issues, display:
+
+"**{N} issue(s) created on {healthCheckRepo}:**
+{list each issue URL}
+
+Workflow complete."
+
+#### IF `gh` is NOT available:
+
+For each confirmed finding, write a local file to `{localFallbackFolder}/`:
+
+**Filename:** `hc-{workflow}-{timestamp}.md` (one file per finding, timestamp as YYYYMMDD-HHmmss)
+
+**File content:** Same structured format as the issue body above, with YAML frontmatter:
+
+```yaml
+---
+type: workflow-health-finding
+workflow: {workflow name}
+step_file: {step file path}
+severity: {bug | friction | gap}
+date: {ISO date}
+---
+```
+
+After writing all files, display:
+
+"**{N} finding(s) saved locally:**
+{list each file path}
+
+GitHub CLI is not available. To submit these as issues, run:
+`gh issue create --repo {healthCheckRepo} --title \"[title]\" --body-file {file-path}`
+
+Or open them manually at: <https://github.com/{healthCheckRepo}/issues/new/choose>
+
+Workflow complete."
+
+---
+
+## CRITICAL STEP COMPLETION NOTE
+
+This is the TERMINAL step — shared across all SKF workflows. After the health check completes (clean run or findings submitted/discarded), the workflow is fully done. No further steps to load.
+
+---
+
+## SYSTEM SUCCESS/FAILURE METRICS
+
+### SUCCESS:
+
+- Clean runs exit immediately with no findings (most common outcome)
+- Findings cite specific step files and sections with real evidence
+- User review gate presented before any submission
+- GitHub issues created with correct labels and structured body (when `gh` available)
+- Local fallback files written with clear manual submission instructions (when `gh` unavailable)
+- Workflow ends cleanly
+
+### SYSTEM FAILURE:
+
+- Fabricating issues that were not actually encountered during the session
+- Reporting vague issues without step file citations ("the workflow was confusing")
+- Skipping the user review gate
+- Creating issues without user confirmation
+- Not providing the local fallback when `gh` is unavailable
+- Continuing to load steps after this one (this is terminal)
+
+**Master Rule:** Honesty is the only policy. Zero findings is the expected, healthy outcome. Fabricating issues to appear thorough undermines the entire self-improvement system and constitutes SYSTEM FAILURE.

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

@@ -3,7 +3,7 @@ name: 'step-01-init'
 description: 'Discover skill, load forge tier state, validate inputs, create test report'
 
 nextStepFile: './step-02-detect-mode.md'
-outputFile: '{forge_data_folder}/{skill_name}/test-report-{skill_name}.md'
+outputFile: '{forge_version}/test-report-{skill_name}.md'
 templateFile: '../templates/test-report-template.md'
 sidecarFile: '{sidecar_path}/forge-tier.yaml'
 skillsOutputFolder: '{skills_output_folder}'
@@ -69,16 +69,24 @@ Provide the skill path or name. I'll search in `{skillsOutputFolder}`.
 
 **Path or name:**"
 
-### 2. Validate Skill Exists
+### 2. Validate Skill Exists (version-aware)
 
-Check that the skill directory contains required files:
+Resolve the skill path using version-aware resolution (see [knowledge/version-paths.md](../../../knowledge/version-paths.md)):
+
+1. Read `{skillsOutputFolder}/.export-manifest.json` and look up the skill name in `exports` to get `active_version`
+2. If found: resolve to `{skill_package}` = `{skillsOutputFolder}/{skill_name}/{active_version}/{skill_name}/`
+3. If not in manifest: check for `active` symlink at `{skillsOutputFolder}/{skill_name}/active` — resolve to `{skill_group}/active/{skill_name}/`
+4. If neither: fall back to flat path `{skillsOutputFolder}/{skill_name}/`. If SKILL.md exists at the flat path, auto-migrate per `knowledge/version-paths.md` migration rules
+5. Store the resolved path as `{resolved_skill_package}`
+
+Check that the skill package contains required files:
 
 **Required files:**
-- `{skillsOutputFolder}/{skill_name}/SKILL.md` — the skill documentation
-- `{skillsOutputFolder}/{skill_name}/metadata.json` — skill metadata
+- `{resolved_skill_package}/SKILL.md` — the skill documentation
+- `{resolved_skill_package}/metadata.json` — skill metadata
 
 **If SKILL.md missing:**
-"**Error: SKILL.md not found at `{skillsOutputFolder}/{skill_name}/SKILL.md`**
+"**Error: SKILL.md not found at `{resolved_skill_package}/SKILL.md`**
 
 This skill has not been created yet. Run the **create-skill** workflow first."
 

package/src/workflows/test-skill/steps-c/step-02-detect-mode.md

@@ -3,7 +3,7 @@ name: 'step-02-detect-mode'
 description: 'Determine naive (individual) vs contextual (stack) testing mode'
 
 nextStepFile: './step-03-coverage-check.md'
-outputFile: '{forge_data_folder}/{skill_name}/test-report-{skill_name}.md'
+outputFile: '{forge_version}/test-report-{skill_name}.md'
 ---
 
 # Step 2: Detect Mode

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

@@ -1,4 +1,5 @@
 ---
+nextStepFile: '../../shared/health-check.md'
 name: 'step-06-report'
 description: 'Generate gap report with remediation suggestions and finalize test report'
 
@@ -166,18 +167,18 @@ Display: "**Test complete.** [C] Finish"
 
 #### Menu Handling Logic:
 
-- IF C: Workflow is complete. No further steps to load.
+- IF C: Load and execute `{nextStepFile}` for workflow self-improvement check.
 - IF Any other: help user respond, then redisplay menu
 
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
-- This is the final step — C ends the workflow
+- C triggers the health check, which is the true workflow exit
 - User may ask questions about the report before finishing
 
 ## CRITICAL STEP COMPLETION NOTE
 
-This is the final step of the test-skill workflow. When the user selects C, the workflow is complete. The test report document at `{outputFile}` contains the full analysis: Test Summary, Coverage Analysis, Coherence Analysis, Completeness Score, and Gap Report.
+When the user selects C, this step chains to the shared health check. After the health check completes, the test-skill workflow is fully done. The test report document at `{outputFile}` contains the full analysis: Test Summary, Coverage Analysis, Coherence Analysis, Completeness Score, and Gap Report.
 
 ---
 

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

@@ -6,21 +6,35 @@ If `source_root` (from metadata.json) is a remote URL (GitHub URL or owner/repo
 
 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).
+2. **Resolve source ref:** Read `source_ref` from the existing `metadata.json`. If the user provided a new `target_version`, resolve its tag first (using the Tag Resolution algorithm in `create-skill/data/source-resolution-protocols.md`).
+
+3. **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}/
+   ```
+
+   If `source_ref` exists and is not `HEAD`/null/`"local"`:
+   ```
+   git clone --depth 1 --branch {source_ref} --single-branch --filter=blob:none --sparse {source_root} {temp_path}
+   ```
+
+   If `source_ref` is `HEAD`/null/`"local"` (or absent):
+   ```
    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.
+   When `source_ref` is a tag (e.g., `v0.5.0`), the clone targets that specific tag to ensure update-skill extracts from the same source version as the original create-skill run. When `source_ref` is `HEAD`, null, or `"local"`, no `--branch` flag is used — the clone targets the remote's default branch. 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 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):**
+5. **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."
 

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

@@ -60,25 +60,32 @@ Load the existing skill and all its provenance data, detect whether this is an i
 "**Which skill would you like to update?**
 
 Provide either:
-- A skill name (resolves to `{skills_output_folder}/{name}/`)
+- A skill name (resolves via version-aware path resolution — see [knowledge/version-paths.md](../../../knowledge/version-paths.md))
 - 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}"
 
+**Version-Aware Path Resolution:**
+1. Read `{skills_output_folder}/.export-manifest.json` and look up the skill name in `exports` to get `active_version`
+2. If found: resolve to `{skill_package}` = `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/`
+3. If not in manifest: check for `active` symlink at `{skills_output_folder}/{skill-name}/active` — resolve to `{skill_group}/active/{skill-name}/`
+4. If neither: fall back to flat path `{skills_output_folder}/{skill-name}/`. If SKILL.md exists at the flat path, auto-migrate per `knowledge/version-paths.md` migration rules
+5. Store the resolved path as `{resolved_skill_package}` for all subsequent artifact loading
+
 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.
+Search for the test report at `{forge_data_folder}/{skill_name}/{active_version}/test-report-{skill_name}.md` (i.e., `{forge_version}/test-report-{skill_name}.md`). If not found at the versioned path, fall back to `{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 at either path, warn and continue with normal source drift mode.
 
 ### 2. Validate Required Artifacts
 
 **Check SKILL.md exists:**
-- Load `{resolved_skill_path}/SKILL.md`
-- If missing: **ABORT** — "No SKILL.md found at `{resolved_skill_path}`. Run create-skill first."
+- Load `{resolved_skill_package}/SKILL.md`
+- If missing: **ABORT** — "No SKILL.md found at `{resolved_skill_package}`. Run create-skill first."
 
 **Check metadata.json exists:**
-- Load `{resolved_skill_path}/metadata.json`
+- Load `{resolved_skill_package}/metadata.json`
 - 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."
 
@@ -102,13 +109,13 @@ Search for the test report at `{forge_data_folder}/{skill_name}/test-report-{ski
 
 ### 4. Load Provenance Map
 
-**Load `{forge_data_folder}/{skill_name}/provenance-map.json`:**
+**Load `{forge_data_folder}/{skill_name}/{active_version}/provenance-map.json`** (i.e., `{forge_version}/provenance-map.json`). If not found at the versioned path, fall back to `{forge_data_folder}/{skill_name}/provenance-map.json`:
 - Extract: export list, file mappings, extraction timestamps, confidence tiers
 - Calculate provenance age (days since last extraction)
 
-**If provenance map missing:**
+**If provenance map missing at both paths:**
 
-"**WARNING:** No provenance map found at `{forge_data_folder}/{skill_name}/provenance-map.json`.
+"**WARNING:** No provenance map found at `{forge_version}/provenance-map.json` or flat fallback.
 
 Without a provenance map, update-skill cannot perform targeted change detection. Options:
 

package/src/workflows/update-skill/steps-c/step-06-write.md

@@ -49,6 +49,7 @@ Write all updated skill artifacts to disk: the merged SKILL.md, updated provenan
 - Focus: file I/O operations — write and verify
 - Limits: write only to skill output and forge data directories
 - Dependencies: steps 02-05 must all be complete
+- Path resolution: See `knowledge/version-paths.md` for canonical path templates (`{skill_package}`, `{skill_group}`, `{forge_version}`, `{forge_group}`)
 
 ## MANDATORY SEQUENCE
 
@@ -56,14 +57,16 @@ Write all updated skill artifacts to disk: the merged SKILL.md, updated provenan
 
 ### 1. Write Updated SKILL.md
 
-Write the merged SKILL.md content to `{skills_output_folder}/{skill_name}/SKILL.md`:
+Write the merged SKILL.md content to `{skill_package}/SKILL.md`:
 - Overwrite the existing file with merged content
 - Preserve file encoding (UTF-8)
 - Verify write by reading back and confirming [MANUAL] section count matches expected
 
+If the version changed (source version differs from the previous metadata version), write to the new `{skill_package}` (creating the version directory if needed). The previous version's directory is preserved on disk.
+
 ### 2. Write Updated metadata.json
 
-Update `{skills_output_folder}/{skill_name}/metadata.json`:
+Update `{skill_package}/metadata.json`:
 - Update `version`: if a source version was detected during re-extraction and differs from the current metadata version, use the source version; otherwise increment patch version
 - Update `generation_date` timestamp to current ISO-8601 date
 - Update `exports` array to reflect current export list
@@ -81,7 +84,7 @@ Update `{skills_output_folder}/{skill_name}/metadata.json`:
 
 ### 3. Write Updated provenance-map.json
 
-Write to `{forge_data_folder}/{skill_name}/provenance-map.json`:
+Write to `{forge_version}/provenance-map.json`:
 
 **For each export in the updated skill:**
 - Update `export_name` if renamed
@@ -117,7 +120,7 @@ Write to `{forge_data_folder}/{skill_name}/provenance-map.json`:
 
 ### 4. Write Updated evidence-report.md
 
-Append update operation section to `{forge_data_folder}/{skill_name}/evidence-report.md` (create the file with a standard header if it does not yet exist):
+Append update operation section to `{forge_version}/evidence-report.md` (create the file with a standard header if it does not yet exist):
 
 ```markdown
 ## Update Operation — {current_date}
@@ -146,17 +149,43 @@ Append update operation section to `{forge_data_folder}/{skill_name}/evidence-re
 - Provenance: {PASS/WARN/FAIL}
 ```
 
-### 5. Write Stack Skill Reference Files (Conditional)
+### 5. Write Stack Skill Reference Files (Conditional) and Regenerate context-snippet.md
 
 **ONLY if skill_type == "stack":**
 
 For each affected reference file from the merge:
 - Write updated `references/{library}.md` files
 - Write updated `references/integrations/{pair}.md` files
-- Regenerate `context-snippet.md` with updated export summaries
 - Verify [MANUAL] sections preserved in each reference file
 
-**If skill_type != "stack":** Skip reference file updates. However, if exports changed (added, removed, or renamed), warn: "⚠️ `context-snippet.md` was NOT updated — exports have changed. Run **[EX] Export Skill** to regenerate the context snippet and update CLAUDE.md/AGENTS.md."
+**For all skills (both single and stack) — regenerate `context-snippet.md`:**
+
+Per `knowledge/version-paths.md` "Writing Workflows (CS, QS, SS, US)", update-skill is a writing workflow that MUST write all deliverables to `{skill_package}`. `context-snippet.md` is one of those deliverables and goes stale whenever exports, version, or gotchas change.
+
+Regenerate the snippet using the format from the matching template file:
+
+- For single skills: `create-skill/data/skill-sections.md` (pipe-delimited indexed format)
+- For stack skills: `create-stack-skill/data/stack-skill-template.md`
+
+Use the **flat legacy form** for the `root:` path in the draft snippet: `root: skills/{skill-name}/`. The platform-specific prefix (`.claude/skills/`, `.cursor/skills/`, `.agents/skills/`) is applied later by `export-skill` step-03 when the skill is exported. Do not choose a platform prefix in update-skill — that is an export-time decision that depends on config.yaml.
+
+Pull values for the regenerated snippet from the updated metadata.json (version, top exports), the merged SKILL.md (section anchors, inline summaries), and the evidence report (new gotchas). If gotchas cannot be derived from the updated evidence but the prior snippet has a `|gotchas:` line, carry forward the prior line with the `[CARRIED]` marker — see `export-skill/steps-c/step-03-generate-snippet.md` for the carry-forward protocol (one-cycle limit).
+
+Write the regenerated snippet to `{skill_package}/context-snippet.md`, preserving file permissions.
+
+**If skill_type == "stack"**, also verify that the reference file updates from the first half of this section have been applied before writing the snippet so the stack snippet reflects the newest integration list.
+
+### 5b. Update Active Symlink (If Version Changed)
+
+If the version was incremented or changed in section 2 (metadata.json update):
+- Create or update the `active` symlink at `{skill_group}/active` pointing to the new `{version}`
+- If the symlink already exists, remove it first and recreate
+
+```
+{skill_group}/active -> {version}
+```
+
+If the version did not change, the existing symlink already points to the correct version -- no action needed.
 
 ### 6. Verify All Writes
 
@@ -183,11 +212,11 @@ For each file written:
 External tool checks deferred from step-05 now run against the written files:
 
 **If skill-check available:**
-- Run: `npx skill-check check {skills_output_folder}/{skill_name} --fix --format json --no-security-scan`
+- Run: `npx skill-check check {skill_package} --fix --format json --no-security-scan`
 - **Context sync after --fix:** If `fixed[]` is non-empty (i.e., `--fix` modified files on disk), re-read the modified SKILL.md to update the in-context copy. This prevents silent divergence between the in-context SKILL.md and the on-disk version that step-07-report will reference.
-- If `body.max_lines` reported, prefer selective split — extract only the largest Tier 2 section(s) to `references/`, keeping Tier 1 inline (inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval). Fall back to `npx skill-check split-body {skills_output_folder}/{skill_name} --write` if not feasible. Verify anchors resolve after split.
+- If `body.max_lines` reported, prefer selective split — extract only the largest Tier 2 section(s) to `references/`, keeping Tier 1 inline (inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval). Fall back to `npx skill-check split-body {skill_package} --write` if not feasible. Verify anchors resolve after split.
 - Run: `npx skill-check diff` if original version was preserved
-- Run: `npx skill-check check {skills_output_folder}/{skill_name} --format json` for security scan
+- Run: `npx skill-check check {skill_package} --format json` for security scan
 
 Record findings in the evidence report (section 4). These are advisory — do not block on warnings.
 
@@ -216,11 +245,12 @@ ONLY WHEN all files have been written and verified will you load {nextStepFile}
 
 ### ✅ SUCCESS:
 
-- SKILL.md written with all merged content and [MANUAL] sections intact
+- SKILL.md written to {skill_package} with all merged content and [MANUAL] sections intact
 - metadata.json updated with new version, timestamp, export counts
-- provenance-map.json updated with current file:line references and timestamps
-- evidence-report.md appended with update operation record
+- provenance-map.json updated at {forge_version} with current file:line references and timestamps
+- evidence-report.md appended at {forge_version} with update operation record
 - Stack reference files updated if applicable
+- Active symlink updated at {skill_group}/active -> {version} if version changed
 - All writes verified by read-back confirmation
 
 ### ❌ SYSTEM FAILURE:

package/src/workflows/update-skill/steps-c/step-07-report.md

@@ -1,6 +1,7 @@
 ---
 name: 'step-07-report'
 description: 'Display comprehensive change summary with diff visualization and workflow chaining recommendations'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 7: Report
@@ -36,7 +37,7 @@ Present a comprehensive change summary showing what was updated, [MANUAL] sectio
 
 - 🎯 Follow MANDATORY SEQUENCE exactly
 - 💾 No file writes — display only
-- 📖 This is the final step — workflow completes here
+- 📖 Chains to shared health check via `{nextStepFile}` — no further steps after that
 
 ## CONTEXT BOUNDARIES:
 
@@ -64,7 +65,7 @@ Source code matches provenance map exactly. The skill `{skill_name}` is current
 
 **Recommendation:** No action required. Run audit-skill periodically to monitor for drift."
 
-→ **Workflow complete.** End here.
+→ Load and execute `{nextStepFile}` for workflow self-improvement check.
 
 ### 2. Present Change Summary
 
@@ -142,11 +143,13 @@ Source code matches provenance map exactly. The skill `{skill_name}` is current
 
 | File | Status |
 |------|--------|
-| `{skills_output_folder}/{skill_name}/SKILL.md` | Updated |
-| `{skills_output_folder}/{skill_name}/metadata.json` | Updated |
-| `{forge_data_folder}/{skill_name}/provenance-map.json` | Updated |
-| `{forge_data_folder}/{skill_name}/evidence-report.md` | Appended |
-| {stack reference files if applicable} | Updated |"
+| `{resolved_skill_package}/SKILL.md` | Updated |
+| `{resolved_skill_package}/metadata.json` | Updated |
+| `{forge_version}/provenance-map.json` | Updated |
+| `{forge_version}/evidence-report.md` | Appended |
+| {stack reference files if applicable} | Updated |
+
+Where `{resolved_skill_package}` = `{skills_output_folder}/{skill_name}/{version}/{skill_name}/` and `{forge_version}` = `{forge_data_folder}/{skill_name}/{version}/` — see [knowledge/version-paths.md](../../../knowledge/version-paths.md)."
 
 ### 5. Workflow Chaining Recommendations
 
@@ -173,7 +176,9 @@ Based on the update results:"
 
 **Update-skill workflow complete for `{skill_name}`.**"
 
-→ **No next step.** Workflow ends here.
+### 7. Workflow Health Check
+
+Load and execute `{nextStepFile}` for workflow self-improvement check.
 
 ---
 

package/src/workflows/verify-stack/steps-c/step-01-init.md

@@ -81,9 +81,14 @@ Wait for user input.
 
 ### 2. Scan Skills Folder
 
-Read the `{skills_output_folder}` directory.
+Read the `{skills_output_folder}` directory. Skills use a version-nested directory structure (see [knowledge/version-paths.md](../../../knowledge/version-paths.md)).
 
-For each subdirectory, check for the presence of `SKILL.md` and `metadata.json`.
+**Version-aware skill discovery:**
+1. Read `{skills_output_folder}/.export-manifest.json` if it exists. For each skill in `exports`, use `active_version` to resolve `{skill_package}` = `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/`
+2. For any subdirectory not covered by the manifest, check for an `active` symlink at `{skills_output_folder}/{dir_name}/active` — resolve to `{skill_group}/active/{dir_name}/`
+3. Fall back to flat path `{skills_output_folder}/{dir_name}/` for unmigrated skills
+
+For each resolved skill package, check for the presence of `SKILL.md` and `metadata.json`.
 
 **For each valid skill directory, extract from metadata.json:**
 - `name` — skill name
@@ -94,7 +99,7 @@ For each subdirectory, check for the presence of `SKILL.md` and `metadata.json`.
 
 **Build a skill inventory** as an internal list of all loaded skills with the fields above.
 
-**If a subdirectory lacks SKILL.md or metadata.json:**
+**If a resolved skill package lacks SKILL.md or metadata.json:**
 - Log: "Skipping `{dir_name}` — missing SKILL.md or metadata.json"
 - Do not include in inventory
 

package/src/workflows/verify-stack/steps-c/step-06-report.md

@@ -3,6 +3,7 @@ name: 'step-06-report'
 description: 'Present the final feasibility report to the user with verdict, findings, and next steps'
 
 outputFile: '{forge_data_folder}/feasibility-report-{project_name}.md'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 6: Present Report
@@ -30,7 +31,7 @@ Present the complete feasibility report to the user. Display the overall verdict
 - 🎯 Focus ONLY on presenting the completed report — no new analysis
 - 🚫 FORBIDDEN to discover new findings, re-analyze skills, or change verdicts
 - 🚫 FORBIDDEN to modify the report content — only read and present
-- 📋 This is the FINAL step — no nextStepFile
+- 📋 Chains to shared health check via `{nextStepFile}` — no further steps after that
 
 ## EXECUTION PROTOCOLS:
 
@@ -160,15 +161,17 @@ Re-run **[VS] Verify Stack** anytime after making changes to your skills or arch
 
 **Verification workflow complete.**"
 
+  Then load and execute `{nextStepFile}` for workflow self-improvement check.
+
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting the menu
 - R may be selected multiple times — always walk through the full report
-- X ends the workflow
+- X triggers the health check, which is the true workflow exit
 
 ## CRITICAL STEP COMPLETION NOTE
 
-This is the final step of the verify-stack workflow. When the user selects X, the workflow is complete. The feasibility report at `{outputFile}` contains the full analysis: Coverage Matrix, Integration Verdicts, Requirements Coverage, and Synthesis & Recommendations.
+When the user selects X, this step chains to the shared health check. After the health check completes, the verify-stack workflow is fully done. The feasibility report at `{outputFile}` contains the full analysis: Coverage Matrix, Integration Verdicts, Requirements Coverage, and Synthesis & Recommendations.
 
 ---