bmad-module-skill-forge 1.4.0 → 1.5.0

package/src/skf-export-skill/assets/managed-section-format.md

@@ -70,14 +70,14 @@ All other IDEs use AGENTS.md as the context file, each with its own skill direct
 
 **`snippet_skill_root_override` (optional):** Authoring repos where all skills live under one shared on-disk directory (e.g. `skills/`) that does not match any per-IDE skill root may set `snippet_skill_root_override: skills/` in `config.yaml`. When set:
 
-- `export-skill/step-03` §2.7 uses the override as `{skill_root}` for snippet generation instead of the IDE-mapped value
-- `export-skill/step-04` §4d (and its equivalents in `drop-skill/step-02` and `rename-skill/step-02`) treat the override as the effective target prefix for the managed-section rebuild: snippets whose prefix already matches the override pass through unchanged, and any other prefix — including per-IDE prefixes carried by sibling snippets that were exported before the override was adopted, and legacy `skills/` drafts — is rewritten to the override so the rebuilt managed section uniformly references the real on-disk location
+- `export-skill/step 3` §2.7 uses the override as `{skill_root}` for snippet generation instead of the IDE-mapped value
+- `export-skill/step 4` §4d (and its equivalents in `drop-skill/step 2` and `rename-skill/step 2`) treat the override as the effective target prefix for the managed-section rebuild: snippets whose prefix already matches the override pass through unchanged, and any other prefix — including per-IDE prefixes carried by sibling snippets that were exported before the override was adopted, and legacy `skills/` drafts — is rewritten to the override so the rebuilt managed section uniformly references the real on-disk location
 
 Consuming projects (the common case) omit the field and keep the default IDE-mapping behavior. The override is a narrow escape hatch for repos that author skills into `{skills_output_folder}` and never duplicate them into `.claude/skills/`-style directories.
 
 ### Consumers
 
-This mapping is the single source of truth. Workflows that need it: `export-skill/step-01` (resolves `target_context_files` from config.yaml IDE list), `export-skill/step-04` (applies four-case logic and rewrites root paths when writing managed sections), `drop-skill/step-02` and `rename-skill/step-02` (rebuild context files after a management operation).
+This mapping is the single source of truth. Workflows that need it: `export-skill/step 1` (resolves `target_context_files` from config.yaml IDE list), `export-skill/step 4` (applies four-case logic and rewrites root paths when writing managed sections), `drop-skill/step 2` and `rename-skill/step 2` (rebuild context files after a management operation).
 
 ## Four-Case Logic
 

package/src/skf-export-skill/assets/snippet-format.md

@@ -4,9 +4,9 @@
 
 The snippet `root:` path must reflect the IDE's actual skill directory — its `skill_root` from the IDE → Context File Mapping table in `managed-section-format.md`. Each IDE has its own skill directory (e.g., `.claude/skills/`, `.windsurf/skills/`, `.github/skills/`).
 
-The root path in context-snippet.md on disk uses the **`skill_root` of the first entry in `target_context_files`** (resolved in step-01 from config.yaml IDE mapping). When assembling managed sections for other context files, step-04 rewrites root paths to match the target context file's skill root.
+The root path in context-snippet.md on disk uses the **`skill_root` of the first entry in `target_context_files`** (resolved in step 1 from config.yaml IDE mapping). When assembling managed sections for other context files, step 4 rewrites root paths to match the target context file's skill root.
 
-**Authoring-repo override:** If `snippet_skill_root_override` is set in `config.yaml`, it replaces the IDE-mapped value for snippet generation and freezes matching prefixes against step-04 rewrites. See the "Resolution rules" section in `managed-section-format.md` for the full semantics.
+**Authoring-repo override:** If `snippet_skill_root_override` is set in `config.yaml`, it replaces the IDE-mapped value for snippet generation and freezes matching prefixes against step 4 rewrites. See the "Resolution rules" section in `managed-section-format.md` for the full semantics.
 
 ## Format Rules
 

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

@@ -0,0 +1,49 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-export-skill.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (uv probe, config load).
+# Overrides append. Use for org-wide pre-flight checks (auth, network,
+# compliance) that must precede any export work.
+
+activation_steps_prepend = []
+
+# Steps to run after activation but before the first stage executes.
+# Overrides append. Use for context loads or banner customization that
+# should run once activation completes successfully.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (publishing standards, distribution-instruction house style, snippet
+# token-budget guardrails). Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "All exported skills must include a CHANGELOG entry."
+#   - a file reference prefixed with `file:`, e.g.
+#     "file:{project-root}/docs/export-policy.md" (globs supported; file
+#     contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# --- Optional asset overrides ---
+#
+# Lift the canonical asset paths so orgs can substitute house-style copies
+# without forking the skill. Empty string = use the bundled default.
+
+managed_section_format_path = ""
+snippet_format_path = ""
+
+# Override the manifest location. Empty = use
+# {skills_output_folder}/.export-manifest.json. Useful for orgs that want
+# a cross-project manifest at a stable path (e.g. ~/.skf/export-manifest.json).
+
+export_manifest_path = ""

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

@@ -1,8 +1,10 @@
 ---
-nextStepFile: './step-04-update-context.md'
-snippetFormatData: 'assets/snippet-format.md'
+nextStepFile: 'update-context.md'
+snippetFormatData: '{snippetFormatPath}'
 ---
 
+<!-- Config: communicate in {communication_language}. Generate snippet content in {document_output_language}. -->
+
 # Step 3: Generate Snippet
 
 ## STEP GOAL:
@@ -12,16 +14,14 @@ To generate or update context-snippet.md for the skill in the Vercel-aligned ind
 ## Rules
 
 - Focus only on generating the context-snippet.md content — T1-now only, no T2 annotations
-- If `passive_context: false` was detected in step-01, skip this step entirely
-- **Multi-skill mode:** when step-01 loaded more than one skill (`len(skill_batch) > 1`), iterate sections 2–5 per skill. Each skill has its own prior-gotchas carry-forward state (§2.5) — do not share state across skills. §2.7 resolves `{skill_root}` once for the run (it depends on `target_context_files`, not the skill). See step-01 §1c.
+- If `passive_context: false` was detected in step 1, skip this step entirely
+- **Multi-skill mode:** when step 1 loaded more than one skill (`len(skill_batch) > 1`), iterate sections 2–5 per skill. Each skill has its own prior-gotchas carry-forward state (§2.5) — do not share state across skills. §2.7 resolves `{skill_root}` once for the run (it depends on `target_context_files`, not the skill). See step 1 §1c.
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Check Passive Context Setting
 
-**If `passive_context: false` was detected in step-01:**
+**If `passive_context: false` was detected in step 1:**
 
 "**Passive context disabled in preferences.yaml. Skipping snippet generation.**"
 
@@ -37,7 +37,7 @@ Load {snippetFormatData} and read the format template for the skill type.
 
 Before generating new snippet content, check for a prior snippet:
 
-1. Read `{resolved_skill_package}/context-snippet.md` if it exists (resolved in step-01 — see `knowledge/version-paths.md`)
+1. Read `{resolved_skill_package}/context-snippet.md` if it exists (resolved in step 1 — see `knowledge/version-paths.md`)
 2. If it exists, extract the `|gotchas:` line (if any). Trim leading whitespace and the `|gotchas:` prefix, then capture the remaining content as `prior_gotchas_content`.
 3. **Detect the carry-forward marker:** If `prior_gotchas_content` starts with the token `[CARRIED]` (whitespace-insensitive), set `prior_gotchas_already_carried = true` and strip the marker before storing the remainder. Otherwise set `prior_gotchas_already_carried = false`.
 4. **Distinguish empty from absent:** If the `|gotchas:` line exists but has no non-whitespace content after the prefix, treat it as **absent** — set `prior_gotchas = null`. Only a non-empty value counts as a prior gotchas line worth carrying forward.
@@ -49,7 +49,7 @@ These values will be used as a fallback in section 3 if new gotchas cannot be de
 
 **If `snippet_skill_root_override` is set in config.yaml:** Use its value directly as `{skill_root}` and skip the IDE-mapping lookup below. This is the authoring-repo escape hatch — repos where skills live under a single shared directory (e.g. `skills/`) that does not match any per-IDE skill root. Log: "Using snippet_skill_root_override: `{override}` — bypassing IDE mapping for snippet root path."
 
-**Otherwise (default):** Using the first entry in `target_context_files` (resolved in step-01), take its `skill_root` value. This is the IDE's actual skill directory (e.g., `.claude/skills/`, `.windsurf/skills/`, `.github/skills/`).
+**Otherwise (default):** Using the first entry in `target_context_files` (resolved in step 1), take its `skill_root` value. This is the IDE's actual skill directory (e.g., `.claude/skills/`, `.windsurf/skills/`, `.github/skills/`).
 
 Store `{skill_root}` for use in snippet generation. The context-snippet.md written to disk uses this resolved skill root path.
 
@@ -62,9 +62,15 @@ Store `{skill_root}` for use in snippet generation. The context-snippet.md writt
 3. Read SKILL.md to extract: heading slugs for `#quick-start` and `#key-types`, inline summary of key types (~10 words)
 4. **Anchor verification (split-body awareness):** For each section anchor (`#quick-start`, `#key-types`), verify the heading exists in SKILL.md. If a `references/` directory exists and `## Full` headings in SKILL.md are absent or stubs (indicating split-body, not a stack skill's structural references), rewrite the anchor to point to the reference file path (e.g., `references/{file}.md#key-types`). If the heading cannot be resolved in either location, omit that anchor line from the snippet.
 5. Derive gotchas from: T2-future annotations in evidence report (breaking changes), async requirements, version-specific behavior.
+
+   **Detect first-export state before applying carry-forward logic.** The `[CARRIED]` one-cycle expiry is meaningful only on a *re-export*. On a first export, the prior `context-snippet.md` was authored by `create-skill` (or `update-skill`) from the evidence report inside the same forge cycle — those gotchas are freshly derived, not "left over from a previous export." Treating them as carry-forward primes them for premature expiry on the second export.
+
+   Read `{skills_output_folder}/.export-manifest.json` (the same file step 4 §4a will rewrite). If the skill name is **absent** from `exports`, OR present with no resolvable `last_exported` for any version under `versions`, this is a first export — set `is_first_export = true`. Otherwise `is_first_export = false`. (Step-04 reads the manifest authoritatively for the rebuild; this read is the lightweight probe step 3 needs to choose the right branch below.)
+
    - **If new gotchas are derived:** Use them (they supersede any prior gotchas). Write as `|gotchas: {pitfall-1}, {pitfall-2}` with no marker.
-   - **If NO new gotchas are derived BUT `prior_gotchas` exists AND `prior_gotchas_already_carried == false`:** First carry-forward cycle — preserve the prior gotchas line, prefixing the value with `[CARRIED]` so the next export can detect that expiry has been reached. Write as `|gotchas: [CARRIED] {prior gotchas content}`. Emit warning: "**Gotchas preserved from prior export (one-cycle carry-forward).** These gotchas will be DROPPED on the next export unless new gotchas are derived or you manually refresh them. Review now if they are still applicable."
-   - **If NO new gotchas are derived AND `prior_gotchas` exists AND `prior_gotchas_already_carried == true`:** Expiry reached — drop the gotchas line entirely. Emit warning: "**Stale gotchas dropped** — the prior gotchas were already carried forward once and cannot be derived from the current evidence report. The snippet now has no gotchas line. If the prior gotchas are still relevant, re-add them to the evidence report's T2-future section and re-run export."
+   - **If NO new gotchas are derived AND `is_first_export == true` AND `prior_gotchas` exists:** Treat the prior gotchas as **freshly derived** by create-skill/update-skill — write them **without** the `[CARRIED]` marker. (The marker only applies to re-exports.) No warning needed; this is the normal first-export shape.
+   - **If NO new gotchas are derived BUT `prior_gotchas` exists AND `is_first_export == false` AND `prior_gotchas_already_carried == false`:** First carry-forward cycle on a re-export — preserve the prior gotchas line, prefixing the value with `[CARRIED]` so the next export can detect that expiry has been reached. Write as `|gotchas: [CARRIED] {prior gotchas content}`. Emit warning: "**Gotchas preserved from prior export (one-cycle carry-forward).** These gotchas will be DROPPED on the next export unless new gotchas are derived or you manually refresh them. Review now if they are still applicable."
+   - **If NO new gotchas are derived AND `prior_gotchas` exists AND `prior_gotchas_already_carried == true`:** Expiry reached (re-export only — first-export branch above takes precedence) — drop the gotchas line entirely. Emit warning: "**Stale gotchas dropped** — the prior gotchas were already carried forward once and cannot be derived from the current evidence report. The snippet now has no gotchas line. If the prior gotchas are still relevant, re-add them to the evidence report's T2-future section and re-run export."
    - **If NO new gotchas derived AND no `prior_gotchas`:** Omit the gotchas line.
 
 Generate:
@@ -116,7 +122,7 @@ Estimate token count of generated snippet (approximate: words * 1.3).
 
 **Estimated tokens:** {count}"
 
-Hold content in context for step-04.
+Hold content in context for step 4.
 
 **If NOT dry-run:**
 

package/src/skf-export-skill/{steps-c/step-07-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
-# to this step file.
+# Note: `shared/health-check.md` resolves relative to the SKF module root
+# ({project-root}/_bmad/skf/ when installed, {project-root}/src/ during
+# development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 7: 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-06
+- No user-facing reports, file writes, or result contracts in this step — those belong in step 6
 - Delegate directly to `{nextStepFile}` with no additional commentary
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`
 

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:
-
-"**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.
+**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).
 
-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
 
@@ -165,14 +126,22 @@ Load `{sidecar_path}/preferences.yaml` (if exists):
 
 ### 4b. Check Test Report (Quality Gate)
 
-Search for a test report at `{forge_data_folder}/{skill_name}/{active_version}/test-report-{skill_name}.md` (i.e., `{forge_version}/test-report-{skill_name}.md`). If not found at the versioned path, fall back to `{forge_data_folder}/{skill_name}/test-report-{skill_name}.md`:
+`skf-test-skill` writes timestamped test-report filenames (`test-report-{skill_name}-{ISO-TIMESTAMP}-{HASH}.md`) — there is no exact-name `test-report-{skill_name}.md` on disk. Locate the most recent report by glob, not by exact filename:
+
+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 6 §4c) and load that file.
+4. If all three lookups fail, the skill has no test report.
+
+**If a test report is found:**
 
-**If test report found:**
 - Read frontmatter `testResult` and `score`
 - If `testResult: fail`: warn: "**Warning:** This skill failed its last test (score: {score}%). Consider running `@Ferris TS` and addressing gaps before export."
 - If `testResult: pass`: note: "Last test: **PASS** ({score}%)"
+- Always surface the actual file picked in the message (e.g. `test-report-my-base-ui-20260507T050917Z-487606-9b2f.md`) — not the no-longer-existent `test-report-{skill_name}.md` — so an operator can navigate to the report from the log.
+
+**If no test report found** (all three lookups returned nothing):
 
-**If no test report found:**
 - Warn: "**Note:** No test report found for this skill. Consider running `@Ferris TS` before export to verify completeness."
 
 Continue to step 5 regardless — this is advisory, not blocking.
@@ -228,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.