bmad-module-skill-forge 1.9.0 → 2.0.1

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
 

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

@@ -5,8 +5,7 @@ refinementRulesData: '{refinementRulesPath}'
 # `{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.
+# metadata-hash, confidence-tier mapping).
 enumerateStackSkillsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-enumerate-stack-skills.py'
   - '{project-root}/src/shared/scripts/skf-enumerate-stack-skills.py'
@@ -46,6 +45,8 @@ Wait for user input. Store the validated architecture document path as `architec
 - 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.
 
+**Resolve `{arch_project_name}` (names the refined output file):** Read the architecture document's YAML frontmatter. If it declares a `project_name`, store that value as `{arch_project_name}`; otherwise fall back to the config `{project_name}` resolved at activation. Stash `{arch_project_name}` as a workflow-context variable — `compile.md` and `report.md` resolve `{outputFile}` from it. This makes a producer-side refine of a consumer's architecture doc (the producer/consumer forge split) name the proposal after the doc's own project rather than the forge workspace config. Producer-side working state (`ra-state-{project_name}.md`) and the VS report auto-probe stay keyed on the config `{project_name}`.
+
 **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
@@ -60,16 +61,18 @@ Wait for user input. Store the validated architecture document path as `architec
 **Primary path — deterministic enumeration via shared helper:**
 
 ```bash
-python3 {enumerateStackSkillsHelper} enumerate {skills_output_folder}
+python3 {enumerateStackSkillsHelper} enumerate {skills_output_folder} --pairs --reliability
 ```
 
 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`.
 
+`--pairs` additionally attaches `skill_inventory.pairs` — the complete, deterministic set of unique `{library_a, library_b}` combinations over the skill names (`itertools.combinations`, sorted-name order, `pair_count == N*(N-1)/2`) — plus `skill_inventory.pair_count`. Cache both alongside the inventory. This is the exact pair set Step 02 (gap analysis) iterates; the helper owns the combinatorics, so a pair can never be silently dropped or duplicated at larger N and downstream steps read the set rather than re-deriving it.
+
 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.
+**Failure-budget guard:** `--reliability` attaches the helper-computed verdict — `inventory_reliable` (boolean), `unreliable_ratio`, `skill_count`, `warning_count` — so the reliability threshold lives in one unit-tested place and this step reads a boolean rather than re-deriving a ratio. If `inventory_reliable` is false, HALT (exit code 7, `halt_reason: "inventory-unreliable"`) with: "Inventory scan unreliable — {warning_count}/{skill_count + warning_count} 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.
+**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. On this degraded path only — with no helper to consult — treat the run as unreliable and HALT the same way if skip warnings exceed one in five of the scanned packages.
 
 ### 3. Validate Minimum Requirements
 
@@ -79,17 +82,7 @@ Each helper-emitted entry includes: `skill_name`, `version`, `language`, `confid
 - 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.
+**Output paths (`{outputFolderPath}`, `forge_data_folder`):** both were asserted non-empty (config-completeness → exit 3, `output-folder-unconfigured` / `forge-folder-unconfigured`) and then probed for writability (→ exit 4, `write-failed`) at On-Activation §5. If either was unconfigured or unwritable the run already halted there, so both are guaranteed present and writable here — no re-check needed.
 
 **Check architecture document:**
 - Confirm it was loaded successfully in section 1

package/src/skf-refine-architecture/references/issue-detection.md

@@ -23,7 +23,7 @@ Find contradictions between what the architecture document claims and what the g
 
 Use the refinement rules loaded in Step 01 from `{refinementRulesData}`. If not available in context, reload from `{refinementRulesData}`.
 
-Extract: issue classification (API Mismatch, Protocol Contradiction, Language Boundary Ignored, Type Incompatibility), VS report integration rules, and citation format.
+Extract: issue classification (API Mismatch, Protocol Contradiction, Language Boundary Ignored, Type Incompatibility) and VS report integration rules.
 
 ### 2. Extract Integration Claims from Architecture
 
@@ -43,7 +43,7 @@ For each claim, record:
 
 ### 3. Verify Claims Against Skill API Surfaces
 
-For each extracted claim, load the relevant skill(s) and check:
+For each extracted claim, verify against the compact API surfaces already collected in Step 02 §4 — the per-skill `{skill_api_surfaces}` summaries (`{exports, protocols, data_formats}`), carried forward as workflow state exactly like `{in_scope_skills}`. Reload a skill's SKILL.md directly only if its summary is unavailable or context has compacted (see Step 02 §4 for the canonical delegate-the-read pattern). Then check:
 
 **API Mismatch check:**
 - Does the claimed API actually exist in the skill's export list?
@@ -66,11 +66,11 @@ For each extracted claim, load the relevant skill(s) and check:
 
 If `vs_report_available` is true:
 
-**Scope filter (reuse `{out_of_scope_skills}` from Step 02 §2b):** The VS report carries verdicts across the entire skill set, which may exceed this architecture's surface. Before promoting any verdict, check the pair's scope — if a verdict is for an **out-of-scope** pair (either library in `{out_of_scope_skills}`), do NOT promote it to an issue for THIS architecture; record it under the informational Out-of-Scope bucket instead. Only **in-scope** pairs' verdicts are promoted by the rules below.
+**Scope filter (reuse `{out_of_scope_skills}` from Step 02 §2b):** The VS report carries verdicts across the entire skill set, which may exceed this architecture's surface. Before promoting any verdict, check the pair's scope — if a verdict is for an **out-of-scope** pair (either library in `{out_of_scope_skills}`), do not promote it to an issue for this architecture; record it under the informational Out-of-Scope bucket instead. Only **in-scope** pairs' verdicts are promoted by the rules below.
 
 **Load the VS feasibility report and extract verdicts:**
-- **Risky verdicts** (match case-insensitively: "Risky", "RISKY", "risky"): Promote to confirmed issues with the VS evidence as additional citation
-- **Blocked verdicts** (match case-insensitively: "Blocked", "BLOCKED", "blocked"): Promote to critical issues requiring architecture redesign
+- **Risky verdicts** (match case-insensitively): Promote to confirmed issues with the VS evidence as additional citation
+- **Blocked verdicts** (match case-insensitively): Promote to critical issues requiring architecture redesign
 - **Plausible verdicts:** Note informatively — Plausible is not an issue by itself. Only flag as a potential issue if the VS rationale text explicitly states "no direct API evidence" or "weak evidence"
 
 **For each VS-sourced issue, include dual citations:**
@@ -81,7 +81,7 @@ If `vs_report_available` is false: Skip this section. Issue detection proceeds w
 
 ### 5. Document Each Issue
 
-For each detected issue, apply the citation format from {refinementRulesData}:
+For each detected issue, cite it in this format:
 
 ```
 **[ISSUE]**: {description}
@@ -98,28 +98,13 @@ Suggestion: {specific correction with API evidence}
 - **Major:** Risky VS verdicts, protocol mismatches, missing bridge layers
 - **Minor:** Plausible VS verdicts where the VS rationale explicitly states "no direct API evidence" or "weak evidence", minor type differences with easy conversion
 
-### 6. Display Issue Detection Results
+### 6. Report Issues & Store Findings
 
-"**Pass 2: Issue Detection — Architecture vs. API Reality**
+Report the in-scope issue count with its critical/major/minor breakdown, then list each issue as a row of **# / Libraries / Issue Type / Severity / Summary** followed by its full §5 citation. One signal is not inferable from the counts and must survive regardless of format:
 
-**Issues Found (in-scope):** {count} ({critical_count} critical, {major_count} major, {minor_count} minor)
+- **Out-of-scope VS verdicts were set aside (from §4):** list them separately for awareness only — they were not counted as issues — and note that re-running with `--scope-skills` pulls any that belong into scope.
 
-{IF issues found:}
-| # | Libraries | Issue Type | Severity | Summary |
-|---|-----------|-----------|----------|---------|
-| {n} | {libs} | {issue_type} | {severity} | {brief description} |
-
-{For each issue, display the full citation with evidence and suggestion}
-
-{IF out-of-scope VS verdicts were set aside (from §4):}
-**Out of scope for this document:** {oos_issue_count} VS verdict(s) involve skills outside this architecture's surface (`{out_of_scope_skills}`) and were NOT counted as issues. Listed for awareness only — re-run with `--scope-skills` if any belongs in scope.
-
-{IF no issues found:}
-**No contradictions detected.** Architecture claims align with verified in-scope skill API surfaces.
-
-**Proceeding to improvement detection...**"
-
-Store all **in-scope** 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. Record any out-of-scope VS verdicts under the shared `<!-- [RA-OUT-OF-SCOPE] ... -->` marker (NOT `[RA-ISSUES]`) so Step 05 does not compile them — 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** issue findings per the Finding Storage rule (refinement rules), under a `<!-- [RA-ISSUES] ... -->` block (its citations carry the architecture claim, skill evidence, VS verdict, severity, and suggestion). Record any out-of-scope VS verdicts under the shared `<!-- [RA-OUT-OF-SCOPE] ... -->` marker so Step 05 leaves them out — informational only.
 
 ### 7. Auto-Proceed to Next Step
 

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

@@ -14,7 +14,7 @@ Gaps are undocumented integration paths — library pairs that have compatible A
 
 ### Detection Method
 
-1. Generate all possible library pairs from the skill inventory
+1. Read the pre-computed unique library pairs from `skill_inventory.pairs` (emitted by the enumerate helper's `--pairs` flag) — do not re-derive them in-context
 2. For each pair, check if both skills export APIs that could connect (compatible types, shared protocols, complementary producer/consumer patterns)
 3. Cross-reference against the architecture document: does the document describe how these two libraries interact?
 4. If compatible APIs exist but NO architecture description exists, this is a **gap**
@@ -77,27 +77,15 @@ Improvements are capability expansions — library features documented in skills
 
 ---
 
-## Refinement Citation Format
+## Finding Storage (Steps 02-04)
 
-Every refinement (gap, issue, or improvement) MUST cite evidence:
-
-```
-**[GAP|ISSUE|IMPROVEMENT]**: {description}
-
-Evidence:
-- {skill_name} exports: `{function_name}({params}) -> {return_type}`
-- {skill_name} provides: `{type_or_protocol}`
-- Architecture states: "{quoted text from original document}"
-- {IF VS report}: VS verdict: {verdict} for {pair}
-
-Suggestion: {specific, actionable recommendation}
-```
+Each analysis step stores its findings two ways: as workflow state for Step 05, and appended to `{forge_data_folder}/ra-state-{project_name}.md` as a labeled `<!-- [RA-...] ... -->` block holding the **complete formatted findings** — full citation blocks with evidence and suggestions, not just counts — so Step 05 can recover them if context degrades on a long run. The refined document itself is written once, in Step 05; Steps 02-04 never write to it.
 
 ---
 
 ## Preservation Rules
 
-1. **NEVER delete original content** — only add annotations and subsections
+1. **Never delete original content** — only add annotations and subsections
 2. **Follow original section layout** — add refinement subsections within existing sections
 3. **Use callout blocks** for issues: `> [!WARNING]` or `> [!NOTE]` format
 4. **Mark additions clearly** — prefix added subsections with "RA:" or use a refinement marker

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

@@ -1,8 +1,9 @@
 ---
 # {outputFile} resolves from the activation-stored {outputFolderPath}
 # variable (set in SKILL.md On Activation §4 from output_folder config +
-# customize override).
-outputFile: '{outputFolderPath}/refined-architecture-{project_name}.md'
+# customize override) and {arch_project_name} (resolved in init.md from the
+# architecture doc's frontmatter project_name, else config project_name).
+outputFile: '{outputFolderPath}/refined-architecture-{arch_project_name}.md'
 nextStepFile: 'health-check.md'
 ---
 
@@ -18,7 +19,7 @@ Present the complete refinement summary to the user. Display counts of gaps fill
 
 - Focus only on presenting the completed refinement — no new analysis
 - Do not discover new gaps, issues, or improvements, and do not modify the refined document
-- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing summary is NOT the terminal step
+- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing summary is not the terminal step
 
 ## MANDATORY SEQUENCE
 
@@ -26,7 +27,7 @@ Present the complete refinement summary to the user. Display counts of gaps fill
 
 Read the `{outputFile}` to have all data available for presentation.
 
-Verify the `## Refinement Summary` section is present. If it is absent, HALT: "⚠️ Refinement Summary not found in `{outputFile}`. Step 05 may not have completed successfully. Re-run [RA] from the beginning."
+Verify the `## Refinement Summary` section is present. If it is absent, HALT (exit code 8, `halt_reason: "recovery-failed"`): "⚠️ Refinement Summary not found in `{outputFile}`. Step 05 may not have completed successfully. Re-run [RA] from the beginning." In headless, emit the error envelope per SKILL.md "Result Contract (Headless)" with `refined_path: null`.
 
 **Extract metrics from the Refinement Summary section:** Parse `gap_count`, `issue_count`, `improvement_count`, `critical_count`, `major_count`, `minor_count`, `high_count`, `medium_count`, `low_count`, and `skill_count` from the Changes Made table and Evidence Sources table. Use these extracted values in the summary table and next-steps sections below.
 
@@ -92,15 +93,17 @@ Re-run **[RA] Refine Architecture** anytime after updating your skills or archit
   SKF_REFINE_ARCHITECTURE_RESULT_JSON: {"status":"success","refined_path":"{outputFile}","gap_count":{gap_count},"issue_count":{issue_count},"improvement_count":{improvement_count},"exit_code":0,"halt_reason":null}
   ```
 
-  Then load, read the full file, and execute `{nextStepFile}` — the health-check step is the true terminal step of this workflow.
+  **Post-completion hook (optional).** If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §4 from `workflow.on_complete`), invoke it after the result contract is finalized:
 
-#### EXECUTION RULES:
+  ```bash
+  {onCompleteCommand} --result-path={result_json_path}
+  ```
 
-- ALWAYS halt and wait for user input after presenting the menu
-- R may be selected multiple times — always walk through all refinements
-- X triggers the health check, which is the true workflow exit
+  where `{result_json_path}` is the per-run record written above (`{outputFolderPath}/refine-architecture-result-{timestamp}.json`). Log success/failure to `workflow_warnings[]` — never fail the workflow on a hook error. The hook runs after the result contract is finalized so notifiers, indexers, or downstream pipelines (index the refined doc, chain the next workflow) see a complete record. When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely.
 
-## CRITICAL STEP COMPLETION NOTE
+  Then load, read the full file, and execute `{nextStepFile}` — the health-check step is the true terminal step of this workflow.
+
+#### EXECUTION RULES:
 
-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 refine-architecture workflow is fully done. The refined architecture at `{outputFile}` contains the full original content plus all gap-fills, issue annotations, and improvement suggestions backed by skill API evidence.
+- This is the exit gate: halt for the user's choice. [R] walks every refinement with its evidence (repeatable — re-shows this menu after each pass); [X] chains to the health check, the true workflow exit. Headless auto-selects [X].
 

package/src/skf-rename-skill/SKILL.md

@@ -21,7 +21,7 @@ Renames a skill across all its versions with transactional safety — copy to th
 
 ## Role
 
-You are Ferris in Management mode — a precision surgeon who operates on the entire skill group atomically. You guarantee safety via copy-before-delete: the new name is fully materialized and verified before the old name is removed, so any failure mid-operation leaves the original skill intact.
+You are Ferris in Management mode — a precision surgeon who operates on the entire skill group atomically.
 
 ## Workflow Rules
 
@@ -31,7 +31,7 @@ These rules apply to every step in this workflow:
 - Never proceed past a verification failure — roll back (delete new directories) and halt
 - Never allow a rename to collide with an existing skill name
 - 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
+- If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread — **except** the atomicity and commit-gate safety helpers that execute.md §0 resolves: a missing one there is a HARD HALT (exit 4), never an LLM fall-through, because hand-driven writes/scans would silently regress the transactional guarantees that keep a failed rename recoverable
 - 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
@@ -53,32 +53,19 @@ These rules apply to every step in this workflow:
 | **Flags** | `--headless` / `-H` (auto-resolve all gates); `--dry-run` (run selection + validation + display the §8 confirmation block, then exit with `status="dry-run"` — no copy, no manifest re-key, no delete). Useful for verifying the rename plan before the irreversible §8 (delete old) section. |
 | **Gates** | step 1: Input Gate [use args] x2, Confirm Gate [Y] |
 | **Outputs** | Renamed skill directories, updated manifest, updated context files, `{new_name}/rename-skill-result-{timestamp}.json` and `{new_name}/rename-skill-result-latest.json` |
-| **Concurrency** | Two simultaneous rename runs against the same `old_name` would corrupt state mid-copy. select.md §4b acquires a PID-file lock at `{forge_data_folder}/{old_name}/.skf-rename.lock` once `old_name` is resolved; live-PID collisions HALT with `halt_reason: "halted-for-concurrent-run"`. Stale locks (dead PID) are cleared silently with a warning. The lock is released by the terminal health-check step (step 4) and by every documented halt path. |
+| **Concurrency** | A PID-file lock at `{forge_data_folder}/{old_name}/.skf-rename.lock` serializes concurrent runs against the same `old_name`; a live-PID collision HALTs with `halt_reason: "halted-for-concurrent-run"` (exit 5). See select.md §4b for the acquire / stale-clear / release mechanism. |
 | **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. The §6 source-authority warning HALTs by default in headless when `source_authority="official"`; set `force_source_authority_in_headless = "true"` in `customize.toml` to auto-acknowledge and proceed (the override is recorded in `headless_decisions[]`). |
-| **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 4 (terminal)                                                                           |
-| 2    | input-missing / input-invalid | step 1 §4/§5 (headless missing `old_name`/`new_name` arg) → `input-missing`; new name fails kebab-case / length / same-as-old → `input-invalid` |
-| 3    | resolution-failure   | step 1 §2 (manifest is malformed JSON); step 1 §3 (no skills found anywhere)               |
-| 4    | write-failure        | On-Activation §3 pre-flight write probe (skills_output_folder / forge_data_folder unwritable); step 2 §1 (copy); step 2 §3 (file content update); step 2 §6 (manifest write); step 2 §7 (context-file rewrite) |
-| 5    | state-conflict       | step 1 §5 (name-collision check fails: target name already in use); step 1 §6 (source-authority="official" headless without `force_source_authority_in_headless`); concurrency lock collision (`halted-for-concurrent-run`) |
-| 6    | user-cancelled       | step 1 §6 (source-authority warning [N]); step 1 §8 confirmation gate `[N]`; any prompt that accepted `cancel`/`exit`/`:q` |
+| **Exit codes** | Stable per-failure-class codes — see `references/exit-codes.md` |
 
 ## Result Contract (Headless)
 
 When `{headless_mode}` is true, step 3 emits a single-line JSON envelope on **stdout** before chaining to step 4, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
 
 ```
-SKF_RENAME_SKILL_RESULT_JSON: {"status":"success|error|dry-run","old_name":"…|null","new_name":"…|null","versions_renamed":[],"manifest_rekeyed":false,"context_files_updated":[],"exit_code":0,"halt_reason":null}
+SKF_RENAME_SKILL_RESULT_JSON: {"status":"success|error|dry-run","old_name":"…|null","new_name":"…|null","versions_renamed":[],"manifest_rekeyed":false,"context_files_updated":[],"exit_code":0,"halt_reason":null,"headless_decisions":[]}
 ```
 
-`status` is `"success"` on the terminal happy path, `"dry-run"` when `--dry-run` was set and the workflow exited before §9 stores decisions, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"manifest-corrupt"`, `"nothing-to-rename"`, `"name-collision"`, `"source-authority-blocked"`, `"halted-for-concurrent-run"`, `"copy-failed"`, `"verify-failed"`, `"manifest-write-failed"`, `"context-rebuild-failed"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above.
+`status` is `"success"` on the terminal happy path, `"dry-run"` when `--dry-run` was set and the workflow exited before §9 stores decisions, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"manifest-corrupt"`, `"nothing-to-rename"`, `"name-collision"`, `"source-authority-blocked"`, `"halted-for-concurrent-run"`, `"copy-failed"`, `"verify-failed"`, `"manifest-write-failed"`, `"write-failed"`, `"user-cancelled"`. (§7 context-file rebuild is best-effort and never halts, so it has no `halt_reason`.) `exit_code` matches `references/exit-codes.md`. `headless_decisions` is the audit trail of confirmation gates auto-resolved under `{headless_mode}` — each entry `{gate, default_action, taken_action, reason}` (the §6 source-authority override and the §8 auto-confirm); it is `[]` in interactive runs and whenever no gate was auto-resolved before the envelope was emitted.
 
 ## On Activation
 
@@ -105,13 +92,16 @@ SKF_RENAME_SKILL_RESULT_JSON: {"status":"success|error|dry-run","old_name":"…|
 
    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 scalar.
 
-   Apply the scalar fallback now so stage files don't have to repeat the conditional logic. For each of the three scalars, if the merged value is empty or absent, the bundled default applies:
+   Apply the scalar fallback now so stage files don't have to repeat the conditional logic. For each of the four scalars, if the merged value is empty or absent, the bundled default applies:
 
    - `{forceSourceAuthorityInHeadless}` ← `workflow.force_source_authority_in_headless` (empty or non-`"true"` = HALT in headless on `"official"` source-authority)
    - `{unknownIdeDefaultContextFile}` ← `workflow.unknown_ide_default_context_file` if non-empty, else `AGENTS.md`
    - `{unknownIdeDefaultSkillRoot}` ← `workflow.unknown_ide_default_skill_root` if non-empty, else `.agents/skills/`
+   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string (no-op — step 3 skips the post-completion hook invocation)
+
+   Stash all four 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.
+   Then apply the resolved array surfaces so they are not silent no-ops: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (entries prefixed `file:` are paths or globs whose contents load as facts — the bundled default loads any `project-context.md` so rename-policy and public-name-stability guardrails stay in mind); and after activation completes, execute each entry in `workflow.activation_steps_append` in order.
 
 4. **Pre-flight write probe.** Verify both `{skills_output_folder}` and `{forge_data_folder}` are writable. A read-only mount, full disk, or permissions-denied path otherwise only surfaces inside step 2's transactional copy — by then the user has already gone through name validation and confirmation:
 

package/src/skf-rename-skill/customize.toml

@@ -1,6 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-rename-skill.
+# Team overrides:     _bmad/custom/skf-rename-skill.toml (under {project-root})
+# Personal overrides: _bmad/custom/skf-rename-skill.user.toml (under {project-root})
 
 [workflow]
 
@@ -34,6 +36,14 @@ persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
 
+# Optional post-completion hook. When non-empty, invoked with
+# `--result-path=<path>` in step 3 after the rename result JSON is
+# finalized (before the terminal health-check step). Failures are logged
+# but never fail the workflow — the rename is already committed. Use for
+# an audit-log emit, skill-registry re-index, or a post-rename notifier.
+
+on_complete = ""
+
 # --- Optional safety + default scalars ---
 #
 # Auto-acknowledge the source-authority="official" warning in headless mode.