bmad-module-skill-forge 2.1.0 → 3.0.0

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

@@ -1,39 +1,16 @@
 ---
 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'
-# Resolve `{updateActiveSymlinkHelper}` similarly. §4 uses it (update
-# action) to atomically repoint `{skill_group}/active` after a version-level
-# purge deletes the version the symlink pointed at — the helper does a
-# temp-symlink + os.replace flip so concurrent readers never see a missing
-# link. Matches skf-update-skill/references/write.md and
-# skf-rename-skill/references/execute.md. HALT if neither candidate exists.
+# {updateActiveSymlinkHelper}: the §4 `active` repoint.
 updateActiveSymlinkProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-update-active-symlink.py'
   - '{project-root}/src/shared/scripts/skf-update-active-symlink.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 `disk_freed`
-# (§4). Bundled with this skill; the same helper backs select.md §9b's
-# blast-radius preview, so gate and report agree on the method.
+# {skillInventoryHelper}: the §4 guarded delete and `resolve`.
+skillInventoryProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-skill-inventory.py'
+  - '{project-root}/src/shared/scripts/skf-skill-inventory.py'
+# {dropRosterHelper}: the §5 context-file check.
+dropRosterHelper: 'scripts/drop-roster.py'
+# {dirSizesHelper}: the §4 `disk_freed` label.
 dirSizesHelper: 'scripts/dir-sizes.py'
 ---
 
@@ -51,24 +28,27 @@ Execute the drop decisions recorded in step 1: update the export manifest, rebui
 - 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
+- Record each degraded outcome as a warning the moment it happens, with the text the section names, so the envelope and the result record carry it: `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning '<the warning>'`, a single quote in it written as a backtick. If the command fails, go on: only that entry is lost.
 
 ## MANDATORY SEQUENCE
 
-### 1. Re-read Version-Paths Knowledge
+### 1. Halt Envelope
 
-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.
+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
 
-Also read `{managedSectionLogic}` for the format template, the four-case logic, and the skill index rebuild rules that will be reused in section 3.
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-drop-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
 
-If `{headless_mode}` is true, also read `{headlessContract}` now — it defines the single-line result envelope the error paths below emit, so the shape is in context even if SKILL.md was compacted out.
+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.
 
 ### 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 == 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.
 
 **If `target_in_manifest == true`:**
 
-**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.
+Write through the `{manifestOpsHelper}` On-Activation §4 resolved: atomic manifest mutation always goes through the helper.
 
 **If `is_skill_level == false` (version-level drop):**
 
@@ -82,88 +62,56 @@ The helper sets `exports.{target_skill}.versions.{version}.status = "deprecated"
 
 **If `is_skill_level == true` (skill-level drop):**
 
-```bash
-python3 {manifestOpsHelper} {skills_output_folder} remove {target_skill}
-```
-
-The helper deletes the `exports.{target_skill}` key entirely; other entries are untouched.
-
-Set context flag `manifest_updated = true`.
-
-**On error (helper non-zero exit):**
+- **Deprecate (`drop_mode == "deprecate"`):** mark every version deprecated and keep the entry, so the soft drop stays reversible. With no version, the helper sets the `status` of every version under `exports.{target_skill}.versions` to `"deprecated"` and leaves `active_version` as it is:
 
-- Do not proceed to section 3
-- 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 `{headlessContract}` with `halt_reason: "manifest-write-failed"` and exit code 4.
+  ```bash
+  python3 {manifestOpsHelper} {skills_output_folder} deprecate {target_skill}
+  ```
 
-### 3. Rebuild Context Files
-
-Load the `ides` list from `config.yaml`. The installer writes IDE identifiers — these must be mapped to context files and skill roots using the "IDE → Context File Mapping" table in `{managedSectionLogic}`.
-
-**Resolve `target_context_files`** using the canonical mapping table in `{managedSectionLogic}`:
-
-1. For each entry in `config.yaml.ides`, look up its `context_file` and `skill_root` from the mapping table
-2. For any entry not found in the table, default to `{unknownIdeDefaultContextFile}` / `{unknownIdeDefaultSkillRoot}` (resolved at SKILL.md On Activation §3 from `workflow.unknown_ide_default_*`, bundled defaults `AGENTS.md` / `.agents/skills/`) and emit a warning: "Unknown IDE '{value}' in config.yaml — defaulting to {unknownIdeDefaultContextFile}"
-3. Deduplicate by `context_file` — when multiple IDEs map to the same context file, use the first configured IDE's `skill_root`
-4. If `config.yaml.ides` is absent or the mapping yields an empty list, fall back to `[{context_file: "{unknownIdeDefaultContextFile}", skill_root: "{unknownIdeDefaultSkillRoot}"}]` and emit a note: "No IDEs configured in config.yaml — defaulting to {unknownIdeDefaultContextFile}"
+- **Purge:** the helper deletes the `exports.{target_skill}` key entirely; other entries are untouched:
 
-Store the result as `target_context_files` for this section.
+  ```bash
+  python3 {manifestOpsHelper} {skills_output_folder} remove {target_skill}
+  ```
 
-For each entry in `target_context_files`:
+When the helper exits 0 (`status: "ok"`), set context flag `manifest_updated = true`.
 
-1. **Resolve target file** at `{context_file}`.
+**On error (the helper exits non-zero):** HALT (exit code 4, `halt_reason: "manifest-write-failed"`, phase `execute:manifest-write`, path `{skills_output_folder}/.export-manifest.json`) in every mode, before section 3: "**Manifest update failed:** {the helper's `error`, `status: not_found` when the entry is no longer there, or its stderr when stdout holds no JSON}. Nothing was changed: no file was deleted, no context file was rebuilt, and the manifest is in its pre-drop state. Re-run the drop once the cause is fixed." The §1 halt envelope carries the resolved `skill`, `drop_mode` and `versions_affected`, with `manifest_updated: false`. The run ends here: step 3 never runs, so no success report is shown and no result file is written.
 
-2. **Read the current file.**
-   - If the file does not exist, skip this context file (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 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. Rebuild Context Files
 
-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
+Rebuild the managed section of each context file step 1 resolved (`target_context_files`, from `resolve-targets` in select.md §9b) the way export-skill writes it, through the `{rebuildManagedSectionsHelper}` On-Activation §4 resolved.
 
-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
+A target's file is `{context_path}`, its `{context_file}` in `{project-root}`, and `{target_paths}` is the `{context_path}` of every target, each quoted, space-separated, in the order of `target_context_files`. For each entry in `target_context_files`:
 
-5. **Rewrite root paths for the current context file** using the generic rewrite algorithm from export-skill step 4 section 4d:
+1. **Check the file.**
 
-   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.
+   ```bash
+   python3 {rebuildManagedSectionsHelper} "{context_path}" check
+   ```
 
-6. **Sort skills alphabetically by name.** Count totals (skills, stack skills).
+   Its `case` decides. `create` (no file) or `append` (no managed section): skip this file, since there is no section to rebuild (export-skill adds one on its next run). `malformed` or `unreadable`: bind `{context_error}` ← `error` and take item 4. The drop does not halt on one context file: section 2 already updated the manifest, which is the canonical state, and the next `[EX] Export Skill` run rebuilds the file once it is repaired. `regenerate`: continue.
 
-7. **Assemble the new managed section** using the format from `{managedSectionLogic}`:
+2. **Build the section body.**
 
-   ```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 -->
+   ```bash
+   python3 {rebuildManagedSectionsHelper} assemble "{context_path}" \
+     --skills-folder "{skills_output_folder}" --skill-root "{skill_root}" \
+     --dropped {target_skill} --orphan-sources {target_paths} \
+     [--skill-root-override "{snippet_skill_root_override}"]
    ```
 
-   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.
+   Add `--skill-root-override` only when `snippet_skill_root_override` is set in `config.yaml`. The helper builds the body export-skill would write for the manifest section 2 left, with the rows of skills the manifest does not know (orphan rows) kept verbatim; `--dropped {target_skill}` keeps the dropped skill's old rows from staying as orphan rows. It writes the body to `{context_path}.skf-content` and prints its result as JSON: show each `warnings[]` line and each `skipped_*` entry as a warning, except a `skipped_deprecated` entry for `{target_skill}`, which the drop itself deprecated. On a non-zero exit, bind `{context_error}` ← `error` and take item 4.
 
-8. **Surgical replacement — atomic, deterministic.** Resolve `{rebuildManagedSectionsHelper}` from `{rebuildManagedSectionsProbeOrder}`; first existing path wins. Then invoke:
+3. **Replace the section.** Feed the staged body to the helper by stdin redirection. Never pass the body inline as `--content "…"` or through `echo`: snippets carry backticks, `$` and quotes, which the shell expands, and the helper checks the text it received, so it would report success on corrupted bytes.
 
    ```bash
-   python3 {rebuildManagedSectionsHelper} {context_file} replace --content "{new_managed_section_text}"
+   python3 {rebuildManagedSectionsHelper} "{context_path}" replace < "{context_path}.skf-content"
    ```
 
-   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 (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.
+   Delete `{context_path}.skf-content` once the helper returns, whatever its exit code. It refuses a body that holds a marker of its own, and then leaves the file unchanged. It exits 0 only when the `status` of its JSON is `"ok"`. On a non-zero exit, bind `{context_error}` ← `error`, or the helper's stderr when stdout holds no JSON.
 
-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.
+4. **On per-file failure:** record `{context_error}` against that context file, record the warning `context_rebuild_failed: {context_file}: {context_error}`, and continue to the next entry. Do not halt: other context files should still be rebuilt.
 
 **After the loop,** record `context_files_updated` as the list of files that were successfully rewritten, and `context_files_failed` as the list of any that failed.
 
@@ -175,84 +123,69 @@ Report: "**Rebuilt managed sections in:** {list of updated files}. {if any faile
 
 **If `drop_mode == "purge"`:**
 
-1. Initialize `files_deleted = []` and `delete_failures = []` (paths whose deletion was attempted but did not succeed).
-
-2. **Measure sizes before deleting anything.** Run the sizing helper once over `affected_directories` so each path's byte size is captured while it still exists:
+1. **Delete through the guarded delete.** Resolve `{skillInventoryHelper}` from `{skillInventoryProbeOrder}` (first existing path wins) and run it once over every path in `affected_directories`, with the skills folder and the forge folder as the only folders it may delete inside:
 
    ```bash
-   uv run {dirSizesHelper} sizes {each path in affected_directories, space-separated}
+   uv run {skillInventoryHelper} guarded-delete --root "{skills_output_folder}" --root "{forge_data_folder}" {each path in affected_directories, quoted, space-separated}
    ```
 
-   Keep each `result.paths[].bytes` as `path_bytes[{path}]`; a path reported `exists: false` is already gone. If the helper is unavailable, fall back to `du -sb` per existing path.
+   The helper removes any trailing `/`, and SKF never deletes through a link. Bind `files_deleted` ← `files_deleted`, `delete_failures` ← `delete_failures` (each `{path, error}`), `{bytes_freed}` ← `bytes_freed` and `{purge_status}` ← `purge_status`. An empty `affected_directories` (a manifest entry whose folders are already gone) deletes nothing and returns `success`.
 
-3. 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. Delete the directory recursively
-   d. Verify deletion succeeded (the path no longer exists)
-   e. Append the path to `files_deleted`
+   When no candidate exists, delete nothing by hand: take the `failed` outcome below, with "the inventory helper that checks each delete is missing; re-install SKF" as the error of every path. On a non-zero exit, or no JSON on stdout, take the `failed` outcome too, with the helper's `error` (its stderr when stdout holds no JSON) as the error of every path.
 
-4. **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. The version directory is already gone at this point, so a symlink problem never claims `delete-failed` — record it and continue (`verification_errors`) so the report surfaces the manual repair rather than masking a successful purge.
-     - **Other non-deprecated versions remain** for `{target_skill}`: resolve `{new_active_version}` = the version the manifest now lists as `active_version` for `{target_skill}` (if that one is deprecated, the newest non-deprecated version in its `versions` map). Repoint `active` to it atomically through the shared helper rather than a hand-rolled `ln` — resolve `{updateActiveSymlinkHelper}` from `{updateActiveSymlinkProbeOrder}` (first existing path wins), then:
+2. **Version-level purge, single version:** if the `active` symlink pointed to the just-deleted version, update or remove it. The version folder is already gone, so a symlink problem never claims `delete-failed`: record the manual repair in `verification_errors`, record the warning `active_link_dangling: {skills_output_folder}/{target_skill}/active: {the manual repair}`, and continue. Read the versions the drop left through the inventory helper's `resolve`, never from the manifest by hand:
+     ```bash
+     uv run {skillInventoryHelper} resolve "{skills_output_folder}" --skill {target_skill} --forge-data-folder "{forge_data_folder}"
+     ```
+     When it exits non-zero, record the manual repair (point `active` at the newest version the manifest does not list as deprecated, or remove it when none is left) as above and continue.
+     - **Other non-deprecated versions remain** (`resolve.counts.non_deprecated` is above `0`): `{new_active_version}` ← `resolve.active_version`, the version the manifest lists as active, unless it is null or its `resolve.versions` entry has `status` `"deprecated"`; then `resolve.newest_non_deprecated`. Repoint `active` to it atomically through the shared helper rather than a hand-rolled `ln`: resolve `{updateActiveSymlinkHelper}` from `{updateActiveSymlinkProbeOrder}` (first existing path wins), then:
        ```bash
        python3 {updateActiveSymlinkHelper} update \
          --skill-group {skills_output_folder}/{target_skill} \
          --version {new_active_version}
        ```
-       The helper does a temp-symlink + `os.replace` flip, so a concurrent reader never sees a missing `active`. Record a `mismatch`/`missing-target` exit (code 2), or a missing helper (no probe candidate), in `verification_errors` with the manual fix (`ln -sfn {new_active_version} {skills_output_folder}/{target_skill}/active`) and continue.
-     - **No non-deprecated versions remain** (reachable only when dropping the sole surviving version, permitted in step 1 because no other non-deprecated versions existed): remove the now-dangling `active` symlink with a single atomic unlink of the link itself — `rm {skills_output_folder}/{target_skill}/active` (unlink removes only the symlink, never its target, and is atomic). A single unlink has one correct outcome and no intermediate state, so it stays in-prompt (the helper has no removal action).
-
-5. **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
+       Record a `mismatch`/`missing-target` exit (code 2), or a missing helper (no probe candidate), as above with the manual fix `ln -sfn {new_active_version} {skills_output_folder}/{target_skill}/active`, and continue.
+     - **No non-deprecated versions remain** (`resolve.counts.non_deprecated` is `0`, reachable only when dropping the sole surviving version, permitted in step 1 because no other non-deprecated versions existed): remove the now-dangling `active` symlink with a single atomic unlink of the link itself: `rm {skills_output_folder}/{target_skill}/active` (unlink removes only the symlink, never its target). When it fails, record it as above with the manual fix `rm {skills_output_folder}/{target_skill}/active`.
 
-6. Sum the sizes of the paths in `files_deleted` and format one human-readable label through the helper — do not add or round in-prompt:
+3. Format the size of the deleted folders through the sizing helper; do not add or round in-prompt:
 
    ```bash
-   uv run {dirSizesHelper} humanize {path_bytes[p] for each p in files_deleted, space-separated}
+   uv run {dirSizesHelper} humanize {bytes_freed}
    ```
 
    Store `result.total_human` as `disk_freed` (e.g. `"4.2 MB"`; `"0 B"` when nothing was deleted).
 
-**On deletion error (per path):**
+**Classify the deletion outcome from `{purge_status}`:**
 
-- Append the path and its error message to `delete_failures`
-- Continue attempting the remaining paths — a partial purge is still better than no purge
-- Report all failures at the end of this section
-
-**After the loop — classify the deletion outcome.** Let `attempted` be the number of paths in `affected_directories` that existed on disk (i.e. were not recorded as "(already absent)"):
-
-- **Full purge failure** — `attempted > 0` AND every attempted path is in `delete_failures` (nothing was deleted): the purge accomplished none of its destructive intent, so it must NOT report success. HALT (exit code 4, `halt_reason: "delete-failed"`): "**Purge failed** — none of the {attempted} target director(ies) could be deleted: {list each path with its error}. The manifest and context files were already updated in sections 2–3; the on-disk files remain and can be removed manually (`rm -rf {path}`)." In headless mode, emit the error envelope per `{headlessContract}` with the resolved `skill`, `drop_mode`, `versions_affected`, `files_deleted: []`, and `manifest_updated` from section 2. Do not proceed to section 5.
-- **Partial purge failure** — `delete_failures` is non-empty but at least one path was deleted: keep record-and-continue. Set `purge_status = "partial"` so step 3's on-disk result record reflects it (the `output-contract-schema.md` `status` enum supports `"partial"`); proceed to section 5. The headless single-line envelope has no `"partial"` value in its enum, so it stays `"success"` while `context_files_failed`/`verification_errors`/the report surface the unfreed paths.
-- **No failures** — `delete_failures` is empty: set `purge_status = "success"` and proceed to section 5.
+- **`failed`**: at least one path was attempted and none was deleted, so the purge accomplished none of its destructive intent and must NOT report success. HALT (exit code 4, `halt_reason: "delete-failed"`, phase `execute:delete`): "**Purge failed:** none of the target folders could be deleted: {list each `delete_failures` path with its error}. The manifest and context files were already updated in sections 2–3; the on-disk files remain and can be removed by hand (`rm -rf {path}`)." The §1 halt envelope carries the resolved `skill`, `drop_mode` and `versions_affected`, `files_deleted: []`, and `manifest_updated` from section 2. Do not proceed to section 5.
+- **`partial`**: `delete_failures` is non-empty but at least one path was deleted. Keep record-and-continue: `purge_status = "partial"` lets step 3's on-disk result record reflect it (the `output-contract-schema.md` `status` enum supports `"partial"`). Record the warning `delete_failed: {path}: {error}` for each `delete_failures` entry, then proceed to section 5.
+- **`success`**: nothing failed (a path already gone is not a failure). Proceed to section 5.
 
 ### 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
+1. **Manifest check** (skip it when `target_in_manifest == false`: section 2 changed no entry). Read the entry through `{manifestOpsHelper}`:
+
+   ```bash
+   python3 {manifestOpsHelper} {skills_output_folder} get {target_skill}
+   ```
 
-2. **Context files check:** For each file in `context_files_updated`, spot-check that the dropped skill/version is no longer referenced between the markers.
+   Version-level drop: `entry.versions.{version}.status` is `"deprecated"` for each version in `target_versions`. Skill-level deprecate: every version in `entry.versions` has `status` `"deprecated"`. Skill-level purge: `status` is `"not_found"`. A failure's manual fix: correct the `{target_skill}` entry of `{skills_output_folder}/.export-manifest.json` by hand.
 
-3. **Purge check (purge mode only):** For each path in `files_deleted`, confirm it no longer exists on disk.
+2. **Context files check** (skip it when `context_files_updated` is empty): list the rows the rebuilt files still hold for the dropped skill, by name and version only:
 
-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.
+   ```bash
+   uv run {dropRosterHelper} rows --skill {target_skill} [--version {version}] {each file in context_files_updated, quoted}
+   ```
 
-### 6. Store Results in Context
+   Pass `--version` for a version-level drop. Each `rows` entry fails the check, as does each `unchecked` entry (a file whose rows could not be read); the manual fix for both is to re-run `[EX] Export Skill`, which rebuilds the file. When the call exits non-zero, the check fails for every file in `context_files_updated`, with the helper's `error` (its stderr when stdout holds no JSON).
+
+If any verification fails, record it in `verification_errors` with its manual fix, record the warning `verification_failed: {what failed}: {its manual fix}`, and do not halt: proceed to step 3 so the report shows what succeeded and what needs manual attention.
 
-Store the following for step 3:
+### 6. Store Results in Context
 
-- `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)"`
-- `delete_failures` — list of `{path, error}` for paths whose deletion was attempted but failed (empty if none; a *full* purge failure already HALTed in section 4 and never reaches this step)
-- `purge_status` — `"success"`, `"partial"` (some paths failed to delete), or `"success"` for soft drops; step 3 maps this to the on-disk result record's `status` field
-- `manifest_updated` — boolean (true if section 2 succeeded)
-- `context_files_updated` — list of successfully rebuilt files
-- `context_files_failed` — list of files that failed to rebuild (empty if none)
-- `verification_errors` — list of verification failures (empty if none)
+Step 3 reads what this step bound where it ran: `files_deleted`, `disk_freed`, `delete_failures`, `purge_status`, `manifest_updated`, `context_files_updated`, `context_files_failed` and `verification_errors`, with `forge_left_in_place` carried from step 1.
 
 ### 7. Load Next Step
 

package/src/skf-drop-skill/references/invocation-contract.md

@@ -0,0 +1,64 @@
+# Invocation Contract: skf-drop-skill
+
+The arguments, gates, exit codes and headless result envelope of `skf-drop-skill`. Interactive runs do not need this file; headless automators and pipelines read it, and the SKILL.md On-Activation HALTs follow its Halt Envelope section.
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | skill_name [required], mode (deprecate/purge) [required], version (`all` or one version) [required for a skill in the manifest; a draft takes only `all`]. An argument supplied at invocation answers its step 1 prompt in either mode, so that prompt is not shown |
+| **Flags** | `--headless` / `-H` (auto-resolve all gates); `--dry-run` (run selection and display the §10 confirmation block, then exit with `status="dry-run"`: no manifest mutation, no file deletion) |
+| **Gates** | step 1: Input Gate [use args] (§4 skill), Scope Gate [use args] (§6 version), Mode Gate [use args] (§8 mode), Confirm Gate [Y] |
+| **Outputs** | Updated manifest, rebuilt context files, (purge: deleted directories), `drop-skill-result-{YYYYMMDD-HHmmss}.json` (UTC) and `drop-skill-result-latest.json` in `{skills_output_folder}` (none for a dry run or a HALT); a run folder under `{project-root}/_bmad-output/.skf-run/`, kept only after a HALT, except an interactive HALT in step 1 or 2, which deletes it |
+| **Headless** | Gates auto-resolve with their default action (SKILL.md Workflow Rules); select.md §6 and §8 halt when the `version` or `mode` argument a headless run must pass is missing. Any non-empty `forbid_purge_in_headless`, set under `[workflow]` in a team or personal override (never in the bundled `customize.toml`, which every update overwrites), stops a headless `mode=purge` at On-Activation §4 (exit code 6, `halt_reason: "headless-purge-forbidden"`) when the customization resolver runs. When it cannot, including an override file that fails to parse, the run warns `customization_resolver_unavailable` and the bundled empty value leaves the guard off. A key written without the `[workflow]` line is ignored with no warning, and the guard stays off. |
+| **Exit codes** | See "Exit Codes" below |
+
+## Exit Codes
+
+Every hard HALT exits with a stable code; the step files name the exact `halt_reason` and phase at each HALT site, and the envelope below carries both.
+
+| Code | Meaning              | Raised by (class) |
+| ---- | -------------------- | ----------------- |
+| 0    | success              | step 4 (terminal) |
+| 2    | input-missing / input-invalid | step 1 input gates: a missing or unmatched `skill_name`, `version` or `--mode` value (§4 / §6 / §8), or a draft skill given a specific `version` or `mode=deprecate` |
+| 3    | resolution-failure   | step 1 §2 corrupt manifest, §3 nothing to drop |
+| 4    | write-failure        | On-Activation §4, or step 1 §2 when the roster helper cannot run (`write-failed`); step 1 §9b, before any change (`context-rebuild-failed`); step 2 manifest write, in every mode (`manifest-write-failed`), or a purge that deleted nothing (`delete-failed`) |
+| 5    | state-conflict       | step 1 §7 active-version guard; §3, §4 or §8b ownership guard (`not-skf-output`) |
+| 6    | user-cancelled       | any interactive cancel or confirm-gate `[N]`; On-Activation headless-purge guard |
+
+## Result Contract (Headless)
+
+The single-line JSON contract every headless run of skf-drop-skill prints. The shared emitter, `shared/scripts/skf-emit-result-envelope.py`, builds each line from the payload the emitting step hands it and checks it against `shared/scripts/schemas/skf-drop-skill-result-envelope.v1.json`, so no stage types an envelope and a HALT prints the right shape whatever else is still in context.
+
+When `{headless_mode}` is true, step 3 prints this envelope on **stdout** before chaining to step 4, a `--dry-run` prints it on **stdout** at the step 1 confirmation gate, and every HARD HALT prints it on **stderr** with `status: "error"`:
+
+```
+SKF_DROP_SKILL_RESULT_JSON: {"status":"success|error|dry-run","skill":"…|null","drop_mode":"…|null","versions_affected":[],"files_deleted":[],"would_delete":[],"forge_left_in_place":null,"manifest_updated":false,"result_path":null,"exit_code":0,"halt_reason":null,"error":null}
+```
+
+Field rules:
+
+- `status`: `"success"` on the terminal happy path, `"dry-run"` when `--dry-run` was set and the workflow stopped at the confirmation gate before any change, `"error"` on any HALT.
+- `halt_reason`: on success and dry-run it is `null`; otherwise one of `"input-missing"`, `"input-invalid"`, `"manifest-corrupt"`, `"nothing-to-drop"`, `"active-version-guard-refused"`, `"not-skf-output"`, `"headless-purge-forbidden"`, `"manifest-write-failed"`, `"context-rebuild-failed"`, `"delete-failed"`, `"write-failed"`, `"user-cancelled"`.
+- `exit_code`: the emitter derives it from `halt_reason`, per the Exit Codes table above (`0` on success and dry-run).
+- `skill`, `drop_mode`, `versions_affected`, `files_deleted`, `manifest_updated`: the values the emit site knows; a key not resolved yet takes the default shown in the template (`null`, `[]` or `false`). `versions_affected` is a list holding the one version dropped, or the string `"all"` for the whole skill.
+- `would_delete`: in a dry run of a purge, the folders the purge would delete (the step 1 purge check's `affected_directories`), so an automator can check the blast radius before it runs the drop; `[]` otherwise, and in a dry run of a deprecate.
+- `forge_left_in_place`: the forge folder a purge leaves in place (or, in a dry run, would leave) because SKF did not generate it; `null` otherwise.
+- `result_path`: the per-run result file step 3 wrote, `{skills_output_folder}/drop-skill-result-{YYYYMMDD-HHmmss}.json` (UTC), stamped by the emitter; `null` for a dry run and a HALT, which write no result file.
+- `error`: `null` on success and dry-run; on a HALT, `{"phase", "reason"}`, plus `path` when the halt names one: the step and gate that halted, and the halt message.
+- `warnings`: present only when the run recorded at least one. A run that reports `success` can still carry the degraded outcomes step 2 records, which the report also shows: `context_rebuild_failed: <context file>: <error>` (a context file it could not rebuild), `active_link_dangling: <skill folder>/active: <manual fix>` (an `active` link a version purge left pointing at no version), `delete_failed: <path>: <error>` (a folder a partial purge could not delete) and `verification_failed: <what failed>: <manual fix>` (a final-state check that failed). Any run can carry `result_file_write_failed: <path>: <reason>` when the emitter could not write a result file, and `customization_resolver_unavailable: <reason>` when On Activation records that the customization resolver could not run, so the overrides under `{project-root}/_bmad/custom/` were not applied.
+
+Each emit site supplies its `halt_reason`, `exit_code` and phase, and whichever discriminating fields it knows; the emitter fills in the rest.
+
+## Halt Envelope
+
+Every HALT names its exit code, `halt_reason` and phase where it stops. In headless mode it prints its envelope before it stops: it stages `{run_dir}/halt.json` as `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>", "exit_code": <code>}`, plus `"path"` when the halt names one and the envelope fields the site names, runs the first command below and displays the line it prints verbatim. The SKILL.md On-Activation run-folder halt has no folder to stage in, so it hands that payload, on one line, to the second command. 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 payload leaves out its default (`null`, `[]` or `false`) and checks `exit_code` against `halt_reason`. When the helper is missing, exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing; in step 1 or 2 it then deletes the run folder.
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-drop-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-drop-skill --target stderr <<'SKF_DROP_HALT'
+{"phase": "on-activation:run-folder", "reason": "<the halt message>", "halt_reason": "write-failed", "exit_code": 4}
+SKF_DROP_HALT
+```
+
+SKILL.md On-Activation §4 binds `{emitEnvelopeHelper}` and `{run_dir}`, and its HALTs follow this section. select.md and execute.md state the same rule in their section 1, so the HALTs of a step never depend on this file.

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

@@ -1,14 +1,10 @@
 ---
 nextStepFile: 'health-check.md'
-# §1 resolves `{manifestOpsHelper}` from this order (installed SKF module path
-# first, src/ dev-checkout fallback) to read the target skill's remaining
-# versions — `get` for the versions+status map and `affected-versions` for the
-# numeric semver-descending order — instead of re-parsing the manifest by hand.
-# A read, not an atomicity-critical write: if neither path resolves, §1 reads
-# the manifest in-prompt.
-manifestOpsProbeOrder:
-  - '{project-root}/_bmad/skf/shared/scripts/skf-manifest-ops.py'
-  - '{project-root}/src/shared/scripts/skf-manifest-ops.py'
+# SKILL.md On-Activation §4 binds `{manifestOpsHelper}`, which §1 reads the
+# skill's remaining versions through (`get` for the versions and their status,
+# `affected-versions` for the numeric semver-descending order), and
+# `{emitEnvelopeHelper}` with `{run_dir}`: the emitter stamps the time and the
+# result file names, so this step types neither.
 ---
 
 <!-- Config: communicate in {communication_language}. Render the report block in {document_output_language}. -->
@@ -22,20 +18,19 @@ Present a clear, final summary of what the drop workflow changed — manifest st
 ## Rules
 
 - Focus only on reporting results stored in context by step 2 — do not re-execute any part of the drop
-- Do not hide verification errors or failed context file rebuilds
-- Chains to the local health-check step via `{nextStepFile}` after completion (see §3)
+- Do not hide verification errors, failed context file rebuilds or folders a purge could not delete
 
 ## MANDATORY SEQUENCE
 
 ### 1. Determine Remaining Versions
 
-**If `is_skill_level == true`:**
+**If `is_skill_level == true` and `drop_mode == "purge"`:**
 
 Set `remaining_versions_display = "(skill fully removed)"`.
 
-**If `is_skill_level == false`:**
+**Otherwise** (one version, or a whole-skill deprecate, which keeps every version in the manifest as `deprecated`):
 
-**Resolve `{manifestOpsHelper}`** ← first existing path in `{manifestOpsProbeOrder}`, then read the target skill's remaining versions through it rather than re-parsing the manifest by hand:
+Read the target skill's remaining versions through the `{manifestOpsHelper}` On-Activation §4 resolved, rather than re-parsing the manifest by hand:
 
 ```bash
 python3 {manifestOpsHelper} {skills_output_folder} get {target_skill}
@@ -50,8 +45,6 @@ python3 {manifestOpsHelper} {skills_output_folder} affected-versions {target_ski
   - 0.1.0 (deprecated)
 ```
 
-**If neither `{manifestOpsProbeOrder}` candidate resolves:** read `exports.{target_skill}.versions` from `{skills_output_folder}/.export-manifest.json` in-prompt, list each remaining version with its `status` (active marked `*`), ordering newest-first by comparing version components numerically.
-
 ### 2. Render the Report
 
 Display the following block, filling in values from context:
@@ -71,6 +64,8 @@ Changes:
 {if drop_mode == "purge":}
 - Files deleted:         {list from files_deleted, or "(none — nothing on disk)"}
 - Disk space freed:      {disk_freed}
+{if delete_failures is non-empty:}- Not deleted:           {each delete_failures path with its error} (remove by hand: `rm -rf {path}`)
+{if forge_left_in_place:}- Left in place (not SKF output): {forge_left_in_place}
 
 Remaining versions for {target_skill}:
 {remaining_versions_display}
@@ -84,40 +79,61 @@ restore the managed section entry.
 {if verification_errors is non-empty:}
 **Verification warnings:**
 {list each verification error}
-These require manual review — see the error-handling guidance in step 2.
+Each item above names its manual fix.
 ```
 
 ### Result Contract
 
-Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skills_output_folder}/drop-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{skills_output_folder}/drop-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all purged file paths in `outputs`; include `target_skill`, `drop_mode`, `versions_affected`, and a `headless_provenance` object in `summary`.
-
-`headless_provenance` persists the §8/§10 decision trail from step 1 so an unattended run's auto-decisions survive in the durable record, not only in the transient log — a consumer can tell an operator-confirmed drop from a headless auto-confirmed one without re-deriving it:
+The shared emitter writes the result contract (`shared/references/output-contract-schema.md`) and prints the envelope; this step stages their content. Write `{run_dir}/result-context.json`:
 
 ```json
-"headless_provenance": {"headless": {headless_mode}, "mode_source": "{mode_source}", "confirm": "{confirm_source}"}
+{
+  "status": "success",
+  "skill": "{target_skill}",
+  "drop_mode": "{drop_mode}",
+  "versions_affected": {target_versions},
+  "files_deleted": {files_deleted},
+  "forge_left_in_place": {forge_left_in_place},
+  "manifest_updated": {manifest_updated},
+  "result_contract": {
+    "skill": "skf-drop-skill",
+    "status": "{record_status}",
+    "outputs": [{"type": "skill", "path": "{each path in files_deleted}"}],
+    "summary": {
+      "target_skill": "{target_skill}",
+      "drop_mode": "{drop_mode}",
+      "versions_affected": {target_versions},
+      "forge_left_in_place": {forge_left_in_place},
+      "headless_provenance": {"headless": {headless_mode}, "mode_source": "{mode_source}", "confirm": "{confirm_source}"}
+    }
+  }
+}
 ```
 
-where `{headless_mode}` is the resolved boolean, `{mode_source}` is the step-1 §8 value (`"--mode argument"` / `"customize.toml.workflow.default_mode"` / `"interactive-prompt"` / `"draft-skill-forced-purge"`), and `{confirm_source}` is the step-1 §10 value (`"headless-auto"` / `"user-explicit"`).
-
-Set the record's `status` from step 2's `purge_status`: `"partial"` when some (but not all) purge-mode directories failed to delete — surface the failing paths from `delete_failures` in `summary.delete_failures` — otherwise `"success"`. A *full* purge failure never reaches this step: step 2 §4 HALTs with `halt_reason: "delete-failed"` and the error-envelope path below handles it.
+- `{target_versions}` is a JSON array (e.g. `["0.5.0"]`) or the string `"all"`; `{files_deleted}` a JSON array of absolute paths (`[]` in deprecate mode, and so is `outputs`); `{forge_left_in_place}` the path step 2 carried, or `null` when none and in deprecate mode; `{manifest_updated}` the boolean from step 2.
+- `{record_status}` is `"partial"` when some (but not all) purge folders failed to delete (step 2's `purge_status`); then also put step 2's `delete_failures` in `summary.delete_failures`. Otherwise it is `"success"`. A full purge failure and a failed manifest write never reach this step: step 2 HALTs with `halt_reason: "delete-failed"` or `"manifest-write-failed"`.
+- `headless_provenance` persists the §8/§10 decision trail from step 1, so an unattended run's auto-decisions survive in the durable record and a consumer can tell an operator-confirmed drop from a headless auto-confirmed one: `{headless_mode}` is the resolved boolean, and `{mode_source}` and `{confirm_source}` the values step 1 set.
+- The payload carries no `warnings`: the emitter adds the ones step 2 recorded, so a run whose envelope reads `success` still names what needs a manual fix.
 
-When `{headless_mode}` is true, also emit the single-line envelope on **stdout** before chaining to step 4 (the full shape and field rules are in `references/headless-contract.md`):
+Then run, in every mode:
 
-```
-SKF_DROP_SKILL_RESULT_JSON: {"status":"success","skill":"{target_skill}","drop_mode":"{drop_mode}","versions_affected":{target_versions},"files_deleted":{files_deleted},"manifest_updated":{manifest_updated},"exit_code":0,"halt_reason":null}
+```bash
+uv run {emitEnvelopeHelper} emit --workflow skf-drop-skill --run-dir "{run_dir}" --result-dir "{skills_output_folder}" < "{run_dir}/result-context.json"
 ```
 
-Substitute `{target_versions}` as a JSON array (e.g. `["0.5.0"]`) or the literal string `"all"`; substitute `{files_deleted}` as a JSON array of absolute paths (`[]` in soft-drop mode); `manifest_updated` is the boolean from step 2's context.
+The emitter stamps the UTC time, the run id, the run's warnings and the auto-decisions select.md recorded (`headless_decisions`) into the record, writes it as `{skills_output_folder}/drop-skill-result-{YYYYMMDD-HHmmss}.json`, copies it to `{skills_output_folder}/drop-skill-result-latest.json` (the stable path pipelines read), and prints the `SKF_DROP_SKILL_RESULT_JSON:` line on stdout (field rules in `references/invocation-contract.md`). Bind `{result_json_path}` ← that line's `result_path`: null when the record could not be written, and the line's `warnings` then say why. When `{headless_mode}` is true, display the line verbatim before chaining to step 4. If the helper exits non-zero, correct `result-context.json` from the `message` of its stderr JSON and run it once more; if it fails again, display "The drop result record could not be written: {message}" and go on, since the drop itself is complete.
 
 ### Post-drop hook (optional)
 
-If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`), invoke it once the result contract above is finalized:
+If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`) and `{result_json_path}` is not null, invoke it once the emitter has written the record:
 
 ```bash
 {onCompleteCommand} --result-path={result_json_path}
 ```
 
-where `{result_json_path}` is the per-run record written above (`{skills_output_folder}/drop-skill-result-{YYYYMMDD-HHmmss}.json`). Log success or failure to `workflow_warnings[]` — never fail the workflow on a hook error; the drop has already completed and may be irreversible. When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely.
+When it exits non-zero, display "on_complete hook failed (exit {code}): {its first stderr line}" as a line of its own (after the envelope line when `{headless_mode}` is true), and never fail the workflow on a hook error: the drop has already completed and may be irreversible. When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely.
+
+Whether or not a hook ran, then delete the run folder, whose payload the emitter has read: `rm -rf "{run_dir}"`.
 
 ### 3. Chain to Health Check