bmad-module-skill-forge 2.0.0 → 2.0.1

package/src/skf-rename-skill/references/execute.md

@@ -24,11 +24,28 @@ updateActiveSymlinkProbeOrder:
 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
+# Resolve `{rebuildManagedSectionsHelper}` similarly. §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'
+# Resolve `{rewriteSkillNameHelper}` similarly. §3 uses it for the four
+# field-scoped in-file rename transforms (SKILL.md frontmatter `name`,
+# metadata.json `name`, provenance-map.json `skill_name`, context-snippet
+# header + `root:` paths) — each a JSON round-trip or anchored-region edit
+# plus the atomic write in one call, so the LLM never hand-edits JSON (which
+# risks key reorder/drop) or eyeballs "only within the frontmatter" (which
+# mis-fires when {old_name} is a substring, e.g. rename -> renamer).
+rewriteSkillNameProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-rewrite-skill-name.py'
+  - '{project-root}/src/shared/scripts/skf-rewrite-skill-name.py'
+# Resolve `{verifyNoTraceHelper}` similarly. §5 uses it for the commit-point
+# no-trace gate: a fixed-file-set, name-token scan over affected_versions with
+# the SKILL.md frontmatter/body region split (frontmatter = hard failure, body
+# = advisory warning) and the directory-listing check, returned as JSON.
+verifyNoTraceProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-verify-no-trace.py'
+  - '{project-root}/src/shared/scripts/skf-verify-no-trace.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -47,9 +64,17 @@ Execute the rename decisions recorded in step 1 as a transaction. Copy the old `
 - Do not proceed past a verification failure in section 5
 - Report each section's outcome as it completes
 
+**Headless error envelope (self-contained).** Every HALT below that says *"emit the error envelope"* means: write this single line to **stderr**, mirroring SKILL.md's Result Contract (Headless) so this stage stays parseable even if SKILL.md is out of context on a `nextStepFile` chain —
+
+```
+SKF_RENAME_SKILL_RESULT_JSON: {"status":"error","old_name":"{old_name}","new_name":"{new_name}","versions_renamed":[],"manifest_rekeyed":false,"context_files_updated":[],"exit_code":<code>,"halt_reason":"<reason>","headless_decisions":{headless_decisions}}
+```
+
+Set `exit_code` and `halt_reason` to the values named at that HALT site (see `references/exit-codes.md`); `old_name`/`new_name` are both resolved by step 1 before this stage runs. `{headless_decisions}` is the audit trail carried from step 1 (the §6 source-authority override if it fired; `[]` otherwise) — emit it verbatim so a halt in this stage still preserves the decision trail.
+
 ## MANDATORY SEQUENCE
 
-**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.
+**Transactional boundary.** After section 1 (copy), the old skill is untouched; a failure in any of sections 2-7 deletes the two new directories (`{new_skill_group}`, `{new_forge_group}`), reports, and halts with the old skill intact. Section 8 (delete old) is the only irreversible point.
 
 ### 0. Re-read Version-Paths Knowledge + Resolve Helpers
 
@@ -57,12 +82,14 @@ Read `{versionPathsKnowledge}` again and confirm the templates (`{skill_package}
 
 **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)
+- `{atomicWriteHelper}` ← first existing path in `{atomicWriteProbeOrder}` (used in §6 for crash-safe manifest restore)
+- `{rewriteSkillNameHelper}` ← first existing path in `{rewriteSkillNameProbeOrder}` (used in §3 for the field-scoped in-file rename transforms + atomic write)
 - `{updateActiveSymlinkHelper}` ← first existing path in `{updateActiveSymlinkProbeOrder}` (used in §4 for atomic symlink repair)
+- `{verifyNoTraceHelper}` ← first existing path in `{verifyNoTraceProbeOrder}` (used in §5 for the deterministic no-trace commit gate)
 - `{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)
+- `{rebuildManagedSectionsHelper}` ← first existing path in `{rebuildManagedSectionsProbeOrder}` (used in §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.
+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/scans would silently regress atomicity (the write helpers) or the deterministic transform and commit-gate checks (`{rewriteSkillNameHelper}`, `{verifyNoTraceHelper}`).
 
 **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.
 
@@ -103,44 +130,25 @@ Report: "**Renamed {count} inner directories** to `{new_name}/`."
 
 ### 3. Update File Contents Inside the New Location
 
-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}/`:
+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.
+**Transform semantics (apply to 3a / 3b / 3c / 3d):** `{rewriteSkillNameHelper}` performs each field-scoped substitution AND the crash-safe write (stage to `<target>.skf-tmp`, fsync, atomic rename) in one call — do NOT compute file content in the prompt. Each `--kind` edits exactly one field/region and leaves everything else byte-for-byte intact, so there is no key reorder/drop from hand-editing JSON and no wrong-region substitution when `{old_name}` is a substring (e.g. `rename` → `renamer`). Invoke it once per file:
 
 ```bash
-echo "{new_content}" | python3 {atomicWriteHelper} write "{target_path}"
+python3 {rewriteSkillNameHelper} "{target_path}" \
+  --kind {skill-frontmatter|metadata-json|context-snippet|provenance-json} \
+  --old-name {old_name} --new-name {new_name}
 ```
 
-**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:**
+Read the JSON result (`changed`, `wrote`, and per-kind fields). Exit 0 = processed (written only if the content changed). A non-zero exit — a missing structural region (no frontmatter delimiters), invalid JSON, or a write failure — is a **file update failure**: trigger the rollback below. Check file existence first: if the target file does not exist, skip the invocation and record it in `section3_warnings` per the per-item notes (a missing file is not a failure).
 
-- Path: `{new_skill_group}/{v}/{new_name}/metadata.json`
-- 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
+**3a. SKILL.md frontmatter** — `--kind skill-frontmatter` on `{new_skill_group}/{v}/{new_name}/SKILL.md`. Replaces the top-level `name:` value inside the frontmatter block only (anchored on `^name:`, so a nested `name:` or a longer key like `renamed:` is untouched); body text is preserved verbatim, so a legitimate mention of `{old_name}` below the closing `---` survives. If the file is missing, record it in `section3_warnings` and continue.
 
-**3c. context-snippet.md:**
+**3b. metadata.json** — `--kind metadata-json` on `{new_skill_group}/{v}/{new_name}/metadata.json`. Sets `name` = `{new_name}` via a JSON round-trip (key order preserved). If the file is missing, record it in `section3_warnings` and continue.
 
-- Path: `{new_skill_group}/{v}/{new_name}/context-snippet.md`
-- Replace the display name header `[{old_name} v...]` → `[{new_name} v...]` (preserving the version suffix)
-- Rewrite every `root:` path that references the old name to use the new name. Parse the `root:` line as `root: {prefix}{old_name}/`, preserve the prefix as-is, and replace `{old_name}` with `{new_name}`. This generically handles any IDE's skill root path (e.g., `.claude/skills/`, `.windsurf/skills/`, `.github/skills/`) as well as the draft `skills/` prefix and legacy forms — no enumeration of known prefixes needed.
-  - 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
+**3c. context-snippet.md** — `--kind context-snippet` on `{new_skill_group}/{v}/{new_name}/context-snippet.md`. Rewrites the display header `[{old_name} v...]` → `[{new_name} v...]` (version suffix preserved) and every `root:` path: it parses `root: {prefix}{old_name}/`, keeps the prefix verbatim, and swaps the trailing `{old_name}/` segment for `{new_name}/` — handling any IDE prefix (`.claude/skills/`, `.windsurf/skills/`, `.github/skills/`, the draft `skills/` prefix) generically, and flattening the legacy `root: skills/{old_name}/active/{old_name}/` form to `root: skills/{new_name}/`. 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 via `{atomicWriteHelper} write`
-- If the file is missing (some versions may not have a provenance map), record it in `section3_warnings` and continue
+**3d. provenance-map.json** — `--kind provenance-json` on `{new_forge_group}/{v}/provenance-map.json`. Sets `skill_name` = `{new_name}` via a JSON round-trip. 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):**
 
@@ -173,26 +181,24 @@ Recreate or repair the `active` symlink in `{new_skill_group}` via `{updateActiv
 
 ### 5. Verify — No Trace of `{old_name}` Inside the New Location
 
-This is the commit-point check. If any match is found, the rename is not safe to commit.
-
-For every version `v` in `affected_versions`, grep (literal substring, case-sensitive) for `{old_name}` in:
-
-- `{new_skill_group}/{v}/{new_name}/SKILL.md`
-- `{new_skill_group}/{v}/{new_name}/metadata.json`
-- `{new_skill_group}/{v}/{new_name}/context-snippet.md`
-- `{new_forge_group}/{v}/provenance-map.json`
+This is the commit-point check. If any structural reference to `{old_name}` remains, the rename is not safe to commit. `{verifyNoTraceHelper}` performs the whole scan deterministically — a fixed-file-set, name-token scan across every `affected_versions` entry, the SKILL.md frontmatter/body region split, and the directory-listing check — and returns the verdict as JSON. Invoke it once:
 
-Also check the directory listing itself:
-
-- `{new_skill_group}/{v}/` should contain `{new_name}/` and MUST NOT contain `{old_name}/`
+```bash
+python3 {verifyNoTraceHelper} "{new_skill_group}" \
+  --forge-group "{new_forge_group}" \
+  --old-name {old_name} --new-name {new_name} \
+  --versions {comma-separated affected_versions}
+```
 
-**Important nuance:** body text of SKILL.md may legitimately mention the old name (e.g., historical notes, changelog, cross-references). The grep is allowed to match within SKILL.md body text ONLY if the match is clearly informational (surrounding prose, not a structural reference). For the purposes of this step, treat any match in `metadata.json`, `context-snippet.md`, `provenance-map.json`, or the SKILL.md frontmatter block as a hard failure. Matches inside the SKILL.md body below the closing `---` are recorded as `verification_warnings` but do not block the rename.
+Per version `v`, the helper scans `SKILL.md` (frontmatter matches → `hard_matches`; matches in the body below the closing `---` → `body_warnings`), `metadata.json`, `context-snippet.md`, and `provenance-map.json` (any match → `hard_matches`), plus the `{new_skill_group}/{v}/` listing (an `{old_name}/` directory present, or the `{new_name}/` directory missing → `dir_violations`). It matches `{old_name}` only as a complete skill-name token — bounded by non-name characters — so a correctly-renamed `{new_name}` that contains `{old_name}` as a substring (e.g. `rename` → `rename-skill`) is never a false leftover, and the frontmatter=hard / body=warning split is applied by region with no meaning-interpretation. A missing file is recorded under `skipped`, not treated as a match. Exit 0 = clean; exit 1 = at least one hard match or dir violation.
 
-**On hard failure (any structural reference to `{old_name}` remains):**
+Read the JSON and decide:
 
-- `rm -rf {new_skill_group}` and `rm -rf {new_forge_group}`
-- 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.
+- **If `clean` is `true` (empty `hard_matches` AND empty `dir_violations`):** the rename is safe to commit. Set `verification_warnings` = the returned `body_warnings` (informational SKILL.md body mentions of `{old_name}` that are retained). Proceed.
+- **If `clean` is `false`:** this is a hard failure —
+  - `rm -rf {new_skill_group}` and `rm -rf {new_forge_group}`
+  - Release the lock: `rm -f "{forge_data_folder}/{old_name}/.skf-rename.lock"`
+  - Halt with: "**Verification failed.** `{old_name}` still appears in: {the files from `hard_matches` plus any `dir_violations`}. 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}.'}"
 
@@ -228,26 +234,65 @@ Report: "**Manifest updated** — re-keyed `exports.{old_name}` → `exports.{ne
 
 ### 7. Rebuild Context Files
 
-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 §6 re-keys the manifest from `{old_name}` to `{new_name}`, every IDE's context file (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`, etc.) still carries the old name in its managed-section snippet rows. This section rewrites each one in-place via the surgical between-marker swap so the on-disk managed sections reflect the new name. It runs only on the success path — the §4–§6 rollback jumps never reach here.
+
+**7a. Resolve `target_context_files`.** Load the `ides` list from `config.yaml`. The installer writes IDE identifiers — map each to a context file and skill root via the "IDE → Context File 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 in the table, default to `{unknownIdeDefaultContextFile}` / `{unknownIdeDefaultSkillRoot}` and emit a warning: `Unknown IDE '{value}' in config.yaml — defaulting to {unknownIdeDefaultContextFile}`.
+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: "{unknownIdeDefaultContextFile}", skill_root: "{unknownIdeDefaultSkillRoot}"}]` and emit a note: `No IDEs configured in config.yaml — defaulting to {unknownIdeDefaultContextFile}`.
+
+**7b. Per-file loop.** For each entry in `target_context_files`:
+
+1. **Resolve the target file** at `{context_file}` (absolute path).
+2. **Read the current file:**
+   - If it does not exist, skip (nothing to rebuild — export-skill re-creates it on its next run).
+   - If it exists but has no `<!-- SKF:BEGIN -->` marker, skip (no managed section to rewrite).
+   - If it has `<!-- SKF:BEGIN -->` but no matching `<!-- SKF:END -->`, record the error against that file and continue to the next entry — do not halt the whole rename on one malformed context file.
+3. **Build the exported skill set (version-aware, deprecated-excluded)** using the same logic as `skf-export-skill/references/update-context.md` §4b (skill set) and §4c (snippet resolution):
+   - Read the manifest's `exports` object (already updated in §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.
+   - 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** using the generic algorithm from `skf-export-skill/references/update-context.md` §4d: parse each snippet's `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`.
+5. **Sort and count.** 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 — atomic, deterministic.** Invoke `{rebuildManagedSectionsHelper}` (resolved in §0) for the between-marker swap:
+
+   ```bash
+   python3 {rebuildManagedSectionsHelper} {context_file} replace --content "{new_managed_section_text}"
+   ```
 
-After the loop returns, the workflow context contains:
+   The helper handles marker location, the between-marker swap, atomic temp-file + rename, and post-write verification (markers preserved, content outside markers byte-identical). It exits non-zero on any failure with a clear `stderr` reason — treat any non-zero exit as a per-file failure.
+8. **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, so context files can be re-rebuilt later via `[EX] Export Skill`.
+
+**7c. After the loop**, record:
 
 - `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`)
+- `context_files_failed` — list of any that failed
 
-Report per the reference's after-loop block, then proceed to §8.
+Report: `**Rebuilt managed sections in:** {list of updated files}. {if any failed: 'Failed: {list} — re-run [EX] Export Skill to retry.'}` Then proceed to §8.
 
 **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)
 
-This is the only section after which rollback is impossible. By this point:
-
-- `{new_skill_group}` is fully materialized with all inner directories renamed and files updated
-- `{new_forge_group}` is fully materialized with `skill_name` updated in every provenance map
-- No structural references to `{old_name}` remain inside either new directory (verified in section 5)
-- The manifest has been re-keyed (section 6)
-- Platform context files reference `{new_name}` (section 7, best-effort)
+This is the only section after which rollback is impossible. Precondition: §1–7 have fully materialized and verified the new name (both new directories renamed, no `{old_name}` references remaining, manifest re-keyed, context files rebuilt best-effort) — only now is deleting the old name safe.
 
 Execute the deletes:
 
@@ -282,25 +327,9 @@ Store the following for step 3:
 - `section3_warnings` — list of missing file warnings (empty if none)
 - `verification_warnings` — list of informational SKILL.md body mentions of `{old_name}` retained (empty if none)
 - `deletion_errors` — list of post-commit deletion errors (empty if none)
+- `headless_decisions` — the audit trail of confirmation gates auto-resolved under `{headless_mode}`, carried forward from step 1 unchanged (empty in interactive runs). Step 3 surfaces it in the result envelope and the per-run result JSON.
 
 ### 10. Load Next Step
 
 Load, read the full file, and then execute `{nextStepFile}`.
 
-## Error Handling Summary
-
-| Section | Failure Mode | Reversible? | Recovery Action |
-|---------|--------------|-------------|-----------------|
-| 1 | Copy failure | Yes | Delete whichever new directory exists; old skill intact |
-| 2 | Inner rename failure | Yes | `rm -rf` both new directories; old skill intact |
-| 3 | File update failure | Yes | `rm -rf` both new directories; old skill intact |
-| 4 | `active` symlink repair failure | Yes | `rm -rf` both new directories; old skill intact |
-| 5 | Verification failure | Yes | `rm -rf` both new directories; old skill intact |
-| 6 | Manifest write failure | Yes | Restore manifest from backup; `rm -rf` both new directories; old skill intact |
-| 7 | Platform context rebuild failure | Per-file | Record errors, continue other platforms; do NOT rollback — manifest and disk are canonical |
-| 8 | Delete failure | **No** | Record deletion errors; new name is already committed; user removes remnants manually |
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN all execution sections have been attempted (copy, inner rename, file updates, symlink fix, verification, manifest re-key, context rebuild, old delete) and results have been stored in context, will you then load and read fully `{nextStepFile}` to generate the final report.
-

package/src/skf-rename-skill/references/exit-codes.md

@@ -0,0 +1,12 @@
+# Exit Codes — skf-rename-skill
+
+Every HARD HALT in the rename 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 §4 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`); step 2 §5 (no-trace verification failed — `{old_name}` still present inside the new location → `verify-failed`; note this rollback is code 5, unlike the copy/write rollbacks at code 4) |
+| 6    | user-cancelled       | step 1 §6 (source-authority warning [N]); step 1 §8 confirmation gate `[N]`; any prompt that accepted `cancel`/`exit`/`:q` |

package/src/skf-rename-skill/references/report.md

@@ -15,7 +15,7 @@ Present a clear, final summary of what the rename workflow changed — old and n
 - Focus only on reporting results stored in context by step 2 — do not re-execute any part of the rename
 - Do not hide verification warnings, context file rebuild failures, or deletion errors
 - Present next-steps guidance so the user knows which downstream workflows to run
-- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing report is NOT the terminal step
+- Chains to the local health-check step via `{nextStepFile}` after completion (see section 2)
 
 ## MANDATORY SEQUENCE
 
@@ -61,6 +61,10 @@ Informational: the old name still appears in SKILL.md body text (prose only, non
   {list each error}
   → The new name is fully committed. Remove the remnants manually with `rm -rf {path}`.
 
+{if headless_decisions is non-empty:}
+Headless auto-decisions:
+  {for each entry: "{gate}: took {taken_action} (default {default_action}) — {reason}"}
+
 ---
 
 **Next steps:**
@@ -71,21 +75,25 @@ Informational: the old name still appears in SKILL.md body text (prose only, non
 
 ### Result Contract
 
-Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skills_output_folder}/{new_name}/rename-skill-result-{timestamp}.json` (reuse the activation-stored `{timestamp}`, resolution to seconds) and a copy at `{skills_output_folder}/{new_name}/rename-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all updated file paths (SKILL.md, metadata.json, context-snippet.md, provenance-map.json) in `outputs`; include `old_name`, `new_name`, and `versions_renamed` in `summary`.
+Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skills_output_folder}/{new_name}/rename-skill-result-{timestamp}.json` (reuse the activation-stored `{timestamp}`, resolution to seconds) and a copy at `{skills_output_folder}/{new_name}/rename-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all updated file paths (SKILL.md, metadata.json, context-snippet.md, provenance-map.json) in `outputs`; include `old_name`, `new_name`, `versions_renamed`, and `headless_decisions` (the auto-resolved gate audit trail carried from step 1 — `[]` in interactive runs) in `summary`.
 
 When `{headless_mode}` is true, also emit the single-line envelope on **stdout** before chaining to step 4 (matches the SKILL.md "Result Contract (Headless)" shape):
 
 ```
-SKF_RENAME_SKILL_RESULT_JSON: {"status":"success","old_name":"{old_name}","new_name":"{new_name}","versions_renamed":{affected_versions},"manifest_rekeyed":{manifest_rekeyed},"context_files_updated":{context_files_updated},"exit_code":0,"halt_reason":null}
+SKF_RENAME_SKILL_RESULT_JSON: {"status":"success","old_name":"{old_name}","new_name":"{new_name}","versions_renamed":{affected_versions},"manifest_rekeyed":{manifest_rekeyed},"context_files_updated":{context_files_updated},"exit_code":0,"halt_reason":null,"headless_decisions":{headless_decisions}}
 ```
 
-Substitute `{affected_versions}` and `{context_files_updated}` as JSON arrays; `manifest_rekeyed` is the boolean from step 2's context.
+Substitute `{affected_versions}`, `{context_files_updated}`, and `{headless_decisions}` as JSON arrays; `manifest_rekeyed` is the boolean from step 2's context.
 
-### 2. Chain to Health Check
+**Post-completion hook (optional).** If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`), invoke it after the result contract is finalized, passing the per-run result path:
 
-ONLY WHEN the rename report has been rendered and the result contract saved will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the report reads as final.
+```bash
+{onCompleteCommand} --result-path={skills_output_folder}/{new_name}/rename-skill-result-{timestamp}.json
+```
 
-## CRITICAL STEP COMPLETION NOTE
+Log success/failure but never fail the workflow on a hook error — the rename is already committed. The hook runs last so an audit-log emit, registry re-index, or notifier sees the completed rename. When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely.
 
-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 rename-skill workflow is fully done. Do not re-run any earlier step automatically — if the user wants another rename, they should re-invoke the workflow from the top.
+### 2. Chain to Health Check
+
+ONLY WHEN the rename report has been rendered and the result contract saved will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the report reads as final.
 

package/src/skf-rename-skill/references/select.md

@@ -1,6 +1,31 @@
 ---
 nextStepFile: 'execute.md'
 versionPathsKnowledge: 'knowledge/version-paths.md'
+# Resolve `{manifestOpsHelper}` by probing `{manifestOpsProbeOrder}` in order
+# (installed SKF module path first, src/ dev-checkout fallback); first existing
+# path wins. §7 uses its `affected-versions` action to enumerate the versions a
+# rename must touch — the union of manifest version keys and on-disk version
+# dirs, deduped and semver-sorted (numeric, so 0.10.0 precedes 0.9.0). Unlike
+# execute.md's write helpers this one is not atomicity-critical: if neither path
+# resolves, §7 falls back to computing the union in the prompt.
+manifestOpsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-manifest-ops.py'
+  - '{project-root}/src/shared/scripts/skf-manifest-ops.py'
+# Resolve `{skillInventoryHelper}` by probing `{skillInventoryProbeOrder}`
+# (installed SKF module path first, src/ dev-checkout fallback). §3 uses it to
+# enumerate the rename candidates: the union of manifest `exports` and on-disk
+# skill directories, each with its version list and active version — computing
+# that union/count in the prompt has one correct answer per input. §3 falls
+# back to an in-prompt scan if neither path resolves.
+skillInventoryProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-skill-inventory.py'
+  - '{project-root}/src/shared/scripts/skf-skill-inventory.py'
+# `{renameNameValidator}` is this skill's own deterministic new-name gate. §5
+# uses it for the format / length / identity / collision checks (one correct
+# answer per (name, filesystem, manifest) state) and the interrupted-rename
+# recovery fingerprint; §5 falls back to the same checks in-prompt if Python is
+# unavailable.
+renameNameValidator: 'scripts/skf-validate-rename-name.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -18,6 +43,14 @@ Identify the skill the user wants to rename, validate the new name against the a
 - Do not accept a new name that fails validation (kebab-case, length, uniqueness)
 - Present the list of affected versions clearly so the user understands the scope
 
+**Headless error envelope (self-contained).** Where a halt below says *"emit the error envelope per SKILL.md 'Result Contract (Headless)'"*, write this single line to **stderr** (restated here so selection halts stay parseable even if SKILL.md is out of context) —
+
+```
+SKF_RENAME_SKILL_RESULT_JSON: {"status":"error","old_name":"…|null","new_name":"…|null","versions_renamed":[],"manifest_rekeyed":false,"context_files_updated":[],"exit_code":<code>,"halt_reason":"<reason>","headless_decisions":[]}
+```
+
+Use the `old_name`/`new_name`, `exit_code`, and `halt_reason` named at each halt site (see `references/exit-codes.md`) — `old_name`/`new_name` are `null` until resolved in §4/§5. `headless_decisions` is `[]` at every selection-stage halt: the only decision this step records (the §6 source-authority override) means *proceed*, so no recorded decision is ever paired with a halt here.
+
 ## MANDATORY SEQUENCE
 
 ### 1. Load Knowledge
@@ -44,19 +77,19 @@ Load `{skills_output_folder}/.export-manifest.json` if it exists.
 
 ### 3. List Available Skills
 
-Build and display a summary of every skill available for rename. Start with the manifest (if any), then augment with on-disk scan.
+Enumerate every skill available for rename deterministically. Resolve `{skillInventoryHelper}` ← first existing path in `{skillInventoryProbeOrder}` and run:
 
-For each skill in the manifest's `exports` (if `manifest_exists` and entries exist):
+```bash
+python3 {skillInventoryHelper} {skills_output_folder}
+```
 
-1. Read `active_version` from the manifest entry
-2. Count the number of versions in the skill's `versions` map
-3. Display `{skill-name} ({n} versions, active: {active_version})`
+Read the JSON. Each entry in `skills[]` carries `name`, its `versions` array, and `active_version` (the helper unions the manifest `exports` with the on-disk directories and dedupes, so manifest-tracked and orphaned skills both appear). A skill whose `name` is absent from `manifest.exports` is a draft/orphan the rename workflow can still handle — annotate it "(not in manifest)".
 
-Also scan `{skills_output_folder}/` for any top-level directories that are NOT present in the manifest's `exports` object. Record these as "(not in manifest)" — they represent draft or orphaned skills that the rename workflow can also handle. When the manifest is missing or empty, every on-disk skill appears in this category.
+**If `{skillInventoryHelper}` has no existing candidate** (neither probe path resolves — e.g. Python/`uv` unavailable): build the list in the prompt instead — read `exports` from the manifest (if `manifest_exists`), scan `{skills_output_folder}/` for top-level directories, union the two, and read each one's `active_version` and version count. Directories absent from `exports` are the "(not in manifest)" entries.
 
-**If the combined list is empty** (no manifest entries AND no on-disk skill directories): halt with "**Rename Skill — nothing to rename.** No skills found in `{skills_output_folder}/`. Run `[CS] Create Skill` first." HALT (exit code 3, `halt_reason: "nothing-to-rename"`). In headless mode, emit the error envelope with `old_name: null`, `new_name: null`.
+**If the list is empty** (no manifest entries AND no on-disk skill directories): halt with "**Rename Skill — nothing to rename.** No skills found in `{skills_output_folder}/`. Run `[CS] Create Skill` first." HALT (exit code 3, `halt_reason: "nothing-to-rename"`). In headless mode, emit the error envelope with `old_name: null`, `new_name: null`.
 
-Display the combined list:
+Display the list, one line per skill as `{name} ({n} versions, active: {active_version})` (append "(not in manifest)" for orphans):
 
 ```
 **Rename Skill — select target**
@@ -108,42 +141,38 @@ printf '%s\n%s\n' "$$" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$LOCK"
 
 **Release contract:**
 
-- The terminal health-check step (step 4) deletes the lock as its final action.
-- **Every halted-for-\* path in this workflow must delete the lock before exiting** — otherwise the next attempt would see a stale lock from this run. The lock-release is a single `rm -f "$LOCK"` per halt site.
+- This run owns the lock only after the `printf … > "$LOCK"` line above runs — i.e. once §4b has cleared the live-PID check and written this run's PID. The live-PID collision halt directly above is the **sole exception**: it exits *before* that line, so the lock belongs to the other live run and this run must **never** delete it (clearing a live lock it just honored would let a third invocation run concurrently).
+- The terminal health-check step (step 4) deletes the lock as its final action on the success path.
+- **Every halt from §5 onward — after this run has acquired the lock — must delete it before exiting** (`rm -f "$LOCK"` per halt site): the §5 input/format/collision halts, the §6 source-authority and cancel halts, the §8 cancel and dry-run exits, and execute.md's copy/verify/manifest/write rollbacks. Otherwise the next attempt would see a stale lock from this run.
 
 ### 5. Ask for New Name
 
 "**What is the new name for this skill?**
-The new name must be kebab-case: lowercase alphanumeric with hyphens, 1-64 characters, matching the regex `^[a-z][a-z0-9-]*[a-z0-9]$` (single-character names may be a single lowercase letter or digit). Or type `cancel` / `exit` / `:q` to abort."
+The new name must be kebab-case: lowercase alphanumeric with hyphens, 1-64 characters, matching the regex `^[a-z0-9]([a-z0-9-]*[a-z0-9])?$` (starts and ends with a lowercase letter or digit; a single letter or digit is valid). Or type `cancel` / `exit` / `:q` to abort."
 
 Wait for user input. Trim whitespace. **GATE [default: use args]** — If `{headless_mode}` and new_name was provided as argument: use it and auto-proceed through validation. If not provided, release the lock and HALT (exit code 2, `halt_reason: "input-missing"`): "headless mode requires new_name argument." In headless, emit the error envelope.
 
 - If the user enters `cancel`, `exit`, `[X]`, `q`, or `:q`: release the lock (`rm -f {forge_data_folder}/{old_name}/.skf-rename.lock`), display "Cancelled — no changes were made.", and HALT (exit code 6, `halt_reason: "user-cancelled"`).
 
-Apply the following validations in order:
-
-1. **Kebab-case format:** Must match `^[a-z][a-z0-9-]*[a-z0-9]$` (or `^[a-z0-9]$` for the single-character case). If it fails:
-   "**Invalid name format.** The new name must be lowercase alphanumeric with hyphens, starting with a letter and ending with a letter or digit. Try again."
-   Re-ask. In headless mode, instead of re-asking, release the lock (`rm -f {forge_data_folder}/{old_name}/.skf-rename.lock`) and HALT (exit code 2, `halt_reason: "input-invalid"`) and emit the error envelope.
+**Validate the candidate deterministically.** Run `{renameNameValidator}` (a per-skill helper, always shipped with the skill) — it applies format, length, identity, and collision in that order and returns the verdict as JSON:
 
-2. **Length:** Must be 1-64 characters per the agentskills.io spec. If it fails:
-   "**Invalid name length.** The new name must be 1-64 characters. Try again."
-   Re-ask. In headless mode, instead of re-asking, release the lock (`rm -f {forge_data_folder}/{old_name}/.skf-rename.lock`) and HALT (exit code 2, `halt_reason: "input-invalid"`) and emit the error envelope.
+```bash
+python3 {renameNameValidator} \
+  --old-name {old_name} --new-name {candidate} \
+  --skills-output-folder {skills_output_folder} \
+  --forge-data-folder {forge_data_folder}
+```
 
-3. **Same as old name:** If the new name equals `old_name`:
-   "**The new name is identical to the current name.** Nothing to rename. Try again or abort the workflow."
-   Re-ask. In headless mode, instead of re-asking, release the lock (`rm -f {forge_data_folder}/{old_name}/.skf-rename.lock`) and HALT (exit code 2, `halt_reason: "input-invalid"`) and emit the error envelope.
+The checks: **format** = the kebab regex `^[a-z0-9]([a-z0-9-]*[a-z0-9])?$` (the module's canonical rule, same as `skf-validate-output.py` / `skf-validate-brief-inputs.py`, so a digit-leading name like `3d-tools` renames cleanly); **length** = 1-64 characters (agentskills.io spec); **identity** = differs from `{old_name}`; **collision** = the name is not a manifest `exports` key, a `{skills_output_folder}` directory, or a `{forge_data_folder}` directory.
 
-4. **Collision check:** The new name MUST NOT collide with any existing skill:
-   - It must not appear as a key in `exports` in the manifest
-   - It must not exist as a top-level directory in `{skills_output_folder}/`
-   - It must not exist as a top-level directory in `{forge_data_folder}/`
+Read `valid`, `first_failure`, `checks`, and `interrupted_rename`. If `valid` is true, store the input as `new_name` and proceed to §6. Otherwise branch on `first_failure` — interactive: display the message and re-ask; headless: release the lock (`rm -f {forge_data_folder}/{old_name}/.skf-rename.lock`), HALT with the mapped code, and emit the error envelope:
 
-   If any collision is detected:
-   "**Name collision.** `{new-name}` already exists at: {list the colliding locations}. Pick a different name."
-   Re-ask. In headless mode, instead of re-asking, release the lock and HALT (exit code 5, `halt_reason: "name-collision"`) and emit the error envelope.
+- **`format`** → "**Invalid name format.** The new name must be lowercase alphanumeric with hyphens, starting and ending with a lowercase letter or digit. Try again." (headless HALT: exit code 2, `halt_reason: "input-invalid"`)
+- **`length`** → "**Invalid name length.** The new name must be 1-64 characters. Try again." (headless HALT: exit code 2, `halt_reason: "input-invalid"`)
+- **`identity`** → "**The new name is identical to the current name.** Nothing to rename. Try again or abort the workflow." (headless HALT: exit code 2, `halt_reason: "input-invalid"`)
+- **`collision`** → "**Name collision.** `{new-name}` already exists at: {the `path` of each entry in `checks.collision.locations`}. Pick a different name." When `interrupted_rename` is true, append: "This may be a stranded partial rename from an earlier interrupted run — `{new_name}` was staged but `{old_name}` was never removed. Confirm the `{new_name}` directories are not a skill you want to keep, then clean them up (`rm -rf {skills_output_folder}/{new_name} {forge_data_folder}/{new_name}`) and re-run this rename." — this gives headless pipelines a named recovery path instead of a dead-end collision halt. (headless HALT: exit code 5, `halt_reason: "name-collision"`)
 
-Only after all four validations pass, store the input as `new_name`.
+**If `{renameNameValidator}` cannot run** (Python/`uv` unavailable): apply the same four checks in the same order in the prompt — the kebab regex, the 1-64 length bound, inequality with `{old_name}`, and the three-source collision lookup (plus the interrupted-rename fingerprint above) — using the identical messages and halt mapping.
 
 ### 6. Source Authority Check
 
@@ -176,14 +205,15 @@ Wait for response.
 
 ### 7. Enumerate Affected Versions
 
-List all versions for `old_name`:
+Resolve `{manifestOpsHelper}` ← first existing path in `{manifestOpsProbeOrder}` (installed SKF module path first, `src/` dev-checkout fallback). Enumerate every version the rename must touch deterministically via its `affected-versions` action:
 
-1. Read every key under `exports.{old_name}.versions` in the manifest
-2. Also list every directory under `{skills_output_folder}/{old_name}/` that looks like a version (any entry that is not `active`)
-3. Union the two sets — this handles both manifest-tracked and orphaned on-disk versions
-4. Sort descending where possible (newest first)
+```bash
+python3 {manifestOpsHelper} {skills_output_folder} affected-versions {old_name}
+```
 
-Store the sorted list as `affected_versions` and count it as `affected_versions_count`.
+Read the JSON result. Store `affected_versions` = `result.affected_versions` and `affected_versions_count` = `result.count`. The helper unions the manifest's `exports.{old_name}.versions` keys with the on-disk version directories under `{skills_output_folder}/{old_name}/` (every entry that is not the `active` symlink), so it handles both manifest-tracked and orphaned on-disk versions, deduplicates, and applies a **numeric** semver-descending sort (so `0.10.0` correctly precedes `0.9.0`, which a lexical sort gets wrong). An incomplete union would risk leaving a version internally un-renamed in the new copy — a leftover that step 2 §5 only catches for the versions it was told about.
+
+**If `{manifestOpsHelper}` has no existing candidate** (neither probe path resolves — e.g. Python/`uv` unavailable): compute `affected_versions` in the prompt instead — read every key under `exports.{old_name}.versions` in the manifest, list every directory under `{skills_output_folder}/{old_name}/` that is not `active`, union the two sets, and sort descending (newest first, comparing version components numerically). Store the list as `affected_versions` and its length as `affected_versions_count`.
 
 Also resolve the four outer paths using the templates from `{versionPathsKnowledge}`:
 
@@ -225,11 +255,11 @@ directories are removed and the old skill remains intact.
 Proceed? [Y/N]
 ```
 
-**GATE [default: Y]** — If `{headless_mode}`: auto-proceed with [Y], log: "headless: auto-confirmed rename {old_name} → {new_name}"
+**GATE [default: Y]** — If `{headless_mode}`: auto-proceed with [Y] and append `{gate: "confirm-rename", default_action: "proceed", taken_action: "proceed", reason: "headless auto-confirm"}` to `headless_decisions[]` (log line: "headless: auto-confirmed rename {old_name} → {new_name}"). Skip this append when `--dry-run` is set — a dry run does not execute the rename, so there is no confirmation to record.
 
 Wait for explicit user response.
 
-**If `--dry-run` was passed**: skip the Y/N prompt entirely. Release the lock (`rm -f {forge_data_folder}/{old_name}/.skf-rename.lock`), display "**[DRY RUN] No changes were made — preview above shows what would be renamed.**", and emit the success envelope per SKILL.md "Result Contract (Headless)" with `status: "dry-run"`, the resolved `old_name`, `new_name`, and `versions_renamed: {affected_versions}`, then HALT (exit code 0). No copy, no manifest re-key, no delete.
+**If `--dry-run` was passed**: skip the Y/N prompt entirely. Release the lock (`rm -f {forge_data_folder}/{old_name}/.skf-rename.lock`), display "**[DRY RUN] No changes were made — preview above shows what would be renamed.**", and emit the success envelope per SKILL.md "Result Contract (Headless)" with `status: "dry-run"`, the resolved `old_name`, `new_name`, `versions_renamed: {affected_versions}`, and `headless_decisions: {headless_decisions}` (carries the §6 source-authority override entry if it fired, else `[]`), then HALT (exit code 0). No copy, no manifest re-key, no delete.
 
 - **If `Y`** → proceed to section 9
 - **If `N`** (or `cancel` / `exit` / `[X]` / `:q`) → release the lock (`rm -f {forge_data_folder}/{old_name}/.skf-rename.lock`), display "**Cancelled.** No changes were made.", HALT (exit code 6, `halt_reason: "user-cancelled"`). In headless mode, emit the error envelope per SKILL.md "Result Contract (Headless)" with the resolved `old_name` and `new_name`.
@@ -248,12 +278,9 @@ Store the following decisions in workflow context for step 2:
 - `old_forge_group` — absolute path `{forge_data_folder}/{old_name}/`
 - `new_forge_group` — absolute path `{forge_data_folder}/{new_name}/`
 - `source_authority_override` — boolean (true if the user acknowledged the `"official"` warning, false/absent otherwise)
+- `headless_decisions` — the audit trail of confirmation gates auto-resolved under `{headless_mode}` (the §6 source-authority override and the §8 auto-confirm entries appended above). Initialize to `[]`; in interactive runs it stays `[]`. Step 2 carries it forward and step 3 surfaces it in the result envelope.
 
 ### 10. Load Next Step
 
 Load, read the full file, and then execute `{nextStepFile}`.
 
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the user has confirmed with `Y` at the confirmation gate AND all selection decisions have been stored in context, will you then load and read fully `{nextStepFile}` to execute the rename.
-