bmad-module-skill-forge 1.4.1 → 1.5.1

package/src/skf-export-skill/{steps-c/step-01-load-skill.md → references/load-skill.md}

@@ -1,7 +1,9 @@
 ---
-nextStepFile: './step-02-package.md'
+nextStepFile: 'package.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 1: Load Skill
 
 ## STEP GOAL:
@@ -15,8 +17,6 @@ To load the target skill's artifacts, validate they meet agentskills.io spec com
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Parse Export Arguments
 
 "**Starting skill export...**"
@@ -25,7 +25,7 @@ Determine the skill(s) to export and any flags:
 
 **Skill Path Discovery (version-aware — see `knowledge/version-paths.md`):**
 - If user provided one or more skill names or paths as arguments, use that list directly
-- If `--all` was passed, build the list from every skill in `{skills_output_folder}/.export-manifest.json.exports` whose `active_version` entry is not `status: "deprecated"` (deprecated skills are excluded from all exports — see step-04 §4b)
+- If `--all` was passed, build the list from every skill in `{skills_output_folder}/.export-manifest.json.exports` whose `active_version` entry is not `status: "deprecated"` (deprecated skills are excluded from all exports — see step 4 §4b)
 - If no explicit skill and no `--all`, discover available skills using the export manifest:
   1. Read `{skills_output_folder}/.export-manifest.json` — list skill names from `exports`
   2. For each skill group directory in `{skills_output_folder}/`, check for `{skill_group}/active/{skill-name}/SKILL.md`
@@ -64,54 +64,15 @@ For each IDE in `config.yaml.ides`:
 
 ### 1b. Detect Snippet Root Prefix Mismatch
 
-**Skip entirely if `snippet_skill_root_override` is already set in `config.yaml`** — the authoring-repo escape hatch is already configured and any on-disk prefix that matches it is ground truth (see `assets/managed-section-format.md` override rules).
-
-Otherwise, probe existing snippets to catch the authoring-repo case (skills live under a single shared directory like `skills/` that does not match any per-IDE `skill_root`) before step-04 silently rewrites their root paths:
-
-1. Collect candidate snippet paths:
-   - Read `{skills_output_folder}/.export-manifest.json` if it exists. For each skill in `exports` with a resolvable `active_version`, add `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md`
-   - Also include the current skill's snippet if present (resolved via manifest / `active` symlink / flat path per `knowledge/version-paths.md`)
-2. For each snippet that exists on disk, read the first line and parse the `root:` value. Strip the trailing `{skill-name}/` to extract the prefix (e.g. `skills/`, `.claude/skills/`)
-3. Collect unique prefixes into `observed_prefixes`
-4. Compare against `target_context_files[0].skill_root` (the first entry's IDE-mapped skill root — used as reference since step-03 §2.7 picks this same entry for snippet generation when no override is set)
-
-**If `observed_prefixes` contains any value that does not match the reference `skill_root`:**
-
-Emit a single warning (once, not per snippet) and present resolution options before proceeding:
+**Skip entirely if `snippet_skill_root_override` is set in `config.yaml`** — the authoring-repo escape hatch is already configured and any on-disk prefix that matches it is ground truth (see `assets/managed-section-format.md` override rules).
 
-"**Snippet root prefix mismatch detected.**
-Existing snippets use: `{observed_prefixes}`
-IDE-mapped skill_root:  `{target_context_files[0].skill_root}`
-
-This usually means you are in an authoring repo where skills live under a single shared directory. Options:
-- **(a) Set override** — add `snippet_skill_root_override: {observed_prefix}` to `config.yaml`. Snippets keep their on-disk prefix; the managed section references the real location.
-- **(b) Proceed with IDE mapping** — step-04 will rewrite every snippet's root path to the IDE's skill_root. Use this only if the IDE's skill directory actually contains the skill files.
-- **(c) Cancel** — abort export and investigate.
-
-If multiple distinct prefixes were observed, the snippets disagree with each other — investigate before choosing (a)."
-
-In `{headless_mode}`, default to (b) and log the observed prefix(es) so the mismatch is visible in run logs. In interactive mode, wait for user choice before continuing to section 2.
-
-**If all observed prefixes match the reference `skill_root` (or no existing snippets were found):** Proceed silently.
+**Otherwise:** load `references/preflight-snippet-root-probe.md` and follow its probe + (a) Set override / (b) Proceed with IDE mapping / (c) Cancel gate protocol. The reference handles candidate snippet collection (manifest-driven), prefix observation, the mismatch warning, and headless default ((b) Proceed). Returns control to §1c on no-mismatch fast path or after a (b) choice.
 
 ### 1c. Multi-skill Mode (when `len(skill_batch) > 1`)
 
-When multiple skills are being exported in a single run (via `--all`, multi-selection at the discovery menu, or an explicit multi-argument invocation), the workflow does NOT loop the full step-01→step-07 sequence once per skill. Instead, it partitions work across steps to avoid repeated gates and redundant batch work:
-
-| Step | Behavior in multi-skill mode |
-|------|------------------------------|
-| step-01 §2–5 | **Iterate per skill** — load, validate, read metadata, and check the test report for every skill in `skill_batch`. Collect per-skill results. |
-| step-01 §6 | **Single gate** — present one consolidated summary table (one row per skill) and a single [C] gate for the whole batch. |
-| step-02 | **Iterate per skill** — validate each skill's package structure and collect per-skill readiness. |
-| step-03 | **Iterate per skill** — regenerate each skill's `context-snippet.md` independently (each skill has its own prior-gotchas carry-forward state). |
-| step-04 | **Batch once** — §3b orphan detection, §4 skill-index rebuild, §5 managed-section assembly, and §6–9 diff + write all execute once for the entire batch. The exported skill set in §4b already enumerates every skill in the manifest — it does not need per-skill iteration. §9b adds/updates a manifest entry per skill in `skill_batch` (not just the last one), then writes the manifest once. |
-| step-05 | **Iterate per skill** — compute token counts per skill, then present one aggregate report. |
-| step-06 | **One batch summary + one result contract** — the files-written table lists every skill; the result contract JSON covers the whole run, and `outputs` enumerates every context-snippet + target context file touched. |
-| step-07 | **Runs once** — health check is per-workflow-run, not per-skill. |
-
-**Halt semantics in batch mode:** if any single skill fails validation in §2 (required-file or metadata-field failure), halt the entire batch before §5 — do not partially export. Report which skill failed and why.
+**If `len(skill_batch) == 1`:** single-skill mode (legacy behavior) — every section below operates on the one skill without iteration. Skip this subsection.
 
-**Single-skill mode (`len(skill_batch) == 1`)** preserves the legacy behavior: every section below operates on the one skill without iteration.
+**If `len(skill_batch) > 1`:** load `references/multi-skill-mode.md` and apply its per-step behavior matrix. The reference partitions work so that step 1 §2–5 iterates per skill, step 1 §6 presents a single consolidated [C] gate, step 4 batches once across the whole run, and step 7 health check runs once. It also defines the all-or-nothing halt semantics if any single skill fails §2 validation.
 
 ### 2. Load and Validate Skill Artifacts
 
@@ -169,7 +130,7 @@ Load `{sidecar_path}/preferences.yaml` (if exists):
 
 1. Glob `{forge_data_folder}/{skill_name}/{active_version}/test-report-{skill_name}-*.md` (i.e. `{forge_version}/test-report-{skill_name}-*.md`). Sort matches descending by the parsed ISO-timestamp segment in the filename (`YYYYMMDDTHHMMSSZ` between the skill name and the hash — `sort -r` on the filename works because the timestamp is the first variable component). Take the first match.
 2. If the versioned glob returns nothing, fall back to the same glob at the flat path `{forge_data_folder}/{skill_name}/test-report-{skill_name}-*.md`. Pick the newest by parsed timestamp.
-3. If neither glob returns anything, look for the stable companion `skf-test-skill-result-latest.json` in the same two directories (versioned first, then flat). Read the report path from `outputs[]` per the canonical contract documented at `shared/references/output-contract-schema.md` (resolved by skf-test-skill step-06 §4c) and load that file.
+3. If neither glob returns anything, look for the stable companion `skf-test-skill-result-latest.json` in the same two directories (versioned first, then flat). Read the report path from `outputs[]` per the canonical contract documented at `shared/references/output-contract-schema.md` (resolved by skf-test-skill step 6 §4c) and load that file.
 4. If all three lookups fail, the skill has no test report.
 
 **If a test report is found:**
@@ -236,11 +197,12 @@ Continue to step 5 regardless — this is advisory, not blocking.
 
 ### 6. Present MENU OPTIONS
 
-Display: "**Select:** [C] Continue to packaging" (multi-skill mode: the single [C] gate covers the whole batch)
+Display: "**Select:** [C] Continue to packaging | [X] Cancel and exit (or type `cancel` / `exit` / `:q`)" (multi-skill mode: the single [C] gate covers the whole batch)
 
 #### Menu Handling Logic:
 
 - IF C: Proceed with loaded skill data, then load, read entire file, then execute {nextStepFile}
+- IF X (or `cancel` / `exit` / `:q`): Display "Cancelled — no packaging or context file writes were performed." and HALT (exit code 6, `halt_reason: "user-cancelled"`). In headless, emit the error envelope per SKILL.md "Result Contract (Headless)" with the resolved `skills`, `context_files_updated: []`, and `manifest_path: null`.
 - IF Any other: help user respond, then [Redisplay Menu Options](#6-present-menu-options)
 
 #### EXECUTION RULES:

package/src/skf-export-skill/references/manifest-rebuild.md

@@ -0,0 +1,68 @@
+---
+# Static reference loaded by update-context.md §4a only when manifest
+# schema documentation is needed (the in-prompt schema is otherwise
+# delegated to skf-manifest-ops.py which handles v2 enforcement and
+# v1→v2 migration internally).
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Export Manifest v2 — Schema Reference
+
+## Purpose
+
+Reference for the v2 export manifest schema enforced by `skf-manifest-ops.py` and consumed by every workflow that touches `{skills_output_folder}/.export-manifest.json`. This file is the source of truth for the v2 shape; the helper script implements it; downstream skills (drop-skill, rename-skill, update-skill) read this same file to stay aligned.
+
+## v2 Schema
+
+```json
+{
+  "schema_version": "2",
+  "exports": {
+    "skill-name": {
+      "active_version": "0.6.0",
+      "versions": {
+        "0.1.0": {
+          "ides": ["claude-code"],
+          "last_exported": "2026-01-15",
+          "status": "deprecated"
+        },
+        "0.5.0": {
+          "ides": ["claude-code"],
+          "last_exported": "2026-03-15",
+          "status": "archived"
+        },
+        "0.6.0": {
+          "ides": ["claude-code", "github-copilot"],
+          "last_exported": "2026-04-04",
+          "status": "active"
+        }
+      }
+    }
+  }
+}
+```
+
+## Status enum
+
+- `"active"` — currently exported; snippet appears in managed sections
+- `"archived"` — previously exported, not active; files retained for rollback
+- `"deprecated"` — dropped via drop-skill workflow; excluded from all exports (files may or may not exist on disk)
+- `"draft"` — created but never exported
+
+## v1 → v2 migration (handled by `skf-manifest-ops.py`)
+
+Pre-rename v2 manifests used a `platforms` array at the version level. If a version entry contains `platforms` instead of (or in addition to) `ides`, the helper treats `platforms` as `ides` and rewrites it on the next manifest write — silent in-place upgrade, no user prompt.
+
+For v1 manifests (no `schema_version` field), the helper migrates in-place on the first read:
+
+1. For each entry in `exports`, read its `last_exported`
+2. Resolve the skill's current version from `{resolved_skill_package}/metadata.json`
+3. Wrap in v2 structure: `active_version` ← resolved version, single entry in `versions` with `status: "active"`, `ides: []` (unknown — fills on next successful export), and `last_exported`
+4. Set `schema_version: "2"` at root
+
+Workflows that load the manifest via `skf-manifest-ops.py read` always receive the v2 shape regardless of on-disk state.
+
+## Integrity invariant
+
+`active_version` must resolve to a `versions` entry. If `active_version` is set but there is no matching key under `versions`, the manifest is inconsistent (possible corruption or a botched v1→v2 migration). Workflows must skip the affected skill and surface a loud warning rather than fall through to a degraded state. The recommended recovery is to re-run `[EX] Export Skill` on the affected skill — the export pass rebuilds the version entry from `metadata.json` ground truth.

package/src/skf-export-skill/references/multi-skill-mode.md

@@ -0,0 +1,38 @@
+---
+# Static reference loaded by load-skill.md §1c only when
+# `len(skill_batch) > 1` (multi-skill mode activated via `--all`,
+# multi-selection at the discovery menu, or explicit multi-argument
+# invocation). In single-skill mode the per-step matrix below does
+# not apply and this file is never loaded. Loaded once per export run.
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Multi-skill Mode — Per-step Behavior Matrix
+
+## Purpose
+
+When multiple skills are exported in a single run, the workflow does NOT loop the full step 1 → step 7 sequence once per skill. Instead, it partitions work across steps to avoid repeated gates and redundant batch work (one §3b orphan-detection pass, one §4 skill-index rebuild, one §6 user gate, one health check, etc.).
+
+Loaded by `load-skill.md` §1c when `len(skill_batch) > 1`.
+
+## Per-step matrix
+
+| Step | Behavior in multi-skill mode |
+|------|------------------------------|
+| step 1 §2–5 | **Iterate per skill** — load, validate, read metadata, and check the test report for every skill in `skill_batch`. Collect per-skill results. |
+| step 1 §6 | **Single gate** — present one consolidated summary table (one row per skill) and a single [C] gate for the whole batch. |
+| step 2 | **Iterate per skill** — validate each skill's package structure and collect per-skill readiness. |
+| step 3 | **Iterate per skill** — regenerate each skill's `context-snippet.md` independently (each skill has its own prior-gotchas carry-forward state). |
+| step 4 | **Batch once** — §3b orphan detection, §4 skill-index rebuild, §5 managed-section assembly, and §6–9 diff + write all execute once for the entire batch. The exported skill set in §4b already enumerates every skill in the manifest — it does not need per-skill iteration. §9b adds/updates a manifest entry per skill in `skill_batch` (not just the last one), then writes the manifest once. |
+| step 5 | **Iterate per skill** — compute token counts per skill, then present one aggregate report. |
+| step 6 | **One batch summary + one result contract** — the files-written table lists every skill; the result contract JSON covers the whole run, and `outputs` enumerates every context-snippet + target context file touched. |
+| step 7 | **Runs once** — health check is per-workflow-run, not per-skill. |
+
+## Halt semantics
+
+If any single skill fails validation in step 1 §2 (required-file or metadata-field failure), halt the entire batch before step 4 §5 — do not partially export. Report which skill failed and why. The principle: a multi-skill run is a unit of work, not a per-skill best-effort sweep — partial exports leave the manifest and managed sections in an ambiguous state that's expensive for the operator to reconcile.
+
+## Single-skill mode (reference)
+
+`len(skill_batch) == 1` preserves the legacy behavior: every section operates on the one skill without iteration, no gate consolidation, no per-step table consultation. This file does not need to be loaded.

package/src/skf-export-skill/references/orphan-context-detection.md

@@ -0,0 +1,75 @@
+---
+# Static reference loaded by update-context.md §3b only when
+# `orphaned_context_files` is non-empty (i.e. the cheap pre-check in
+# §3b found a context file on disk with an SKF managed section that
+# is no longer in the current `target_context_files`). The reference
+# carries the (a)/(b)/(c) gate protocol, headless default, and
+# downstream-state contract; the trigger detection itself stays
+# inline in §3b so the LLM knows when to invoke this protocol.
+---
+
+<!-- Config: communicate in {communication_language}. Render the orphan list and gate prompt in {document_output_language}. -->
+
+# Orphan Context-File Detection — Gate Protocol
+
+## Purpose
+
+Handle the (a) clear / (b) keep / (c) rewrite gate when one or more known context files (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`) on disk contain an SKF managed section but their owning IDE is no longer listed in `config.yaml.ides`. Loaded by `update-context.md` §3b after the cheap pre-check populates `orphaned_context_files`.
+
+## Inputs
+
+- `orphaned_context_files` — list of `{context_file, file_path}` entries built by §3b's pre-check
+- `target_context_files` — current export's IDE → context-file map (from step 1)
+- `{headless_mode}` — boolean flag from workflow context
+
+## Gate Protocol
+
+Emit the warning and gate:
+
+> **Orphaned context files detected.** The following files contain SKF managed sections but no configured IDEs target them:
+> {list: context file → file path}
+>
+> The managed sections in these files are stale. Options:
+>
+> - **(a) clear** — remove the SKF managed section from each orphaned file (surgical marker replacement, leaves user content intact)
+> - **(b) keep** — leave them untouched (they will remain stale until you re-add an IDE that targets this file or delete the file)
+> - **(c) rewrite** — also rewrite the orphaned files with the current skill index (use this if the IDE was removed by mistake)
+
+Wait for user choice.
+
+**Headless / non-interactive default:** when `{headless_mode}` (or dry-run, or unattended), default to **(b) keep** and print the warning only — no destructive action without explicit consent.
+
+## Choice handling
+
+### (a) clear
+
+For each file in `orphaned_context_files`:
+
+1. Replace everything between `<!-- SKF:BEGIN` and `<!-- SKF:END -->` (inclusive) with an empty string, preserving surrounding content byte-exactly.
+2. Append the file path to `orphans_cleared` (workflow-context list, surfaced in the §6 result contract).
+
+### (b) keep
+
+Record nothing. The orphaned files remain on disk, untouched. Proceed.
+
+### (c) rewrite
+
+Add each entry in `orphaned_context_files` to a separate `rewrite_context_files` list. This list is kept distinct from `target_context_files` so the user's intent to only export to configured IDEs is preserved in the manifest update at §9b — `rewrite_context_files` participates in the §4–§9a write loop for this run only and is not promoted into the manifest's `ides` arrays.
+
+Use `.agents/skills/` as the default skill root for rewritten orphans (the IDE-neutral path used when the original IDE mapping is no longer available).
+
+Record each rewritten file in `orphans_rewritten` (workflow-context list, surfaced in the §6 result contract).
+
+## Downstream contract
+
+After this protocol completes, §3b returns control to §4 with these workflow-context variables populated:
+
+- `orphans_cleared: []` — set when the user chose (a) or stayed empty otherwise
+- `orphans_rewritten: []` — set when the user chose (c) or stayed empty otherwise
+- `rewrite_context_files: []` — extends the per-context-file iteration in §4–§9a when the user chose (c)
+
+The §4–§9a loop iterates over `target_context_files + rewrite_context_files`. The §9b manifest update reads only `target_context_files` (rewritten orphans are not promoted into the manifest).
+
+## Scope note
+
+This cleanup only runs during interactive export (and the headless default explicitly does nothing destructive). Drop-skill and rename-skill operate on the manifest's declared context files and are not responsible for orphan detection — their scope is the active manifest, not arbitrary on-disk markers.

package/src/skf-export-skill/references/orphan-row-detection.md

@@ -0,0 +1,102 @@
+---
+# Static reference loaded by update-context.md §4c.1 only when
+# `orphan_managed_rows` is non-empty (i.e. the cheap pre-check in
+# §4c.1 found `[skill-name v...]` entries in the prior managed
+# section that are absent from the manifest-driven exported skill
+# set built in §4b). The reference carries the (a)/(b)/(c) gate
+# protocol, headless default, deviations[] contract, and §6
+# result-contract integration; the trigger detection itself stays
+# inline in §4c.1 so the LLM knows when to invoke this protocol.
+---
+
+<!-- Config: communicate in {communication_language}. Render the orphan list and gate prompt in {document_output_language}. -->
+
+# Orphan Managed-Section Rows — Gate Protocol
+
+## Purpose
+
+Handle the (a) Drop / (b) Preserve verbatim / (c) Cancel gate when the prior managed section in the first target context file contains `[skill-name v...]` rows for skills that are not in the manifest-driven exported skill set — typically externally-installed skills authored in a different repo and dropped into `{skills_output_folder}` without going through export-skill.
+
+Strict ADR-K would silently drop such rows, but the user's managed section is load-bearing — silent removal of an installed skill is a regression. The convention captured in `skills/export-skill-result-latest.json` deviations is to make this an explicit operator (or `{headless_mode}`) choice.
+
+## Inputs
+
+- `orphan_managed_rows` — list of `{skill_name, version, snippet_text, source_files: []}` entries built by §4c.1's pre-check across **every** target context file, deduplicated by `(skill_name, version)`. `source_files` carries the file paths the orphan appeared in (one entry per file in which the row was found). `snippet_text` is the original snippet line(s) captured verbatim from the first encountered occurrence, used for re-emission if (b) is chosen.
+- `target_context_files` — the full IDE → context-file list (referenced in the gate's framing copy so the user understands the consolidation scope)
+- `{headless_mode}` — boolean flag from workflow context
+
+## Gate Protocol
+
+Emit the gate:
+
+> **Managed-section rows present but absent from manifest** (consolidated across {len(target_context_files)} target context file(s)):
+>
+> {list each as `- {skill_name} v{version} (in: {comma-separated source_files})`}
+>
+> These skills appear in one or more existing managed sections but no entry exists in `.export-manifest.json` and no source draft exists under `{skills_output_folder}/{skill_name}/`. They were likely installed from a different repo and never run through export-skill in this project. Options:
+>
+> - **(a) Drop** — remove these rows from the rebuilt managed section across **all** target context files (strict ADR-K behavior). The skills' on-disk files are not touched, but they will no longer appear in any context file's managed index.
+> - **(b) Preserve verbatim** — copy each orphan's existing snippet line(s) into the rebuilt managed section across **all** target context files unchanged (one canonical row per `(skill, version)` written everywhere — orphans become symmetric across IDEs as a side effect, which is the correct outcome since the user's intent is "these external skills should appear in my managed index"). Records `deviations[].kind = "preserve_external_skills"` with the affected skill names, versions, and `source_files` in the result contract for audit.
+> - **(c) Cancel** — abort export. Run export-skill against each external skill (or remove the orphan rows from the context files manually) before re-running.
+
+Wait for user choice.
+
+**Headless default** (when `{headless_mode}`): auto-select **(b) Preserve verbatim**, with the same `deviations[]` entry. Emit a loud log line:
+
+> `headless: {N} managed-section rows had no manifest entry; preserving verbatim with deviations[].kind = preserve_external_skills. Run export-skill against each to migrate them into the manifest.`
+
+Silent drop under automation would regress the user's managed section without consent; cancel under automation would block the whole export over an externally-installed skill the user did not author. Preservation matches the prior-attentive-operator convention.
+
+## Choice handling
+
+### (a) Drop
+
+Do not include any orphan rows in the rebuilt section. Record:
+
+```
+orphans_dropped = [{skill_name, version}, …]
+```
+
+in workflow context for the §6 result contract.
+
+### (b) Preserve verbatim
+
+Append each captured `snippet_text` to the assembled section after the manifest-driven entries, preserving alphabetical order in the merged list (sort the combined set of `manifest-driven` + `orphan` snippets by `skill_name`). Each `(skill, version)` is written **once** per rebuilt managed section — the deduplication done by §4c.1 means there is no per-file divergence to reconcile here.
+
+Append the following entry to the `deviations[]` array in the §6 result contract:
+
+```json
+{
+  "kind": "preserve_external_skills",
+  "skills": [
+    {"name": "...", "version": "...", "source_files": ["..."]}
+  ],
+  "rationale": "managed-section row exists but no manifest entry / no source draft"
+}
+```
+
+`source_files` per skill records the prior context files the orphan was found in (asymmetric provenance preserved for audit) — useful when an operator later debugs which IDE's managed section originally carried the row.
+
+The same orphans are written to **every** target context file in the §4–§9a loop, so all configured IDEs end up with consistent managed sections (asymmetric prior orphans become symmetric — the correct outcome for the "preserve external skills" intent).
+
+### (c) Cancel
+
+HALT the workflow:
+
+- Do not rewrite any context file.
+- Do not update the manifest.
+- Do not produce a result contract.
+- Exit code 6, `halt_reason: "user-cancelled"` (matches the §8 Menu cancel semantics).
+- In headless mode this branch is never taken (headless default is (b)), so this exit path is interactive-only.
+
+## Downstream contract
+
+After this protocol completes, §4c.1 returns control to §4d with these workflow-context variables populated:
+
+- `orphans_dropped: []` — set when the user chose (a) or stayed empty otherwise
+- `deviations[]` — extended with the `preserve_external_skills` entry when the user chose (b)
+- The assembled managed section contains the orphan rows verbatim when (b) was chosen, and excludes them when (a) was chosen
+
+## Scope note
+
+This detection runs once per export run (not per target context file) — the §4c.1 pre-check iterates **every** entry in `target_context_files` and deduplicates by `(skill_name, version)` before invoking this protocol, so the gate's choice applies globally and asymmetric orphans (a row present in `.cursorrules` but not in `CLAUDE.md`, or vice versa) are detected and surfaced with `source_files` provenance.

package/src/skf-export-skill/{steps-c/step-02-package.md → references/package.md}

@@ -1,7 +1,9 @@
 ---
-nextStepFile: './step-03-generate-snippet.md'
+nextStepFile: 'generate-snippet.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Validate package contents in {document_output_language}. -->
+
 # Step 2: Package
 
 ## STEP GOAL:
@@ -12,21 +14,19 @@ To assemble and validate an agentskills.io-compliant package structure from the
 
 - Focus only on package structure assembly and validation — do not modify SKILL.md content
 - Auto-proceed when complete
-- **Multi-skill mode:** when step-01 loaded more than one skill (`len(skill_batch) > 1`), iterate sections 1–4 below per skill using each skill's `{resolved_skill_package}`. Collect per-skill status; report the aggregate in §4 as one row per skill. Halt the batch if any skill is NOT READY. See step-01 §1c.
+- **Multi-skill mode:** when step 1 loaded more than one skill (`len(skill_batch) > 1`), iterate sections 1–4 below per skill using each skill's `{resolved_skill_package}`. Collect per-skill status; report the aggregate in §4 as one row per skill. Halt the batch if any skill is NOT READY. See step 1 §1c.
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Validate Package Structure
 
-Verify the skill package at `{resolved_skill_package}` (resolved in step-01 via manifest or `active` symlink — see `knowledge/version-paths.md`) contains the expected agentskills.io package layout:
+Verify the skill package at `{resolved_skill_package}` (resolved in step 1 via manifest or `active` symlink — see `knowledge/version-paths.md`) contains the expected agentskills.io package layout:
 
 ```
 {skill_package} = {skills_output_folder}/{skill-name}/{version}/{skill-name}/
 ├── SKILL.md              ← Required: Active skill document
 ├── metadata.json         ← Required: Machine-readable metadata
-├── context-snippet.md    ← Will be generated/updated in step-03
+├── context-snippet.md    ← Will be generated/updated in step 3
 ├── references/           ← Optional: Progressive disclosure
 │   ├── {function-a}.md
 │   └── {function-b}.md
@@ -66,7 +66,7 @@ Determine package status:
 
 **READY:** All required files present, all required metadata fields valid
 **WARNINGS:** Ready but with missing recommended fields or empty references/
-**NOT READY:** Missing required files or required metadata fields (should not reach here — step-01 would have halted)
+**NOT READY:** Missing required files or required metadata fields (should not reach here — step 1 would have halted)
 
 ### 4. Report Package Status
 

package/src/skf-export-skill/references/preflight-snippet-root-probe.md

@@ -0,0 +1,79 @@
+---
+# Static reference loaded by load-skill.md §1b only when
+# `snippet_skill_root_override` is UNSET in config.yaml. When the
+# override is set, every existing snippet's on-disk prefix is ground
+# truth by contract — no probe needed and the entire authoring-repo
+# escape hatch is already configured. Loaded once per export run, not
+# per skill.
+---
+
+<!-- Config: communicate in {communication_language}. Render the warning and gate prompt in {document_output_language}. -->
+
+# Snippet Root Prefix Mismatch — Pre-flight Probe
+
+## Purpose
+
+Catch the authoring-repo case before step 4 silently rewrites root paths. In an authoring repo, skills typically live under a single shared directory (`skills/`) that does not match any per-IDE `skill_root` (`.claude/skills/`, `.cursor/skills/`, etc.). Without this probe, step 4's root-rewrite algorithm would replace the on-disk prefix with an IDE-mapped one that the snippet files do not actually reside under.
+
+Loaded by `load-skill.md` §1b after `target_context_files` is resolved and `snippet_skill_root_override` is confirmed unset.
+
+## Inputs
+
+- `target_context_files[0].skill_root` — the reference IDE-mapped skill root (used because step 3 §2.7 picks this same entry for snippet generation when no override is set)
+- `{skills_output_folder}` — for manifest-driven candidate enumeration
+- Current skill's snippet path (resolved via manifest / `active` symlink / flat path per `knowledge/version-paths.md`)
+- `{headless_mode}` — boolean flag from workflow context
+
+## Probe Algorithm
+
+1. Collect candidate snippet paths:
+   - Read `{skills_output_folder}/.export-manifest.json` if it exists. For each skill in `exports` with a resolvable `active_version`, add `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md`.
+   - Also include the current skill's snippet if present.
+2. For each snippet that exists on disk, read the first line and parse the `root:` value. Strip the trailing `{skill-name}/` to extract the prefix (e.g. `skills/`, `.claude/skills/`).
+3. Collect unique prefixes into `observed_prefixes`.
+4. Compare against `target_context_files[0].skill_root` (the reference).
+
+## Mismatch Gate
+
+**If `observed_prefixes` contains any value that does not match the reference `skill_root`:**
+
+Emit a single warning (once, not per snippet) and present resolution options before continuing to §2:
+
+> **Snippet root prefix mismatch detected.**
+> Existing snippets use: `{observed_prefixes}`
+> IDE-mapped skill_root:  `{target_context_files[0].skill_root}`
+>
+> This usually means you are in an authoring repo where skills live under a single shared directory. Options:
+>
+> - **(a) Set override** — add `snippet_skill_root_override: {observed_prefix}` to `config.yaml`. Snippets keep their on-disk prefix; the managed section references the real location.
+> - **(b) Proceed with IDE mapping** — step 4 will rewrite every snippet's root path to the IDE's skill_root. Use this only if the IDE's skill directory actually contains the skill files.
+> - **(c) Cancel** — abort export and investigate.
+> - **(d) Use observed prefix for this run only** — set the effective snippet root to the single observed on-disk prefix for this export run, without writing to `config.yaml`. The managed section references the real on-disk location. (Only offered when exactly one prefix was observed.)
+>
+> If multiple distinct prefixes were observed, the snippets disagree with each other — investigate before choosing (a) or (d).
+
+Wait for user choice.
+
+**Headless default:** when `{headless_mode}`, default to **(b) Proceed with IDE mapping** and log the observed prefix(es) so the mismatch is visible in run logs (not silent).
+
+## Choice handling
+
+### (a) Set override
+
+Halt and instruct the user to update `config.yaml` with `snippet_skill_root_override: {observed_prefix}`, then re-run export. Exit code 6, `halt_reason: "user-cancelled"` (configuration change is out-of-band — workflow does not edit config.yaml on the user's behalf).
+
+### (b) Proceed with IDE mapping
+
+Continue to §2. Step 4's root-rewrite algorithm will rewrite every snippet's prefix to the reference `skill_root`. The user is accepting that the IDE's skill directory contains the actual files; if it does not, the resulting managed section will reference paths that don't resolve.
+
+### (c) Cancel
+
+HALT. Exit code 6, `halt_reason: "user-cancelled"`. No files written.
+
+### (d) Use observed prefix for this run only
+
+**Only available when `observed_prefixes` contains exactly one value.** Set the effective snippet root for this run to that single observed prefix — do NOT mutate `config.yaml`. Step 4's root-rewrite algorithm uses this value as the reference instead of `target_context_files[0].skill_root`, so snippets keep their on-disk prefix and the managed section resolves to the real location. Print a one-line hint: "Persist `snippet_skill_root_override: {observed_prefix}` in config.yaml to skip this prompt on future exports." Continue to §2.
+
+## No-mismatch fast path
+
+**If all observed prefixes match the reference `skill_root` (or no existing snippets were found):** no warning, no gate. Return control to §1b and proceed silently to §2.

package/src/skf-export-skill/{steps-c/step-06-summary.md → references/summary.md}

@@ -1,7 +1,9 @@
 ---
-nextStepFile: './step-07-health-check.md'
+nextStepFile: 'health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Render the user-facing summary in {document_output_language}. -->
+
 # Step 6: Summary
 
 ## STEP GOAL:
@@ -12,12 +14,10 @@ To present a complete export summary showing all files written, token counts, an
 
 - Focus only on summarizing what was done and providing next steps — no additional file writes
 - Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing summary is NOT the terminal step
-- **Multi-skill mode:** emit ONE consolidated summary and ONE result contract for the whole batch. The files-written table lists every skill in `skill_batch` (one row per skill's `context-snippet.md` + one row per target managed-section file, shared across the batch). The result contract's `outputs` enumerates every context-snippet file plus every target context file. Distribution instructions (§2) key off `source_authority` per skill — present one block per distinct authority value observed in the batch, listing the skills it applies to. See step-01 §1c.
+- **Multi-skill mode:** emit ONE consolidated summary and ONE result contract for the whole batch. The files-written table lists every skill in `skill_batch` (one row per skill's `context-snippet.md` + one row per target managed-section file, shared across the batch). The result contract's `outputs` enumerates every context-snippet file plus every target context file. Distribution instructions (§2) key off `source_authority` per skill — present one block per distinct authority value observed in the batch, listing the skills it applies to. See step 1 §1c.
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Compile Export Summary
 
 "**Export Complete{if dry-run: ' (Dry Run)'}**
@@ -89,18 +89,18 @@ Your skill is generated from an external dependency for local use.
 
 ### 3. Use It In This Project
 
-Always show this section (regardless of `source_authority`) so the author can install the skill they just forged into the current project and try it immediately:
+Always show this section (regardless of `source_authority`) so the author can install the skill they just forged into the current project and try it immediately.
+
+**Rendering rule for the command below — must be obeyed:** substitute `{resolved_skill_package}` with the actual resolved path before printing (do not leave the placeholder for the user to replace). The substituted path must be either absolute (starts with `/`) or `./`-prefixed. A bare relative path like `skills/foo/1.0.0/foo` is parsed by the `skills` CLI as `https://github.com/skills/foo.git` (org/repo GitHub lookup) and will fail with an authentication error. If `{resolved_skill_package}` resolves to a relative path, prefix it with `./` before emitting.
 
 "### Use It In This Project
 
-To install this skill into the current project right now:
+To install this skill into the current project right now, run:
 
 ```
 npx skills add {resolved_skill_package}
 ```
 
-Replace `{resolved_skill_package}` with the absolute path to the package folder shown above (from step-02), e.g. `{skills_output_folder}/{skill-name}/{version}/{skill-name}/`.
-
 For other source formats (registry name, git URL, tarball, etc.), see the **Installation → Source Formats** section at <https://www.npmjs.com/package/skills>.
 
 If the installed skill's commands are not available in the same IDE session, reload plugins (e.g. for Claude Code users, run `/reload-plugins`) or restart your AI editor. Next time you will see the command `/{skill-name}` (e.g. `/{skill-name}`)."
@@ -130,18 +130,30 @@ No files were written. To run the export for real:
 
 ### 6. Result Contract
 
-Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skills_output_folder}/export-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{skills_output_folder}/export-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all context files and target managed-section files in `outputs`; include total always-on and on-trigger token counts in `summary`.
+Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skills_output_folder}/export-skill-result-{timestamp}.json` (reuse the activation-stored `{timestamp}`, resolution to seconds) and a copy at `{skills_output_folder}/export-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all context files and target managed-section files in `outputs`; include total always-on and on-trigger token counts in `summary`.
+
+When `{headless_mode}` is true, also emit the single-line envelope on **stdout** before chaining to step 7 (matches the SKILL.md "Result Contract (Headless)" shape):
 
-**`deviations[]` field (export-skill-specific extension):** when step-04 §4c.1 detected manifest-orphan managed rows and the operator (or `{headless_mode}`) chose **(b) Preserve verbatim**, also include a `deviations[]` array in the contract. Each entry has the shape:
+```
+SKF_EXPORT_RESULT_JSON: {"status":"success","skills":{skill_batch_names},"context_files_updated":{context_files_updated},"manifest_path":"{skills_output_folder}/.export-manifest.json","headless_decisions":{headless_decisions},"exit_code":0,"halt_reason":null}
+```
+
+Substitute `{skill_batch_names}`, `{context_files_updated}`, and `{headless_decisions}` as JSON arrays. When `--dry-run` was set, emit `"status":"dry-run"` instead and report what *would* have been written without performing the writes.
+
+**`deviations[]` field (export-skill-specific extension):** when step 4 §4c.1 detected manifest-orphan managed rows and the operator (or `{headless_mode}`) chose **(b) Preserve verbatim**, also include a `deviations[]` array in the contract. Each entry has the shape:
 
 ```json
 {
   "kind": "preserve_external_skills",
-  "skills": [{"name": "skill-name", "version": "1.0.0"}, …],
+  "skills": [
+    {"name": "skill-name", "version": "1.0.0", "source_files": ["CLAUDE.md", ".cursorrules"]}
+  ],
   "rationale": "managed-section row exists but no manifest entry / no source draft"
 }
 ```
 
+`source_files` per skill records the prior context files the orphan was found in (the §4c.1 multi-file scan deduplicates by `(skill, version)` and tracks which target context files originally carried the row — useful when an operator later debugs which IDE's managed section first introduced the external skill).
+
 Other workflow choices that diverge from the strict spec path may add their own entries with a distinct `kind` value — auditors then have one place to look for "what did this run choose to do differently from the canonical flow." Omit the field when there are no deviations rather than writing an empty array, so the absence is readable as "ran the canonical path."
 
 ### 7. Chain to Health Check