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

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

@@ -0,0 +1,278 @@
+---
+nextStepFile: './step-07-report.md'
+---
+
+# Step 6: Write Updated Files
+
+## STEP GOAL:
+
+Verify the merged SKILL.md and stack reference files that step-04 section 6b wrote to disk, then write the derived artifacts (metadata.json, provenance-map.json, evidence-report.md, context-snippet.md, and the active symlink).
+
+## Rules
+
+- Focus only on verifying merged files and writing derived artifacts — merge content was already written in step-04
+- Do not modify merged SKILL.md content — any mismatch detected during verification triggers HALT, not repair
+- Do not skip provenance map update — critical for future audits
+- HALT immediately on verification failure before writing any derived artifact — a partial-write skill package is worse than an unchanged one
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 0. Description Guard Protocol
+
+**Used by:** §7 (`skill-check check --fix` and `skill-check split-body --write`), and any future tool invocation that may modify SKILL.md's frontmatter on disk.
+
+External validators occasionally rewrite the frontmatter `description` field — `skill-check --fix` may replace it with a generic or truncated version, and `split-body` may touch it during mechanical restructuring. The merged description written to disk in step-04 is **authoritative**: it reflects the final merge of the prior skill's description (with any author edits preserved) and fresh re-extraction results. Losing it to a tool's well-meaning rewrite breaks discovery quality and — if the prior skill was compiled from a sanitized description (step-05 §2a) — can re-introduce angle-bracket tokens that then fail tessl on the next run.
+
+To prevent this, any tool invocation in §7 that may touch SKILL.md must run inside the following four-phase guard:
+
+1. **Capture.** Before invoking the tool, read `{skill_package}/SKILL.md` frontmatter and snapshot the exact `description` value into a local variable (e.g., `guarded_description`). Capture the in-context copy as well.
+2. **Execute.** Run the tool as specified in its section.
+3. **Verify.** After the tool completes, re-read the on-disk SKILL.md and compare its frontmatter `description` against `guarded_description`. Normalize whitespace for comparison (trim leading/trailing whitespace, collapse internal runs) but do not ignore content differences.
+4. **Restore on divergence.** If the post-tool description differs from `guarded_description` in any way other than whitespace normalization, write `guarded_description` back to the on-disk SKILL.md frontmatter and update the in-context copy to match. Record `description_guard_restored: true` with the tool name in context for the evidence report.
+
+**What counts as divergence:**
+
+- The description was replaced (different content).
+- The description was truncated (suffix missing).
+- Angle-bracket tokens were re-introduced (should never happen if the prior skill was correctly sanitized, but protect anyway).
+- The field was deleted entirely (extreme tool behavior).
+
+**What does NOT count as divergence:** whitespace-only differences (trailing newline, trimmed spaces) — treat as equivalent.
+
+**Why this lives in update-skill too:** the guard protocol was first introduced in `skf-create-skill/step-06-validate.md §0` to defend the freshly-compiled description. Update-skill runs the identical `skill-check check --fix` command against the merged skill package in §7, so it faces the same risk and needs the same defense. Keep the two §0 protocols functionally identical — if external tool behavior changes, update both workflows.
+
+### 1. Verify SKILL.md Write
+
+SKILL.md was written in step-04 section 6b. Verify the write landed intact before proceeding to any derived-artifact writes.
+
+- Read `{skill_package}/SKILL.md` from disk
+- Count `<!-- [MANUAL:*] -->` opening markers and compare against the [MANUAL] inventory captured in step-01
+- Verify the resolved `{skill_package}` path matches the version directory step-04 wrote to (if the version changed, step-04 updated `{skill_package}` in context to point at the new path)
+- If [MANUAL] count matches and path resolves: proceed to section 2
+- **If [MANUAL] count does not match: HALT immediately.** Do not write `metadata.json`, `provenance-map.json`, or any other artifact — further writes would compound the inconsistency. Alert the user:
+
+  "**[MANUAL] section count mismatch after write.** Expected {N} from step-01 inventory, found {M} on disk at `{skill_package}/SKILL.md`. The skill package is in an inconsistent state. Manual recovery required — restore the previous version from `{skill_group}/{previous_version}/` or fix the file in place, then re-run update-skill."
+
+### 2. Write Updated metadata.json
+
+Update `{skill_package}/metadata.json`:
+- Update `version`: **if `update_mode == "gap-driven"`, do not bump — the skill is being repaired against the same source commit, so leave `version` unchanged and update only `generation_date` / `last_update` below.** This keeps metadata `version` consistent with the on-disk `{skill_package}` path, which step-04 §6b also leaves unchanged in gap-driven mode (see step-04 §6b's "If the source version detected during step-03 differs..." carve-out — in gap-driven mode no source version is detected, so step-04 writes into the existing version directory). Otherwise, 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
+- Update `stats` from re-extraction results:
+  - `exports_documented`: count of exports with documentation in the merged skill
+  - `exports_public_api`: count of exports from public entry points (`__init__.py`, `index.ts`, `lib.rs`, or equivalent)
+  - `exports_internal`: count of all other non-underscore-prefixed exports
+  - `exports_total`: `exports_public_api` + `exports_internal`
+  - `public_api_coverage`: `exports_documented / exports_public_api` (`null` if `exports_public_api` is 0)
+  - `total_coverage`: `exports_documented / exports_total` (`null` if `exports_total` is 0)
+- Update `confidence_distribution` from re-extraction results:
+  - `confidence_distribution.t1`, `confidence_distribution.t1_low`, `confidence_distribution.t2`, `confidence_distribution.t3`: update counts from re-extraction results
+  - `scripts_count`, `assets_count`: update from re-extraction results if scripts/assets changed
+- For stack skills: update `library_count`, `integration_count` if changed
+
+### 3. Write Updated provenance-map.json
+
+Write to `{forge_version}/provenance-map.json`:
+
+**If `no_reextraction == true` (gap-driven mode from step-03 section 0):**
+Dispatch per-entry on the verification outcome recorded by step-03 — gap-driven runs produce a mix of `verified`, `moved`, `re-extracted`, and `unknown` outcomes, and each requires a different provenance-map write strategy:
+
+- **`verified` exports**: no fresh extraction data exists — do NOT overwrite `confidence`, `extraction_method`, `ast_node_type`, `params[]`, `return_type`, `source_file`, or `source_line`. The provenance entry stays byte-identical.
+- **`moved` exports**: update `source_line` (and `source_file` if different) to the new location recorded by the spot-check. Do not touch other fields.
+- **`re-extracted` exports** (resolved via step-03 §0a's Targeted Re-Extraction Branch from `remediation_paths[]`): write a full entry — `source_file`, `source_line`, `confidence`, `extraction_method`, `ast_node_type`, `params[]`, `return_type` — from §0a's fresh AST extraction record. This is the only gap-driven outcome that produces normal-mode-quality provenance; do NOT fall through to the byte-identical preservation above.
+- **`unknown` exports** (not in provenance map; no `source_citation`; `severity` is `Medium`, `Low`, or `Info`, OR `remediation_paths[]` was empty and §0a did not halt): add new entries with fields populated from step-04 merge output. `source_file`/`source_line` may be `null` here — leave these fields unset rather than writing stale values. **This path is only acceptable for `severity` in `Medium`, `Low`, or `Info`.** A Critical/High `unknown` reaching this branch indicates step-03 §0a was skipped or bypassed and is a workflow bug — step-03 §0a should have halted with status `halted-for-remediation-path` before step-06 ran. If you encounter one, halt with a pointer to §0a rather than writing null citations for a blocking gap.
+- Skip the "For each export in the updated skill" bullets below — they apply only to normal re-extraction mode.
+
+**For each export in the updated skill (normal mode only):**
+- Update `export_name` if renamed
+- Update `params[]` array if parameters changed (add, remove, or modify individual entries)
+- Update `return_type` if changed
+- Update `source_file` if moved
+- Update `source_line` from fresh extraction
+- Update `confidence` from extraction results
+- Update `extraction_method` and `ast_node_type` if re-extracted with different tools
+
+**For deleted exports:**
+- Remove entry from provenance map
+
+**For new exports:**
+- Add new entry with full structured fields: `export_name`, `export_type`, `params[]`, `return_type`, `source_file`, `source_line`, `confidence`, `extraction_method`, `ast_node_type`
+
+**For script/asset file changes (if `file_entries` exists):**
+- MODIFIED_FILE: copy updated file to `scripts/` or `assets/`, update `content_hash` in `file_entries`
+- DELETED_FILE: remove file from `scripts/` or `assets/`, remove entry from `file_entries`
+- NEW_FILE: copy file to `scripts/` or `assets/`, add entry to `file_entries` with `file_name`, `file_type`, `source_file`, `confidence: "T1-low"`, `extraction_method: "file-copy"`, `content_hash`
+
+**Add update operation metadata:**
+```json
+{
+  "last_update": "{current_date}",
+  "update_type": "{incremental if normal mode | full if degraded_mode}",
+  "files_changed": {count},
+  "exports_affected": {count},
+  "confidence_tier": "{tier}",
+  "manual_sections_preserved": {count}
+}
+```
+
+### 4. Write Updated evidence-report.md
+
+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}
+
+**Trigger:** {manual / audit-skill chain}
+**Forge Tier:** {tier}
+**Mode:** {normal / degraded}
+
+### Changes Detected
+- Files modified: {count}
+- Files added: {count}
+- Files deleted: {count}
+- Exports affected: {total}
+
+### Merge Results
+- Exports updated: {count}
+- Exports added: {count}
+- Exports removed: {count}
+- [MANUAL] sections preserved: {count}
+- Conflicts resolved: {count}
+
+### Validation Summary
+- Spec compliance: {PASS/WARN/FAIL}
+- [MANUAL] integrity: {PASS/WARN/FAIL}
+- Confidence tiers: {PASS/WARN/FAIL}
+- Provenance: {PASS/WARN/FAIL}
+
+### Description Guard
+- Restored: {true/false}
+- Triggering tool: {tool_name or —}
+- Original description preserved: {true/false}
+- Notes: {one-sentence detail or —}
+
+### Context Snippet
+- Regenerated: {true/false}
+- Triggers fired: {list or —}
+- Notes: {one-sentence detail or —}
+```
+
+**Description Guard population** (used by §7 Post-Write Validation when the §0 protocol fires): fill all four fields from context when `description_guard_restored == true` (triggering tool, whether restore succeeded, what changed). When `Restored: false`, the other three fields are `—` — this is the clean-run expected state. Same field semantics and populator logic as create-skill step-06 §8.
+
+**Context Snippet population** (used by §5 after the staleness check runs): §4 writes the sub-block with placeholders; §5 updates the on-disk evidence report in place after deciding whether to regenerate. Set `Regenerated: true` and populate `Triggers fired` with any combination of `headline-exports`, `version`, `gotchas` when at least one trigger fired. Set `Regenerated: false` and `Triggers fired: —` when none fired (the gap-driven / internals-only outcome). Always fill `Notes` with a one-sentence reason (e.g., `"Gap-driven repair — no snippet surface changed"`, `"Version bumped 0.1.0 → 0.2.0; headline exports re-ranked"`).
+
+### 5. Verify Stack Skill Reference File Writes (Conditional) and Regenerate context-snippet.md
+
+**ONLY if skill_type == "stack":**
+
+Stack reference files were written in step-04 section 6b. Verify each affected reference file that the merge produced:
+
+- Read each `references/{library}.md` back from disk
+- Read each `references/integrations/{pair}.md` back from disk
+- Verify per-file [MANUAL] section counts match the per-file inventory captured in step-01
+- **If any verification fails: HALT** using the same recovery protocol as section 1 — do not regenerate `context-snippet.md` or write any further derived artifact
+
+**For all skills (both single and stack) — regenerate `context-snippet.md` if stale:**
+
+`context-snippet.md` is a `{skill_package}` deliverable that goes stale whenever **headline exports**, **version**, or **gotchas** change in this run. Regenerate it only when at least one of these triggers fired; otherwise skip — a skip is the correct outcome for gap-driven repairs and other runs that touch internals below the snippet's surface, where regenerating would produce byte-identical content.
+
+**Staleness triggers:**
+
+- **Headline exports changed** — the top-K exports surfaced in the snippet differ from the prior snippet (a `NEW_EXPORT` was promoted into a headline slot, or a `MODIFIED_EXPORT` changed the signature/shape of a surfaced export).
+- **Version changed** — §2 bumped `version` (normal mode with detected source drift; never fires in gap-driven mode per §2's carve-out).
+- **Gotchas changed** — new gotchas surfaced from this run's evidence that were not in the prior snippet, or a prior gotcha was invalidated and removed.
+
+**Record the decision on the on-disk evidence report:** open `{forge_version}/evidence-report.md` (written by §4 with placeholder values in the `### Context Snippet` sub-block) and update that sub-block under the Update Operation section just written. Set `Regenerated: true|false`, fill `Triggers fired:` with the list of triggers that fired (or `—` when none), and write a one-sentence `Notes:` entry. See §4's "Context Snippet population" note for field semantics.
+
+**If no trigger fired:** skip regeneration — do not touch `context-snippet.md` on disk. The snippet remains valid against the prior run's surface. Continue to §5b.
+
+**If at least one trigger fired:** regenerate the snippet using the format from the matching template file:
+
+- For single skills: `skf-create-skill/assets/skill-sections.md` (pipe-delimited indexed format)
+- For stack skills: `skf-create-stack-skill/assets/stack-skill-template.md`
+
+Use the **flat draft form** for the `root:` path in the draft snippet: `root: skills/{skill-name}/`. The per-IDE skill root (e.g., `.claude/skills/`, `.windsurf/skills/`, `.github/skills/` — see `skf-export-skill/assets/managed-section-format.md`) is applied later by `export-skill` step-03 when the skill is exported. Do not choose an IDE-specific 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 `skf-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 Derived Artifact Writes
+
+SKILL.md was verified in section 1 and stack reference files in section 5 (both written by step-04 section 6b). This section verifies the artifacts this step wrote: `metadata.json`, `provenance-map.json`, `evidence-report.md`, `context-snippet.md`, and the `active` symlink from §5b.
+
+For each derived artifact:
+- Read back the file
+- Confirm content matches expected output
+- Report verification status
+
+**Active symlink verification:** resolve `readlink({skill_group}/active)` and assert it equals the `version` just written to `metadata.json` in §2. This closes the §5b gap where a silent skip would otherwise leave the manifest and symlink divergent — the symlink is the fallback resolver for consumers that don't read the manifest (see `knowledge/version-paths.md` §Reading Workflows step 5), so a mismatch must fail the step, not warn. Applies in every mode — gap-driven runs do not bump `version`, but the symlink must still point to the current `version`, otherwise a prior partial run left it pointing elsewhere.
+
+"**Write Verification:**
+
+| File | Status |
+|------|--------|
+| SKILL.md | {VERIFIED in section 1} |
+| metadata.json | {VERIFIED/FAILED} |
+| provenance-map.json | {VERIFIED/FAILED} |
+| evidence-report.md | {VERIFIED/FAILED} |
+| context-snippet.md | {VERIFIED/FAILED} |
+| {skill_group}/active symlink | {VERIFIED/FAILED} (readlink → {resolved_version}, expected {version}) |
+| {stack reference files...} | {VERIFIED in section 5} |
+
+**On symlink FAILED:** HALT. Do not proceed to §7 post-write validation or §8 menu. Alert the user: "**Active symlink divergence.** `{skill_group}/active` resolves to `{resolved_version}` but `metadata.json` reports `version: {version}`. §5b did not apply. Re-point the symlink manually (`ln -sfn {version} {skill_group}/active`) or re-run update-skill, then re-verify." This matches the severity of the other four artifact checks — silent divergence here mis-routes any downstream consumer that uses the symlink fallback.
+
+**All files written and verified.**"
+
+### 7. Run Post-Write Validation (Deferred from Step 05)
+
+External tool checks deferred from step-05 now run against the written files.
+
+**Description Guard Protocol:** every invocation below that may modify SKILL.md (`skill-check check --fix` and any `split-body` write) must run inside the four-phase guard defined in §0. Capture `guarded_description` before each call, execute, verify against the post-tool description, and restore on divergence. Do not rely on per-call ad-hoc preservation logic — use the §0 protocol.
+
+**If skill-check available:**
+
+- Run: `npx skill-check check {skill_package} --fix --format json --no-security-scan` **inside the §0 guard**.
+- **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. The §0 guard has already restored `description` if divergent; the re-read picks up any other fix-corrected content.
+- 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). **If falling back to `npx skill-check split-body {skill_package} --write`, run it inside the §0 guard** — split-body can also touch frontmatter. Verify anchors resolve after split.
+- Run: `npx skill-check diff` if original version was preserved.
+- Run: `npx skill-check check {skill_package} --format json` for security scan. (Read-only; guard not required.)
+
+Record findings in the evidence report (section 4), including any `description_guard_restored` events recorded by the §0 protocol. These are advisory — do not block on warnings.
+
+**If skill-check unavailable:** Skip with note — structural checks from step-05 are sufficient.
+
+### 8. Present MENU OPTIONS
+
+Display: "**Proceeding to report...**"
+
+#### Menu Handling Logic:
+
+- After all writes verified and post-write validation complete, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed step with no user choices
+- Proceed directly to report after verification
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN all files have been written and verified will you load {nextStepFile} to display the change report.
+

package/src/{workflows/update-skill → skf-update-skill}/steps-c/step-07-report.md

@@ -1,6 +1,5 @@
 ---
-name: 'step-07-report'
-description: 'Display comprehensive change summary with diff visualization and workflow chaining recommendations'
+nextStepFile: './step-08-health-check.md'
 ---
 
 # Step 7: Report
@@ -9,41 +8,11 @@ description: 'Display comprehensive change summary with diff visualization and w
 
 Present a comprehensive change summary showing what was updated, [MANUAL] sections preserved, confidence tier breakdown, and recommend next workflow actions in the SKF chain.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+## Rules
 
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a precision code analyst operating in Surgeon mode
-- ✅ Report factually — no embellishment, no speculation
-- ✅ Every reported metric must trace to actual operations performed
-- ✅ Recommendations based on validation results and workflow chaining contracts
-
-### Step-Specific Rules:
-
-- 🎯 Focus ONLY on reporting — all operations are complete
-- 🚫 FORBIDDEN to modify any files — report is read-only display
-- 💬 Present clear, actionable summary with next step recommendations
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow MANDATORY SEQUENCE exactly
-- 💾 No file writes — display only
-- 📖 This is the final step — workflow completes here
-
-## CONTEXT BOUNDARIES:
-
-- Available: all results from steps 01-06 (baseline, change manifest, extraction results, merge results, validation results, write verification)
-- Focus: summary and recommendations
-- Limits: display only — no modifications
-- Dependencies: all previous steps must be complete (or no-change shortcut from step 02)
+- Focus only on reporting — all operations are complete; do not modify any files
+- Present clear, actionable summary with next step recommendations
+- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing summary is NOT the terminal step
 
 ## MANDATORY SEQUENCE
 
@@ -64,7 +33,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, read the full file, and execute `{nextStepFile}` — the health-check step is the true terminal step of this workflow.
 
 ### 2. Present Change Summary
 
@@ -148,7 +117,7 @@ Source code matches provenance map exactly. The skill `{skill_name}` is current
 | `{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)."
+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`."
 
 ### 5. Workflow Chaining Recommendations
 
@@ -169,35 +138,11 @@ Based on the update results:"
 "- **audit-skill** — Re-run to verify CRITICAL/HIGH drift resolved
 - **export-skill** — Package once audit confirms clean state"
 
-### 6. Workflow Complete
-
-"---
-
-**Update-skill workflow complete for `{skill_name}`.**"
-
-→ **No next step.** Workflow ends here.
-
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
+### 5b. Result Contract
 
-- Comprehensive summary displayed with all metrics from the update operation
-- Change categories broken down clearly
-- Confidence tier breakdown reported
-- [MANUAL] preservation status confirmed
-- Validation findings presented if any
-- Files written listed with paths
-- Workflow chaining recommendations provided
-- No-change shortcut handled correctly
+Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{forge_version}/update-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_version}/update-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all modified file paths in `outputs`; include `exports_affected`, `files_modified`, and `validation_status` (passed/warnings/failures) in `summary`.
 
-### ❌ SYSTEM FAILURE:
+### 6. Chain to Health Check
 
-- Reporting metrics not backed by actual operations
-- Not reporting [MANUAL] preservation status
-- Not providing workflow chaining recommendations
-- Modifying any files during reporting
-- Not handling the no-change shortcut from step 02
+ONLY WHEN the change summary has been presented, files-written list displayed, and result contract saved will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the report reads as final.
 
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/skf-update-skill/steps-c/step-08-health-check.md

@@ -0,0 +1,22 @@
+---
+# `shared/health-check.md` resolves relative to the SKF module root
+# (`_bmad/skf/` when installed, `src/` during development), NOT relative
+# to this step file.
+nextStepFile: 'shared/health-check.md'
+---
+
+# Step 8: Workflow Health Check
+
+## STEP GOAL:
+
+Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of update-skill — after the shared health check completes, the workflow is fully done.
+
+## Rules
+
+- No user-facing reports, file writes, or result contracts in this step — those belong in step-07
+- Delegate directly to `{nextStepFile}` with no additional commentary
+- Do not attempt any other action between loading this step and executing `{nextStepFile}`
+
+## MANDATORY SEQUENCE
+
+Load `{nextStepFile}`, read it fully, then execute it.

package/src/skf-verify-stack/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: skf-verify-stack
+description: Pre-code stack feasibility verification against architecture and PRD documents. Use when the user requests to "verify a tech stack" or "verify stack."
+---
+
+# Verify Stack
+
+## Overview
+
+Cross-references generated skills against architecture and PRD documents to produce a feasibility report with evidence-backed integration verdicts, coverage analysis, and requirements mapping. This is a read-only workflow — it never modifies skills or input documents, only reads and produces a feasibility report. Every verdict must cite specific APIs, types, or function signatures from the generated skills.
+
+**Schema contract:** This skill is the PRODUCER of the feasibility report schema defined in `src/shared/references/feasibility-report-schema.md`. All report outputs emit `schemaVersion: "1.0"` in frontmatter, use only the defined verdict tokens (`Verified|Plausible|Risky|Blocked` per pair; `FEASIBLE|CONDITIONALLY_FEASIBLE|NOT_FEASIBLE` overall), follow the fixed section-heading order, and are written through `src/shared/scripts/skf-atomic-write.py write` to both the timestamped file and the stable `-latest.md` copy.
+
+## Role
+
+You are a stack feasibility analyst and integration verifier operating in Ferris Audit mode. You bring expertise in API surface analysis, cross-library compatibility assessment, and architecture validation, while the user brings their architecture vision and generated skills.
+
+## Workflow Rules
+
+These rules apply to every step in this workflow:
+
+- Read-only — never modify skills, architecture docs, or PRD files
+- Every verdict must cite evidence from the generated skills
+- Read each step file completely before taking any action
+- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
+- Only load one step file at a time — never preload future steps
+- If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
+- Always communicate in `{communication_language}`
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+
+## Stages
+
+| # | Step | File | Auto-proceed |
+|---|------|------|--------------|
+| 1 | Initialize & Load Inputs | steps-c/step-01-init.md | No (confirm) |
+| 2 | Coverage Analysis | steps-c/step-02-coverage.md | Yes |
+| 3 | Integration Verification | steps-c/step-03-integrations.md | Yes |
+| 4 | Requirements Mapping | steps-c/step-04-requirements.md | Yes |
+| 5 | Synthesize Verdict | steps-c/step-05-synthesize.md | Yes |
+| 6 | Report | steps-c/step-06-report.md | No (confirm) |
+| 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | architecture_doc_path [required], prd_path [optional] |
+| **Gates** | step-01: Input Gate [use args] | step-06: Confirm Gate [C] |
+| **Outputs** | `feasibility-report-{projectSlug}-{timestamp}.md` and `feasibility-report-{projectSlug}-latest.md` (copy, not symlink) per `src/shared/references/feasibility-report-schema.md` — with integration verdicts, coverage analysis, recommendations, and evidence sources |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
+   - `project_name`, `user_name`, `communication_language`
+   - `skills_output_folder`, `forge_data_folder`, `document_output_language`
+
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+
+3. Load, read the full file, and then execute `./steps-c/step-01-init.md` to begin the workflow.

package/src/skf-verify-stack/assets/feasibility-report-template.md

@@ -0,0 +1,76 @@
+---
+schemaVersion: "1.0"
+reportType: feasibility
+projectName: ""
+projectSlug: ""
+generatedAt: ""
+generatedBy: skf-verify-stack
+overallVerdict: "CONDITIONALLY_FEASIBLE"
+coveragePercentage: 0
+pairsVerified: 0
+pairsPlausible: 0
+pairsRisky: 0
+pairsBlocked: 0
+recommendationCount: 0
+prdAvailable: false
+# Producer-local bookkeeping (not part of the shared consumer contract):
+workflowType: 'verify-stack'
+architectureDoc: ''
+prdDoc: ''
+previousReport: ''
+skillsAnalyzed: 0
+stepsCompleted: []
+requirementsPass: ''
+requirementsFulfilled: null
+requirementsPartial: null
+requirementsNotAddressed: null
+deltaImproved: null
+deltaRegressed: null
+deltaNew: null
+deltaUnchanged: null
+---
+
+# Stack Feasibility Report: {projectName}
+
+**Verification Date:** {generatedAt}
+**Architecture Document:** {architectureDoc}
+**PRD Document:** {prdDoc}
+**Skills Analyzed:** {skillsAnalyzed}
+
+> Schema contract: `src/shared/references/feasibility-report-schema.md` (schemaVersion `1.0`). Consumers MUST halt on `schemaVersion` mismatch.
+
+## Executive Summary
+
+**Overall Verdict:** {FEASIBLE | CONDITIONALLY_FEASIBLE | NOT_FEASIBLE}
+
+{1-2 sentence summary}
+
+---
+
+## Coverage Analysis
+
+<!-- Appended by step-02-coverage -->
+
+---
+
+## Integration Verdicts
+
+<!-- Appended by step-03-integrations.
+Consumers grep for the `## Integration Verdicts` heading to locate the pair table.
+The table header is fixed and MUST be emitted exactly as shown below: -->
+
+| lib_a | lib_b | verdict | rationale |
+|-------|-------|---------|-----------|
+
+---
+
+## Recommendations
+
+<!-- Appended by step-05-synthesize -->
+
+---
+
+## Evidence Sources
+
+<!-- Appended by step-05-synthesize — cite each skill's SKILL.md path, metadata_schema_version,
+     confidence_tier, stack manifest (if any), and architecture/PRD doc paths -->

package/src/{workflows/verify-stack/data → skf-verify-stack/references}/coverage-patterns.md

@@ -26,11 +26,19 @@ Parse document section headers for technology groupings:
 
 ### Coverage Verdict
 
-| Verdict | Meaning |
-|---------|---------|
-| **Covered** | A generated skill exists in `skills/` for this technology |
+The coverage matrix renders two verdict tokens per referenced technology: **Covered** and **Missing**. Extra skills (skills present in the inventory but NOT referenced by the architecture document) are tracked in a separate informational subdivision — they are not coverage verdicts and do not appear in the primary `Technology → Skill Match → Verdict` column. See step-02 §4 for the Extra-skill subdivision output.
+
+| Verdict     | Meaning                                                          |
+|-------------|------------------------------------------------------------------|
+| **Covered** | A generated skill exists in `skills/` for this technology        |
 | **Missing** | Technology is referenced in architecture doc but no skill exists |
-| **Extra** | A skill exists but the technology is not referenced in the architecture doc (informational, not an error) |
+
+**Informational — Extra skills subdivision (not a verdict; rendered in a separate section per step-02 §4):**
+
+| Label                                  | Meaning                                                                                                                          |
+|----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
+| **Extra (unreferenced)**               | Skill exists with a resolvable `source_repo` / `source_root`, but no architecture tech token matches it                          |
+| **Orphan (source_repo unresolvable)**  | Skill's `source_repo` is empty, malformed, or its basename cannot be extracted — cross-reference against architecture impossible |
 
 ## Output Format