bmad-module-skill-forge 2.2.0 → 4.0.0

package/src/skf-drop-skill/references/select.md

@@ -1,27 +1,17 @@
 ---
 nextStepFile: 'execute.md'
-versionPathsKnowledge: 'knowledge/version-paths.md'
-# Read-side inventory helpers (reads, not atomicity-critical). §2 uses
-# `{manifestOpsHelper} read` (manifest parse + v1→v2 migration + corrupt-JSON
-# detection); §3 uses `{skillInventoryHelper}` (on-disk scan + exports∪on-disk
-# diff for orphan detection) and `{manifestOpsHelper} affected-versions <skill>`
-# (numeric semver-descending order, so 0.10.0 precedes 0.9.0 — LLM-unreliable).
-# Probe each in order (installed SKF path first, src/ fallback); first hit wins.
-# If neither candidate resolves, the section computes the result in-prompt.
-manifestOpsProbeOrder:
-  - '{project-root}/_bmad/skf/shared/scripts/skf-manifest-ops.py'
-  - '{project-root}/src/shared/scripts/skf-manifest-ops.py'
+# {dropRosterHelper}: the §2 roster.
+dropRosterHelper: 'scripts/drop-roster.py'
+# {skillInventoryHelper}: the §8b purge check.
 skillInventoryProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-skill-inventory.py'
   - '{project-root}/src/shared/scripts/skf-skill-inventory.py'
-# Standalone single-line result-envelope contract emitted at every headless
-# HALT in this step. Loaded in §1 so no error path depends on SKILL.md
-# remaining in context under compaction.
-headlessContract: 'headless-contract.md'
-# Deterministic recursive byte sizing + human formatting for the §9b
-# blast-radius line. Bundled with this skill (no probe order needed);
-# execute.md §4 reuses the same helper for the canonical `disk_freed`.
+# {dirSizesHelper}: the §9b size of the folders in scope.
 dirSizesHelper: 'scripts/dir-sizes.py'
+# {atomicWriteHelper}: the §7 recovery that points `active` at the version to keep.
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -34,66 +24,47 @@ Identify exactly what the user wants to drop — which skill, which version(s),
 
 ## Rules
 
-- Focus only on selection, validation, and confirmation — do not modify the manifest or delete files
+- Focus only on selection, validation, and confirmation: do not change the manifest, a context file or a skill folder (this step writes only its envelope payloads, in `{run_dir}`)
 - Do not proceed without explicit user confirmation at the final gate
 - Do not drop an active version when other non-deprecated versions exist
 - Present selections clearly so the user can verify scope, mode, and blast radius
-- **Interactive cancel (every gate below):** at any prompt, `cancel` / `exit` / `[X]` / `q` / `:q` → display "Cancelled — no changes were made." and HALT (exit code 6, `halt_reason: "user-cancelled"`). Stated once here; the §10 commit gate adds its own tip + headless envelope on top of this.
+- **Interactive cancel (every gate below):** at any prompt, `cancel` / `exit` / `[X]` / `q` / `:q` → display "Cancelled: no changes were made." and HALT (exit code 6, `halt_reason: "user-cancelled"`). Stated once here; the §10 commit gate adds its own tip on top of this.
 
 ## MANDATORY SEQUENCE
 
-### 1. Load Knowledge
+### 1. Halt Envelope
 
-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.
-
-If `{headless_mode}` is true, also read `{headlessContract}` now — it defines the single-line result envelope every HALT below emits, so the shape is in context even if SKILL.md was compacted out.
-
-### 2. Read Export Manifest
-
-**Resolve `{manifestOpsHelper}`** ← first existing path in `{manifestOpsProbeOrder}`. Parse the manifest through it rather than hand-rolling JSON — the helper migrates v1→v2, normalizes `platforms`→`ides`, and reports a parse error deterministically:
+Every HALT in this step names its exit code, `halt_reason` and phase. In headless mode it also prints its envelope through the shared emitter before it stops (`{emitEnvelopeHelper}` and `{run_dir}` come from SKILL.md On-Activation §4): stage `{run_dir}/halt.json` as `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>", "exit_code": <code>}` plus the envelope fields the site names (and `"path"` when the halt names one), then run
 
 ```bash
-python3 {manifestOpsHelper} {skills_output_folder} read
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-drop-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
 ```
 
-Read the JSON result:
-
-- **`status == "error"`** — the manifest file exists but is malformed (the helper returns `{"status":"error","error":"Manifest JSON parse error: ..."}`): 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 `{headlessContract}` with `skill: null`, `drop_mode: null`, `versions_affected: []`.
-- **`status == "ok"`** — use `result.manifest` (already migrated to v2) as `manifest` for the rest of this step. Set `manifest_exists = true` when `manifest.exports` has at least one entry, else `false` (a missing manifest reads back as an empty `exports` object, so it correctly yields `false`).
+and display the line it prints verbatim. Write the payload as valid JSON: in the halt message and `path`, replace each backslash with / and each double quote with a backtick. The emitter gives every field the site leaves out its default (`null`, `[]` or `false`) and checks `exit_code` against `halt_reason`. If it exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message, emits nothing and then deletes the run folder (`rm -rf "{run_dir}"`), which nothing reads after it.
 
-When `manifest_exists = false`, section 3's on-disk scan is authoritative: draft skills (created by `[CS]`/`[QS]`/`[SS]` but never exported) can still be hard-dropped in purge mode, and section 8 restricts the options to purge only — soft-deprecate is meaningless without a manifest entry to record it against.
+### 2. Read the Roster
 
-**If neither `{manifestOpsProbeOrder}` candidate resolves:** read the manifest file in-prompt — a missing/empty file is `manifest_exists = false`; a file with `exports` entries is `true` (no `schema_version` field means v1 — treat each entry as a single active version); invalid JSON takes the corrupt-manifest HALT above.
-
-### 3. List Available Skills
-
-Build and display a summary of every skill available to drop: every manifest-tracked skill, plus every on-disk skill not in the manifest (draft/orphaned, eligible for purge only).
-
-**Manifest-tracked skills** come from the `manifest` resolved in section 2 — for each key in `manifest.exports`, its `active_version` and its `versions` map (with each version's `status`) are already parsed. Order each skill's versions newest-first through the helper rather than by eye:
+Read every skill this drop can offer in one call:
 
 ```bash
-python3 {manifestOpsHelper} {skills_output_folder} affected-versions {skill-name}
+uv run {dropRosterHelper} skills "{skills_output_folder}" --forge-data-folder "{forge_data_folder}" [--skill "{skill_name}"]
 ```
 
-`result.affected_versions` is that skill's versions deduped and sorted in the helper's numeric-descending order (see the frontmatter note). Annotate each with its `status` from `manifest.exports.{skill-name}.versions.{version}.status` and mark `active_version` with a trailing `*`.
+Pass `--skill` when a `skill_name` argument was supplied: the roster then holds that skill only. Bind `{roster}` ← the result.
 
-**On-disk (not-in-manifest) skills** come from the inventory helper. **Resolve `{skillInventoryHelper}`** ← first existing path in `{skillInventoryProbeOrder}`; it scans `{skills_output_folder}/` and computes the exports∪on-disk merge for you — do not re-scan the directory in the prompt:
+- **`code` is `manifest-corrupt`** (the file exists but does not parse): 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"`, phase `select:manifest-read`, path `{skills_output_folder}/.export-manifest.json`) with the §1 halt envelope.
+- **Any other non-zero exit, or no JSON on stdout:** HALT (exit code 4, `halt_reason: "write-failed"`, phase `select:roster`) with the §1 halt envelope: "SKF cannot list the skills to drop: {the result's `error`, or the first stderr line}. Nothing was changed. Re-install SKF."
 
-```bash
-python3 {skillInventoryHelper} {skills_output_folder}
-```
+### 3. List Available Skills
+
+`{roster}.skills` holds every skill in the export manifest and every skill SKF generated that the manifest does not list (`purge_only` true: a draft, which only a purge can drop), each with its `versions` newest first. Bind `{not_offered}` ← the names in `{roster}.not_offered`: folders holding a skill SKF did not generate, which the roster never offers. When `{roster}.inventory` is false (the inventory helper could not run), the roster holds the manifest skills alone, because SKF cannot check that it generated a folder the manifest does not list, and `{not_offered}` is empty.
 
-Any `result.skills[].name` that is **not** a key in `manifest.exports` is a draft or orphaned skill — record it as "(not in manifest — purge only)". When the manifest is empty, every on-disk skill lands here. The inventory lists only skills with an on-disk directory, so a manifest entry whose files were already removed still appears above via `manifest.exports`.
+**If the combined roster is empty** (`{roster}.empty` is true):
 
-**If the combined roster is empty** (no `manifest.exports` entries AND `result.skills[]` is empty): 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 per `{headlessContract}` with `skill: null`, `drop_mode: null`, `versions_affected: []`.
+- When a skill name was supplied as an argument and it is in `{not_offered}`, take the §4 refusal for that folder first, in either mode: display its message and HALT (exit code 5, `halt_reason: "not-skf-output"`, phase `select:roster`), with `skill: "{name}"` in the §1 halt envelope.
+- Otherwise 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." When `{not_offered}` is non-empty, append: "Left untouched (not SKF output): {not_offered}." HALT (exit code 3, `halt_reason: "nothing-to-drop"`, phase `select:roster`) with the §1 halt envelope.
 
-Display the combined list (versions newest-first):
+When a `skill_name` argument was supplied, show no list: §4 takes the name. Otherwise display the combined list, each skill's versions in the roster's order, each with its `status` ("on disk only" when its `in_manifest` is false) and a trailing `*` on the one whose `active` is true; a `purge_only` skill shows "(not in manifest: purge only)" in place of its versions. When `{not_offered}` is non-empty, show one line under the list: "Not offered (not SKF output): {not_offered}".
 
 ```
 **Drop Skill — select target**
@@ -105,27 +76,34 @@ Available skills:
    - 0.1.0 (deprecated)
 2. express
    - 4.18.0 (active) *
-3. legacy-helper (not in manifest — purge only)
-```
+3. legacy-helper (not in manifest: purge only)
 
-**If neither helper resolves** (Python/helper unavailable): fall back to the in-prompt computation — list each `manifest.exports` skill (versions with `status`, active marked `*`, ordered newest-first by comparing version components numerically), then scan `{skills_output_folder}/` for top-level directories absent from `manifest.exports` and record them as "(not in manifest — purge only)". If the combined list is empty, take the "nothing to drop" HALT above.
+Not offered (not SKF output): my-module-skill
+```
 
 ### 4. Ask Which Skill
 
+**GATE [default: use args]:** when a `skill_name` argument was supplied, take it as the answer below in either mode, without showing the prompt; the two checks that follow still apply, and an interactive run whose supplied name fails one runs §2's call again without `--skill` and shows §3's list before it asks. When none was supplied, headless mode HALTs (exit code 2, `halt_reason: "input-missing"`, phase `select:skill`) with the §1 halt envelope: "headless mode requires skill name argument." Interactive mode asks:
+
 "**Which skill would you like to drop?**
 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 (exit code 2, `halt_reason: "input-missing"`): "headless mode requires skill name argument." In headless mode, emit the error envelope per `{headlessContract}` with `skill: null`, `drop_mode: null`.
+Wait for user input. Accept either the numeric index or the skill name (exact match).
 
+- **If the input names a folder in `{not_offered}`:** display "**`{name}` is not SKF output: nothing was changed.** `{skills_output_folder}/{name}/` has no SKF marker in its `metadata.json`, so SKF will not delete it. A shared `{skills_output_folder}` is supported: SKF leaves the skills it did not generate alone, so manage `{name}` yourself (to remove it, delete that folder). Only if `{skills_output_folder}` holds a module's own source rather than skills, set `skills_output_folder` in `{project-root}/_bmad/skf/config.yaml` to a folder of its own, move your SKF skills there and re-run `/skf-setup`." When that folder's `{roster}.not_offered` entry has a non-empty `errors` list (for example, the folder is a link), show those errors in place of the marker sentence.
+  - **Interactive:** Re-display the list and ask again.
+  - **Headless (`{headless_mode}` is true):** HALT (exit code 5, `halt_reason: "not-skf-output"`, phase `select:skill`), with `skill: "{name}"` in the §1 halt envelope.
 - **If the user's input does not match any listed skill:**
   - **Interactive:** Re-display the list and ask again.
-  - **Headless (`{headless_mode}` is true):** the supplied `skill_name` argument resolves to no skill in the combined list — there is no further input to re-prompt for. HALT (exit code 2, `halt_reason: "input-invalid"`): "headless mode: skill argument `{supplied value}` does not match any listed skill." Emit the error envelope per `{headlessContract}` with `skill: null`, `drop_mode: null`, `versions_affected: []`.
+  - **Headless (`{headless_mode}` is true):** the supplied `skill_name` argument resolves to no skill in the combined list, and there is no further input to re-prompt for. HALT (exit code 2, `halt_reason: "input-invalid"`, phase `select:skill`) with the §1 halt envelope: "headless mode: skill argument `{supplied value}` does not match any listed skill."
 
-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.
+Store the selection as `target_skill`, and `target_in_manifest` ← its `{roster}.skills` entry's `in_manifest`: the sections below restrict the drop options of a skill the manifest does not list.
 
 ### 5. Display Version Details
 
-**If `target_in_manifest = true`**, display every version with its full metadata from the manifest:
+Bind `{version_rows}` ← the `versions` of `{target_skill}`'s roster entry (the manifest's and the on-disk versions, newest first, each with its manifest `status`, `in_manifest`, `on_disk`, `last_exported` and `ides`) and `{version_counts}` ← its `counts` (`non_deprecated` counts the manifest versions whose `status` is not `"deprecated"`, and `on_disk` the version folders); §6 to §9b read them.
+
+**If `target_in_manifest = true`**, display every `{version_rows}` entry with `in_manifest` true:
 
 ```
 **{target_skill} — versions:**
@@ -142,16 +120,18 @@ Store the selection as `target_skill`. Also store `target_in_manifest = true` if
 ```
 **{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}
+  {each `{version_rows}` entry whose `on_disk` is true, newest first, or "(flat layout)" when the roster entry's `layout` is "flat"}
 
-**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.
+**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 (a forge folder SKF did not generate stays where it is).
 ```
 
 ### 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.
+**GATE [default: use args]:** the `version` argument answers this section in either mode, so a supplied value is never asked for again.
 
-**If `target_in_manifest = true`:**
+**If `target_in_manifest = false`:** a draft skill can only be dropped as a whole. A `version` argument other than `all` asks for less, and the drop never widens it to every version: HALT (exit code 2, `halt_reason: "input-invalid"`, phase `select:scope`) in either mode, with `skill: "{target_skill}"` in the §1 halt envelope: "`{target_skill}` has no manifest entry, so only the whole skill can be dropped. Re-run with `version=all`." Otherwise (no `version` argument, or `all`), skip the prompt: set `target_versions = "all"` and `is_skill_level = true`, then proceed to section 7.
+
+**If `target_in_manifest = true`:** a `version` argument of `all` takes **[A]** below, and any other value takes **[N]** with that value as the answer to "Which version?", without showing either prompt. With no `version` argument, headless mode HALTs (exit code 2, `halt_reason: "input-missing"`, phase `select:scope`), with `skill: "{target_skill}"` in the §1 halt envelope, rather than guess between one version and the whole skill: "headless mode requires a `version` argument for `{target_skill}`: `all`, or one of its versions ({each `{version_rows}` entry with `in_manifest` true})." Interactive mode asks:
 
 "**Drop which version(s)?**
 
@@ -165,10 +145,10 @@ Wait for user selection.
 
 "**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`.
+Wait for user input (a supplied `version` argument is the input). Validate that the version is a `{version_rows}` entry with `in_manifest` true.
 
 - **If it does not match (interactive):** repeat the prompt.
-- **If it does not match (headless — `{headless_mode}` is true):** the supplied `version` argument is unparseable or absent from the `versions` map — there is no further input to re-prompt for. HALT (exit code 2, `halt_reason: "input-invalid"`): "headless mode: version argument `{supplied value}` does not exist in `{target_skill}`'s versions." Emit the error envelope per `{headlessContract}` with `skill: "{target_skill}"`, `drop_mode: null`, `versions_affected: []`.
+- **If it does not match (headless, `{headless_mode}` is true):** the supplied `version` argument is not a `{version_rows}` entry with `in_manifest` true, and there is no further input to re-prompt for. HALT (exit code 2, `halt_reason: "input-invalid"`, phase `select:scope`), with `skill: "{target_skill}"` in the §1 halt envelope: "headless mode: version argument `{supplied value}` does not exist in `{target_skill}`'s versions."
 
 Set `target_versions = [<selected version>]` and `is_skill_level = false`.
 
@@ -182,87 +162,107 @@ Set `target_versions = "all"` and `is_skill_level = true`.
 
 **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
+1. Read the selected version's `status` from its `{version_rows}` entry
 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:
+   a. Read `{version_counts}.non_deprecated` (§5): the manifest versions of `{target_skill}` whose `status` is not `"deprecated"` (`active`, `archived` or `draft`), this one included. The guard never counts by hand.
+   b. If that count is above `1` → 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
+      **(a)** Make the version you keep active first: point the `active` link at it (`uv run {atomicWriteHelper} flip-link --link "{skills_output_folder}/{target_skill}/active" --target <version to keep>`), run `[EX] Export Skill` for `{target_skill}`, which exports that version and archives `{version}`, then return here to drop `{version}`, OR
 
       **(b)** Use the `[A] All versions` option to drop every version of `{target_skill}` at once."
 
-      HALT (exit code 5, `halt_reason: "active-version-guard-refused"`). In headless mode, emit the error envelope per `{headlessContract}` with `skill: "{target_skill}"`, `drop_mode: null`, `versions_affected: ["{version}"]`. Do not proceed.
+      In (a), `<version to keep>` is the first `{version_rows}` entry other than `{version}` whose `in_manifest` and `on_disk` are true and whose `status` is not `"deprecated"` (the rows are newest first); with no such entry, show `<version to keep>` as written. `{atomicWriteHelper}` is the first existing path in `{atomicWriteProbeOrder}`, or its first entry when neither exists.
 
-   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)
+      HALT (exit code 5, `halt_reason: "active-version-guard-refused"`, phase `select:active-version-guard`), with `skill: "{target_skill}"` and `versions_affected: ["{version}"]` in the §1 halt envelope. Do not proceed.
+
+   c. Otherwise (a count of `1`, or no other version in the manifest) → the active version is the ONLY non-deprecated 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"` (record `mode_source = "draft-skill-forced-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."
+**GATE [default: use args]:** a `mode` argument answers this section in either mode, and an interactive run with none asks; the cases below say when the run HALTs instead. When `{headless_mode}` is true, record the `drop_mode` this section sets as an auto-decision before §8b runs: stage `{run_dir}/decision.json` as `{"gate": "select.mode", "default_action": "use args", "taken_action": "<drop_mode>", "reason": "<mode_source>"}` and run
 
-**If `target_in_manifest = true`:**
+```bash
+uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"
+```
+
+The emitter folds each recorded decision into the result record's `headless_decisions`, and §10 records its auto-confirm the same way. If the command fails, go on: only that entry is lost.
+
+**If `target_in_manifest = false`:** Skip this prompt — soft-deprecate is meaningless without a manifest entry to mark, so only a purge applies. Take the first case that matches:
 
-**If a `mode` argument was supplied at invocation:** an explicit `mode` arg is the per-run override and takes precedence over `{defaultMode}`. If it is `"deprecate"` or `"purge"`, set `drop_mode` from it and record the decision source `mode_source = "--mode argument"`. If a `mode` arg was supplied but is not one of `deprecate` / `purge`, HALT (exit code 2, `halt_reason: "input-invalid"`): "invalid `--mode` value `{supplied}` — expected `deprecate` or `purge`." In headless mode, emit the error envelope per `{headlessContract}` with `skill: "{target_skill}"`, `drop_mode: null`.
+1. A `mode` argument other than `purge`: HALT (exit code 2, `halt_reason: "input-invalid"`, phase `select:mode`), with `skill: "{target_skill}"` in the §1 halt envelope: "`{target_skill}` has no manifest entry, so there is nothing to deprecate. Re-run with `--mode purge` to delete it."
+2. `{headless_mode}` is true and no `mode` argument was passed: HALT (exit code 2, `halt_reason: "input-missing"`, phase `select:mode`), with `skill: "{target_skill}"` in the §1 halt envelope: "headless mode: `{target_skill}` has no manifest entry, so only a purge applies; re-run with `--mode purge`."
+3. Otherwise force `drop_mode = "purge"` (record `mode_source = "draft-skill-forced-purge"`), 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.", and apply §8b. An interactive run still confirms the purge at §10. A headless run reaches this case only with `mode=purge`, which the On-Activation guard has already checked against `{forbidPurgeInHeadless}`.
 
-**Else if `{defaultMode}` is non-empty (`"deprecate"` or `"purge"`)**: skip the prompt, set `drop_mode = "{defaultMode}"`, and record the decision source `mode_source = "customize.toml.workflow.default_mode"` for the headless decision trail.
+**If `target_in_manifest = true`:**
+
+**If a `mode` argument was supplied at invocation:** if it is `"deprecate"` or `"purge"`, set `drop_mode` from it and record the decision source `mode_source = "--mode argument"`. If a `mode` arg was supplied but is not one of `deprecate` / `purge`, HALT (exit code 2, `halt_reason: "input-invalid"`, phase `select:mode`), with `skill: "{target_skill}"` in the §1 halt envelope: "invalid `--mode` value `{supplied}`: expected `deprecate` or `purge`."
 
-**Otherwise (interactive):** If `{headless_mode}` is true at this point (no `mode` arg and no `{defaultMode}`), there is no input to prompt for — HALT (exit code 2, `halt_reason: "input-missing"`): "headless mode requires `--mode deprecate|purge` or `default_mode` in customize.toml to set the drop mode." Emit the error envelope per `{headlessContract}` with `skill: "{target_skill}"`, `drop_mode: null`. Otherwise, prompt the user:
+**Otherwise:** If `{headless_mode}` is true (no `mode` arg), there is no input to prompt for: HALT (exit code 2, `halt_reason: "input-missing"`, phase `select:mode`), with `skill: "{target_skill}"` in the §1 halt envelope: "headless mode requires `--mode deprecate|purge` to set the drop mode." Otherwise, prompt the user. Before showing the menu, run the §8b purge check at the current scope; when `{purge_verdict}` is not `"ok"`, leave out **[P]** and add the line "Purge is not offered: {the §8b refusal message for `{purge_reason}`}."
 
 "**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.**
+- **[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 {affected_directories} from disk (a forge folder SKF did not generate stays where it is). **Irreversible.**
 - **[X]** Cancel and exit (or type `cancel` / `exit` / `:q`)"
 
 Wait for user selection.
 
 Set `drop_mode` to `"deprecate"` (on D) or `"purge"` (on P), and record `mode_source = "interactive-prompt"`.
 
-### 9. Compute Affected Directories
+### 8b. Purge Guard
 
-Using the templates from `{versionPathsKnowledge}`, resolve the list of directories that would be affected:
+A purge deletes only what SKF generated, and the inventory helper decides what that is: never decide by hand whether SKF generated a folder.
 
-**If `is_skill_level = false` (version-level drop):**
+**The purge check.** Run it once, at the scope §6 chose, and reuse its result wherever this step reads it (§8's menu, the guard below and §9). Resolve `{skillInventoryHelper}` ← first existing path in `{skillInventoryProbeOrder}`:
 
-- `{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}/`
+```bash
+uv run {skillInventoryHelper} "{skills_output_folder}" --skill {target_skill} --purge-check [--purge-version {version}] --forge-data-folder "{forge_data_folder}"
+```
+
+Pass `--purge-version {version}` for a single-version drop (`is_skill_level = false`) and leave it out for a whole skill. From its `purge_check`, bind `{purge_verdict}` ← `verdict`, `{purge_reason}` ← `reason`, `{purge_detail}` ← `detail`, `{purge_entries}` ← `offending_entries`, `{affected_directories}` ← `affected_directories`, `{forge_left_in_place}` ← `forge_left_in_place` and `{forge_errors}` ← `forge_errors`. The helper alone decides what a purge may delete: `{purge_reason}` names the rule that refused, and `{forge_left_in_place}` the forge folder a purge leaves where it is because SKF did not generate it.
 
-**If `is_skill_level = true` (skill-level drop):**
+When `{skillInventoryHelper}` resolves to no path, `{roster}.inventory` is false, the call exits non-zero, or its result has no `purge_check` (an installed `skf-skill-inventory.py` older than the flag), bind `{purge_verdict}` and `{purge_reason}` to `"unknown"`: SKF cannot check what it would delete.
 
-- `{skill_group}` = `{skills_output_folder}/{target_skill}/`
-- `{forge_group}` = `{forge_data_folder}/{target_skill}/`
+**The guard.** Skip it when `drop_mode == "deprecate"`. When `{purge_verdict}` is not `"ok"`, HALT (exit code 5, `halt_reason: "not-skf-output"`, phase `select:purge-guard`) with the message for `{purge_reason}`, and `skill: "{target_skill}"` and `drop_mode: "purge"` in the §1 halt envelope.
 
-Store the list as `affected_directories`.
+- `skill-mixed-whole`: "**Purge refused: `{skills_output_folder}/{target_skill}/` also holds entries SKF did not generate:** {purge_entries}. Nothing was deleted. Move them out of the folder and re-run. For a skill in the manifest, you can also purge a single version SKF generated, or use `--mode deprecate`. A version folder with no `metadata.json` can also be one that an interrupted update-skill run left behind; delete it yourself in that case."
+- `skill-version-not-skf`: "**Purge refused: SKF did not generate `{skills_output_folder}/{target_skill}/{version}`** (it has no SKF marker in its `metadata.json`, or it is a link). Nothing was deleted. Use `--mode deprecate` to mark the version deprecated in the manifest only, or remove it yourself."
+- `skill-version-mixed`: "**Purge refused: `{skills_output_folder}/{target_skill}/{version}` also holds entries SKF did not generate:** {purge_entries}. Nothing was deleted. Move them out and re-run, or use `--mode deprecate`."
+- `skill-foreign`, `reserved-name` or `unknown`: "**Purge refused: SKF cannot confirm that it generated `{skills_output_folder}/{target_skill}/`:** {reason}. Nothing was deleted. Use `--mode deprecate` to mark it deprecated in the manifest only, or delete the folder yourself." `{reason}` is `{purge_detail}` (it names a link, or a `metadata.json` with no SKF marker), and for `unknown` "the inventory helper is missing, or the installed `skf-skill-inventory.py` has no purge check; re-install SKF".
+- `forge-mixed-whole`: "**Purge refused: `{forge_data_folder}/{target_skill}/` also holds entries SKF did not generate:** {purge_entries}. Nothing was deleted. Move them out of the folder and re-run. For a skill in the manifest, you can also purge a single version SKF generated, or use `--mode deprecate`."
+- `forge-version-mixed`: "**Purge refused: `{forge_data_folder}/{target_skill}/{version}/` holds entries SKF did not generate:** {purge_entries}. Nothing was deleted. Move them out and re-run, or use `--mode deprecate`."
 
-If `drop_mode == "deprecate"`, record the list but present it as "retained" in the confirmation output — no deletion will occur.
+### 9. Compute Affected Directories
+
+`affected_directories` is the §8b purge check's list: the folders a purge at this scope deletes. In deprecate mode the list shows what the drop keeps on disk, and §10 presents it as retained. When the purge check has no verdict (`"unknown"`), build it from these paths instead: `{skills_output_folder}/{target_skill}/{version}` and `{forge_data_folder}/{target_skill}/{version}` for a single version, `{skills_output_folder}/{target_skill}` and `{forge_data_folder}/{target_skill}` for a whole skill, each without a trailing `/`, and only once when both settings name one folder.
 
 #### 9b. Compute Blast-Radius Metrics (for §10 summary)
 
-Compute three scalars to put in front of the path list at §10, so the user sees the scale of an irreversible drop before scanning individual paths:
+Compute the three scalars §10's `Scope:` line shows:
 
-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)
+1. **`versions_count`**: the number of skill versions in scope, never counted by hand:
+   - Version-level drop: `1`
+   - Skill-level drop: `{version_counts}.non_deprecated` (§5) for a skill in the manifest (the deprecated versions are already absent from the active managed sections), and `{version_counts}.on_disk` for a draft
 
-2. **`bytes_total`** — the on-disk size of `affected_directories`. Delegate the recursive sum and the human label to the sizing helper rather than adding file sizes in-prompt:
+2. **`bytes_total`**: the on-disk size of `affected_directories`. Delegate the recursive sum and the human label to the sizing helper rather than adding file sizes in-prompt:
 
    ```bash
-   uv run {dirSizesHelper} sizes {each path in affected_directories, space-separated}
+   uv run {dirSizesHelper} sizes {each path in affected_directories, quoted, space-separated}
    ```
 
-   Read `total_human` (e.g. `"4.2 MB"`) as `bytes_total` and `total_bytes` as `bytes_total_raw`; non-existent paths report `exists: false` and drop out of the total. If the helper is unavailable, fall back to `du -sb` per path — the display is best-effort. execute.md §4 re-runs the same helper on the paths it actually deletes for the canonical `disk_freed`, so the two share one method and differ only if files change between this gate and execution.
+   Read `total_human` (e.g. `"4.2 MB"`) as `bytes_total`; a path that does not exist adds nothing. If the helper is unavailable, fall back to `du -sb` per path: the display is best-effort.
 
-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 the `{unknownIdeDefaultContextFile}` fallback for unknown IDEs)
-   - Deduplicate by `context_file`
-   - Count the result. If `config.yaml.ides` is absent or empty, default to `1` (the single `{unknownIdeDefaultContextFile}` fallback)
+3. **`context_files_count`**: the number of context files step 2 rebuilds. Map the `ides` list of `config.yaml` (an absent key is an empty list) through the IDE mapping export-skill writes the section with, using the `{rebuildManagedSectionsHelper}` On-Activation §4 resolved:
 
-Store as `blast_radius = {versions_count, bytes_total, bytes_total_raw, context_files_count}` for §10's summary line.
+   ```bash
+   python3 {rebuildManagedSectionsHelper} resolve-targets --ides "{ides}"
+   ```
+
+   `{ides}` is the comma-joined list. Store `targets` as `target_context_files` (one `{context_file, skill_root, ides}` entry per file; an IDE the mapping does not list, and an empty list, resolve to AGENTS.md with `.agents/skills/`), set `context_files_count` to its length, and show each `warnings[]` and `notes[]` line. When the helper exits non-zero, HALT (exit code 4, `halt_reason: "context-rebuild-failed"`, phase `select:context-files`), with `skill: "{target_skill}"` and `drop_mode: "{drop_mode}"` in the §1 halt envelope: "SKF cannot resolve the context files to rebuild: {the helper's `error`, or its stderr when stdout holds no JSON}. Nothing was changed. Re-install SKF."
 
 ### 10. Confirmation Gate
 
@@ -278,6 +278,7 @@ Display the full operation summary with the blast-radius summary line ahead of t
   Files:
     {for each path in affected_directories, list one per line}
     {or "(retained on disk — soft drop)" if drop_mode == "deprecate"}
+    {if forge_left_in_place:} Left in place (not SKF output): {forge_left_in_place}{if forge_errors is non-empty: ": " + forge_errors}
 
 {if drop_mode == "purge":}
   ⚠️  This operation cannot be undone. Files will be permanently deleted.
@@ -287,11 +288,7 @@ Display the full operation summary with the blast-radius summary line ahead of t
 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.
-
-**Resolve `--dry-run` first — it takes precedence over the headless auto-confirm.** `--dry-run` and `--headless` can be combined (dry-run is the automated-preview path), so a dry-run run must always short-circuit to the preview below and never mutate, even when `{headless_mode}` is true.
-
-**If `--dry-run` was passed**: skip the Y/N prompt entirely — do not evaluate the headless auto-confirm gate. Display the `[DRY RUN]` line with the resolved selection, so the user can re-run interactively with the same values when ready to commit:
+**If `--dry-run` was passed**, it takes precedence over the headless auto-confirm: skip the Y/N prompt even when `{headless_mode}` is true, change nothing, and display the `[DRY RUN]` line with the resolved selection, so the user can re-run with the same values when ready to commit:
 
 ```
 **[DRY RUN] No changes were made — preview above shows what would be dropped.**
@@ -302,28 +299,29 @@ Resolved selection:
   Mode:    {Deprecate (soft) | Purge (hard)}
 ```
 
-Then emit the success envelope per `{headlessContract}` 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.
+When `{headless_mode}` is true, stage the preview as `{run_dir}/result-context.json` and print its envelope. `would_delete` lists the folders a purge would delete, so an automator can check the blast radius before it runs the drop:
 
-**Otherwise (not a dry-run) — GATE [default: Y]:** If `{headless_mode}`: auto-proceed with [Y], record `confirm_source = "headless-auto"`, log: "headless: auto-confirmed drop of {target_skill}"
+```json
+{"status": "dry-run", "skill": "{target_skill}", "drop_mode": "{drop_mode}", "versions_affected": {target_versions}, "would_delete": {affected_directories when drop_mode is purge, else []}, "forge_left_in_place": {forge_left_in_place when drop_mode is purge, else null}}
+```
+
+```bash
+uv run {emitEnvelopeHelper} emit --workflow skf-drop-skill --run-dir "{run_dir}" < "{run_dir}/result-context.json"
+```
+
+A dry run passes no `--result-dir`, so it writes no result file. Then, in either mode, delete the run folder (`rm -rf "{run_dir}"`) and HALT (exit code 0). In a headless run, display the line the emitter printed verbatim (the `message` of its stderr JSON when it exits non-zero) after the delete and before the HALT, with nothing after it, so a `claude -p` caller reads it as the final message. The manifest, filesystem, and context files are untouched.
+
+**Otherwise (not a dry-run), GATE [default: Y]:** If `{headless_mode}`: auto-proceed with [Y], record `confirm_source = "headless-auto"`, stage `{run_dir}/decision.json` as `{"gate": "select.confirm", "default_action": "Y", "taken_action": "Y", "reason": "headless auto-confirm"}` and run the §8 `record` command, and log: "headless: auto-confirmed drop of {target_skill}"
 
 Wait for explicit user response.
 
 - **If `Y`** → record `confirm_source = "user-explicit"` and proceed to section 11
-- **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 `{headlessContract}` with the resolved `skill`, `drop_mode`, and `versions_affected`.
+- **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"`, phase `select:confirm`).
 - **Any other input** → re-display the confirmation and ask again
 
 ### 11. Store Decisions in Context
 
-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 2 will delete in purge mode (or retain in deprecate mode)
-- `mode_source` — where `drop_mode` was decided, set inline at §8 (one of the four sources named there)
-- `confirm_source` — how the §10 gate was cleared, set inline at §10 (`"headless-auto"` or `"user-explicit"`)
+Step 2 reads the decisions this step bound where it made them: `target_skill`, `target_in_manifest`, `target_versions`, `drop_mode`, `is_skill_level`, `affected_directories`, `mode_source`, `forge_left_in_place`, `target_context_files` and `confirm_source`.
 
 ### 12. Load Next Step
 

package/src/skf-drop-skill/scripts/dir-sizes.py

@@ -1,16 +1,18 @@
 #!/usr/bin/env python3
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.11"
 # ///
 """Deterministic directory-size measurement for skf-drop-skill.
 
-The drop workflow twice needs an exact recursive byte total plus a stable
-human label ("4.2 MB" / "812 KB"): select.md §9b renders the blast-radius
-line ahead of the confirmation gate, and execute.md §4 reports the canonical
-`disk_freed`. Summing file sizes and rounding a unit in the prompt has one
-correct answer per input, so it belongs here — identical input yields
-identical output, and the gate preview and the post-purge report agree on the
-method (they can still differ only because they read at different times).
+The drop workflow twice needs a stable human label ("4.2 MB" / "812 KB"):
+select.md section 9b renders the blast-radius line ahead of the confirmation
+gate from the exact recursive byte total measured here, and execute.md
+section 4 formats the canonical `disk_freed` from the `bytes_freed` that
+skf-skill-inventory.py guarded-delete measured just before it deleted each
+folder. Summing file sizes and rounding a unit in the prompt has one correct
+answer per input, so it belongs here: identical input yields identical
+output, and the gate preview and the post-purge report agree on the method
+(they can still differ only because they read at different times).
 
 Two operations:
 
@@ -19,14 +21,16 @@ Two operations:
                         excluded from the total). Symlinks are measured by the
                         size of the link itself, never followed.
   humanize <bytes>...   sum a set of already-measured byte counts and format
-                        one human label. execute.md §4 feeds it the sizes of
-                        the paths that were actually deleted.
+                        one human label. execute.md section 4 feeds it the
+                        `bytes_freed` of guarded-delete.
 
-Output is a single JSON object on stdout. Exit codes: 0 ok; 2 usage error
-(missing/unknown op, or a non-integer byte count for `humanize`).
+Output is a single JSON object on stdout. Exit codes: 0 ok (and --help);
+2 usage error (missing/unknown op or argument, or a non-integer byte count
+for `humanize`), reported as a JSON error on stderr.
 """
 from __future__ import annotations
 
+import argparse
 import json
 import os
 import sys
@@ -97,20 +101,44 @@ def _op_humanize(raw: list[str]) -> dict:
     return {"status": "ok", "op": "humanize", "total_bytes": total, "total_human": humanize_bytes(total)}
 
 
-def main(argv: list[str]) -> int:
-    if not argv:
-        print(json.dumps({"status": "error", "error": "usage: dir-sizes.py {sizes|humanize} <args>"}), file=sys.stderr)
-        return 2
-    op, args = argv[0], argv[1:]
-    if op == "sizes":
-        print(json.dumps(_op_sizes(args)))
-        return 0
-    if op == "humanize":
-        print(json.dumps(_op_humanize(args)))
-        return 0
-    print(json.dumps({"status": "error", "error": f"unknown op: {op!r}"}), file=sys.stderr)
-    return 2
+class _JsonErrorParser(argparse.ArgumentParser):
+    """Report a usage error as the same stderr JSON and exit 2 as a bad byte count.
+
+    The subcommand parsers are made with this class too, so an unknown op or
+    flag never reaches argparse's own plain-text usage.
+    """
+
+    def error(self, message: str) -> None:
+        print(json.dumps({"status": "error", "error": f"usage error: {self.prog}: {message}"}), file=sys.stderr)
+        sys.exit(2)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = _JsonErrorParser(
+        prog="dir-sizes.py",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    sub = parser.add_subparsers(dest="op", required=True, metavar="{sizes,humanize}")
+
+    p_sizes = sub.add_parser("sizes", help="recursive byte size of each path, and their total")
+    p_sizes.add_argument("paths", nargs="*", metavar="path",
+                         help="a file or folder to measure; a link is measured as itself, never followed")
+
+    p_humanize = sub.add_parser("humanize", help="sum already-measured byte counts into one human label")
+    p_humanize.add_argument("byte_counts", nargs="*", metavar="bytes",
+                            help="an integer byte count, such as guarded-delete's bytes_freed")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    if args.op == "sizes":
+        print(json.dumps(_op_sizes(args.paths)))
+    else:
+        print(json.dumps(_op_humanize(args.byte_counts)))
+    return 0
 
 
 if __name__ == "__main__":
-    sys.exit(main(sys.argv[1:]))
+    sys.exit(main())