bmad-module-skill-forge 2.2.0 → 3.0.0

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

@@ -16,8 +16,8 @@ Renames a skill across all its versions with transactional safety — copy to th
 - `{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.
+- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root; e.g. `shared/health-check.md`, which the terminal step chains to, and the envelope schema `shared/scripts/schemas/skf-rename-skill-result-envelope.v1.json`.
+- **Sibling skills:** a path that names another SKF skill's folder (`skf-<name>/...`) resolves from the SKF module root, and that skill must be installed with this one. On Activation step 1 cites `skf-export-skill/assets/managed-section-format.md`, the format the context-file rebuild writes.
 
 ## Role
 
@@ -30,8 +30,9 @@ 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
+- Never rename a folder SKF did not generate: select.md §4a takes that verdict from the inventory helper
 - 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 — **except** the atomicity and commit-gate safety helpers that execute.md §0 resolves: a missing one there is a HARD HALT (exit 4), never an LLM fall-through, because hand-driven writes/scans would silently regress the transactional guarantees that keep a failed rename recoverable
+- Every helper is required: select.md §1, §5's validator call and execute.md §0 halt (exit 4) without one, and no stage does a helper's write, scan or check by hand
 - 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
@@ -41,78 +42,42 @@ These rules apply to every step in this workflow:
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
 | 1 | Select & Validate | references/select.md | No (confirm) |
-| 2 | Execute Rename | references/execute.md | No (confirm) |
+| 2 | Execute Rename | references/execute.md | Yes |
 | 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] |
-| **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** | A PID-file lock at `{forge_data_folder}/{old_name}/.skf-rename.lock` serializes concurrent runs against the same `old_name`; a live-PID collision HALTs with `halt_reason: "halted-for-concurrent-run"` (exit 5). See select.md §4b for the acquire / stale-clear / release mechanism. |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. The §6 source-authority warning HALTs by default in headless when `source_authority="official"`; set `force_source_authority_in_headless = "true"` in `customize.toml` to auto-acknowledge and proceed (the override is recorded in `headless_decisions[]`). |
-| **Exit codes** | Stable per-failure-class codes — see `references/exit-codes.md` |
-
-## Result Contract (Headless)
-
-When `{headless_mode}` is true, step 3 emits a single-line JSON envelope on **stdout** before chaining to step 4, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
-
-```
-SKF_RENAME_SKILL_RESULT_JSON: {"status":"success|error|dry-run","old_name":"…|null","new_name":"…|null","versions_renamed":[],"manifest_rekeyed":false,"context_files_updated":[],"exit_code":0,"halt_reason":null,"headless_decisions":[]}
-```
-
-`status` is `"success"` on the terminal happy path, `"dry-run"` when `--dry-run` was set and the workflow exited before §9 stores decisions, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"manifest-corrupt"`, `"nothing-to-rename"`, `"name-collision"`, `"source-authority-blocked"`, `"halted-for-concurrent-run"`, `"copy-failed"`, `"verify-failed"`, `"manifest-write-failed"`, `"write-failed"`, `"user-cancelled"`. (§7 context-file rebuild is best-effort and never halts, so it has no `halt_reason`.) `exit_code` matches `references/exit-codes.md`. `headless_decisions` is the audit trail of confirmation gates auto-resolved under `{headless_mode}` — each entry `{gate, default_action, taken_action, reason}` (the §6 source-authority override and the §8 auto-confirm); it is `[]` in interactive runs and whenever no gate was auto-resolved before the envelope was emitted.
+Headless callers: the inputs, flags, gate map, outputs, concurrency rule and `SKF_RENAME_SKILL_RESULT_JSON` result envelope live in `references/invocation-contract.md`, and the exit codes in `references/exit-codes.md`. Interactive runs do not need them.
 
 ## 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 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.
+   - `snippet_skill_root_override` (optional string): when set, the context-file rebuild in step 2 passes it to `assemble` as `--skill-root-override`, so every row's `root:` takes it instead of the target IDE's skill root. See `skf-export-skill/assets/managed-section-format.md` for full semantics.
 
-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.
+2. **Bind the invocation once**, in every mode:
+   - `{headless_mode}`: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
+   - `{acknowledge_official}`: true if `--acknowledge-official` was passed, else false.
+   - `{dry_run}`: true if `--dry-run` was passed, else false.
+   - `{old_name_arg}` and `{new_name_arg}`: the current name and the new name the invocation supplied, as arguments or in a request such as "rename cognee to cognee-ai", each null when absent. select.md §4 and §5 take a supplied name in either mode instead of asking for it.
 
 3. **Resolve workflow customization.** Run:
 
    ```bash
-   python3 {project-root}/_bmad/scripts/resolve_customization.py \
-       --skill {skill-root} --key workflow
+   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-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.
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-rename-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case keep the reason as `{customization_resolver_unavailable}` (unset when the resolver ran) for select.md §1 to record once it has created `{run_dir}`.
 
-   Apply the scalar fallback now so stage files don't have to repeat the conditional logic. For each of the four scalars, if the merged value is empty or absent, the bundled default applies:
+   Apply the scalar fallback now so stage files don't have to repeat the conditional logic. For each of the two 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/`
+   - `{forceSourceAuthorityInHeadless}` ← true when `workflow.force_source_authority_in_headless` is `"true"` or the TOML boolean `true`, else false (a headless run halts on an `"official"` skill unless it passes `--acknowledge-official`)
    - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string (no-op — step 3 skips the post-completion hook invocation)
 
-   Stash all four as workflow-context variables. Stage files reference them directly — no conditional at the usage site.
-
-   Then apply the resolved array surfaces so they are not silent no-ops: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (entries prefixed `file:` are paths or globs whose contents load as facts — the bundled default loads any `project-context.md` so rename-policy and public-name-stability guardrails stay in mind); and after activation completes, execute each entry in `workflow.activation_steps_append` in order.
-
-4. **Pre-flight write probe.** Verify both `{skills_output_folder}` and `{forge_data_folder}` are writable. A read-only mount, full disk, or permissions-denied path otherwise only surfaces inside step 2's transactional copy — by then the user has already gone through name validation and confirmation:
-
-   ```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
-   ```
+   Stash both as workflow-context variables. Stage files reference them directly, with no conditional at the usage site.
 
-   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).
+   Then apply the resolved array surfaces so they are not silent no-ops: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (entries prefixed `file:` are paths or globs whose contents load as facts: the bundled default loads every `project-context.md` under `{project-root}`; an entry prefixed `!` drops each earlier entry it names and loads nothing itself, so an override's `"!file:{project-root}/**/project-context.md"` turns that default off); and after activation completes, execute each entry in `workflow.activation_steps_append` in order.
 
-5. Load, read the full file, and then execute `references/select.md` to begin the workflow.
+4. Load, read the full file, and then execute `references/select.md` to begin the workflow.

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

@@ -1,8 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-rename-skill.
-# Team overrides:     _bmad/custom/skf-rename-skill.toml (under {project-root})
-# Personal overrides: _bmad/custom/skf-rename-skill.user.toml (under {project-root})
+# Team overrides:     {project-root}/_bmad/custom/skf-rename-skill.toml
+# Personal overrides: {project-root}/_bmad/custom/skf-rename-skill.user.toml
 
 [workflow]
 
@@ -10,15 +10,16 @@
 #   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,
+# Steps to run in On Activation step 3, after config load and headless
+# resolution and before the workflow's first step (select.md). 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.
+# Steps to run at the end of On Activation, after the prepend steps and
+# the persistent facts load, just before select.md loads. Overrides append.
+# Use for context loads or banner customization.
 
 activation_steps_append = []
 
@@ -26,37 +27,42 @@ activation_steps_append = []
 # (rename-policy reminders, public-name-stability rules, audit guardrails).
 # Overrides append.
 #
-# Each entry is either:
+# Each entry is one of:
 #   - 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).
+#   - an entry prefixed with `!`, which loads nothing and drops each earlier
+#     entry it names.
+#
+# The default below loads every project-context.md under {project-root}.
+# Overrides append, so they cannot delete it; to stop loading those files,
+# set in {project-root}/_bmad/custom/skf-rename-skill.toml:
+#   persistent_facts = ["!file:{project-root}/**/project-context.md"]
 
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
 
-# Optional post-completion hook. When non-empty, invoked with
-# `--result-path=<path>` in step 3 after the rename result JSON is
-# finalized (before the terminal health-check step). Failures are logged
-# but never fail the workflow — the rename is already committed. Use for
-# an audit-log emit, skill-registry re-index, or a post-rename notifier.
+# Optional post-completion hook: a shell command, run from {project-root}
+# in report step 3 with `--result-path=<the per-run result file the shared
+# emitter wrote>` appended, before the terminal health-check step. It is
+# skipped when the emitter wrote no result file, and a --dry-run never
+# reaches it. A hook failure is logged and never fails the rename, which is
+# already committed. Use for an audit-log emit, a skill-registry re-index or
+# a post-rename notifier.
 
 on_complete = ""
 
-# --- Optional safety + default scalars ---
+# --- Optional safety scalar ---
 #
-# 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.
+# A standing approval for headless renames of skills whose
+# source_authority is "official". Empty (the default) halts such a run with
+# source-authority-blocked unless its invocation passes
+# --acknowledge-official, which approves that one run and is the preferred
+# answer: a local rename diverges from any registry-published name. Set it
+# to "true" (or the TOML boolean true) in a team or personal override to
+# let every headless rename of an official skill proceed; each run still
+# records the decision in its headless_decisions.
 
 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 = ""