bmad-module-skill-forge 2.2.0 → 3.0.0

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

@@ -1,8 +1,8 @@
 ---
-# 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).
+# Static reference named by update-context.md §9b, loaded only when
+# manifest schema documentation is needed (skf-manifest-ops.py enforces
+# the v2 shape and migrates v1 internally, so no step edits the manifest
+# in the prompt).
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -11,7 +11,7 @@
 
 ## 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.
+Reference for the v2 export manifest schema that `skf-manifest-ops.py` enforces for every workflow that touches `{skills_output_folder}/.export-manifest.json`. This file documents the v2 shape and the helper implements it: export-skill, drop-skill and rename-skill read and edit manifest entries through the helper (`read`, `get`, `set`, `deprecate`, `remove`, `rename`), and `skf-rebuild-managed-sections.py assemble` reads it through the same code. Rename-skill's rollback is the one write outside it: it restores the byte copy of the manifest it kept before the re-key.
 
 ## v2 Schema
 
@@ -54,12 +54,11 @@ Reference for the v2 export manifest schema enforced by `skf-manifest-ops.py` an
 
 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:
+For v1 manifests (no `schema_version` field), every read returns the v2 shape, and the next write through the helper stores it:
 
-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
+1. Each entry's `versions` list becomes a map with one record per version: `ides: []` (unknown, filled on the next successful export) and `last_exported` from the manifest's `updated_at`
+2. The entry's `active_version` keeps its value; that version's record gets `status: "active"`, or `"deprecated"` when the entry carries `deprecated: true`, and every other version `status: "archived"`
+3. The `deprecated` and `deprecated_versions` keys are dropped and `schema_version: "2"` is set at the root
 
 Workflows that load the manifest via `skf-manifest-ops.py read` receive a `{"status": "ok", "manifest": {...}}` envelope; the `manifest` value is always in canonical v2 shape regardless of on-disk state (parse `result["manifest"]`, not the top-level object).
 

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

@@ -23,15 +23,15 @@ Loaded by `load-skill.md` §1c when `len(skill_batch) > 1`.
 | 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 3 | **Iterate per skill**: regenerate each skill's `context-snippet.md` independently (each skill has its own prior-gotchas carry-forward state), staging and measuring each draft in the run's one stage folder. |
+| step 4 | **Batch once**: §3b orphan detection, §4 section build, §5 to §9 check, preview, gate and write all run once for the entire batch. Each `assemble` call names every skill in `skill_batch` with `--include`, beside every skill of the manifest, so no batch member is left out, even on a first export. §9b records every skill in `skill_batch` with one `set` each, and §9c then writes each skill's snippet. |
 | 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 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, every target context file touched and the manifest. |
 | 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.
+If any single skill fails validation in step 1 §2 (required-file or metadata-field failure) or is refused by the §2 ownership gate (`not-skf-output`: a flat skill SKF did not generate), halt the entire batch before step 4: 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)
 

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

@@ -37,13 +37,21 @@ Emit the warning and gate:
 
 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.
+**GATE [default: b]**, headless or non-interactive: when `{headless_mode}` (or dry-run, or unattended), default to **(b) keep** and print the warning only: no destructive action without explicit consent.
+
+When `{headless_mode}` is true, also record the decision in the run sink, listing each orphaned file's `file_path` with `/` in place of `\` so it stays a JSON string. If `record` exits non-zero, display its error line and go on (a failed `record` never stops the run):
+
+```bash
+uv run {emitEnvelopeHelper} record --workflow skf-export-skill --run-dir "{run_dir}" --decision <<'SKF_JSON'
+{"gate":"update-context.orphan-context-files","default_action":"b","taken_action":"b","reason":"headless: orphaned context files kept untouched","evidence":{"files":["{file_path}"]}}
+SKF_JSON
+```
 
 ## Choice handling
 
 ### (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.
+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 writes the section with; do not excise markers in-prompt. `{rebuildManagedSectionsHelper}` is the path SKILL.md's On Activation resolved, and activation halts (exit code 4, `halt_reason: "context-rebuild-failed"`) when no candidate exists: falling through to an in-prompt excision would regress the atomic-write + post-clear verify guarantee.
 
 For each file in `orphaned_context_files`:
 
@@ -62,7 +70,7 @@ 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.
+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` joins the §4 to §9 writes 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).
 
@@ -74,9 +82,9 @@ After this protocol completes, §3b returns control to §4 with these workflow-c
 
 - `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)
+- `rewrite_context_files: []`: joins the targets of §4 to §9 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).
+§4 to §9 run 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
 

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

@@ -1,12 +1,12 @@
 ---
 # 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.
+# `orphan_rows` is non-empty (the §4b `assemble` results list
+# `[skill-name v...]` rows of the current managed sections whose skill
+# neither the export manifest nor this run's batch holds). The
+# reference carries the (a)/(b)/(c) gate protocol, headless default,
+# deviations[] contract, and step 6 result-contract integration; the
+# trigger 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}. -->
@@ -15,13 +15,13 @@
 
 ## 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.
+Handle the (a) Drop / (b) Preserve verbatim / (c) Cancel gate when the managed section of a target context file holds `[skill-name v...]` rows for skills that neither the export manifest nor this run's batch holds: 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.
+- `orphan_rows`: the `{skill_name, version, snippet_text, source_files: [], skill_type}` entries `assemble` returned in §4b, found across **every** target context file and 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 row captured verbatim from the first file that holds it, which (b) writes back unchanged.
 - `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
 
@@ -33,17 +33,25 @@ Emit the gate:
 >
 > {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:
+> These skills appear in one or more existing managed sections, but `.export-manifest.json` has no entry for them and this export does not include them. 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.
+> - **(c) Cancel** — abort export. Before re-running, run export-skill on each of these skills that SKF generated (its `metadata.json` carries an SKF marker) to add it to the manifest, and remove the rows of the other skills from the context files yourself.
 
 Wait for user choice.
 
-**Headless default** (when `{headless_mode}`): auto-select **(b) Preserve verbatim**, with the same `deviations[]` entry. Emit a loud log line:
+**GATE [default: b]** (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.`
+> `headless: {N} managed-section rows had no manifest entry; preserving verbatim with deviations[].kind = preserve_external_skills. Run export-skill on each skill SKF generated to add it to the manifest; remove the rows of other skills from the context files yourself.`
+
+Record the decision in the run sink, listing each orphan row as `{skill_name} v{version}`. If `record` exits non-zero, display its error line and go on (a failed `record` never stops the run):
+
+```bash
+uv run {emitEnvelopeHelper} record --workflow skf-export-skill --run-dir "{run_dir}" --decision <<'SKF_JSON'
+{"gate":"update-context.orphan-rows","default_action":"b","taken_action":"b","reason":"headless: managed-section rows with no manifest entry preserved verbatim","evidence":{"rows":["{skill_name} v{version}"]}}
+SKF_JSON
+```
 
 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.
 
@@ -51,19 +59,19 @@ Silent drop under automation would regress the user's managed section without co
 
 ### (a) Drop
 
-Do not include any orphan rows in the rebuilt section. Record:
+Run update-context.md §4b again for every target with `--orphans drop`, so no rebuilt section holds an orphan row. Record:
 
 ```
 orphans_dropped = [{skill_name, version}, …]
 ```
 
-in workflow context for the §6 result contract.
+in workflow context for the step 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.
+Keep the bodies §4b staged: `assemble` already wrote each orphan's `snippet_text` into them verbatim, sorted with the other rows by skill name, **once** per section, and counted it as a stack skill when its row has a `|stack:` line. Nothing is merged by hand.
 
-Append the following entry to the `deviations[]` array in the §6 result contract:
+Append the following entry to the `deviations[]` array in the step 6 result contract:
 
 ```json
 {
@@ -77,7 +85,7 @@ Append the following entry to the `deviations[]` array in the §6 result contrac
 
 `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).
+Every §4b call scans every target file in the same order, so the same orphans are written to **every** target context file: 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
 
@@ -86,17 +94,18 @@ HALT the workflow:
 - Do not rewrite any context file.
 - Do not update the manifest.
 - Do not produce a result contract.
+- Delete the `{export_stage_dir}` folder, as every exit from update-context.md does.
 - 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:
+After this protocol completes, §4c.1 returns control to §5 with these workflow-context variables populated:
 
-- `orphans_dropped: []` — set when the user chose (a) or stayed empty otherwise
+- `orphans_dropped: []`: set when the user chose (a), else empty
 - `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
+- The staged bodies hold the orphan rows verbatim when (b) was chosen, and leave them out 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.
+This gate runs once per export run, not per target context file: every §4b call passes every target file as `--orphan-sources`, so each result lists the same orphans, deduplicated by `(skill_name, version)`. 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/references/package.md

@@ -1,98 +1,40 @@
 ---
 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}. -->
+<!-- Config: communicate in {communication_language}. Render the package status in {document_output_language}. -->
 
 # Step 2: Package
 
 ## STEP GOAL:
 
-To assemble and validate an agentskills.io-compliant package structure from the loaded skill artifacts, ensuring all required components are present and properly formatted for distribution.
+To report each skill's package status from the export-gate verdict step 1 §2 retained, without checking the package again.
 
 ## Rules
 
-- Focus only on package structure assembly and validation — do not modify SKILL.md content
+- Read the verdict, never re-derive a check it covers, and never modify the package
 - Auto-proceed when complete
-- **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.
+- **Multi-skill mode:** when step 1 loaded more than one skill (`len(skill_batch) > 1`), report one row per skill, each from its own verdict. See step 1 §1c.
 
 ## MANDATORY SEQUENCE
 
-### 1. Validate Package Structure
+### 1. Read the Verdict
 
-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:
+Use the export-gate JSON step 1 §2 retained for `{resolved_skill_package}`. Only when it is not in context, run `python3 {validateOutputHelper} {resolved_skill_package} --export-gate` again: the same package gives the same verdict. Step 1 §2 halts on `NOT_READY`, so `export_status` is `READY` or `WARNINGS` here.
 
-```
-{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 3
-├── references/           ← Optional: Progressive disclosure
-│   ├── {function-a}.md
-│   └── {function-b}.md
-├── scripts/              ← Optional: Executable automation
-└── assets/               ← Optional: Templates, schemas, configs
-```
+### 2. Report Package Status
 
-**Component checks — from the export-gate verdict (do not re-derive):**
+"**Package checked.**
 
-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:
+**Status:** {export_status}
+**references/:** {the count of `.md` files under `{resolved_skill_package}/references/`, or none}
 
-- `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 export_status is WARNINGS:}
+**Warnings** (none of them stops the export):
+- {the `field` of each `validation.metadata.recommended_missing` entry, each path in `validation.crossref_7b.orphans`, and the message of each low issue in `validation.metadata.issues`, such as an empty `exports` array or a forge tier in an older stack's `confidence_tier`}"
 
-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
-
-Check metadata.json for recommended (non-required) fields:
-
-- `description` — Brief skill description
-- `source_repo` — Source repository URL
-- `language` — Primary language of source code
-- `ast_node_count` — Number of AST nodes analyzed
-- `tool_versions` — Tools used during generation
-
-**For each missing recommended field:** Note as warning, do not halt.
-
-### 3. Assess Package Readiness
-
-Read `export_status` directly from the export-gate verdict (step 1 §2) — do not re-compute the status by hand:
-
-- **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:** {export_status: READY / WARNINGS}
-
-**Required Components:**
-- SKILL.md: ✅
-- metadata.json: ✅ (required fields valid per export-gate verdict)
-- references/: {✅ present ({count} files) / ⚠️ not present}
-
-{If warnings (export_status: WARNINGS):}
-**Warnings:**
-- {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.**"
-
-### 5. Proceed to Snippet Generation
+### 3. Proceed to Snippet Generation
 
 Display: "**Proceeding to snippet generation...**"
 
-Auto-proceed (no user choices): once package validation is complete, load, read entirely, and execute `{nextStepFile}`.
-
+Auto-proceed (no user choices): load, read entirely, and execute `{nextStepFile}`.

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

@@ -1,98 +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.
-# 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'
+# Loaded by load-skill.md §1b, once per run, only when config.yaml sets no
+# `snippet_skill_root_override`.
 ---
 
-<!-- Config: communicate in {communication_language}. Render the warning and gate prompt in {document_output_language}. -->
+<!-- Config: communicate in {communication_language}. Render the question, the warning and the gate prompt in {document_output_language}. -->
 
-# Snippet Root Prefix Mismatch — Pre-flight Probe
+# Snippet Root 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.
+Decide where the managed section points each skill before step 3 writes a `root:` path. A consuming project points at its IDE's skill folder (`.claude/skills/`, `.cursor/skills/` and so on), where `npx skills add` installs each skill. An authoring repo keeps its skills in one shared folder, such as `skills/`, and sets `snippet_skill_root_override` in `config.yaml`. Only a root an earlier export chose shows the layout: create-skill, create-stack-skill, quick-skill and update-skill write the draft root `skills/{skill-name}/` into every snippet they build, whatever the layout. So a repo whose skills live in `skills/` sets `snippet_skill_root_override: skills/`: a `skills/{skill-name}/` root an earlier export wrote reads as a draft root, and without the override the probe asks the Layout Question, whose headless default is the IDE skill folder.
 
-Loaded by `load-skill.md` §1b after `target_context_files` is resolved and `snippet_skill_root_override` is confirmed unset.
+`{reference_root}` is `target_context_files[0].skill_root`, the root step 3 writes when nothing overrides it.
 
-## Inputs
+## Probe
 
-- `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
+List the snippet of each version the export manifest records: for each skill in step 1 §1's `result.manifest.exports` whose `active_version` has an entry under `versions`, `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md`. A skill the manifest does not list was never exported, so its snippet holds the draft root only. With no snippet to list, go to the Layout Question. Otherwise run:
 
-## Probe Algorithm
+```bash
+python3 {rebuildManagedSectionsHelper} root-probe {snippet-1} {snippet-2} … --reference-root "{reference_root}" --project-root "{project-root}"
+```
 
-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. **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:
+The helper reads each snippet's `root:` prefix and leaves out a snippet that is missing, has no root, or holds the draft root (it lists those skills in `draft_roots`). It returns `observed_prefixes`, `mismatch` (true when one of them is not `{reference_root}`), `mismatched_skills`, and `disk_root`: `{reference_root}` when that folder holds every mismatched skill, else the one observed prefix when that folder holds them all, else null. Then:
 
-   ```bash
-   python3 {rebuildManagedSectionsHelper} root-probe {candidate-snippet-1} {candidate-snippet-2} … --reference-root {target_context_files[0].skill_root}
-   ```
+- `observed_prefixes` is empty: no earlier export chose a root. Ask the Layout Question.
+- `mismatch` is false: every earlier export chose `{reference_root}`. Ask nothing and return to load-skill.md §1b.
+- `mismatch` is true: take the Mismatch Gate.
 
-   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:
+## Layout Question
 
-   ```json
-   {"status": "ok", "reference_root": "…", "observed_prefixes": ["…"], "mismatch": true}
-   ```
+> **Where should the managed section point your skills?** No earlier export has chosen yet. By default each row points at `{reference_root}{skill-name}/`, your IDE's skill folder, where `npx skills add` installs the skill (step 6 prints the command).
+>
+> - **[I] IDE skill folder** (default): point at `{reference_root}`.
+> - **[S] Shared skills folder**: point at the skills where SKF writes them, for a repo that keeps them there. Export, drop-skill and rename-skill read that choice from `config.yaml`.
+> - **[X] Cancel**
 
-   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.
+Wait for the user's choice.
 
-## Mismatch Gate
+- **[I]**: return to load-skill.md §1b.
+- **[S]**: display "Add `snippet_skill_root_override: {skills_prefix}` to `{project-root}/_bmad/skf/config.yaml`, then re-run the export." and HALT (exit code 6, `halt_reason: "user-cancelled"`): the workflow never edits `config.yaml`. `{skills_prefix}` is the path of `{skills_output_folder}` from `{project-root}`, with a trailing `/`, such as `skills/`.
+- **[X]** / `cancel` / `exit` / `:q`: HALT (exit code 6, `halt_reason: "user-cancelled"`). Nothing was written.
+- **GATE [default: I]**: headless, record the decision in the run sink with the command below, log "headless: no earlier export chose a snippet root, using the IDE skill folder", then take [I]. If `record` exits non-zero, display its error line and go on: a failed `record` never stops the run.
 
-**If `result["mismatch"]` is `true`** (some value in `observed_prefixes` does not match the reference `skill_root`):
+```bash
+uv run {emitEnvelopeHelper} record --workflow skf-export-skill --run-dir "{run_dir}" --decision <<'SKF_JSON'
+{"gate":"load-skill.snippet-root-layout","default_action":"I","taken_action":"I","reason":"headless: no earlier export chose a snippet root, using the IDE skill folder","evidence":{"reference_root":"{reference_root}"}}
+SKF_JSON
+```
 
-Emit a single warning (once, not per snippet) and present resolution options before continuing to §2:
+## Mismatch Gate
 
 > **Snippet root prefix mismatch detected.**
-> Existing snippets use: `{observed_prefixes}`
-> IDE-mapped skill_root:  `{target_context_files[0].skill_root}`
+> Earlier exports point at: `{observed_prefixes}`
+> The IDE mapping points at: `{reference_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`, which export, drop-skill and rename-skill all read. Snippets keep their on-disk prefix.
+> - **(b) Proceed with IDE mapping**: every row's root becomes `{reference_root}`. Use this when that folder holds the skills, or will once you install them there.
+> - **(c) Cancel**: abort the export and investigate.
+> - **(d) Use the observed prefix for this run only**: every row's root stays `{observed_prefix}`, and `config.yaml` is not changed. (Offered only when exactly one prefix was observed.)
 >
-> - **(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
+> If several prefixes were observed, the snippets disagree with each other: investigate before choosing (a).
 
-HALT. Exit code 6, `halt_reason: "user-cancelled"`. No files written.
+Wait for the user's choice.
 
-### (d) Use observed prefix for this run only
+**GATE [default: (d) or (b), by the disk]**: headless, take (d) when `disk_root` is the observed prefix (that folder holds the skills and `{reference_root}` does not), else (b): `{reference_root}` holds them, or no folder does yet, as in a project that installs its skills after the export. `{choice}` is the option taken. Log it with the observed prefixes, record the decision in the run sink with the command below (`{disk_root}` is `none` when it is null), then take that option. If `record` exits non-zero, display its error line and go on: a failed `record` never stops the run.
 
-**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.
+```bash
+uv run {emitEnvelopeHelper} record --workflow skf-export-skill --run-dir "{run_dir}" --decision <<'SKF_JSON'
+{"gate":"load-skill.snippet-root-probe","default_action":"{choice}","taken_action":"{choice}","reason":"headless: snippet root prefix mismatch, option {choice} by the folder on disk that holds the skills","evidence":{"observed_prefixes":{observed_prefixes},"reference_root":"{reference_root}","disk_root":"{disk_root}"}}
+SKF_JSON
+```
 
-## No-mismatch fast path
+### Choice handling
 
-**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.
+- **(a) Set override**: display "Add `snippet_skill_root_override: {observed_prefix}` to `{project-root}/_bmad/skf/config.yaml`, then re-run the export." and HALT (exit code 6, `halt_reason: "user-cancelled"`): the workflow never edits `config.yaml`.
+- **(b) Proceed with IDE mapping**: return to load-skill.md §1b. Step 4 writes `{reference_root}` as every row's root.
+- **(c) Cancel**: HALT (exit code 6, `halt_reason: "user-cancelled"`). Nothing was written.
+- **(d) Use the observed prefix for this run only**: bind `{snippet_skill_root_override}` ← the observed prefix for this run, without editing `config.yaml`. Step 3 §2.7 and step 4 §4b read it as they read the `config.yaml` value, so every snippet and row keeps that root. Display "Persist `snippet_skill_root_override: {observed_prefix}` in `{project-root}/_bmad/skf/config.yaml` to skip this question next time: drop-skill and rename-skill read only `config.yaml` when they rebuild the section." Return to load-skill.md §1b.

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

@@ -1,28 +1,43 @@
-<!-- Config: emit exactly as specified — this is a machine-parsed contract. Loaded standalone by any halting stage; it back-references no other file. -->
+<!-- Config: a machine-parsed contract. The shared emitter builds every line; never type one. -->
 
 # 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.
+The single-line `SKF_EXPORT_RESULT_JSON: {…}` envelope export-skill emits on non-interactive (`{headless_mode}`) runs. Pipeline consumers parse it to branch on the run's outcome; `shared/scripts/schemas/skf-export-result-envelope.v1.json` describes each field. The shared emitter builds every line from the payload the run passes it on stdin, checks it against that schema and prints it.
+
+`{emitEnvelopeHelper}` is the emitter SKILL.md's On Activation resolved: the first existing path of `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py` and `{project-root}/src/shared/scripts/skf-emit-result-envelope.py`. `{run_dir}` is the run folder a headless run created under `{project-root}/_bmad-output/.skf-run/`: its sink holds the auto-decision each gate recorded, which the emitter folds into every line as `headless_decisions`.
 
 ## 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.
+- **Success / dry-run:** step 6 (`summary.md` §6) runs `emit` once, on **stdout**, before chaining to step 7.
+- **Every HARD HALT** of a headless run: run `emit-halt` as below, which prints the line on **stderr** with `status: "error"`, then exit with the halt's code (Exit Codes below). An interactive halt displays its message only.
 
-## Shape
+## Emitting a Halt
 
+Each HARD HALT a headless run can reach names its exit code, its `halt_reason` and its phase in the step files; every other field follows the run's state as below. Pass the halt's payload in a quoted heredoc, so no value is expanded. Each value is a JSON string: write a path with `/` in place of `\`, and a quote inside the message as a backtick.
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-export-skill [--run-dir "{run_dir}"] --target stderr <<'SKF_JSON'
+{"phase":"<phase>","reason":"<the halt message>","halt_reason":"<halt_reason>","skills":["<name>"]}
+SKF_JSON
 ```
-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
+- `phase` is the phase the halt site names, `<step file> §<section>` (for example `update-context §9`), and `reason` is the message the halt displays, on one line.
+- `halt_reason` is the value the halt site names. The emitter derives `exit_code` from it and sets `status: "error"`; leave both out.
+- Always pass `skills`, the resolved batch (`[]` only before step 1 bound `skill_batch`, as at every On Activation halt).
+- Add `context_files_updated`, the context files step 4 §9 wrote before the halt, once it has written one, and `manifest_path`, the `{manifest_path}` step 4 §9b bound, once the manifest is written. Before that, leave each out: the emitter gives `context_files_updated` `[]` and `manifest_path` `null`.
+- Pass `--run-dir` once On Activation bound `{run_dir}`, so the line carries the decisions taken before the halt. A halt writes no result file.
+
+Display the line the emitter prints. If it exits non-zero or prints no line, display the halt reason alone.
+
+## Exit Codes
 
-- `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.
+Every HARD HALT exits with a stable code, so headless automators can branch on the failure class without grepping message text:
 
-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.
+| Code | Meaning              | Raised by (halt site → `halt_reason`)                                                         |
+| ---- | -------------------- | -------------------------------------------------------------------------------------------- |
+| 0    | success              | step 7 (terminal); also `status="dry-run"` when `--dry-run` is set                          |
+| 2    | input-missing        | step 1 §1: a headless run with no `skill_name` and no `--all` (a non-interactive run cannot answer the skill-selection menu) → `input-missing` |
+| 3    | resolution-failure   | step 1 §1 (discovery finds no skills on disk / in the manifest; the export manifest does not parse; context-file resolution refuses an unknown `--context-file` value or cannot read the IDE mapping); step 1 §2 (the inventory helper finds no version of a named skill to export, or its required artifacts are missing or its metadata is invalid: export-gate FAIL); multi-skill batch (any skill failing §2 validation halts the whole batch) → `resolution-failure`; step 1 §2 flat fallback (a flat `SKILL.md` with no SKF marker in its `metadata.json`, so SKF will not migrate or export it) → `not-skf-output` |
+| 4    | write-failure        | On-Activation §4 (the run folder cannot be created) or §5 pre-flight write check, or step 4 §9c (a snippet write fails) → `write-failed`; On-Activation §4 (a required helper is missing), step 3 §4 (the token counter fails), step 4 §3b (an orphaned file's clear fails), §4b (the body cannot be built, for example a context file that is not UTF-8 text) or §9 (a write fails its check) → `context-rebuild-failed`; step 4 §9b manifest write → `manifest-write-failed` |
+| 5    | state-conflict       | step 4 §4b or §5: `check` finds a `<!-- SKF:BEGIN` marker that no `<!-- SKF:END -->` closes in a target context file → `malformed-markers` |
+| 6    | user-cancelled       | step 1 §6 gate `[X]`/cancel; step 1 §1b snippet root: the layout question [S]/[X] or the mismatch gate (a)/(c); step 4 §8 gate `[X]`/cancel; step 4 §4c.1 orphan-row (c) Cancel; any prompt accepting `cancel`/`exit`/`:q` → `user-cancelled` |