bmad-module-skill-forge 1.4.0 → 1.5.0

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

@@ -1,8 +1,13 @@
 ---
-outputFile: '{output_folder}/refined-architecture-{project_name}.md'
-nextStepFile: './step-07-health-check.md'
+# {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'
+nextStepFile: 'health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Render the user-facing summary in {document_output_language}. -->
+
 # Step 6: Present Report
 
 ## STEP GOAL:
@@ -17,8 +22,6 @@ Present the complete refinement summary to the user. Display counts of gaps fill
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Load Refined Document
 
 Read the `{outputFile}` to have all data available for presentation.
@@ -81,7 +84,13 @@ Re-run **[RA] Refine Architecture** anytime after updating your skills or archit
 
   ### Result Contract
 
-  Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{output_folder}/refine-architecture-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{output_folder}/refine-architecture-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include the refined architecture doc path in `outputs`; include `gap_count`, `issue_count`, and `improvement_count` in `summary`.
+  Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{outputFolderPath}/refine-architecture-result-{timestamp}.json` (reuse the activation-stored `{timestamp}`, resolution to seconds) and a copy at `{outputFolderPath}/refine-architecture-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include the refined architecture doc path in `outputs`; include `gap_count`, `issue_count`, and `improvement_count` in `summary`. On any write failure: HALT (exit code 4, `halt_reason: "write-failed"`) and emit the error envelope.
+
+  When `{headless_mode}` is true, also emit the single-line envelope on **stdout** before chaining to step 7 (matches the SKILL.md "Result Contract (Headless)" shape):
+
+  ```
+  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.
 

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

@@ -9,6 +9,16 @@ description: Rename a skill across all its versions — transactional copy-verif
 
 Renames a skill across all its versions with transactional safety — copy to the new name, verify all references updated, delete the old name only after verification succeeds. Rebuilds platform context files to reference the new name. The agentskills.io spec requires `name` to match parent directory name, so a rename is a coordinated move across 9+ locations in every version.
 
+## Conventions
+
+- Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+- **Module-level path exception:** paths starting with `knowledge/` or `shared/` resolve from the SKF module root, not the skill root — install layout puts both at `{project-root}/_bmad/skf/`. The `versionPathsKnowledge: 'knowledge/version-paths.md'` frontmatter scalar in stage files uses this convention; same for `shared/health-check.md` chained from the terminal step.
+- **Cross-skill data coupling:** `references/execute.md` reads `skf-export-skill/assets/managed-section-format.md` for the IDE→context-file mapping table and the skill-index rebuild rules when re-keying context files post-rename. Rename-skill assumes that asset is present at install time and that its semantics are stable across the two skills' versions.
+
 ## 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.
@@ -20,39 +30,99 @@ These rules apply to every step in this workflow:
 - Never delete the old skill directories until the new name has been fully materialized and verified
 - Never proceed past a verification failure — roll back (delete new directories) and halt
 - Never allow a rename to collide with an existing skill name
-- Read each step file completely before taking any action
-- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
 - Only load one step file at a time — never preload future steps
 - If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
 - Always communicate in `{communication_language}`
+- At any interactive prompt, the inputs `cancel`, `exit`, `[X]`, `q`, or `:q` exit cleanly with exit code 6 (`halt_reason: "user-cancelled"`)
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
-| 1 | Select & Validate | steps-c/step-01-select.md | No (confirm) |
-| 2 | Execute Rename | steps-c/step-02-execute.md | No (confirm) |
-| 3 | Report | steps-c/step-03-report.md | Yes |
-| 4 | Workflow Health Check | steps-c/step-04-health-check.md | Yes |
+| 1 | Select & Validate | references/select.md | No (confirm) |
+| 2 | Execute Rename | references/execute.md | No (confirm) |
+| 3 | Report | references/report.md | Yes |
+| 4 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
 | **Inputs** | old_name [required], new_name [required] |
-| **Gates** | step-01: Input Gate [use args] x2, Confirm Gate [Y] |
-| **Outputs** | Renamed skill directories, updated manifest, updated context files |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **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. |
+| **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` |
+
+## 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}
+```
+
+`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.
 
 ## On Activation
 
 1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
    - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
    - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
-   - `snippet_skill_root_override` (optional string) — when set, the context-file rebuild in step-02 preserves any snippet `root:` prefix that matches the override instead of rewriting it to the target IDE's skill root. See `skf-export-skill/assets/managed-section-format.md` for full semantics.
+   - `snippet_skill_root_override` (optional string) — when set, the context-file rebuild in step 2 preserves any snippet `root:` prefix that matches the override instead of rewriting it to the target IDE's skill root. See `skf-export-skill/assets/managed-section-format.md` for full semantics.
    - Generate and store `timestamp` as `YYYYMMDD-HHmmss` format. This value is fixed for the entire workflow run.
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
+
+3. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-root} --key workflow
+   ```
+
+   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+
+   - `{skill-root}/customize.toml` — bundled defaults
+   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
+   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+
+   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each 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:
+
+   - `{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/`
+
+   Stash all three as workflow-context variables. Stage files reference them directly — no conditional at the usage site.
+
+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:
+
+   ```bash
+   for dir in "{skills_output_folder}" "{forge_data_folder}"; do
+     mkdir -p "$dir" && \
+       printf 'probe' > "$dir/.skf-write-probe" && \
+       rm "$dir/.skf-write-probe"
+   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 `old_name: null` and `new_name: null` (neither is resolved yet at activation time).
 
-3. Load, read the full file, and then execute `./steps-c/step-01-select.md` to begin the workflow.
+5. Load, read the full file, and then execute `references/select.md` to begin the workflow.

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

@@ -0,0 +1,52 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-rename-skill.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (uv probe, config load).
+# Overrides append. Use for org-wide pre-flight checks (audit-log emit,
+# ticket-reference enforcement) that must precede any rename work.
+
+activation_steps_prepend = []
+
+# Steps to run after activation but before the first stage executes.
+# Overrides append. Use for context loads or banner customization that
+# should run once activation completes successfully.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (rename-policy reminders, public-name-stability rules, audit guardrails).
+# Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Renames of skills tagged `published` require approval."
+#   - a file reference prefixed with `file:`, e.g.
+#     "file:{project-root}/docs/rename-policy.md" (globs supported; file
+#     contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# --- Optional safety + default scalars ---
+#
+# Auto-acknowledge the source-authority="official" warning in headless mode.
+# Empty string = HALT in headless when source_authority is "official"
+# (the safe default — local renames diverge from any registry-published
+# name). Set to "true" to silently proceed and record the override in the
+# headless decision trail.
+
+force_source_authority_in_headless = ""
+
+# Fallback IDE → context-file mapping for unknown IDEs in `config.yaml.ides`.
+# Empty string = use bundled defaults (AGENTS.md / .agents/skills/).
+# Used by execute.md §7 when rebuilding context files.
+
+unknown_ide_default_context_file = ""
+unknown_ide_default_skill_root = ""

package/src/skf-rename-skill/{steps-c/step-02-execute.md → references/execute.md}

@@ -1,19 +1,48 @@
 ---
-nextStepFile: './step-03-report.md'
+nextStepFile: 'report.md'
 versionPathsKnowledge: 'knowledge/version-paths.md'
 managedSectionLogic: 'skf-export-skill/assets/managed-section-format.md'
+# Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in
+# order (installed SKF module path first, src/ dev-checkout fallback);
+# first existing path wins. §3 + §6 use it for crash-safe file rewrites
+# (stage to .skf-tmp, fsync, rename) — letting the LLM write directly
+# risks half-written artifacts on process kill or disk-full mid-write.
+# HALT if neither candidate exists.
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+# Resolve `{updateActiveSymlinkHelper}` similarly. §4 uses it to
+# atomically repair the `active` symlink with `flock` and the Windows
+# junction fallback — `rm + ln -s` would race against concurrent readers
+# and silently break on Windows.
+updateActiveSymlinkProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-update-active-symlink.py'
+  - '{project-root}/src/shared/scripts/skf-update-active-symlink.py'
+# Resolve `{manifestOpsHelper}` similarly. §6 uses the `rename` action
+# for atomic re-key (preserves `active_version`, `versions` map, all
+# fields, then writes via temp + rename).
+manifestOpsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-manifest-ops.py'
+  - '{project-root}/src/shared/scripts/skf-manifest-ops.py'
+# Resolve `{rebuildManagedSectionsHelper}` similarly. §7.7 uses the
+# `replace` action for the surgical between-marker rewrite.
+rebuildManagedSectionsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-rebuild-managed-sections.py'
+  - '{project-root}/src/shared/scripts/skf-rebuild-managed-sections.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 2: Execute Rename (Transactional)
 
 ## STEP GOAL:
 
-Execute the rename decisions recorded in step-01 as a transaction. Copy the old `{skill_group}` and `{forge_group}` to the new name, rename inner directories, rewrite every in-file reference, verify no trace of the old name remains inside the new location, update the export manifest, rebuild platform context files, and only then delete the old directories. Any failure before the final delete rolls back by removing the new directories — the old skill remains intact.
+Execute the rename decisions recorded in step 1 as a transaction. Copy the old `{skill_group}` and `{forge_group}` to the new name, rename inner directories, rewrite every in-file reference, verify no trace of the old name remains inside the new location, update the export manifest, rebuild platform context files, and only then delete the old directories. Any failure before the final delete rolls back by removing the new directories — the old skill remains intact.
 
 ## Rules
 
 - Execute sections strictly in order — each section depends on the previous one
-- Do not re-prompt the user — decisions were made in step-01
+- Do not re-prompt the user — decisions were made in step 1
 - Do not delete anything from old directories before section 8
 - Do not proceed past a verification failure in section 5
 - Report each section's outcome as it completes
@@ -22,15 +51,26 @@ Execute the rename decisions recorded in step-01 as a transaction. Copy the old
 
 **CRITICAL:** This is transactional. After section 1 (copy), the old skill is untouched. If any section between 2 and 7 fails, delete `{new_skill_group}` and `{new_forge_group}`, report the failure, and halt — the old skill remains intact. Only section 8 (delete old) makes the operation irreversible. Do not skip, reorder, or improvise.
 
-### 0. Re-read Version-Paths Knowledge
+### 0. Re-read Version-Paths Knowledge + Resolve Helpers
 
 Read `{versionPathsKnowledge}` again and confirm the templates (`{skill_package}`, `{skill_group}`, `{forge_version}`, `{forge_group}`) and the Rename section. Also read `{managedSectionLogic}` for the managed-section format template and the skill index rebuild rules that will be reused in section 7.
 
+**Resolve helpers** in parallel — these are independent file-existence checks that batch into one tool-call message:
+
+- `{atomicWriteHelper}` ← first existing path in `{atomicWriteProbeOrder}` (used in §3, §6 for crash-safe writes)
+- `{updateActiveSymlinkHelper}` ← first existing path in `{updateActiveSymlinkProbeOrder}` (used in §4 for atomic symlink repair)
+- `{manifestOpsHelper}` ← first existing path in `{manifestOpsProbeOrder}` (used in §6 for the manifest re-key)
+- `{rebuildManagedSectionsHelper}` ← first existing path in `{rebuildManagedSectionsProbeOrder}` (used in §7.7 for between-marker swap)
+
+If any helper has no existing candidate, release the lock and HALT (exit code 4, `halt_reason: "write-failed"`) — the rename's safety guarantees depend on these helpers and a fall-through to LLM-driven writes would silently regress atomicity.
+
+**Lock release contract:** every halt path in this step ends with `rm -f "{forge_data_folder}/{old_name}/.skf-rename.lock"` before exiting. The terminal health-check (step 4) is the success-path release.
+
 ### 1. Copy skill_group and forge_group
 
-**Precondition:** Both `{new_skill_group}` and `{new_forge_group}` must NOT exist (step-01 validated this in the collision check, but verify again before copying).
+**Precondition:** Both `{new_skill_group}` and `{new_forge_group}` must NOT exist (step 1 validated this in the collision check, but verify again before copying).
 
-1. If `{new_skill_group}` or `{new_forge_group}` exists on disk, halt with: "**Collision detected at execution time.** `{new_skill_group}` or `{new_forge_group}` now exists on disk — it did not exist during step-01 selection. Aborting before any files are touched."
+1. If `{new_skill_group}` or `{new_forge_group}` exists on disk, halt with: "**Collision detected at execution time.** `{new_skill_group}` or `{new_forge_group}` now exists on disk — it did not exist during step 1 selection. Aborting before any files are touched."
 
 2. Copy `{old_skill_group}` to `{new_skill_group}` recursively:
    - Preserve file permissions, timestamps, and symlinks
@@ -64,17 +104,24 @@ Report: "**Renamed {count} inner directories** to `{new_name}/`."
 
 For each version `v` in `affected_versions`, operate on the files inside `{new_skill_group}/{v}/{new_name}/` (the freshly renamed inner directory) and `{new_forge_group}/{v}/`:
 
+**Write semantics (apply to 3a / 3b / 3c / 3d):** Compute the new file content in memory (LLM judgment work), then pipe it to `{atomicWriteHelper} write <target>` so the rewrite is staged in `<target>.skf-tmp`, fsync'd, and atomically renamed into place. A process kill or disk-full event mid-rewrite leaves the original file intact — no half-written artifacts.
+
+```bash
+echo "{new_content}" | python3 {atomicWriteHelper} write "{target_path}"
+```
+
 **3a. SKILL.md frontmatter:**
 
 - Path: `{new_skill_group}/{v}/{new_name}/SKILL.md`
 - In the YAML frontmatter (between the leading `---` markers), replace the `name:` field value from `{old_name}` to `{new_name}`
 - Only replace within the frontmatter block — do not substitute matches inside the body text
+- Pipe via `{atomicWriteHelper} write` per the write semantics above
 - If the file is missing, record it in `section3_warnings` and continue
 
 **3b. metadata.json:**
 
 - Path: `{new_skill_group}/{v}/{new_name}/metadata.json`
-- Parse the JSON, set `name` = `{new_name}`, write back preserving formatting
+- Parse the JSON, set `name` = `{new_name}`, write back preserving formatting via `{atomicWriteHelper} write`
 - If the file is missing, record it in `section3_warnings` and continue
 
 **3c. context-snippet.md:**
@@ -85,36 +132,43 @@ For each version `v` in `affected_versions`, operate on the files inside `{new_s
   - Example: `root: .windsurf/skills/{old_name}/` → `root: .windsurf/skills/{new_name}/`
   - Example: `root: skills/{old_name}/` → `root: skills/{new_name}/`
   - Legacy pre-fix form `root: skills/{old_name}/active/{old_name}/` → `root: skills/{new_name}/` (normalize to flat form during rename)
+- Pipe via `{atomicWriteHelper} write` per the write semantics above
 - If the file is missing, record it in `section3_warnings` and continue
 
 **3d. provenance-map.json:**
 
 - Path: `{new_forge_group}/{v}/provenance-map.json`
-- Parse JSON, set `skill_name` = `{new_name}`, write back preserving formatting
+- Parse JSON, set `skill_name` = `{new_name}`, write back via `{atomicWriteHelper} write`
 - If the file is missing (some versions may not have a provenance map), record it in `section3_warnings` and continue
 
 **Rollback on any update failure (not just a missing file):**
 
 - `rm -rf {new_skill_group}` and `rm -rf {new_forge_group}`
-- Halt with: "**File update failed** at `{path}`: {error}. Rolled back both new directories. Old skill is intact."
+- Release the lock: `rm -f "{forge_data_folder}/{old_name}/.skf-rename.lock"`
+- Halt with: "**File update failed** at `{path}`: {error}. Rolled back both new directories. Old skill is intact." HALT (exit code 4, `halt_reason: "write-failed"`). In headless, emit the error envelope.
 
 Report: "**Updated file contents** across {affected_versions_count} version(s): SKILL.md, metadata.json, context-snippet.md, provenance-map.json."
 
 ### 4. Fix the `active` Symlink in the New Location
 
-Recreate or repair the `active` symlink in `{new_skill_group}`:
+Recreate or repair the `active` symlink in `{new_skill_group}` via `{updateActiveSymlinkHelper}` — the helper holds an `flock` on `{new_skill_group}/active.lock`, surfaces a clear error on Windows non-dev-mode (no silent fallback), and uses the `ln -sfn tmp && mv -Tf tmp link` pattern to make the flip atomic against concurrent readers.
 
-1. Inspect `{old_skill_group}/active` to determine the target version (the value the symlink points to — typically just the version string, not an absolute path)
-2. Check `{new_skill_group}/active`:
-   - If the copy in section 1 preserved it correctly and it points to the same version string → leave it as-is
-   - If it exists but points somewhere invalid (e.g., an absolute path back into the old location) → remove and recreate it
-   - If it is missing (some copy tools do not preserve symlinks) → create it
-3. The symlink target should be a relative path: the version string alone (e.g., `0.6.0`), so that `{new_skill_group}/active/{new_name}/` resolves correctly
+1. Inspect `{old_skill_group}/active` to determine the target version (the value the symlink points to — typically just the version string, not an absolute path). If `{old_skill_group}/active` does not exist, skip this section — there is no symlink to repair.
+2. Invoke:
 
-**Rollback on failure:**
+   ```bash
+   python3 {updateActiveSymlinkHelper} flip-link \
+     --link {new_skill_group}/active \
+     --target {target_version}
+   ```
+
+3. The helper handles all four cases (missing, present-and-correct, present-and-stale, present-and-invalid) uniformly via atomic replace.
+
+**Rollback on helper non-zero exit:**
 
 - `rm -rf {new_skill_group}` and `rm -rf {new_forge_group}`
-- Halt with: "**Failed to repair `active` symlink** in `{new_skill_group}`: {error}. Rolled back both new directories. Old skill is intact."
+- Release the lock: `rm -f "{forge_data_folder}/{old_name}/.skf-rename.lock"`
+- Halt with: "**Failed to repair `active` symlink** in `{new_skill_group}`: {captured stderr}. Rolled back both new directories. Old skill is intact." HALT (exit code 4, `halt_reason: "write-failed"`). In headless, emit the error envelope.
 
 ### 5. Verify — No Trace of `{old_name}` Inside the New Location
 
@@ -136,13 +190,14 @@ Also check the directory listing itself:
 **On hard failure (any structural reference to `{old_name}` remains):**
 
 - `rm -rf {new_skill_group}` and `rm -rf {new_forge_group}`
-- Halt with: "**Verification failed.** `{old_name}` still appears in: {list of paths}. Rolled back both new directories. Old skill is intact."
+- Release the lock: `rm -f "{forge_data_folder}/{old_name}/.skf-rename.lock"`
+- Halt with: "**Verification failed.** `{old_name}` still appears in: {list of paths}. Rolled back both new directories. Old skill is intact." HALT (exit code 5, `halt_reason: "verify-failed"`). In headless, emit the error envelope.
 
 Report: "**Verified** — no structural references to `{old_name}` remain inside the new location across {affected_versions_count} version(s). {if verification_warnings is non-empty: 'Informational body-text mentions retained in SKILL.md: {list}.'}"
 
 ### 6. Update Export Manifest
 
-**If `manifest_exists = false` (step-01 recorded no manifest on disk):**
+**If `manifest_exists = false` (step 1 recorded no manifest on disk):**
 
 Skip this section entirely. Set `manifest_updated = false` and `manifest_backup = null`. There is no manifest to re-key — the skill was never exported. Section 7 will find no platform context files to rebuild either (no manifest means no prior export, so no `<!-- SKF:BEGIN -->` markers exist), and any platform file that happens to be present will be left alone by the section 2 marker check.
 
@@ -150,19 +205,21 @@ Report: "**Manifest update skipped** — no `.export-manifest.json` on disk. The
 
 **If `manifest_exists = true`:**
 
-1. Load `{skills_output_folder}/.export-manifest.json`
-2. **Hold a deep copy in memory** as `manifest_backup` — required for rollback in this section and section 7 on failure
-3. If the manifest contains `exports.{old_name}`:
-   - Set `exports.{new_name}` = deep copy of `exports.{old_name}` (preserving `active_version`, `versions` map, and all fields)
-   - Delete `exports.{old_name}`
-4. If the manifest does NOT contain `exports.{old_name}` (the skill was on disk but never exported), skip the re-key — the manifest has nothing to change for this skill
-5. Write the updated manifest back to `{skills_output_folder}/.export-manifest.json`
+1. **Hold a deep copy in memory** as `manifest_backup` — required for rollback in this section and section 7 on failure. Read `{skills_output_folder}/.export-manifest.json` once and stash the parsed object.
+2. **Re-key via the helper.** If the manifest contains `exports.{old_name}`, invoke:
+
+   ```bash
+   python3 {manifestOpsHelper} {skills_output_folder} rename {old_name} {new_name}
+   ```
 
-**Rollback on write failure:**
+   The helper preserves `active_version`, `versions` map, and all fields, then writes the manifest atomically via temp + rename. If the manifest does NOT contain `exports.{old_name}` (the skill was on disk but never exported), skip the invocation — the manifest has nothing to change.
 
-- Restore the manifest from `manifest_backup` (write it back to disk)
+**Rollback on helper non-zero exit:**
+
+- Restore the manifest from `manifest_backup` via `{atomicWriteHelper} write {skills_output_folder}/.export-manifest.json` (re-pipe the JSON-serialized backup)
 - `rm -rf {new_skill_group}` and `rm -rf {new_forge_group}`
-- Halt with: "**Manifest update failed:** {error}. Restored manifest from backup and rolled back new directories. Old skill is intact."
+- Release the lock: `rm -f "{forge_data_folder}/{old_name}/.skf-rename.lock"`
+- Halt with: "**Manifest update failed:** {captured stderr}. Restored manifest from backup and rolled back new directories. Old skill is intact." HALT (exit code 4, `halt_reason: "manifest-write-failed"`). In headless, emit the error envelope.
 
 Set context flag `manifest_updated = true`.
 
@@ -170,78 +227,16 @@ Report: "**Manifest updated** — re-keyed `exports.{old_name}` → `exports.{ne
 
 ### 7. Rebuild Context Files
 
-Load the `ides` list from `config.yaml`. The installer writes IDE identifiers — these must be mapped to context files and skill roots using the "IDE → Context File Mapping" table in `{managedSectionLogic}`.
-
-**Resolve `target_context_files`** using the canonical mapping table in `{managedSectionLogic}`:
-
-1. For each entry in `config.yaml.ides`, look up its `context_file` and `skill_root` from the mapping table
-2. For any entry not found in the table, default to AGENTS.md / `.agents/skills/` and emit a warning: "Unknown IDE '{value}' in config.yaml — defaulting to AGENTS.md"
-3. Deduplicate by `context_file` — when multiple IDEs map to the same context file, use the first configured IDE's `skill_root`
-4. If `config.yaml.ides` is absent or the mapping yields an empty list, fall back to `[{context_file: "AGENTS.md", skill_root: ".agents/skills/"}]` and emit a note: "No IDEs configured in config.yaml — defaulting to AGENTS.md"
-
-Store the result as `target_context_files` for this section.
-
-For each entry in `target_context_files`:
-
-1. **Resolve target file** at `{context_file}`.
-
-2. **Read the current file.**
-   - If the file does not exist, skip this context file (nothing to rebuild — the file will be re-created next time export-skill runs)
-   - If the file exists but contains no `<!-- SKF:BEGIN -->` marker, skip this context file (no managed section to rewrite)
-   - If the file contains `<!-- SKF:BEGIN -->` but no matching `<!-- SKF:END -->`, record the error against that context file and continue to the next entry — do not halt the entire rename on a malformed context file
-
-3. **Build the exported skill set (version-aware, deprecated-excluded)** using the same logic as export-skill step-04 section 4b and the snippet resolution logic from section 4c:
-   - Read the manifest's `exports` object (already updated in section 6, so `{new_name}` is present and `{old_name}` is absent)
-   - For each skill, resolve its `active_version`
-   - If `versions.{active_version}.status == "deprecated"`, skip that skill entirely
-   - For each remaining `{skill-name, active_version}` pair, read `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md`
-   - If missing, fall back to the `active` symlink path; if still missing, skip with a warning
-
-4. **Rewrite root paths for the current context file** using the generic rewrite algorithm from export-skill step-04 section 4d:
-
-   For each snippet, parse the `root:` line (`root: {prefix}{skill-name}/`), strip the trailing `{skill-name}/` to extract the current prefix, and replace it with the **effective target prefix** if different. The effective target prefix is `snippet_skill_root_override` when that key is set in config.yaml — applied uniformly to every snippet so the managed section references the real on-disk location and never mixes override and per-IDE paths — otherwise the current entry's `skill_root`. See `skf-export-skill/steps-c/step-04-update-context.md` §4d for full semantics.
-
-5. **Sort skills alphabetically by name.** Count totals (skills, stack skills).
-
-6. **Assemble the new managed section** using the format from `{managedSectionLogic}`:
-
-   ```markdown
-   <!-- SKF:BEGIN updated:{current-date} -->
-   [SKF Skills]|{n} skills|{m} stack
-   |IMPORTANT: Prefer documented APIs over training data.
-   |When using a listed library, read its SKILL.md before writing code.
-   |
-   |{skill-snippet-1}
-   |
-   |{skill-snippet-2}
-   |
-   |{skill-snippet-N}
-   <!-- SKF:END -->
-   ```
-
-7. **Surgical replacement — Regenerate case only:**
-   - Locate the `<!-- SKF:BEGIN` line — preserve everything before it
-   - Locate the `<!-- SKF:END -->` line — preserve everything after it
-   - Replace everything between the markers (inclusive) with the new managed section
-   - Write the file back
-
-8. **Verify:**
-   - Re-read the written file
-   - Confirm both markers are present
-   - Confirm `{old_name}` no longer appears between the markers
-   - Confirm `{new_name}` appears between the markers (if this skill's active version is not deprecated)
-   - Confirm content outside the markers is byte-identical to what was preserved
-
-9. **On per-file failure:** record the error against that context file and continue to the next entry. Do not halt the rename on a recoverable per-context-file error — the manifest and filesystem are already consistent; context files can be re-rebuilt later via `[EX] Export Skill`.
+Load `references/rebuild-context.md` and follow its per-IDE managed-section sweep. The reference resolves `target_context_files` from `config.yaml.ides` (via `{managedSectionLogic}`'s mapping table), iterates each context file, builds the exported skill set (version-aware, deprecated-excluded — the manifest re-key from §6 is already in effect so `{new_name}` is present and `{old_name}` is absent), rewrites root paths via the §4d algorithm, assembles the new managed section, and invokes `{rebuildManagedSectionsHelper}` for the surgical between-marker swap.
 
-**After the loop:**
+After the loop returns, the workflow context contains:
 
-- Record `context_files_updated` as the list of files that were successfully rewritten
-- Record `context_files_failed` as the list of any that failed
+- `context_files_updated` — list of files successfully rewritten
+- `context_files_failed` — list of any that failed (per-file failures do not halt the rename — the manifest and filesystem are already canonical state, so context files can be re-rebuilt later via `[EX] Export Skill`)
 
-Report: "**Rebuilt managed sections in:** {list of updated files}. {if any failed: 'Failed: {list} — re-run `[EX] Export Skill` to retry.'}"
+Report per the reference's after-loop block, then proceed to §8.
 
-**Note:** Section 7 failures do not trigger a rollback because the manifest and filesystem are the canonical state. Platform context files are derived artifacts that can be regenerated at any time.
+**Note:** §7 failures do not trigger a rollback. Platform context files are derived artifacts; the manifest and on-disk skill directories are the canonical state.
 
 ### 8. Delete Old Directories (Point of No Return)
 
@@ -272,7 +267,7 @@ Report: "**Deleted old directories:** `{old_skill_group}` and `{old_forge_group}
 
 ### 9. Store Results in Context
 
-Store the following for step-03:
+Store the following for step 3:
 
 - `old_name` — the previous skill name
 - `new_name` — the new skill name

package/src/skf-rename-skill/references/health-check.md

@@ -0,0 +1,30 @@
+---
+# Note: `shared/health-check.md` resolves relative to the SKF module root
+# ({project-root}/_bmad/skf/ when installed, {project-root}/src/ during
+# development), NOT relative to this step file.
+nextStepFile: 'shared/health-check.md'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 4: Workflow Health Check
+
+## STEP GOAL:
+
+Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of rename-skill — after the shared health check completes, the workflow is fully done.
+
+## Rules
+
+- No user-facing reports, file writes, or result contracts in this step — those belong in step 3
+- Delegate directly to `{nextStepFile}` with no additional commentary
+- Do not attempt any other action between loading this step and executing `{nextStepFile}`
+
+## MANDATORY SEQUENCE
+
+1. **Release the rename lock.** Delete `{forge_data_folder}/{old_name}/.skf-rename.lock` if it still exists (the lock is acquired in select.md §4b and released here as the terminal cleanup). A no-op when `old_name` was never resolved or the lock was already removed by an earlier halt path.
+
+   ```bash
+   rm -f "{forge_data_folder}/{old_name}/.skf-rename.lock"
+   ```
+
+2. Load `{nextStepFile}`, read it fully, then execute it.