bmad-module-skill-forge 1.4.0 → 1.5.0

package/src/skf-create-stack-skill/{steps-c/step-07-generate-output.md → references/generate-output.md}

@@ -1,6 +1,7 @@
 ---
-nextStepFile: './step-08-validate.md'
+nextStepFile: 'validate.md'
 stackSkillTemplate: 'assets/stack-skill-template.md'
+provenanceMapSchemaPath: 'assets/provenance-map-schema.md'
 # Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
 # path wins. HALT if neither resolves — stage/commit/flip-link/write below
@@ -10,6 +11,8 @@ atomicWriteProbeOrder:
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
+<!-- Config: communicate in {communication_language}. Artifact text in {document_output_language}. -->
+
 # Step 7: Generate Output Files
 
 ## STEP GOAL:
@@ -24,8 +27,6 @@ Write all deliverable and workspace artifact files to their target directories.
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Resolve Paths and Stage Target Directory
 
 Resolve `{version}` from the primary library version or default to `1.0.0` (see S11 in "Primary library" note below). The final artifact paths are:
@@ -40,7 +41,7 @@ Resolve `{version}` from the primary library version or default to `1.0.0` (see
 
 Where the skill name is `{project_name}-stack` and `{version}` is the semver version (with build metadata stripped per `knowledge/version-paths.md`).
 
-**Primary library definition (S11):** In code-mode, the primary library is the dependency with the highest import count from step-03; its `version` (from the manifest) becomes `{primary_library_version}`. In compose-mode, use the highest semver across constituent skill `metadata.json` files. If neither is available, fall back to `1.0.0`.
+**Primary library definition (S11):** In code-mode, the primary library is the dependency with the highest import count from step 3; its `version` (from the manifest) becomes `{primary_library_version}`. In compose-mode, use the highest semver across constituent skill `metadata.json` files. If neither is available, fall back to `1.0.0`.
 
 **Pre-flight: group-dir type check (S3):** If `{skills_output_folder}/{project_name}-stack/` already exists, probe `{skills_output_folder}/{project_name}-stack/active/{project_name}-stack/metadata.json`. If that metadata exists and `skill_type != "stack"`, HALT with:
 
@@ -74,7 +75,7 @@ mkdir -p {forge_version}
 python3 {atomicWriteHelper} commit-dir --rollback --target {skill_package}
 ```
 
-Then abort with a structured error contract (see B7): purge any `{forge_version}/*-tmp` staging artifacts, emit `{"status":"error","skill":"skf-create-stack-skill","stage":"step-07","reason":"<message>"}` on stderr, and halt the workflow.
+Then abort with a structured error contract (see B7): purge any `{forge_version}/*-tmp` staging artifacts, emit `{"status":"error","skill":"skf-create-stack-skill","stage":"step 7","reason":"<message>"}` on stderr, and halt the workflow.
 
 ### 2. Stage SKILL.md
 
@@ -136,7 +137,7 @@ Write `{skill_staging}/metadata.json`:
 Populate all fields from the metadata.json schema defined in `{stackSkillTemplate}`.
 
 **Tier fields:**
-- `forge_tier` — the run tier (Quick/Forge/Forge+/Deep) resolved in step-01.
+- `forge_tier` — the run tier (Quick/Forge/Forge+/Deep) resolved in step 1.
 - `confidence_tier` — the dominant T-code from `confidence_distribution`. Pick the tier with the highest count; resolve ties toward the weaker tier (T1-low > T1, T2 > T1-low, T3 > T2) so the reported value never overstates confidence. When `confidence_distribution` is empty (no libraries extracted), emit `"T1-low"` as the conservative default.
 
 ```json
@@ -191,87 +192,12 @@ If any workspace write fails, invoke the rollback contract from §1.
 
 **provenance-map.json:**
 
-**In code-mode:**
-```json
-{
-  "provenance_version": "2.0",
-  "skill_name": "{project_name}-stack",
-  "skill_type": "stack",
-  "source_repo": ["{repo_url_1}", "{repo_url_2}"],
-  "source_commit": {"{repo_1}": "{hash_1}", "{repo_2}": "{hash_2}"},
-  "generated_at": "{ISO-8601}",
-  "entries": [
-    {
-      "export_name": "{name}",
-      "export_type": "{type}",
-      "source_library": "{library-name}",
-      "params": [],
-      "return_type": "{type}",
-      "source_file": "{file}",
-      "source_line": 0,
-      "confidence": "T1|T1-low|T2",
-      "extraction_method": "ast_bridge|source_reading|qmd_bridge",
-      "signature_source": "T1|T2|T3"
-    }
-  ],
-  "integrations": [
-    {
-      "libraries": ["{libA}", "{libB}"],
-      "pattern_type": "{type}",
-      "detection_method": "co-import grep",
-      "co_import_files": [{"file": "{path}", "line": 0}],
-      "confidence": "T1|T2"
-    }
-  ]
-}
-```
+Use the schema from `{provenanceMapSchemaPath}` — see that asset for the canonical templates and field definitions of both variants:
 
-**In compose-mode:**
-```json
-{
-  "provenance_version": "2.0",
-  "skill_name": "{project_name}-stack",
-  "skill_type": "stack",
-  "source_repo": null,
-  "source_commit": null,
-  "source_ref": null,
-  "generated_at": "{ISO-8601}",
-  "entries": [
-    {
-      "export_name": "{name}",
-      "export_type": "{type}",
-      "source_library": "{library-name}",
-      "params": [],
-      "return_type": "{type}",
-      "source_file": "{from constituent skill}",
-      "source_line": 0,
-      "confidence": "T1|T1-low|T2",
-      "extraction_method": "compose-from-skill",
-      "signature_source": "T1|T2|T3"
-    }
-  ],
-  "integrations": [
-    {
-      "libraries": ["{libA}", "{libB}"],
-      "pattern_type": "{type}",
-      "detection_method": "architecture_co_mention|inferred_from_shared_domain",
-      "co_import_files": [],
-      "confidence": "T2|T3"
-    }
-  ],
-  "constituents": [
-    {
-      "skill_name": "{constituent-skill-name}",
-      "skill_path": "skills/{skill-dir}/",
-      "version": "{version from constituent metadata.json}",
-      "composed_at": "{ISO-8601}",
-      "metadata_hash": "sha256:{hash of constituent metadata.json}"
-    }
-  ]
-}
-```
+- **In code-mode:** use the code-mode variant (`source_repo` / `source_commit` populated; `extraction_method` ∈ `ast_bridge|source_reading|qmd_bridge`; `detection_method = "co-import grep"`).
+- **In compose-mode:** use the compose-mode variant (source-anchor fields `null`; `extraction_method = "compose-from-skill"`; `detection_method ∈ "architecture_co_mention|inferred_from_shared_domain"`; includes the additional `constituents[]` array for drift detection).
 
-> **Note:** Per-export entries use the same schema as single skills (see `skill-sections.md`), with `source_library` identifying the originating library. In compose-mode, `constituents[]` enables audit to detect constituent drift via metadata hash comparison. **Use the `metadata_hash` value already stored in workflow state during step-02 (S13) — do NOT re-read and re-hash at step-07 time. The stored hash captures the state as it was at manifest-detection time, which is the correct provenance anchor.**
+**Use the `metadata_hash` value already stored in workflow state during step 2 (S13) — do NOT re-read and re-hash at step 7 time. The stored hash captures the state as it was at manifest-detection time, which is the correct provenance anchor.**
 
 **evidence-report.md:**
 - Extraction summary per library

package/src/skf-create-stack-skill/{steps-c/step-10-health-check.md → references/health-check.md}

@@ -1,10 +1,12 @@
 ---
 # `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
+# (`{project-root}/_bmad/skf/` when installed, `src/` during development), NOT relative
 # to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 10: Workflow Health Check
 
 ## STEP GOAL:
@@ -13,7 +15,7 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 
 ## Rules
 
-- No user-facing reports, file writes, or result contracts in this step — those belong in step-09
+- No user-facing reports, file writes, or result contracts in this step — those belong in step 9
 - Delegate directly to `{nextStepFile}` with no additional commentary
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`
 

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

@@ -1,8 +1,10 @@
 ---
-nextStepFile: './step-02-detect-manifests.md'
+nextStepFile: 'detect-manifests.md'
 forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 1: Initialize
 
 ## STEP GOAL:
@@ -15,8 +17,6 @@ Load forge tier configuration, validate prerequisites, and prepare the stack ski
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 0. Validate Project Config
 
 Before anything else, load `{project-root}/_bmad/skf/config.yaml`. If the file is missing OR fails YAML parse OR lacks the required top-level keys (`project_name`, `output_folder`, `skills_output_folder`, `forge_data_folder`, `sidecar_path`), HALT with:
@@ -29,6 +29,72 @@ Before anything else, load `{project-root}/_bmad/skf/config.yaml`. If the file i
 
 STOP — do not proceed.
 
+### 0b. Resume Check
+
+Before any further init work, check for an interrupted prior run.
+
+**Probe path.** Resolve `{resume_skill_name}` as `{project_name}-stack` (the same skill name used at step 7) and probe `{forge_data_folder}/{resume_skill_name}/in-progress.json`. (The file lives at the version-agnostic skill root so it can be found before `{version}` resolution.)
+
+**If no in-progress.json exists:** Continue to §1.
+
+**If in-progress.json exists:** Load and parse it. Read `last_completed_step` and `started_at` (ISO-8601 timestamp). Surface a soft gate:
+
+"**Resume previous run?**
+
+Found a previous in-progress run at `{forge_data_folder}/{resume_skill_name}/in-progress.json` from {started_at}, last completed at step {last_completed_step}.
+
+- **[C] Continue** (recommended) — resume from the next step after {last_completed_step}, restoring saved workflow state.
+- **[F] Fresh** — archive the existing in-progress.json (rename to `in-progress.{timestamp}.json`) and start over from step 1.
+- **[X] Cancel and exit** — leave the in-progress.json untouched and halt.
+
+Select [C/F/X]:"
+
+**Headless default:** `[C]` Continue.
+
+**On [C] Continue:**
+1. Restore workflow context from in-progress.json fields: `last_completed_step`, `workflow_state` (mode, tier, scope), and any accumulator fields (partial extractions, ranked libraries, integration pairs, compile-stack output) that the writing step persisted.
+2. Determine the resume target: the step file that runs immediately after `last_completed_step`.
+3. Jump directly to that step file by loading and executing it (skip the remaining §0b–§5 init substeps for this run).
+
+**On [F] Fresh:**
+1. Compute `{archive_timestamp}` as the current UTC time in `YYYYMMDDTHHMMSSZ` form.
+2. Rename `{forge_data_folder}/{resume_skill_name}/in-progress.json` → `{forge_data_folder}/{resume_skill_name}/in-progress.{archive_timestamp}.json`.
+3. Continue with §1 of this file as if no prior run existed.
+
+**On [X] Cancel and exit:** HARD HALT with exit code 6 (user-cancelled). Do NOT modify the in-progress.json. Emit the result envelope on stderr per the Result Contract in SKILL.md:
+
+```
+SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{resume_skill_name}","stack_libraries":[],"mode":null,"exit_code":6,"halt_reason":"user-cancelled"}
+```
+
+**in-progress.json schema (read side).** This PR wires only the READ side of the resume protocol. The WRITE side — each stage step persisting an updated in-progress.json after it completes — is deferred to a follow-up PR. When write-side wiring lands, each step writes the file via `skf-atomic-write.py write` at the end of its mandatory sequence with this shape:
+
+```json
+{
+  "schema_version": "1.0",
+  "skill_name": "{project_name}-stack",
+  "started_at": "{ISO-8601 of step 1 start}",
+  "updated_at": "{ISO-8601 of most recent step completion}",
+  "last_completed_step": "step-NN",
+  "workflow_state": {
+    "mode": "code|compose",
+    "forge_tier": "Quick|Forge|Forge+|Deep",
+    "headless_mode": false,
+    "scope": {"explicit_deps": [], "scope_overrides": {}, "architecture_doc_path": null}
+  },
+  "accumulators": {
+    "manifests": [],
+    "ranked_libraries": [],
+    "extractions": {},
+    "integration_pairs": [],
+    "compiled_stack": null,
+    "workflow_warnings": []
+  }
+}
+```
+
+Until the write side is wired, in-progress.json will not naturally appear and §0b will fall through to §1 on every run. The resume gate is a no-op until that follow-up lands.
+
 ### 1. Load Forge Tier Configuration
 
 Load `{forgeTierFile}` from the Ferris sidecar.
@@ -60,7 +126,7 @@ Extract:
 **Tier-dependent tools:**
 - **Quick:** gh_bridge (source reading) — graceful degradation to local file reading if unavailable
 - **Forge:** ast_bridge (ast-grep structural analysis) — required for Forge tier
-- **Forge+:** ast_bridge + ccc_bridge (ccc semantic co-import augmentation) — ccc available for step-05
+- **Forge+:** ast_bridge + ccc_bridge (ccc semantic co-import augmentation) — ccc available for step 5
 - **Deep:** qmd_bridge (QMD temporal enrichment) — required for Deep tier
 
 See `knowledge/tool-resolution.md` for how each bridge name resolves to concrete tools per IDE environment.

package/src/skf-create-stack-skill/references/integration-patterns.md

@@ -1,3 +1,5 @@
+<!-- Config: communicate in {communication_language}. -->
+
 # Integration Pattern Detection Rules
 
 ## Co-Import Detection

package/src/skf-create-stack-skill/references/manifest-patterns.md

@@ -1,3 +1,5 @@
+<!-- Config: communicate in {communication_language}. -->
+
 # Manifest Detection Patterns
 
 ## Supported Ecosystems

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

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

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

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

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

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

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

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

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

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