bmad-module-skill-forge 1.4.1 → 1.5.1

package/src/skf-quick-skill/{steps-c/step-03-quick-extract.md → references/quick-extract.md}

@@ -1,13 +1,13 @@
 ---
-nextStepFile: './step-04-compile.md'
+nextStepFile: 'compile.md'
 publicApiExtractorProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-extract-public-api.py'
   - '{project-root}/src/shared/scripts/skf-extract-public-api.py'
 ---
 
-# Step 3: Quick Extract
+<!-- Config: communicate in {communication_language}. -->
 
-Communicate with the user in `{communication_language}`.
+# Step 3: Quick Extract
 
 ## STEP GOAL:
 
@@ -21,7 +21,7 @@ To read the resolved GitHub repository source and extract the public API surface
 
 ## MANDATORY SEQUENCE
 
-**Ref-aware source reading:** When `source_ref` is set from tag resolution (see step-01), append `?ref={source_ref}` to all GitHub API content and tree requests (e.g., `gh api repos/{owner}/{repo}/contents/{path}?ref={source_ref}`) to read from the tagged version. When using web browsing, use the tagged URL format (e.g., `github.com/{owner}/{repo}/blob/{source_ref}/{path}`). This ensures extraction reads from the same source version resolved during tag resolution.
+**Ref-aware source reading:** When `source_ref` is set from tag resolution (see step 1), append `?ref={source_ref}` to all GitHub API content and tree requests (e.g., `gh api repos/{owner}/{repo}/contents/{path}?ref={source_ref}`) to read from the tagged version. When using web browsing, use the tagged URL format (e.g., `github.com/{owner}/{repo}/blob/{source_ref}/{path}`). This ensures extraction reads from the same source version resolved during tag resolution.
 
 **Parallel-fetch directive:** §1 (README), §2 (manifest), and §3 (entry-point exports) read independent files from the same `?ref={source_ref}` and are safe to issue as one batched tool-call message rather than three sequential round trips. For multi-module Maven (`<modules>`) and multi-project Gradle (`include(...)`) builds, also fetch all submodule `pom.xml` / `build.gradle[.kts]` files in parallel rather than serially per module — N module fetches collapse to O(1) wall-clock time.
 
@@ -144,7 +144,7 @@ Common causes:
 
 Select: [R] Retry with new hints · [P] Proceed anyway (low-confidence skill) · [A] Abort"
 
-- **IF R** — prompt for new `scope_hint` ("New scope hint (e.g. `src/server/`):") and optional new `language_hint` ("New language hint (or empty to keep `{language}`):"). Update the extraction context with the new hints, then **re-execute step-03 from §1** with the new values. Discards the prior empty inventory.
+- **IF R** — prompt for new `scope_hint` ("New scope hint (e.g. `src/server/`):") and optional new `language_hint` ("New language hint (or empty to keep `{language}`):"). Update the extraction context with the new hints, then **re-execute step 3 from §1** with the new values. Discards the prior empty inventory.
 - **IF P** — log "user accepted zero-exports outcome" and proceed to §5. The compiled skill will be README-content-only with confidence `low`. Record `zero_exports_rescue: "user-accepted"` in the inventory so the result contract summary surfaces it.
 - **IF A** — HARD HALT with **exit code 3 (resolution-failure)**: "Aborted. Run `/skf-create-skill` from a brief if you want a guided extraction with provenance tracking." Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "quick-extract"`, `error.code: "resolution-failure"`, `error.details: {exports_found: 0, description_empty: true, language: "{language}", scope: "{scope_hint or 'entire repo'}"}`, `skill_package: null`).
 

package/src/skf-quick-skill/references/registry-resolution.md

@@ -1,3 +1,5 @@
+<!-- Config: communicate in {communication_language}. -->
+
 # Registry Resolution Patterns
 
 ## Package-to-Repo Resolution

package/src/skf-quick-skill/{steps-c/step-01-resolve-target.md → references/resolve-target.md}

@@ -1,14 +1,14 @@
 ---
-nextStepFile: './step-02-ecosystem-check.md'
+nextStepFile: 'ecosystem-check.md'
 registryResolutionData: 'references/registry-resolution.md'
 packageResolverProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-resolve-package.py'
   - '{project-root}/src/shared/scripts/skf-resolve-package.py'
 ---
 
-# Step 1: Resolve Target
+<!-- Config: communicate in {communication_language}. -->
 
-Communicate with the user in `{communication_language}`.
+# Step 1: Resolve Target
 
 ## STEP GOAL:
 
@@ -23,7 +23,7 @@ To accept a GitHub URL or package name from the user, resolve it to a GitHub rep
 
 ### 1. Accept User Input
 
-**Batch mode:** if `--batch` is active (see SKILL.md "Batch Mode"), the current target was already resolved by On Activation step 4 from the next batch line and placed into the workflow context as `target`, with optional `language_hint` and `scope_hint` per-line modifiers. Skip the prompt below — emit `{"batch":<n>,"target":"<target>","status":"start"}` to stderr and proceed directly to §1b with the batch-supplied values.
+**Batch mode:** if `--batch` is active (see SKILL.md "Batch Mode"), the current target was already resolved by On Activation step 5 from the next batch line and placed into the workflow context as `target`, with optional `language_hint` and `scope_hint` per-line modifiers. Skip the prompt below — emit `{"batch":<n>,"target":"<target>","status":"start"}` to stderr and proceed directly to §1b with the batch-supplied values.
 
 **Single-target mode** (default):
 
@@ -37,9 +37,13 @@ Examples: `cocoindex`, `@tanstack/query`, `https://github.com/tursodatabase/limb
 
 **Optional:**
 - **Language hint:** (if the repo is multi-language)
-- **Scope hint:** (specific directories to focus on)"
+- **Scope hint:** (specific directories to focus on)
+
+Or type `cancel` / `exit` / `:q` / `[X]` to leave without writing anything."
+
+Wait for user input. **Cancel branch** — if the user types `cancel`, `exit`, `:q`, `[X]`, or selects `[X] Cancel and exit`, display `"Cancelled — no files were written."` and HARD HALT with **exit code 6 (user-cancelled)** per the SKILL.md exit-code map. Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "resolve-target"`, `error.code: "user-cancelled"`, `skill_package: null`). Cancellation here is non-destructive — no files have been written yet.
 
-Wait for user input. **GATE [default: use args]** — If `{headless_mode}` and a target (URL or package name) was provided as argument: use it as the target input and auto-proceed, log: "headless: using provided target". If no target provided in headless mode, HALT with: "headless mode requires a target argument."
+**GATE [default: use args]** — If `{headless_mode}` and a target (URL or package name) was provided as argument: use it as the target input and auto-proceed, log: "headless: using provided target". If no target provided in headless mode, HALT with: "headless mode requires a target argument."
 
 ### 1b. Parse Version Targeting
 
@@ -107,9 +111,9 @@ In interactive mode, wait for corrected input and loop back to step 2. In headle
 
 ### 3a. Verify Target Version Tag (when applicable)
 
-Skip this section if `target_version` is null (auto-detect path — version comes from manifest read in step-03).
+Skip this section if `target_version` is null (auto-detect path — version comes from manifest read in step 3).
 
-When the user explicitly supplied `@version` in §1b, verify the tag exists in the resolved repo before extraction. Otherwise step-03 silently reads from the default branch while metadata records the requested version — a quiet provenance bug where the SKILL.md claims version 0.5.0 but the exports actually came from main.
+When the user explicitly supplied `@version` in §1b, verify the tag exists in the resolved repo before extraction. Otherwise step 3 silently reads from the default branch while metadata records the requested version — a quiet provenance bug where the SKILL.md claims version 0.5.0 but the exports actually came from main.
 
 Probe both with-and-without v-prefix (the v-prefix is conventional but not universal across ecosystems):
 
@@ -148,13 +152,13 @@ Determine primary language from:
 
    Collect every match into `detected_languages`.
 
-3. **Single-language case** (`len(detected_languages) <= 1`) — set `language` to the detected value (or HALT in step-01 §3 if zero matches).
+3. **Single-language case** (`len(detected_languages) <= 1`) — set `language` to the detected value (or HALT in step 1 §3 if zero matches).
 
 4. **Multi-language case** (`len(detected_languages) > 1`) — surface the choice rather than silently picking the first match. Multi-language repos (Python + JS bindings, or monorepos with mixed manifests) otherwise produce a skill for whichever manifest probe hits first, with no signal that the user might have wanted the other one.
 
    "**`{repo_name}` has manifests for multiple languages:** {detected_languages}.
 
-   Primary guess: **{first_match}** (manifest-priority order). If you wanted a different language, abort and re-run with `--language-hint <lang>` or with the optional language hint at step-01 §1.
+   Primary guess: **{first_match}** (manifest-priority order). If you wanted a different language, abort and re-run with `--language-hint <lang>` or with the optional language hint at step 1 §1.
 
    Select: [C] Continue with `{first_match}` · [A] Abort"
 

package/src/skf-quick-skill/{steps-c/step-05-write-and-validate.md → references/write-and-validate.md}

@@ -1,5 +1,5 @@
 ---
-nextStepFile: './step-06-finalize.md'
+nextStepFile: 'finalize.md'
 frontmatterValidatorProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-validate-frontmatter.py'
   - '{project-root}/src/shared/scripts/skf-validate-frontmatter.py'
@@ -8,13 +8,13 @@ outputValidatorProbeOrder:
   - '{project-root}/src/shared/scripts/skf-validate-output.py'
 ---
 
-# Step 5: Write & Validate
+<!-- Config: communicate in {communication_language}. Generated SKILL.md text in {document_output_language}. -->
 
-Communicate with the user in `{communication_language}`. Validation reports are user-facing — render their narrative content in `{document_output_language}`.
+# Step 5: Write & Validate
 
 ## STEP GOAL:
 
-To write the compiled SKILL.md, context-snippet.md, and metadata.json to the versioned skill package, then validate them on disk against the agentskills.io specification at community tier. Writing happens here (before step-06 finalization) because `skill-check` is a file-based CLI — it reads artifacts from disk — so the files must exist before validation runs. Report any gaps or issues. Validation is advisory — issues are reported but do not block the workflow.
+To write the compiled SKILL.md, context-snippet.md, and metadata.json to the versioned skill package, then validate them on disk against the agentskills.io specification at community tier. Writing happens here (before step 6 finalization) because `skill-check` is a file-based CLI — it reads artifacts from disk — so the files must exist before validation runs. Report any gaps or issues. Validation is advisory — issues are reported but do not block the workflow.
 
 ## Rules
 

package/src/skf-refine-architecture/SKILL.md

@@ -9,6 +9,14 @@ description: Improve architecture doc using verified skill data and VS feasibili
 
 Takes an original architecture document + generated skills + optional VS feasibility report, and produces a refined architecture with gaps filled, issues flagged, and improvements suggested — all backed by specific API evidence from the generated skills. This workflow enhances the original architecture — it never deletes original content, only adds annotations, subsections, and suggestions.
 
+## Conventions
+
+- Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
 ## Role
 
 You are an architecture refinement analyst operating in Ferris Architect mode. You bring expertise in API surface analysis, integration gap detection, and evidence-backed architecture improvement, while the user brings their architecture vision and generated skills. Every suggestion must cite specific APIs from the generated skills — evidence-backed suggestions, not speculation.
@@ -18,40 +26,102 @@ You are an architecture refinement analyst operating in Ferris Architect mode. Y
 These rules apply to every step in this workflow:
 
 - Never speculate — every gap, issue, or improvement must cite specific APIs, types, or function signatures 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}`
+- At any interactive prompt, the inputs `cancel`, `exit`, `[X]`, `q`, or `:q` exit cleanly with exit code 6 (`halt_reason: "user-cancelled"`)
 - 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 | Gap Analysis | steps-c/step-02-gap-analysis.md | Yes |
-| 3 | Issue Detection | steps-c/step-03-issue-detection.md | Yes |
-| 4 | Improvements | steps-c/step-04-improvements.md | Yes |
-| 5 | Compile Refined Architecture | steps-c/step-05-compile.md | No (review) |
-| 6 | Report | steps-c/step-06-report.md | Yes |
-| 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
+| 1 | Initialize & Load Inputs | references/init.md | No (confirm) |
+| 2 | Gap Analysis | references/gap-analysis.md | Yes |
+| 3 | Issue Detection | references/issue-detection.md | Yes |
+| 4 | Improvements | references/improvements.md | Yes |
+| 5 | Compile Refined Architecture | references/compile.md | No (review) |
+| 6 | Report | references/report.md | Yes |
+| 7 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | architecture_doc_path [required] |
-| **Gates** | step-01: Input Gate [use args] | step-05: Review Gate [C] |
-| **Outputs** | refined-architecture-{project_name}.md |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **Inputs** | architecture_doc_path [required], vs_report_path [optional] |
+| **Flags** | `--headless` / `-H` (auto-resolve all gates); `--architecture-doc <path>` (skip step 1 prompt for the required input); `--vs-report-path <path>` (skip step 1 prompt for the optional VS report) |
+| **Gates** | step 1: Input Gate [use args] | step 5: Review Gate [C] |
+| **Outputs** | `refined-architecture-{project_name}.md` at `{outputFolderPath}`, plus `refine-architecture-result-{timestamp}.json` and `refine-architecture-result-latest.json` |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. Per-flag args (`--architecture-doc`, `--vs-report-path`) consumed at the gates that would otherwise prompt. |
+| **Exit codes** | See "Exit Codes" below |
+
+## Exit Codes
+
+Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
+
+| Code | Meaning              | Raised by                                                                                    |
+| ---- | -------------------- | -------------------------------------------------------------------------------------------- |
+| 0    | success              | step 7 (terminal)                                                                           |
+| 2    | input-missing / input-invalid | step 1 §1 (headless missing `architecture-doc` arg, or invalid path) → `input-missing`; non-existent file → `input-invalid` |
+| 3    | resolution-failure   | step 1 §3 (`output_folder` or `forge_data_folder` unconfigured) |
+| 4    | write-failure        | On-Activation §3 pre-flight write probe; step 1 §3c (RA state file write failed); step 5 §6 (refined-architecture write failed); step 6 §3 (result-contract write failed) |
+| 5    | state-conflict       | step 1 §3 (no skills found — refinement requires ≥1 skill) |
+| 6    | user-cancelled       | step 1 §1 prompt cancelled; any prompt that accepted `cancel`/`exit`/`:q`; step 5 review gate `[X]` |
+| 7    | inventory-unreliable | step 1 §2 (>20% skill-inventory warnings exceed budget) |
+
+## Result Contract (Headless)
+
+When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
+
+```
+SKF_REFINE_ARCHITECTURE_RESULT_JSON: {"status":"success|error","refined_path":"…|null","gap_count":0,"issue_count":0,"improvement_count":0,"exit_code":0,"halt_reason":null}
+```
+
+`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"insufficient-skills"`, `"output-folder-unconfigured"`, `"forge-folder-unconfigured"`, `"inventory-unreliable"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above.
 
 ## On Activation
 
 1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
    - `project_name`, `user_name`, `communication_language`, `document_output_language`
-   - `skills_output_folder`, `forge_data_folder`, `output_folder`
+   - `skills_output_folder`, `forge_data_folder`, `output_folder`, `sidecar_path`
+
+2. **Compute run-scoped variables:**
+   - `timestamp` ← UTC `YYYYMMDD-HHmmss` captured at activation time. Fixed for the entire workflow run; report.md reuses this when writing the result contract.
+
+3. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
+
+4. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-root} --key workflow
+   ```
+
+   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+
+   - `{skill-root}/customize.toml` — bundled defaults
+   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
+   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+
+   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+
+   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each scalar, if the merged value is empty or absent, use the bundled default:
+
+   - `{refinementRulesPath}` ← `workflow.refinement_rules_path` if non-empty, else `references/refinement-rules.md`
+   - `{outputFolderPath}` ← `workflow.output_folder_path` if non-empty, else `{output_folder}`
+
+   Stash both as workflow-context variables. Stage files reference them directly — no conditional at the usage site.
+
+5. **Pre-flight write probe.** Verify both `{outputFolderPath}` and `{forge_data_folder}` are writable. A read-only mount, full disk, or permissions-denied path otherwise only surfaces at init.md §3c's RA state file write — by then the user has already gone through input prompts:
+
+   ```bash
+   for dir in "{outputFolderPath}" "{forge_data_folder}"; do
+     mkdir -p "$dir" && \
+       printf 'probe' > "$dir/.skf-write-probe" && \
+       rm "$dir/.skf-write-probe"
+   done
+   ```
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+   On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`). In headless mode, emit the error envelope per **Result Contract (Headless)** with `refined_path: null`.
 
-3. Load, read the full file, and then execute `./steps-c/step-01-init.md` to begin the workflow.
+6. Load, read the full file, and then execute `references/init.md` to begin the workflow.

package/src/skf-refine-architecture/customize.toml

@@ -0,0 +1,49 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-refine-architecture.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (uv probe, config load).
+# Overrides append. Use for org-wide pre-flight checks (auth, network,
+# compliance) that must precede architecture refinement work.
+
+activation_steps_prepend = []
+
+# Steps to run after activation but before the first stage executes.
+# Overrides append. Use for context loads or banner customization that
+# should run once activation completes successfully.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (refinement standards, evidence-citation rules, house-style preservation
+# guardrails). Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Refinements must cite specific API signatures, never speculate."
+#   - a file reference prefixed with `file:`, e.g.
+#     "file:{project-root}/docs/refine-policy.md" (globs supported; file
+#     contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# --- Optional asset overrides ---
+#
+# Lift the canonical refinement-rules path so orgs can substitute house-style
+# rules (e.g. add domain-specific gap categories) without forking the skill.
+# Empty string = use the bundled default.
+
+refinement_rules_path = ""
+
+# Override the destination directory for the refined architecture document.
+# Empty = use {output_folder} from config.yaml. Useful for orgs that want
+# refined-architecture artifacts to land under a curated docs tree.
+
+output_folder_path = ""

package/src/skf-refine-architecture/{steps-c/step-05-compile.md → references/compile.md}

@@ -1,8 +1,10 @@
 ---
-nextStepFile: './step-06-report.md'
-outputFile: '{output_folder}/refined-architecture-{project_name}.md'
+nextStepFile: 'report.md'
+outputFile: '{outputFolderPath}/refined-architecture-{project_name}.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Compile the refined architecture document in {document_output_language}. -->
+
 # Step 5: Compile Refined Architecture
 
 ## STEP GOAL:
@@ -17,8 +19,6 @@ Produce the refined architecture document by starting with the original as a bas
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Prepare the Original as Base
 
 Load the complete original architecture document.

package/src/skf-refine-architecture/{steps-c/step-02-gap-analysis.md → references/gap-analysis.md}

@@ -1,8 +1,10 @@
 ---
-nextStepFile: './step-03-issue-detection.md'
-refinementRulesData: 'references/refinement-rules.md'
+nextStepFile: 'issue-detection.md'
+refinementRulesData: '{refinementRulesPath}'
 ---
 
+<!-- Config: communicate in {communication_language}. Append gap-analysis findings to the RA state file in {document_output_language}. -->
+
 # Step 2: Gap Analysis
 
 ## STEP GOAL:
@@ -16,8 +18,6 @@ Find undocumented integration paths — library pairs that have compatible APIs
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Reference Refinement Rules
 
 Use the refinement rules loaded in Step 01 from `{refinementRulesData}`. If not available in context, reload from `{refinementRulesData}`.
@@ -129,7 +129,7 @@ Suggestion: {proposed architecture section content}
 
 **Proceeding to issue detection (still produces value with 1 skill)...**"
 
-Store all gap findings as workflow state for Step 05. To ensure durability across long runs, also append a `<!-- [RA-GAPS] ... -->` comment block to `{forge_data_folder}/ra-state-{project_name}.md` containing the **complete formatted gap findings** (full citation blocks with evidence and suggestions, not just counts) — Step 05 can read this back if context degrades. **Do NOT write to `{output_folder}/refined-architecture-{project_name}.md` — that file is created only in step-05.**
+Store all gap findings as workflow state for Step 05. To ensure durability across long runs, also append a `<!-- [RA-GAPS] ... -->` comment block to `{forge_data_folder}/ra-state-{project_name}.md` containing the **complete formatted gap findings** (full citation blocks with evidence and suggestions, not just counts) — Step 05 can read this back if context degrades. **Do NOT write to `{output_folder}/refined-architecture-{project_name}.md` — that file is created only in step 5.**
 
 ### 7. Auto-Proceed to Next Step
 

package/src/skf-refine-architecture/{steps-c/step-07-health-check.md → references/health-check.md}

@@ -1,10 +1,12 @@
 ---
-# `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
-# to this step file.
+# Note: `shared/health-check.md` resolves relative to the SKF module root
+# ({project-root}/_bmad/skf/ when installed, {project-root}/src/ during
+# development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 7: Workflow Health Check
 
 ## STEP GOAL:
@@ -13,7 +15,7 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 
 ## Rules
 
-- No user-facing reports, file writes, or result contracts in this step — those belong in step-06
+- No user-facing reports, file writes, or result contracts in this step — those belong in step 6
 - Delegate directly to `{nextStepFile}` with no additional commentary
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`
 

package/src/skf-refine-architecture/{steps-c/step-04-improvements.md → references/improvements.md}

@@ -1,8 +1,10 @@
 ---
-nextStepFile: './step-05-compile.md'
-refinementRulesData: 'references/refinement-rules.md'
+nextStepFile: 'compile.md'
+refinementRulesData: '{refinementRulesPath}'
 ---
 
+<!-- Config: communicate in {communication_language}. Append improvement findings to the RA state file in {document_output_language}. -->
+
 # Step 4: Improvement Detection
 
 ## STEP GOAL:
@@ -17,8 +19,6 @@ Identify capability expansions — library features documented in the generated
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Reference Refinement Rules
 
 Use the refinement rules loaded in Step 01 from `{refinementRulesData}`. If not available in context, reload from `{refinementRulesData}`.
@@ -102,7 +102,7 @@ Suggestion: {how to incorporate this capability into the architecture}
 
 **Proceeding to compile refined architecture...**"
 
-Store all improvement findings as workflow state for Step 05. To ensure durability across long runs, also append a `<!-- [RA-IMPROVEMENTS] ... -->` comment block to `{forge_data_folder}/ra-state-{project_name}.md` containing the **complete formatted improvement findings** (full citation blocks with evidence, value ratings, and suggestions — not just counts) — Step 05 can read this back if context degrades. **Do NOT write to `{output_folder}/refined-architecture-{project_name}.md` — that file is created only in step-05.**
+Store all improvement findings as workflow state for Step 05. To ensure durability across long runs, also append a `<!-- [RA-IMPROVEMENTS] ... -->` comment block to `{forge_data_folder}/ra-state-{project_name}.md` containing the **complete formatted improvement findings** (full citation blocks with evidence, value ratings, and suggestions — not just counts) — Step 05 can read this back if context degrades. **Do NOT write to `{output_folder}/refined-architecture-{project_name}.md` — that file is created only in step 5.**
 
 ### 7. Auto-Proceed to Next Step
 

package/src/skf-refine-architecture/references/init.md

@@ -0,0 +1,144 @@
+---
+nextStepFile: 'gap-analysis.md'
+refinementRulesData: '{refinementRulesPath}'
+# 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 skill inventory (cascade-resolved exports,
+# metadata-hash, confidence-tier mapping) — replacing a hand-rolled
+# subagent fan-out that re-derived the same data on every run.
+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}. -->
+
+# 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
+
+### 1. Accept Input Documents
+
+"**Refine Architecture — Evidence-Backed Refinement** (additive — never deletes original content).
+
+If you wanted to *verify* the stack first, type `cancel` and run `[VS] Verify Stack`; if no skills exist yet, run `[CS] Create Skill`. Otherwise, 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
+
+Or type `cancel` / `exit` / `:q` at any prompt to abort cleanly."
+
+Wait for user input. Store the validated architecture document path as `architecture_doc`. **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 `--vs-report-path` was provided, consume it at the VS validation 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: Display "Cancelled — no refinement 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 VS report (if provided via `--vs-report-path` or interactive input):**
+- 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
+
+**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 version-aware resolution (export-manifest → `active` symlink → flat fallback), captures the exports cascade (metadata → references → SKILL.md), maps `confidence_tier`, and emits structured JSON with one entry per skill plus a top-level `warnings[]` array. Cache the result as `skill_inventory`.
+
+Each helper-emitted entry includes: `skill_name`, `version`, `language`, `confidence_tier`, `exports_documented`, `source_repo`, `source_root`, and a `metadata_hash` for change-detection across runs. The helper's `warnings[]` carries per-skill skip reasons (missing SKILL.md/metadata.json, non-symlink `active`, orphan-versions, schema-version violations).
+
+**Failure-budget guard:** If `len(warnings) / (len(skill_inventory) + len(warnings)) > 0.20`, HALT (exit code 7, `halt_reason: "inventory-unreliable"`) with: "Inventory scan unreliable — {len(warnings)}/{total} skills returned skip warnings. Re-run [RA] after skills stabilize." In headless, emit the error envelope.
+
+**Fallback path — graceful degradation when the helper is unavailable:** If `{enumerateStackSkillsHelper}` has no existing candidate, fall through to the LLM-driven inventory: walk `{skills_output_folder}` and for each `{skill_package}` read `metadata.json` and extract `name`, `language`, `confidence_tier`, `stats.exports_documented`, `source_repo`/`source_root`. Skip packages missing SKILL.md or metadata.json with a logged warning. Same 20% failure budget applies.
+
+### 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 (exit code 5, `halt_reason: "insufficient-skills"`). In headless, emit the error envelope.
+- 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 `{outputFolderPath}`** (resolved at activation from `output_folder` config + customize override):
+- Verify the path 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 (exit code 3, `halt_reason: "output-folder-unconfigured"`). In headless, emit the error envelope.
+- The directory existence + writability was probed at On-Activation §5 — if it failed there, this section never runs.
+
+**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 (exit code 3, `halt_reason: "forge-folder-unconfigured"`). In headless, emit the error envelope.
+- The directory existence + writability was probed at On-Activation §5.
+
+**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 5 never loads stale findings from a prior run.
+
+On any write failure (read-only mount, disk full, permissions denied): HALT (exit code 4, `halt_reason: "write-failed"`) with the captured error and emit the error envelope. The On-Activation §5 probe should have caught this earlier — if it surfaces here, the filesystem state changed mid-workflow.
+
+### 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-refine-architecture/{steps-c/step-03-issue-detection.md → references/issue-detection.md}

@@ -1,8 +1,10 @@
 ---
-nextStepFile: './step-04-improvements.md'
-refinementRulesData: 'references/refinement-rules.md'
+nextStepFile: 'improvements.md'
+refinementRulesData: '{refinementRulesPath}'
 ---
 
+<!-- Config: communicate in {communication_language}. Append issue-detection findings to the RA state file in {document_output_language}. -->
+
 # Step 3: Issue Detection
 
 ## STEP GOAL:
@@ -17,8 +19,6 @@ Find contradictions between what the architecture document claims and what the g
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Reference Refinement Rules
 
 Use the refinement rules loaded in Step 01 from `{refinementRulesData}`. If not available in context, reload from `{refinementRulesData}`.
@@ -114,7 +114,7 @@ Suggestion: {specific correction with API evidence}
 
 **Proceeding to improvement detection...**"
 
-Store all issue findings as workflow state for Step 05. To ensure durability across long runs, also append a `<!-- [RA-ISSUES] ... -->` comment block to `{forge_data_folder}/ra-state-{project_name}.md` containing the **complete formatted issue findings** (full citation blocks with architecture claims, skill evidence, VS verdicts, severity, and suggestions — not just counts) — Step 05 can read this back if context degrades. **Do NOT write to `{output_folder}/refined-architecture-{project_name}.md` — that file is created only in step-05.**
+Store all issue findings as workflow state for Step 05. To ensure durability across long runs, also append a `<!-- [RA-ISSUES] ... -->` comment block to `{forge_data_folder}/ra-state-{project_name}.md` containing the **complete formatted issue findings** (full citation blocks with architecture claims, skill evidence, VS verdicts, severity, and suggestions — not just counts) — Step 05 can read this back if context degrades. **Do NOT write to `{output_folder}/refined-architecture-{project_name}.md` — that file is created only in step 5.**
 
 ### 7. Auto-Proceed to Next Step
 

package/src/skf-refine-architecture/references/refinement-rules.md

@@ -1,3 +1,5 @@
+<!-- Static reference loaded by gap-analysis.md, issue-detection.md, and improvements.md. -->
+
 # Architecture Refinement Rules
 
 ## Purpose