bmad-module-skill-forge 1.4.1 → 1.5.0

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

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

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

@@ -1,7 +1,9 @@
 ---
-nextStepFile: './step-07-health-check.md'
+nextStepFile: 'health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Render the user-facing summary in {document_output_language}. -->
+
 # Step 6: Summary
 
 ## STEP GOAL:
@@ -12,12 +14,10 @@ To present a complete export summary showing all files written, token counts, an
 
 - Focus only on summarizing what was done and providing next steps — no additional file writes
 - Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing summary is NOT the terminal step
-- **Multi-skill mode:** emit ONE consolidated summary and ONE result contract for the whole batch. The files-written table lists every skill in `skill_batch` (one row per skill's `context-snippet.md` + one row per target managed-section file, shared across the batch). The result contract's `outputs` enumerates every context-snippet file plus every target context file. Distribution instructions (§2) key off `source_authority` per skill — present one block per distinct authority value observed in the batch, listing the skills it applies to. See step-01 §1c.
+- **Multi-skill mode:** emit ONE consolidated summary and ONE result contract for the whole batch. The files-written table lists every skill in `skill_batch` (one row per skill's `context-snippet.md` + one row per target managed-section file, shared across the batch). The result contract's `outputs` enumerates every context-snippet file plus every target context file. Distribution instructions (§2) key off `source_authority` per skill — present one block per distinct authority value observed in the batch, listing the skills it applies to. See step 1 §1c.
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Compile Export Summary
 
 "**Export Complete{if dry-run: ' (Dry Run)'}**
@@ -99,7 +99,7 @@ To install this skill into the current project right now:
 npx skills add {resolved_skill_package}
 ```
 
-Replace `{resolved_skill_package}` with the absolute path to the package folder shown above (from step-02), e.g. `{skills_output_folder}/{skill-name}/{version}/{skill-name}/`.
+Replace `{resolved_skill_package}` with the absolute path to the package folder shown above (from step 2), e.g. `{skills_output_folder}/{skill-name}/{version}/{skill-name}/`.
 
 For other source formats (registry name, git URL, tarball, etc.), see the **Installation → Source Formats** section at <https://www.npmjs.com/package/skills>.
 
@@ -130,18 +130,30 @@ No files were written. To run the export for real:
 
 ### 6. Result Contract
 
-Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skills_output_folder}/export-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{skills_output_folder}/export-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all context files and target managed-section files in `outputs`; include total always-on and on-trigger token counts in `summary`.
+Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skills_output_folder}/export-skill-result-{timestamp}.json` (reuse the activation-stored `{timestamp}`, resolution to seconds) and a copy at `{skills_output_folder}/export-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all context files and target managed-section files in `outputs`; include total always-on and on-trigger token counts in `summary`.
+
+When `{headless_mode}` is true, also emit the single-line envelope on **stdout** before chaining to step 7 (matches the SKILL.md "Result Contract (Headless)" shape):
+
+```
+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}
+```
 
-**`deviations[]` field (export-skill-specific extension):** when step-04 §4c.1 detected manifest-orphan managed rows and the operator (or `{headless_mode}`) chose **(b) Preserve verbatim**, also include a `deviations[]` array in the contract. Each entry has the shape:
+Substitute `{skill_batch_names}`, `{context_files_updated}`, and `{headless_decisions}` as JSON arrays. When `--dry-run` was set, emit `"status":"dry-run"` instead and report what *would* have been written without performing the writes.
+
+**`deviations[]` field (export-skill-specific extension):** when step 4 §4c.1 detected manifest-orphan managed rows and the operator (or `{headless_mode}`) chose **(b) Preserve verbatim**, also include a `deviations[]` array in the contract. Each entry has the shape:
 
 ```json
 {
   "kind": "preserve_external_skills",
-  "skills": [{"name": "skill-name", "version": "1.0.0"}, …],
+  "skills": [
+    {"name": "skill-name", "version": "1.0.0", "source_files": ["CLAUDE.md", ".cursorrules"]}
+  ],
   "rationale": "managed-section row exists but no manifest entry / no source draft"
 }
 ```
 
+`source_files` per skill records the prior context files the orphan was found in (the §4c.1 multi-file scan deduplicates by `(skill, version)` and tracks which target context files originally carried the row — useful when an operator later debugs which IDE's managed section first introduced the external skill).
+
 Other workflow choices that diverge from the strict spec path may add their own entries with a distinct `kind` value — auditors then have one place to look for "what did this run choose to do differently from the canonical flow." Omit the field when there are no deviations rather than writing an empty array, so the absence is readable as "ran the canonical path."
 
 ### 7. Chain to Health Check

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

@@ -1,7 +1,9 @@
 ---
-nextStepFile: './step-06-summary.md'
+nextStepFile: 'summary.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Render the token report in {document_output_language}. -->
+
 # Step 5: Token Report
 
 ## STEP GOAL:
@@ -12,15 +14,13 @@ To calculate approximate token counts for all exported artifacts and present a c
 
 - Focus only on token counting and reporting — read-only measurement
 - Auto-proceed when complete
-- **Multi-skill mode:** when step-01 loaded more than one skill (`len(skill_batch) > 1`), compute token counts per skill, then present one aggregate table with one row per skill (context-snippet.md, SKILL.md, metadata.json, references/, package total). Measure the managed section once for the run — it is shared across the batch. See step-01 §1c.
+- **Multi-skill mode:** when step 1 loaded more than one skill (`len(skill_batch) > 1`), compute token counts per skill, then present one aggregate table with one row per skill (context-snippet.md, SKILL.md, metadata.json, references/, package total). Measure the managed section once for the run — it is shared across the batch. See step 1 §1c.
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Calculate Token Counts
 
-For each artifact, estimate tokens using the heuristic: **words * 1.3** (approximate for GPT/Claude tokenizers). This same heuristic is used in step-03 for snippet token estimation.
+For each artifact, estimate tokens using the heuristic: **words * 1.3** (approximate for GPT/Claude tokenizers). This same heuristic is used in step 3 for snippet token estimation.
 
 **Artifacts to measure:**
 

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

@@ -1,8 +1,32 @@
 ---
-nextStepFile: './step-05-token-report.md'
-managedSectionData: 'assets/managed-section-format.md'
+nextStepFile: 'token-report.md'
+managedSectionData: '{managedSectionFormatPath}'
+# Resolve `{rebuildManagedSectionsHelper}` by probing
+# `{rebuildManagedSectionsProbeOrder}` in order (installed SKF module path
+# first, src/ dev-checkout fallback); first existing path wins. §9 uses
+# the `replace` action for the surgical between-marker swap with
+# atomic temp-file + rename, marker preservation, and post-write verify.
+# HALT if no candidate exists — the in-prompt prose path silently regresses
+# the Case 4 (malformed markers) HARD HALT guarantee.
+rebuildManagedSectionsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-rebuild-managed-sections.py'
+  - '{project-root}/src/shared/scripts/skf-rebuild-managed-sections.py'
+# Resolve `{manifestOpsHelper}` similarly. §9b uses `read` / `set` for
+# atomic v2-schema-aware manifest mutation (handles v1→v2 migration and
+# `platforms`→`ides` rename internally).
+manifestOpsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-manifest-ops.py'
+  - '{project-root}/src/shared/scripts/skf-manifest-ops.py'
+# Resolve `{atomicWriteHelper}` similarly. §6 Case 1 (Create) and §6
+# Case 2 (Append) use it via `write` for safe artifact emission — the
+# in-prompt write would risk half-written files on process kill.
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
+<!-- Config: communicate in {communication_language}. Render the change preview and managed section in {document_output_language}. -->
+
 # Step 4: Update Context
 
 ## STEP GOAL:
@@ -14,16 +38,14 @@ To update the managed `<!-- SKF:BEGIN/END -->` section in the platform-appropria
 - Focus only on the managed section update in the target context file
 - Do not modify any content outside `<!-- SKF:BEGIN -->` and `<!-- SKF:END -->` markers
 - Do not write without user confirmation — this modifies shared project files
-- If `passive_context: false` was detected in step-01, skip this step entirely
-- **Multi-skill mode:** this step executes ONCE for the whole batch, not once per skill. §4b already builds the exported skill set from the manifest (plus current export targets), so a multi-skill run naturally appears as a single rebuild. The only batch adjustment is in §9b: update the manifest entry for every skill in `skill_batch` (not just one), and include all of them when computing `ides_written`. See step-01 §1c.
+- If `passive_context: false` was detected in step 1, skip this step entirely
+- **Multi-skill mode:** this step executes ONCE for the whole batch, not once per skill. §4b already builds the exported skill set from the manifest (plus current export targets), so a multi-skill run naturally appears as a single rebuild. The only batch adjustment is in §9b: update the manifest entry for every skill in `skill_batch` (not just one), and include all of them when computing `ides_written`. See step 1 §1c.
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Check Passive Context Setting
 
-**If `passive_context: false` was detected in step-01:**
+**If `passive_context: false` was detected in step 1:**
 
 "**Passive context disabled in preferences.yaml. Skipping context update.**"
 
@@ -37,7 +59,7 @@ Load {managedSectionData} and read the complete format template and four-case lo
 
 ### 3. Determine Target File(s)
 
-Using the `target_context_files` list resolved in step-01, determine all target files. Each entry has `{context_file, skill_root}` — the context file to write and the IDE's skill directory for root path resolution.
+Using the `target_context_files` list resolved in step 1, determine all target files. Each entry has `{context_file, skill_root}` — the context file to write and the IDE's skill directory for root path resolution.
 
 For each entry in `target_context_files`, resolve target file path: `{context_file}`
 
@@ -49,87 +71,29 @@ For each entry in `target_context_files`, resolve target file path: `{context_fi
 
 A context file becomes orphaned when its IDE is removed from `config.yaml` after a prior export. The file still contains an SKF managed section pointing to stale skill versions, but no future export will rewrite it.
 
-Build `orphaned_context_files` — the set of context files that exist on disk with an `<!-- SKF:BEGIN -->` marker but whose context file is NOT in the current `target_context_files` list:
-
-1. For each known context file in `{CLAUDE.md, .cursorrules, AGENTS.md}`:
-   - If the context file is in `target_context_files`, skip (it will be rewritten in the main loop)
-   - Otherwise, check whether the file exists at `{context_file}`
-   - If the file exists, read it and check for the `<!-- SKF:BEGIN -->` marker
-   - If the marker is present, add the file path to `orphaned_context_files` along with the context file name
-
-2. If `orphaned_context_files` is non-empty, emit a warning:
-
-   "**Orphaned context files detected.** The following files contain SKF managed sections but no configured IDEs target them:
-   {list: context file → file path}
-
-   The managed sections in these files are stale. Options:
-   - **(a) clear** — remove the SKF managed section from each orphaned file (surgical marker replacement, leaves user content intact)
-   - **(b) keep** — leave them untouched (they will remain stale until you re-add an IDE that targets this file or delete the file)
-   - **(c) rewrite** — also rewrite the orphaned files with the current skill index (use this if the IDE was removed by mistake)"
-
-3. Wait for user choice. In non-interactive mode (dry-run or unattended), default to **(b) keep** and print the warning only.
-
-4. If the user chose **(a) clear**: for each orphaned file, replace everything between `<!-- SKF:BEGIN` and `<!-- SKF:END -->` (inclusive) with an empty string, preserving surrounding content byte-exactly. Record the cleared files in `orphans_cleared`.
-
-5. If the user chose **(c) rewrite**: add each orphaned context file to a separate `rewrite_context_files` list (kept distinct from `target_context_files` so the user's intent to only export to configured IDEs is preserved in the manifest). Use `.agents/skills/` as the default skill root for rewritten orphans. Sections 4–9a will loop over `target_context_files + rewrite_context_files` for this run only. Record the rewritten files in `orphans_rewritten`.
+**Cheap pre-check (always run, ~3 file existence checks):** build `orphaned_context_files` — for each known context file in `{CLAUDE.md, .cursorrules, AGENTS.md}` that is NOT in `target_context_files`, check whether it exists on disk and contains the `<!-- SKF:BEGIN -->` marker. If yes, add `{context_file, file_path}` to `orphaned_context_files`.
 
-6. If the user chose **(b) keep**: record nothing and proceed.
+**If `orphaned_context_files` is non-empty:** load `references/orphan-context-detection.md` and follow its (a) clear / (b) keep / (c) rewrite gate protocol. The reference handles user prompting, headless default (keep), and downstream-state recording (`orphans_cleared`, `orphans_rewritten`, `rewrite_context_files`). When the user chooses (c), the §4–§9a loop iterates over `target_context_files + rewrite_context_files`.
 
-This cleanup only runs during interactive export. Drop-skill and rename-skill operate on the manifest's declared context files and are not responsible for orphan detection.
+**If `orphaned_context_files` is empty:** proceed to §4.
 
 ### 4. Rebuild Complete Skill Index
 
 #### 4a. Read Export Manifest (v2 — version-aware)
 
-Read `{skills_output_folder}/.export-manifest.json` — see `knowledge/version-paths.md` for the full v2 schema:
-
-**If the file exists:** Parse JSON. Check for `schema_version` field:
-
-**v2 manifest** (`schema_version: "2"`):
-```json
-{
-  "schema_version": "2",
-  "exports": {
-    "skill-name": {
-      "active_version": "0.6.0",
-      "versions": {
-        "0.1.0": {
-          "ides": ["claude-code"],
-          "last_exported": "2026-01-15",
-          "status": "deprecated"
-        },
-        "0.5.0": {
-          "ides": ["claude-code"],
-          "last_exported": "2026-03-15",
-          "status": "archived"
-        },
-        "0.6.0": {
-          "ides": ["claude-code", "github-copilot"],
-          "last_exported": "2026-04-04",
-          "status": "active"
-        }
-      }
-    }
-  }
-}
+Read the manifest via `{manifestOpsHelper}` (resolved at §9 from `{manifestOpsProbeOrder}` — see frontmatter):
+
+```bash
+python3 {manifestOpsHelper} {skills_output_folder} read
 ```
 
-**Status values:**
-- `"active"` — currently exported; snippet appears in managed sections
-- `"archived"` — previously exported, not active; files retained for rollback
-- `"deprecated"` — dropped via drop-skill workflow; excluded from all exports (files may or may not exist on disk)
-- `"draft"` — created but never exported
+The helper handles v2-schema enforcement, v1→v2 migration, and the `platforms`→`ides` rename internally. The returned JSON is always in canonical v2 shape regardless of on-disk state.
 
-**Legacy `platforms` → `ides` rename:** 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`, treat `platforms` as `ides` and rewrite it to `ides` on the next manifest write. This is a silent in-place upgrade — no user prompt, no v3 bump.
+**Schema reference:** `references/manifest-rebuild.md` documents the v2 shape, the status enum (`active`/`archived`/`deprecated`/`draft`), the v1 migration path, and the `active_version` integrity invariant. Load that file only when an inline schema reminder is needed — the helper enforces the shape so the in-prompt prose is not load-bearing.
 
-**v1 manifest** (no `schema_version` field — migrate in-place to v2):
-1. For each entry in `exports`, read its `last_exported` (v1 had no per-version IDE list)
-2. Resolve the skill's current version from `{resolved_skill_package}/metadata.json`
-3. Wrap in v2 structure: set `active_version` to the resolved version, create a single entry in `versions` with `status: "active"`, `ides: []` (unknown — will be filled on next successful export), and `last_exported`
-4. Set `schema_version: "2"` at root
-5. Hold the migrated structure in context (it will be written in section 9b)
+**Integrity guard:** if the helper returns an entry where `active_version` does not resolve to a key in `versions`, the manifest is inconsistent. Skip the affected skill and log: "**Manifest integrity warning:** `{skill-name}.active_version = v{active_version}` has no matching entry under `versions`. Skipping. Re-run `[EX] Export Skill` on `{skill-name}` to repair the manifest entry."
 
-**If the file does not exist** (first export or migration): Treat as empty — only the current export target will appear in the rebuilt index.
+**If the manifest does not exist** (first export or fresh forge): the helper returns `{"schema_version": "2", "exports": {}}`. Only the current export target will appear in the rebuilt index.
 
 #### 4b. Build Exported Skill Set (version-aware)
 
@@ -158,32 +122,23 @@ Instead of globbing `{skills_output_folder}/*/context-snippet.md`, resolve snipp
 
 #### 4c.1 Detect Orphaned Managed-Section Rows (manifest-absent skills)
 
-A managed-section row becomes orphaned when a `[skill-name v...]` entry already exists in the prior managed section but the skill is not in the exported skill set built in 4b — typically an externally-installed skill that was authored in a different repo and dropped into the user's `{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 an attentive operator caught manually in this run, recording a `deviations[].kind = "preserve_external_skills"` ad-hoc.
-
-Detect this case before §5 assembly so the operator (or `{headless_mode}`) makes an explicit choice:
-
-1. Read the prior managed section from the **first target context file** (`target_context_files[0].context_file`). Parse the `[skill-name v...]` rows between `<!-- SKF:BEGIN -->` and `<!-- SKF:END -->` into `prior_section_rows` — a list of `{skill_name, version}` pairs. If the file does not exist or has no managed section, set `prior_section_rows = []` and skip to §5.
-2. Build `orphan_managed_rows` — every entry in `prior_section_rows` whose `skill_name` is NOT in the exported skill set built in 4b (manifest entries plus current-export targets). For each orphan, capture the original snippet line(s) verbatim from the prior section.
-3. **If `orphan_managed_rows` is non-empty**, present a halt-gate:
-
-   "**Managed-section rows present but absent from manifest:**
-
-   {list each as `- {skill_name} v{version}`}
+A managed-section row becomes orphaned when a `[skill-name v...]` entry already exists in the prior managed section but the skill is not in the exported skill set built in 4b — typically an externally-installed skill 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 is a regression.
 
-   These skills appear in the existing managed section in `{first-context-file}` 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:
+**Cheap pre-check (always run before §5 assembly).** Scan **every** target context file (not just the first), deduplicate by `(skill_name, version)`, and present one consolidated gate. Asymmetric orphans — a row present in `.cursorrules` but absent from `CLAUDE.md`, or vice versa — must be detected; otherwise the §4 rebuild loop silently overwrites the orphan-bearing file's content (ADR-J violation: silent loss of user content).
 
-   - **(a) Drop** — remove these rows from the rebuilt managed section (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 unchanged. Records `deviations[].kind = \"preserve_external_skills\"` with the affected skill names and versions 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 file manually) before re-running."
+1. Initialize `orphan_managed_rows = []` (a list of `{skill_name, version, snippet_text, source_files: []}` entries — `source_files` carries provenance for the gate display and the audit `deviations[]` entry).
+2. **Iterate every entry in `target_context_files`:**
+   a. Read the prior managed section from `{entry.context_file}`. If the file does not exist or has no `<!-- SKF:BEGIN -->` marker, skip this entry — it has no orphans by definition.
+   b. Parse the `[skill-name v...]` rows between `<!-- SKF:BEGIN -->` and `<!-- SKF:END -->` into `file_rows` — a list of `{skill_name, version, snippet_text}` triples (capture the original snippet line(s) verbatim so they can be re-emitted unchanged if (b) is chosen).
+   c. For each `row` in `file_rows`:
+      - If `row.skill_name` is in the exported skill set built in 4b (manifest entries plus current-export targets), skip — not an orphan.
+      - Otherwise look up `(row.skill_name, row.version)` in `orphan_managed_rows`:
+        - If already present, append `entry.context_file` to that row's `source_files` list (deduplicated). Keep the first-encountered `snippet_text` — divergent snippets across files for the same `(skill, version)` are themselves a user-content asymmetry but the `(b) Preserve verbatim` semantic writes one canonical row to every target file, so picking the first is deterministic and avoids silently choosing.
+        - If new, append `{skill_name: row.skill_name, version: row.version, snippet_text: row.snippet_text, source_files: [entry.context_file]}`.
 
-4. **Gate handling:**
-   - **(a) Drop:** Do not include any orphan rows in the rebuilt section. Record `orphans_dropped = [{skill_name, version}, …]` in workflow context for the §6 result contract.
-   - **(b) Preserve verbatim:** Append each captured snippet to the assembled section after the manifest-driven entries, preserving alphabetical order in the merged list. Append `{kind: "preserve_external_skills", skills: [{name, version}, …], rationale: "managed-section row exists but no manifest entry / no source draft"}` to the `deviations[]` array in the §6 result contract. The same orphans are written to **every** target context file in the loop (so all configured IDEs end up with consistent managed sections).
-   - **(c) Cancel:** HALT the workflow. Do not rewrite any context file. Do not update the manifest. Do not produce a result contract.
+**If `orphan_managed_rows` is non-empty:** load `references/orphan-row-detection.md` and follow its (a) Drop / (b) Preserve verbatim / (c) Cancel gate protocol. The reference handles user prompting (with per-orphan `source_files` provenance), headless default (Preserve verbatim), `deviations[]` recording (including `source_files` per orphan for audit), and §6 result-contract integration.
 
-5. **Headless default** (when `{headless_mode}`): auto-select **(b) Preserve verbatim**, with the same `deviations[]` entry. Emit a loud log line: `"headless: {N} managed-section rows had no manifest entry; preserving verbatim with deviations[].kind = preserve_external_skills. Run export-skill against each to migrate them into the manifest."` Silent drop under automation would regress the user's managed section without consent; cancel under automation would block the whole export over an externally-installed skill the user did not author. Preservation matches the prior-attentive-operator convention captured in `skills/export-skill-result-latest.json` deviations.
-
-This detection runs once per export run (not per target context file) — orphan rows are inherent to the prior state of the first context file and the choice is global.
+**If `orphan_managed_rows` is empty:** proceed to §4d.
 
 #### 4d. Rewrite Root Paths for Target Context File
 
@@ -246,8 +201,9 @@ Assemble the complete managed section:
 - Preserved: ALL content before `<!-- SKF:BEGIN` and after `<!-- SKF:END -->`
 
 **Case 4: Malformed markers (file contains `<!-- SKF:BEGIN` but no `<!-- SKF:END -->`)**
-- Action: HALT with warning: "Malformed SKF markers detected in `{target-file}` — `<!-- SKF:BEGIN` found but `<!-- SKF:END -->` is missing. Please restore the end marker manually before running export."
-- Do NOT attempt to write or append — the file is in an inconsistent state
+- Action: HALT (exit code 5, `halt_reason: "malformed-markers"`) with warning: "Malformed SKF markers detected in `{target-file}` — `<!-- SKF:BEGIN` found but `<!-- SKF:END -->` is missing. Please restore the end marker manually before running export."
+- Do NOT attempt to write or append — the file is in an inconsistent state.
+- In headless mode, emit the error envelope per SKILL.md "Result Contract (Headless)" with `manifest_path: null`, `context_files_updated: []`.
 
 ### 7. Present Change Preview
 
@@ -280,18 +236,19 @@ Auto-proceed to {nextStepFile}.
 
 **If NOT dry-run:**
 
-Display: "**Select:** [C] Continue — write changes to {target-file}"
+Display: "**Select:** [C] Continue — write changes to {target-file} | [X] Cancel and exit (or type `cancel` / `exit` / `:q`)"
 
 **Multi-target behavior:** When processing multiple context files, present all previews together before asking for a single confirmation. After confirmation, write all target files sequentially, verifying each one.
 
 "**Targets:** {list all context-file → target-file pairs}
 **Ready to write changes to all targets?**"
 
-Display: "**Select:** [C] Continue — write changes to all targets"
+Display: "**Select:** [C] Continue — write changes to all targets | [X] Cancel and exit"
 
 #### Menu Handling Logic:
 
 - IF C: Write the changes to all target files (or single target), verify each write succeeded, then load, read entire file, then execute {nextStepFile}
+- IF X (or `cancel` / `exit` / `:q`): Display "Cancelled — no context files were written." 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](#8-present-menu-options)
 
 #### EXECUTION RULES:
@@ -303,16 +260,49 @@ Display: "**Select:** [C] Continue — write changes to all targets"
 
 ### 9. Write and Verify (Non-Dry-Run Only)
 
-After user confirms with 'C':
+After user confirms with 'C', resolve the helpers in parallel — these are independent file-existence checks that batch into one tool-call message:
+
+- `{rebuildManagedSectionsHelper}` ← first existing path in `{rebuildManagedSectionsProbeOrder}` (used for Cases 2 and 3)
+- `{atomicWriteHelper}` ← first existing path in `{atomicWriteProbeOrder}` (used for Case 1)
+- `{manifestOpsHelper}` ← first existing path in `{manifestOpsProbeOrder}` (used in §9b)
 
-1. Write the file using the appropriate case logic
-2. Re-read the written file
-3. Verify `<!-- SKF:BEGIN` and `<!-- SKF:END -->` markers are present
-4. Verify content outside markers is unchanged (for Cases 2 and 3)
-5. Report: "**{target-file} updated successfully.** Verified: markers present, external content preserved."
+If any helper has no existing candidate, HALT (exit code 4, `halt_reason: "context-rebuild-failed"`) and emit the error envelope per SKILL.md "Result Contract (Headless)" — the rewrite's safety guarantees depend on these helpers and a fall-through to LLM-driven writes would silently regress atomicity, marker preservation, and the Case 4 malformed-marker HARD HALT contract.
 
-**If verification fails:**
-"**WARNING: Write verification failed.** {describe issue}. File may need manual review."
+For each target context file, dispatch by case:
+
+**Case 1 (Create — file does not exist):**
+
+```bash
+echo "{new_managed_section_text}" | python3 {atomicWriteHelper} write "{target-file}"
+```
+
+The helper stages the content into `<target>.skf-tmp`, fsyncs, and atomically renames into place.
+
+**Case 2 (Append — file exists, no `<!-- SKF:BEGIN` marker):**
+
+```bash
+python3 {rebuildManagedSectionsHelper} {target-file} insert --content "{new_managed_section_text}"
+```
+
+The helper appends the managed section to the end of the file via the same atomic temp-file + rename pattern.
+
+**Case 3 (Regenerate — file contains `<!-- SKF:BEGIN` and `<!-- SKF:END -->`):**
+
+```bash
+python3 {rebuildManagedSectionsHelper} {target-file} replace --content "{new_managed_section_text}"
+```
+
+The helper performs the surgical between-marker swap with post-write verification (markers present, content outside markers byte-identical).
+
+**Case 4 (malformed markers — already HALTed in §6):** never reaches here.
+
+**Verification (deferred to helpers):** the `replace`/`insert`/`write` actions above each perform their own verification. Treat any non-zero exit as a write failure:
+
+- HALT (exit code 4, `halt_reason: "context-rebuild-failed"`) and report `{target-file}: {captured stderr}`.
+- In headless mode, emit the error envelope.
+- Continue to the next target file only on success — partial-batch writes are acceptable in single-skill mode but the overall envelope reports per-target outcomes.
+
+On success per file, report: "**{target-file} updated successfully.** Verified by `{rebuildManagedSectionsHelper}` (or `{atomicWriteHelper}` for Case 1)."
 
 ### 9b. Update Export Manifest (Non-Dry-Run Only)
 
@@ -342,11 +332,17 @@ After user confirms with 'C':
      - If the version already exists in `versions`, union its existing `ides` with `ides_written` (deduplicate, keep sorted), refresh `last_exported`, and set `status: "active"`
      - If this is a new version, add it to `versions` with `status: "active"` and set any previously-active version's status to `"archived"`
      - Preserve all other version entries in `versions` (do not delete archived versions)
-5. Write the updated manifest once to `{skills_output_folder}/.export-manifest.json` after all skills in the batch have been applied
+5. Write the updated manifest atomically via `{manifestOpsHelper}` after all skills in the batch have been applied. For each skill / version pair, invoke:
+
+   ```bash
+   python3 {manifestOpsHelper} {skills_output_folder} set {skill-name} {version}
+   ```
+
+   The helper handles v2-schema validation, v1→v2 migration, and `platforms`→`ides` rename internally — no in-prompt JSON manipulation needed. Each `set` invocation merges the per-version `ides` and `last_exported` fields into the existing entry. After all skills have been set, re-read the manifest via `{manifestOpsHelper} {skills_output_folder} read` to confirm the final state matches expectations.
 
 **Dry-run mode:** Do NOT update the manifest. Display: "**[DRY RUN] Export manifest would be updated for {skill-name-list} — ides: {ides_written}.**" (list every skill in `skill_batch`)
 
-**Error handling:** If manifest write fails, warn but do not fail the workflow — the managed section was already written successfully.
+**Error handling:** If `{manifestOpsHelper}` exits non-zero, HALT (exit code 4, `halt_reason: "manifest-write-failed"`) with the captured `stderr`. The managed section was already written successfully; the operator's recovery path is to manually reconcile the on-disk managed section with the manifest, then re-run `[EX] Export Skill --all` to refresh the manifest. In headless mode, emit the error envelope per SKILL.md "Result Contract (Headless)" with `manifest_path: null` and the partial `context_files_updated` list.
 
 ## CRITICAL STEP COMPLETION NOTE