bmad-module-skill-forge 1.4.1 → 1.5.1

package/src/skf-create-stack-skill/{steps-c/step-04-parallel-extract.md → references/parallel-extract.md}

@@ -1,7 +1,12 @@
 ---
-nextStepFile: './step-05-detect-integrations.md'
+nextStepFile: 'detect-integrations.md'
+enumerateStackSkillsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-enumerate-stack-skills.py'
+  - '{project-root}/src/shared/scripts/skf-enumerate-stack-skills.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 4: Parallel Library Extraction
 
 ## STEP GOAL:
@@ -16,32 +21,54 @@ For each confirmed dependency, extract key exports, usage patterns, and API surf
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 0. Check Compose Mode
 
 **If `compose_mode` is true:**
 
 "**Extraction data already available from individual skills. Skipping extraction phase.**"
 
-For each confirmed skill, load SKILL.md from the version-aware path resolved in step-02.
+For each confirmed skill, load SKILL.md from the version-aware path resolved in step 2.
+
+**Re-resolve at step 4 entry (S17):** Between step 2 manifest detection and step 4 extraction, a concurrent write could have advanced a skill's `active_version`. On entering this step, re-resolve `skill_package_path` for each confirmed skill via the export-manifest (or symlink fallback) and capture the freshly-read `version` and `metadata_hash` into workflow state. If the `metadata_hash` diverges from the value stored in step 2, log a warning `"constituent '{skill_name}' changed between step 2 and step 4 — using fresh values"` and replace the workflow-state entry (so step 7 provenance records the hash active at extraction time, with the drift logged for audit).
+
+Use `skill_package_path` (stored in step 2 and optionally refreshed above) directly — this already points to the resolved `{skill_package}` or `{active_skill}` directory containing the skill's artifacts. If `skill_package_path` is not available, resolve via the `{active_skill}` template: `{skills_output_folder}/{skill_dir}/active/{skill_dir}/SKILL.md` (see `knowledge/version-paths.md`).
+
+**Exports resolution order (H1) — script-driven:** Do NOT walk per-skill `metadata.json` → `references/` → SKILL.md by hand. Invoke the helper once at step entry to compute the full inventory for every confirmed skill in one deterministic call:
 
-**Re-resolve at step-04 entry (S17):** Between step-02 manifest detection and step-04 extraction, a concurrent write could have advanced a skill's `active_version`. On entering this step, re-resolve `skill_package_path` for each confirmed skill via the export-manifest (or symlink fallback) and capture the freshly-read `version` and `metadata_hash` into workflow state. If the `metadata_hash` diverges from the value stored in step-02, log a warning `"constituent '{skill_name}' changed between step-02 and step-04 — using fresh values"` and replace the workflow-state entry (so step-07 provenance records the hash active at extraction time, with the drift logged for audit).
+**Resolve `{enumerateStackSkillsHelper}`** from `{enumerateStackSkillsProbeOrder}`; first existing path wins. HALT if no candidate exists.
 
-Use `skill_package_path` (stored in step-02 and optionally refreshed above) directly — this already points to the resolved `{skill_package}` or `{active_skill}` directory containing the skill's artifacts. If `skill_package_path` is not available, resolve via the `{active_skill}` template: `{skills_output_folder}/{skill_dir}/active/{skill_dir}/SKILL.md` (see `knowledge/version-paths.md`).
+```bash
+uv run {enumerateStackSkillsHelper} enumerate {skills_output_folder}
+```
+
+The script emits JSON of the form:
 
-**Exports resolution order (H1):** For each confirmed skill, populate the `exports` field using the first source that returns a non-empty list:
+```json
+{
+  "skills": [
+    {
+      "name": "<skill-name>",
+      "path": "<rel-to-skills-root, forward-slash>",
+      "exports": ["..."],
+      "exports_source": "metadata|references|skill-md|unknown",
+      "confidence": "T1|T2|T1-low",
+      "metadata_hash": "sha256:..." | null
+    }
+  ],
+  "cycles": ["<skill-name>"],
+  "warnings": ["<text>"]
+}
+```
 
-1. **Primary — `metadata.json.exports[]`:** Read the skill's `metadata.json` and use the `exports[]` array directly. This is the most structured and trustworthy source.
-2. **Fallback — `references/`:** If `metadata.json.exports[]` is empty or missing, scan the `references/` subdirectory of the skill package for per-export files and reconstruct the export list from filenames/headers. Log a warning: `"{skill_name}: metadata.json.exports[] empty — reconstructed from references/"` and record the warning in workflow state for the evidence report.
-3. **Last resort — SKILL.md prose parsing:** If both prior sources are unavailable, parse the SKILL.md "Exports" / "API" section prose. Log a stronger warning: `"{skill_name}: falling back to SKILL.md prose parsing — exports may be incomplete"` and record it in workflow state.
+Cache this result as `stack_skill_inventory` in workflow state — the per-skill subagent fan-out at §1+ MUST read from this cache rather than re-reading each skill's `SKILL.md` / `metadata.json` / `references/` to determine exports. Append every entry in `warnings[]` to workflow state for the evidence report (the script already labels them per-skill, e.g. `"<skill-name>: no exports found via any resolution path"`). For every entry in `cycles[]`, halt with a structured-error contract on stderr — a composes-cycle makes the stack unbuildable.
 
-Build a `per_library_extractions[]` entry for each skill with the following fields:
-- `library`: skill name from metadata.json
-- `exports`: exports list resolved via the order above
-- `exports_source`: one of `metadata|references|prose` — capture which resolution path was used (so step-07 provenance can record it)
-- `usage_patterns`: usage patterns from the SKILL.md usage section
-- `confidence`: the skill's existing confidence tier (one of `T1|T1-low|T2|T3` per `confidence-tiers.md`) — inherited directly. Do not silently drop T3 evidence; carry whatever tier the source skill declared.
+Build a `per_library_extractions[]` entry for each skill by reading from the cached inventory:
+- `library`: `inventory.skills[i].name`
+- `exports`: `inventory.skills[i].exports`
+- `exports_source`: `inventory.skills[i].exports_source` (one of `metadata|references|skill-md|unknown` — capture for step 7 provenance)
+- `confidence`: `inventory.skills[i].confidence` (one of `T1|T2|T1-low`; `unknown` source ⇒ `T1-low`). Do not silently drop T3 evidence; carry whatever tier the source skill declared if §1+ subagent analysis upgrades the value.
+- `metadata_hash`: `inventory.skills[i].metadata_hash` — record for step 7 provenance (null when exports came from references/ or SKILL.md prose).
+- `usage_patterns`: populated by the §1+ per-skill subagent fan-out, NOT by this script. The script provides the inventory + exports; the subagent does the per-skill usage analysis. They're complementary.
 
 Display an extraction summary:
 
@@ -150,7 +177,7 @@ For each library extraction:
 **If ALL extractions fail:** HALT — cannot produce meaningful stack skill. Before halting (B7):
 
 1. Purge any in-flight staging artifacts under the forge workspace: remove `{forge_data_folder}/{project_name}-stack/{version}/*-tmp` and any `{forge_data_folder}/{project_name}-stack/{version}/*.skf-tmp` directories so partial state does not linger.
-2. Emit a structured error contract on stderr: `{"status":"error","skill":"skf-create-stack-skill","stage":"step-04","reason":"all extractions failed","libraries":[...]}`.
+2. Emit a structured error contract on stderr: `{"status":"error","skill":"skf-create-stack-skill","stage":"step 4","reason":"all extractions failed","libraries":[...]}`.
 3. Exit with a non-zero status so headless pipelines detect the failure.
 
 ### 4. Display Extraction Summary

package/src/skf-create-stack-skill/{steps-c/step-03-rank-and-confirm.md → references/rank-and-confirm.md}

@@ -1,7 +1,9 @@
 ---
-nextStepFile: './step-04-parallel-extract.md'
+nextStepFile: 'parallel-extract.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 3: Rank and Confirm Scope
 
 ## STEP GOAL:
@@ -15,8 +17,6 @@ Count import frequency for each dependency across the codebase, rank by usage, a
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Count Import Frequency
 
 **If `compose_mode` is true:**
@@ -122,7 +122,7 @@ Display final confirmation:
 
 ### 5. Present MENU OPTIONS
 
-Display: **Select:** [C] Continue to Extraction
+Display: **Select:** [C] Continue to Extraction | [X] Cancel and exit
 
 #### EXECUTION RULES:
 
@@ -133,5 +133,6 @@ Display: **Select:** [C] Continue to Extraction
 #### Menu Handling Logic:
 
 - IF C: Store current `confirmed_dependencies` (including any modifications made since initial presentation), then load, read entire file, then execute {nextStepFile}
+- IF X: Invoke the rollback contract (purge any `{forge_data_folder}/{project_name}-stack/{version}/*-tmp` and `*.skf-tmp` staging artifacts under the forge workspace, leave any existing committed stack package untouched), emit the `SKF_STACK_RESULT_JSON` envelope on stderr with `status: "error"`, `halt_reason: "user-cancelled"`, `exit_code: 6`, and exit with code 6
 - IF Any other: Process as scope modification (add/remove skills from `confirmed_dependencies`), update the in-memory `confirmed_dependencies` list accordingly, redisplay the updated skills table, then [Redisplay Menu Options](#5-present-menu-options)
 

package/src/skf-create-stack-skill/{steps-c/step-09-report.md → references/report.md}

@@ -1,5 +1,5 @@
 ---
-nextStepFile: './step-10-health-check.md'
+nextStepFile: 'health-check.md'
 # Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
 # path wins. HALT if neither resolves.
@@ -8,6 +8,8 @@ atomicWriteProbeOrder:
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
+<!-- Config: communicate in {communication_language}. Artifact text in {document_output_language}. -->
+
 # Step 9: Stack Skill Report
 
 ## STEP GOAL:
@@ -23,8 +25,6 @@ Display the final summary of the forged stack skill with confidence distribution
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Display Stack Forged Banner
 
 "**Stack forged: {project_name}-stack — {lib_count} libraries, {integration_count} integration patterns**

package/src/skf-create-stack-skill/{steps-c/step-08-validate.md → references/validate.md}

@@ -1,8 +1,10 @@
 ---
-nextStepFile: './step-09-report.md'
+nextStepFile: 'report.md'
 stackSkillTemplate: 'assets/stack-skill-template.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Artifact text in {document_output_language}. -->
+
 # Step 8: Validate Output
 
 ## STEP GOAL:
@@ -16,8 +18,6 @@ Validate all written output files against their expected structure and verify co
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Verify File Existence
 
 Check that all expected files exist from written_files[]:
@@ -47,7 +47,7 @@ timeout 10s npx --no-install skill-check -h
 ```
 
 - If exits 0: Use skill-check for automated validation in sections 3, 9.
-- If exits non-zero, times out, or returns "command not found": Use manual fallback paths. Mark `metadata.validation_status: "manual-only"` (do this in step-07 when appropriate) and record every skipped check in the evidence report.
+- If exits non-zero, times out, or returns "command not found": Use manual fallback paths. Mark `metadata.validation_status: "manual-only"` (do this in step 7 when appropriate) and record every skipped check in the evidence report.
 
 **Important:** Do not assume availability — empirical check required.
 
@@ -57,7 +57,7 @@ timeout 10s npx --no-install skill-check -h
 
 This validates frontmatter, description, body limits, links, formatting — and auto-fixes deterministic issues. Parse JSON for `qualityScore`, `diagnostics[]`, `fixed[]`.
 
-**Post-fix provenance drift guard (S15):** If `fixed[]` is non-empty, `skill-check --fix` has modified `SKILL.md` after step-07 wrote it. The safe default for v1.0 is to emit a **WARNING** finding listing each auto-fix (`"skill-check --fix modified SKILL.md: {fix_description} — metadata.json hashes/provenance may be out of date"`). Do NOT silently accept the fixes without surfacing the drift. If the caller wants authoritative metadata, they should re-run the workflow.
+**Post-fix provenance drift guard (S15):** If `fixed[]` is non-empty, `skill-check --fix` has modified `SKILL.md` after step 7 wrote it. The safe default for v1.0 is to emit a **WARNING** finding listing each auto-fix (`"skill-check --fix modified SKILL.md: {fix_description} — metadata.json hashes/provenance may be out of date"`). Do NOT silently accept the fixes without surfacing the drift. If the caller wants authoritative metadata, they should re-run the workflow.
 
 **If `body.max_lines` reported**, prefer selective split: extract only the largest Tier 2 section(s) to `references/`, keeping Tier 1 content inline (inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval). Fall back to `npx skill-check split-body <skill-dir> --write` if not feasible. Verify `#quick-start` and `#key-types` anchors still resolve after split. Then re-validate.
 
@@ -120,7 +120,7 @@ Verify context-snippet.md follows Vercel-aligned indexed format:
 - [ ] First line matches: `[{project}-stack v{version}]|root: {prefix}{project}-stack/` where prefix is `skills/` (draft form) or any IDE skill root (`.{dir}/skills/`)
 - [ ] Second line starts with `|IMPORTANT:`
 - [ ] Stack and integrations lines present
-- [ ] Approximate token count is ~80-120 tokens (use the `ceil(char_count / 4)` heuristic from step-07 §5; tolerate up to ~150 if the overflow strategy was applied and a workflow_warning was emitted)
+- [ ] Approximate token count is ~80-120 tokens (use the `ceil(char_count / 4)` heuristic from step 7 §5; tolerate up to ~150 if the overflow strategy was applied and a workflow_warning was emitted)
 
 Record format violations as **WARNING** findings.
 

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

@@ -9,6 +9,16 @@ description: Drop a specific skill version or an entire skill — soft (deprecat
 
 Drops a specific skill version or an entire skill, either as a soft deprecation (manifest-only, files retained) or a hard purge (files deleted). Ensures platform context files are rebuilt to exclude dropped versions. Every destructive action requires explicit user confirmation — nothing is deleted silently. The export manifest is the source of truth; the filesystem is updated to match.
 
+## Conventions
+
+- Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+- **Module-level path exception:** paths starting with `knowledge/` or `shared/` resolve from the SKF module root, not the skill root — install layout puts both at `{project-root}/_bmad/skf/`. The `versionPathsKnowledge: 'knowledge/version-paths.md'` frontmatter scalar in stage files uses this convention; same for `shared/health-check.md` chained from the terminal step.
+- **Cross-skill data coupling:** `references/execute.md` reads `skf-export-skill/assets/managed-section-format.md` for the IDE→context-file mapping table and the four-case (Create / Append / Regenerate / Malformed) logic when rebuilding context files. Drop-skill assumes that asset is present at install time and that its semantics are stable across the two skills' versions.
+
 ## Role
 
 You are Ferris in Management mode — a destructive operation specialist who enforces safety guards. You treat every drop as potentially irreversible and require explicit confirmation before touching the manifest or filesystem. You protect the active version, keep the export manifest consistent with on-disk state, and ensure downstream platform context files are rebuilt.
@@ -19,39 +29,101 @@ These rules apply to every step in this workflow:
 
 - Never delete files without explicit user confirmation in purge mode
 - Never drop an active version when other non-deprecated versions exist — enforce the active version guard
-- Read each step file completely before taking any action
-- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
 - Only load one step file at a time — never preload future steps
 - If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
 - Always communicate in `{communication_language}`
+- At any interactive prompt, the inputs `cancel`, `exit`, `[X]`, `q`, or `:q` exit cleanly with exit code 6 (`halt_reason: "user-cancelled"`)
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
-| 1 | Select Target | steps-c/step-01-select.md | No (confirm) |
-| 2 | Execute Drop | steps-c/step-02-execute.md | Yes |
-| 3 | Report | steps-c/step-03-report.md | Yes |
-| 4 | Workflow Health Check | steps-c/step-04-health-check.md | Yes |
+| 1 | Select Target | references/select.md | No (confirm) |
+| 2 | Execute Drop | references/execute.md | Yes |
+| 3 | Report | references/report.md | Yes |
+| 4 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
 | **Inputs** | skill_name [required], mode (deprecate/purge) [required], version (all/specific) [required] |
-| **Gates** | step-01: Input Gate [use args], Confirm Gate [Y] |
-| **Outputs** | Updated manifest, rebuilt context files, (purge: deleted directories) |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **Flags** | `--headless` / `-H` (auto-resolve all gates); `--dry-run` (run selection + display the §10 confirmation block, then exit with `status="dry-run"` — no manifest mutation, no file deletion). Useful for "show me what this would touch before I commit." |
+| **Gates** | step 1: Input Gate [use args], Confirm Gate [Y] |
+| **Outputs** | Updated manifest, rebuilt context files, (purge: deleted directories), `drop-skill-result-{timestamp}.json` and `drop-skill-result-latest.json` |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. When `forbid_purge_in_headless` is `"true"` in `customize.toml` AND `drop_mode = "purge"`, On-Activation §4 HALTs with exit code 6 (`halt_reason: "headless-purge-forbidden"`) before any work begins. |
+| **Exit codes** | See "Exit Codes" below |
+
+## Exit Codes
+
+Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
+
+| Code | Meaning              | Raised by                                                                                    |
+| ---- | -------------------- | -------------------------------------------------------------------------------------------- |
+| 0    | success              | step 4 (terminal)                                                                           |
+| 2    | input-missing / input-invalid | step 1 §4 (headless missing `skill_name` arg) → `input-missing`; non-existent skill / unparseable version → `input-invalid` |
+| 3    | resolution-failure   | step 1 §2 (manifest is malformed JSON); step 1 §3 (no skills found anywhere)               |
+| 4    | write-failure        | On-Activation §3 pre-flight write probe (skills_output_folder unwritable); step 2 §2 (manifest write); step 2 §3 (context-file rewrite); step 2 §4 (directory delete) |
+| 5    | state-conflict       | step 1 §7 (active-version-guard refuses to drop the active version while non-deprecated peers remain) |
+| 6    | user-cancelled       | step 1 §10 confirmation gate `[N]`; any prompt that accepted `cancel`/`exit`/`:q`; On-Activation §4 (`headless-purge-forbidden`) |
+
+## 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_DROP_SKILL_RESULT_JSON: {"status":"success|error|dry-run","skill":"…|null","drop_mode":"…|null","versions_affected":[],"files_deleted":[],"manifest_updated":false,"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 §11 stores decisions, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"manifest-corrupt"`, `"nothing-to-drop"`, `"active-version-guard-refused"`, `"headless-purge-forbidden"`, `"manifest-write-failed"`, `"context-rebuild-failed"`, `"delete-failed"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above.
 
 ## On Activation
 
 1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
    - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
    - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
-   - `snippet_skill_root_override` (optional string) — when set, the context-file rebuild in step-02 preserves any snippet `root:` prefix that matches the override instead of rewriting it to the target IDE's skill root. See `skf-export-skill/assets/managed-section-format.md` for full semantics.
+   - `snippet_skill_root_override` (optional string) — when set, the context-file rebuild in step 2 preserves any snippet `root:` prefix that matches the override instead of rewriting it to the target IDE's skill root. See `skf-export-skill/assets/managed-section-format.md` for full semantics.
    - Generate and store `timestamp` as `YYYYMMDD-HHmmss` format. This value is fixed for the entire workflow run.
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
+
+3. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-root} --key workflow
+   ```
+
+   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+
+   - `{skill-root}/customize.toml` — bundled defaults
+   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
+   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+
+   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each scalar.
+
+   Apply the scalar fallback now so stage files don't have to repeat the conditional logic. For each of the four scalars, if the merged value is empty or absent, the bundled default applies:
+
+   - `{defaultMode}` ← `workflow.default_mode` (empty = always prompt; `"deprecate"` or `"purge"` = skip §8 Ask Mode)
+   - `{forbidPurgeInHeadless}` ← `workflow.forbid_purge_in_headless` (empty or non-`"true"` = no guard)
+   - `{unknownIdeDefaultContextFile}` ← `workflow.unknown_ide_default_context_file` if non-empty, else `AGENTS.md`
+   - `{unknownIdeDefaultSkillRoot}` ← `workflow.unknown_ide_default_skill_root` if non-empty, else `.agents/skills/`
+
+   Stash all four as workflow-context variables. Stage files reference them directly — no conditional at the usage site.
+
+4. **Pre-flight write probe + headless-purge guard.**
+
+   First, verify `{skills_output_folder}` is writable. A read-only mount, full disk, or permissions-denied path otherwise only surfaces at step 2's manifest write — by then the user has already gone through every selection prompt:
+
+   ```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 `skill: null` and `drop_mode: null` (neither is resolved yet at activation time).
+
+   Second, enforce the headless-purge guard. If `{headless_mode}` is true AND `{forbidPurgeInHeadless}` is `"true"` AND the parsed `mode` arg is `"purge"`: HALT with exit code 6 and `halt_reason: "headless-purge-forbidden"`, emit the error envelope, and exit immediately. The operator must re-run with `mode=deprecate` or set `forbid_purge_in_headless = ""` (or omit the override entirely) to proceed.
 
-3. Load, read the full file, and then execute `./steps-c/step-01-select.md` to begin the workflow.
+5. Load, read the full file, and then execute `references/select.md` to begin the workflow.

package/src/skf-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}`