bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-create-stack-skill/references/report.md

@@ -25,68 +25,17 @@ Display the final summary of the forged stack skill with confidence distribution
 
 ## MANDATORY SEQUENCE
 
-### 1. Display Stack Forged Banner
+### 1. Report the Forge Result
 
-"**Stack forged: {project_name}-stack — {lib_count} libraries, {integration_count} integration patterns**
+Surface the forge result to the console, leading with the win:
 
-Forge tier: **{tier}**"
+- **Headline:** stack `{project_name}-stack` — `{lib_count}` libraries, `{integration_count}` integration patterns, forge tier `{tier}`.
+- **Confidence distribution:** the T1 / T1-low / T2 counts (T1 = AST-verified structural extraction, T1-low = source-reading inference, T2 = QMD-enriched temporal context). **In compose-mode**, note the tiers are inherited from the source skills — they reflect the extraction method used when those skills were originally generated, not the current compose run.
+- **Output files:** the `{skill_package}` deliverables (SKILL.md, context-snippet.md with `{token_estimate}` tokens, metadata.json, `references/` per-library files, and `references/integrations/` pair files when integrations exist), the `{forge_version}` workspace (provenance-map.json, evidence-report.md), and the `{skill_group}/active -> {version}` symlink.
+- **Validation:** all checks passed, or `{warning_count}` finding(s) each with its description.
+- **Warnings — only if `workflow_warnings[]` is non-empty:** the accumulated entries rendered as `[{step}/{severity}] {code}: {message}`. `workflow_warnings[]` (defined in SKILL.md's *Workflow state contract*) is the single sink surfacing every warning pushed during the run; if it is empty, omit this section.
 
-### 2. Display Confidence Distribution
-
-"**Confidence distribution:**
-
-| Tier | Count | Description |
-|------|-------|-------------|
-| T1 | {count} | AST-verified structural extraction |
-| T1-low | {count} | Source reading inference |
-| T2 | {count} | QMD-enriched temporal context |
-
-{IF compose_mode:}
-*Note: Confidence tiers above are inherited from source skills — they reflect the extraction method used when those skills were originally generated, not the current compose run.*
-{END IF}"
-
-### 3. Display Output File Summary
-
-"**Output files:**
-
-**Deliverables** (`{skill_package}`):
-- SKILL.md — Integration patterns, library summaries, conventions
-- context-snippet.md — Compressed stack index ({token_estimate} tokens)
-- metadata.json — Skill metadata and library registry
-- references/ — {lib_count} per-library reference files
-{If integrations:} - references/integrations/ — {pair_count} integration pair files
-
-**Workspace** (`{forge_version}`):
-- provenance-map.json — Extraction source tracking
-- evidence-report.md — Evidence and confidence breakdown
-
-**Symlink:** `{skill_group}/active` -> `{version}`"
-
-### 4. Display Validation Summary
-
-**If validation passed with no findings:**
-
-"**Validation:** All checks passed"
-
-**If validation had findings:**
-
-"**Validation:** {warning_count} warning(s) found
-{For each finding:}
-- ⚠ {description}"
-
-### 5. Display Warnings (Conditional)
-
-Read from the `workflow_warnings[]` accumulator defined in the Workflow Rules of `SKILL.md` (M4). Every step that emitted a warning during this run pushed a structured entry there — this section is the single sink that surfaces them.
-
-**Only display if `workflow_warnings[]` is non-empty:**
-
-"**Warnings:**
-{For each entry in workflow_warnings[]:}
-- [{step}/{severity}] {code}: {message}"
-
-**If `workflow_warnings[]` is empty:** Skip this section entirely.
-
-### 6. Recommend Next Workflows
+### 2. Recommend Next Workflows
 
 "**Next steps:**
 - **[TS] test-skill** — Validate the stack skill against its own assertions
@@ -94,7 +43,7 @@ Read from the `workflow_warnings[]` accumulator defined in the Workflow Rules of
 
 - **[VS] verify-stack** — Validate the stack's integration feasibility against your architecture document{IF compose_mode:} (re-run to confirm feasibility after any architecture changes from **[RA] refine-architecture**){END IF}"
 
-### 6b. Result Contract
+### 2b. Result Contract
 
 Write the result contract per `shared/references/output-contract-schema.md` using the shared atomic writer. Two artifacts — both written via `skf-atomic-write.py write`:
 
@@ -122,7 +71,23 @@ Include `SKILL.md`, `context-snippet.md`, and `metadata.json` paths in `outputs`
 
 If either atomic write fails, log the error, leave any prior `-latest.json` untouched, and continue — the report is advisory and should not block the health-check chain.
 
-### 7. Chain to Health Check
+**Headless success envelope.** When `{headless_mode}` is true, emit the single-line result envelope on **stdout** (the success counterpart to the error envelopes every HARD HALT emits on stderr) before chaining to step 10. `skill_package` is the absolute path to the committed package; `stack_libraries` is the included library names:
+
+```
+SKF_STACK_RESULT_JSON: {"status":"success","skill_package":"{skill_package}","skill_name":"{project_name}-stack","stack_libraries":["<lib>", "..."],"mode":"{code|compose}","exit_code":0,"halt_reason":null}
+```
+
+### 2c. Post-Completion Hook (optional)
+
+If `{onCompleteCommand}` (resolved at SKILL.md On Activation §3 from `workflow.on_complete`) is non-empty, invoke it now — after the result contract (§2b) is written, before chaining to health-check:
+
+```bash
+{onCompleteCommand}
+```
+
+Run it with a bounded timeout (default 60s). On success, continue. On non-zero exit, timeout, or any failure, append the reason to `workflow_warnings[]` (e.g. `on_complete — failed (exit {N}): {stderr_first_line}`) and continue. **The hook must never fail the workflow** — it is integration glue (catalog registration, downstream pipeline notify) orthogonal to the forged stack. When `{onCompleteCommand}` is empty (bundled default), skip this section entirely.
+
+### 3. Chain to Health Check
 
-ONLY WHEN the forge banner, confidence distribution, output file summary, validation summary, warnings (if any), next-workflow recommendations, and result contract have all been handled will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the report reads as final.
+After the report sections above are handled, load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the report reads as final.
 

package/src/skf-create-stack-skill/references/validate.md

@@ -1,6 +1,8 @@
 ---
 nextStepFile: 'report.md'
-stackSkillTemplate: 'assets/stack-skill-template.md'
+outputValidatorProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-output.py'
+  - '{project-root}/src/shared/scripts/skf-validate-output.py'
 ---
 
 <!-- Config: communicate in {communication_language}. Artifact text in {document_output_language}. -->
@@ -20,12 +22,25 @@ Validate all written output files against their expected structure and verify co
 
 ### 1. Verify File Existence
 
-Check that all expected files exist from written_files[]:
+Run the shared deterministic output validator once against the committed package — it checks the three core deliverable files' existence, SKILL.md frontmatter, and context-snippet format/token in a single call, so this step consumes its JSON rather than re-deriving those by hand. Resolve `{outputValidator}` from `{outputValidatorProbeOrder}` (first existing path wins). If neither candidate exists, log a WARNING (`"output validator unavailable — skf-validate-output.py missing"`) and fall back to the manual file/frontmatter/snippet checks below.
+
+```bash
+python3 {outputValidator} {skill_package} --generated-by create-stack-skill --skill-type stack
+```
+
+Consume from its JSON:
+
+- `files_found` — existence of `SKILL.md` / `context-snippet.md` / `metadata.json` (the three core deliverable rows below).
+- `validation.skill_md.frontmatter` — feeds the frontmatter check in §3 (manual-fallback path).
+- `validation.context_snippet.issues` — feeds §8.
+- `validation.stack_counts` — the stack count-equalities, derived deterministically from disk + metadata by the `--skill-type stack` pass: `issues[]` (each `{severity, field, message}`, one per mismatch of `library_count` / `integration_count` / `confidence_distribution`; empty when all agree) and `observed` (`library_count_meta`, `ref_file_count`, `integration_count_meta`, `pair_file_count`, `confidence_sum`). Feeds the count rows in §5 and the confidence-sum row in §7 — do not re-count files or re-sum the distribution by hand.
+
+**Under `--skill-type stack`, `validation.skill_md.body` and `validation.metadata` are emitted as `{"skipped": ...}` markers** — the *individual-skill* schema (which looks for `## Overview` / `Description` / `Key Exports` / `Usage` sections and a `source_repo` field) does not apply to a stack package, so the validator skips those passes and runs `validation.stack_counts` instead. Stack-shaped body structure and the remaining (non-count) metadata fields are checked in §4 / §5.
+
+Then confirm the remaining files the validator does not cover:
 
 **Deliverables** (`{skill_package}`):
-- [ ] SKILL.md
-- [ ] context-snippet.md
-- [ ] metadata.json
+- [ ] SKILL.md · context-snippet.md · metadata.json — from `files_found` above
 - [ ] references/ directory with per-library files
 - [ ] references/integrations/ directory with pair files (if integrations detected)
 
@@ -36,7 +51,7 @@ Check that all expected files exist from written_files[]:
 **Symlink:**
 - [ ] `{skill_group}/active` exists and resolves to `{version}`
 
-Record any missing files as **ERROR** findings.
+Record any missing files (from `files_found` or the manual rows) as **ERROR** findings.
 
 ### 2. Check Tool Availability
 
@@ -57,21 +72,15 @@ timeout 10s npx --no-install skill-check -h
 
 This validates frontmatter, description, body limits, links, formatting — and auto-fixes deterministic issues. Parse JSON for `scores[].score` (match the entry by `relativePath`/`skillId`; falls back to a top-level `qualityScore` on older skill-check builds), `diagnostics[]`, `fixed[]`.
 
-**Post-fix provenance drift guard (S15):** If `fixed[]` is non-empty, `skill-check --fix` has modified `SKILL.md` after step 7 wrote it. The safe default for v1.0 is to emit a **WARNING** finding listing each auto-fix (`"skill-check --fix modified SKILL.md: {fix_description} — metadata.json hashes/provenance may be out of date"`). Do NOT silently accept the fixes without surfacing the drift. If the caller wants authoritative metadata, they should re-run the workflow.
+**Post-fix provenance drift guard (S15):** If `fixed[]` is non-empty, `skill-check --fix` has modified `SKILL.md` after step 7 wrote it — so the `metadata.json` hashes/provenance recorded against the pre-fix body may now be stale. Emit a **WARNING** finding listing each auto-fix (`"skill-check --fix modified SKILL.md: {fix_description} — metadata.json hashes/provenance may be out of date"`) rather than silently accepting the fixes, so the drift is surfaced. If the caller wants authoritative metadata, they should re-run the workflow.
 
-**If `body.max_lines` reported**, prefer selective split: extract only the largest Tier 2 section(s) to `references/`, keeping Tier 1 content inline (inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval). For a stack capstone the canonical split is the catalog (`Library Reference Index` + `Per-Library Summaries`) → `references/stack-catalog.md`, leaving an inline pointer (see `{stackSkillTemplate}` "Sizing Guidance"). This is the **intended** large-stack layout, not a violation: §4 below accepts the pointer form, so clearing the skill-check body ERROR this way does not also trip the structure check. Fall back to `npx skill-check split-body <skill-dir> --write` if not feasible. Verify any in-SKILL.md anchor links (e.g. to the catalog/pointer or other moved sections) still resolve after the split. Then re-validate.
+**If `body.max_lines` reported**, prefer selective split: extract only the largest Tier 2 section(s) to `references/`, keeping Tier 1 content inline (inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval). For a stack capstone the canonical split is the catalog (`Library Reference Index` + `Per-Library Summaries`) → `references/stack-catalog.md`, leaving an inline pointer (see `{stackSkillTemplatePath}` "Sizing Guidance"). This is the **intended** large-stack layout, not a violation: §4 below accepts the pointer form, so clearing the skill-check body ERROR this way does not also trip the structure check. Fall back to `npx skill-check split-body <skill-dir> --write` if not feasible. Verify any in-SKILL.md anchor links (e.g. to the catalog/pointer or other moved sections) still resolve after the split. Then re-validate.
 
-**If unavailable**, perform manual frontmatter check:
-- [ ] Frontmatter present with `---` delimiters
-- [ ] `name` — present, non-empty, lowercase alphanumeric + hyphens, 1-64 chars, matches `{project_name}-stack`
-- [ ] `description` — present, non-empty, 1-1024 characters
-- [ ] No unknown fields — only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` permitted
-
-Record frontmatter violations as **WARNING** findings. Invalid frontmatter will fail `npx skills add` and `npx skill-check check`.
+**If unavailable**, do not hand-walk the frontmatter — use `validation.skill_md.frontmatter` from the §1 output-validator run, which checks delimiters, `name` format + directory match (`{project_name}-stack`), `description` presence/length, and unknown fields against the agentskills.io allow-set. Record each reported issue at its severity as a **WARNING** finding. (If the output validator was *also* unavailable in §1, fall back to the manual checklist: `---` delimiters; `name` lowercase-alphanumeric-plus-hyphens 1-64 chars matching `{project_name}-stack`; `description` present and 1-1024 chars; only `name`/`description`/`license`/`compatibility`/`metadata`/`allowed-tools` permitted.) Invalid frontmatter will fail `npx skills add` and `npx skill-check check`.
 
 ### 4. Validate SKILL.md Body Structure
 
-Load `{stackSkillTemplate}` and verify SKILL.md contains expected sections:
+Load `{stackSkillTemplatePath}` and verify SKILL.md contains expected sections:
 
 - [ ] Header with project name, library count, integration count, forge tier
 - [ ] Integration Patterns section (before per-library summaries)
@@ -93,11 +102,12 @@ Parse metadata.json and verify required fields:
 - [ ] `version` and `generation_date` present
 - [ ] `forge_tier` is present and matches the forge tier from step 01 (`Quick|Forge|Forge+|Deep`)
 - [ ] `confidence_tier` is present and is exactly one of `T1|T1-low|T2|T3` — the dominant T-code computed from `confidence_distribution` (pick the tier with the highest count; ties resolve to the weaker tier: T1-low > T1, T2 > T1-low, T3 > T2 for tie-break so the reported tier never overstates confidence)
-- [ ] `library_count` matches actual reference files; `integration_count` matches pair files
 - [ ] `libraries` array present and non-empty
 - [ ] `confidence_distribution` object present with `t1`, `t1_low`, `t2`, `t3` keys (lowercase, matching template definition)
 
-Record mismatches as **WARNING** findings.
+**Count equalities (library / integration)** — do NOT re-count files here; take them from `validation.stack_counts` in the §1 output-validator run (invoked with `--skill-type stack`), which derived them deterministically from disk. The `library_count` vs per-library reference files and `integration_count` vs integration pair files checks surface as `field: "library_count"` / `field: "integration_count"` entries in `validation.stack_counts.issues[]` (absent when they agree); echo the exact numbers from `validation.stack_counts.observed` (`library_count_meta` / `ref_file_count`, `integration_count_meta` / `pair_file_count`). The `confidence_distribution`-sum equality is covered in §7.
+
+Record each `validation.stack_counts.issues[]` count entry (`library_count` / `integration_count`) and any other mismatch above as **WARNING** findings.
 
 ### 6. Validate Reference File Completeness
 
@@ -113,17 +123,17 @@ Scan all output files for confidence tier coverage:
 
 - [ ] SKILL.md: each per-library summary and integration pair entry has a confidence label
 - [ ] Reference files: each has a confidence label in its header
-- [ ] metadata.json: confidence_distribution sums match library_count
+- [ ] metadata.json: `confidence_distribution` sums to `library_count` — take this from the §1 output-validator run (`--skill-type stack`): the `field: "confidence_distribution"` entry in `validation.stack_counts.issues[]` is present only on mismatch, with `validation.stack_counts.observed.confidence_sum` vs `library_count_meta` for the exact numbers. Do not re-sum the distribution by hand.
 
-Record missing tier labels as **WARNING** findings.
+Record missing tier labels and any `validation.stack_counts` `confidence_distribution` issue as **WARNING** findings.
 
 ### 8. Validate context-snippet.md
 
-Verify context-snippet.md follows Vercel-aligned indexed format:
-- [ ] First line matches: `[{project}-stack v{version}]|root: {prefix}{project}-stack/` where prefix is `skills/` (draft form) or any IDE skill root (`.{dir}/skills/`)
-- [ ] Second line starts with `|IMPORTANT:`
+Take the first-line format, `|IMPORTANT:` second-line, and token-estimate checks from `validation.context_snippet.issues` returned by the §1 output-validator run — it performs the line-1 `[name vVersion]|root:` pattern match, the line-2 check, and the `len(content)//4` token estimate deterministically, so this step does not recompute them. Record each reported issue as a **WARNING** finding.
+
+Then verify the two stack-specific rows the generic validator does not cover:
 - [ ] Stack and integrations lines present
-- [ ] Approximate token count is ~80-120 tokens (use the `ceil(char_count / 4)` heuristic from step 7 §5; tolerate up to ~150 if the overflow strategy was applied and a workflow_warning was emitted)
+- [ ] Token estimate lands near the ~80-120 design target from step 7 §5 (the validator flags only its wider <40 / >200 bounds; an ~80-150 snippet with an overflow-strategy `workflow_warning` is expected, not a defect)
 
 Record format violations as **WARNING** findings.
 
@@ -137,13 +147,7 @@ Record security findings as advisory **WARNING** findings — they do not block
 
 ### 10. Display Validation Results
 
-**If all checks pass:**
-
-"**Validation complete — all checks passed.** Files: {count}/{count} present. SKILL.md structure valid. metadata.json fields verified. {lib_count} library + {pair_count} integration files verified. Confidence tiers: complete coverage. **Proceeding to summary report...**"
-
-**If warnings found:**
-
-"**Validation complete with {warning_count} finding(s).** Findings: {list each: severity, description, file_path}. Files: {present}/{expected} present. Warnings: {count}. Errors: {count}. {If errors: Note missing files may indicate a write failure in step 07.} **Proceeding to summary report...**"
+Report the validation outcome. If all checks passed, state so and name what was verified: file presence (`{count}/{count}`), SKILL.md structure, metadata.json fields, the `{lib_count}` library + `{pair_count}` integration reference files, and complete confidence-tier coverage. If there were findings, report the `{warning_count}` finding(s) — each with severity, description, and file path — plus files present/expected and warning/error counts; when errors include missing files, note this may indicate a write failure in step 07.
 
 ### 11. Auto-Proceed to Next Step
 

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

@@ -7,7 +7,7 @@ description: Drop a specific skill version or an entire skill — soft (deprecat
 
 ## Overview
 
-Drops a specific skill version or an entire skill, either as a soft deprecation (manifest-only, files retained) or a hard purge (files deleted). Ensures platform context files are rebuilt to exclude dropped versions. Every destructive action requires explicit user confirmation — nothing is deleted silently. The export manifest is the source of truth; the filesystem is updated to match.
+Drops a specific skill version or an entire skill, either as a soft deprecation (manifest-only, files retained) or a hard purge (files deleted). Ensures platform context files are rebuilt to exclude dropped versions. In interactive mode every destructive action requires explicit user confirmation — nothing is deleted silently; headless runs auto-resolve the gates with their default action and log each auto-decision. The export manifest is the source of truth; the filesystem is updated to match.
 
 ## Conventions
 
@@ -21,13 +21,13 @@ Drops a specific skill version or an entire skill, either as a soft deprecation
 
 ## Role
 
-You are Ferris in Management mode — a destructive operation specialist who enforces safety guards. You treat every drop as potentially irreversible and require explicit confirmation before touching the manifest or filesystem. You protect the active version, keep the export manifest consistent with on-disk state, and ensure downstream platform context files are rebuilt.
+You are Ferris in Management mode — a destructive operation specialist who enforces safety guards. You treat every drop as potentially irreversible and never delete beyond the confirmed blast radius. You protect the active version, keep the export manifest consistent with on-disk state, and ensure downstream platform context files are rebuilt.
 
 ## Workflow Rules
 
 These rules apply to every step in this workflow:
 
-- Never delete files without explicit user confirmation in purge mode
+- Never delete files in purge mode without clearing the §10 confirmation gate (auto-resolved with its default in headless)
 - Never drop an active version when other non-deprecated versions exist — enforce the active version guard
 - Only load one step file at a time — never preload future steps
 - If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
@@ -52,31 +52,25 @@ These rules apply to every step in this workflow:
 | **Flags** | `--headless` / `-H` (auto-resolve all gates); `--dry-run` (run selection + display the §10 confirmation block, then exit with `status="dry-run"` — no manifest mutation, no file deletion). Useful for "show me what this would touch before I commit." |
 | **Gates** | step 1: Input Gate [use args], Confirm Gate [Y] |
 | **Outputs** | Updated manifest, rebuilt context files, (purge: deleted directories), `drop-skill-result-{timestamp}.json` and `drop-skill-result-latest.json` |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. When `forbid_purge_in_headless` is `"true"` in `customize.toml` AND `drop_mode = "purge"`, On-Activation §4 HALTs with exit code 6 (`halt_reason: "headless-purge-forbidden"`) before any work begins. |
+| **Headless** | Gates auto-resolve with their default action (see Workflow Rules). When `forbid_purge_in_headless` is `"true"` in `customize.toml` AND the effective drop mode is `"purge"` (defined in On-Activation §4 — explicit `mode=purge` or `default_mode` purge), §4 HALTs with exit code 6 (`halt_reason: "headless-purge-forbidden"`) before any work begins. |
 | **Exit codes** | See "Exit Codes" below |
 
 ## Exit Codes
 
-Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
+Every hard HALT exits with a stable code so headless automators branch on the failure class without grepping message text. The `Raised by` column names the HALT class per code; the authoritative per-site declarations (with exact `halt_reason`) live in the step files.
 
-| Code | Meaning              | Raised by                                                                                    |
-| ---- | -------------------- | -------------------------------------------------------------------------------------------- |
-| 0    | success              | step 4 (terminal)                                                                           |
-| 2    | input-missing / input-invalid | step 1 §4 (headless missing `skill_name` arg) → `input-missing`; non-existent skill / unparseable version → `input-invalid` |
-| 3    | resolution-failure   | step 1 §2 (manifest is malformed JSON); step 1 §3 (no skills found anywhere)               |
-| 4    | write-failure        | On-Activation §3 pre-flight write probe (skills_output_folder unwritable); step 2 §2 (manifest write); step 2 §3 (context-file rewrite); step 2 §4 (directory delete) |
-| 5    | state-conflict       | step 1 §7 (active-version-guard refuses to drop the active version while non-deprecated peers remain) |
-| 6    | user-cancelled       | step 1 §10 confirmation gate `[N]`; any prompt that accepted `cancel`/`exit`/`:q`; On-Activation §4 (`headless-purge-forbidden`) |
+| Code | Meaning              | Raised by (class) |
+| ---- | -------------------- | ----------------- |
+| 0    | success              | step 4 (terminal) |
+| 2    | input-missing / input-invalid | step 1 headless input gates — missing or unmatched `skill_name`, `version`, or `--mode` value (§4 / §6 / §8) |
+| 3    | resolution-failure   | step 1 manifest/skill-list resolution (§2 corrupt manifest, §3 nothing to drop) |
+| 4    | write-failure        | On-Activation write probe; step 2 manifest write / context rebuild / full-purge failure |
+| 5    | state-conflict       | step 1 active-version guard (§7) |
+| 6    | user-cancelled       | any interactive cancel or confirm-gate `[N]`; On-Activation headless-purge guard |
 
 ## Result Contract (Headless)
 
-When `{headless_mode}` is true, step 3 emits a single-line JSON envelope on **stdout** before chaining to step 4, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
-
-```
-SKF_DROP_SKILL_RESULT_JSON: {"status":"success|error|dry-run","skill":"…|null","drop_mode":"…|null","versions_affected":[],"files_deleted":[],"manifest_updated":false,"exit_code":0,"halt_reason":null}
-```
-
-`status` is `"success"` on the terminal happy path, `"dry-run"` when `--dry-run` was set and the workflow exited before §11 stores decisions, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"manifest-corrupt"`, `"nothing-to-drop"`, `"active-version-guard-refused"`, `"headless-purge-forbidden"`, `"manifest-write-failed"`, `"context-rebuild-failed"`, `"delete-failed"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above.
+When `{headless_mode}` is true, step 3 emits a single-line `SKF_DROP_SKILL_RESULT_JSON:` envelope on **stdout**; every HARD HALT emits the same shape on **stderr** with `status: "error"`. The template, `status`/`halt_reason` semantics, `exit_code` (per the Exit Codes table above), and full enum live in `references/headless-contract.md` — the emitting stages load it directly, so an error path never depends on this file.
 
 ## On Activation
 
@@ -103,14 +97,17 @@ SKF_DROP_SKILL_RESULT_JSON: {"status":"success|error|dry-run","skill":"…|null"
 
    If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each scalar.
 
-   Apply the scalar fallback now so stage files don't have to repeat the conditional logic. For each of the four scalars, if the merged value is empty or absent, the bundled default applies:
+   Apply the scalar fallback now so stage files don't have to repeat the conditional logic. For each of the five scalars, if the merged value is empty or absent, the bundled default applies:
 
    - `{defaultMode}` ← `workflow.default_mode` (empty = always prompt; `"deprecate"` or `"purge"` = skip §8 Ask Mode)
    - `{forbidPurgeInHeadless}` ← `workflow.forbid_purge_in_headless` (empty or non-`"true"` = no guard)
    - `{unknownIdeDefaultContextFile}` ← `workflow.unknown_ide_default_context_file` if non-empty, else `AGENTS.md`
    - `{unknownIdeDefaultSkillRoot}` ← `workflow.unknown_ide_default_skill_root` if non-empty, else `.agents/skills/`
+   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty (no-op — step 3 skips the post-drop hook entirely)
+
+   Stash all five as workflow-context variables. Stage files reference them directly — no conditional at the usage site.
 
-   Stash all four as workflow-context variables. Stage files reference them directly — no conditional at the usage site.
+   Also apply the array surfaces: run `workflow.activation_steps_prepend` now, keep `workflow.persistent_facts` as standing context (`file:` entries load their contents), then run `workflow.activation_steps_append` after.
 
 4. **Pre-flight write probe + headless-purge guard.**
 
@@ -124,6 +121,6 @@ SKF_DROP_SKILL_RESULT_JSON: {"status":"success|error|dry-run","skill":"…|null"
 
    On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`). In headless mode, emit the error envelope per **Result Contract (Headless)** with `skill: null` and `drop_mode: null` (neither is resolved yet at activation time).
 
-   Second, enforce the headless-purge guard. If `{headless_mode}` is true AND `{forbidPurgeInHeadless}` is `"true"` AND the parsed `mode` arg is `"purge"`: HALT with exit code 6 and `halt_reason: "headless-purge-forbidden"`, emit the error envelope, and exit immediately. The operator must re-run with `mode=deprecate` or set `forbid_purge_in_headless = ""` (or omit the override entirely) to proceed.
+   Second, enforce the headless-purge guard. First compute the **effective drop mode**: it is `"purge"` when the parsed `mode` arg is `"purge"`, OR when no `mode` arg was passed AND `{defaultMode}` (resolved in §3) is `"purge"` — a purge reached via `default_mode` is still an unattended irreversible purge and must be caught here, not only an explicit `--mode purge`. If `{headless_mode}` is true AND `{forbidPurgeInHeadless}` is `"true"` AND the effective drop mode is `"purge"`: HALT with exit code 6 and `halt_reason: "headless-purge-forbidden"`, emit the error envelope, and exit immediately. The operator must re-run with an explicit `mode=deprecate` (an explicit arg overrides `default_mode`) or set `forbid_purge_in_headless = ""` (or omit the override entirely) to proceed.
 
 5. Load, read the full file, and then execute `references/select.md` to begin the workflow.

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

@@ -1,6 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-drop-skill.
+# Team overrides:     {project-root}/_bmad/custom/skf-drop-skill.toml
+# Personal overrides: {project-root}/_bmad/custom/skf-drop-skill.user.toml
 
 [workflow]
 
@@ -34,6 +36,14 @@ persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
 
+# Optional post-drop hook. When non-empty, invoked with
+# `--result-path=<path>` after the drop-skill result JSON is finalized
+# (references/report.md). Failures are logged to workflow_warnings[] but
+# never fail the workflow — useful for audit-log emit, a notifier, or a
+# ticket-tracker integration after an irreversible purge.
+
+on_complete = ""
+
 # --- Optional safety + default scalars ---
 #
 # Default drop mode. Empty string = always prompt the user at §8 Ask Mode.

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

@@ -18,6 +18,23 @@ manifestOpsProbeOrder:
 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.
+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.
+dirSizesHelper: 'scripts/dir-sizes.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -43,6 +60,8 @@ Read `{versionPathsKnowledge}` again and confirm the templates and management op
 
 Also read `{managedSectionLogic}` for the format template, the four-case logic, and the skill index rebuild rules that will be reused in section 3.
 
+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.
+
 ### 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.
@@ -75,7 +94,7 @@ Set context flag `manifest_updated = true`.
 
 - 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 SKILL.md "Result Contract (Headless)" with `halt_reason: "manifest-write-failed"` and exit code 4.
+- 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.
 
 ### 3. Rebuild Context Files
 
@@ -84,9 +103,9 @@ Load the `ides` list from `config.yaml`. The installer writes IDE identifiers
 **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 AGENTS.md / `.agents/skills/` and emit a warning: "Unknown IDE '{value}' in config.yaml — defaulting to AGENTS.md"
+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: "AGENTS.md", skill_root: ".agents/skills/"}]` and emit a note: "No IDEs configured in config.yaml — defaulting to AGENTS.md"
+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}"
 
 Store the result as `target_context_files` for this section.
 
@@ -152,37 +171,62 @@ Report: "**Rebuilt managed sections in:** {list of updated files}. {if any faile
 
 ### 4. Delete Files (Purge Mode Only)
 
-**If `drop_mode != "purge"`**, skip this section entirely. Set `files_deleted = []` and `disk_freed = "N/A (soft drop)"`, then jump to section 5.
+**If `drop_mode != "purge"`**, skip this section entirely. Set `files_deleted = []`, `disk_freed = "N/A (soft drop)"`, `delete_failures = []`, and `purge_status = "success"`, then jump to section 5.
 
 **If `drop_mode == "purge"`:**
 
-1. Initialize `files_deleted = []` and `bytes_freed = 0`.
+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:
+
+   ```bash
+   uv run {dirSizesHelper} sizes {each path in affected_directories, space-separated}
+   ```
 
-2. For each directory path in `affected_directories`:
+   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.
+
+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. Compute the directory size in bytes before deletion (recursive sum)
-   d. Delete the directory recursively
-   e. Verify deletion succeeded (the path no longer exists)
-   f. Append the path to `files_deleted` and add its byte size to `bytes_freed`
+   c. Delete the directory recursively
+   d. Verify deletion succeeded (the path no longer exists)
+   e. Append the path to `files_deleted`
 
-3. **Version-level purge, single version:**
+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:
-     - If other versions remain in the manifest for `{target_skill}`, repoint `active` to the manifest's current `active_version` (skipping deprecated)
-     - If no non-deprecated versions remain, remove the `active` symlink (reachable only when dropping the sole surviving version, which in step 1 was permitted because no other non-deprecated versions existed)
-
-4. **Skill-level purge:**
+   - 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:
+       ```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
 
-5. Convert `bytes_freed` to a human-readable string for the final report (e.g. `"4.2 MB"`). Store as `disk_freed`.
+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:
+
+   ```bash
+   uv run {dirSizesHelper} humanize {path_bytes[p] for each p in files_deleted, space-separated}
+   ```
+
+   Store `result.total_human` as `disk_freed` (e.g. `"4.2 MB"`; `"0 B"` when nothing was deleted).
 
-**On deletion error:**
+**On deletion error (per path):**
 
-- Record which path failed and the error message
-- Continue attempting the remaining paths — partial purge is still better than no purge
+- 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.
+
 ### 5. Verify Final State
 
 Run these verification checks:
@@ -203,6 +247,8 @@ Store the following for step 3:
 
 - `files_deleted` — list of directory paths actually deleted (purge mode) or `[]` (soft drop)
 - `disk_freed` — human-readable size (purge mode) or `"N/A (soft drop)"`
+- `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)
@@ -210,20 +256,5 @@ Store the following for step 3:
 
 ### 7. Load Next Step
 
-Load, read the full file, and then execute `{nextStepFile}`.
-
-## Error Handling Summary
-
-If any stage fails, record which stage failed and provide recovery guidance in the final report:
-
-| Failed Stage | Recovery Guidance |
-|--------------|-------------------|
-| Manifest update | "Manifest is in pre-drop state. Re-run the workflow once the underlying I/O issue is resolved. No files were deleted." |
-| Context file rebuild | "Manifest is already updated. Re-run `[EX] Export Skill` against any still-valid skill to regenerate the affected managed sections, or rerun the drop workflow." |
-| File deletion (purge) | "Manifest and context files are consistent. Remaining directories listed in the report can be deleted manually: `rm -rf {path}`." |
-| Verification | "Execution completed but post-write checks found drift. See the report for specific paths requiring manual review." |
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN all execution stages have been attempted (manifest update, context rebuild, file deletion in purge mode, verification) and results have been stored in context, will you then load and read fully `{nextStepFile}` to generate the final report.
+The report in `{nextStepFile}` renders from the results stored in §6, so chain to it only after every execution stage above has been attempted and its outcome stored. Load, read the full file, and then execute it.
 

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

@@ -0,0 +1,18 @@
+# Headless Result Envelope
+
+The single-line JSON contract every headless run of skf-drop-skill emits. It stands alone: the stages that emit it load this file directly, so an error path never depends on any other file staying in context under compaction.
+
+When `{headless_mode}` is true, step 3 emits this envelope on **stdout** before chaining to step 4; every HARD HALT emits the same shape on **stderr** with `status: "error"`:
+
+```
+SKF_DROP_SKILL_RESULT_JSON: {"status":"success|error|dry-run","skill":"…|null","drop_mode":"…|null","versions_affected":[],"files_deleted":[],"manifest_updated":false,"exit_code":0,"halt_reason":null}
+```
+
+Field rules:
+
+- `status` — `"success"` on the terminal happy path, `"dry-run"` when `--dry-run` was set and the workflow exited at the confirmation gate before any mutation, `"error"` on any HALT.
+- `halt_reason` — `null` on success/dry-run; otherwise one of `"input-missing"`, `"input-invalid"`, `"manifest-corrupt"`, `"nothing-to-drop"`, `"active-version-guard-refused"`, `"headless-purge-forbidden"`, `"manifest-write-failed"`, `"context-rebuild-failed"`, `"delete-failed"`, `"write-failed"`, `"user-cancelled"`.
+- `exit_code` — the stable numeric code the emitting HALT specifies (`0` on success/dry-run).
+- `skill` / `drop_mode` / `versions_affected` / `files_deleted` / `manifest_updated` — the discriminating values the emit site supplies; any key not yet resolved at that point takes the default shown in the template (`null`, `[]`, or `false`).
+
+Each emit site supplies its own `exit_code`, `halt_reason`, and whichever discriminating fields are known at that point; all other keys default as shown.

package/src/skf-drop-skill/references/health-check.md

@@ -9,16 +9,4 @@ nextStepFile: 'shared/health-check.md'
 
 # Step 4: Workflow Health Check
 
-## STEP GOAL:
-
-Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of drop-skill — after the shared health check completes, the workflow is fully done.
-
-## Rules
-
-- No user-facing reports, file writes, or result contracts in this step — those belong in step 3
-- Delegate directly to `{nextStepFile}` with no additional commentary
-- Do not attempt any other action between loading this step and executing `{nextStepFile}`
-
-## MANDATORY SEQUENCE
-
-Load `{nextStepFile}`, read it fully, then execute it.
+This is the terminal step of drop-skill. Load `{nextStepFile}`, read it fully, then execute it — do nothing else here (no user-facing reports, file writes, or result contracts; those were step 3). After the shared health check completes, the workflow is done.