bmad-module-skill-forge 2.0.0 → 2.0.1

package/src/skf-quick-skill/references/resolve-target.md

@@ -1,9 +1,12 @@
 ---
 nextStepFile: 'ecosystem-check.md'
-registryResolutionData: 'references/registry-resolution.md'
+registryResolutionData: '{registryResolutionPath}'
 packageResolverProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-resolve-package.py'
   - '{project-root}/src/shared/scripts/skf-resolve-package.py'
+detectLanguageProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-language.py'
+  - '{project-root}/src/shared/scripts/skf-detect-language.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -19,7 +22,7 @@ To accept a GitHub URL or package name from the user, resolve it to a GitHub rep
 - Focus only on resolving the target to a GitHub repository — do not begin extraction or compilation
 - If resolution fails, hard halt with actionable guidance
 
-## MANDATORY SEQUENCE
+## Steps
 
 ### 1. Accept User Input
 
@@ -41,7 +44,7 @@ Examples: `cocoindex`, `@tanstack/query`, `https://github.com/tursodatabase/limb
 
 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. **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 exit-code map in `references/halt-contract.md`. Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "resolve-target"`, `error.code: "user-cancelled"`, `skill_package: null`). Cancellation here is non-destructive — no files have been written yet.
 
 **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."
 
@@ -79,7 +82,7 @@ If you are describing a skill you want to **create from scratch** rather than co
 
 Otherwise, paste the package name or GitHub URL of the library you want to wrap, and quick-skill will resolve it."
 
-**GATE [default: HALT]** — In headless mode, emit the same redirect message and HALT with **exit code 3 (resolution-failure)** 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: "resolution-failure"`, `skill_package: null`). Do not attempt registry lookups against prose input; that wastes ~3-4 round trips and produces a less actionable error message than the redirect above.
+**GATE [default: HALT]** — In headless mode, emit the same redirect message and HALT with **exit code 3 (resolution-failure)** per the exit-code map in `references/halt-contract.md`. Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `skill_package: null`). Do not attempt registry lookups against prose input; that wastes ~3-4 round trips and produces a less actionable error message than the redirect above.
 
 ### 3. Registry Resolution
 
@@ -107,7 +110,7 @@ Check:
 
 **Provide the GitHub URL directly to continue.**"
 
-In interactive mode, wait for corrected input and loop back to step 2. In headless mode, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `skill_package: null`) and exit 3.
+In interactive mode, wait for corrected input and loop back to step 2. In headless mode, emit the error result contract per `references/halt-contract.md` (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `skill_package: null`) and exit 3.
 
 ### 3a. Verify Target Version Tag (when applicable)
 
@@ -135,35 +138,36 @@ Recent tags in this repo:
 
 Re-run with one of these tags, or omit the `@version` suffix to auto-detect from the default branch."
 
-Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `error.details: {requested_version: "{target_version}", available_tags: [...top 5]}`, `skill_package: null`). In headless mode, exit immediately; do not loop.
+Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `error.details: {requested_version: "{target_version}", available_tags: [...top 5]}`, `skill_package: null`). In headless mode, exit immediately; do not loop.
 
 ### 4. Detect Language
 
-Determine primary language from:
+**Resolve `{detectLanguageHelper}`** from `{detectLanguageProbeOrder}`; first existing path wins. If no candidate exists (e.g. Python/`uv` unavailable), fall back to the manifest-priority walk documented in the helper's `--help` — `package.json` → JavaScript/TypeScript (TypeScript when a `tsconfig.json` is also present), `Cargo.toml` → Rust, `pyproject.toml`/`setup.py`/`setup.cfg` → Python, `go.mod` → Go, `pom.xml` → Java, `build.gradle.kts` → Kotlin, `build.gradle` → Kotlin when `src/main/kotlin/` exists else Java, `*.csproj`/`*.sln` → C#, `Gemfile` → Ruby, then extension frequency — applied by hand.
 
-1. **User-provided language hint** (overrides detection — skip the ambiguity gate below).
-2. **Manifest-presence scan** — check the repo root for ALL of these (priority order = first hit wins on auto-pick):
-   - `package.json` → JavaScript/TypeScript
-   - `pyproject.toml` or `setup.py` → Python
-   - `Cargo.toml` → Rust
-   - `go.mod` → Go
-   - `pom.xml` → Java (or Kotlin if `src/main/kotlin/` is present)
-   - `build.gradle.kts` or `build.gradle` → Kotlin (or Java if only `src/main/java/` is present)
+Determine primary language:
 
-   Collect every match into `detected_languages`.
+1. **User-provided language hint** (overrides detection) — set `language` to the hint and skip straight to §5. The disambiguation gate below does not run.
 
-3. **Single-language case** (`len(detected_languages) <= 1`) — set `language` to the detected value (or HALT in step 1 §3 if zero matches).
+2. **Delegate the rule walk to `{detectLanguageHelper}`** — it is the single source of truth for the manifest → language rule table (including the `package.json` JS-vs-TS disambiguation); do not restate or re-derive it here. Fetch the repo file listing once (`gh api repos/{owner}/{repo}/git/trees/{source_ref or default branch}?recursive=1`, reading the `path` values), then hand the flat list to the script:
 
-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.
+   ```bash
+   echo '{"tree": [<flat list of repo-relative file paths>]}' | uv run {detectLanguageHelper}
+   ```
+
+   The script returns `{language, confidence, detection_source, detected_languages}` after walking the deterministic rule table (manifest presence first, then extension-frequency fallback). `detected_languages` is the ordered, deduplicated set of every manifest-level match in priority order, with `detected_languages[0]` equal to the winning `language`.
+
+3. **Auto-pick** — set `language` to the returned `language`. If `detected_languages` is empty (the script recognized no manifest and no source extensions — `language` is `"unknown"`), treat it as a zero-match resolution and HALT with the step 1 §3 resolution-failure guidance so the user can supply a language hint or a different target.
+
+4. **Multi-language gate** (`len(detected_languages) > 1`) — the script found manifests for more than one language. Surface the choice rather than silently keeping the first match. Multi-language repos (Python + JS bindings, or monorepos with mixed manifests) otherwise produce a skill for whichever manifest sorts first in priority order, 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 1 §1.
+   Primary guess: **{language}** (`detected_languages[0]`, 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"
+   Select: [C] Continue with `{language}` · [A] Abort"
 
-   - **IF C** — log "user accepted multi-manifest pick: `{first_match}`" and set `language` to the first match.
-   - **IF A** — HARD HALT with **exit code 3 (resolution-failure)**: "Aborted to disambiguate language. Re-run with a `language_hint`." Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `error.details: {detected_languages: [...], auto_pick: "{first_match}"}`, `skill_package: null`).
+   - **IF C** — log "user accepted multi-manifest pick: `{language}`" and keep `language`.
+   - **IF A** — HARD HALT with **exit code 3 (resolution-failure)**: "Aborted to disambiguate language. Re-run with a `language_hint`." Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `error.details: {detected_languages: [...], auto_pick: "{language}"}`, `skill_package: null`).
    - **GATE [default: C]** — Headless mode auto-proceeds with the manifest-priority pick; record `detected_languages` and `language_resolution: "auto-picked-first"` in the extraction context so the result contract surfaces the ambiguity downstream.
 
 ### 5. Confirm Resolution
@@ -179,16 +183,5 @@ Determine primary language from:
 
 ### 6. Proceed to Next Step
 
-#### Menu Handling Logic:
-
-- After successful resolution confirmation, immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an init step with auto-proceed after successful resolution
-- Proceed directly to next step after confirmation
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the target has been successfully resolved to a GitHub repository with confirmed URL, name, and detected language will you load and read fully `{nextStepFile}` to execute the ecosystem check.
+Once the target is resolved to a GitHub repository with confirmed URL, name, and detected language, load and execute {nextStepFile} for the ecosystem check.
 

package/src/skf-quick-skill/references/write-and-validate.md

@@ -18,12 +18,10 @@ To write the compiled SKILL.md, context-snippet.md, and metadata.json to the ver
 
 ## Rules
 
-- Write exactly what was compiled — do not modify content during writing
-- Validation is advisory — report issues but never block output
-- Do not modify compiled content post-validation — report only
+- Write exactly what was compiled — do not modify content during writing or after validation
 - Community-tier validation (lighter than official requirements)
 
-## MANDATORY SEQUENCE
+## Steps
 
 ### 1. Create Output Directory
 
@@ -39,7 +37,7 @@ If `{skill_package}` already exists, confirm with user before overwriting:
 "**Directory `{skill_package}` already exists.** Overwrite will replace the prior compiled output; validation results, result contracts, and any manual tweaks from the previous run will not be preserved. Overwrite existing files? [Y/N]"
 
 - **If user selects Y:** Proceed to section 2.
-- **If user selects N:** HARD HALT with **exit code 5 (overwrite-cancelled)** per the SKILL.md exit-code map: "Overwrite cancelled. Existing skill preserved. Run [QS] with a different skill name or remove the existing directory manually." Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "write-and-validate"`, `error.code: "overwrite-cancelled"`, `skill_package` set to the existing path that was preserved). Disk write of the `-latest.json` envelope is REQUIRED here since `{skill_package}` is known.
+- **If user selects N:** HARD HALT with **exit code 5 (overwrite-cancelled)** per the exit-code map in `references/halt-contract.md`: "Overwrite cancelled. Existing skill preserved. Run [QS] with a different skill name or remove the existing directory manually." Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "write-and-validate"`, `error.code: "overwrite-cancelled"`, `skill_package` set to the existing path that was preserved). Write the `-latest.json` envelope to disk here — `{skill_package}` is known, so consumers that hardcode that path see a deterministic file even on this cancelled run.
 
 **GATE [default: Y]** — If `{headless_mode}` is true, auto-proceed with Y and log: "headless: overwriting existing `{skill_package}`".
 
@@ -53,7 +51,7 @@ Write the three compiled artifacts to the skill package so that validation in se
 
 Confirm after each write: "Written: SKILL.md" / "Written: context-snippet.md" / "Written: metadata.json". When `--skip-snippet` is active, log "Skipped: context-snippet.md (--skip-snippet)" instead of the snippet write confirmation.
 
-**If any write fails — HARD HALT (exit code 4, write-failure):** Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "write-and-validate"`, `error.code: "write-failure"`, `error.details: {failed_path: <path>, error: <details>}`, `skill_package` set, `outputs` listing any files that did write successfully before the failure).
+**If any write fails — HARD HALT (exit code 4, write-failure):** Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "write-and-validate"`, `error.code: "write-failure"`, `error.details: {failed_path: <path>, error: <details>}`, `skill_package` set, `outputs` listing any files that did write successfully before the failure).
 
 "**Write failed:** Could not write to `{file_path}`.
 
@@ -71,8 +69,6 @@ Run: `npx skill-check -h`
 - If succeeds (returns usage information): Continue to automated validation (section 4)
 - If fails (command not found or error): Skip to manual fallback in section 4
 
-**Important:** Use the verification command. Do not assume availability — empirical check required.
-
 ### 4. Validate SKILL.md via skill-check (if available)
 
 **If `npx skill-check` is available**, run automated validation + security scan in one invocation against the skill package written in section 2 (security scan is enabled by default when `--no-security-scan` is omitted, so the same call covers §6 and avoids paying the npx startup cost twice):
@@ -84,24 +80,24 @@ npx skill-check check {skill_package} --fix --format json
 This validates frontmatter, description, body limits, links, and formatting; runs the security scan; and auto-fixes deterministic issues (field ordering, slug format, required fields, trailing newlines).
 
 **Parse JSON output** to extract:
-- `scores[].score` — overall score (0-100); match the entry by `relativePath`/`skillId` (older skill-check builds exposed this as a top-level `qualityScore`)
+- `scores[].score` — overall score (0-100); match the entry by `relativePath`/`skillId`
 - `diagnostics[]` — remaining issues after auto-fix
 - `fixed[]` — issues automatically corrected
 - `security[]` (when present) — security findings, recorded as advisory warnings (security issues do not block output)
 
 Record quality score, remaining diagnostics, and security findings as validation issues.
 
-**If skill-check is NOT available**, run the shared frontmatter validator instead of an LLM-walked checklist. Resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}`; first existing path wins. If no candidate exists, log a high-severity issue ("frontmatter validator unavailable — both `npx skill-check` and `skf-validate-frontmatter.py` missing") and skip frontmatter validation.
+**If skill-check is not available**, run the shared frontmatter validator. Resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}`; first existing path wins. If no candidate exists, log a high-severity issue ("frontmatter validator unavailable — both `npx skill-check` and `skf-validate-frontmatter.py` missing") and skip frontmatter validation.
 
 ```bash
 uv run {frontmatterValidator} {skill_package}/SKILL.md --skill-dir-name {repo_name}
 ```
 
-The validator emits JSON with `status` (`pass`/`fail`), `issues[]` (each with `severity`, `code`, `message`), and `frontmatter` (the parsed name/description). It checks frontmatter delimiters, name format (Unicode letters + digits + hyphens, no consecutive/trailing hyphens), name-directory match, description presence and length, and unknown fields against the agentskills.io spec — the same shape this step would otherwise hand-walk. Record each `issues[]` entry as a validation issue with its reported severity. Missing frontmatter or missing required fields are high-severity — skills without valid frontmatter will fail `npx skills add` and `npx skill-check check`.
+The validator emits JSON with `status` (`pass`/`fail`), `issues[]` (each with `severity`, `code`, `message`), and `frontmatter` (the parsed name/description). It checks frontmatter delimiters, name format (Unicode letters + digits + hyphens, no consecutive/trailing hyphens), name-directory match, description presence and length, and unknown fields against the agentskills.io spec. Record each `issues[]` entry as a validation issue with its reported severity. Missing frontmatter or missing required fields are high-severity — skills without valid frontmatter will fail `npx skills add` and `npx skill-check check`.
 
 ### 5. Validate Body, Snippet, and Metadata via skf-validate-output.py
 
-Run the shared output validator against the on-disk skill package — it performs the body-structure, snippet-format, and metadata-shape checks that this step previously walked by hand. Pass `--skip-frontmatter` since §4 has already covered frontmatter.
+Run the shared output validator against the on-disk skill package — it performs the body-structure, snippet-format, and metadata-shape checks. Pass `--skip-frontmatter` since §4 has already covered frontmatter.
 
 **Resolve `{outputValidator}`:** probe `{outputValidatorProbeOrder}` (installed first, dev fallback); first existing path wins. If neither candidate exists, log a high-severity issue ("output validator unavailable — `skf-validate-output.py` missing") and skip body/snippet/metadata validation.
 
@@ -111,7 +107,7 @@ python3 {outputValidator} {skill_package} --generated-by quick-skill --skip-fron
 
 The validator emits JSON with `result` (PASS/FAIL), `validation.skill_md.body[]`, `validation.context_snippet.issues[]`, `validation.metadata.issues[]`, and a severity-bucketed `summary`. Record each issue as a validation issue at its reported severity.
 
-Coverage replaces these former hand-walked checklists:
+The validator covers:
 
 - **Body structure** — Overview, Description, Key Exports, Usage sections present (medium when missing)
 - **Context snippet** — `[{name} v{version}]|root: ...` first line, `|IMPORTANT:` second line, ~80–120-token length
@@ -149,16 +145,5 @@ Set `validation_result` with pass/fail status, quality score, and issues list.
 
 ### 8. Auto-Proceed to Finalize
 
-#### Menu Handling Logic:
-
-- After validation report, immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed step — validation is advisory
-- Proceed directly to finalize step after reporting results
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN deliverables have been written to `{skill_package}` and validation checks are complete and results reported will you load and read fully `{nextStepFile}` to execute finalization.
+Once deliverables are written to `{skill_package}` and validation is reported (advisory), load and execute {nextStepFile} to finalize.
 

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

@@ -50,8 +50,8 @@ These rules apply to every step in this workflow:
 |--------|--------|
 | **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); `--scope-skills <names>` (comma-separated in-scope skill names; overrides scope derivation in gap analysis) |
-| **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` |
+| **Gates** | step 1: Input Gate [use args] | step 5: Review Gate [C] continue / [X] cancel | step 6: Exit menu [R] review / [X] exit |
+| **Outputs** | `refined-architecture-{arch_project_name}.md` at `{outputFolderPath}` (`{arch_project_name}` = the architecture doc's frontmatter `project_name`, else config `project_name` — resolved in init.md), 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 |
 
@@ -63,8 +63,8 @@ Every HARD HALT in this workflow exits with a stable code so headless automators
 | ---- | -------------------- | -------------------------------------------------------------------------------------------- |
 | 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) |
+| 3    | resolution-failure   | On-Activation §5 (`output_folder` or `forge_data_folder` unconfigured) |
+| 4    | write-failure        | On-Activation §5 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) |
@@ -110,10 +110,17 @@ SKF_REFINE_ARCHITECTURE_RESULT_JSON: {"status":"success|error","refined_path":"
 
    - `{refinementRulesPath}` ← `workflow.refinement_rules_path` if non-empty, else `references/refinement-rules.md`
    - `{outputFolderPath}` ← `workflow.output_folder_path` if non-empty, else `{output_folder}`
+   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty (no-op — report.md skips the hook invocation entirely)
 
-   Stash both as workflow-context variables. Stage files reference them directly — no conditional at the usage site.
+   Stash all three 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:
+   Also apply the array surfaces (not silent no-ops): run `workflow.activation_steps_prepend` now, treat `workflow.persistent_facts` as standing context for the run (`file:`-prefixed entries load their file/glob contents as facts), then run `workflow.activation_steps_append` after activation.
+
+5. **Pre-flight config + write probe.** Assert both output paths are configured, then probe writability — order matters: an empty path makes `mkdir -p ""` fail, which would misreport a *missing config* (exit 3) as a *write failure* (exit 4) and collapse the distinction the Result Contract draws.
+
+   **Config-completeness (exit 3).** If `{outputFolderPath}` is empty: HALT (exit code 3, `halt_reason: "output-folder-unconfigured"`) — "`output_folder` is not configured in config.yaml. Add an `output_folder` path and re-run [RA]." If `{forge_data_folder}` is empty: HALT (exit code 3, `halt_reason: "forge-folder-unconfigured"`) — "`forge_data_folder` is not configured in config.yaml. Add a `forge_data_folder` path and re-run [RA]."
+
+   **Write probe (exit 4).** With both paths now non-empty, verify each is writable — a read-only mount, full disk, or permissions-denied path otherwise only surfaces at init.md §3c's RA state file write, by which point the user has already gone through input prompts:
 
    ```bash
    for dir in "{outputFolderPath}" "{forge_data_folder}"; do
@@ -123,6 +130,6 @@ SKF_REFINE_ARCHITECTURE_RESULT_JSON: {"status":"success|error","refined_path":"
    done
    ```
 
-   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`.
+   On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`). In headless mode, every HALT above emits the error envelope per **Result Contract (Headless)** with `refined_path: null`.
 
 6. Load, read the full file, and then execute `references/init.md` to begin the workflow.

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

@@ -1,6 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-refine-architecture.
+# Team overrides:     _bmad/custom/skf-refine-architecture.toml (under {project-root})
+# Personal overrides: _bmad/custom/skf-refine-architecture.user.toml (under {project-root})
 
 [workflow]
 
@@ -47,3 +49,10 @@ refinement_rules_path = ""
 # refined-architecture artifacts to land under a curated docs tree.
 
 output_folder_path = ""
+
+# Optional post-completion hook. When non-empty, invoked with
+# `--result-path=<path>` after the refined architecture and result JSON are
+# finalized (step 6). Use to index the refined doc, notify, or chain the next
+# workflow. Failures are logged to workflow_warnings[] but never fail the run.
+
+on_complete = ""

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

@@ -1,6 +1,7 @@
 ---
 nextStepFile: 'report.md'
-outputFile: '{outputFolderPath}/refined-architecture-{project_name}.md'
+# {arch_project_name} resolved in init.md (arch-doc frontmatter project_name, else config project_name).
+outputFile: '{outputFolderPath}/refined-architecture-{arch_project_name}.md'
 ---
 
 <!-- Config: communicate in {communication_language}. Compile the refined architecture document in {document_output_language}. -->
@@ -23,7 +24,7 @@ Produce the refined architecture document by starting with the original as a bas
 
 Load the complete original architecture document.
 
-This is the base. Every line of the original MUST appear in the refined document, unmodified.
+This is the base. Every line of the original appears in the refined document unmodified — the workflow only adds annotations and subsections; dropping or rewording original content silently discards the user's architecture.
 
 **Context recovery check:** If gap, issue, or improvement findings from Steps 02-04 are not available in context (e.g., due to context degradation in long runs), attempt to read the durability state from `{forge_data_folder}/ra-state-{project_name}.md`. Parse the `<!-- [RA-GAPS] -->`, `<!-- [RA-ISSUES] -->`, and `<!-- [RA-IMPROVEMENTS] -->` comment blocks to recover the complete formatted findings (each block contains full citation text with evidence, not just counts). If a section is still missing or contains only summary counts after recovery, HALT (exit code 8, `halt_reason: "recovery-failed"`): "⚠️ Context for the [Gaps|Issues|Improvements] analysis was lost and the durability state is insufficient to reconstruct findings. Re-run [RA] from the beginning — step 01 will reset the state file, then steps 02-04 will rebuild all findings." In headless, emit the error envelope per SKILL.md "Result Contract (Headless)" with `refined_path: null`.
 
@@ -112,6 +113,8 @@ Append a `## Refinement Summary` section containing:
 
 Write the complete refined architecture to `{outputFile}`.
 
+On any write failure (read-only mount, disk full, permissions denied): HALT (exit code 4, `halt_reason: "write-failed"`) with the captured error. In headless, emit the error envelope per SKILL.md "Result Contract (Headless)" with `refined_path: null`. The On-Activation §5 write probe should have caught an unwritable output folder earlier — if it surfaces here, the filesystem state changed mid-workflow.
+
 ### 7. Present Compiled Document for Review
 
 "**Refined architecture compiled. Please review:**
@@ -134,16 +137,15 @@ Please review the refinements:
 
 ### 8. Present MENU OPTIONS
 
-Display: **Select:** [C] Continue to Final Report
+Display: **Select:** [C] Continue to Final Report | [X] Cancel
 
-#### EXECUTION RULES:
+#### GATE [default: C]
 
-- ALWAYS halt and wait for user input after presenting compilation
-- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-approve compiled architecture"
-- ONLY proceed to next step when user approves and selects 'C'
+This is a review gate: halt for the user's decision and do not chain onward until they approve — an unreviewed compile ships un-vetted refinements. Headless auto-selects [C] (log: "headless: auto-approve compiled architecture").
 
 #### Menu Handling Logic:
 
 - IF C: Load, read entire file, then execute {nextStepFile}
+- IF cancel / exit / [X] / q / :q: HALT (exit code 6, `halt_reason: "user-cancelled"`) — display "Cancelled — refinement not finalized." In headless, emit the error envelope per SKILL.md "Result Contract (Headless)" with `refined_path: null`. These global cancel tokens pre-empt the feedback branch below.
 - IF Any other: Process as feedback, adjust specific refinements in the document, rewrite {outputFile}, redisplay preview, then [Redisplay Menu Options](#8-present-menu-options)
 

package/src/skf-refine-architecture/references/gap-analysis.md

@@ -22,21 +22,15 @@ Find undocumented integration paths — library pairs that have compatible APIs
 
 Use the refinement rules loaded in Step 01 from `{refinementRulesData}`. If not available in context, reload from `{refinementRulesData}`.
 
-Extract: gap classification (Missing Integration Path, Undocumented Data Flow, Absent Bridge Layer), detection method, and citation format.
+Extract: gap classification (Missing Integration Path, Undocumented Data Flow, Absent Bridge Layer) and detection method.
 
 ### 2. Extract Integration Claims from Architecture
 
 Parse the architecture document for statements describing two or more technologies working together.
 
-**Detection method — prose-based co-mention analysis:**
-- Identify sentences or paragraphs where two or more technology names appear together
-- Look for integration verbs: "connects to", "communicates with", "wraps", "extends", "consumes", "produces", "bridges", "integrates with", "sits between", "feeds into", "receives from"
-- Look for data flow descriptions: "{A} sends data to {B}", "{A} results are consumed by {B}"
-- Look for layer boundary descriptions: "{A} at the API layer connects to {B} at the data layer"
+**Detection method — prose-based co-mention analysis:** From prose text, find sentences or paragraphs where two or more technology names appear in an *integration relationship* — data flowing between them, one wrapping/bridging/extending/consuming another, or a layer boundary connecting them — not mere co-mention in the same document.
 
-**CRITICAL:** Do NOT parse Mermaid diagram syntax. Use only prose text for co-mention detection.
-
-**Mermaid Limitation Warning:** If `` ```mermaid `` blocks are present in the architecture document, inform the user: "Integration paths documented exclusively in Mermaid diagrams are excluded from co-mention analysis and may appear as false-positive gaps. Consider adding prose descriptions for diagram-only integration paths." Display this warning informatively and immediately continue — this does not halt or modify the analysis sequence.
+**Mermaid limitation:** Detect co-mentions from prose text only, not from Mermaid diagram syntax — an integration drawn only in a diagram would otherwise surface as a false-positive gap. If `` ```mermaid `` blocks are present in the architecture document, inform the user: "Integration paths documented exclusively in Mermaid diagrams are excluded from co-mention analysis and may appear as false-positive gaps. Consider adding prose descriptions for diagram-only integration paths." Display this warning informatively and immediately continue — this does not halt or modify the analysis sequence.
 
 **Build documented pairs list:**
 - Each pair: `{library_a, library_b, architectural_context}`
@@ -44,7 +38,7 @@ Parse the architecture document for statements describing two or more technologi
 
 ### 2b. Establish Document Scope
 
-The skill inventory (Step 01 §2) can span a wider product surface than the architecture document under refinement. Pairs drawn from a different surface are NOT actionable gaps for THIS document — surfacing them injects irrelevant integration recommendations (e.g. wiring real-time A/V libraries into an admin-dashboard architecture).
+The skill inventory (Step 01 §2) can span a wider product surface than the architecture document under refinement. Pairs drawn from a different surface are not actionable gaps for this document — surfacing them injects irrelevant integration recommendations (e.g. wiring real-time A/V libraries into an admin-dashboard architecture).
 
 Resolve the in-scope skill set:
 
@@ -53,15 +47,15 @@ Resolve the in-scope skill set:
 
 `{out_of_scope_skills}` = inventory skills not in `{in_scope_skills}`. A library pair is **out-of-scope** when either of its libraries is in `{out_of_scope_skills}`.
 
-**Safe default:** If scope cannot be derived (e.g. the architecture references no inventory skill by name) and no `{scope_skills}` was provided, treat ALL skills as in-scope and note: "Could not derive document scope — analyzing all skill pairs." This preserves prior behavior rather than hiding gaps.
+**Safe default:** If scope cannot be derived (e.g. the architecture references no inventory skill by name) and no `{scope_skills}` was provided, treat all skills as in-scope and note: "Could not derive document scope — analyzing all skill pairs." This keeps borderline gaps visible rather than hiding them.
 
 Store `{in_scope_skills}` and `{out_of_scope_skills}` as workflow state — Step 03 (issue detection) reuses them.
 
-### 3. Generate All Possible Library Pairs
+### 3. Read the Pre-Computed Library Pairs
 
-From the skill inventory, generate all unique combinations of library pairs.
+Read the pre-computed unique library pairs from `skill_inventory.pairs` (the enumerate helper's `--pairs` output cached in Step 01 §2 — the complete, deterministic pair set). Do not re-derive it in-context: a silently dropped or duplicated pair is a missed integration gap, this workflow's headline output.
 
-For N skills, this produces N*(N-1)/2 unique pairs.
+If `skill_inventory.pairs` is absent (the helper was unavailable and the Step 01 §2 fallback path ran), derive the pairs from the inventory as a graceful-degradation fallback only.
 
 ### 4. Load Skill API Surfaces for Cross-Reference
 
@@ -69,10 +63,10 @@ For N skills, this produces N*(N-1)/2 unique pairs.
 
 For each library in the skill inventory, delegate reading to a parallel subagent. Launch up to **8 subagents concurrently** (batch larger inventories in rounds of 8).
 
-**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:
+**Each subagent receives one skill's SKILL.md path and:**
+1. Reads the SKILL.md file
+2. Extracts the API surface
+3. Returns only this compact JSON — no prose or extra commentary:
 
 ```json
 {
@@ -89,7 +83,7 @@ For each library in the skill inventory, delegate reading to a parallel subagent
 - `data_formats`: any data format indicators found in the SKILL.md
 - If a field has no matches, return an empty array `[]`
 
-**Parent collects all subagent JSON summaries.** Do not load full SKILL.md content into parent context.
+**Parent collects all subagent JSON summaries.** Do not load full SKILL.md content into parent context. Store the collected summaries as `{skill_api_surfaces}` workflow state — Step 03 (issue detection) and Step 04 (improvements) reuse them exactly like `{in_scope_skills}`, rather than re-reading each SKILL.md into the parent. This §4 delegate-the-read (compact-JSON return, no full-file load in parent) is the canonical API-surface read pattern for the workflow.
 
 **From metadata.json (read in parent — lightweight), also extract:**
 - `language` — primary programming language
@@ -97,21 +91,21 @@ For each library in the skill inventory, delegate reading to a parallel subagent
 
 ### 5. Cross-Reference: Identify Gaps
 
-For each possible library pair NOT already documented in the architecture:
+For each library pair in `skill_inventory.pairs` (from §3) not already documented in the architecture:
 
 **Check API compatibility:**
 - Does Library A export types or data that Library B can consume?
 - Do both libraries share a compatible protocol or data format?
 - Are they in the same language or is there a bridge mechanism available?
 
-**Scope routing (from §2b):** Before classifying, check the pair's scope. If the pair is **out-of-scope** (either library is in `{out_of_scope_skills}`), do NOT add it to the gap list even when its APIs are compatible — record it in the informational **Out-of-Scope** bucket instead (a compatible pair that belongs to a different product surface than this architecture). Only **in-scope** pairs proceed to gap classification below.
+**Scope routing (from §2b):** Before classifying, check the pair's scope. If the pair is **out-of-scope** (either library is in `{out_of_scope_skills}`), do not add it to the gap list even when its APIs are compatible — record it in the informational **Out-of-Scope** bucket instead (a compatible pair that belongs to a different product surface than this architecture). Only **in-scope** pairs proceed to gap classification below.
 
 **If compatible APIs exist (in-scope pair) but NO architecture mention:**
 - Classify the gap type (Missing Integration Path, Undocumented Data Flow, or Absent Bridge Layer)
 - Document the connecting APIs from both skills
 - Propose a brief architecture section describing the integration
 
-**Apply the citation format from {refinementRulesData}:**
+**Cite each gap in this format:**
 ```
 **[GAP]**: {description}
 
@@ -125,37 +119,14 @@ Suggestion: {proposed architecture section content}
 
 **If no compatible APIs:** Skip this pair — not all pairs need to integrate.
 
-### 6. Display Gap Analysis Results
-
-"**Pass 1: Gap Analysis — Undocumented Integration Paths**
-
-**Gaps Found (in-scope):** {count}
-
-{IF gaps found:}
-| # | Library A | Library B | Gap Type | Connecting APIs |
-|---|-----------|-----------|----------|-----------------|
-| {n} | {lib_a} | {lib_b} | {gap_type} | {brief API description} |
-
-{For each gap, display the full citation with evidence and suggestion}
-
-{IF out-of-scope compatible pairs exist (from §2b/§5):}
-**Out of scope for this document:** {oos_count} compatible pair(s) involve skills outside this architecture's surface — `{out_of_scope_skills}` — and were NOT counted as gaps. Listed for awareness only:
-
-| Library A | Library B | Reason |
-|-----------|-----------|--------|
-| {lib_a} | {lib_b} | out-of-scope — not referenced in this architecture |
-
-If any of these belongs in this architecture, re-run with `--scope-skills` naming the skills to include.
-
-{IF no gaps found AND N > 1:}
-**No undocumented integration paths detected.** The architecture document covers all compatible in-scope library pairs.
+### 6. Report Gaps & Store Findings
 
-{IF no gaps found AND N == 1:}
-**⚠️ Gap analysis skipped — only 1 skill loaded.** Pairwise integration analysis requires at least 2 skills. If the architecture references multiple libraries, those without a matching skill are invisible to gap analysis. **Recommendation:** Generate skills for all architecture libraries with [CS] or [QS] before running [RA] for comprehensive gap detection.
+Report the in-scope gap count, then list each gap as a row of **# / Library A / Library B / Gap Type / Connecting APIs** followed by its full §5 citation. Two signals are not inferable from the counts and must survive regardless of format:
 
-**Proceeding to issue detection (still produces value with 1 skill)...**"
+- **N == 1 (only one skill loaded):** gap analysis is skipped — pairwise integration analysis needs ≥2 skills, and libraries without a matching skill are invisible to it. Recommend generating skills for all architecture libraries with [CS] or [QS] before re-running [RA], and note issue detection still runs.
+- **Out-of-scope compatible pairs exist (from §2b/§5):** list them separately for awareness only — they were not counted as gaps — and note that re-running with `--scope-skills` (naming the skills to include) pulls any that belong into scope.
 
-Store all **in-scope** 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. Record out-of-scope pairs under a separate `<!-- [RA-OUT-OF-SCOPE] ... -->` marker (NOT `[RA-GAPS]`) so Step 05 does not compile them into the refined document — they are informational only. **Do NOT write to `{output_folder}/refined-architecture-{project_name}.md` — that file is created only in step 5.**
+Store the **in-scope** gap findings per the Finding Storage rule (refinement rules), under a `<!-- [RA-GAPS] ... -->` block. Record out-of-scope pairs under a separate `<!-- [RA-OUT-OF-SCOPE] ... -->` marker so Step 05 leaves them out of the refined document — they are informational only.
 
 ### 7. Auto-Proceed to Next Step
 

package/src/skf-refine-architecture/references/health-check.md

@@ -1,7 +1,7 @@
 ---
 # 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.
+# development), not relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 

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

@@ -23,7 +23,7 @@ Identify capability expansions — library features documented in the generated
 
 Use the refinement rules loaded in Step 01 from `{refinementRulesData}`. If not available in context, reload from `{refinementRulesData}`.
 
-Extract: improvement classification (Unused Capability, Cross-Library Synergy, Alternative Pattern), detection method, and citation format.
+Extract: improvement classification (Unused Capability, Cross-Library Synergy, Alternative Pattern) and detection method.
 
 ### 2. Build Architecture Usage Map
 
@@ -39,15 +39,13 @@ This creates a map of `{library} -> {described_usage[]}` for comparison against
 
 For each skill in the inventory:
 
-**Load the full API surface from SKILL.md:**
-- All exported functions with signatures
-- All exported types and interfaces
-- All documented capabilities and features
-- All protocol support indicators
+**Start from the surfaces already collected.** Reuse `{skill_api_surfaces}` (the compact `{exports, protocols, data_formats}` summaries from Step 02 §4) for exports, types, and protocol support — do not re-read SKILL.md in the parent.
+
+**For the fuller capability read** — documented capabilities and features that go beyond §4's exports/protocols/data_formats extraction — delegate to parallel subagents mirroring Step 02 §4 (the canonical delegate-the-read pattern): each subagent reads one SKILL.md and returns compact JSON listing that skill's documented capabilities/features; the parent collects the summaries without loading full SKILL.md content. Reload a file directly only if its summary is unavailable or context has compacted.
 
 **Compare against the architecture usage map:**
 - Which exports does the architecture reference or imply usage of?
-- Which exports are NOT referenced in the architecture at all?
+- Which exports are not referenced in the architecture at all?
 
 **For each unreferenced capability:**
 - Evaluate relevance: would this capability strengthen the architecture?
@@ -66,7 +64,7 @@ Examine pairs of skills for complementary capabilities not exploited in the arch
 
 ### 5. Document Each Improvement
 
-For each detected improvement, apply the citation format from {refinementRulesData}:
+For each detected improvement, cite it in this format:
 
 ```
 **[IMPROVEMENT]**: {description}
@@ -84,25 +82,11 @@ Suggestion: {how to incorporate this capability into the architecture}
 - **Medium:** Capabilities that add convenience or efficiency improvements
 - **Low:** Capabilities that are nice-to-have but not impactful
 
-### 6. Display Improvement Suggestions
-
-"**Pass 3: Improvement Detection — Untapped Capabilities**
-
-**Improvements Found:** {count} ({high_count} high value, {medium_count} medium, {low_count} low)
-
-{IF improvements found:}
-| # | Library | Improvement Type | Value | Summary |
-|---|---------|-----------------|-------|---------|
-| {n} | {lib} | {type} | {value} | {brief description} |
-
-{For each improvement, display the full citation with evidence and suggestion}
-
-{IF no improvements found:}
-**No untapped capabilities detected.** The architecture fully leverages the skill API surfaces.
+### 6. Report Improvements & Store Findings
 
-**Proceeding to compile refined architecture...**"
+Report the improvement count with its high/medium/low value breakdown, then list each improvement as a row of **# / Library / Improvement Type / Value / Summary** followed by its full §5 citation.
 
-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.**
+Store the improvement findings per the Finding Storage rule (refinement rules), under a `<!-- [RA-IMPROVEMENTS] ... -->` block (its citations carry the evidence, value rating, and suggestion).
 
 ### 7. Auto-Proceed to Next Step