bmad-module-skill-forge 3.0.0 → 5.0.0

package/src/shared/scripts/skf-count-tokens.py

@@ -23,11 +23,24 @@ Measured artifacts (all relative to the positional skill-package dir):
                            extracted from the first --target-file that contains one
                            (shared across the batch; measured once)
 
+The managed_section object also gives `skills`, the number of skill rows (each
+`[name v...]` row header) in the measured block, and `target_files`, every --target-file
+that holds a block, in the order passed and each once. A target file that cannot be read
+as UTF-8 text is skipped.
+
 package_total sums context-snippet.md + SKILL.md + metadata.json + references_total and
 DELIBERATELY EXCLUDES the managed-section row — the managed section is a shared all-skills
 cost reported separately, and including it would double-count this skill's own snippet
 (see references/token-report.md §1).
 
+context_budget gives the token report's Context Budget Impact values, in tokens:
+  - always_on:       the managed section (loaded in every session); null when no
+                     target file holds a block
+  - on_trigger:      SKILL.md (loaded when the skill triggers)
+  - full_disclosure: SKILL.md + references_total (loaded when every reference is read too);
+                     neither the snippet nor metadata.json, so it is not package_total
+  - snippet:         context-snippet.md (this skill's share of the managed section)
+
 CLI:
   python3 skf-count-tokens.py <skill-package-dir>
   python3 skf-count-tokens.py <skill-package-dir> --target-file CLAUDE.md
@@ -52,6 +65,13 @@ MANAGED_SECTION_RE = re.compile(
     re.DOTALL,
 )
 
+# A skill row header of the managed section: `[name v<version>]` at the start of a line,
+# optionally after the format's leading `|`, with or without a `root:` field. The
+# ` v<version>` keeps the section's own `[SKF Skills]|{n} skills|{m} stack` header out.
+# This is skf-rebuild-managed-sections.py's ROW_HEADER_PATTERN, so both scripts count the
+# rows parse_managed_rows returns (test-skf-count-tokens.py keeps them in step).
+MANAGED_ROW_RE = re.compile(r"^\|?\[(?P<name>[^\]]+?) v(?P<version>[^\]\s]+)\]", re.MULTILINE)
+
 # Core per-skill artifacts, in report order. (references/ is handled separately.)
 CORE_ARTIFACTS = [
     ("context-snippet.md", "context-snippet"),
@@ -87,6 +107,11 @@ def extract_managed_section(text: str) -> str | None:
     return m.group(0) if m else None
 
 
+def count_managed_skills(section: str) -> int:
+    """The number of skill rows (`[name v...]` row headers) in a managed section."""
+    return len(MANAGED_ROW_RE.findall(section))
+
+
 def measure_reference_files(references_dir: Path) -> tuple[list[dict], dict]:
     """Measure every file under references/ (recursively, sorted). Returns (per-file rows, total)."""
     rows: list[dict] = []
@@ -144,20 +169,38 @@ def count_package(skill_dir: Path, target_files: list[Path] | None = None) -> di
         "tokens": sum(core_by_role[r]["tokens"] for r in core_by_role) + references_total["tokens"],
     }
 
-    # Managed section — first --target-file that actually contains a block wins.
-    managed_section = {"present": False, "source_file": None, "words": 0, "tokens": 0}
+    # Managed section: the first --target-file that actually contains a block is measured;
+    # target_files lists every one that holds a block.
+    managed_section = {"present": False, "source_file": None, "target_files": [], "skills": 0,
+                       "words": 0, "tokens": 0}
+    seen: set[Path] = set()
     for tf in target_files:
         tf = Path(tf)
-        if not tf.is_file():
+        if tf.resolve() in seen or not tf.is_file():
             continue
-        section = extract_managed_section(_read_text(tf))
-        if section is not None:
-            managed_section = {
-                "present": True,
-                "source_file": tf.as_posix(),
+        seen.add(tf.resolve())
+        try:
+            section = extract_managed_section(_read_text(tf))
+        except (OSError, UnicodeDecodeError):
+            continue  # unreadable or not UTF-8: it holds no block this helper can measure
+        if section is None:
+            continue
+        managed_section["target_files"].append(tf.as_posix())
+        if not managed_section["present"]:
+            managed_section.update(
+                present=True,
+                source_file=tf.as_posix(),
+                skills=count_managed_skills(section),
                 **measure(section),
-            }
-            break
+            )
+
+    # The Context Budget Impact values token-report.md §2 renders.
+    context_budget = {
+        "always_on": managed_section["tokens"] if managed_section["present"] else None,
+        "on_trigger": core_by_role["skill-md"]["tokens"],
+        "full_disclosure": core_by_role["skill-md"]["tokens"] + references_total["tokens"],
+        "snippet": core_by_role["context-snippet"]["tokens"],
+    }
 
     return {
         "status": "ok",
@@ -166,6 +209,7 @@ def count_package(skill_dir: Path, target_files: list[Path] | None = None) -> di
         "references_total": references_total,
         "managed_section": managed_section,
         "package_total": package_total,
+        "context_budget": context_budget,
     }
 
 

package/src/shared/scripts/skf-derive-assembly-shape.py

@@ -46,6 +46,7 @@ Exit codes:
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import json
 import sys
 from pathlib import Path
@@ -53,6 +54,8 @@ from typing import Any
 
 import yaml
 
+RESOLVER = Path(__file__).resolve().parent / "skf-resolve-authoritative-files.py"
+
 
 def derive_assembly_shape(brief: dict[str, Any]) -> dict[str, Any]:
     """Return the assembly-shape decision for a parsed brief."""
@@ -73,6 +76,20 @@ def _die(message: str) -> None:
     sys.exit(2)
 
 
+def _parse_brief_yaml(text: str):
+    """The brief's YAML as skf-resolve-authoritative-files.py (from this
+    folder) reads it: an SKF 1.x brief's trailing `---` is no second document."""
+    spec = importlib.util.spec_from_file_location("skf_resolve_authoritative_files", RESOLVER)
+    if spec is None or spec.loader is None:
+        _die(f"cannot load {RESOLVER.name} beside {Path(__file__).name}")
+    resolver = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(resolver)
+    except (OSError, ImportError, SyntaxError) as exc:
+        _die(f"cannot load {RESOLVER.name} beside {Path(__file__).name}: {exc}")
+    return resolver.parse_brief_yaml(text)
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="skf-derive-assembly-shape",
@@ -93,7 +110,7 @@ def main(argv: list[str] | None = None) -> int:
         text = p.read_text(encoding="utf-8")
 
     try:
-        brief = yaml.safe_load(text)
+        brief = _parse_brief_yaml(text)
     except yaml.YAMLError as exc:
         _die(f"Brief is not valid YAML: {exc}")
     if not isinstance(brief, dict):

package/src/shared/scripts/skf-detect-scripts-assets.py

@@ -1,6 +1,6 @@
 # /// script
 # requires-python = ">=3.11"
-# dependencies = []
+# dependencies = ["pyyaml"]
 # ///
 """SKF Detect Scripts & Assets — file-level artifact detection for skill compilation.
 
@@ -22,11 +22,32 @@ CLI:
   uv run skf-detect-scripts-assets.py detect <source-root> \\
       [--scripts-intent detect|none] \\
       [--assets-intent detect|none] \\
-      [--scope-include "pattern1,pattern2,..."] \\
+      [--brief <skill-brief.yaml>] \\
       [--max-lines 500]
 
+--brief keeps a file only when the skill brief's scope takes it, by the
+one brief-scope test of skf-classify-changed-files.py (load_scope, loaded
+from this folder only when --brief is given), which update-skill's
+Category A and Category D and audit-skill's Script/Asset Drift use too:
+the glob rules of skf-resolve-authoritative-files.py (`**` spans any
+number of folders, `*` and `?` never cross a `/`), each `scope.include`
+and `scope.exclude` pattern normalized (forward slashes, no leading `./`),
+and a path in scope when an include matches it and no exclude does. With
+an empty `scope.include`, a path is in scope when no exclude matches it
+and its extension is one the brief's `language` uses. The test runs before
+the script and asset rules. The brief's intents are not read here:
+--scripts-intent and --assets-intent set them. A --brief that names no
+file, one that cannot be read and an empty one (an unbound brief path)
+exit 1, never an unscoped run. Without --brief every file is in scope.
+
 Detection rules — scripts:
-  Directory convention: scripts/, bin/, tools/, cli/
+  Directory convention: scripts/, bin/, tools/, cli/ (at any depth). A
+    Python package's folder is code, not a script folder: a `.py` file
+    under such a folder that holds `__init__.py` is a script only with a
+    shebang, a top-level `if __name__ == "__main__":` block (either
+    comparison order, parentheses allowed, never a line inside a string)
+    or when it is the package's `__main__.py` (the `python -m` entry).
+    is_package_module() is that rule.
   Shebang signals: #!/bin/bash, #!/usr/bin/env python|node|bash|sh, etc.
   Entry point declarations: package.json `bin`, pyproject.toml [project.scripts]
   CLI argument-parser imports are detected for the LLM-judgment tier only —
@@ -44,6 +65,13 @@ Exclusions:
   Generated paths: dist/, build/, .webpack/, node_modules/, __pycache__/,
     target/ (Rust), .next/, .nuxt/, out/, coverage/
 
+file_kind() is the per-file rule: a script (is_script) before an asset
+(asset_type), each asked only when its kind is on. detect() calls it with
+its intents; skf-compare-file-hashes.py (audit-skill's Script/Asset Drift)
+loads this file and walks with iter_files, is_binary_path,
+entry_point_script_paths and file_kind, both kinds on, so audit-skill finds
+the same new files update-skill's Category D finds through detect.
+
 Size flag:
   Files >max-lines (default 500) get size_flag="oversized" but are still
   included — the caller decides whether to bundle them.
@@ -63,15 +91,18 @@ Confidence is always "T1-low" — file existence verified, content not
 AST-analyzed. Matches the spec at extraction-patterns-tracing.md §Provenance.
 
 Exit codes:
-  0  — detection succeeded (including --scripts-intent=none --assets-intent=none)
-  1  — user error (bad source root, malformed args)
+  0  detection succeeded (including --scripts-intent=none --assets-intent=none)
+  1  user error (bad source root, malformed args, a --brief that names no
+     file, cannot be read or is empty, or a scope test that cannot be
+     loaded): one `error:` line on stderr
 """
 
 from __future__ import annotations
 
 import argparse
-import fnmatch
+import ast
 import hashlib
+import importlib.util
 import json
 import re
 import sys
@@ -182,18 +213,6 @@ def in_directory(path: Path, root: Path, dir_names: set[str]) -> bool:
     return any(seg in dir_names for seg in relative_segments(path, root))
 
 
-def matches_scope(path: Path, root: Path, scope_patterns: list[str]) -> bool:
-    """Match `path` against scope-include glob patterns relative to root.
-
-    Forward-slash form so scope patterns like "scripts/*" match on Windows
-    too — fnmatch is byte-exact and won't normalize separators for us.
-    """
-    if not scope_patterns:
-        return True
-    rel = path.relative_to(root).as_posix()
-    return any(fnmatch.fnmatch(rel, pattern) for pattern in scope_patterns)
-
-
 # --------------------------------------------------------------------------
 # Read helpers
 # --------------------------------------------------------------------------
@@ -294,6 +313,8 @@ def _parse_package_json_bin(source_root: Path) -> Iterable[Path]:
         data = json.loads(text)
     except json.JSONDecodeError:
         return ()
+    if not isinstance(data, dict):  # valid JSON but no object (`[]`, `null`, a number): no `bin`
+        return ()
     bin_field = data.get("bin")
     if isinstance(bin_field, str):
         candidates = [bin_field]
@@ -325,11 +346,72 @@ def _parse_pyproject_scripts(source_root: Path) -> Iterable[Path]:
     return ()
 
 
+# The fallback for a file that does not parse: a column-0 `if` comparing
+# __name__ with "__main__", either way round, parentheses allowed.
+_MAIN_BLOCK_RE = re.compile(
+    r"^if\s*\(?\s*(?:__name__\s*==\s*(['\"])__main__\1|(['\"])__main__\2\s*==\s*__name__)\s*\)?\s*:", re.M
+)
+
+
+def in_package_script_dir(path: Path, source_root: Path) -> bool:
+    """True when a script folder (SCRIPT_DIRS) over `path` holds
+    `__init__.py`: a Python package that happens to be named tools/, cli/,
+    bin/ or scripts/, whose modules are code."""
+    segments = relative_segments(path, source_root)
+    return any(
+        seg in SCRIPT_DIRS and source_root.joinpath(*segments[: i + 1], "__init__.py").is_file()
+        for i, seg in enumerate(segments)
+    )
+
+
+def has_shebang(path: Path) -> bool:
+    try:
+        with path.open("rb") as fh:
+            return fh.read(2) == b"#!"
+    except OSError:
+        return False
+
+
+def _is_main_test(test: ast.expr) -> bool:
+    """`__name__ == "__main__"` or `"__main__" == __name__`."""
+    if not (isinstance(test, ast.Compare) and len(test.ops) == 1 and isinstance(test.ops[0], ast.Eq)):
+        return False
+    sides = (test.left, test.comparators[0])
+    return (any(isinstance(s, ast.Name) and s.id == "__name__" for s in sides)
+            and any(isinstance(s, ast.Constant) and s.value == "__main__" for s in sides))
+
+
+def has_main_block(path: Path) -> bool:
+    """True when the file holds a top-level `if __name__ == "__main__":`
+    (either order, parenthesized or not). The file is parsed, so such a
+    line inside a string never counts; a file that does not parse is
+    matched line by line."""
+    text = read_text_safe(path)
+    if not text:
+        return False
+    try:
+        tree = ast.parse(text)
+    except (SyntaxError, ValueError):
+        return _MAIN_BLOCK_RE.search(text) is not None
+    return any(isinstance(node, ast.If) and _is_main_test(node.test) for node in tree.body)
+
+
+def is_package_module(path: Path, source_root: Path) -> bool:
+    """True when `path` is a module of a Python package named like a script
+    folder (in_package_script_dir): code, not a script, unless it runs on
+    its own (a shebang, a top-level `__main__` block, or the package's
+    `__main__.py`, which `python -m` runs)."""
+    return (path.suffix.lower() == ".py" and in_package_script_dir(path, source_root)
+            and path.name != "__main__.py" and not (has_shebang(path) or has_main_block(path)))
+
+
 def is_script(path: Path, source_root: Path, *, entry_points: set[Path]) -> tuple[bool, str | None]:
     """Decide whether `path` is a script. Returns (is_script, shebang_lang)."""
     if path.resolve() in entry_points:
         return True, detect_shebang_language(path)
     if in_directory(path, source_root, SCRIPT_DIRS):
+        if is_package_module(path, source_root):
+            return False, None
         return True, detect_shebang_language(path)
     shebang_lang = detect_shebang_language(path)
     if shebang_lang is not None:
@@ -379,6 +461,25 @@ def asset_type(path: Path, source_root: Path) -> str | None:
     return None
 
 
+def file_kind(path: Path, source_root: Path, entry_points: set[Path], *,
+              scripts: bool = True, assets: bool = True) -> tuple[str, str | None] | None:
+    """What `path` is: ("script", its shebang language or None), ("asset",
+    its asset type) or None. A script is never also an asset: is_script is
+    asked first, when `scripts` is on, then asset_type, when `assets` is on.
+    `entry_points` is entry_point_script_paths(source_root) (an empty set
+    when scripts are off). The kind strings are the ones
+    skf-classify-changed-files.py's Scope.wants takes."""
+    if scripts:
+        is_scr, shebang_lang = is_script(path, source_root, entry_points=entry_points)
+        if is_scr:
+            return "script", shebang_lang
+    if assets:
+        atype = asset_type(path, source_root)
+        if atype is not None:
+            return "asset", atype
+    return None
+
+
 # --------------------------------------------------------------------------
 # Purpose extraction
 # --------------------------------------------------------------------------
@@ -474,10 +575,12 @@ def detect(
     *,
     scripts_intent: str = "detect",
     assets_intent: str = "detect",
-    scope_patterns: list[str] | None = None,
+    scope=None,
     max_lines: int = 500,
 ) -> dict:
-    scope_patterns = scope_patterns or []
+    """The inventories of `source_root`. `scope` is the brief's Scope
+    (skf-classify-changed-files.py load_scope, --brief): a file it does not
+    take is neither a script nor an asset. None takes every file."""
     scripts_skipped = scripts_intent == "none"
     assets_skipped = assets_intent == "none"
 
@@ -494,30 +597,27 @@ def detect(
             files_scanned += 1
             if is_binary_path(path):
                 continue
-            if not matches_scope(path, source_root, scope_patterns):
+            if scope is not None and not scope.takes(path.relative_to(source_root).as_posix()):
                 continue
 
-            if not scripts_skipped:
-                is_scr, shebang_lang = is_script(
-                    path, source_root, entry_points=entry_points
-                )
-                if is_scr:
-                    scripts_inventory.append(
-                        build_script_record(
-                            path, source_root,
-                            shebang_lang=shebang_lang, max_lines=max_lines,
-                        )
+            found = file_kind(path, source_root, entry_points,
+                              scripts=not scripts_skipped, assets=not assets_skipped)
+            if found is None:
+                continue
+            kind, detail = found
+            if kind == "script":
+                scripts_inventory.append(
+                    build_script_record(
+                        path, source_root,
+                        shebang_lang=detail, max_lines=max_lines,
                     )
-                    continue  # a script can't also be an asset
-
-            if not assets_skipped:
-                atype = asset_type(path, source_root)
-                if atype is not None:
-                    assets_inventory.append(
-                        build_asset_record(
-                            path, source_root, atype=atype, max_lines=max_lines,
-                        )
+                )
+            else:
+                assets_inventory.append(
+                    build_asset_record(
+                        path, source_root, atype=detail, max_lines=max_lines,
                     )
+                )
 
     # Deterministic ordering for stable diffs / cacheability
     scripts_inventory.sort(key=lambda r: r["source_file"])
@@ -541,28 +641,69 @@ def detect(
 # --------------------------------------------------------------------------
 
 
+_SIBLINGS: dict[str, object] = {}
+
+
+def _sibling(filename: str):
+    """A helper installed beside this script, loaded once as a module:
+    skf-classify-changed-files.py, whose load_scope is --brief's scope
+    test (it loads skf-resolve-authoritative-files.py beside it). Raises
+    whatever loading it raises."""
+    module = _SIBLINGS.get(filename)
+    if module is None:
+        path = Path(__file__).resolve().parent / filename
+        name = "skf_" + filename.removeprefix("skf-").removesuffix(".py").replace("-", "_")
+        spec = importlib.util.spec_from_file_location(name, path)
+        if spec is None or spec.loader is None or not path.is_file():
+            raise ImportError(f"{filename} not found beside {Path(__file__).name}")
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        _SIBLINGS[filename] = module
+    return module
+
+
+def _error(message: str) -> int:
+    """`message` as one `error:` line on stderr (a YAML error spans several
+    lines: each line break and the space around it becomes one space); exit 1."""
+    print("error: " + re.sub(r"\s*[\r\n]\s*", " ", message.strip("\r\n")), file=sys.stderr)
+    return 1
+
+
+def load_brief_scope(brief: str):
+    """--brief's Scope. Raises ValueError for an empty value, a brief that
+    names no file or cannot be read, and a scope test that cannot be loaded
+    (a classifier or resolver missing, out of date or failing)."""
+    if not brief.strip():
+        raise ValueError("--brief is empty (an unbound brief path?): pass the brief, or leave --brief out")
+    try:
+        return _sibling("skf-classify-changed-files.py").load_scope(Path(brief))
+    except ValueError:  # a brief it cannot find or read
+        raise
+    except Exception as exc:  # whatever the scope test raises, the run reports it on one line
+        raise ValueError(f"cannot load the brief's scope test beside {Path(__file__).name}: {exc}; "
+                         "re-install SKF") from exc
+
+
 def _cmd_detect(args: argparse.Namespace) -> int:
     source_root = Path(args.source_root).resolve()
     if not source_root.is_dir():
-        print(f"error: source root not a directory: {source_root}", file=sys.stderr)
-        return 1
-    scope_patterns = (
-        [s.strip() for s in args.scope_include.split(",") if s.strip()]
-        if args.scope_include
-        else []
-    )
+        return _error(f"source root not a directory: {source_root}")
     if args.scripts_intent not in ("detect", "none"):
-        print(f"error: --scripts-intent must be detect|none", file=sys.stderr)
-        return 1
+        return _error("--scripts-intent must be detect|none")
     if args.assets_intent not in ("detect", "none"):
-        print(f"error: --assets-intent must be detect|none", file=sys.stderr)
-        return 1
+        return _error("--assets-intent must be detect|none")
+    scope = None
+    if args.brief is not None:
+        try:
+            scope = load_brief_scope(args.brief)
+        except ValueError as exc:
+            return _error(str(exc))
 
     result = detect(
         source_root,
         scripts_intent=args.scripts_intent,
         assets_intent=args.assets_intent,
-        scope_patterns=scope_patterns,
+        scope=scope,
         max_lines=args.max_lines,
     )
     json.dump(result, sys.stdout, indent=2)
@@ -589,9 +730,10 @@ def _build_parser() -> argparse.ArgumentParser:
         help="detect|none (default: detect)",
     )
     p.add_argument(
-        "--scope-include",
+        "--brief",
         default=None,
-        help="comma-separated glob patterns to limit detection (relative to source-root)",
+        metavar="BRIEF",
+        help="the skill brief (skill-brief.yaml): detect only in the files its scope takes",
     )
     p.add_argument(
         "--max-lines",

package/src/shared/scripts/skf-detect-workspaces.py

@@ -160,6 +160,26 @@ skf-recommend-scope-type.py reads (registry.ts, components.ts and their .tsx
 forms, at any depth), found by that script's own rule (the sibling in this
 folder, which must sit beside this script).
 
+Brief scope (scoped_tree)
+-------------------------
+
+scoped_tree(tree, excludes, glob_match) is the tree a skill brief's
+scope.exclude globs leave, as workspace detection reads it (#780): a
+workspace member counts only through the files the brief keeps. It holds
+each file no exclude glob matches, but a manifest (a MEMBER_MANIFESTS name);
+each root manifest (a file at the root named in MEMBER_MANIFESTS,
+CONTENT_MANIFESTS or nx.json), always; and each member manifest (a
+MEMBER_MANIFESTS name below the root) whose folder still holds, at any
+depth, a non-manifest file no exclude glob matches, whether or not a glob
+matches the manifest itself. A member manifest whose folder holds no
+non-manifest file at all stays unless a glob matches it. So `rust/**`,
+`rust/**/*.rs` or `rust/*/src/**` drops the members under rust/,
+`**/Cargo.toml` alone drops none, and a workspace with no member left is
+no workspace, while one with a member left still is. With no exclude glob
+the tree is returned as given. Callers (test-skill's stage-helper-payload.py
+and skf-extract-public-api.py's monorepo arm) pass the glob rule of
+skf-resolve-authoritative-files.py, which this script does not load.
+
 Exit codes:
 
   0  success (regardless of is_monorepo value)
@@ -181,6 +201,7 @@ import posixpath
 import re
 import sys
 import tomllib
+from collections.abc import Callable
 from pathlib import Path
 from typing import Optional
 
@@ -200,6 +221,11 @@ RECOGNISED_MANIFESTS = (
 # in the tree alone): --manifest-files lists them, --manifest-dir reads them,
 # and a warning names each one the tree lists that was not supplied.
 CONTENT_MANIFESTS = ("package.json", "pnpm-workspace.yaml", "lerna.json", "rush.json", "Cargo.toml")
+# The manifest a workspace member is found by: a recognised one, or an Nx
+# project's project.json. scoped_tree keeps one while its folder keeps a file.
+MEMBER_MANIFESTS = RECOGNISED_MANIFESTS + ("project.json",)
+# The root files scoped_tree keeps whatever the brief excludes.
+ROOT_MANIFESTS = frozenset(MEMBER_MANIFESTS + CONTENT_MANIFESTS + ("nx.json",))
 MAX_MANIFEST_BYTES = 1024 * 1024
 # Folders a snapshot's module root is never followed down through (names
 # matched in lower case): tests, test helpers and fixtures, docs and sites,
@@ -698,6 +724,47 @@ def detect(payload: dict) -> dict:
     }
 
 
+# --------------------------------------------------------------------------
+# Brief scope
+# --------------------------------------------------------------------------
+
+
+def scoped_tree(tree: list[str], excludes: list[str], glob_match: Callable[[str, str], bool]) -> list[str]:
+    """The paths of `tree` workspace detection reads under a brief whose
+    scope.exclude globs are `excludes`, in their order: see "Brief scope" in
+    the module docstring. `glob_match(path, glob)` is the brief's glob rule."""
+    if not excludes:
+        return list(tree)
+
+    def manifest(path: str) -> bool:
+        return posixpath.basename(path) in MEMBER_MANIFESTS
+
+    excluded = {path for path in tree if any(glob_match(path, glob) for glob in excludes)}
+    holding: set[str] = set()  # folders holding a non-manifest file
+    kept_holding: set[str] = set()  # folders holding one no exclude glob matches
+    for path in tree:
+        if manifest(path):
+            continue
+        parts = path.split("/")
+        for depth in range(1, len(parts)):
+            folder = "/".join(parts[:depth])
+            holding.add(folder)
+            if path not in excluded:
+                kept_holding.add(folder)
+    kept = []
+    for path in tree:
+        if "/" not in path and path in ROOT_MANIFESTS:
+            keep = True
+        elif not manifest(path):
+            keep = path not in excluded
+        else:
+            folder = posixpath.dirname(path)
+            keep = folder in kept_holding or (folder not in holding and path not in excluded)
+        if keep:
+            kept.append(path)
+    return kept
+
+
 # --------------------------------------------------------------------------
 # Tree snapshot
 # --------------------------------------------------------------------------

package/src/shared/scripts/skf-emit-result-envelope.py

@@ -423,11 +423,12 @@ def _compute_tool_deltas(current: dict, previous) -> tuple[list[str], list[str]]
 def _resolver_warning(payload: dict) -> list[str]:
     """The customization_resolver_unavailable warning, when the payload reports one.
 
-    Every workflow's On Activation runs resolve_customization.py. When that
-    script is missing or fails, the run falls back to the skill's own
-    customize.toml, so the team and user overrides under `_bmad/custom/`
-    silently do nothing; the payload key carries the resolver's reason so
-    the envelope says so.
+    Every workflow's On Activation runs skf-resolve-customization.py, which
+    runs BMAD core's resolve_customization.py. When either script is missing
+    or fails, or a core before 6.11.0 would read another folder's overrides,
+    the run falls back to the skill's own customize.toml, so the team and
+    user overrides under `_bmad/custom/` silently do nothing; the payload
+    key carries the reason, whatever its words, so the envelope says so.
     """
     reason = payload.get("customization_resolver_unavailable")
     if not reason: