bmad-module-skill-forge 0.8.3 → 0.9.0

package/src/workflows/drop-skill/steps-c/step-01-select.md

@@ -0,0 +1,298 @@
+---
+name: 'step-01-select'
+description: 'Select skill, version(s), and drop mode (deprecate/purge)'
+nextStepFile: './step-02-execute.md'
+versionPathsKnowledge: '../../../knowledge/version-paths.md'
+---
+
+# Step 1: Select Drop Target
+
+## STEP GOAL:
+
+Identify exactly what the user wants to drop — which skill, which version(s), and whether the drop is a soft deprecation (manifest-only) or a hard purge (files deleted). Enforce the active version guard, gather the list of affected directories, and obtain explicit user confirmation before any write or delete operation is scheduled.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER schedule a destructive operation without explicit user confirmation
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are Ferris in Management mode — a destructive operation specialist
+- ✅ Safety first, confirmation required
+- ✅ You protect the active version and enforce the active version guard
+- ✅ You treat every drop as potentially irreversible — soft drops are recoverable, hard drops are not
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on selection, validation, and confirmation
+- 🚫 FORBIDDEN to proceed without explicit user confirmation at the final gate
+- 🚫 FORBIDDEN to modify the manifest or delete any files in this step — execution happens in step-02
+- 🚫 FORBIDDEN to drop an active version when other non-deprecated versions exist
+- 💬 Present selections clearly so the user can verify scope, mode, and blast radius before committing
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load version-paths knowledge and the export manifest (if present) alongside an on-disk skill scan
+- 💾 Gather all selection decisions into context for step-02
+- 📖 Show version lists, statuses, and directory paths clearly so the user understands what will be affected
+- 🚫 Halt only if neither the manifest nor an on-disk scan yields any skill — a missing manifest is not fatal for purge mode because draft skills (created but never exported) can still be legitimately hard-dropped from disk
+
+## CONTEXT BOUNDARIES:
+
+- Available: Export manifest v2, SKF module config variables, on-disk skill directory listing
+- Focus: Selection, validation, and user confirmation
+- Limits: Do not write to the manifest, do not delete any files — execution is deferred to step-02
+- Dependencies: At least one skill must exist in either the export manifest or on disk under `{skills_output_folder}/`; otherwise the workflow halts. Draft skills (on disk but not in the manifest) are eligible for purge mode only
+
+## 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:
+
+- Path templates: `{skill_package}`, `{skill_group}`, `{forge_version}`, `{forge_group}`
+- Export manifest v2 schema (`schema_version`, `exports`, `active_version`, `versions` map, `status` field values)
+- Skill management operations (Drop section — soft vs hard, active version guard, skill-level drop)
+
+You will use these templates and rules to build directory paths and enforce safety guards in the following sections.
+
+### 2. Read Export Manifest
+
+Load `{skills_output_folder}/.export-manifest.json` if it exists.
+
+**If the file is missing, empty, or contains no `exports` entries:** Treat as an empty manifest — proceed to section 3 and rely on the on-disk directory scan. Draft skills (created by `[CS]`/`[QS]`/`[SS]` but never exported) can still be hard-dropped in purge mode. Store `manifest_exists = false` so section 8 (Ask Mode) can restrict the options to purge only. Soft-deprecate is meaningless without a manifest to record the deprecation against.
+
+**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."
+
+### 3. List Available Skills
+
+Build and display a summary of every skill available to drop. Start with the manifest (if any), then augment with an on-disk scan.
+
+For each skill in the manifest's `exports` (only if `manifest_exists = true` and entries exist):
+
+1. Read `active_version` from the manifest entry
+2. List every entry in the skill's `versions` map with its `status` field
+3. Mark the active version with a trailing `*`
+4. Sort versions in descending order (newest first) where possible
+
+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."
+
+Display the combined list:
+
+```
+**Drop Skill — select target**
+
+Available skills:
+1. cognee
+   - 0.1.0 (deprecated)
+   - 0.5.0 (archived)
+   - 0.6.0 (active) *
+2. express
+   - 4.18.0 (active) *
+3. legacy-helper (not in manifest — purge only)
+```
+
+### 4. Ask Which Skill
+
+"**Which skill would you like to drop?**
+Enter the skill name or its number from the list above."
+
+Wait for user input. Accept either the numeric index or the skill name (exact match).
+
+**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.
+
+### 5. Display Version Details
+
+**If `target_in_manifest = true`**, display every version with its full metadata from the manifest:
+
+```
+**{target_skill} — versions:**
+
+| Version | Status     | Last Exported | Platforms              |
+|---------|------------|---------------|------------------------|
+| 0.1.0   | deprecated | 2026-01-15    | claude                 |
+| 0.5.0   | archived   | 2026-03-15    | claude                 |
+| 0.6.0   | active *   | 2026-04-04    | claude, copilot        |
+```
+
+**If `target_in_manifest = false`** (draft skill discovered only by on-disk scan), display the on-disk version directories instead and note the constraint:
+
+```
+**{target_skill} — on-disk versions (not in manifest):**
+
+  {list version subdirectories found under {skills_output_folder}/{target_skill}/, or "(flat layout)" if no version nesting is present}
+
+**Note:** This skill has no manifest entry, so soft-deprecate is not available. Only a skill-level hard purge can be performed — the drop will delete the entire on-disk skill group and forge group.
+```
+
+### 6. Ask Scope
+
+**If `target_in_manifest = false`:** Skip this prompt — draft skills can only be dropped as a whole. Set `target_versions = "all"` and `is_skill_level = true`, then proceed to section 7.
+
+**If `target_in_manifest = true`:**
+
+"**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)"
+
+Wait for user selection.
+
+**If [N] Specific version:**
+
+"**Which version?** Enter the version string (e.g. `0.5.0`)."
+
+Wait for user input. Validate that the version exists in the manifest's `versions` map for `target_skill`. If not, repeat the prompt.
+
+Set `target_versions = [<selected version>]` and `is_skill_level = false`.
+
+**If [A] All versions:**
+
+Set `target_versions = "all"` and `is_skill_level = true`.
+
+### 7. Active Version Guard
+
+**Does not apply when `target_in_manifest = false`:** A draft skill has no manifest-recorded active version, so the guard is a no-op. Proceed to section 8.
+
+**Applies only when `target_in_manifest = true` AND `is_skill_level = false` (specific version selected):**
+
+1. Read the selected version's `status` field from the manifest
+2. If `status != "active"` → skip this guard, the version is safe to drop
+3. If `status == "active"`:
+   a. Count the number of OTHER versions in the `versions` map with `status != "deprecated"` (i.e., `active`, `archived`, or `draft`)
+   b. If that count is `> 0` → REFUSE the drop:
+
+      "**Cannot drop the active version `{version}`.**
+      Other non-deprecated versions of `{target_skill}` still exist. To proceed, either:
+
+      **(a)** Switch the active version to another version first by re-running `[EX] Export Skill` with a different version selected, then return here to drop `{version}`, OR
+
+      **(b)** Use the `[A] All versions` option to drop every version of `{target_skill}` at once."
+
+      HALT the workflow. 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)
+
+### 8. Ask Mode
+
+**If `target_in_manifest = false`:** Skip this prompt — soft-deprecate is meaningless without a manifest entry to mark. Force `drop_mode = "purge"` and inform the user: "**Mode forced to purge** — `{target_skill}` has no manifest entry, so there is nothing to deprecate. The skill's on-disk directories will be deleted."
+
+**If `target_in_manifest = true`:**
+
+"**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.**"
+
+Wait for user selection.
+
+Set `drop_mode` to `"deprecate"` (on D) or `"purge"` (on P).
+
+### 9. Compute Affected Directories
+
+Using the templates from `{versionPathsKnowledge}`, resolve the list of directories that would be affected:
+
+**If `is_skill_level = false` (version-level drop):**
+
+- `{skill_package}` = `{skills_output_folder}/{target_skill}/{version}/{target_skill}/`
+- The enclosing version directory = `{skills_output_folder}/{target_skill}/{version}/`
+- `{forge_version}` = `{forge_data_folder}/{target_skill}/{version}/`
+
+**If `is_skill_level = true` (skill-level drop):**
+
+- `{skill_group}` = `{skills_output_folder}/{target_skill}/`
+- `{forge_group}` = `{forge_data_folder}/{target_skill}/`
+
+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.
+
+### 10. Confirmation Gate
+
+Display the full operation summary:
+
+```
+**About to drop:**
+
+  Skill:   {target_skill}
+  Version: {version or "ALL versions"}
+  Mode:    {Deprecate (soft) | Purge (hard)}
+  Files:
+    {for each path in affected_directories, list one per line}
+    {or "(retained on disk — soft drop)" if drop_mode == "deprecate"}
+
+{if drop_mode == "purge":}
+  ⚠️  This operation cannot be undone. Files will be permanently deleted.
+{else:}
+  Files remain on disk. Reversible by manually editing the manifest.
+
+Proceed? [Y/N]
+```
+
+Wait for explicit user response.
+
+- **If `Y`** → proceed to section 11
+- **If `N`** → "**Cancelled.** No changes were made." HALT the workflow
+- **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:
+
+- `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)
+
+### 12. Load Next Step
+
+Load, read the full file, and then execute `{nextStepFile}`.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the user has confirmed with `Y` at the confirmation gate AND all selection decisions have been stored in context, will you then load and read fully `{nextStepFile}` to execute the drop.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Version-paths knowledge loaded and applied via templates (no hardcoded paths)
+- Export manifest read if present; on-disk scan augments the list; halt only if both are empty
+- Complete skill and version list displayed with statuses, active marker, and on-disk-only entries flagged "(not in manifest — purge only)"
+- Skill, version(s), and mode selected by explicit user input; mode forced to purge for not-in-manifest skills
+- Active version guard enforced for manifest-tracked skills — refused to drop an active version with surviving non-deprecated peers
+- Affected directories computed from templates
+- Explicit user confirmation (`Y`) received at the confirmation gate
+- All selection decisions stored in context for step-02 (including `target_in_manifest`)
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding without reading version-paths knowledge
+- Halting when the manifest is missing but on-disk skills exist — the fallback scan MUST be attempted before any "nothing to drop" halt
+- Offering soft-deprecate for a skill that has no manifest entry
+- Hardcoding directory paths instead of using `{skill_package}`, `{skill_group}`, `{forge_version}`, `{forge_group}` templates
+- Allowing a drop of the active version when other non-deprecated versions exist
+- Modifying the manifest or deleting files in this step (execution belongs to step-02)
+- Skipping the confirmation gate or proceeding on any response other than `Y`
+- Not storing decisions in context for step-02
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. No destructive action proceeds without explicit user confirmation.

package/src/workflows/drop-skill/steps-c/step-02-execute.md

@@ -0,0 +1,290 @@
+---
+name: 'step-02-execute'
+description: 'Execute the drop operation — update manifest, rebuild context files, delete files if purge'
+nextStepFile: './step-03-report.md'
+versionPathsKnowledge: '../../../knowledge/version-paths.md'
+managedSectionLogic: '../../export-skill/data/managed-section-format.md'
+---
+
+# 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.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER modify content outside `<!-- SKF:BEGIN/END -->` markers in platform context files
+- 🛑 NEVER delete files outside the `affected_directories` list from step-01
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step, ensure entire file is read
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are Ferris in Management mode — a destructive operation specialist
+- ✅ Execute only the decisions confirmed in step-01 — no scope expansion, no "while I'm at it" extras
+- ✅ Surgical precision: preserve all content outside `<!-- SKF:BEGIN/END -->` markers
+- ✅ Manifest and filesystem must end in a consistent state
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on manifest update, context rebuild, and (in purge mode) file deletion
+- 🚫 FORBIDDEN to re-prompt the user — decisions were made in step-01
+- 🚫 FORBIDDEN to delete files in deprecate mode
+- 🚫 FORBIDDEN to widen the deletion scope beyond `affected_directories`
+- 💬 Report each stage's outcome as it completes so the user sees progress
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Re-read version-paths knowledge to avoid drift between step files
+- 💾 Persist the manifest update before touching platform context files
+- 📖 Rebuild managed sections from the updated manifest, not from memory
+- 🚫 If any stage fails, halt and report which stage failed with recovery guidance
+
+## CONTEXT BOUNDARIES:
+
+- Available: Decisions from step-01 (`target_skill`, `target_versions`, `drop_mode`, `is_skill_level`, `affected_directories`), SKF module config, version-paths knowledge, managed-section format
+- Focus: Manifest mutation, context rebuild, filesystem deletion (purge only)
+- Limits: Only modify content between `<!-- SKF:BEGIN/END -->` markers; only delete directories enumerated in `affected_directories`
+- Dependencies: Step-01 must have completed and stored all decisions in context
+
+## 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.
+
+Also read `{managedSectionLogic}` for the format template, the four-case logic, and the skill index rebuild rules that will be reused in section 3.
+
+### 2. Update Export Manifest
+
+**If `target_in_manifest == false`** (draft skill discovered only by on-disk scan): Skip this section entirely. There is no manifest entry to deprecate or delete. Set `manifest_updated = false` and proceed directly to section 3. Step-01 forced `drop_mode = "purge"` and `is_skill_level = true` in this case, so the subsequent sections will hard-delete the on-disk directories without any manifest interaction.
+
+**If `target_in_manifest == true`:**
+
+Load `{skills_output_folder}/.export-manifest.json`.
+
+**If `is_skill_level == false` (version-level drop):**
+
+For each version in `target_versions`:
+
+1. Navigate to `exports.{target_skill}.versions.{version}`
+2. Set `status = "deprecated"`
+3. Leave `platforms`, `last_exported`, and all other fields unchanged
+
+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.
+
+**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
+
+**Write the updated manifest back to `{skills_output_folder}/.export-manifest.json`.**
+
+Set context flag `manifest_updated = true`.
+
+**On error (read/parse/write failure):**
+
+- 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
+
+### 3. Rebuild Platform Context Files
+
+Load the `ides` list from `config.yaml`. The installer writes installer-specific IDE identifiers (e.g. `claude-code`, `github-copilot`, `codex`, `cline`, `roo`, `windsurf`, `cursor`, `other`), NOT platform values — these must be mapped to platforms before any target-file lookup.
+
+**Resolve `target_platforms`** using the "IDE → Platform Mapping" table in `{managedSectionLogic}`:
+
+1. For each entry in `config.yaml.ides`, look up its platform value (`claude-code` → `claude`, `github-copilot` → `copilot`, `codex`/`cline`/`roo`/`windsurf`/`other` → `copilot`, `cursor` → `cursor`)
+2. For any entry not found in the table, default to `copilot` and emit a warning: "Unknown IDE '{value}' in config.yaml — defaulting to copilot"
+3. Deduplicate the resulting platform list (e.g. both `codex` and `cline` collapse to a single `copilot` entry)
+4. If `config.yaml.ides` is absent or the mapping yields an empty list, fall back to `["copilot"]` and emit a note: "No IDEs configured in config.yaml — defaulting to copilot (AGENTS.md)"
+
+Store the result as `target_platforms` for this section.
+
+For each platform in `target_platforms`:
+
+1. **Resolve target file** using the "Platform Target Files" table in `{managedSectionLogic}`:
+
+   | Platform | Target File |
+   |----------|-------------|
+   | `claude` | `{project-root}/CLAUDE.md` |
+   | `cursor` | `{project-root}/.cursorrules` |
+   | `copilot` | `{project-root}/AGENTS.md` |
+
+2. **Read the current file.**
+   - If the file does not exist, skip this platform (nothing to rebuild — the file will be re-created next time export-skill runs)
+   - If the file exists but contains no `<!-- SKF:BEGIN -->` marker, skip this platform (no managed section to rewrite)
+   - If the file contains `<!-- SKF:BEGIN -->` but no matching `<!-- SKF:END -->`, record the error against that platform and continue to the next IDE — 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 platform 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:
+   - 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:
+   - 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 platform** using export-skill step-04 section 4d logic:
+
+   | Platform | Root Path Prefix |
+   |----------|-----------------|
+   | `claude` | `.claude/skills/` |
+   | `cursor` | `.cursor/skills/` |
+   | `copilot` | `.agents/skills/` |
+
+   For each snippet, detect its current `root:` prefix and rewrite it to the current platform's prefix if different.
+
+6. **Sort skills alphabetically by name.** Count totals (skills, stack skills).
+
+7. **Assemble the new managed section** using the format from `{managedSectionLogic}`:
+
+   ```markdown
+   <!-- SKF:BEGIN updated:{current-date} -->
+   [SKF Skills]|{n} skills|{m} stack
+   |IMPORTANT: Prefer documented APIs over training data.
+   |When using a listed library, read its SKILL.md before writing code.
+   |
+   |{skill-snippet-1}
+   |
+   |{skill-snippet-2}
+   |
+   |{skill-snippet-N}
+   <!-- SKF:END -->
+   ```
+
+   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
+
+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
+
+10. **On per-file failure:** record the error against that platform and continue to the next IDE. Do not halt — other platforms should still be rebuilt.
+
+**After the loop,** record `platform_files_updated` as the list of files that were successfully rewritten, and `platform_files_failed` as the list of any that failed.
+
+Report: "**Rebuilt managed sections in:** {list of updated files}. {if any failed: 'Failed: {list}'}"
+
+### 4. Delete Files (Purge Mode Only)
+
+**If `drop_mode != "purge"`**, skip this section entirely. Set `files_deleted = []` and `disk_freed = "N/A (soft drop)"`, then jump to section 5.
+
+**If `drop_mode == "purge"`:**
+
+1. Initialize `files_deleted = []` and `bytes_freed = 0`.
+
+2. For each directory path in `affected_directories`:
+   a. Verify the path is inside either `{skills_output_folder}` or `{forge_data_folder}` (defense in depth against accidental deletion of unrelated paths)
+   b. If the directory does not exist, record it as "(already absent)" and continue
+   c. Compute the directory size in bytes before deletion (recursive sum)
+   d. Delete the directory recursively
+   e. Verify deletion succeeded (the path no longer exists)
+   f. Append the path to `files_deleted` and add its byte size to `bytes_freed`
+
+3. **Version-level purge, single version:**
+   - `{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)
+
+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
+
+5. Convert `bytes_freed` to a human-readable string for the final report (e.g. `"4.2 MB"`). Store as `disk_freed`.
+
+**On deletion error:**
+
+- Record which path failed and the error message
+- Continue attempting the remaining paths — partial purge is still better than no purge
+- Report all failures at the end of this section
+
+### 5. Verify Final State
+
+Run these verification checks:
+
+1. **Manifest check:** Re-read `{skills_output_folder}/.export-manifest.json` and confirm:
+   - Version-level drop: `exports.{target_skill}.versions.{version}.status == "deprecated"`
+   - Skill-level drop: `exports.{target_skill}` is absent
+
+2. **Platform files check:** For each file in `platform_files_updated`, spot-check that the dropped skill/version is no longer referenced between the markers.
+
+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.
+
+### 6. Store Results in Context
+
+Store the following for step-03:
+
+- `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)"`
+- `manifest_updated` — boolean (true if section 2 succeeded)
+- `platform_files_updated` — list of successfully rebuilt files
+- `platform_files_failed` — list of files that failed to rebuild (empty if none)
+- `verification_errors` — list of verification failures (empty if none)
+
+### 7. Load Next Step
+
+Load, read the full file, and then execute `{nextStepFile}`.
+
+## Error Handling Summary
+
+If any stage fails, record which stage failed and provide recovery guidance in the final report:
+
+| Failed Stage | Recovery Guidance |
+|--------------|-------------------|
+| Manifest update | "Manifest is in pre-drop state. Re-run the workflow once the underlying I/O issue is resolved. No files were deleted." |
+| Platform rebuild | "Manifest is already updated. Re-run `[EX] Export Skill` against any still-valid skill to regenerate the affected managed sections, or rerun the drop workflow." |
+| File deletion (purge) | "Manifest and platform files are consistent. Remaining directories listed in the report can be deleted manually: `rm -rf {path}`." |
+| Verification | "Execution completed but post-write checks found drift. See the report for specific paths requiring manual review." |
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN all execution stages have been attempted (manifest update, context rebuild, file deletion in purge mode, verification) and results have been stored in context, will you then load and read fully `{nextStepFile}` to generate the final report.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Version-paths knowledge and managed-section format re-read at the start of the step
+- Export manifest updated correctly (deprecated status for version-level, skill removal for skill-level)
+- Platform context files rebuilt for all configured IDEs using the same logic as export-skill step-04 (sections 4b–5), with surgical replacement preserving all content outside markers
+- Deprecated versions no longer appear in any managed section
+- Purge mode: all directories in `affected_directories` deleted with size accounting; `active` symlink updated or removed as appropriate
+- Soft drop: no files deleted; `files_deleted` is empty and `disk_freed` is `"N/A (soft drop)"`
+- Verification checks executed on manifest, platform files, and (if purge) deleted paths
+- All results stored in context for step-03
+- Errors at any stage are recorded with recovery guidance rather than silently swallowed
+
+### ❌ SYSTEM FAILURE:
+
+- Deleting files in soft drop mode
+- Deleting directories outside the `affected_directories` list
+- Modifying content outside `<!-- SKF:BEGIN/END -->` markers
+- Rebuilding managed sections from memory instead of the updated manifest
+- Including deprecated versions in the rebuilt skill index
+- Not updating the `active` symlink after a version-level purge when the dropped version was the target
+- Not verifying the final state
+- Hardcoding paths instead of using `{skill_package}`, `{skill_group}`, `{forge_version}`, `{forge_group}` templates
+- Halting the entire workflow on a recoverable per-platform error instead of continuing and reporting
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. The manifest and the filesystem must end in a consistent state, and every destructive action must trace back to a decision made in step-01.