bmad-module-skill-forge 1.4.1 → 1.5.1

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} --ides {ides_written}
+   ```
+
+   `{ides_written}` is the comma-joined sorted IDE set computed in step 3. The helper handles v2-schema validation, v1→v2 migration, and `platforms`→`ides` rename internally — no in-prompt JSON manipulation needed. Each `set` invocation unions the supplied `--ides` into the version entry's existing `ides` (deduplicated, sorted) server-side and refreshes `last_exported`. 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