bmad-module-skill-forge 1.4.1 → 1.5.0

package/src/skf-verify-stack/references/init.md

@@ -0,0 +1,166 @@
+---
+nextStepFile: 'coverage.md'
+feasibilitySchemaRef: 'src/shared/references/feasibility-report-schema.md'
+atomicWriteScript: '{project-root}/src/shared/scripts/skf-atomic-write.py'
+# {outputFile} and {outputFileLatest} resolve from the activation-stored
+# {project_slug}, {timestamp}, and {outputFolderPath} variables (set in
+# SKILL.md On Activation §2 + §4). The activation-stored values are
+# fixed for the entire run, so every later reference sees the same
+# filename — no order-of-operations bug.
+outputFile: '{outputFolderPath}/feasibility-report-{project_slug}-{timestamp}.md'
+outputFileLatest: '{outputFolderPath}/feasibility-report-{project_slug}-latest.md'
+# Resolve `{enumerateStackSkillsHelper}` by probing
+# `{enumerateStackSkillsProbeOrder}` in order (installed SKF module path
+# first, src/ dev-checkout fallback); first existing path wins. §2 calls
+# it for the deterministic skills inventory (cascade-resolved exports,
+# metadata-hash for change-detection, confidence-tier mapping). HALT if
+# neither candidate exists — falls through to LLM-driven subagent fan-out
+# only as graceful degradation, see §2.
+enumerateStackSkillsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-enumerate-stack-skills.py'
+  - '{project-root}/src/shared/scripts/skf-enumerate-stack-skills.py'
+---
+
+<!-- Config: communicate in {communication_language}. Initialize the feasibility report skeleton in {document_output_language}. -->
+
+# Step 1: Initialize Verification
+
+## STEP GOAL:
+
+Load all generated skills from the skills output folder, accept the architecture document path (required) and optional PRD/vision document path from the user, validate that all inputs exist and are readable, create the feasibility report document, and present an initialization summary before auto-proceeding.
+
+## Rules
+
+- Focus only on loading inputs, scanning skills, and creating the report skeleton — do not perform analysis
+- Auto-proceed — halts only on validation errors
+
+## MANDATORY SEQUENCE
+
+### 1. Accept Input Documents
+
+"**Verify Stack — Feasibility Analysis** (read-only — never modifies your skills, architecture doc, or PRD).
+
+If you meant to *generate* skills first, type `cancel` and run `[CS] Create Skill` or `[QS] Quick Skill`. Otherwise, please provide the following:
+1. **Architecture document path** (REQUIRED) — your project's architecture doc
+2. **PRD or vision document path** (OPTIONAL) — for requirements coverage analysis
+3. **Previous feasibility report path** (OPTIONAL) — for delta comparison with a prior run (provide a backup copy)
+
+Or type `cancel` / `exit` / `:q` at any prompt to abort cleanly."
+
+Wait for user input. **GATE [default: use args]** — If `{headless_mode}` and `--architecture-doc` was provided: use that path and auto-proceed, log: "headless: using provided architecture path". If `--prd` and/or `--previous-report` were provided, consume them at the corresponding sub-validations below. If `--architecture-doc` is absent in headless: HALT (exit code 2, `halt_reason: "input-missing"`) and emit the error envelope.
+
+- If the user enters `cancel`, `exit`, `[X]`, `q`, or `:q` at any sub-prompt below: Display "Cancelled — no analysis was performed." and HALT (exit code 6, `halt_reason: "user-cancelled"`).
+
+**Validate architecture document:**
+- Confirm the file exists and is readable
+- If missing or unreadable → "Architecture document not found at `{path}`. Provide a valid path."
+- HALT (exit code 2, `halt_reason: "input-invalid"`) if the user cannot provide a valid path. In headless, emit the error envelope per SKILL.md "Result Contract (Headless)" immediately.
+
+**Validate PRD document (if provided):**
+- Confirm the file exists and is readable
+- If missing → "PRD document not found at `{path}`. Proceeding without PRD — requirements pass will be skipped."
+- Store PRD availability as `prdAvailable: true|false`
+
+**Validate previous report (if provided):**
+- Confirm the file exists and is readable
+- **Collision check:** Resolve `{outputFile}` from the activation-stored `{outputFolderPath}`, `{project_slug}`, and `{timestamp}` (all three computed in SKILL.md On Activation §2 + §4 — they are fixed for the entire run). Then compare both the provided path and `{outputFile}` via `(st_dev, st_ino)` tuples obtained from `stat(2)` on each path (do not rely on absolute-path string equality — symlinks, bind mounts, and case-insensitive filesystems can defeat string comparison; the `(st_dev, st_ino)` comparison is the canonical kernel-level equivalent of `os.path.realpath`-based equality and is strictly stronger because it also catches hardlinks). If `{outputFile}` does not yet exist, resolve its parent via `realpath`, stat that directory, and combine `(st_dev, parent_ino, basename)` for comparison. If the two paths resolve to the same inode, warn: "The previous report path points to the same inode as the new report. This file will be overwritten during this run. Provide a path to a backup copy, or leave empty to skip delta comparison." HALT (exit code 5, `halt_reason: "previous-report-collision"`) until resolved. In headless, emit the error envelope.
+- If missing → "Previous report not found at `{path}`. Proceeding without delta comparison."
+- Store as `previousReport: {path}` (or empty string if not provided)
+
+### 2. Scan Skills Folder
+
+**Pre-flight — skills folder existence:**
+- If `{skills_output_folder}` does not exist on disk: HALT (exit code 3, `halt_reason: "skills-folder-missing"`) with "**Cannot proceed.** `{skills_output_folder}` does not exist — run **[SF] Setup Forge** to initialize the forge, then generate skills with [CS] or [QS]." In headless, emit the error envelope.
+- If `{skills_output_folder}` exists but is empty (no subdirectories at all): HALT (exit code 3, `halt_reason: "skills-folder-missing"`) with "**Cannot proceed.** `{skills_output_folder}` contains 0 skills. Generate skills with [CS] Create Skill or [QS] Quick Skill, then re-run [VS]." In headless, emit the error envelope.
+
+**Resolve `{enumerateStackSkillsHelper}`** from `{enumerateStackSkillsProbeOrder}`; first existing path wins.
+
+**Primary path — deterministic enumeration via shared helper:**
+
+```bash
+python3 {enumerateStackSkillsHelper} enumerate {skills_output_folder}
+```
+
+The helper walks `{skills_output_folder}`, reads each `metadata.json`, applies the exports cascade (metadata → references/ → SKILL.md prose), maps `confidence_tier` (T1/T2/T1-low), captures stack-skill cycles via `composes:`, and emits structured JSON with one entry per skill plus a top-level `warnings[]` array. Cache the result as `skill_inventory` (used by §3, §4, §5, and the integrations + coverage stages).
+
+Each helper-emitted entry includes: `skill_name`, `version`, `language`, `confidence_tier`, `exports` (cascade-resolved), `source_repo`, `source_root`, plus a `metadata_hash` for change-detection across runs. The helper's `warnings[]` carries per-skill skip reasons (missing manifest, malformed JSON, non-symlink `active`, orphan-versions, schema-version violations).
+
+**Failure-budget guard:** If `len(warnings) / len(skill_inventory) + len(warnings) > 0.20` (the same 20% threshold chosen so a single malformed skill in a small 3-5 skill inventory does not trip the halt), HALT (exit code 7, `halt_reason: "inventory-unreliable"`) with: "Inventory scan unreliable — {len(warnings)}/{total} skills returned malformed metadata or skip warnings. Re-run [VS] after skills stabilize." In headless, emit the error envelope.
+
+**Capture mtime:** For each accepted skill in `skill_inventory`, also record `metadata.json`'s mtime via `stat` into the entry as `metadata_mtime`. Step-03 will re-verify this to detect mid-run modifications.
+
+**Fallback path — graceful degradation when the helper is unavailable:** If `{enumerateStackSkillsHelper}` has no existing candidate (e.g. partial installation), fall through to the LLM-driven subagent fan-out: launch up to **8 subagents concurrently**, each reading one resolved skill package's `metadata.json` and returning the same JSON shape the helper would emit. Apply the same 20% failure-budget guard. This path exists so verify-stack survives a missing helper, but the deterministic helper is preferred — it has a tested cascade resolver, captures the metadata-hash, and surfaces every skip reason in `warnings[]` consistently.
+
+### 3. Validate Minimum Requirements
+
+**Check skill count:**
+- At least 2 valid skills must exist (a stack requires multiple libraries)
+- If fewer than 2 → "**Cannot proceed.** Only {count} skill(s) found in `{skills_output_folder}`. A stack requires at least 2 skills. Generate more skills with [CS] Create Skill or [QS] Quick Skill, then re-run [VS]."
+- HALT (exit code 5, `halt_reason: "insufficient-skills"`). In headless, emit the error envelope.
+
+**Check forge_data_folder:**
+- Verify `forge_data_folder` was resolved from config.yaml and is non-empty
+- If undefined or empty → "**Cannot proceed.** `forge_data_folder` is not configured in config.yaml. Re-run [SF] Setup Forge to initialize."
+- HALT (exit code 3, `halt_reason: "forge-folder-unconfigured"`). In headless, emit the error envelope.
+
+**Check architecture document:**
+- Confirm it was loaded successfully in section 1
+- If not → HALT with error (should not reach here if section 1 validation passed)
+
+### 4. Create Feasibility Report
+
+This skill is the PRODUCER of the feasibility report schema defined in `{feasibilitySchemaRef}`. All outputs MUST conform to that schema — in particular: `schemaVersion: "1.0"`, the defined verdict token set (`Verified|Plausible|Risky|Blocked`; overall `FEASIBLE|CONDITIONALLY_FEASIBLE|NOT_FEASIBLE`), the filename pattern, and the section-heading order.
+
+**Filename variables** (already computed at activation — do not re-derive):
+- `project_slug`: set in SKILL.md On Activation §2 from `project_name`
+- `timestamp`: set in SKILL.md On Activation §2 (UTC `YYYYMMDD-HHmmss`, fixed for the run)
+- `outputFile` resolves to `{outputFolderPath}/feasibility-report-{project_slug}-{timestamp}.md` per the stage frontmatter template
+- `outputFileLatest` resolves to `{outputFolderPath}/feasibility-report-{project_slug}-latest.md` (a copy, not a symlink — per schema)
+
+**Load** `{reportTemplatePath}` (the customize-aware template path resolved in SKILL.md On Activation §4) and stage the initial content.
+
+**Populate frontmatter (per shared schema — required keys):**
+- `schemaVersion: "1.0"`
+- `reportType: feasibility`
+- `projectName: "{project_name}"`
+- `projectSlug: "{project_slug}"`
+- `generatedAt: "{ISO-8601 UTC}"`
+- `generatedBy: skf-verify-stack`
+- `overallVerdict: "CONDITIONALLY_FEASIBLE"` (provisional until step 5 finalizes)
+- `coveragePercentage: 0`
+- `pairsVerified: 0`, `pairsPlausible: 0`, `pairsRisky: 0`, `pairsBlocked: 0`
+- `recommendationCount: 0`
+- `prdAvailable: true|false` (from section 1 validation)
+
+**Populate producer-local bookkeeping keys (not part of the consumer contract):**
+- `architectureDoc`, `prdDoc` (or "none"), `previousReport` (or empty string)
+- `skillsAnalyzed: {count}`
+- `stepsCompleted: ['init']`
+
+**Atomic write:** Pipe the staged content through `python3 {atomicWriteScript} write --target {outputFile}` and then again with `--target {outputFileLatest}`. Both writes use the same staged content. Do NOT use `rm`+rewrite; do NOT create a symlink for the `-latest` copy.
+
+On any non-zero exit from either write: HALT (exit code 4, `halt_reason: "write-failed"`) and emit the error envelope per SKILL.md "Result Contract (Headless)" with `report_path: null`, `report_latest_path: null`, `overall_verdict: null`.
+
+### 5. Display Initialization Summary
+
+"**Stack Verification Initialized**
+
+| Field | Value |
+|-------|-------|
+| **Skills Loaded** | {count} |
+| **Architecture Doc** | {architecture_doc} |
+| **PRD Document** | {prd_doc or 'Not provided — requirements pass will be skipped'} |
+| **Previous Report** | {previousReport or 'Not provided — no delta comparison'} |
+
+**Skill Inventory:**
+
+| Skill | Language | Tier | Exports |
+|-------|----------|------|---------|
+| {skill_name} | {language} | {confidence_tier} | {exports_documented} |
+
+**Proceeding to coverage analysis...**"
+
+### 6. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+

package/src/skf-verify-stack/references/integration-verification-rules.md

@@ -17,7 +17,7 @@ Token set is defined canonically in `src/shared/references/feasibility-report-sc
 | **Risky**     | Type mismatch, protocol gap, or language boundary requiring a bridge                           | A clear gap exists (e.g., TypeScript↔Rust FFI needed) but a workaround is architecturally feasible — a named workaround MUST be cited in the recommendation                                                                                                        |
 | **Blocked**   | Fundamental incompatibility — no feasible integration path even with a bridge or adapter layer | The two libraries cannot exchange data in any documented way; requires replacing one of the libraries                                                                                                                                                              |
 
-**Promotion rule:** `Verified` requires Check 4 evidence. If Checks 1 and 3 pass but Check 4 fails (no literal substring/name citation from either skill's SKILL.md), the verdict is capped at `Plausible`. This rule is enforced by step-03 §4 and is the producer obligation declared in the shared schema.
+**Promotion rule:** `Verified` requires Check 4 evidence. If Checks 1 and 3 pass but Check 4 fails (no literal substring/name citation from either skill's SKILL.md), the verdict is capped at `Plausible`. This rule is enforced by step 3 §4 and is the producer obligation declared in the shared schema.
 
 ---
 

package/src/skf-verify-stack/{steps-c/step-03-integrations.md → references/integrations.md}

@@ -1,13 +1,15 @@
 ---
-nextStepFile: './step-04-requirements.md'
-integrationRulesData: 'references/integration-verification-rules.md'
-coveragePatternsData: 'references/coverage-patterns.md'
+nextStepFile: 'requirements.md'
+integrationRulesData: '{integrationRulesPath}'
+coveragePatternsData: '{coveragePatternsPath}'
 feasibilitySchemaRef: 'src/shared/references/feasibility-report-schema.md'
 atomicWriteScript: '{project-root}/src/shared/scripts/skf-atomic-write.py'
-outputFile: '{forge_data_folder}/feasibility-report-{project_slug}-{timestamp}.md'
-outputFileLatest: '{forge_data_folder}/feasibility-report-{project_slug}-latest.md'
+outputFile: '{outputFolderPath}/feasibility-report-{project_slug}-{timestamp}.md'
+outputFileLatest: '{outputFolderPath}/feasibility-report-{project_slug}-latest.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Append the Integration Verdicts section to the report in {document_output_language}. -->
+
 # Step 3: Integration Verification
 
 ## STEP GOAL:
@@ -22,8 +24,6 @@ Cross-reference API surfaces between library pairs that the architecture documen
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Load Integration Verification Rules
 
 Load `{integrationRulesData}` for the cross-reference verification protocol.
@@ -54,7 +54,7 @@ Parse the architecture document for statements describing two or more technologi
 
 <!-- Subagent delegation: read SKILL.md files in parallel, return compact JSON -->
 
-For each library in an integration pair, delegate SKILL.md reading to a parallel subagent. Launch up to **8 subagents concurrently** (batch if needed — same 8-way cap as step-01 §2; keeps aggregate token window manageable while still parallelizing typical stack sizes). Each subagent receives one skill's SKILL.md path and MUST:
+For each library in an integration pair, delegate SKILL.md reading to a parallel subagent. Launch up to **8 subagents concurrently** (batch if needed — same 8-way cap as step 1 §2; keeps aggregate token window manageable while still parallelizing typical stack sizes). Each subagent receives one skill's SKILL.md path and MUST:
 1. Read the SKILL.md file
 2. Extract the API surface
 3. ONLY return this compact JSON — no prose, no extra commentary:
@@ -78,7 +78,7 @@ For each library in an integration pair, delegate SKILL.md reading to a parallel
 
 **CRITICAL — these fields are inferred, not declared.** `protocols` and `data_formats` do not exist in any skill's `metadata.json`. Treat them as weak evidence from prose scanning only. When either list is used to justify compatibility in Check 2, the per-pair verdict MUST be capped at `Plausible` (see the schema's producer obligations — `src/shared/references/feasibility-report-schema.md`).
 
-**Schema validation (parent):** Each subagent response must contain the required keys (`skill_name`, `language`, `exports`). Reject responses missing required keys and exclude that skill from pair evaluation; HALT if more than **20%** (same failure-budget threshold as step-01 §2; see the justification there) of subagent calls return malformed JSON.
+**Schema validation (parent):** Each subagent response must contain the required keys (`skill_name`, `language`, `exports`). Reject responses missing required keys and exclude that skill from pair evaluation; HALT if more than **20%** (same failure-budget threshold as step 1 §2; see the justification there) of subagent calls return malformed JSON.
 
 **Parent collects all subagent JSON summaries.** Do not load full SKILL.md content into parent context.
 
@@ -88,7 +88,7 @@ For each library in an integration pair, delegate SKILL.md reading to a parallel
 - `stats.exports_documented` — export count
 - `confidence_tier` — extraction confidence level
 
-**mtime re-verification:** Re-stat each `metadata.json` and compare against the mtime captured in step-01. If any mtime moved during the run, abort any pair involving that skill with rationale "skill modified mid-run — re-run [VS]".
+**mtime re-verification:** Re-stat each `metadata.json` and compare against the mtime captured in step 1. If any mtime moved during the run, abort any pair involving that skill with rationale "skill modified mid-run — re-run [VS]".
 
 Store collected API surface summaries for cross-referencing.
 
@@ -163,8 +163,8 @@ For each integration pair `{library_a, library_b}`, apply the verification proto
 Write the **Integration Verdicts** section to `{outputFile}` (heading is fixed — consumers grep for `## Integration Verdicts`; the table header MUST be the canonical `| lib_a | lib_b | verdict | rationale |` per `{feasibilitySchemaRef}`; the skill-local display table with the extra Context/Source/Evidence columns can be rendered beneath it for human readers):
 - Emit the canonical `| lib_a | lib_b | verdict | rationale |` table first (verdict tokens MUST be one of `Verified`, `Plausible`, `Risky`, `Blocked` — case-sensitive)
 - Include the extended table with Context, Source, and Evidence columns below it
-- Include recommendations for Risky and Blocked pairs (Blocked recommendations MUST cite a named candidate per step-05 H6, or the explicit no-candidate notice)
-- Update frontmatter: append `'step-03-integrations'` to `stepsCompleted`; set `pairsVerified`, `pairsPlausible`, `pairsRisky`, `pairsBlocked` counts
+- Include recommendations for Risky and Blocked pairs (Blocked recommendations MUST cite a named candidate per step 5 H6, or the explicit no-candidate notice)
+- Update frontmatter: append `'integrations'` to `stepsCompleted`; set `pairsVerified`, `pairsPlausible`, `pairsRisky`, `pairsBlocked` counts
 - Pipe the updated full content through `python3 {atomicWriteScript} write --target {outputFile}` and again with `--target {outputFileLatest}`
 
 ### 7. Auto-Proceed to Next Step

package/src/skf-verify-stack/{steps-c/step-06-report.md → references/report.md}

@@ -1,11 +1,17 @@
 ---
-outputFile: '{forge_data_folder}/feasibility-report-{project_slug}-{timestamp}.md'
-outputFileLatest: '{forge_data_folder}/feasibility-report-{project_slug}-latest.md'
+# {outputFile} and {outputFileLatest} resolve from the activation-stored
+# {project_slug}, {timestamp}, and {outputFolderPath} variables (set in
+# SKILL.md On Activation §2 + §4) — same template as init.md frontmatter
+# so every stage sees the same path.
+outputFile: '{outputFolderPath}/feasibility-report-{project_slug}-{timestamp}.md'
+outputFileLatest: '{outputFolderPath}/feasibility-report-{project_slug}-latest.md'
 feasibilitySchemaRef: 'src/shared/references/feasibility-report-schema.md'
 atomicWriteScript: '{project-root}/src/shared/scripts/skf-atomic-write.py'
-nextStepFile: './step-07-health-check.md'
+nextStepFile: 'health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Render the user-facing summary in {document_output_language}. -->
+
 # Step 6: Present Report
 
 ## STEP GOAL:
@@ -19,17 +25,15 @@ Present the complete feasibility report to the user. Display the overall verdict
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Load Complete Report
 
 Read the entire `{outputFile}` to have all data available for presentation.
 
-Verify all expected sections are present in order per `{feasibilitySchemaRef}`: `## Executive Summary`, `## Coverage Analysis`, `## Integration Verdicts`, `## Recommendations`, `## Evidence Sources`. If any section is missing or out of order, HALT and report the schema violation — do not display partial results.
+Verify all expected sections are present in order per `{feasibilitySchemaRef}`: `## Executive Summary`, `## Coverage Analysis`, `## Integration Verdicts`, `## Recommendations`, `## Evidence Sources`. If any section is missing or out of order, HALT (exit code 5, `halt_reason: "schema-violation"`) and report the schema violation — do not display partial results. In headless, emit the error envelope per SKILL.md "Result Contract (Headless)" with `report_path: "{outputFile}"`, `overall_verdict: null`.
 
 **Extract metrics from `{outputFile}` frontmatter** (per shared schema in `{feasibilitySchemaRef}`): `skillsAnalyzed`, `coveragePercentage`, `pairsVerified` (as `verified_count`), `pairsPlausible` (as `plausible_count`), `pairsRisky` (as `risky_count`), `pairsBlocked` (as `blocked_count`), `requirementsFulfilled` (as `fulfilled_count`), `requirementsPartial` (as `partial_count`), `requirementsNotAddressed` (as `not_addressed_count`), `requirementsPass`, `overallVerdict`, and `recommendationCount`. Use these mapped display names in the summary table and next steps below.
 
-**Schema guard:** Verify `schemaVersion == "1.0"` in the frontmatter. If mismatched, HALT with "Report frontmatter schemaVersion `{value}` does not match producer schema `1.0` — report was corrupted between steps. Re-run [VS]." (Producer never proceeds past a schema mismatch.)
+**Schema guard:** Verify `schemaVersion == "1.0"` in the frontmatter. If mismatched, HALT (exit code 5, `halt_reason: "schema-violation"`) with "Report frontmatter schemaVersion `{value}` does not match producer schema `1.0` — report was corrupted between steps. Re-run [VS]." (Producer never proceeds past a schema mismatch.) In headless, emit the error envelope.
 
 ### 2. Present Summary
 
@@ -62,35 +66,7 @@ Verify all expected sections are present in order per `{feasibilitySchemaRef}`:
 
 ### 3. Present Detailed Findings
 
-Walk through each section briefly, focusing on items that need attention:
-
-"**Coverage Highlights:**
-{IF 100% coverage:}
-- All referenced technologies have a matching skill
-
-{IF any missing:}
-- **Missing:** {list of missing technology names}
-
-**Integration Verdicts:**
-{IF all Verified/Plausible:}
-- All integration pairs verified or plausible — no blockers
-
-{IF any Risky:}
-- **Risky:** {list of risky pairs with brief concern}
-
-{IF any Blocked:}
-- **Blocked:** {list of blocked pairs with brief incompatibility}
-
-{IF requirements pass completed:}
-**Requirements Gaps:**
-{IF all Fulfilled:}
-- All stated requirements addressed by the stack
-
-{IF any Partially Fulfilled:}
-- **Partially Fulfilled:** {list of partially covered requirements with gap description}
-
-{IF any Not Addressed:}
-- **Not Addressed:** {list of unaddressed requirements}"
+Walk through the highlights — coverage gaps, risky/blocked integrations, and partial/unaddressed requirements (when a PRD pass ran). Cite specific items by name; cap at the top ~5 per category to keep the summary scannable. The full detail is in `{outputFile}` for the user to inspect via the [R] Review menu (§5).
 
 ### 4. Present Next Steps
 
@@ -124,9 +100,17 @@ Based on the overall verdict, present the appropriate recommendation:
 
 Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{forge_data_folder}/verify-stack-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_data_folder}/verify-stack-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include the feasibility report path (both `{outputFile}` and `{outputFileLatest}`) in `outputs`; include `overallVerdict` (`FEASIBLE` / `CONDITIONALLY_FEASIBLE` / `NOT_FEASIBLE`), `coveragePercentage`, and `recommendationCount` in `summary` — use the case-sensitive schema tokens.
 
-Write both JSON files through `python3 {atomicWriteScript} write --target ...` to avoid partial-write corruption.
+Write both JSON files through `python3 {atomicWriteScript} write --target ...` to avoid partial-write corruption. On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`) and emit the error envelope.
+
+When `{headless_mode}` is true, also emit the single-line envelope on **stdout** before chaining to step 7 (matches the SKILL.md "Result Contract (Headless)" shape):
 
-**Result-contract ordering:** The result contract is written exactly once on the first entry to step-06 (the `[X] Exit verification` path). Re-walks of the report via the `[R] Review full report` menu option do NOT regenerate it — the contract captures the run, not the presentation loop. If the user selects `[R]` repeatedly before exiting, the single on-disk contract written on first entry remains authoritative.
+```
+SKF_VERIFY_STACK_RESULT_JSON: {"status":"success","report_path":"{outputFile}","report_latest_path":"{outputFileLatest}","overall_verdict":"{overallVerdict}","coverage_percentage":{coveragePercentage},"recommendation_count":{recommendationCount},"exit_code":0,"halt_reason":null}
+```
+
+`{overallVerdict}` uses the schema tokens (`FEASIBLE` / `CONDITIONALLY_FEASIBLE` / `NOT_FEASIBLE`).
+
+**Result-contract ordering:** The result contract is written exactly once on the first entry to step 6 (the `[X] Exit verification` path). Re-walks of the report via the `[R] Review full report` menu option do NOT regenerate it — the contract captures the run, not the presentation loop. If the user selects `[R]` repeatedly before exiting, the single on-disk contract written on first entry remains authoritative.
 
 ### 5. Present Menu
 
@@ -150,7 +134,4 @@ Re-run **[VS] Verify Stack** anytime after making changes to your skills or arch
 - R may be selected multiple times — always walk through the full report
 - X triggers the health check, which is the true workflow exit
 
-## CRITICAL STEP COMPLETION NOTE
-
-When the user selects X, this step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md`. After the health check completes, the verify-stack workflow is fully done. The feasibility report at `{outputFile}` (and its stable `-latest.md` copy) contains the full analysis under the fixed headings: Executive Summary, Coverage Analysis, Integration Verdicts, Recommendations, Evidence Sources.
 

package/src/skf-verify-stack/{steps-c/step-04-requirements.md → references/requirements.md}

@@ -1,11 +1,13 @@
 ---
-nextStepFile: './step-05-synthesize.md'
+nextStepFile: 'synthesize.md'
 feasibilitySchemaRef: 'src/shared/references/feasibility-report-schema.md'
 atomicWriteScript: '{project-root}/src/shared/scripts/skf-atomic-write.py'
-outputFile: '{forge_data_folder}/feasibility-report-{project_slug}-{timestamp}.md'
-outputFileLatest: '{forge_data_folder}/feasibility-report-{project_slug}-latest.md'
+outputFile: '{outputFolderPath}/feasibility-report-{project_slug}-{timestamp}.md'
+outputFileLatest: '{outputFolderPath}/feasibility-report-{project_slug}-latest.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Append the Requirements Coverage section to the report in {document_output_language}. -->
+
 # Step 4: Requirements Coverage
 
 ## STEP GOAL:
@@ -20,8 +22,6 @@ If a PRD or vision document was provided in Step 01, verify that the combined ca
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Check PRD Availability
 
 **Read `prdAvailable` from `{outputFile}` frontmatter (set in Step 01). If `prdAvailable` is false (no PRD/vision document was provided):**
@@ -34,7 +34,7 @@ To include this pass, re-run **[VS]** with a PRD or vision document path.
 
 **Proceeding to synthesis...**"
 
-Update `{outputFile}` frontmatter: append `'step-04-requirements'` to `stepsCompleted`; set `requirementsPass: "skipped"`. Pipe the updated content through `python3 {atomicWriteScript} write --target {outputFile}` and again with `--target {outputFileLatest}`.
+Update `{outputFile}` frontmatter: append `'requirements'` to `stepsCompleted`; set `requirementsPass: "skipped"`. Pipe the updated content through `python3 {atomicWriteScript} write --target {outputFile}` and again with `--target {outputFileLatest}`.
 
 Load, read the full file and then execute `{nextStepFile}`. **STOP HERE — do not execute sections 2-6.**
 
@@ -102,7 +102,7 @@ For each requirement, evaluate whether the combined capabilities of the generate
 Write the Requirements Coverage content under the `## Recommendations` section (or as a clearly-titled subsection preceding Recommendations — the shared schema's fixed top-level headings are Executive Summary, Coverage Analysis, Integration Verdicts, Recommendations, Evidence Sources; requirements detail lives under Recommendations):
 - Include the full requirements coverage table
 - Include recommendations for Not Addressed and Partially Fulfilled items
-- Update frontmatter: append `'step-04-requirements'` to `stepsCompleted`
+- Update frontmatter: append `'requirements'` to `stepsCompleted`
 - Set `requirementsPass: "completed"`
 - Set `requirementsFulfilled`, `requirementsPartial`, `requirementsNotAddressed` counts
 - Pipe the updated full content through `python3 {atomicWriteScript} write --target {outputFile}` and again with `--target {outputFileLatest}`

package/src/skf-verify-stack/{steps-c/step-05-synthesize.md → references/synthesize.md}

@@ -1,11 +1,13 @@
 ---
-nextStepFile: './step-06-report.md'
+nextStepFile: 'report.md'
 feasibilitySchemaRef: 'src/shared/references/feasibility-report-schema.md'
 atomicWriteScript: '{project-root}/src/shared/scripts/skf-atomic-write.py'
-outputFile: '{forge_data_folder}/feasibility-report-{project_slug}-{timestamp}.md'
-outputFileLatest: '{forge_data_folder}/feasibility-report-{project_slug}-latest.md'
+outputFile: '{outputFolderPath}/feasibility-report-{project_slug}-{timestamp}.md'
+outputFileLatest: '{outputFolderPath}/feasibility-report-{project_slug}-latest.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Append the Executive Summary, synthesized verdict, and Recommendations to the report in {document_output_language}. -->
+
 # Step 5: Synthesize Verdict
 
 ## STEP GOAL:
@@ -19,8 +21,6 @@ Calculate the overall feasibility verdict based on all three analysis passes, ge
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Calculate Overall Verdict
 
 **Zero-coverage short-circuit (evaluate before anything else):** Read `coveragePercentage` from `{outputFile}` frontmatter. If `coveragePercentage == 0`, force `overallVerdict: NOT_FEASIBLE` with rationale "no coverage — analysis vacuous: zero generated skills match the architecture's referenced technologies, so integration and requirements verdicts cannot produce meaningful evidence." Skip the remainder of the verdict ladder; proceed directly to section 2 to generate recommendations for the Missing skills surfaced by Step 02.
@@ -47,7 +47,7 @@ If ANY of the following apply, the verdict is `CONDITIONALLY_FEASIBLE`. Include
 - Rationale: {IF requirements pass completed:} the stack can support the architecture as described — all requirements fully fulfilled, every integration pair has a literal cross-reference. {IF requirements pass was skipped:} the stack can support the architecture as described — requirements were not evaluated (no PRD provided)
 
 **Post-verdict: Zero integration pairs guard (apply after ANY verdict):**
-If zero integration pairs were extracted (all four integration counts are 0), fire the guard whenever the user continued past the step-02 `[C] Continue anyway` prompt (i.e., any `[C]` continuation from 0% coverage or any other zero-state) — regardless of how many technologies the architecture document references:
+If zero integration pairs were extracted (all four integration counts are 0), fire the guard whenever the user continued past the step 2 `[C] Continue anyway` prompt (i.e., any `[C]` continuation from 0% coverage or any other zero-state) — regardless of how many technologies the architecture document references:
 - If the verdict was `FEASIBLE`, override to `CONDITIONALLY_FEASIBLE`
 - Regardless of verdict, append this note to the rationale: "No integration claims were found in the architecture document prose. Manual review recommended to confirm that technology relationships are not documented exclusively in diagrams or implied without explicit co-mention."
 
@@ -103,7 +103,7 @@ Assemble the following for the report:
 
 **Overall verdict** with rationale citing the decision logic.
 
-**Recommendation list** ordered by priority (count total recommendations as `recommendationCount` — persist this count to `{outputFile}` frontmatter for use in step-06):
+**Recommendation list** ordered by priority (count total recommendations as `recommendationCount` — persist this count to `{outputFile}` frontmatter for use in step 6):
 1. Blocked integrations (if any)
 2. Missing skills
 3. Risky integrations
@@ -128,7 +128,7 @@ Write the **Recommendations** and **Evidence Sources** sections to `{outputFile}
 - Include suggested next workflow at the end of `## Recommendations`
 - Populate `## Evidence Sources` with per-skill citations (SKILL.md path, `metadata_schema_version`, `confidence_tier`, stack manifest if any) and architecture/PRD doc paths
 - Update frontmatter (shared-schema keys):
-  - Append `'step-05-synthesize'` to `stepsCompleted`
+  - Append `'synthesize'` to `stepsCompleted`
   - Set `overallVerdict` to one of `FEASIBLE`, `CONDITIONALLY_FEASIBLE`, `NOT_FEASIBLE` (case-sensitive, underscores — NOT spaces)
   - Set `recommendationCount` to the total number of recommendations
   - If delta was computed (section 3), set `deltaImproved`, `deltaRegressed`, `deltaNew`, `deltaUnchanged`

package/tools/validate-docs-drift.js

@@ -90,7 +90,7 @@ function resolveOmsPath(anchors) {
 }
 
 // Accept either a full SHA match or a short-SHA prefix match, per
-// src/skf-update-skill/steps-c/step-03-re-extract.md:36 — the pinned commit
+// src/skf-update-skill/references/re-extract.md:36 — the pinned commit
 // is often stored as an 8-char short hash. Both anchors and metadata are
 // lowercased before comparison; blank / null values never match.
 function commitsMatch(anchorCommit, metadataCommit) {

package/src/skf-refine-architecture/steps-c/step-01-init.md

@@ -1,136 +0,0 @@
----
-nextStepFile: './step-02-gap-analysis.md'
-refinementRulesData: 'references/refinement-rules.md'
----
-
-# Step 1: Initialize Refinement
-
-## STEP GOAL:
-
-Load the architecture document (required), scan the skills folder to build a skill inventory with metadata, load the optional VS feasibility report for context, validate that all inputs exist and meet minimum requirements, and present an initialization summary before auto-proceeding.
-
-## Rules
-
-- Focus only on loading inputs, scanning skills, and validating prerequisites — do not perform analysis
-- Present a clear initialization summary so downstream steps have validated inputs
-
-## MANDATORY SEQUENCE
-
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
-### 1. Accept Input Documents
-
-"**Refine Architecture — Evidence-Backed Refinement**
-
-Please provide the following:
-1. **Architecture document path** (REQUIRED) — your project's architecture doc to refine
-2. **VS feasibility report path** (OPTIONAL) — from a previous [VS] Verify Stack run, for additional context"
-
-Wait for user input. Store the validated architecture document path as `architecture_doc`. **GATE [default: use args]** — If `{headless_mode}` and architecture doc path was provided as argument: use that path and auto-proceed, log: "headless: using provided architecture path".
-
-**Validate architecture document:**
-- Confirm the file exists and is readable
-- If missing or unreadable: "Architecture document not found at `{path}`. Provide a valid path."
-- HALT until a valid architecture document is provided
-
-**Validate VS report (if provided):**
-- Confirm the file exists and is readable
-- If missing at user-provided path: attempt auto-probe (below) before giving up
-- Store VS report availability as `vs_report_available: true|false` and `vs_report_path`
-
-### 2. Scan Skills Folder
-
-Read the `{skills_output_folder}` directory. Skills use a version-nested directory structure (see `knowledge/version-paths.md`).
-
-**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
-- `language` — primary language
-- `confidence_tier` — Quick, Forge, Forge+, or Deep
-- `exports_documented` — read from `stats.exports_documented` in metadata.json (count of documented exports)
-- `source_repo` or `source_root` — original source repository
-
-**Build a skill inventory** as an internal list of all loaded skills with the fields above.
-
-**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
-
-### 3. Validate Minimum Requirements
-
-**Check skill count:**
-- At least 1 valid skill must exist
-- If no skills found: "**Cannot proceed.** No skills found in `{skills_output_folder}`. Generate skills with [CS] Create Skill or [QS] Quick Skill, then re-run [RA]."
-- HALT workflow
-- If exactly 1 valid skill found: "⚠️ Proceeding with 1 skill. Note: gap analysis will find no gaps — pairwise analysis requires at least 2 skills. Step 02 will still execute and issue an appropriate notice. Issue detection and improvement detection will proceed normally."
-
-**Check output_folder:**
-- Verify `output_folder` was resolved from config.yaml and is non-empty
-- If undefined or empty: "**Cannot proceed.** `output_folder` is not configured in config.yaml. Add an `output_folder` path and re-run [RA]."
-- HALT workflow
-- Verify the `output_folder` directory exists. If it does not exist, create it. HALT with error if creation fails.
-
-**Check forge_data_folder:**
-- Verify `forge_data_folder` was resolved from config.yaml and is non-empty
-- If undefined or empty: "**Cannot proceed.** `forge_data_folder` is not configured in config.yaml. Add a `forge_data_folder` path to your config.yaml and re-run [RA]."
-- HALT workflow
-- Verify the `forge_data_folder` directory exists. If it does not exist, attempt to create it. If creation fails: "**Cannot proceed.** `forge_data_folder` at `{forge_data_folder}` does not exist and could not be created. Create the directory manually and re-run [RA]."
-- HALT workflow on creation failure
-
-**Check architecture document:**
-- Confirm it was loaded successfully in section 1
-- If not: HALT with error (should not reach here if section 1 validation passed)
-
-### 3b. Auto-Probe VS Report
-
-**Auto-probe VS report (if not provided by user in section 1, OR if user-provided path was invalid):**
-- Only attempt if `forge_data_folder` is non-empty and the directory exists (validated above); otherwise skip probe and set `vs_report_available: false`
-- Check for `{forge_data_folder}/feasibility-report-{project_name}.md`
-- If found: "Auto-discovered VS report at `{path}`. Loading for additional context."
-- Store `vs_report_available: true` and `vs_report_path`
-- If not found: `vs_report_available: false` — "Proceeding without VS report — issue detection will rely on skill data only."
-
-### 3c. Reset RA State File
-
-Create (or overwrite) `{forge_data_folder}/ra-state-{project_name}.md` with a fresh header:
-
-```markdown
-<!-- RA state for {project_name} — generated {current_date} -->
-```
-
-This ensures steps 02-04 append to a clean slate and context recovery in step-05 never loads stale findings from a prior run.
-
-### 4. Load Refinement Rules
-
-Load `{refinementRulesData}` for reference by downstream steps.
-
-Extract: gap detection rules, issue detection rules, improvement detection rules, citation format, and preservation rules.
-
-### 5. Display Initialization Summary
-
-"**Architecture Refinement Initialized**
-
-| Field | Value |
-|-------|-------|
-| **Architecture Doc** | {architecture_doc} |
-| **VS Report** | {vs_report_path or 'Not provided — issue detection will use skill data only'} |
-| **Skills Loaded** | {skill_count} |
-
-**Skill Inventory:**
-
-| Skill | Language | Tier | Exports |
-|-------|----------|------|---------|
-| {skill_name} | {language} | {confidence_tier} | {exports_documented} |
-
-**Proceeding to gap analysis...**"
-
-### 6. Auto-Proceed to Next Step
-
-Load, read the full file and then execute `{nextStepFile}`.
-

package/src/skf-rename-skill/steps-c/step-04-health-check.md

@@ -1,22 +0,0 @@
----
-# `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 4: Workflow Health Check
-
-## STEP GOAL:
-
-Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of rename-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-03
-- 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.