bmad-module-skill-forge 2.1.0 → 3.0.0

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

@@ -1,12 +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:
+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. In headless mode each HALT also prints its `SKF_RENAME_SKILL_RESULT_JSON` line through the shared emitter, which derives `exit_code` from `halt_reason` through the schema's `skf-envelope.exit_codes`; this table says where each code is raised:
 
 | 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` |
+| 0    | success              | step 3 (a finished rename, before the step 4 health check); step 1 §8 (the `--dry-run` exit, `status: "dry-run"`) |
+| 2    | input-missing / input-invalid | step 1 §4/§5 (headless missing `old_name`/`new_name` arg) → `input-missing`; step 1 §4 (headless `old_name` matches no listed skill) → `input-invalid`; step 1 §5 (headless: the new name fails kebab-case / length / same-as-old; an interactive run asks again) → `input-invalid` |
+| 3    | resolution-failure   | step 1 §2 (manifest is malformed JSON) → `manifest-corrupt`; step 1 §3 (no skill SKF generated found anywhere) → `nothing-to-rename` |
+| 4    | write-failure        | step 1 §1 (the run-lock, envelope, manifest or inventory helper is missing, or the pre-flight write probe finds the run folder, skills_output_folder or forge_data_folder unwritable), step 1 §2, §3, §5 and §7 (the manifest read, the skill listing, the new-name validator or the version listing prints no JSON), step 1 §4b (the run lock could not be taken), step 1 §6 and §8 (an auto-decision could not be recorded), step 2 §0 (a helper is missing) and step 2 §1 (the run lock could not be renewed) → `write-failed`; step 2 §1 (copy → `copy-failed`); step 2 §2 (inner-dir rename, file content update or the record it writes to the run folder) / §4 (symlink repair) → `write-failed`; step 2 §6 (manifest backup or 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 §4a, entered from §3 or §4 (a folder SKF did not generate, one that also holds entries SKF did not generate, or ownership that cannot be checked, in the skill folder or its forge folder, or a forge folder that is a link, is not a folder, or cannot be listed → `not-skf-output`; a flat-layout skill → `flat-layout`); step 1 §5 (name-collision check fails: target name already in use, or `improvement-queue`, or an earlier rename to that name stopped after re-keying the export manifest, whose leftover folders the message names) → `name-collision`; step 1 §6 (source-authority="official" headless without `--acknowledge-official` or `force_source_authority_in_headless`) → `source-authority-blocked`; step 1 §4b (another rename of the same skill holds a run lock that has not gone stale) and step 2 §1 (this run's lock went stale while it waited at a step 1 gate) → `halted-for-concurrent-run`; step 2 §5 (no-trace verification failed: `{old_name}` still present inside the new location, or the verifier exits 2 with no JSON → `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` → `user-cancelled` |

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

@@ -21,10 +21,4 @@ Chain to the shared workflow self-improvement health check at `{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.
+1. Load `{nextStepFile}`, read it fully, then execute it.

package/src/skf-rename-skill/references/invocation-contract.md

@@ -0,0 +1,25 @@
+# Invocation Contract: skf-rename-skill
+
+The inputs, flags, gate map, outputs and headless result envelope of `skf-rename-skill`. Interactive runs do not need this file; headless callers and pipeline integrators read it. `references/exit-codes.md` says where each exit code is raised.
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | `old_name` [required], `new_name` [required]. A supplied name answers its question in either mode: an interactive run asks only for a name that is missing, or again for one that fails its check. |
+| **Flags** | `--headless` / `-H` (auto-resolve all gates); `--dry-run` (run selection + validation + display the step 1 §8 confirmation block, then exit with `status="dry-run"`: no run lock, no copy, no manifest re-key, no delete, no result file); `--acknowledge-official` (answers the step 1 §6 source-authority warning for this run only, so a headless run may rename a skill whose `source_authority` is `"official"`; the decision is recorded in `headless_decisions[]`). |
+| **Gates** | step 1: Input Gate [use args] x2 (§4 old name, §5 new name); Source-Authority Gate [Y/N] (§6, only for an `"official"` skill; headless default: HALT `source-authority-blocked` unless `--acknowledge-official` or the `force_source_authority_in_headless` setting); Confirm Gate [Y] (§8). Step 2 asks nothing. |
+| **Outputs** | Renamed skill directories, updated manifest, updated context files, `{new_name}/rename-skill-result-{YYYYMMDD-HHmmss}.json` (UTC) and `{new_name}/rename-skill-result-latest.json`; a halt keeps its run folder under `{project-root}/_bmad-output/.skf-run/` |
+| **Concurrency** | step 1 §4b takes the run lock `{forge_data_folder}/.skf-rename-{old_name}.lock` through `skf-run-lock.py`. While another rename of the same `old_name` holds a lock that has not gone stale (60 minutes after it was taken or renewed), the run HALTs with `halt_reason: "halted-for-concurrent-run"` (exit 5). Every exit releases it; `--dry-run` takes none. |
+| **Headless** | All gates auto-resolve with their default action when `{headless_mode}` is true. The §6 source-authority warning HALTs by default when `source_authority="official"`: pass `--acknowledge-official` to proceed for one run. The `force_source_authority_in_headless = "true"` setting, in a team or personal override of this skill (SKILL.md On Activation step 3 names the files), is a standing approval for every headless run. Either way the decision is recorded in `headless_decisions[]`. |
+| **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, the `--dry-run` exit (step 1 §8) emits it on **stdout** with `status: "dry-run"`, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`. The model never types the line: each site passes its payload to the shared emitter, `shared/scripts/skf-emit-result-envelope.py`, which checks it against `shared/scripts/schemas/skf-rename-skill-result-envelope.v1.json`:
+
+```
+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":[],"run_id":"…","result_path":"…|null"}
+```
+
+`status` is `"success"` on the terminal happy path, `"dry-run"` when `--dry-run` was set and the workflow exited before step 1 §9 stores decisions, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"manifest-corrupt"`, `"nothing-to-rename"`, `"not-skf-output"`, `"flat-layout"`, `"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`. `manifest_rekeyed` is true only when step 2 re-keyed an `exports.{old_name}` entry. `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 decision, with `--acknowledge-official` or the setting as its reason, and the §8 auto-confirm); it is `[]` in interactive runs and whenever no gate was auto-resolved before the envelope was emitted. The schema describes the other fields: `versions_renamed`, `run_id`, `result_path`, a halt's `error` and the optional `warnings`.

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

@@ -1,5 +1,15 @@
 ---
 nextStepFile: 'health-check.md'
+# `{emitEnvelopeHelper}` and `{runLockHelper}` stay bound from step 1 §1;
+# resolve them again when a binding was lost: first existing path wins. §1
+# writes the result files and the envelope through the first, and §4
+# releases the run lock through the second.
+emitEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
+runLockProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-run-lock.py'
+  - '{project-root}/src/shared/scripts/skf-run-lock.py'
 ---
 
 <!-- Config: communicate in {communication_language}. Render the report block in {document_output_language}. -->
@@ -8,92 +18,93 @@ nextStepFile: 'health-check.md'
 
 ## STEP GOAL:
 
-Present a clear, final summary of what the rename workflow changed — old and new names, versions renamed, file-level update counts, manifest re-key, platform context rebuild, and any residual warnings or deletion errors — so the user can verify the outcome and know whether any manual follow-up is required.
+End the rename with one terminal sequence: write the result files and the envelope through the shared emitter, present a clear, final summary of what the rename workflow changed (old and new names, versions renamed, the files rewritten, manifest re-key, platform context rebuild, and any residual warnings or deletion errors) so the user can verify the outcome and know whether any manual follow-up is required, fire the post-completion hook, release the run lock, and chain to the health check.
 
 ## Rules
 
-- Focus only on reporting results stored in context by step 2 — do not re-execute any part of the rename
+- Report only the results step 2 recorded from its helpers: do not re-execute any part of the rename, and never state a count or a version list step 2 did not record
 - 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 (see section 2)
+- Run the sections in order: the rename is already committed, so nothing here halts or undoes it
 
 ## MANDATORY SEQUENCE
 
-### 1. Render the Report
+### 1. Write the Result Files and the Envelope
 
-Display the following block, filling in values from context:
+Read `{run_dir}/rename-rewrite.json`, the record step 2 §2's helper wrote (step 2 rolls back a run whose record it could not write), and bind from it `renamed_versions`, `files_rewritten`, `rewrite_counts` ← `counts`, `package_warnings` and `missing_files`.
 
+Stage the rename's result in the run folder, every value from what step 2 recorded: write each string as JSON (escape `"`, `\` and control characters, and write every path with `/`). Then let the shared emitter write the result files. From `{project-root}`:
+
+```bash
+cat > "{run_dir}/result-context.json" <<'SKF_RESULT'
+{"status": "success", "old_name": "{old_name}", "new_name": "{new_name}", "versions_renamed": <renamed_versions as a JSON array>, "manifest_rekeyed": <manifest_rekeyed>, "context_files_updated": <context_files_updated as a JSON array>, "halt_reason": null, "result_contract": {"skill": "skf-rename-skill", "status": "success", "outputs": <one {"type": "skill", "path": "<path>"} per path in files_rewritten>, "summary": {"old_name": "{old_name}", "new_name": "{new_name}", "versions_renamed": <renamed_versions>, "manifest_rekeyed": <manifest_rekeyed>, "context_files_updated": <context_files_updated>, "context_files_failed": <context_files_failed>, "forge_left_in_place": <forge_left_in_place, or null>}}}
+SKF_RESULT
+uv run {emitEnvelopeHelper} emit --workflow skf-rename-skill --run-dir "{run_dir}" --result-dir "{skills_output_folder}/{new_name}" < "{run_dir}/result-context.json"
 ```
-**Rename complete.**
 
-From: {old_name}
-To:   {new_name}
+The emitter checks the envelope against `shared/scripts/schemas/skf-rename-skill-result-envelope.v1.json`, adds the decisions and warnings the run recorded, and writes the result files in `{skills_output_folder}/{new_name}/` as `shared/references/output-contract-schema.md` describes. It prints the `SKF_RENAME_SKILL_RESULT_JSON:` line on stdout: bind `{result_line}` ← that line, and from its JSON `{result_path}` ← `result_path` (the per-run record, or null when it could not be written), `{headless_decisions}` ← `headless_decisions` and `{run_warnings}` ← `warnings` (empty when absent).
 
-Versions renamed: {affected_versions_count} ({comma-separated affected_versions})
+When the emitter exits non-zero and its `message` names the payload, fix `{run_dir}/result-context.json` once and run it again. If it still exits non-zero, or prints no line, the rename stays committed: show its stderr message as a warning, bind `{result_line}` and `{result_path}` to null and `{headless_decisions}` and `{run_warnings}` to empty lists, and go on. No result file was written, and §4 keeps the run folder.
 
-References updated:
-  - SKILL.md frontmatter       (×{affected_versions_count})
-  - metadata.json              (×{affected_versions_count})
-  - context-snippet.md         (×{affected_versions_count})
-  - provenance-map.json        (×{affected_versions_count})
+### 2. Render the Report
 
-Manifest updated: {if manifest_rekeyed: "exports.{new_name} (re-keyed from exports.{old_name})" else: "(no manifest entry existed for {old_name})"}
-Context files rebuilt: {list from context_files_updated, or "(none)"}
-{if context_files_failed is non-empty:}
-Context files FAILED: {list from context_files_failed}
-  → Re-run `[EX] Export Skill` to retry the managed section rebuild for these files.
+Open with "**Rename complete.**", then show, each from what step 2 recorded:
 
-{if section2_warnings is non-empty:}
-Warnings (inner directory rename):
-  {list each warning from section2_warnings}
+- From `{old_name}` to `{new_name}`, and the versions renamed: the number and the list of `renamed_versions`.
+- The references updated, each with its count from `rewrite_counts`: SKILL.md frontmatter, metadata.json, context-snippet.md and, when `{forge_move}` or `{same_folder}` is true, provenance-map.json.
+- The manifest: `exports.{new_name}`, re-keyed from `exports.{old_name}`, when `manifest_rekeyed` is true, else that no manifest entry existed for `{old_name}`.
+- The context files rebuilt (`context_files_updated`, or "(none)"). When `context_files_failed` is not empty, list it with: "Re-run `[EX] Export Skill` to retry the managed section rebuild for these files."
+- When `{forge_left_in_place}` is set: "Left in place (not SKF output): {forge_left_in_place}. SKF did not generate it, so it keeps its name."
+- Each entry of `package_warnings`, `missing_files` and `{run_warnings}`, as warnings, except a `{run_warnings}` entry that starts with `installed-copy-not-renamed:`, which the next steps name.
+- When `verification_warnings` is not empty, the SKILL.md files whose body text still names the old name (prose only, non-structural), with: "These are typically historical notes or changelog entries. Review and edit them by hand if you want them updated."
+- When `deletion_errors` is not empty, each one, with: "The new name is fully committed. Remove the remnants by hand with `rm -rf {path}`."
+- Each entry of `{headless_decisions}`, as "{gate}: took {taken_action} (default {default_action}): {reason}".
+- The result file: `{result_path}`, or "(not written)".
 
-{if section3_warnings is non-empty:}
-Warnings (missing files during content update):
-  {list each warning from section3_warnings}
+Close with the next steps:
 
-{if verification_warnings is non-empty:}
-Informational: the old name still appears in SKILL.md body text (prose only, non-structural) in:
-  {list each path from verification_warnings}
-  → These are typically historical notes or changelog entries. Review and edit manually if you want them updated.
+- For each path in `installed_copies`: "`{path}` is the copy `npx skills add` installed under `{old_name}`, and the rebuilt rows point at the same folder under `{new_name}`. Remove it, run `npx skills add {new_skill_group}/{version}/{new_name}`, then reload the IDE." `{version}` is `target_version`, else the first of `renamed_versions` (newest first), and `{new_skill_group}` is absolute, as export requires.
+- Run `@Ferris EX` if you want to re-verify the managed sections in platform context files.
+- If you had QMD collections or external tooling registered under `{old_name}`, re-run `@Ferris SF` (or your registration command) to re-index under `{new_name}`.
+- If this skill was published to agentskills.io under `{old_name}`, the registry version is unchanged: this rename is a LOCAL operation only.
 
-{if deletion_errors is non-empty:}
-**Post-commit deletion errors:**
-  {list each error}
-  → The new name is fully committed. Remove the remnants manually with `rm -rf {path}`.
+When `{headless_mode}` is true, display `{result_line}` verbatim on its own line after the report, when §1 printed one: it is the run's envelope, on **stdout**.
 
-{if headless_decisions is non-empty:}
-Headless auto-decisions:
-  {for each entry: "{gate}: took {taken_action} (default {default_action}) — {reason}"}
+### 3. Post-Completion Hook (optional)
 
----
+If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`) and `{result_path}` is not null, run it as a shell command from `{project-root}` with the per-run result file §1 wrote:
 
-**Next steps:**
-  - Run `@Ferris EX` if you want to re-verify the managed sections in platform context files
-  - If you had QMD collections or external tooling registered under `{old_name}`, re-run `@Ferris SF` (or your registration command) to re-index under `{new_name}`
-  - If this skill was published to agentskills.io under `{old_name}`, the registry version is unchanged — this rename is a LOCAL operation only
+```bash
+{onCompleteCommand} --result-path="{result_path}"
 ```
 
-### Result Contract
+Log success/failure but never fail the workflow on a hook error: the rename is already committed. The hook runs after the result files are written so an audit-log emit, registry re-index, or notifier sees the completed rename. When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely; when `{result_path}` is null, skip it with one line saying no result file was written for it to read.
 
-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`.
+### 4. Release the Run Lock and the Run Folder
 
-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):
+Release the lock step 1 §4b took, naming it by its full path. From `{project-root}`, run:
 
+```bash
+uv run {runLockHelper} release \
+    --lock "{forge_data_folder}/.skf-rename-{old_name}.lock" \
+    --owner "{lock_owner}"
 ```
-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}`, `{context_files_updated}`, and `{headless_decisions}` as JSON arrays; `manifest_rekeyed` is the boolean from step 2's context.
+Never stop on the result:
+
+- `released` true, or `reason` `absent`: continue.
+- `reason` `not-owner`: another rename took the lock over after this run's lock went stale, and the helper left that run's lock in place. Tell the user in one line "The run lock {forge_data_folder}/.skf-rename-{old_name}.lock now belongs to {held_by}: another rename of {old_name} took it over while this one ran.", then continue.
+- The command fails or prints no JSON: tell the user in one line "The run lock {forge_data_folder}/.skf-rename-{old_name}.lock was not released ({the first stderr line}); delete it when no rename of {old_name} is running.", then continue.
 
-**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:
+Then, when §1's emitter printed its line, delete the run folder:
 
 ```bash
-{onCompleteCommand} --result-path={skills_output_folder}/{new_name}/rename-skill-result-{timestamp}.json
+rm -f "{run_dir}/result-context.json" "{run_dir}/decision.json" "{run_dir}/headless-decisions.jsonl" "{run_dir}/warnings.jsonl" "{run_dir}/rename-rewrite.json" "{run_dir}/export-manifest.backup.json" && rmdir "{run_dir}"
 ```
 
-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.
+When that fails, tell the user in one line that `{run_dir}` stays and can be deleted, then continue. When §1's emitter printed no line, keep `{run_dir}` instead and tell the user in one line that it holds the run's decisions, its warnings and the payload the emitter refused.
 
-### 2. Chain to Health Check
+### 5. 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.
+The report reads as final, but the workflow ends at step 4: load, read the full file, and then execute `{nextStepFile}`.