bmad-module-skill-forge 1.9.0 → 2.0.1

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

@@ -122,7 +122,7 @@ Target file contains `<!-- SKF:BEGIN` but no matching `<!-- SKF:END -->` marker.
 When regenerating (Case 3) or creating/appending (Cases 1-2), rebuild the skill index from the **exported skill set** only:
 
 1. Read `{skills_output_folder}/.export-manifest.json` (v2 schema — see `knowledge/version-paths.md`) to determine which skills have been explicitly exported and their `active_version` (if no manifest exists, only the current export target qualifies)
-2. For each skill in the exported set, resolve the snippet at `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md` (i.e., `{skill_package}/context-snippet.md`). Do NOT use glob patterns across version directories — always resolve via manifest `active_version` or `active` symlink
+2. For each skill in the exported set, resolve the snippet at `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md` (i.e., `{skill_package}/context-snippet.md`). Do NOT use glob patterns across version directories — always resolve via manifest `active_version` or `active` symlink, falling back to the flat `{skills_output_folder}/{skill-name}/context-snippet.md` path for a skill not yet migrated to the versioned layout
 3. Count total skills and stack skills (from filtered set only)
 4. Assemble filtered snippets into managed section
 5. Sort alphabetically by skill name
@@ -132,7 +132,4 @@ When regenerating (Case 3) or creating/appending (Cases 1-2), rebuild the skill
 
 ## Safety Rules
 
-- NEVER modify content outside the `<!-- SKF:BEGIN/END -->` markers
-- ALWAYS preserve existing file content above and below markers
-- ALWAYS verify file was written correctly after write
-- If write fails, report error — do not attempt partial writes
+Only the bytes between `<!-- SKF:BEGIN -->` and `<!-- SKF:END -->` are yours to rewrite; everything above and below is the user's own file (their CLAUDE.md/AGENTS.md/.cursorrules) and must survive byte-for-byte — rewriting outside the markers destroys their content. On write failure, report and stop — never leave a partial write. Route writes through the atomic-write / rebuild-managed-sections helpers: they verify byte-identity of the content outside the markers after each write, so no separate hand-check is needed.

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

@@ -1,6 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-export-skill.
+# Team overrides:     _bmad/custom/skf-export-skill.toml (under {project-root})
+# Personal overrides: _bmad/custom/skf-export-skill.user.toml (under {project-root})
 
 [workflow]
 
@@ -34,6 +36,14 @@ persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
 
+# Optional post-export hook. When non-empty, invoked with
+# `--result-path=<path>` after step 6 finalizes the per-run result JSON
+# (before the terminal health-check step). Useful for downstream
+# distribution, notification, or pipeline chaining. Failures are logged to
+# workflow_warnings[] but never fail the workflow. Empty = no-op (default).
+
+on_complete = ""
+
 # --- Optional asset overrides ---
 #
 # Lift the canonical asset paths so orgs can substitute house-style copies
@@ -41,9 +51,3 @@ persistent_facts = [
 
 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/references/generate-snippet.md

@@ -1,6 +1,14 @@
 ---
 nextStepFile: 'update-context.md'
 snippetFormatData: '{snippetFormatPath}'
+# Resolve `{countTokensHelper}` by probing `{countTokensProbeOrder}` in order
+# (installed SKF module path first, src/ dev-checkout fallback); the first
+# existing path wins. §5 uses it to report the written snippet's authoritative
+# token count (char-over-four, matching step 5's token report) instead of the
+# in-prompt `words * 1.3` heuristic.
+countTokensProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-count-tokens.py'
+  - '{project-root}/src/shared/scripts/skf-count-tokens.py'
 ---
 
 <!-- Config: communicate in {communication_language}. Generate snippet content in {document_output_language}. -->
@@ -73,36 +81,17 @@ Store `{skill_root}` for use in snippet generation. The context-snippet.md writt
    - **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:
-```
-[{skill-name} v{version}]|root: {skill_root}{skill-name}/
-|IMPORTANT: {skill-name} v{version} — read SKILL.md before writing {skill-name} code. Do NOT rely on training data.
-|quick-start:{SKILL.md#quick-start}
-|api: {export-1}(), {export-2}(), {export-3}, {export-4}(), {export-5}
-|key-types:{SKILL.md#key-types} — {inline summary ~10 words}
-|gotchas: {pitfall-1}, {pitfall-2}
-```
-
-**If fewer exports than limit:** List all available.
-**If no exports:** Omit the api line.
-**If no gotchas derivable AND no prior gotchas to carry forward:** Omit the gotchas line.
+Emit the single-skill template from {snippetFormatData} (loaded in §2), filling `api` from the exports selected above (list all if fewer than the limit; omit the line if there are none), `key-types` from the inline summary extracted above, and `gotchas` per the carry-forward decision tree above (omit the line when it resolves to none).
 
 **For stack skills (`skill_type: "stack"`):**
 
-Generate:
-```
-[{project}-stack v{version}]|root: {skill_root}{project}-stack/
-|IMPORTANT: {project}-stack — read SKILL.md before writing integration code. Do NOT rely on training data.
-|stack: {dep-1}@{v1}, {dep-2}@{v2}, {dep-3}@{v3}
-|integrations: {pattern-1}, {pattern-2}
-|gotchas: {pitfall-1}, {pitfall-2}
-```
+Emit the stack-skill template from {snippetFormatData}, filling `stack` from metadata.json `components` and `integrations` from metadata.json `integrations`.
 
 **Stack skill gotchas carry-forward:** Same one-cycle expiry logic as single skills. If no new gotchas derived and `prior_gotchas_already_carried == false`, preserve with the `[CARRIED]` prefix. If already carried once (`prior_gotchas_already_carried == true`), drop the line and warn loudly. See the single-skill steps for the complete protocol.
 
 ### 4. Verify Token Count
 
-Estimate token count of generated snippet (approximate: words * 1.3).
+Estimate the generated snippet's token count with the **char-over-four** convention (`len(snippet)//4`) over the content held in context — the same convention `skf-count-tokens.py` uses for step 5's token report, so the two numbers agree. The freshly generated snippet is only in context here (not yet on disk), so this pre-write estimate stays in-prompt to drive the trim decision below; step 5 confirms it authoritatively against the written file via the helper.
 
 - Target: ~80-120 tokens per skill (aspirational for Quick/Forge tiers)
 - Warning threshold: >300 tokens (hard ceiling — Deep tier may legitimately exceed 120 when gotchas carry load-bearing breaking-change notices)
@@ -122,12 +111,20 @@ Estimate token count of generated snippet (approximate: words * 1.3).
 
 **Estimated tokens:** {count}"
 
-Hold content in context for step 4.
+Use the §4 char-over-four estimate for `{count}` — nothing is written in dry-run, so the helper has no on-disk snippet to measure. Hold content in context for step 4.
 
 **If NOT dry-run:**
 
 Write the generated content to `{resolved_skill_package}/context-snippet.md`.
 
+Then confirm the token count authoritatively: resolve `{countTokensHelper}` from `{countTokensProbeOrder}` (first existing path wins) and run it against the written package, reading the `context-snippet.md` row's `tokens` value:
+
+```bash
+python3 {countTokensHelper} {resolved_skill_package}
+```
+
+Use that value as `{count}` — it matches step 5's token report exactly. If the helper cannot run (no Python/uv), fall back to the §4 char-over-four estimate.
+
 "**context-snippet.md written.**
 **Path:** `{resolved_skill_package}/context-snippet.md`
 **Estimated tokens:** {count}"
@@ -136,16 +133,5 @@ Write the generated content to `{resolved_skill_package}/context-snippet.md`.
 
 Display: "**Proceeding to context update...**"
 
-#### Menu Handling Logic:
-
-- After snippet generation completes, immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed step with no user choices
-- Proceed directly to next step after generation
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN snippet generation is complete (or skipped due to passive_context opt-out) will you load and read fully `{nextStepFile}` to execute context update.
+Auto-proceed (no user choices): once snippet generation is complete (or skipped via the `passive_context` opt-out), load, read entirely, and execute `{nextStepFile}`.
 

package/src/skf-export-skill/references/load-skill.md

@@ -1,5 +1,16 @@
 ---
 nextStepFile: 'package.md'
+managedSectionData: '{managedSectionFormatPath}'
+# Resolve `{validateOutputHelper}` by probing `{validateOutputProbeOrder}` in
+# order (installed SKF module path first, src/ dev-checkout fallback); first
+# existing path wins. §2 runs it with `--export-gate` to obtain the
+# agentskills.io export verdict — required-field presence, enum membership,
+# JSON validity, and the SKILL.md Section 7b <-> scripts/assets cross-reference
+# — as one deterministic JSON result, instead of re-deriving those checks
+# in-prompt each run. package.md §1-4 renders its status from the same verdict.
+validateOutputProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-output.py'
+  - '{project-root}/src/shared/scripts/skf-validate-output.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -25,18 +36,20 @@ 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 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`
-  3. If neither manifest nor `active` symlink yields results, fall back to flat path: `{skills_output_folder}/{skill-name}/SKILL.md`
+- 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). **First-export fallback:** if the manifest is absent or its `exports` object is empty (a fresh repo with skills on disk but no prior export), do not resolve to an empty set — enumerate skills on disk instead, using the same discovery ladder as the no-argument branch below (`active` symlinks at `{skills_output_folder}/{skill-name}/active/{skill-name}/SKILL.md`, then flat `{skills_output_folder}/{skill-name}/SKILL.md`). Every disk-discovered skill is non-deprecated by definition — deprecation status lives only in the manifest.
+- If no explicit skill and no `--all`, then:
+  - **Headless guard:** if `{headless_mode}` is true, HALT (exit code 2, `halt_reason: "input-missing"`) — a non-interactive run cannot answer the skill-selection menu; the operator must pass an explicit `skill_name` or `--all`. Emit the error envelope per `references/result-envelope.md` with `skills: []`, `context_files_updated: []`, `manifest_path: null`.
+  - **Interactive:** 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`
+    3. If neither manifest nor `active` symlink yields results, fall back to flat path: `{skills_output_folder}/{skill-name}/SKILL.md`
 - If multiple skills are found, present the list and accept either a single selection or a comma-/space-separated multi-selection (e.g. `1, 2, 3` or `all`)
-- If no skills found, halt: "No skills found in {skills_output_folder}/. Run create-skill first."
+- If no skills found, HALT (exit code 3, `halt_reason: "resolution-failure"`): "No skills found in {skills_output_folder}/. Run create-skill first." In headless, emit the error envelope per `references/result-envelope.md` with `skills: []`, `context_files_updated: []`, `manifest_path: null`.
 
 Store the resolved selection as `skill_batch` — a list of one or more skill names. `len(skill_batch) > 1` activates multi-skill mode (see §1c below).
 
 **Flag Parsing:**
-- `--all` flag: Check if provided. When true and no explicit skill list was given, `skill_batch` is the full non-deprecated manifest set (see above).
+- `--all` flag: Check if provided. When true and no explicit skill list was given, `skill_batch` is the full non-deprecated manifest set — or, when no manifest exists yet, the full on-disk discovery set (see the first-export fallback above).
 - `--context-file` flag: Check if explicitly provided (CLAUDE.md, .cursorrules, or AGENTS.md). Replaces the old `--platform` flag.
 - `--dry-run` flag: Check if provided. Default: `false`
 
@@ -44,16 +57,9 @@ Store the resolved selection as `skill_batch` — a list of one or more skill na
 
 If `--context-file` is explicitly provided, use that single context file as the sole target. Determine the skill root from the first configured IDE that maps to that context file (or `.agents/skills/` for AGENTS.md if no matching IDE is configured). If other IDEs are configured in config.yaml, emit a note: "**Note:** Exporting to {context-file} only. config.yaml also lists: {other-ides}. Run without `--context-file` to export to all configured IDEs."
 
-If `--context-file` is NOT provided, read the `ides` list from config.yaml and map each IDE to its context file and skill root using the "IDE → Context File Mapping" table in `skf-export-skill/assets/managed-section-format.md`. Every IDE the installer offers has an explicit mapping — no silent skips.
+If `--context-file` is NOT provided, read the `ides` list from config.yaml and map each entry to its `context_file` and `skill_root` using the "IDE → Context File Mapping" table plus the "Resolution rules" in `{managedSectionData}` — that canonical file carries the deduplication (group by context file; first configured IDE's skill root wins), the unknown-IDE default-and-warn, and the missing-`ides`-key (treat as empty list) behavior, each with its exact warning/report string. Every IDE the installer offers has an explicit mapping — no silent skips.
 
-For each IDE in `config.yaml.ides`:
-
-1. Look up its `context_file` and `skill_root` from the canonical mapping table
-2. If the IDE is not in the table, default to AGENTS.md / `.agents/skills/` and warn: "Unknown IDE '{value}' in config.yaml — defaulting to AGENTS.md with `.agents/skills/`"
-
-**Deduplication:** Group by `context_file`. When multiple IDE entries map to the same context file (e.g. both `codex` and `cline` map to AGENTS.md), deduplicate so each context file appears in `target_context_files` only once. Use the **first configured IDE's** `skill_root` for that context file. Report the deduplication: "Multiple IDEs target AGENTS.md — using {first-ide}'s skill root (`{skill_root}`). Each IDE's skills are installed to its own directory."
-
-**Missing-key handling:** If the `ides` key is absent from config.yaml (older installation or manually edited file), treat it as an empty list.
+Apply those rules to `config.yaml.ides`, then:
 
 - If mapping produces one or more context files (after dedup), store as `target_context_files` list — each entry has `{context_file, skill_root}`
 - If mapping produces zero entries (empty ides list and no recognized entries), fall back to `[{context_file: "AGENTS.md", skill_root: ".agents/skills/"}]` with note: "No IDEs configured in config.yaml — defaulting to AGENTS.md with `.agents/skills/`."
@@ -64,13 +70,13 @@ For each IDE in `config.yaml.ides`:
 
 ### 1b. Detect Snippet Root Prefix Mismatch
 
-**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).
+**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 `{managedSectionData}` override rules).
 
 **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`)
 
-**If `len(skill_batch) == 1`:** single-skill mode (legacy behavior) — every section below operates on the one skill without iteration. Skip this subsection.
+**If `len(skill_batch) == 1`:** single-skill mode — every section below operates on the one skill without iteration. Skip this subsection.
 
 **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.
 
@@ -95,15 +101,22 @@ Load all files from `{resolved_skill_package}`:
 - `references/` — Progressive disclosure directory
 - `context-snippet.md` — Existing snippet (will be regenerated)
 
-**Validation Checks:**
-1. `SKILL.md` exists and is non-empty
-2. `metadata.json` exists and is valid JSON
-3. `metadata.json` contains required fields: `name`, `version`, `skill_type`, `source_authority`, `exports`, `generation_date`, `confidence_tier`
-4. `metadata.json.exports` is a non-empty array (warn if empty — graceful handling)
+**Validation (deterministic — the export gate):**
+
+Run the export gate against the resolved package. Resolve `{validateOutputHelper}` from `{validateOutputProbeOrder}` (first existing path wins):
+
+```bash
+python3 {validateOutputHelper} {resolved_skill_package} --export-gate
+```
+
+The script emits one JSON verdict covering every check this step used to derive by hand: `SKILL.md` present and non-empty; `metadata.json` present and valid JSON; the required agentskills.io fields present (`name`, `version`, `skill_type`, `source_authority`, `exports`, `generation_date`, `confidence_tier`); enum membership (`skill_type` ∈ single/stack, `source_authority` ∈ official/internal/community, `confidence_tier` ∈ Quick/Forge/Forge+/Deep); a non-empty `exports` array (empty is a low warning, not a halt); and the SKILL.md Section 7b ↔ on-disk `scripts/`/`assets/` cross-reference (a §7b-named file absent on disk is a high issue; an unreferenced on-disk file is a low orphan warning). Read `result` (PASS/FAIL), `export_status` (READY/WARNINGS/NOT_READY), and the issue arrays under `validation.metadata.{issues,enum_issues}` and `validation.crossref_7b.{missing,orphans}`. **Retain this JSON as the export verdict** — step 2 (`package.md`) renders its status from it without re-deriving the checks.
 
-**If any required validation fails:**
-"**Export cannot proceed.** Missing or invalid: {list failures}
+**If the script cannot run** (no `uv`/Python — e.g. claude.ai web): perform the equivalent checks by hand; `python3 {validateOutputHelper} --help` documents exactly what it verifies.
+
+**If `result` is `FAIL` / `export_status` is `NOT_READY`** (any high-severity issue in `validation.*`):
+"**Export cannot proceed.** Missing or invalid: {list the high-severity issue messages from the script's `validation.metadata.{issues,enum_issues}` and `validation.crossref_7b.missing`}
 Run create-skill to generate a complete skill first."
+Then HALT (exit code 3, `halt_reason: "resolution-failure"`). In headless, emit the error envelope per `references/result-envelope.md` with the resolved `skills`, `context_files_updated: []`, `manifest_path: null`.
 
 ### 3. Read Skill Metadata
 
@@ -196,23 +209,12 @@ Continue to step 5 regardless — this is advisory, not blocking.
 
 **Are these the correct skills to export?**"
 
-### 6. Present MENU OPTIONS
-
-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:
-
-- ALWAYS halt and wait for user input after presenting menu
-- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-continue past skill confirmation"
-- ONLY proceed to next step when user selects 'C'
+### 6. Confirmation Gate
 
-## CRITICAL STEP COMPLETION NOTE
+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), then wait for the reply.
 
-ONLY WHEN the user confirms the correct skill is loaded by selecting 'C' will you load and read fully `{nextStepFile}` to execute packaging.
+- **[C]** — proceed with the loaded skill data: load, read entirely, and execute `{nextStepFile}`.
+- **[X]** / `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 `references/result-envelope.md` with the resolved `skills`, `context_files_updated: []`, and `manifest_path: null`.
+- **Any other input** — help the user respond, then redisplay this gate.
+- **Headless** [default C]: auto-proceed with [C], log "headless: auto-continue past skill confirmation".
 

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

@@ -35,4 +35,4 @@ If any single skill fails validation in step 1 §2 (required-file or metadata-fi
 
 ## 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.
+`len(skill_batch) == 1` runs the single-skill path: 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

@@ -43,10 +43,18 @@ Wait for user choice.
 
 ### (a) clear
 
+The marker excision is deterministic surgery with one correct answer per input — a mis-parsed boundary silently corrupts the user's surrounding content. Delegate it to the tested `clear` action of `skf-rebuild-managed-sections.py`, the same helper `update-context.md` §9 uses for the between-marker swap; do not excise markers in-prompt. Resolve `{rebuildManagedSectionsHelper}` from `update-context.md`'s `{rebuildManagedSectionsProbeOrder}` frontmatter (first existing path wins). If no candidate exists, HALT (exit code 4, `halt_reason: "context-rebuild-failed"`) per `update-context.md` §9 — falling through to an in-prompt excision would regress the atomic-write + post-clear verify guarantee.
+
 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).
+1. Run:
+
+   ```bash
+   python3 {rebuildManagedSectionsHelper} {file_path} clear
+   ```
+
+   The `clear` action removes the entire `<!-- SKF:BEGIN -->`…`<!-- SKF:END -->` block (and its surrounding blank lines), leaves the rest of the file intact, and performs an atomic temp-file + rename write with a post-clear verify that the section is gone. Treat any non-zero exit (or a `status: "error"` envelope) as a clear failure — HALT (exit code 4, `halt_reason: "context-rebuild-failed"`) reporting `{file_path}: {captured stderr}`. This branch is interactive-only (the headless default is (b) keep), so it emits no result envelope here.
+2. On success (`status: "ok"`, `action: "cleared"`), append the file path to `orphans_cleared`. On a non-empty list, record it in the §6 result contract as a `deviations[]` entry (`kind: "clear_orphan_context"`, `files: [...]`) — the extensible deviations mechanism summary.md §6 documents for choices that diverge from the canonical export path.
 
 ### (b) keep
 
@@ -58,7 +66,7 @@ Add each entry in `orphaned_context_files` to a separate `rewrite_context_files`
 
 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).
+Record each rewritten file in `orphans_rewritten`. On a non-empty list, record it in the §6 result contract as a `deviations[]` entry (`kind: "rewrite_orphan_context"`, `files: [...]`) — the same extensible deviations mechanism summary.md §6 documents.
 
 ## Downstream contract
 

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

@@ -1,5 +1,13 @@
 ---
 nextStepFile: 'generate-snippet.md'
+# `{validateOutputHelper}` resolves from `{validateOutputProbeOrder}` (first
+# existing path wins). Step 1 §2 already ran `--export-gate` and retained the
+# JSON verdict; this step renders its status from that verdict. Only re-run the
+# command below if the step-1 JSON is not in context (e.g. package.md entered
+# directly). The verdict is deterministic — same package → same result.
+validateOutputProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-output.py'
+  - '{project-root}/src/shared/scripts/skf-validate-output.py'
 ---
 
 <!-- Config: communicate in {communication_language}. Validate package contents in {document_output_language}. -->
@@ -34,19 +42,16 @@ Verify the skill package at `{resolved_skill_package}` (resolved in step 1 via m
 └── assets/               ← Optional: Templates, schemas, configs
 ```
 
-**Check each component:**
-1. `SKILL.md` — Verify has frontmatter with `name` field
-2. `metadata.json` — Verify required agentskills.io fields:
-   - `name` (string, non-empty)
-   - `version` (string, semver format preferred)
-   - `skill_type` ("single" or "stack")
-   - `source_authority` ("official", "internal", or "community")
-   - `exports` (array)
-   - `generation_date` (ISO date string)
-   - `confidence_tier` ("Quick", "Forge", "Forge+", or "Deep")
-3. `references/` — If exists, check at least one .md file present
-4. `scripts/` — If exists, verify at least one file present and each file referenced in SKILL.md Section 7b exists. Warn for orphaned scripts (present but not referenced).
-5. `assets/` — If exists, verify at least one file present and each file referenced in SKILL.md Section 7b exists. Warn for orphaned assets (present but not referenced).
+**Component checks — from the export-gate verdict (do not re-derive):**
+
+Step 1 §2 already ran the export gate (`python3 {validateOutputHelper} {resolved_skill_package} --export-gate`) and retained its JSON. Read that verdict rather than re-listing the required fields, enum values, or Section 7b rules here — it deterministically covers all of it:
+
+- `SKILL.md` present and non-empty; `metadata.json` present and valid JSON — `validation.skill_md.issues` / `validation.metadata.issues`
+- Required agentskills.io fields present (`name`, `version`, `skill_type`, `source_authority`, `exports`, `generation_date`, `confidence_tier`) — `validation.metadata.issues`
+- Enum membership (`skill_type`, `source_authority`, `confidence_tier`) — `validation.metadata.enum_issues`
+- SKILL.md Section 7b ↔ on-disk `scripts/`/`assets/` cross-reference — `validation.crossref_7b.missing` (high: §7b-named file absent on disk) and `validation.crossref_7b.orphans` (low: on-disk file not referenced in §7b)
+
+If the step-1 JSON is not in context (e.g. this step was entered directly), re-run the command above to regenerate it — the verdict is deterministic. `references/` presence (at least one `.md`) remains a simple on-disk observation for the §4 report.
 
 ### 2. Validate Metadata Completeness
 
@@ -62,26 +67,26 @@ Check metadata.json for recommended (non-required) fields:
 
 ### 3. Assess Package Readiness
 
-Determine package status:
+Read `export_status` directly from the export-gate verdict (step 1 §2) — do not re-compute the status by hand:
 
-**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 1 would have halted)
+- **READY** — the verdict has no issues (`export_status: "READY"`).
+- **WARNINGS** — only medium/low issues remain (`export_status: "WARNINGS"`): §7b orphans, an empty `exports` array, or the recommended-field notes from §2 above.
+- **NOT READY** — any high-severity issue (`export_status: "NOT_READY"`). Step 1 §2 halts on this, so a healthy run never reaches here; if it does, surface the high-severity messages and halt.
 
 ### 4. Report Package Status
 
 "**Package structure validated.**
 
-**Status:** {READY / WARNINGS}
+**Status:** {export_status: READY / WARNINGS}
 
 **Required Components:**
 - SKILL.md: ✅
-- metadata.json: ✅ ({count} required fields valid)
+- metadata.json: ✅ (required fields valid per export-gate verdict)
 - references/: {✅ present ({count} files) / ⚠️ not present}
 
-{If warnings:}
+{If warnings (export_status: WARNINGS):}
 **Warnings:**
-- {list missing recommended fields}
+- {list missing recommended fields from §2, plus any `validation.crossref_7b.orphans` and an empty `exports` warning from the verdict}
 
 **Package is ready for snippet generation.**"
 
@@ -89,16 +94,5 @@ Determine package status:
 
 Display: "**Proceeding to snippet generation...**"
 
-#### Menu Handling Logic:
-
-- After package validation completes, immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed step with no user choices
-- Proceed directly to next step after validation
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN package validation is complete will you load and read fully `{nextStepFile}` to execute snippet generation.
+Auto-proceed (no user choices): once package validation is complete, load, read entirely, and execute `{nextStepFile}`.
 

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

@@ -5,6 +5,15 @@
 # truth by contract — no probe needed and the entire authoring-repo
 # escape hatch is already configured. Loaded once per export run, not
 # per skill.
+# Resolve `{rebuildManagedSectionsHelper}` by probing
+# `{rebuildManagedSectionsProbeOrder}` in order (installed SKF module
+# path first, src/ dev-checkout fallback); first existing path wins.
+# The `root-probe` action reads each candidate snippet's first line,
+# parses/strips the `root:` prefix, and returns `observed_prefixes` +
+# `mismatch` — deterministic prefix comparison the LLM must not re-derive.
+rebuildManagedSectionsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-rebuild-managed-sections.py'
+  - '{project-root}/src/shared/scripts/skf-rebuild-managed-sections.py'
 ---
 
 <!-- Config: communicate in {communication_language}. Render the warning and gate prompt in {document_output_language}. -->
@@ -26,16 +35,26 @@ Loaded by `load-skill.md` §1b after `target_context_files` is resolved and `sni
 
 ## Probe Algorithm
 
-1. Collect candidate snippet paths:
+1. Collect candidate snippet paths (manifest-driven orchestration — stays in-prompt):
    - 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).
+2. **Read the prefixes and compare via the helper** — reading each snippet's first line, parsing/stripping the `root:` prefix, collecting the unique set, and comparing against the reference is deterministic prefix arithmetic with one correct answer per input. Resolve `{rebuildManagedSectionsHelper}` from `{rebuildManagedSectionsProbeOrder}` (frontmatter — first existing path wins; if no candidate exists, skip the probe and continue to §2 without a warning rather than blocking export on a missing dev-only helper), then run:
+
+   ```bash
+   python3 {rebuildManagedSectionsHelper} root-probe {candidate-snippet-1} {candidate-snippet-2} … --reference-root {target_context_files[0].skill_root}
+   ```
+
+   Pass every candidate snippet path from step 1 as a positional argument and the reference `skill_root` as `--reference-root`. The helper reads each snippet that exists, parses its first-line `root:` value, strips the trailing `{skill-name}/` (recovered from the row's own `[skill-name v...]` header) to extract the prefix, and returns:
+
+   ```json
+   {"status": "ok", "reference_root": "…", "observed_prefixes": ["…"], "mismatch": true}
+   ```
+
+   Set `observed_prefixes = result["observed_prefixes"]` (already unique and sorted; missing or root-less snippets contribute nothing). `result["mismatch"]` is `true` when any observed prefix differs from the reference `skill_root` — the trigger for the Mismatch Gate below.
 
 ## Mismatch Gate
 
-**If `observed_prefixes` contains any value that does not match the reference `skill_root`:**
+**If `result["mismatch"]` is `true`** (some value in `observed_prefixes` does not match the reference `skill_root`):
 
 Emit a single warning (once, not per snippet) and present resolution options before continuing to §2:
 

package/src/skf-export-skill/references/result-envelope.md

@@ -0,0 +1,28 @@
+<!-- Config: emit exactly as specified — this is a machine-parsed contract. Loaded standalone by any halting stage; it back-references no other file. -->
+
+# Headless Result Envelope
+
+The single-line JSON envelope export-skill emits on non-interactive (`{headless_mode}`) runs. Pipeline consumers parse it to branch on the run's outcome, so its shape must be reproduced exactly. This file stands alone — every HARD-HALT stage can load it without SKILL.md in context.
+
+## Emission rule
+
+- **Success / dry-run:** step 6 (`summary.md`) emits the envelope on **stdout**, once, before chaining to step 7.
+- **Every HARD HALT:** emit the same envelope shape on **stderr** with `status: "error"`, then exit with the matching code.
+
+## Shape
+
+```
+SKF_EXPORT_RESULT_JSON: {"status":"success|error|dry-run","skills":[],"context_files_updated":[],"manifest_path":"…|null","headless_decisions":[],"exit_code":0,"halt_reason":null}
+```
+
+## Fields
+
+- `status` — `"success"` on the terminal happy path, `"dry-run"` when `--dry-run` skipped the §4 context and manifest writes (the run still reaches the terminal step), `"error"` on any HALT.
+- `skills` — resolved skill names in the batch (JSON array).
+- `context_files_updated` — context files successfully written this run (JSON array; `[]` when a HALT preceded any write).
+- `manifest_path` — the written manifest path, or `null` when no manifest write completed.
+- `headless_decisions` — the `{gate, default_action, taken_action, reason}` entries logged as each gate auto-resolved (JSON array).
+- `exit_code` — 0 success/dry-run · 2 input-missing · 3 resolution-failure · 4 write-failure · 5 state-conflict · 6 user-cancelled.
+- `halt_reason` — `null` on success/dry-run, else one of: `"input-missing"`, `"resolution-failure"`, `"malformed-markers"`, `"manifest-write-failed"`, `"context-rebuild-failed"`, `"write-failed"`, `"user-cancelled"`. Each value is emitted by a real HALT site (see the SKILL.md Exit Codes table for the code↔reason map); the enum lists no value that no stage emits.
+
+A halting stage sets the branch-specific fields inline (e.g. `manifest_path: null`, `context_files_updated: []`) and fills the rest from the shape above.

package/src/skf-export-skill/references/summary.md

@@ -132,7 +132,7 @@ No files were written. To run the export for real:
 
 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):
+When `{headless_mode}` is true, also emit the single-line envelope on **stdout** before chaining to step 7 (per `references/result-envelope.md`):
 
 ```
 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}
@@ -156,11 +156,17 @@ Substitute `{skill_batch_names}`, `{context_files_updated}`, and `{headless_deci
 
 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
+### 6b. Post-Export Hook (Optional)
+
+If `{onCompleteCommand}` (resolved at SKILL.md On Activation §4 from `workflow.on_complete`) is non-empty, invoke it now — after both the per-run and `-latest` result JSON have been written:
 
-ONLY WHEN the export summary, distribution instructions, and result contract are complete will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the summary reads as final.
+```bash
+{onCompleteCommand} --result-path={skills_output_folder}/export-skill-result-{timestamp}.json
+```
 
-## CRITICAL STEP COMPLETION NOTE
+Run it with a bounded timeout. On success, continue. On non-zero exit, timeout, or any failure, append the reason to `workflow_warnings[]` (e.g. `on_complete — failed (exit {N}): {stderr_first_line}`) and continue. **The hook must never fail the workflow** — it is integration glue (downstream distribution, notifier, pipeline chain) and any failure there is orthogonal to the export outcome. When `{onCompleteCommand}` is empty (bundled default), skip this section entirely.
+
+### 7. Chain to Health Check
 
-This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md`. After the health check completes, the export-skill workflow is fully done.
+ONLY WHEN the export summary, distribution instructions, result contract, and on-complete hook (or its skip on an empty `{onCompleteCommand}`) are complete will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the summary reads as final.