bmad-module-skill-forge 2.1.0 → 3.0.0

package/src/skf-drop-skill/scripts/drop-roster.py

@@ -0,0 +1,322 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+"""Drop Skill roster: the two lists a drop reads, each from one call.
+
+  skills <skills-folder> --forge-data-folder <path> [--skill <name>]
+      select.md section 2: every skill the drop can offer (section 3 lists
+      it). It joins the export manifest, read through skf-manifest-ops.py
+      (which migrates a v1 manifest), with the on-disk scan of
+      skf-skill-inventory.py: each manifest skill, and each skill SKF
+      generated that the manifest does not list (a draft, which only a purge
+      can drop). A folder holding a skill SKF did not generate is never
+      offered: it is listed in `not_offered`, with the scan's errors for it.
+      Each skill carries its versions newest first, in the order
+      skf-skill-inventory.py resolve gives them (numeric, so 0.10.0 comes
+      before 0.9.0), each with its manifest status, last export date and
+      IDEs, and the counts the active-version guard and the blast-radius
+      line read. With --skill the roster holds that skill only, so a run
+      given its target reads one skill rather than every one; `empty` and
+      `not_offered` still cover the whole folder.
+
+      Without skf-skill-inventory.py (an older or broken install), or when
+      its scan or resolve fails, `inventory` is false and the roster holds
+      the manifest skills alone: SKF cannot check that it generated a folder
+      the manifest does not list, so none is offered.
+
+  rows --skill <name> [--version <v>]... <context-file>...
+      execute.md section 5: the managed-section rows the context files still
+      hold for a skill (for those versions only, with --version), as
+      {file, version}, read with the parser skf-rebuild-managed-sections.py
+      writes the section with. A row's snippet text never comes back. A file
+      whose markers are malformed, or that cannot be read, is listed in
+      `unchecked` with the reason: its rows are unknown. A missing file holds
+      no row.
+
+Both shared scripts are read from the shared scripts folder beside this
+skill's folder (shared/scripts/), where the installer puts them in an
+installed project as in this checkout.
+
+Output (stdout, one JSON object):
+
+  skills: {"status": "ok", "inventory": bool, "inventory_error": str|null,
+           "skills": [{"name", "in_manifest", "purge_only", "active_version",
+                       "layout": "versioned"|"flat"|"none"|null,
+                       "versions": [{"version", "status", "active",
+                                     "in_manifest", "on_disk",
+                                     "last_exported", "ides"}],
+                       "counts": {"non_deprecated", "on_disk"}}],
+           "not_offered": [{"name", "errors"}], "empty": bool}
+  rows:   {"status": "ok", "skill", "versions": [...]|null,
+           "rows": [{"file", "version"}], "unchecked": [{"file", "error"}]}
+
+`status` of a version is its manifest status, null for a folder the manifest
+does not list; `active` marks the manifest's active_version. `counts` gives
+`non_deprecated` (the manifest versions whose status is not "deprecated")
+and `on_disk` (the version folders; null without the inventory helper).
+
+Exit codes:
+  0  status "ok"
+  1  status "error", with a `code`: manifest-corrupt (the export manifest
+     exists but does not parse, is not UTF-8 or is not an object of entry
+     objects; `path` names it) or helper-missing (a shared script this one
+     reads cannot be loaded)
+  2  usage error (JSON on stderr)
+"""
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+# Installed (under _bmad/skf/ or an IDE's skills folder) and in a dev
+# checkout (src/), shared/ sits beside this skill's folder.
+SHARED_SCRIPTS = Path(__file__).resolve().parent.parent.parent / "shared" / "scripts"
+MANIFEST_OPS = "skf-manifest-ops.py"
+INVENTORY = "skf-skill-inventory.py"
+REBUILD = "skf-rebuild-managed-sections.py"
+MANIFEST_FILE = ".export-manifest.json"
+# What a shared helper raises on a file it cannot read as it expects (a
+# manifest of the wrong shape or encoding, a folder it cannot list).
+HELPER_ERRORS = (AttributeError, TypeError, ValueError, OSError)
+
+
+def _load(filename: str):
+    """(module, None) for a shared script, or (None, the reason it cannot load)."""
+    path = SHARED_SCRIPTS / filename
+    try:
+        spec = importlib.util.spec_from_file_location(filename[:-3].replace("-", "_"), path)
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+    except (ImportError, OSError, AttributeError, SyntaxError) as e:
+        return None, f"cannot load {filename} from {SHARED_SCRIPTS} ({e}): re-install SKF"
+    return module, None
+
+
+def _plain_name(value) -> bool:
+    """True for a name that is one folder name and nothing else."""
+    return isinstance(value, str) and value not in ("", ".", "..") and not any(c in value for c in "/\\:\0")
+
+
+def _manifest_rows(entry) -> tuple[str | None, dict]:
+    """(active_version, {version: {status, last_exported, ides}}) of a migrated manifest entry."""
+    if not isinstance(entry, dict):
+        return None, {}
+    active = entry.get("active_version")
+    active = active if isinstance(active, str) and active else None
+    versions = entry.get("versions")
+    records = {}
+    if isinstance(versions, dict):
+        for version, record in versions.items():
+            record = record if isinstance(record, dict) else {}
+            status = record.get("status")
+            last = record.get("last_exported")
+            ides = record.get("ides")
+            records[version] = {
+                "status": status if isinstance(status, str) else None,
+                "last_exported": last if isinstance(last, str) and last else None,
+                "ides": [i for i in ides if isinstance(i, str)] if isinstance(ides, list) else [],
+            }
+    return active, records
+
+
+def _version_row(version: str, active: str | None, records: dict, on_disk: bool) -> dict:
+    record = records.get(version, {})
+    return {
+        "version": version,
+        "status": record.get("status"),
+        "active": version == active,
+        "in_manifest": version in records,
+        "on_disk": on_disk,
+        "last_exported": record.get("last_exported"),
+        "ides": record.get("ides", []),
+    }
+
+
+def _skill(name, entry, ops, manifest_path, inventory, skills_folder, forge_folder) -> dict:
+    """One roster entry: the skill's versions newest first, with their manifest records and counts."""
+    active, records = _manifest_rows(entry)
+    in_manifest = entry is not None
+    resolved = None
+    if inventory is not None and _plain_name(name):
+        resolved = inventory.resolve_skill(skills_folder, name, forge_folder)
+    if resolved is not None:
+        rows = [_version_row(r["version"], active, records, r["on_disk"]) for r in resolved["versions"]]
+        layout = resolved["layout"]
+    else:
+        # No on-disk scan: the manifest's versions, in the manifest helper's order.
+        ordered = ops.cmd_affected_versions(manifest_path, skills_folder, name).get("sources", {}).get("manifest", [])
+        rows = [_version_row(v, active, records, False) for v in ordered if v in records]
+        layout = None
+    return {
+        "name": name,
+        "in_manifest": in_manifest,
+        "purge_only": not in_manifest,
+        "active_version": active,
+        "layout": layout,
+        "versions": rows,
+        "counts": {
+            "non_deprecated": sum(1 for r in rows if r["in_manifest"] and r["status"] != "deprecated"),
+            "on_disk": sum(1 for r in rows if r["on_disk"]) if resolved is not None else None,
+        },
+    }
+
+
+def _read_manifest(ops, manifest_path: Path) -> tuple[dict | None, str | None]:
+    """(data, None), or (None, why the manifest cannot be read as one).
+
+    The manifest helper reports a file that is not JSON; a JSON value of the
+    wrong shape (a list, or an entry that is not an object) or a file that is
+    not UTF-8 makes it raise instead, which is the same corrupt manifest.
+    """
+    try:
+        data, err = ops.read_manifest(manifest_path)
+    except HELPER_ERRORS as e:
+        return None, f"Manifest cannot be read: {type(e).__name__}: {e}"
+    if err:
+        return None, err
+    if not isinstance(data, dict) or not isinstance(data.get("exports", {}), dict):
+        return None, "Manifest is not an object with an `exports` object"
+    return data, None
+
+
+def roster(skills_folder: str, forge_folder: str, only: str | None = None) -> tuple[dict, int]:
+    """The `skills` result and its exit code."""
+    ops, err = _load(MANIFEST_OPS)
+    if ops is None:
+        return {"status": "error", "code": "helper-missing", "error": err}, 1
+    manifest_path = Path(skills_folder) / MANIFEST_FILE
+    data, err = _read_manifest(ops, manifest_path)
+    if err:
+        return {"status": "error", "code": "manifest-corrupt", "error": err, "path": str(manifest_path)}, 1
+    exports = data.get("exports", {})
+
+    inventory, inventory_error = _load(INVENTORY)
+    drafts, not_offered = [], []
+    if inventory is not None:
+        try:
+            scan = inventory.scan_inventory(skills_folder, forge_data_folder=forge_folder)
+        except HELPER_ERRORS as e:
+            scan = {"status": "error", "error": f"the inventory scan failed: {type(e).__name__}: {e}"}
+        if scan.get("status") == "ok":
+            for found in scan["skills"]:
+                if found.get("skf_skill") and found["name"] not in exports:
+                    drafts.append(found["name"])
+            errors = {found["name"]: found.get("errors", []) for found in scan["skills"]}
+            not_offered = [{"name": name, "errors": errors.get(name, [])}
+                           for name in scan.get("not_skf_output", []) if name not in exports]
+        elif scan.get("code") != "DIR_NOT_FOUND":  # a missing folder holds no skill
+            inventory, inventory_error = None, scan.get("error", "the inventory scan failed")
+
+    names = sorted(exports) + sorted(drafts)
+    listed = [n for n in names if n == only] if only is not None else names
+    try:
+        skills = [_skill(name, exports.get(name), ops, manifest_path, inventory, skills_folder, forge_folder)
+                  for name in listed]
+    except HELPER_ERRORS as e:
+        if inventory is None:
+            raise
+        # A resolve that fails is a scan that failed: the manifest skills alone, as without the helper.
+        inventory, inventory_error = None, f"the inventory resolve failed: {type(e).__name__}: {e}"
+        drafts, not_offered = [], []
+        names = sorted(exports)
+        listed = [n for n in names if n == only] if only is not None else names
+        skills = [_skill(name, exports.get(name), ops, manifest_path, None, skills_folder, forge_folder)
+                  for name in listed]
+    return {
+        "status": "ok",
+        "inventory": inventory is not None,
+        "inventory_error": None if inventory is not None else inventory_error,
+        "skills": skills,
+        "not_offered": not_offered,
+        "empty": not names,
+    }, 0
+
+
+def rows(skill: str, versions: list[str], context_files: list[str]) -> tuple[dict, int]:
+    """The `rows` result and its exit code."""
+    rebuild, err = _load(REBUILD)
+    if rebuild is None:
+        return {"status": "error", "code": "helper-missing", "error": err}, 1
+    found, unchecked = [], []
+    for path in context_files:
+        content, err = rebuild.read_context_file(path)
+        if err:
+            if not rebuild.is_missing(err):
+                unchecked.append({"file": path, "error": err})
+            continue
+        problem = rebuild.find_unclosed_begin(content)
+        if problem:
+            unchecked.append({"file": path, "error": f"malformed markers: {problem[1]}"})
+            continue
+        match = rebuild.find_managed_section(content)
+        if not match:
+            continue
+        for row in rebuild.parse_managed_rows(match.group(2)):
+            if row["skill_name"] == skill and (not versions or row["version"] in versions):
+                found.append({"file": path, "version": row["version"]})
+    return {"status": "ok", "skill": skill, "versions": versions or None, "rows": found,
+            "unchecked": unchecked}, 0
+
+
+class _JsonErrorParser(argparse.ArgumentParser):
+    """Report a usage error as JSON on stderr with exit 2, the subcommands included."""
+
+    def error(self, message: str) -> None:
+        print(json.dumps({"status": "error", "error": f"usage error: {self.prog}: {message}"}), file=sys.stderr)
+        sys.exit(2)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = _JsonErrorParser(
+        prog="drop-roster.py",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    sub = parser.add_subparsers(dest="op", required=True, metavar="{skills,rows}")
+
+    p_skills = sub.add_parser("skills", help="the skills a drop can offer, with their versions")
+    p_skills.add_argument("skills_folder", metavar="skills-folder", help="{skills_output_folder}")
+    p_skills.add_argument("--forge-data-folder", required=True, help="{forge_data_folder}")
+    p_skills.add_argument("--skill", help="list this skill only (the name the run was given)")
+
+    p_rows = sub.add_parser("rows", help="the managed-section rows the context files hold for a skill")
+    p_rows.add_argument("--skill", required=True, help="the skill whose rows to list")
+    p_rows.add_argument("--version", action="append", default=[], dest="versions",
+                        help="list the rows of this version only (repeatable)")
+    p_rows.add_argument("context_files", nargs="+", metavar="context-file", help="a context file to read")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    if args.op == "skills":
+        result, code = roster(args.skills_folder, args.forge_data_folder, args.skill)
+    else:
+        result, code = rows(args.skill, args.versions, args.context_files)
+    print(json.dumps(result, indent=2))
+    return code
+
+
+def _force_utf8(*streams) -> None:
+    """Reconfigure stdout and stderr to UTF-8, keeping each stream's error handler.
+
+    A Windows console pipes them as cp1252, which cannot print every character
+    a path may hold.
+    """
+    for stream in streams:
+        if hasattr(stream, "reconfigure"):
+            errors = getattr(stream, "errors", None)
+            if errors is None:
+                stream.reconfigure(encoding="utf-8")
+            else:
+                stream.reconfigure(encoding="utf-8", errors=errors)
+
+
+if __name__ == "__main__":
+    _force_utf8(sys.stdout, sys.stderr)
+    sys.exit(main())

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

@@ -1,36 +1,37 @@
 ---
 name: skf-export-skill
-description: Package for distribution and inject context into CLAUDE.md/AGENTS.md/.cursorrules. Use when the user requests to "export" or "package a skill."
+description: Exports an SKF skill, validating its package, writing its context snippet and updating the managed section in CLAUDE.md, AGENTS.md or .cursorrules. Use when the user requests to "export a skill" or "package a skill."
 ---
 
 # Export Skill
 
 ## Overview
 
-Packages a completed skill as an agentskills.io-compliant package, generates context snippets, and updates the managed section in CLAUDE.md/.cursorrules/AGENTS.md for platform-aware context injection. It is the sole publishing gate — create-skill/update-skill produce drafts; only export writes platform context files and distribution packages.
+Checks a completed skill against the agentskills.io export gate, writes its context snippet and updates the managed section in CLAUDE.md, AGENTS.md or .cursorrules. It is the sole publishing gate: create-skill and update-skill produce drafts, and only export writes the context files and records the skill in `.export-manifest.json`.
 
 ## Conventions
 
 - Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
-- **Module-level path exception:** bare `knowledge/` and `shared/` paths resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root (e.g. `knowledge/version-paths.md`, `shared/health-check.md`).
-- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root; for example `knowledge/version-paths.md` and `shared/health-check.md`.
+- **Sibling skills:** a path that names another SKF skill's folder (`skf-<name>/...`) resolves from the SKF module root, and that skill must be installed with this one.
+- `references/` holds the workflow stages, chained by frontmatter `nextStepFile`; the files a stage loads when it needs them (`load-skill.md` loads `multi-skill-mode.md` and `preflight-snippet-root-probe.md`, `update-context.md` loads `orphan-context-detection.md`, `orphan-row-detection.md` and `manifest-rebuild.md`); and the headless contract (`invocation-contract.md`, `result-envelope.md`). `assets/` holds the snippet and managed-section templates.
 - `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
 - `{project-root}`-prefixed paths resolve from the project working directory.
 - `{skill-name}` resolves to the skill directory's basename.
-- **Cross-skill data coupling:** `assets/managed-section-format.md` (loaded by drop-skill and rename-skill's `execute.md`) and `references/update-context.md` §4a (v2 manifest schema enforced by `skf-manifest-ops.py`) are the source of truth for those contracts — schema-breaking changes here need coordinated updates across those skills.
+- **Cross-skill data coupling:** export-skill, drop-skill and rename-skill write the managed section only through `shared/scripts/skf-rebuild-managed-sections.py`, in the format `assets/managed-section-format.md` documents, and change `.export-manifest.json` only through `shared/scripts/skf-manifest-ops.py` (v2 schema in `references/manifest-rebuild.md`). A change to either contract changes all three skills.
 
 ## Role
 
-You are a delivery and packaging specialist collaborating with a skill developer, pairing your skill-packaging, ecosystem-compliance, and context-injection expertise with their completed skill and distribution requirements.
+You are Ferris in Delivery mode, a packaging specialist: you check a developer's completed skill against the ecosystem rules and inject it into the context files it targets.
 
 ## Workflow Rules
 
-These rules apply to every step in this workflow:
-
 - Only load one step file at a time — never preload future steps
 - Always communicate in `{communication_language}`
 - At any interactive prompt, the inputs `cancel`, `exit`, `[X]`, `q`, or `:q` exit cleanly with exit code 6 (`halt_reason: "user-cancelled"`)
-- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and record each auto-decision in the run sink (`references/result-envelope.md`)
+- Every HALT names its exit code, `halt_reason` and phase; in headless mode it first emits its envelope as `references/result-envelope.md` states
+- **Snippet timing:** step 3 only stages each `context-snippet.md` outside the project; step 4 §9c copies it into the skill package after its [C] gate, as step 4's last write. A cancel, a dry run or a halt before §9c leaves every snippet, and a carried gotchas line's one `[CARRIED]` cycle, as it was.
 
 ## Stages
 
@@ -46,77 +47,52 @@ These rules apply to every step in this workflow:
 
 ## Invocation Contract
 
-| Aspect | Detail |
-|--------|--------|
-| **Inputs** | `skill_name` [one or more, required unless `--all`] |
-| **Flags** | `--headless` / `-H` (auto-resolve all gates); `--all` (export every non-deprecated skill in `.export-manifest.json`); `--dry-run` (stage everything but write nothing — context files, manifest, and snippet are previewed only; the run completes read-only through the terminal step; `status="dry-run"`) |
-| **Gates** | step 1: single Confirm Gate [C] for the whole batch | step 4: single Confirm Gate [C] for the whole batch |
-| **Outputs** | Updated `.export-manifest.json` (every skill in the batch), updated context files (CLAUDE.md/AGENTS.md/.cursorrules), per-skill `context-snippet.md`, per-run result contract `export-skill-result-{timestamp}.json` and `export-skill-result-latest.json` |
-| **Multi-skill mode** | Activated when more than one skill is selected (via `--all`, multi-selection, or multi-argument invocation). See `references/load-skill.md` §1c for the per-step iteration map. |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. Each auto-resolved gate appends a `{gate, default_action, taken_action, reason}` entry to `headless_decisions[]`, surfaced in step 6's `SKF_EXPORT_RESULT_JSON` envelope so non-interactive runs can be audited post-hoc. |
-| **Exit codes** | See "Exit Codes" below |
-
-## Exit Codes
-
-Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
-
-| 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 — 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); step 1 §2 (a named skill's 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` |
-| 4    | write-failure        | On-Activation §5 pre-flight write probe → `write-failed`; step 4 §3b / §9 / §4c.1 (managed-section create/append/rewrite/clear verify fails, or a required helper is unresolvable) → `context-rebuild-failed`; step 4 §9b manifest write → `manifest-write-failed` |
-| 5    | state-conflict       | step 4 §6 — malformed `<!-- SKF:BEGIN/END -->` markers in the target context file (`<!-- SKF:BEGIN` present, `<!-- SKF:END -->` missing) → `malformed-markers` |
-| 6    | user-cancelled       | step 1 §6 gate `[X]`/cancel; step 1 §1b snippet-root probe (a)/(c); step 4 §8 gate `[X]`/cancel; step 4 §4c.1 orphan-row (c) Cancel; any prompt accepting `cancel`/`exit`/`:q` → `user-cancelled` |
-
-## Result Contract (Headless)
-
-When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
-
-```
-SKF_EXPORT_RESULT_JSON: {"status":"success|error|dry-run","skills":[],"context_files_updated":[],"manifest_path":"…|null","headless_decisions":[],"exit_code":0,"halt_reason":null}
-```
-
-`references/result-envelope.md` is the single source for the full field semantics and the `halt_reason` enum — halting stages load it directly, so the enum lives in exactly one place. `exit_code` matches the Exit Codes table above.
+Headless callers and pipelines: the inputs, flags, gates, outputs and exit codes are in `references/invocation-contract.md`, and the `SKF_EXPORT_RESULT_JSON` envelope in `references/result-envelope.md`. Interactive runs do not need them.
 
 ## On Activation
 
 1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
    - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
    - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
-   - `snippet_skill_root_override` (optional string) — when set, overrides the IDE-derived `skill_root` for snippet `root:` paths. Authoring repos that keep all skills under a single on-disk folder (e.g. `skills/`) set this once so exported snippets reference the real layout instead of a per-IDE directory that does not exist. Consuming projects omit it.
+   - `snippet_skill_root_override` (optional): the `root:` prefix of every snippet and managed-section row in place of the IDE skill folder, for an authoring repo that keeps its skills in one folder such as `skills/`; step 1's snippet-root option (d) sets it for one run without changing `config.yaml`.
 
-2. **Compute run-scoped variables:**
-   - `timestamp` ← UTC `YYYYMMDD-HHmmss` captured at activation time. Fixed for the entire workflow run; summary.md reuses this when writing the result contract.
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
 
-3. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
-
-4. **Resolve workflow customization.** Run:
+3. **Resolve workflow customization.** Run:
 
    ```bash
-   python3 {project-root}/_bmad/scripts/resolve_customization.py \
-       --skill {skill-root} --key workflow
+   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-export-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. Keep the reason as `{customization_resolver_unavailable}` (unset when the resolver ran): a headless run records it once step 4 creates its run folder, and an interactive run only prints it.
 
-   - `{skill-root}/customize.toml` — bundled defaults
-   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
-   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+   Bind each scalar to its bundled default when the merged value is empty or absent:
 
-   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+   - `{snippetFormatPath}` ← `workflow.snippet_format_path`, else `assets/snippet-format.md`
+   - `{onCompleteCommand}` ← `workflow.on_complete`, else empty (step 6 then runs no hook)
 
-   Apply the fallback now so stage files don't have to repeat the conditional logic. For each scalar, if the merged value is empty or absent, use the bundled default:
+   Then apply the array surfaces: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (`file:`-prefixed entries are paths or globs whose contents load as facts: the bundled default loads every `project-context.md` under `{project-root}`; an entry prefixed `!` drops each earlier entry it names and loads nothing itself, so an override's `"!file:{project-root}/**/project-context.md"` turns that default off); then, after activation completes and before the first stage runs, execute each entry in `workflow.activation_steps_append` in order.
 
-   - `{managedSectionFormatPath}` ← `workflow.managed_section_format_path` if non-empty, else `assets/managed-section-format.md`
-   - `{snippetFormatPath}` ← `workflow.snippet_format_path` if non-empty, else `assets/snippet-format.md`
-   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string (no-op — step 6 skips the hook invocation)
+4. **Resolve the helpers and create the run folder.** Resolve each helper to the first of its two paths that exists, the installed module first, all in parallel:
 
-   Stash all three as workflow-context variables. Stage files reference them directly — no conditional at the usage site.
+   - `{emitEnvelopeHelper}` ← 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` (every envelope, result file and headless record).
+   - `{manifestOpsHelper}` ← `{project-root}/_bmad/skf/shared/scripts/skf-manifest-ops.py`, else `{project-root}/src/shared/scripts/skf-manifest-ops.py` (steps 1, 3 and 4).
+   - `{skillInventoryHelper}` ← `{project-root}/_bmad/skf/shared/scripts/skf-skill-inventory.py`, else `{project-root}/src/shared/scripts/skf-skill-inventory.py` (step 1).
+   - `{rebuildManagedSectionsHelper}` ← `{project-root}/_bmad/skf/shared/scripts/skf-rebuild-managed-sections.py`, else `{project-root}/src/shared/scripts/skf-rebuild-managed-sections.py` (steps 1 and 4).
+   - `{validateOutputHelper}` ← `{project-root}/_bmad/skf/shared/scripts/skf-validate-output.py`, else `{project-root}/src/shared/scripts/skf-validate-output.py` (steps 1 and 2).
+   - `{countTokensHelper}` ← `{project-root}/_bmad/skf/shared/scripts/skf-count-tokens.py`, else `{project-root}/src/shared/scripts/skf-count-tokens.py` (steps 3 and 5).
 
-   **Apply the array surfaces so they are not silent no-ops:** execute each entry in `workflow.activation_steps_prepend` in order now (org-wide pre-flight such as auth, network, or compliance); treat every entry in `workflow.persistent_facts` as standing context for the whole run (`file:`-prefixed entries are paths or globs whose contents load as facts — the bundled default loads any `project-context.md`); then, after activation completes and before the first stage runs, execute each entry in `workflow.activation_steps_append` in order.
+   No step has a fallback for them, so check them all here, before any prompt or write. If one has no existing path, HALT (exit code 4, `halt_reason: "context-rebuild-failed"`) at phase `on-activation §4`: "`{the missing helper's file name}` is missing. Nothing was changed. Re-install SKF."
 
-5. **Pre-flight write probe.** Verify `{skills_output_folder}` is writable. A read-only mount, full disk, or permissions-denied path otherwise only surfaces at step 4's managed-section rewrite — by then the user has already confirmed the batch:
+   When `{headless_mode}` is true, create the run folder, whose sink holds the headless auto-decisions:
+
+   ```bash
+   mkdir -p "{project-root}/_bmad-output/.skf-run" && mktemp -d "{project-root}/_bmad-output/.skf-run/skf-export-skill-XXXXXXXX"
+   ```
+
+   Bind `{run_dir}` ← the path it prints. Step 6 deletes it once the run's envelope is built; a HARD HALT leaves it in place. If it cannot be created, HALT (exit code 4, `halt_reason: "write-failed"`) at phase `on-activation §4`. When `{customization_resolver_unavailable}` is set, record it there: write `customization_resolver_unavailable: <reason>` to `{run_dir}/resolver-warning.txt` with a file write (a resolver error can hold quotes or `$( )`, so never echo it or type it into an argument), then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/resolver-warning.txt")"` from `{project-root}`.
+
+5. **Pre-flight write check.** Verify `{skills_output_folder}` is writable, so a read-only mount, a full disk or a denied path stops the run before the user confirms a batch. Without `--dry-run`, probe it with a write:
 
    ```bash
    mkdir -p "{skills_output_folder}" && \
@@ -124,6 +100,8 @@ SKF_EXPORT_RESULT_JSON: {"status":"success|error|dry-run","skills":[],"context_f
      rm "{skills_output_folder}/.skf-write-probe"
    ```
 
-   On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`). In headless mode, emit the error envelope per `references/result-envelope.md` with `skills: []`, `context_files_updated: []`, `manifest_path: null`.
+   With `--dry-run`, check without writing: `test -w "{skills_output_folder}"` when the folder exists; when it does not, skip the check, since step 1 then finds no skill to export.
+
+   On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`) at phase `on-activation §5`.
 
 6. Load, read the full file, and then execute `references/load-skill.md` to begin the workflow.

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

@@ -14,9 +14,11 @@
 <!-- SKF:END -->
 ```
 
+`skf-rebuild-managed-sections.py` writes this section for export-skill, drop-skill and rename-skill. Its `assemble` action builds the body between the markers, and its `insert` and `replace` actions write both markers and the `updated:` date around that body, so the three skills write the same bytes for the same manifest and snippets.
+
 ## IDE → Context File Mapping (config.yaml `ides` list)
 
-The installer writes IDE identifiers to `config.yaml` under the `ides` key. Any workflow that rebuilds context files from `config.yaml` MUST map each entry to its context file and skill root using this table — it is the **single source of truth**.
+The installer writes IDE identifiers to `config.yaml` under the `ides` key. The helper's `resolve-targets` action maps each one to its context file and skill root from `shared/data/ide-context-files.json`, the one mapping export-skill, drop-skill and rename-skill read. The tables below show that file for readers, and a test keeps them equal to it.
 
 Each IDE has two independent properties:
 
@@ -62,74 +64,36 @@ All other IDEs use AGENTS.md as the context file, each with its own skill direct
 
 ### Resolution rules
 
-**Deduplication:** When multiple IDE entries map to the same context file, deduplicate so each context file is processed exactly once. Use the **first configured IDE's** skill root for that context file's snippet root paths. Report the deduplication to the user: "Multiple IDEs target AGENTS.md — using {first IDE}'s skill root (`{skill_root}`). Each IDE's skills are installed to its own directory."
-
-**Missing `ides` key:** If the `ides` key is absent from `config.yaml`, treat it as an empty list. If the resulting set is empty (no recognized entries), fall back to AGENTS.md with `.agents/skills/` as the skill root.
-
-**Unknown IDE values:** Warn: "Unknown IDE '{value}' in config.yaml — defaulting to AGENTS.md with `.agents/skills/`"
+`resolve-targets` returns one target per context file, with the warnings and notes to show: IDEs that share a context file take the first configured IDE's skill root, and an absent, empty or unknown IDE resolves to AGENTS.md with `.agents/skills/`. To add an IDE, add it to the shared mapping; no workflow setting changes the mapping.
 
 **`snippet_skill_root_override` (optional):** Authoring repos where all skills live under one shared on-disk directory (e.g. `skills/`) that does not match any per-IDE skill root may set `snippet_skill_root_override: skills/` in `config.yaml`. When set:
 
 - `export-skill/step 3` §2.7 uses the override as `{skill_root}` for snippet generation instead of the IDE-mapped value
-- `export-skill/step 4` §4d (and its equivalents in `drop-skill/step 2` and `rename-skill/step 2`) treat the override as the effective target prefix for the managed-section rebuild: snippets whose prefix already matches the override pass through unchanged, and any other prefix — including per-IDE prefixes carried by sibling snippets that were exported before the override was adopted, and legacy `skills/` drafts — is rewritten to the override so the rebuilt managed section uniformly references the real on-disk location
+- export-skill, drop-skill and rename-skill pass it to `assemble` as `--skill-root-override`, which makes it the `root:` prefix of every row it writes: a snippet whose prefix already matches passes through unchanged, and any other prefix (a per-IDE prefix on a snippet exported before the override was adopted, or a legacy `skills/` draft) is rewritten to it, so the section uniformly references the real on-disk location
 
 Consuming projects (the common case) omit the field and keep the default IDE-mapping behavior. The override is a narrow escape hatch for repos that author skills into `{skills_output_folder}` and never duplicate them into `.claude/skills/`-style directories.
 
 ### Consumers
 
-This mapping is the single source of truth. Workflows that need it: `export-skill/step 1` (resolves `target_context_files` from config.yaml IDE list), `export-skill/step 4` (applies four-case logic and rewrites root paths when writing managed sections), `drop-skill/step 2` and `rename-skill/step 2` (rebuild context files after a management operation).
+Workflows that resolve context files through `resolve-targets`: `export-skill/step 1` (the target context files), `drop-skill/step 1` (the confirmation's context-file count) and step 2, and `rename-skill/step 2` (the rebuild after a management operation).
 
 ## Four-Case Logic
 
-### Case 1: Create (No File Exists)
-
-Target file does not exist. Create new file with managed section only.
-
-```markdown
-<!-- SKF:BEGIN updated:{date} -->
-{managed section content}
-<!-- SKF:END -->
-```
-
-### Case 2: Append (File Exists, No Section)
-
-Target file exists but contains no `<!-- SKF:BEGIN` marker. Append managed section at end of file.
-
-1. Read existing file content
-2. Append two blank lines
-3. Append managed section with markers
-4. Write file
-
-### Case 3: Regenerate (Existing Section)
+`skf-rebuild-managed-sections.py <context-file> check` reports the case of each context file as `case`, and the case picks the write. Both writes take only the body between the markers, as `assemble` stages it:
 
-Target file contains `<!-- SKF:BEGIN` and `<!-- SKF:END -->` markers. Replace content between markers.
+- **Create** (no file): `insert`, which creates the file with the section.
+- **Append** (a file with no `<!-- SKF:BEGIN` marker): `insert`, which adds the section at the end of the file.
+- **Regenerate** (a file with a section): `replace`, which swaps the old section for the new one and writes both markers itself.
+- **Malformed** (a `<!-- SKF:BEGIN` with no `<!-- SKF:END -->` closing it): HALT and leave the file untouched. `check` names the line; the user restores the end marker, or deletes the stray begin marker, and re-runs.
 
-1. Read existing file content
-2. Find `<!-- SKF:BEGIN` line (preserve everything before it)
-3. Find `<!-- SKF:END -->` line (preserve everything after it)
-4. Replace everything between markers (inclusive) with new managed section
-5. Write file
-
-### Case 4: Malformed Markers (Halt)
-
-Target file contains `<!-- SKF:BEGIN` but no matching `<!-- SKF:END -->` marker. This indicates a corrupted managed section.
-
-1. Halt workflow with error: "Malformed managed section — `<!-- SKF:BEGIN` found but no `<!-- SKF:END -->`. Fix the markers manually before re-running export."
-2. Do not modify the file
+drop-skill and rename-skill rewrite only a section that exists: they leave a missing file, or one with no section, as it is (export-skill adds the section on its next run), and report a malformed file as failed while they rebuild the others.
 
 ## Regeneration: Full Index Rebuild
 
-When regenerating (Case 3) or creating/appending (Cases 1-2), rebuild the skill index from the **exported skill set** only:
-
-1. Read `{skills_output_folder}/.export-manifest.json` (v2 schema — see `knowledge/version-paths.md`) to determine which skills have been explicitly exported and their `active_version` (if no manifest exists, only the current export target qualifies)
-2. For each skill in the exported set, resolve the snippet at `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md` (i.e., `{skill_package}/context-snippet.md`). Do NOT use glob patterns across version directories — always resolve via manifest `active_version` or `active` symlink, falling back to the flat `{skills_output_folder}/{skill-name}/context-snippet.md` path for a skill not yet migrated to the versioned layout
-3. Count total skills and stack skills (from filtered set only)
-4. Assemble filtered snippets into managed section
-5. Sort alphabetically by skill name
-6. Update the header line with correct counts
+`skf-rebuild-managed-sections.py assemble` builds the body from the **exported skill set** only: the skills of `{skills_output_folder}/.export-manifest.json` whose active version is not deprecated, plus the skills an export names with `--include`. Its docstring lists the rules it applies (where it reads each snippet, the rows of skills the manifest does not know, the sort and the counts).
 
 **Rationale:** create-skill and update-skill also write `context-snippet.md` as a build artifact, but only export-skill is the publishing gate (ADR-K). The `.export-manifest.json` file tracks which skills have passed through export-skill, preventing draft skills from leaking into the agent's passive context.
 
 ## Safety Rules
 
-Only the bytes between `<!-- SKF:BEGIN -->` and `<!-- SKF:END -->` are yours to rewrite; everything above and below is the user's own file (their CLAUDE.md/AGENTS.md/.cursorrules) and must survive byte-for-byte — rewriting outside the markers destroys their content. On write failure, report and stop — never leave a partial write. Route writes through the atomic-write / rebuild-managed-sections helpers: they verify byte-identity of the content outside the markers after each write, so no separate hand-check is needed.
+Only the bytes between the `<!-- SKF:BEGIN` and `<!-- SKF:END -->` markers are SKF's to rewrite. Everything above and below them is the user's own file (their CLAUDE.md, AGENTS.md or .cursorrules) and must survive byte-for-byte. Route every write through `skf-rebuild-managed-sections.py`: it writes atomically and reads the file back to check the markers and the bytes outside them, so no separate hand-check is needed. On a write failure, report and stop.

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

@@ -6,7 +6,9 @@ The snippet `root:` path must reflect the IDE's actual skill directory — its `
 
 The root path in context-snippet.md on disk uses the **`skill_root` of the first entry in `target_context_files`** (resolved in step 1 from config.yaml IDE mapping). When assembling managed sections for other context files, step 4 rewrites root paths to match the target context file's skill root.
 
-**Authoring-repo override:** If `snippet_skill_root_override` is set in `config.yaml`, it replaces the IDE-mapped value for snippet generation and freezes matching prefixes against step 4 rewrites. See the "Resolution rules" section in `managed-section-format.md` for the full semantics.
+**Authoring-repo override:** If `snippet_skill_root_override` is set in `config.yaml`, or for one run by step 1's snippet-root option (d), it replaces the IDE-mapped value for snippet generation and becomes every row's root in step 4. See the "Resolution rules" section in `managed-section-format.md` for the full semantics.
+
+**A house-style copy** of this file (`snippet_format_path` in `customize.toml`) keeps the lines scripts parse: line 1 with its `root:` field, line 2's `|IMPORTANT:` start and skill name, the `|gotchas:` label with its `[CARRIED]` marker, and no bare `|` line. That setting's comment says which script reads each one.
 
 ## Format Rules