bmad-module-skill-forge 1.4.1 → 1.5.0

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

@@ -0,0 +1,57 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-drop-skill.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (uv probe, config load).
+# Overrides append. Use for org-wide pre-flight checks (audit-log emit,
+# ticket-reference enforcement) that must precede any destructive work.
+
+activation_steps_prepend = []
+
+# Steps to run after activation but before the first stage executes.
+# Overrides append. Use for context loads or banner customization that
+# should run once activation completes successfully.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (drop-policy reminders, retention guardrails, audit-trail rules).
+# Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Purges of skills tagged `compliance` require ticket reference."
+#   - a file reference prefixed with `file:`, e.g.
+#     "file:{project-root}/docs/drop-policy.md" (globs supported; file
+#     contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# --- Optional safety + default scalars ---
+#
+# Default drop mode. Empty string = always prompt the user at §8 Ask Mode.
+# Set to "deprecate" or "purge" to skip the prompt — the headless
+# auto-decision log records the override source.
+
+default_mode = ""
+
+# Hard-block hard-purge in headless mode. When set to "true", a headless
+# invocation with `mode=purge` HALTs at activation with exit code 6
+# (`halt_reason: "headless-purge-forbidden"`) instead of silently deleting
+# files. Operators must either re-run with `mode=deprecate` or unset this
+# flag for that run. Empty string = no guard (default).
+
+forbid_purge_in_headless = ""
+
+# Fallback IDE → context-file mapping for unknown IDEs in `config.yaml.ides`.
+# Empty string = use bundled defaults (AGENTS.md / .agents/skills/).
+
+unknown_ide_default_context_file = ""
+unknown_ide_default_skill_root = ""

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

@@ -1,26 +1,42 @@
 ---
-nextStepFile: './step-03-report.md'
+nextStepFile: 'report.md'
 versionPathsKnowledge: 'knowledge/version-paths.md'
 managedSectionLogic: 'skf-export-skill/assets/managed-section-format.md'
+# Resolve `{manifestOpsHelper}` by probing `{manifestOpsProbeOrder}` in
+# order (installed SKF module path first, src/ dev-checkout fallback);
+# first existing path wins. §2 calls it for atomic manifest deprecate /
+# remove with v1→v2 migration handled internally — letting the LLM hand-
+# roll JSON manipulation risks key-order drift, indent regressions, and
+# write-atomicity bugs. HALT if neither candidate exists.
+manifestOpsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-manifest-ops.py'
+  - '{project-root}/src/shared/scripts/skf-manifest-ops.py'
+# Resolve `{rebuildManagedSectionsHelper}` similarly. §3 calls it (replace
+# action) for the surgical between-marker rewrite — the LLM still computes
+# the new managed section text, but the file mutation is deterministic
+# (atomic temp-file + rename, marker preservation, post-write verify).
+rebuildManagedSectionsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-rebuild-managed-sections.py'
+  - '{project-root}/src/shared/scripts/skf-rebuild-managed-sections.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 2: Execute Drop
 
 ## STEP GOAL:
 
-Execute the drop decisions recorded in step-01: update the export manifest, rebuild platform context files so dropped versions disappear from managed sections, and (in purge mode) delete the affected directories from disk. Record everything that was changed for the final report in step-03.
+Execute the drop decisions recorded in step 1: update the export manifest, rebuild platform context files so dropped versions disappear from managed sections, and (in purge mode) delete the affected directories from disk. Record everything that was changed for the final report in step 3.
 
 ## Rules
 
 - Focus only on manifest update, context rebuild, and (in purge mode) file deletion
-- Do not re-prompt the user — decisions were made in step-01
+- Do not re-prompt the user — decisions were made in step 1
 - Do not delete files in deprecate mode; do not widen deletion scope beyond `affected_directories`
 - Report each stage's outcome as it completes
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Re-read Version-Paths Knowledge
 
 Read `{versionPathsKnowledge}` again and confirm the templates and management operations. This ensures the execution step uses the same rules as the selection step even when run in isolation.
@@ -33,32 +49,33 @@ Also read `{managedSectionLogic}` for the format template, the four-case logic,
 
 **If `target_in_manifest == true`:**
 
-Load `{skills_output_folder}/.export-manifest.json`.
+**Resolve `{manifestOpsHelper}`** from `{manifestOpsProbeOrder}`; first existing path wins. HALT (exit code 4, `halt_reason: "manifest-write-failed"`) if no candidate exists — atomic manifest mutation must go through the helper.
 
 **If `is_skill_level == false` (version-level drop):**
 
-For each version in `target_versions`:
+For each version in `target_versions`, invoke:
 
-1. Navigate to `exports.{target_skill}.versions.{version}`
-2. Set `status = "deprecated"`
-3. Leave `ides`, `last_exported`, and all other fields unchanged
+```bash
+python3 {manifestOpsHelper} {skills_output_folder} deprecate {target_skill} {version}
+```
 
-Do NOT change `active_version` on the skill entry in this pass — if the dropped version was the active one (only reachable when it was the sole non-deprecated version per the step-01 guard), the active_version field will still point at it, but every consumer excludes deprecated versions from exports.
+The helper sets `exports.{target_skill}.versions.{version}.status = "deprecated"` and writes the manifest atomically. It does NOT change `active_version` on the skill entry — if the dropped version was the active one (only reachable when it was the sole non-deprecated version per the step 1 guard), the field still points at it, but every consumer excludes deprecated versions from exports.
 
 **If `is_skill_level == true` (skill-level drop):**
 
-1. Delete the `exports.{target_skill}` key entirely from the manifest
-2. Leave all other skill entries untouched
+```bash
+python3 {manifestOpsHelper} {skills_output_folder} remove {target_skill}
+```
 
-**Write the updated manifest back to `{skills_output_folder}/.export-manifest.json`.**
+The helper deletes the `exports.{target_skill}` key entirely; other entries are untouched.
 
 Set context flag `manifest_updated = true`.
 
-**On error (read/parse/write failure):**
+**On error (helper non-zero exit):**
 
 - Do not proceed to section 3
-- Report: "**Manifest update failed:** {error}. No files were deleted and platform context files were not rebuilt. The manifest is in its pre-drop state — rerun the workflow once the underlying issue is resolved."
-- Store `manifest_updated = false` and jump to section 6
+- Report: "**Manifest update failed:** {captured stderr}. No files were deleted and platform context files were not rebuilt. The manifest is in its pre-drop state — rerun the workflow once the underlying issue is resolved."
+- Store `manifest_updated = false` and jump to section 6. In headless mode, emit the error envelope per SKILL.md "Result Contract (Headless)" with `halt_reason: "manifest-write-failed"` and exit code 4.
 
 ### 3. Rebuild Context Files
 
@@ -82,20 +99,20 @@ For each entry in `target_context_files`:
    - If the file exists but contains no `<!-- SKF:BEGIN -->` marker, skip this context file (no managed section to rewrite)
    - If the file contains `<!-- SKF:BEGIN -->` but no matching `<!-- SKF:END -->`, record the error against that context file and continue to the next entry — do not halt the entire drop on a malformed context file. The manifest has already been updated in section 2 and is canonical state; the context file can be repaired manually and rebuilt on the next `[EX] Export Skill` run.
 
-3. **Build the exported skill set (version-aware, deprecated-excluded)** using the same logic as export-skill step-04 section 4b:
+3. **Build the exported skill set (version-aware, deprecated-excluded)** using the same logic as export-skill step 4 section 4b:
    - Read the manifest's `exports` object (already updated in section 2)
    - For each skill, resolve its `active_version`
    - If `versions.{active_version}.status == "deprecated"`, skip that skill entirely
    - The result is the set of `{skill-name, active_version}` pairs that should appear in the managed section
 
-4. **Resolve and filter snippets** using export-skill step-04 section 4c logic:
+4. **Resolve and filter snippets** using export-skill step 4 section 4c logic:
    - For each `{skill-name, active_version}` in the set, read `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md`
    - If the file is missing, fall back to the `active` symlink path, then skip with a warning if still not found
    - Collect successful snippets into the skill index
 
-5. **Rewrite root paths for the current context file** using the generic rewrite algorithm from export-skill step-04 section 4d:
+5. **Rewrite root paths for the current context file** using the generic rewrite algorithm from export-skill step 4 section 4d:
 
-   For each snippet, parse the `root:` line (`root: {prefix}{skill-name}/`), strip the trailing `{skill-name}/` to extract the current prefix, and replace it with the **effective target prefix** if different. The effective target prefix is `snippet_skill_root_override` when that key is set in config.yaml — applied uniformly to every snippet so the managed section references the real on-disk location and never mixes override and per-IDE paths — otherwise the current entry's `skill_root`. See `skf-export-skill/steps-c/step-04-update-context.md` §4d for full semantics.
+   For each snippet, parse the `root:` line (`root: {prefix}{skill-name}/`), strip the trailing `{skill-name}/` to extract the current prefix, and replace it with the **effective target prefix** if different. The effective target prefix is `snippet_skill_root_override` when that key is set in config.yaml — applied uniformly to every snippet so the managed section references the real on-disk location and never mixes override and per-IDE paths — otherwise the current entry's `skill_root`. See `skf-export-skill/references/update-context.md` §4d for full semantics.
 
 6. **Sort skills alphabetically by name.** Count totals (skills, stack skills).
 
@@ -117,17 +134,15 @@ For each entry in `target_context_files`:
 
    If the filtered skill index is empty (e.g., the dropped skill was the only one), still emit the header with `0 skills|0 stack` and no skill entries. This keeps the managed section syntactically valid.
 
-8. **Surgical replacement — Case 3 (Regenerate) only:**
-   - Locate the `<!-- SKF:BEGIN` line — preserve everything before it
-   - Locate the `<!-- SKF:END -->` line — preserve everything after it
-   - Replace everything between the markers (inclusive) with the new managed section
-   - Write the file back
+8. **Surgical replacement — atomic, deterministic.** Resolve `{rebuildManagedSectionsHelper}` from `{rebuildManagedSectionsProbeOrder}`; first existing path wins. Then invoke:
+
+   ```bash
+   python3 {rebuildManagedSectionsHelper} {context_file} replace --content "{new_managed_section_text}"
+   ```
+
+   The helper handles marker location, 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.
 
-9. **Verify:**
-   - Re-read the written file
-   - Confirm both markers are present
-   - Confirm `{target_skill}` (at the dropped version, or at all versions if skill-level) no longer appears between the markers
-   - Confirm content outside the markers is byte-identical to what was preserved
+9. **Verify (deferred to helper).** The `replace` action above performs verification internally. Treat any non-zero exit code as a per-file failure (next bullet). If the helper is missing entirely (no probe candidate exists), HALT (exit code 4, `halt_reason: "context-rebuild-failed"`) — the rewrite cannot proceed without the atomic helper.
 
 10. **On per-file failure:** record the error against that context file and continue to the next entry. Do not halt — other context files should still be rebuilt.
 
@@ -155,7 +170,7 @@ Report: "**Rebuilt managed sections in:** {list of updated files}. {if any faile
    - `{skills_output_folder}/{target_skill}/{version}/` is deleted, but `{skills_output_folder}/{target_skill}/` remains (it still contains other versions or the `active` symlink)
    - If the `active` symlink pointed to the just-deleted version, update or remove it:
      - If other versions remain in the manifest for `{target_skill}`, repoint `active` to the manifest's current `active_version` (skipping deprecated)
-     - If no non-deprecated versions remain, remove the `active` symlink (reachable only when dropping the sole surviving version, which in step-01 was permitted because no other non-deprecated versions existed)
+     - If no non-deprecated versions remain, remove the `active` symlink (reachable only when dropping the sole surviving version, which in step 1 was permitted because no other non-deprecated versions existed)
 
 4. **Skill-level purge:**
    - `{skills_output_folder}/{target_skill}/` and `{forge_data_folder}/{target_skill}/` are deleted in full — the `active` symlink disappears with the parent directory
@@ -180,11 +195,11 @@ Run these verification checks:
 
 3. **Purge check (purge mode only):** For each path in `files_deleted`, confirm it no longer exists on disk.
 
-If any verification fails, record the specific failure in `verification_errors` but do not halt — proceed to step-03 so the report can surface what succeeded and what needs manual attention.
+If any verification fails, record the specific failure in `verification_errors` but do not halt — proceed to step 3 so the report can surface what succeeded and what needs manual attention.
 
 ### 6. Store Results in Context
 
-Store the following for step-03:
+Store the following for step 3:
 
 - `files_deleted` — list of directory paths actually deleted (purge mode) or `[]` (soft drop)
 - `disk_freed` — human-readable size (purge mode) or `"N/A (soft drop)"`

package/src/skf-drop-skill/{steps-c/step-04-health-check.md → references/health-check.md}

@@ -1,10 +1,12 @@
 ---
-# `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
-# to this step file.
+# Note: `shared/health-check.md` resolves relative to the SKF module root
+# ({project-root}/_bmad/skf/ when installed, {project-root}/src/ during
+# development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 4: Workflow Health Check
 
 ## STEP GOAL:
@@ -13,7 +15,7 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 
 ## Rules
 
-- No user-facing reports, file writes, or result contracts in this step — those belong in step-03
+- No user-facing reports, file writes, or result contracts in this step — those belong in step 3
 - Delegate directly to `{nextStepFile}` with no additional commentary
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`
 

package/src/skf-drop-skill/{steps-c/step-03-report.md → references/report.md}

@@ -1,7 +1,9 @@
 ---
-nextStepFile: './step-04-health-check.md'
+nextStepFile: 'health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Render the report block in {document_output_language}. -->
+
 # Step 3: Report Drop Results
 
 ## STEP GOAL:
@@ -10,14 +12,12 @@ Present a clear, final summary of what the drop workflow changed — manifest st
 
 ## Rules
 
-- Focus only on reporting results stored in context by step-02 — do not re-execute any part of the drop
+- Focus only on reporting results stored in context by step 2 — do not re-execute any part of the drop
 - Do not hide verification errors or failed context file rebuilds
 - Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing report is NOT the terminal step
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly.
-
 ### 1. Determine Remaining Versions
 
 **If `is_skill_level == true`:**
@@ -66,13 +66,21 @@ restore the managed section entry.
 {if verification_errors is non-empty:}
 **Verification warnings:**
 {list each verification error}
-These require manual review — see the error-handling guidance in step-02.
+These require manual review — see the error-handling guidance in step 2.
 ```
 
 ### Result Contract
 
 Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skills_output_folder}/drop-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{skills_output_folder}/drop-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all purged file paths in `outputs`; include `target_skill`, `drop_mode`, and `versions_affected` 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_DROP_SKILL_RESULT_JSON: {"status":"success","skill":"{target_skill}","drop_mode":"{drop_mode}","versions_affected":{target_versions},"files_deleted":{files_deleted},"manifest_updated":{manifest_updated},"exit_code":0,"halt_reason":null}
+```
+
+Substitute `{target_versions}` as a JSON array (e.g. `["0.5.0"]`) or the literal string `"all"`; substitute `{files_deleted}` as a JSON array of absolute paths (`[]` in soft-drop mode); `manifest_updated` is the boolean from step 2's context.
+
 ### 3. Chain to Health Check
 
 ONLY WHEN the 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-drop-skill/{steps-c/step-01-select.md → references/select.md}

@@ -1,8 +1,10 @@
 ---
-nextStepFile: './step-02-execute.md'
+nextStepFile: 'execute.md'
 versionPathsKnowledge: 'knowledge/version-paths.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 1: Select Drop Target
 
 ## STEP GOAL:
@@ -18,8 +20,6 @@ Identify exactly what the user wants to drop — which skill, which version(s),
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Load Knowledge
 
 Read `{versionPathsKnowledge}` completely and extract:
@@ -38,7 +38,7 @@ Load `{skills_output_folder}/.export-manifest.json` if it exists.
 
 **If the file exists with entries:** Parse JSON and verify `schema_version` is `"2"`. If the manifest is v1 (no `schema_version` field), note this but continue — treat every entry as having a single active version derived from its current state. Store `manifest_exists = true`.
 
-**Hard halt condition:** If the file exists but is malformed (not valid JSON), halt with: "**Export manifest is corrupt** at `{skills_output_folder}/.export-manifest.json` — fix or remove the file before dropping."
+**Hard halt condition:** If the file exists but is malformed (not valid JSON), halt with: "**Export manifest is corrupt** at `{skills_output_folder}/.export-manifest.json` — fix or remove the file before dropping." HALT (exit code 3, `halt_reason: "manifest-corrupt"`). In headless mode, emit the error envelope per SKILL.md "Result Contract (Headless)" with `skill: null`, `drop_mode: null`, `versions_affected: []`.
 
 ### 3. List Available Skills
 
@@ -53,7 +53,7 @@ For each skill in the manifest's `exports` (only if `manifest_exists = true` and
 
 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 eligible for purge mode only. When the manifest is missing or empty, every on-disk skill appears in this category.
 
-**If the combined list is empty** (no manifest entries AND no on-disk skill directories): halt with "**Drop Skill — nothing to drop.** No skills found in `{skills_output_folder}/` and no entries in `.export-manifest.json`. Run `[CS] Create Skill` first."
+**If the combined list is empty** (no manifest entries AND no on-disk skill directories): halt with "**Drop Skill — nothing to drop.** No skills found in `{skills_output_folder}/` and no entries in `.export-manifest.json`. Run `[CS] Create Skill` first." HALT (exit code 3, `halt_reason: "nothing-to-drop"`). In headless mode, emit the error envelope with `skill: null`, `drop_mode: null`, `versions_affected: []`.
 
 Display the combined list:
 
@@ -73,11 +73,12 @@ Available skills:
 ### 4. Ask Which Skill
 
 "**Which skill would you like to drop?**
-Enter the skill name or its number from the list above."
+Enter the skill name or its number from the list above, or `cancel` / `exit` / `:q` to abort."
 
-Wait for user input. Accept either the numeric index or the skill name (exact match). **GATE [default: use args]** — If `{headless_mode}` and skill name was provided as argument: select that skill and auto-proceed. If not provided, HALT: "headless mode requires skill name argument."
+Wait for user input. Accept either the numeric index or the skill name (exact match). **GATE [default: use args]** — If `{headless_mode}` and skill name was provided as argument: select that skill and auto-proceed. If not provided, HALT (exit code 2, `halt_reason: "input-missing"`): "headless mode requires skill name argument." In headless mode, emit the error envelope with `skill: null`, `drop_mode: null`.
 
-**If the user's input does not match any listed skill:** Re-display the list and ask again.
+- If the user enters `cancel`, `exit`, `[X]`, `q`, or `:q`: Display "Cancelled — no changes were made." and HALT (exit code 6, `halt_reason: "user-cancelled"`).
+- **If the user's input does not match any listed skill:** Re-display the list and ask again.
 
 Store the selection as `target_skill`. Also store `target_in_manifest = true` if the selected skill has an entry in the manifest, `false` otherwise — subsequent sections use this flag to restrict the available drop options.
 
@@ -114,10 +115,13 @@ Store the selection as `target_skill`. Also store `target_in_manifest = true` if
 "**Drop which version(s)?**
 
 - **[N]** Specific version — soft deprecate or hard purge a single version
-- **[A]** All versions — drops the entire skill (skill-level operation)"
+- **[A]** All versions — drops the entire skill (skill-level operation)
+- **[X]** Cancel and exit (or type `cancel` / `exit` / `:q`)"
 
 Wait for user selection.
 
+- If the user enters `cancel`, `exit`, `[X]`, `q`, or `:q`: Display "Cancelled — no changes were made." and HALT (exit code 6, `halt_reason: "user-cancelled"`).
+
 **If [N] Specific version:**
 
 "**Which version?** Enter the version string (e.g. `0.5.0`)."
@@ -149,7 +153,7 @@ Set `target_versions = "all"` and `is_skill_level = true`.
 
       **(b)** Use the `[A] All versions` option to drop every version of `{target_skill}` at once."
 
-      HALT the workflow. Do not proceed.
+      HALT (exit code 5, `halt_reason: "active-version-guard-refused"`). In headless mode, emit the error envelope per SKILL.md "Result Contract (Headless)" with `skill: "{target_skill}"`, `drop_mode: null`, `versions_affected: ["{version}"]`. Do not proceed.
 
    c. If the count is `0` → the active version is the ONLY version; allow the drop to continue (it is functionally equivalent to a skill-level drop on a single-version skill)
 
@@ -159,13 +163,20 @@ Set `target_versions = "all"` and `is_skill_level = true`.
 
 **If `target_in_manifest = true`:**
 
+**If `{defaultMode}` is non-empty (`"deprecate"` or `"purge"`)**: skip the prompt, set `drop_mode = "{defaultMode}"`, and log the override source for the headless decision trail (`"customize.toml.workflow.default_mode"`).
+
+**Otherwise:**
+
 "**How should this be dropped?**
 
 - **[D]** Deprecate (soft) — Mark the version as `deprecated` in the manifest. Files remain on disk. Export-skill will exclude it from all platform context files. Reversible by editing the manifest.
-- **[P]** Purge (hard) — Deprecate AND delete files from disk (`{skill_package}` and `{forge_version}`, or full `{skill_group}` and `{forge_group}` for a skill-level drop). **Irreversible.**"
+- **[P]** Purge (hard) — Deprecate AND delete files from disk (`{skill_package}` and `{forge_version}`, or full `{skill_group}` and `{forge_group}` for a skill-level drop). **Irreversible.**
+- **[X]** Cancel and exit (or type `cancel` / `exit` / `:q`)"
 
 Wait for user selection.
 
+- If the user enters `cancel`, `exit`, `[X]`, `q`, or `:q`: Display "Cancelled — no changes were made." and HALT (exit code 6, `halt_reason: "user-cancelled"`).
+
 Set `drop_mode` to `"deprecate"` (on D) or `"purge"` (on P).
 
 ### 9. Compute Affected Directories
@@ -187,9 +198,27 @@ Store the list as `affected_directories`.
 
 If `drop_mode == "deprecate"`, record the list but present it as "retained" in the confirmation output — no deletion will occur.
 
+#### 9b. Compute Blast-Radius Metrics (for §10 summary)
+
+Compute three scalars to put in front of the path list at §10. The user's "I didn't know it would touch THAT" footgun is real — 12 paths can hide 50MB of on-disk content and a sweep across every IDE's managed section. A one-line summary makes the scale legible before the gate.
+
+1. **`versions_count`** — the number of skill versions in scope:
+   - Version-level drop: `len(target_versions)` (typically `1`)
+   - Skill-level drop: count of non-deprecated versions in `exports.{target_skill}.versions` (the deprecated ones are already absent from the active managed sections)
+
+2. **`bytes_total`** — recursive sum of byte sizes for every path in `affected_directories` that exists on disk. For each path, walk it and sum file sizes (`du -sb {path}` or equivalent). Skip non-existent paths silently — the §10 display is best-effort. Convert to a human-readable string for display (e.g. `"4.2 MB"`, `"812 KB"`); store the raw integer alongside as `bytes_total_raw` if a downstream step wants exact arithmetic. Defense in depth with execute.md §4 — that section will recompute per-path sizes for the canonical `disk_freed` reporting; this pre-compute is purely for the gate display and may slightly disagree if files change between gate and execute (acceptable for an "approximate" label).
+
+3. **`context_files_count`** — the number of distinct context files the §3 rebuild loop will rewrite:
+   - Read `config.yaml.ides`
+   - For each entry, look up its `context_file` via the canonical mapping table in `skf-export-skill/assets/managed-section-format.md` (use `AGENTS.md` fallback for unknown IDEs)
+   - Deduplicate by `context_file`
+   - Count the result. If `config.yaml.ides` is absent or empty, default to `1` (the AGENTS.md fallback)
+
+Store as `blast_radius = {versions_count, bytes_total, bytes_total_raw, context_files_count}` for §10's summary line.
+
 ### 10. Confirmation Gate
 
-Display the full operation summary:
+Display the full operation summary with the blast-radius summary line ahead of the path list so the user sees the scale before scanning paths:
 
 ```
 **About to drop:**
@@ -197,6 +226,7 @@ Display the full operation summary:
   Skill:   {target_skill}
   Version: {version or "ALL versions"}
   Mode:    {Deprecate (soft) | Purge (hard)}
+  Scope:   {versions_count} version(s), ~{bytes_total} on disk, will rebuild {context_files_count} context file(s)
   Files:
     {for each path in affected_directories, list one per line}
     {or "(retained on disk — soft drop)" if drop_mode == "deprecate"}
@@ -209,24 +239,42 @@ Display the full operation summary:
 Proceed? [Y/N]
 ```
 
+The `Scope:` line is the §9b-computed `blast_radius` rendered as one line. In `deprecate` mode the `~{bytes_total} on disk` reads as "size that will remain on disk (soft drop — files retained)"; the user is still served by knowing it. In `purge` mode it reads as "approximate disk that will be freed". The wording stays the same — the surrounding `Mode:` field disambiguates intent.
+
 **GATE [default: Y]** — If `{headless_mode}`: auto-proceed with [Y], log: "headless: auto-confirmed drop of {target_skill}"
 
 Wait for explicit user response.
 
+**If `--dry-run` was passed**: skip the Y/N prompt entirely. Display the `[DRY RUN]` line followed by a copy-pasteable selection memo so the user can capture this preview in their shell history and re-run it (interactively, picking the same values) when they're ready to commit:
+
+```
+**[DRY RUN] No changes were made — preview above shows what would be dropped.**
+
+To repeat this selection later:
+  Skill:   {target_skill}
+  Version: {target_versions[0] if is_skill_level == false else "all"}
+  Mode:    {Deprecate (soft) | Purge (hard)}
+
+Re-invoke `/skf-drop-skill {target_skill}` and re-select these values, or
+re-run with `--dry-run` to preview again.
+```
+
+Then emit the success envelope per SKILL.md "Result Contract (Headless)" with `status: "dry-run"`, the resolved `skill`, `drop_mode`, and `versions_affected`, then HALT (exit code 0). The manifest, filesystem, and context files are untouched.
+
 - **If `Y`** → proceed to section 11
-- **If `N`** → "**Cancelled.** No changes were made." HALT the workflow
+- **If `N`** (or `cancel` / `exit` / `[X]` / `:q`) → "**Cancelled.** No changes were made. (Tip: invoke with `--dry-run` next time to preview the operation without reaching the commit prompt.)" HALT (exit code 6, `halt_reason: "user-cancelled"`). In headless mode, emit the error envelope per SKILL.md "Result Contract (Headless)" with the resolved `skill`, `drop_mode`, and `versions_affected`.
 - **Any other input** → re-display the confirmation and ask again
 
 ### 11. Store Decisions in Context
 
-Store the following decisions in workflow context for step-02:
+Store the following decisions in workflow context for step 2:
 
 - `target_skill` — the skill name
 - `target_in_manifest` — boolean (true if the skill has a manifest entry, false if it was discovered only by on-disk scan)
 - `target_versions` — list of version strings (`[<version>]`) or the literal string `"all"`
 - `drop_mode` — `"deprecate"` or `"purge"` (always `"purge"` when `target_in_manifest = false`)
 - `is_skill_level` — boolean (true if all versions; always true when `target_in_manifest = false`)
-- `affected_directories` — list of absolute directory paths that step-02 will delete in purge mode (or retain in deprecate mode)
+- `affected_directories` — list of absolute directory paths that step 2 will delete in purge mode (or retain in deprecate mode)
 
 ### 12. Load Next Step
 

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

@@ -9,6 +9,15 @@ description: Package for distribution and inject context into CLAUDE.md/AGENTS.m
 
 Packages a completed skill as an agentskills.io-compliant package, generates context snippets, and updates the managed section in CLAUDE.md/.cursorrules/AGENTS.md for platform-aware context injection. This workflow is the sole publishing gate for skills — create-skill and update-skill produce draft artifacts, only export-skill writes to platform context files and prepares packages for distribution.
 
+## Conventions
+
+- Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+- **Cross-skill data coupling (export-skill is a hub):** `assets/managed-section-format.md` is loaded by `skf-drop-skill/references/execute.md` and `skf-rename-skill/references/execute.md` (IDE→context-file mapping table and four-case logic). `references/update-context.md` §4a manifest-schema documentation is the source of truth for the v2 schema enforced by `skf-manifest-ops.py`. Other skills depend on these files at install time — schema-breaking changes here require coordinated updates across at least three skills.
+
 ## Role
 
 You are a delivery and packaging specialist collaborating with a skill developer. You bring expertise in skill packaging, ecosystem compliance, and context injection patterns, while the user brings their completed skill and distribution requirements.
@@ -17,33 +26,57 @@ You are a delivery and packaging specialist collaborating with a skill developer
 
 These rules apply to every step in this workflow:
 
-- Read each step file completely before taking any action
-- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
 - Only load one step file at a time — never preload future steps
 - Always communicate in `{communication_language}`
+- At any interactive prompt, the inputs `cancel`, `exit`, `[X]`, `q`, or `:q` exit cleanly with exit code 6 (`halt_reason: "user-cancelled"`)
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
-| 1 | Load Skill | steps-c/step-01-load-skill.md | No (confirm) |
-| 2 | Package | steps-c/step-02-package.md | Yes |
-| 3 | Generate Snippet | steps-c/step-03-generate-snippet.md | Yes |
-| 4 | Update Context | steps-c/step-04-update-context.md | No (confirm) |
-| 5 | Token Report | steps-c/step-05-token-report.md | Yes |
-| 6 | Summary | steps-c/step-06-summary.md | Yes |
-| 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
+| 1 | Load Skill | references/load-skill.md | No (confirm) |
+| 2 | Package | references/package.md | Yes |
+| 3 | Generate Snippet | references/generate-snippet.md | Yes |
+| 4 | Update Context | references/update-context.md | No (confirm) |
+| 5 | Token Report | references/token-report.md | Yes |
+| 6 | Summary | references/summary.md | Yes |
+| 7 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | skill_name [one or more, required unless `--all`], `--all` [optional — exports every non-deprecated skill in `.export-manifest.json`] |
-| **Gates** | step-01: single Confirm Gate [C] for the whole batch | step-04: single Confirm Gate [C] for the whole batch |
-| **Outputs** | Updated .export-manifest.json (every skill in the batch), updated context files (CLAUDE.md/AGENTS.md/.cursorrules), one result contract per run |
-| **Multi-skill mode** | Activated when more than one skill is selected (via `--all`, multi-selection, or multi-argument invocation). See `steps-c/step-01-load-skill.md` §1c for the per-step iteration map. |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **Inputs** | `skill_name` [one or more, required unless `--all`] |
+| **Flags** | `--headless` / `-H` (auto-resolve all gates); `--all` (export every non-deprecated skill in `.export-manifest.json`); `--dry-run` (resolve and stage everything but exit before §4 writes to context files; envelope `status="dry-run"`) |
+| **Gates** | step 1: single Confirm Gate [C] for the whole batch | step 4: single Confirm Gate [C] for the whole batch |
+| **Outputs** | Updated `.export-manifest.json` (every skill in the batch), updated context files (CLAUDE.md/AGENTS.md/.cursorrules), per-skill `context-snippet.md`, per-run result contract `export-skill-result-{timestamp}.json` and `export-skill-result-latest.json` |
+| **Multi-skill mode** | Activated when more than one skill is selected (via `--all`, multi-selection, or multi-argument invocation). See `references/load-skill.md` §1c for the per-step iteration map. |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. Each auto-resolved gate appends a `{gate, default_action, taken_action, reason}` entry to `headless_decisions[]`, surfaced in step 6's `SKF_EXPORT_RESULT_JSON` envelope so non-interactive runs can be audited post-hoc. |
+| **Exit codes** | See "Exit Codes" below |
+
+## Exit Codes
+
+Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
+
+| Code | Meaning              | Raised by                                                                                    |
+| ---- | -------------------- | -------------------------------------------------------------------------------------------- |
+| 0    | success              | step 7 (terminal); also `status="dry-run"` when `--dry-run` is set                          |
+| 2    | input-missing / input-invalid | step 1 (no `skill_name` and no `--all` in headless) → `input-missing`; non-existent or malformed skill → `input-invalid` |
+| 3    | resolution-failure   | step 1 §2 (no skills found / required artifacts missing); step 1 §1c (multi-skill batch contains a stack-skill that requires re-composition) |
+| 4    | write-failure        | On-Activation §3 pre-flight write probe; step 4 §6 (managed-section rewrite); step 4 §9 (manifest write); step 6 §4 (result-contract write) |
+| 5    | state-conflict       | step 4 §3b/§4c.1 (orphan context-files or manifest-orphan rows when user selects [c] Cancel); step 4 (malformed `<!-- SKF:BEGIN/END -->` markers in target context file) |
+| 6    | user-cancelled       | step 1 §6 confirmation gate `[X]`/cancel; step 4 §8 confirmation gate `[X]`/cancel; any prompt that accepted `cancel`/`exit`/`:q` |
+
+## Result Contract (Headless)
+
+When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
+
+```
+SKF_EXPORT_RESULT_JSON: {"status":"success|error|dry-run","skills":[],"context_files_updated":[],"manifest_path":"…|null","headless_decisions":[],"exit_code":0,"halt_reason":null}
+```
+
+`status` is `"success"` on the terminal happy path, `"dry-run"` when `--dry-run` was set and the workflow exited before §4 writes, `"error"` on any HALT. `halt_reason` is one of: `null` (success / dry-run), `"input-missing"`, `"input-invalid"`, `"resolution-failure"`, `"stack-redirect"`, `"orphan-cancelled"`, `"malformed-markers"`, `"manifest-write-failed"`, `"context-rebuild-failed"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above.
 
 ## On Activation
 
@@ -52,6 +85,42 @@ These rules apply to every step in this workflow:
    - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
    - `snippet_skill_root_override` (optional string) — when set, overrides the IDE-derived `skill_root` for snippet `root:` paths. Authoring repos that keep all skills under a single on-disk folder (e.g. `skills/`) set this once so exported snippets reference the real layout instead of a per-IDE directory that does not exist. Consuming projects omit it.
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+2. **Compute run-scoped variables:**
+   - `timestamp` ← UTC `YYYYMMDD-HHmmss` captured at activation time. Fixed for the entire workflow run; summary.md reuses this when writing the result contract.
+
+3. **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.
+
+4. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-root} --key workflow
+   ```
+
+   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+
+   - `{skill-root}/customize.toml` — bundled defaults
+   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
+   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+
+   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+
+   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each scalar, if the merged value is empty or absent, use the bundled default:
+
+   - `{managedSectionFormatPath}` ← `workflow.managed_section_format_path` if non-empty, else `assets/managed-section-format.md`
+   - `{snippetFormatPath}` ← `workflow.snippet_format_path` if non-empty, else `assets/snippet-format.md`
+   - `{exportManifestPath}` ← `workflow.export_manifest_path` if non-empty, else `{skills_output_folder}/.export-manifest.json`
+
+   Stash all three as workflow-context variables. Stage files reference them directly — no conditional at the usage site.
+
+5. **Pre-flight write probe.** Verify `{skills_output_folder}` is writable. A read-only mount, full disk, or permissions-denied path otherwise only surfaces at step 4's managed-section rewrite — by then the user has already confirmed the batch:
+
+   ```bash
+   mkdir -p "{skills_output_folder}" && \
+     printf 'probe' > "{skills_output_folder}/.skf-write-probe" && \
+     rm "{skills_output_folder}/.skf-write-probe"
+   ```
+
+   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 `skills: []`, `context_files_updated: []`, `manifest_path: null`.
 
-3. Load, read the full file, and then execute `./steps-c/step-01-load-skill.md` to begin the workflow.
+6. Load, read the full file, and then execute `references/load-skill.md` to begin the workflow.