bmad-module-skill-forge 2.0.0 → 2.0.1

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
 
@@ -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 → `copy-failed`); step 2 §2 (inner-dir rename) / §3 (file content update) / §4 (symlink repair) → `write-failed`; step 2 §6 (manifest write → `manifest-write-failed`). step 2 §7 (context-file rewrite) is **best-effort and never halts** — per-file failures are recorded in `context_files_failed` and the rename still succeeds (manifest + disk are canonical; re-run `[EX] Export Skill` to retry). |
-| 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"`, `"write-failed"`, `"user-cancelled"`. (§7 context-file rebuild is best-effort and never halts, so it has no `halt_reason`.) `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.