bmad-module-skill-forge 3.0.0 → 5.0.0

package/src/shared/scripts/skf-structural-diff.py

@@ -63,6 +63,20 @@ Matching:
   listed in ambiguous_names[] with the files on each side, for a reviewer
   to judge.
 
+Public surface:
+  A current entry may carry `public`, true or false: the mark
+  skf-extraction-snapshot.py build --scope-type public-api gives each
+  export by the public-surface rule a public-api skill's provenance map is
+  kept to. After the pairing above, a current entry marked false that
+  pairs with none (no baseline entry of its name and file, and no move)
+  goes to not_public[], not added[]: create-skill and update-skill never
+  document an export off the surface, so it is no drift. One whose name is
+  in ambiguous_names[] stays in added[], where a reviewer pairs it. A
+  matched or moved entry is compared whatever its mark, so a baseline
+  entry off the surface is never reported removed. An entry with no mark
+  (any other scope type, a family with no barrel, an older snapshot) is
+  added as before. not_public[] never counts toward the exit code.
+
 File scope (--files FILE):
   For a caller that re-extracted only the files that changed (update-skill's
   Category B), --files limits the diff to the exports of the files FILE
@@ -116,12 +130,27 @@ Canonicalization (applied symmetrically to BOTH sides before matching):
   ` = default`), so a runner's export compares with the map's entry.
 
 Change detection:
-  The diffed fields are type, signature, params, return_type and line. A
-  field is only compared when present (non-null) on BOTH sides: a field
-  absent on one side means "insufficient data", never an asserted change.
+  The diffed fields are type (compared through export-type, below),
+  signature, params, return_type and line. A field is only compared when
+  present (non-null) on BOTH sides: a field absent on one side means
+  "insufficient data", never an asserted change.
   This avoids false positives when the two inventories carry different
   metadata. The line of a moved export is not compared: a move changes it.
 
+  export-type: no record is rewritten, but when a matched export's two
+  types differ, a semantic kind a by-eye read records is the base kind
+  the recipe runner records for the same declaration when the base-kind
+  side's canonical signature shows that form: `async_function` is
+  `function` for an `async def`, `async function`, `async fn` or
+  `async unsafe fn`, or a `const`, `let` or `var` bound to an `async`
+  arrow or function (after `export`, `default`, `declare` or `pub`);
+  `decorator` is `function` for a Python `def` or `async def`; `enum` is
+  `class` for a Python class with a stdlib `Enum`, `IntEnum`, `StrEnum`,
+  `ReprEnum`, `Flag` or `IntFlag` base. Either side may hold the by-eye
+  kind; with no signature on the base-kind side the types differ. Each
+  export whose types it takes as one counts once as `export-type` in
+  applied_transforms.
+
   A signature has two parts, the parameters and the return type. A side
   carries the parameters as params or in its signature, and the return
   type as return_type or in its signature. When both sides carry a part
@@ -145,7 +174,7 @@ Output:
   JSON object:
     summary:            { added, removed, changed, moved, unchanged,
                           label_changes, ambiguous_names,
-                          signature_unverified }
+                          signature_unverified, not_public }
     added:              list of entries present in current but not baseline
     removed:            list of entries present in baseline but not current
     changed:            list of { name, field, baseline_value, current_value,
@@ -168,17 +197,26 @@ Output:
                         params and return_type each side carries.
                         Informational: never a change, never in the exit
                         code
+    not_public:         list of current entries marked `public: false`
+                        that pair with no baseline entry and whose name is
+                        not ambiguous (see Public surface): exports off a
+                        public-api skill's public surface, left out of
+                        added[]. Not drift, never in the exit code
     unchanged_count:    number of entries that matched with no field change
                         (a label change or an unverified signature alone
                         leaves an entry unchanged)
     applied_transforms: list of { transform, count }: which canonicalization
-                        transforms actually fired and how many values each
-                        touched (empty when none fired). Surfaced by audit
+                        transforms, and the export-type comparison,
+                        actually fired and how many values each touched
+                        (export-type: how many exports; empty when none
+                        fired). Surfaced by audit
                         step 6's Provenance section so a reviewer can tell
                         which differences the diff collapsed.
 
-  added[] and removed[] hold normalized records: name, type, signature,
-  params, return_type, file, line, confidence and extraction_method.
+  added[], removed[] and not_public[] hold normalized records: name, type,
+  signature, params, return_type, file, line, confidence and
+  extraction_method, and `public` when the entry carries a true or false
+  mark (see Public surface).
 
   With --group-by source_library, each side is split by its entries'
   source_library (a stack's libraries; an entry without one falls in a
@@ -208,8 +246,9 @@ Exit codes:
      inventory whose entries all lack the field while the other's have it,
      an output that cannot be written, or a usage error ({status: "error",
      error} on stdout, or argparse's usage on stderr)
-  Label differences (label_changes) and unverified signatures
-  (signature_unverified) do not count toward the exit code.
+  Label differences (label_changes), unverified signatures
+  (signature_unverified) and exports off the public surface (not_public) do
+  not count toward the exit code.
 """
 
 from __future__ import annotations
@@ -275,6 +314,37 @@ _STDLIB_PREFIX_RE = re.compile(
     r"(?<![\w.])(?:typing|dataclasses|collections\.abc|collections|enum)\."
 )
 
+# export-type: a semantic kind a by-eye read records, against the base kind
+# the recipe runner records for the same declaration, names one kind when
+# the base-kind side's canonical signature shows that form. Any other pair
+# of types, or a base-kind side with no signature, is compared as written.
+# An async form: `async def`, `async function`, `async fn` or `async unsafe
+# fn`, or a `const` / `let` / `var` bound to an `async` arrow or function
+# (`export const add = async (x) => x;`), after any `export`, `default`,
+# `declare` or `pub` modifier.
+_ASYNC_FORM_RE = re.compile(
+    r"^\s*(?:(?:export|default|declare|pub(?:\s*\([^()]*\))?)\s+)*"
+    r"(?:async\s+(?:unsafe\s+)?(?:def|function|fn)\b"
+    r"|(?:const|let|var)\s+[\w$]+\s*(?::(?:[^=]|=>)*)?=\s*async\b)"
+)
+_DEF_FORM_RE = re.compile(r"^\s*(?:async\s+)?def\s")
+_CLASS_BASES_RE = re.compile(r"^\s*class\s+\w+\s*\(([^()]*)\)")
+_ENUM_BASES = frozenset({"Enum", "IntEnum", "StrEnum", "ReprEnum", "Flag", "IntFlag"})
+
+
+def _enum_class_form(signature: str) -> bool:
+    """True when a Python class declaration lists a stdlib enum base."""
+    m = _CLASS_BASES_RE.match(signature)
+    return m is not None and any(base.strip() in _ENUM_BASES for base in m.group(1).split(","))
+
+
+# (by-eye kind, base kind) -> the test of the base-kind side's signature.
+EXPORT_TYPE_FORMS = {
+    ("async_function", "function"): lambda signature: _ASYNC_FORM_RE.match(signature) is not None,
+    ("decorator", "function"): lambda signature: _DEF_FORM_RE.match(signature) is not None,
+    ("enum", "class"): _enum_class_form,
+}
+
 
 # --------------------------------------------------------------------------
 # Loading
@@ -561,6 +631,10 @@ def _normalize_entries(
             "confidence": entry.get("confidence"),
             "extraction_method": entry.get("extraction_method"),
         }
+        # The snapshot's public-surface mark, kept only when it is one, so an
+        # unmarked inventory's records are as before.
+        if isinstance(entry.get("public"), bool):
+            record["public"] = entry["public"]
         key = (name, _file_key(record["file"]))
         kept = result.get(key)
         if kept is not None and not (
@@ -616,6 +690,21 @@ def _label_change(base_rec: dict, curr_rec: dict) -> dict | None:
     return None
 
 
+def _export_type_collapses(base_rec: dict, curr_rec: dict) -> bool:
+    """True when two matched records' types name one kind (EXPORT_TYPE_FORMS):
+    one side's by-eye kind against the other's base kind, whose canonical
+    signature shows that form. Either side may hold the by-eye kind."""
+    for by_eye, base in ((base_rec, curr_rec), (curr_rec, base_rec)):
+        kinds = (by_eye.get("type"), base.get("type"))
+        signature = base.get("signature")
+        if not all(isinstance(kind, str) for kind in kinds) or not isinstance(signature, str):
+            continue
+        form = EXPORT_TYPE_FORMS.get(kinds)
+        if form is not None and form(signature):
+            return True
+    return False
+
+
 def _signature_fields(rec: dict) -> list[str]:
     return [field for field in SIGNATURE_FIELDS if rec.get(field) is not None]
 
@@ -641,7 +730,8 @@ def _unverified_signature(base_rec: dict, curr_rec: dict) -> dict | None:
 # --------------------------------------------------------------------------
 
 
-LISTS = ["added", "removed", "changed", "moved", "ambiguous_names", "label_changes", "signature_unverified"]
+LISTS = ["added", "removed", "changed", "moved", "ambiguous_names", "label_changes", "signature_unverified",
+         "not_public"]
 
 
 def _key_order(key: tuple) -> tuple:
@@ -656,14 +746,18 @@ def _diff_records(
     baseline: dict[tuple, dict],
     current: dict[tuple, dict],
     unchanged_names: collections.Counter | None = None,
+    transform_counts: collections.Counter | None = None,
 ) -> dict:
     """Diff two (name, file)-keyed record sets: the LISTS, plus the counts
     unchanged_count and changed_exports (exports with a changed field).
 
     unchanged_names counts the names of exports left out of both sets as
     unchanged (--files): each counts on both sides when a move needs a name
-    unique on both sides.
+    unique on both sides. transform_counts gains one export-type for each
+    matched export whose types name one kind (_export_type_collapses).
     """
+    if transform_counts is None:
+        transform_counts = collections.Counter()
     removed_keys = sorted((k for k in baseline if k not in current), key=_key_order)
     added_keys = sorted((k for k in current if k not in baseline), key=_key_order)
 
@@ -697,8 +791,20 @@ def _diff_records(
 
     # Emit normalized entries (uniform shape) so added[] and removed[] render
     # into the same report table even though they originate from the
-    # snapshot and provenance-map shapes.
-    added = [current[k] for k in added_keys if k not in paired_curr]
+    # snapshot and provenance-map shapes. After the pairing, a leftover
+    # current entry marked off the public surface is no addition, unless its
+    # name is ambiguous: a reviewer may pair it as a move.
+    ambiguous = {item["name"] for item in ambiguous_names}
+    added: list[dict] = []
+    not_public: list[dict] = []
+    for key in added_keys:
+        if key in paired_curr:
+            continue
+        rec = current[key]
+        if rec.get("public") is False and rec["name"] not in ambiguous:
+            not_public.append(rec)
+        else:
+            added.append(rec)
     removed = [baseline[k] for k in removed_keys if k not in paired_base]
 
     changed: list[dict] = []
@@ -736,6 +842,11 @@ def _diff_records(
             if base_val is None or curr_val is None:
                 continue
             if base_val != curr_val:
+                # A by-eye kind and the runner's base kind of one declaration
+                # are one type: compared pairwise, never rewritten.
+                if field == "type" and _export_type_collapses(base_rec, curr_rec):
+                    transform_counts["export-type"] += 1
+                    continue
                 changed.append({
                     "name": curr_rec["name"],
                     "field": field,
@@ -771,6 +882,7 @@ def _diff_records(
         "ambiguous_names": ambiguous_names,
         "label_changes": label_changes,
         "signature_unverified": signature_unverified,
+        "not_public": not_public,
         "unchanged_count": unchanged_count,
         "changed_exports": changed_exports,
     }
@@ -786,6 +898,7 @@ def _summary(part: dict) -> dict:
         "label_changes": len(part["label_changes"]),
         "ambiguous_names": len(part["ambiguous_names"]),
         "signature_unverified": len(part["signature_unverified"]),
+        "not_public": len(part["not_public"]),
     }
 
 
@@ -813,10 +926,11 @@ def diff_inventories(
     """Compute the structural diff between two export inventories.
 
     Returns a dict with keys: summary, added, removed, changed, moved,
-    ambiguous_names, label_changes, signature_unverified, unchanged_count,
-    applied_transforms; with group_by, group_by and groups; and with files,
-    file_scope (see the module docstring). files limits the diff to the
-    exports of those files, and every other export is taken as unchanged.
+    ambiguous_names, label_changes, signature_unverified, not_public,
+    unchanged_count, applied_transforms; with group_by, group_by and
+    groups; and with files, file_scope (see the module docstring). files
+    limits the diff to the exports of those files, and every other export
+    is taken as unchanged.
 
     Raises ValueError when group_by is set and one side has entries but
     none with a group_by value while the other side has some; the message
@@ -869,6 +983,7 @@ def diff_inventories(
             _normalize_entries(base_part, reexport_map, transform_counts),
             _normalize_entries(curr_part, reexport_map, transform_counts),
             unchanged_names,
+            transform_counts,
         )
         if group_by:
             for name in LISTS:

package/src/shared/scripts/skf-update-active-symlink.py

@@ -16,12 +16,17 @@ to verify it points where expected and halts on divergence.
 This helper consolidates the two steps into one workflow-specific
 invocation:
 
+  - holds {skill-group}/active.skf-lock, the lock skf-atomic-write.py
+    flip-link takes, from the read through the re-read, so one flip of
+    the link runs at a time; while another flip holds it, waits up to
+    FLIP_LOCK_WAIT_SECONDS, then returns busy without touching the link
   - detects whether a flip is required (idempotent: already pointing
     at the target → no-op)
-  - performs the flip atomically (symlink → temp name → os.replace)
-    so concurrent readers never see a missing symlink
+  - performs the flip through skf-atomic-write.py's replace_link, the
+    code flip-link runs (link at a temp name → os.replace), so on POSIX
+    concurrent readers never see a missing symlink
   - verifies the post-state and surfaces ok / flipped / mismatch
-    / missing-target
+    / missing-target / busy
 
 Two subcommands:
 
@@ -41,7 +46,7 @@ silently breaks downstream consumers that expect it to resolve.
 
 Output JSON (stdout):
   {
-    "status": "ok" | "flipped" | "mismatch" | "missing-target",
+    "status": "ok" | "flipped" | "mismatch" | "missing-target" | "busy",
     "skill_group": "<abs path>",
     "active_link": "<abs path to active>",
     "expected_target": "<version>",
@@ -52,19 +57,28 @@ Output JSON (stdout):
   }
 
 Exit codes:
-  0  — ok (already correct) or flipped (just updated)
-  1  — script error (bad args, group path invalid)
-  2  — mismatch (verify mode and target diverges) OR missing-target
-       (the {version} directory doesn't exist; caller must halt)
-
-Platform: POSIX symlinks. On Windows this script intentionally
-exits 1 with a clear error — update-skill's documented supported
-platform is WSL2 (same as skf-atomic-write.py's flip-link).
+  0: ok (already correct) or flipped (just updated)
+  1: script error, one `error:` line on stderr and nothing on stdout
+     (group path invalid, a real folder or file at {skill-group}/active,
+     skf-atomic-write.py not loadable from this script's folder, or the
+     link could not be moved); argparse exits 2 on bad arguments
+  2: mismatch (verify mode and target diverges), missing-target
+     (the {version} directory doesn't exist; caller must halt), or
+     busy (update: another flip held the link's lock for the whole
+     wait; the link is unchanged, caller must halt)
+
+Platform: Linux, macOS and native Windows, as skf-atomic-write.py's
+flip-link. On Windows the flip removes the old link first whenever the
+rename over it is refused, which it always is over a directory link, so
+it is not atomic there; without symlink privilege the new link is a
+directory junction. A junction reads back as the name of the version folder it
+resolves to, so `ok` means the link names {version} whichever kind it is.
 """
 
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import json
 import os
 import sys
@@ -72,6 +86,23 @@ from pathlib import Path
 
 
 ACTIVE_NAME = "active"
+ATOMIC_WRITE_HELPER = Path(__file__).resolve().parent / "skf-atomic-write.py"
+# A flip holds <link>.skf-lock for well under a millisecond, so update waits
+# this long for another flip to let it go before it returns busy.
+FLIP_LOCK_WAIT_SECONDS = 5.0
+
+
+def _load_atomic_write():
+    """Load skf-atomic-write.py, which installs into the same folder as this script."""
+    try:
+        spec = importlib.util.spec_from_file_location("skf_atomic_write", ATOMIC_WRITE_HELPER)
+        if spec is None or spec.loader is None:
+            raise ImportError("no import spec")
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+    except (OSError, ImportError, SyntaxError) as e:
+        raise OSError(f"cannot load the flip-lock helper {ATOMIC_WRITE_HELPER}: {e}") from e
+    return module
 
 
 # --------------------------------------------------------------------------
@@ -80,46 +111,51 @@ ACTIVE_NAME = "active"
 
 
 def read_link_target(link_path: Path) -> str | None:
-    """Return the symlink target as a relative string, or None if the link
-    doesn't exist. Raises ValueError if `link_path` exists but isn't a symlink
-    (someone replaced it with a regular dir/file)."""
-    if not link_path.exists() and not link_path.is_symlink():
+    """Return what the link at `link_path` names, or None if nothing is there.
+
+    A symlink gives its stored target (`1.6.2` for the links SKF makes). A
+    Windows junction, which Path.is_symlink() does not report and whose
+    os.readlink is an absolute `\\\\?\\` path, gives the name of the folder it
+    resolves to when that folder sits beside it, else its stored path (a
+    junction whose folder is gone, one that leads elsewhere, or a loop). Raises
+    ValueError if `link_path` exists but is not a link (someone replaced it
+    with a regular dir/file)."""
+    if not os.path.lexists(link_path):
         return None
-    if not link_path.is_symlink():
+    if link_path.is_symlink():
+        return os.readlink(link_path)
+    try:
+        stored = os.readlink(link_path)
+    except (OSError, ValueError):
         raise ValueError(
             f"{link_path} exists but is not a symlink — refusing to overwrite "
             "(manual recovery required)"
-        )
-    return os.readlink(link_path)
+        ) from None
+    try:
+        resolved = link_path.resolve(strict=True)
+    except (OSError, RuntimeError):  # Python 3.11 and 3.12 raise RuntimeError on a loop
+        return stored
+    if resolved.parent == link_path.parent.resolve():
+        return resolved.name
+    return stored
 
 
 def atomic_flip_symlink(link_path: Path, target_name: str) -> None:
-    """Atomically point `link_path` at `target_name` using the
-    create-temp + rename pattern. `target_name` is a relative path
-    interpreted in the parent of `link_path` (same convention as
-    {skill_group}/active → version-dir-sibling).
-
-    Implementation: os.symlink writes a new link at link_path.tmp,
-    then os.replace atomically renames it over link_path. POSIX
-    rename is atomic for symlinks, so concurrent readers either see
-    the old target or the new one, never a missing file.
+    """Point `link_path` at `target_name` using the create-temp + rename
+    pattern. `target_name` is a relative path interpreted in the parent of
+    `link_path` (same convention as {skill_group}/active → version-dir-sibling).
+
+    Implementation: skf-atomic-write.py's replace_link, the code flip-link
+    runs, with `.{name}.skf-symlink.tmp` as the temp name: it removes a stale
+    temp from a prior crash, writes the new link there and os.replace renames
+    it over link_path. POSIX rename is atomic for symlinks, so concurrent
+    readers either see the old target or the new one, never a missing file.
+    On Windows the old link is removed first whenever the rename over it is
+    refused, which it always is over a directory link; without symlink
+    privilege the new link is a junction.
     """
-    parent = link_path.parent
-    tmp = parent / f".{link_path.name}.skf-symlink.tmp"
-    # Clean up a stale temp from a prior crash, if any.
-    if tmp.is_symlink() or tmp.exists():
-        os.unlink(tmp)
-    try:
-        os.symlink(target_name, tmp)
-        os.replace(tmp, link_path)
-    except OSError:
-        # Best-effort cleanup; raise the original error.
-        try:
-            if tmp.is_symlink() or tmp.exists():
-                os.unlink(tmp)
-        except OSError:
-            pass
-        raise
+    tmp = link_path.parent / f".{link_path.name}.skf-symlink.tmp"
+    _load_atomic_write().replace_link(link_path, target_name, tmp)
 
 
 # --------------------------------------------------------------------------
@@ -191,8 +227,25 @@ def _envelope_mismatch(skill_group: Path, version: str, current: str | None) ->
             f"Active symlink divergence. `{skill_group / ACTIVE_NAME}` "
             f"resolves to `{cur}` but metadata.json reports `version: "
             f"{version}`. The flip did not apply. Re-point the symlink manually "
-            f"(`ln -sfn {version} {skill_group / ACTIVE_NAME}`) or re-run "
-            "update-skill, then re-verify."
+            f"(`uv run \"{ATOMIC_WRITE_HELPER}\" flip-link --link \"{skill_group / ACTIVE_NAME}\" "
+            f"--target \"{version}\"`) or re-run update-skill, then re-verify."
+        ),
+    }
+
+
+def _envelope_busy(skill_group: Path, version: str, message: str) -> dict:
+    return {
+        "status": "busy",
+        "skill_group": str(skill_group),
+        "active_link": str(skill_group / ACTIVE_NAME),
+        "expected_target": version,
+        "current_target": None,
+        "action_taken": "halt",
+        "log_message": f"active_symlink_update: busy ({message})",
+        "halt_message": (
+            f"Another flip of `{skill_group / ACTIVE_NAME}` held its lock for "
+            f"{FLIP_LOCK_WAIT_SECONDS:g} s, so the link is unchanged. "
+            "Re-run once the other run ends."
         ),
     }
 
@@ -204,16 +257,24 @@ def update(skill_group: Path, version: str) -> dict:
         return _envelope_missing_target(skill_group, version)
 
     link_path = skill_group / ACTIVE_NAME
-    current = read_link_target(link_path)
-    if current == version:
-        return _envelope_ok(skill_group, version, current)
+    atomic_write = _load_atomic_write()
+    try:
+        lock_fd = atomic_write.take_flip_lock(link_path, wait=FLIP_LOCK_WAIT_SECONDS)
+    except atomic_write.FlipLockHeld as exc:
+        return _envelope_busy(skill_group, version, str(exc))
+    try:
+        current = read_link_target(link_path)
+        if current == version:
+            return _envelope_ok(skill_group, version, current)
 
-    atomic_flip_symlink(link_path, version)
+        atomic_flip_symlink(link_path, version)
 
-    # Re-read to confirm
-    post = read_link_target(link_path)
+        # Re-read to confirm
+        post = read_link_target(link_path)
+    finally:
+        atomic_write.release_flip_lock(link_path, lock_fd)
     if post != version:
-        # Should be impossible — os.replace would have raised — but defend
+        # Only a writer that skips the lock, such as a hand-run `ln -sfn`, gets here.
         return _envelope_mismatch(skill_group, version, post)
     return _envelope_flipped(skill_group, version, current)
 
@@ -235,7 +296,7 @@ def verify(skill_group: Path, version: str) -> dict:
 def _exit_code_for_status(status: str) -> int:
     if status in ("ok", "flipped"):
         return 0
-    if status in ("mismatch", "missing-target"):
+    if status in ("mismatch", "missing-target", "busy"):
         return 2
     return 1
 
@@ -298,14 +359,6 @@ def _build_parser() -> argparse.ArgumentParser:
 
 
 def main(argv: list[str] | None = None) -> int:
-    if sys.platform.startswith("win"):
-        print(
-            "error: native Windows symlinks require admin/developer mode; "
-            "use WSL2 to run update-skill (same constraint as "
-            "skf-atomic-write.py flip-link)",
-            file=sys.stderr,
-        )
-        return 1
     parser = _build_parser()
     args = parser.parse_args(argv)
     return args.func(args)

package/src/shared/scripts/skf-validate-brief-schema.py

@@ -52,6 +52,7 @@ from __future__ import annotations
 
 import argparse
 import datetime
+import importlib.util
 import json
 import sys
 from pathlib import Path
@@ -62,6 +63,23 @@ from jsonschema import Draft202012Validator
 
 
 SCHEMA_PATH = Path(__file__).resolve().parent / "schemas" / "skill-brief.v1.json"
+RESOLVER_PATH = Path(__file__).resolve().parent / "skf-resolve-authoritative-files.py"
+
+
+def _load_resolver():
+    """skf-resolve-authoritative-files.py from this folder: its
+    parse_brief_yaml reads a brief's YAML, an SKF 1.x brief's trailing `---`
+    included. A missing file raises OSError, which skf-quick-batch.py
+    reports as a validator that cannot be loaded."""
+    spec = importlib.util.spec_from_file_location("skf_resolve_authoritative_files", RESOLVER_PATH)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot load {RESOLVER_PATH.name} beside {Path(__file__).name}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+_RESOLVER = _load_resolver()
 
 
 # --------------------------------------------------------------------------
@@ -77,7 +95,7 @@ def load_schema() -> dict:
 def load_brief_text(text: str) -> tuple[dict | None, str | None]:
     """Parse YAML text. Returns (brief, error_message)."""
     try:
-        brief = yaml.safe_load(text)
+        brief = _RESOLVER.parse_brief_yaml(text)
     except yaml.YAMLError as exc:
         return None, f"Brief is not valid YAML: {exc}"
     if brief is None:

package/src/shared/scripts/skf-validate-output.py

@@ -146,6 +146,14 @@ def validate_body_structure(content):
     return issues
 
 
+# The context snippet's length bounds, in `len(text)//4` tokens. The ceiling is
+# the hard 300-token ceiling export-skill's generate-snippet.md §4 sets (a Deep
+# snippet may pass the ~80-120 target when its gotchas carry load-bearing
+# breaking-change notices), so a snippet that step accepts is never flagged.
+SNIPPET_TOKEN_FLOOR = 40
+SNIPPET_TOKEN_CEILING = 300
+
+
 def validate_context_snippet(content):
     """Validate context-snippet.md format. Returns list of issues."""
     issues = []
@@ -169,10 +177,11 @@ def validate_context_snippet(content):
 
     # Approximate token count (rough: ~4 chars per token)
     approx_tokens = len(content) // 4
-    if approx_tokens < 40:
+    if approx_tokens < SNIPPET_TOKEN_FLOOR:
         issues.append({"severity": "low", "field": "length", "message": f"Context snippet may be too short (~{approx_tokens} tokens)"})
-    elif approx_tokens > 200:
-        issues.append({"severity": "low", "field": "length", "message": f"Context snippet may be too long (~{approx_tokens} tokens)"})
+    elif approx_tokens > SNIPPET_TOKEN_CEILING:
+        issues.append({"severity": "low", "field": "length",
+                       "message": f"Context snippet is above the {SNIPPET_TOKEN_CEILING}-token ceiling (~{approx_tokens} tokens)"})
 
     return issues