bmad-module-skill-forge 4.0.0 → 5.0.0

package/src/shared/scripts/skf-extraction-inventory.py

@@ -37,9 +37,11 @@ Subcommands:
            any case) and its entry-point diff can be read, each export of a
            language family whose entry_points.by_language status is
            `barrel` is marked `public: true` when its name and file are a
-           pair of the diff's `public` (its name, or the name `local` gives
-           it in that file) or `extraction_gaps`, or when a `public` item of
-           its name and family has no file; `public: false` otherwise. A
+           pair of the diff's `public` or `other_definitions` (each other
+           in-scope definition of a public name, #830; its name, or the
+           name `local` gives it in that file) or `extraction_gaps`, or
+           when a `public` item of its name and family has no file;
+           `public: false` otherwise. A
            `public` item with `via` namespace and a `members` list (what
            the submodule passes on, which users reach as `pkg.sub.name`)
            gives its members' pairs (each member's name, or its `local`
@@ -208,6 +210,7 @@ Inventory shape (the keys this helper reads or writes):
     "authoritative_files_scan": {...} | null,
     "extraction_rules": {"recipe_set", "recipes", "scope", "ast_grep_version"},
     "public_surface": {"by_language": {...}, "public": [...],
+                       "other_definitions": [...],
                        "extraction_gaps": [...]} | null,
     "t2_annotations": [...], "t3_items": [...], "warnings": ["..."]
   }
@@ -447,7 +450,7 @@ class _PublicSurface:
         self.barrels = {family for family, status in statuses.items() if status == "barrel"}
         self.pairs: set[tuple[str, str]] = set()
         self.unfiled: set[tuple[object, str]] = set()  # (family, name) of a public name no file defines
-        for key in ("public", "extraction_gaps"):
+        for key in ("public", "other_definitions", "extraction_gaps"):
             for item in diff.get(key) or []:
                 if not isinstance(item, dict) or not isinstance(item.get("name"), str) or not item["name"]:
                     continue
@@ -459,8 +462,8 @@ class _PublicSurface:
                         if isinstance(member, dict) and isinstance(member.get("name"), str) and member["name"]:
                             self._add(family, member["name"], member.get("local"), member.get("file"), True)
                     continue
-                self._add(family, item["name"], item.get("local") if key == "public" else None, item.get("file"),
-                          key == "public")
+                self._add(family, item["name"], item.get("local") if key != "extraction_gaps" else None,
+                          item.get("file"), key == "public")
 
     def _add(self, family: object, name: str, local: object, path: object, listed_public: bool) -> None:
         """The pairs one public name (or gap) gives: (name, file) and (local, file), or, with no file, its
@@ -507,6 +510,7 @@ def public_surface(extraction: object) -> tuple[_PublicSurface | None, str | Non
 # The fields of an entry_point_diff item the rule reads, which the inventory's public_surface keeps for `add`, and
 # those of each member of a namespace item.
 SURFACE_FIELDS = {"public": ("name", "language", "file", "local", "via", "members"),
+                  "other_definitions": ("name", "language", "file", "local"),
                   "extraction_gaps": ("name", "language", "file")}
 MEMBER_FIELDS = ("name", "local", "file")
 NOT_PUBLIC_NAMED = 10  # the names the not-public warning spells out, as update-skill's apply does

package/src/shared/scripts/skf-extraction-snapshot.py

@@ -130,12 +130,12 @@ build
   recipe found (the runner's `entry_point_diff.extraction_gaps`), less the
   ones an export of the snapshot now holds, then, with --provenance-map,
   the baseline gaps: each entry of the map the snapshot lacks whose file
-  still declares it (the runner leaves out an underscore name such as
-  `__version__`, and a module), which would otherwise read as removed. A
-  baseline gap gives the line that declares the name, `entry` null and,
-  when the entry has one, its `export_type`. It is checked only for an
-  entry whose file is `extracted` or `read-by-eye`, whose name is not
-  dotted, and that the snapshot holds neither under its name nor under
+  still declares it (the runner leaves out a Python or Rust underscore
+  name such as `__version__`, and a module), which would otherwise read as
+  removed. A baseline gap gives the line that declares the name, `entry`
+  null and, when the entry has one, its `export_type`. It is checked only
+  for an entry whose file is `extracted` or `read-by-eye`, whose name is
+  not dotted, and that the snapshot holds neither under its name nor under
   its `reexported_as` target at that file. The selection and the
   declaration are skf-verify-provenance-completeness.py's (`baseline_gaps`,
   by `declared_line`), loaded from beside this script, the rule

package/src/shared/scripts/skf-parse-gaps.py

@@ -91,10 +91,13 @@ provenance map): for a gap with an `export` (null for one with none),
    "candidates": [{"source_file", "source_line", "export_type"}, ...]}
 
 `candidates` holds every entries[] row whose export_name is the export, in
-the map's order. With a `source_citation`, only the rows whose source_file
-is the citation's file count (both compared stripped, with backslashes read
-as `/` and no leading `./`), and of several such rows the one whose
-source_line is the citation's line. Without one, every candidate counts.
+the map's order; when no row has that export_name, every row whose
+`reexported_as` is the export (one the map holds under its declared name,
+which a gap names by the public name a re-export gives it), each view then
+adding the row's own `export_name`. With a `source_citation`, only the
+rows whose source_file is the citation's file count (both compared
+stripped, with backslashes read as `/` and no leading `./`), and of
+several such rows the one whose source_line is the citation's line. Without one, every candidate counts.
 One row left is `found` (its `entry`), several are `ambiguous` (a spot-check
 of the wrong one would move another export's line) and none is `not-found`.
 `match` prints {"status": "ok", "name", "citation", "map_match"} for a name
@@ -142,16 +145,34 @@ Translate (update-skill gap-driven.md §1): `translate` turns the gaps
 `parse` wrote (--gaps) into the change manifest, written to -o as
 {"mode": "gap-driven", "entries": [...]}. Each gap is routed by its
 `category` through CHANGE_CATEGORIES (gap-driven.md §1's table), never by
-its severity; a category the table does not hold is not routed. Each
-entry, in this key order:
+its severity; a category the table does not hold is not routed, and takes
+no entry, so nothing is written for it. A `stale-documentation` gap is not
+routed: the source has no line to repair the name from, and removing its
+documentation unchecked could delete a name the surface missed or one the
+source still declares. Nor is a `metadata-drift` gap: write.md §2's
+`metadata` call recounts the counts a patch would set (except under the
+drift override and for a docs-only skill, where it passes the counts
+metadata.json records), so no metadata patch holds. Each entry, in this
+key order:
 
   name                      the gap's `export`, else the answered `name`
   gap_id, category          the gap's `id`, its `category` (else the
                             answered one), `severity`
   severity
   source_citation           the gap's, left out when it is null or names a
-                            line inside the skill package (`SKILL.md` or a
-                            `references/*.md` file, under any folder)
+                            line inside the skill package: `SKILL.md` or a
+                            `.md` file under `references/`, written relative
+                            to the package, after `{skill_package}/`, or
+                            after the package folder of SKF's layout
+                            (`skills/{name}/{version}/{name}/` or
+                            `skills/{name}/`, after any leading folders)
+  package_citation          a `split-body-mismatch` gap's in-package
+                            citation, {"file", "line"}, its file relative to
+                            the package (`{skill_package}/` dropped): the
+                            file merge Priority 8 edits. Left out for any
+                            other gap, and for one whose category is a
+                            judgment's answer: an older report's Source may
+                            name the body it kept
   remediation_paths, resolved_paths, rejected_paths
                             the gap's ([] when parse had no --source-root);
                             a `provenance-completeness` gap with no
@@ -193,14 +214,20 @@ the gap's own text to judge from, each need one of:
                `provenance-completeness` gap with no path to scan
 
 --judgments answers them: a JSON object keyed by gap id, each value an
-object of `category` (a slug, or null: not routed), `name` (a string, or
+object of `category` (a slug, one the table does not route giving that
+category's reason, or null: not routed), `name` (a string, or
 null: not routed), `rescope` (true or false; given for any `missing-export`
 or `missing-type` gap, it is honoured) and `source_file` (a path relative
 to the source root, or null). Other keys are left for gap-records. With
 every need answered it writes the manifest and prints {"status":
 "written", "output", "gap_count", "not_routed": [{"id", "title",
-"category"}], "warnings": [...]}. `warnings` holds parse's warnings as
-`test-report: <warning>`, `test-report: not routed: <id> (<category>)` for
+"category", "reason"}], "warnings": [...]}. A not-routed gap's `reason`
+says why update-skill does not repair it and who does: NOT_ROUTED_REASONS
+gives one for each ledger category the table does not route (gap-driven.md
+§1's Not routed list), NO_REPAIR is the reason of a gap with no
+category or one no table holds, and NO_EXPORT that of a gap whose export
+is answered null. `warnings` holds parse's warnings as `test-report:
+<warning>`, `test-report: not routed: <id> (<category>): <reason>` for
 each gap not routed, and, with --read-only, `proposed-amendment: excluded
 <path> (scope-expansion); not written: --<mode>` for each rescope.
 
@@ -865,10 +892,16 @@ def _line_number(value: object) -> int | None:
 def map_match(entries: list, name: str, citation: dict | None) -> dict:
     """The provenance map entry an export names, keyed on its citation (see "Map match" in the module docstring)."""
     def view(entry: dict) -> dict:
-        return {key: entry.get(key) for key in ("source_file", "source_line", "export_type")}
+        out = {key: entry.get(key) for key in ("source_file", "source_line", "export_type")}
+        if entry["export_name"].strip() != name.strip():  # matched by its reexported_as: the name to check
+            out["export_name"] = entry["export_name"]
+        return out
 
-    named = [e for e in entries if isinstance(e, dict) and isinstance(e.get("export_name"), str)
-             and e["export_name"].strip() == name.strip()]
+    def named_by(key: str) -> list[dict]:
+        return [e for e in entries if isinstance(e, dict) and isinstance(e.get("export_name"), str)
+                and isinstance(e.get(key), str) and e[key].strip() == name.strip()]
+
+    named = named_by("export_name") or named_by("reexported_as")
     left = named
     if citation:
         cited = _norm_file(citation.get("file"))
@@ -959,7 +992,6 @@ CHANGE_CATEGORIES = {
     "provenance-completeness": "NEW_EXPORT",
     "signature-mismatch": "MODIFIED_EXPORT",
     "fabricated-signature": "MODIFIED_EXPORT",
-    "stale-documentation": "MODIFIED_EXPORT",
     "provenance-line": "MOVED_EXPORT",
     "split-body-mismatch": "STRUCTURAL_FIX",
     "structural": "STRUCTURAL_FIX",
@@ -969,9 +1001,50 @@ CHANGE_CATEGORIES = {
     "integration-pattern": "STRUCTURAL_FIX",
     "migration-section": "STRUCTURAL_FIX",
     "scripts-assets": "STRUCTURAL_FIX",
-    "metadata-drift": "metadata update",
     "metadata": "metadata update",
 }
+# gap-driven.md §1's Not routed list, word for word: why update-skill repairs no gap of each other ledger category,
+# and who does. A gap takes NO_REPAIR when it has no category or one no table holds, and NO_EXPORT when its export
+# is answered null.
+NOT_ROUTED_REASONS = {
+    "stale-documentation": (
+        "the source has no line to repair the name from, so a person removes its documentation when the name is "
+        "gone from the source, fixes the brief's scope when the surface missed it, or, when the source still "
+        "declares the name, keeps the documentation and re-runs Test Skill at a tier that classifies it"),
+    "metadata-drift": (
+        "update-skill recounts `stats.exports_public_api`, `stats.exports_documented` and "
+        "`stats.effective_denominator` each time it writes metadata.json, so a metadata patch to them does not hold "
+        "(under `--allow-workspace-drift` and for a docs-only skill it keeps the recorded public API counts and "
+        "`stats.effective_denominator` instead); Create Skill rebuilds diverging barrel counts from the source and "
+        "recounts a `stats.effective_denominator` the brief's `scope.tier_a_include` set disagrees with "
+        "(denominator drift), a person fixes denominator deflation on a brief with no tier A list by adding "
+        "`scope.tier_a_include` to it, and documented-surface counts that differ by the `Type::method` entries the "
+        "named-export count leaves out need no fix"),
+    "provenance-unverified": (
+        "the line-check rules could not verify the line, so a person checks by hand that it defines the export and, "
+        "when another line does, sets its provenance `source_line` to that line"),
+    "denominator-inflation": (
+        "it concerns the brief's scope and the count design, which a person decides in the skill brief, as the "
+        "gap's remediation says"),
+    "brief-scope-stale": (
+        "a person edits the brief's scope globs by hand so each matches the files it meant, since update-skill "
+        "does not rewrite them"),
+    "multi-denominator": (
+        "no fix is needed, since the barrel and the documented surface measure different sets by design and the "
+        "report records both counts"),
+    "numerator-inflation": "a person documents the absent exports in SKILL.md or references/, reading each from "
+                           "the source",
+    "scripts-assets-provenance": "a person adds the file's row to the provenance map's `file_entries`, or removes "
+                                 "the file from the skill",
+    "observation": "a person applies it only when they agree, since it is advisory, and a documented extra needs no "
+                   "change",
+    "discovery": "a person improves the skill's description so realistic prompts route to it, or runs the discovery "
+                 "test Test Skill skipped",
+    "description": "a person edits the description in the SKILL.md frontmatter as the gap suggests",
+    "external-validator": "a person applies the skill-check diagnostic or Tessl Review suggestion to SKILL.md",
+}
+NO_REPAIR = "update-skill has no repair for this category, so a person follows the gap's remediation"
+NO_EXPORT = "it names no export for update-skill to repair, so a person follows the gap's remediation"
 EXPORT_CATEGORIES = ("NEW_EXPORT", "MODIFIED_EXPORT", "MOVED_EXPORT", "DELETED_EXPORT")
 RESCOPE_CATEGORIES = ("missing-export", "missing-type")  # rule R1
 COMPLETENESS = "provenance-completeness"  # rule R3
@@ -985,8 +1058,14 @@ _LEDGER_REMEDIATION = re.compile(
     r"|Find the \d+ exports the denominator counts that SKILL\.md and references/ do not name "
     r"\(`[^`\n]+` lists the exports\) and document each with its signature\."
 )
-# A citation of generated markdown: the skill's SKILL.md or a references/*.md file.
-_PACKAGE_FILE = re.compile(r"(?:^|/)(?:SKILL\.md|references/[^/]+\.md)$")
+# A citation of generated markdown: the skill's SKILL.md or a .md file under its references/, relative to the
+# package, after `{skill_package}/`, or after the package folder of SKF's layout as a project-relative path
+# (`skills/{name}/{version}/{name}/`, or the flat `skills/{name}/`, after any leading folders). A path under any
+# other folder (`docs/references/guide.md`) is source.
+_PACKAGE_FILE = re.compile(
+    r"(?:\{skill_package\}/|(?:[^/]+/)*skills/(?P<name>[^/]+)/(?:[^/]+/(?P=name)/)?)?"
+    r"(?P<file>SKILL\.md|references/(?:[^/]+/)*[^/]+\.md)")
+SPLIT_BODY = "split-body-mismatch"
 # The answers translate reads, with the JSON types each takes.
 _ANSWER_TYPES = {"category": (str, type(None)), "name": (str, type(None)), "rescope": (bool,),
                  "source_file": (str, type(None))}
@@ -994,14 +1073,38 @@ _IS_WINDOWS = os.name == "nt"
 _REPLACE_WAIT_SECONDS = 5.0
 
 
+def _package_path(citation: dict | None) -> str | None:
+    """The citation's file relative to the skill package, or None when it names no file of the package."""
+    path = _norm_file(citation.get("file")) if isinstance(citation, dict) else None
+    path = path.strip("`") if path else None
+    found = _PACKAGE_FILE.fullmatch(path) if path and ".." not in path.split("/") else None
+    return found.group("file") if found else None
+
+
 def in_skill_package(citation: dict | None) -> bool:
     """True when a citation names a line of generated markdown, not source.
 
-    >>> [in_skill_package({"file": f, "line": 1}) for f in ("SKILL.md", "{skill_package}/references/api.md", "src/a.ts")]
-    [True, True, False]
+    >>> [in_skill_package({"file": f, "line": 1}) for f in ("SKILL.md", "{skill_package}/references/api.md",
+    ...                                                     "references/integrations/a-b.md", "src/a.ts",
+    ...                                                     "skills/oms-cognee/0.5.8/oms-cognee/SKILL.md",
+    ...                                                     "docs/references/guide.md")]
+    [True, True, True, False, True, False]
     """
-    path = _norm_file(citation.get("file")) if isinstance(citation, dict) else None
-    return bool(path and _PACKAGE_FILE.search(path))
+    return _package_path(citation) is not None
+
+
+def package_citation(citation: dict | None) -> dict | None:
+    """An in-package citation with its file relative to the package, else None.
+
+    >>> for f in ("{skill_package}/references/api.md", "SKILL.md", "skills/lib/references/api.md", "src/a.ts"):
+    ...     print(package_citation({"file": f, "line": 3}))
+    {'file': 'references/api.md', 'line': 3}
+    {'file': 'SKILL.md', 'line': 3}
+    {'file': 'references/api.md', 'line': 3}
+    None
+    """
+    path = _package_path(citation)
+    return {"file": path, "line": citation.get("line")} if path else None
 
 
 def written_remediation(text: object) -> bool:
@@ -1051,9 +1154,10 @@ def translate_gaps(parsed: dict, map_entries: list, judgments: dict, *, read_onl
     entries: list[dict] = []
     not_routed: list[dict] = []
 
-    def skip(gap: dict, category: str | None) -> None:
-        not_routed.append({"id": gap["id"], "title": gap.get("title"), "category": category})
-        warnings.append(f"test-report: not routed: {gap['id']} ({category or 'no category'})")
+    def skip(gap: dict, category: str | None, reason: str | None = None) -> None:
+        reason = reason or NOT_ROUTED_REASONS.get(category or "", NO_REPAIR)
+        not_routed.append({"id": gap["id"], "title": gap.get("title"), "category": category, "reason": reason})
+        warnings.append(f"test-report: not routed: {gap['id']} ({category or 'no category'}): {reason}")
 
     def ask(gap: dict, category: str | None, want: list[str]) -> None:
         needs.append({"gap_id": gap["id"], "title": gap.get("title"), "category": category,
@@ -1079,11 +1183,14 @@ def translate_gaps(parsed: dict, map_entries: list, judgments: dict, *, read_onl
         name = export or _answer_text(answers.get("name"))
         if change in EXPORT_CATEGORIES and name is None:
             if "name" in answers:  # answered null: no export to repair
-                skip(gap, category)
+                skip(gap, category, NO_EXPORT)
             else:
                 ask(gap, category, ["name"])
             continue
         citation = gap.get("source_citation")
+        # the gap's own category, which the ledger recorded: a judged one is an older report's, whose Source may
+        # name the body that report still kept
+        package = package_citation(citation) if gap.get("category") == SPLIT_BODY else None
         if in_skill_package(citation):
             citation = None
         match = map_match(map_entries, name, citation) if name else None
@@ -1123,6 +1230,8 @@ def translate_gaps(parsed: dict, map_entries: list, judgments: dict, *, read_onl
         entry = {"name": name, "gap_id": gap["id"], "category": category, "severity": gap.get("severity")}
         if citation:
             entry["source_citation"] = citation
+        if package:
+            entry["package_citation"] = package
         entry["remediation_paths"] = list(gap.get("remediation_paths") or [])
         entry["resolved_paths"] = resolved
         entry["rejected_paths"] = rejected

package/src/shared/scripts/skf-render-metadata-stats.py

@@ -73,7 +73,7 @@ Judgment payload (stdin JSON, compute mode)::
 
     {
       "exports_public_api":  40,          # int  — public-entry-point export count (judgment)
-      "exports_internal":    19,          # int  — non-underscore internal export count (judgment)
+      "exports_internal":    19,          # int: internal export count, Python/Rust/Dart `_` names left out (judgment)
       "effective_denominator": 12,        # int|null — optional, curated-subset scopes only
       "pattern_surfaces_documented": 8,   # int  — reference-app only (exports_documented proxy)
       "exports_documented":  0,           # int  — stack only (own-barrel count, usually 0)

package/src/shared/scripts/skf-resolve-customization.py

@@ -0,0 +1,197 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+"""SKF Resolve Customization: BMAD core's customization resolver, on any core from 6.4.0.
+
+Every SKF workflow, and Ferris, reads its `_bmad/custom/` overrides through
+BMAD core's customization resolver, `_bmad/scripts/resolve_customization.py`
+under the project root, which the BMAD Method installer adds. SKF passes it
+`--project-root`, a flag core takes only from 6.11.0: core 6.4.0 to 6.10.0
+stops on it with argparse's exit 2, so SKF runs this helper in its place.
+It takes core's long flags only (core's -s, -p and -k are refused):
+
+  uv run skf-resolve-customization.py --skill <skill-root> \\
+      --project-root <project-root> --key <key> [--key <key>]...
+
+1. It runs core's resolver with those arguments, `--project-root` included,
+   under its own interpreter, from the project root. `uv run` gives this
+   file a Python that meets its requires-python, which core needs for
+   `tomllib`; core 6.10.0 and earlier declare none, so uv would not choose
+   one for them.
+2. When core rejects `--project-root` (exit 2, nothing on stdout, and
+   `error: unrecognized arguments: ... --project-root` on stderr), it works
+   out the root a core before 6.11.0 picks without the flag: the nearest
+   folder, from the skill folder up and the skill folder itself first, that
+   holds `_bmad` or `.git` (a file or a folder), else the same search from
+   the project root. When that is the project root, it runs core again
+   without the flag, and that run's result is the helper's. Otherwise core
+   would read another folder's overrides, so it refuses.
+
+Output:
+  stdout  on exit 0, core's stdout byte for byte (the JSON core prints);
+          on any other exit, nothing.
+  stderr  the stderr of the core run whose result is the helper's: on a
+          rerun without the flag, the rerun's only (the rejected call's is
+          dropped). A failure of the helper's own prints one line first: the
+          reason a workflow's warning quotes.
+
+Exit codes:
+  0  core resolved the customization
+  1  core's resolver is missing (first stderr line: `not found`), could
+     not start, did not finish or was stopped by a signal, or core exited 1
+     (a customize.toml or an override it cannot read)
+  2  a core before 6.11.0 would read the overrides under another folder
+     (first stderr line: `BMAD core before 6.11.0: ...`), a usage error of
+     the helper's, or core's own exit 2 (a core from 6.11.0), passed through
+  3  core found no Python 3.11 or later (`tomllib`)
+  Any other exit code is core's own, passed through.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+CORE_RESOLVER = ("_bmad", "scripts", "resolve_customization.py")
+FIRST_CORE_WITH_FLAG = "6.11.0"
+CORE_TIMEOUT_SEC = 120
+PROJECT_ROOT_FLAG = "--project-root"
+MISSING = "not found"
+ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
+# argparse's line for a flag it does not know, wherever the usage line wraps.
+REJECTED_FLAG_RE = re.compile(r"error: unrecognized arguments: (?:.*\s)?--project-root(?:[=\s]|$)", re.M)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skf-resolve-customization",
+        description=(
+            "Run BMAD core's customization resolver with --project-root. On a core before "
+            f"{FIRST_CORE_WITH_FLAG}, which rejects that flag, run it again without the flag when "
+            "core would read this project's overrides anyway, and refuse otherwise."
+        ),
+    )
+    parser.add_argument("--skill", required=True, help="the skill folder that holds customize.toml")
+    parser.add_argument(
+        "--project-root",
+        required=True,
+        help="the project folder: core's resolver is under its _bmad/scripts/, the overrides under _bmad/custom/",
+    )
+    parser.add_argument(
+        "--key",
+        action="append",
+        default=[],
+        help="a dotted key to resolve, repeatable; with none, core prints the whole merge",
+    )
+    return parser
+
+
+def _nearest_marked(start: Path) -> Path | None:
+    """The nearest folder, `start` itself first, holding `_bmad` or `.git` (a file or a folder)."""
+    current = start.resolve()
+    while True:
+        if (current / "_bmad").exists() or (current / ".git").exists():
+            return current
+        if current.parent == current:
+            return None
+        current = current.parent
+
+
+def legacy_project_root(skill: Path, cwd: Path) -> Path | None:
+    """The project root BMAD core 6.4.0 to 6.10.0 picks without --project-root, run from `cwd`."""
+    return _nearest_marked(skill) or _nearest_marked(cwd)
+
+
+def _same_folder(a: Path, b: Path) -> bool:
+    try:
+        return os.path.samefile(a, b)
+    except OSError:
+        return a.resolve() == b.resolve()
+
+
+def rejects_project_root(returncode: int, stdout: bytes, stderr: bytes) -> bool:
+    """True when core stopped on --project-root as a flag it does not know; never on exit 2 alone."""
+    if returncode != 2 or stdout:
+        return False
+    text = ANSI_RE.sub("", stderr.decode("utf-8", "replace"))
+    return REJECTED_FLAG_RE.search(text) is not None
+
+
+def _run_core(argv: list[str], cwd: Path) -> subprocess.CompletedProcess:
+    env = dict(os.environ)
+    # Core 6.11.0 and later import config_utils from their own folder, which a safe path drops.
+    env.pop("PYTHONSAFEPATH", None)
+    # Core before 6.8.0 writes its JSON in the locale's encoding.
+    env["PYTHONIOENCODING"] = "utf-8"
+    return subprocess.run(
+        argv, cwd=cwd, env=env, stdin=subprocess.DEVNULL, capture_output=True,
+        timeout=CORE_TIMEOUT_SEC, check=False,
+    )
+
+
+def _write(stream, data: bytes) -> None:
+    if not data:
+        return
+    buffer = getattr(stream, "buffer", None)
+    if buffer is None:
+        stream.write(data.decode("utf-8", "replace"))
+        stream.flush()
+        return
+    buffer.write(data)
+    buffer.flush()
+
+
+def _say(*lines: str) -> None:
+    _write(sys.stderr, "".join(line + "\n" for line in lines).encode("utf-8"))
+
+
+def _finish(proc: subprocess.CompletedProcess) -> int:
+    """Core's result as the helper's: its stdout only on exit 0, its stderr always."""
+    if proc.returncode < 0:  # stopped by a signal: core may have printed no reason
+        _say(f"BMAD core's customization resolver was stopped by signal {-proc.returncode}")
+        _write(sys.stderr, proc.stderr)
+        return 1
+    if proc.returncode == 0:
+        _write(sys.stdout, proc.stdout)
+    _write(sys.stderr, proc.stderr)
+    return proc.returncode
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    root = Path(os.path.abspath(args.project_root))
+    skill = Path(os.path.abspath(args.skill))
+    core = root.joinpath(*CORE_RESOLVER)
+    if not core.is_file():
+        _say(MISSING, f"BMAD core's customization resolver is not at {core}: the BMAD Method installer adds it.")
+        return 1
+    command = [sys.executable, str(core), "--skill", str(skill)]
+    keys = [word for key in args.key for word in ("--key", key)]
+    try:
+        first = _run_core([*command, PROJECT_ROOT_FLAG, str(root), *keys], root)
+        if not rejects_project_root(first.returncode, first.stdout, first.stderr):
+            return _finish(first)
+        legacy = legacy_project_root(skill, root)
+        if legacy is not None and _same_folder(legacy, root):
+            return _finish(_run_core([*command, *keys], root))
+    except subprocess.TimeoutExpired:
+        _say(f"BMAD core's customization resolver did not finish within {CORE_TIMEOUT_SEC} seconds")
+        return 1
+    except OSError as exc:
+        _say(f"BMAD core's customization resolver could not start: {exc}")
+        return 1
+    _say(
+        f"BMAD core before {FIRST_CORE_WITH_FLAG}: its customization resolver takes no {PROJECT_ROOT_FLAG} "
+        f"and would read the overrides under {legacy}, not under {root}; upgrade BMAD core to "
+        f"{FIRST_CORE_WITH_FLAG} or later"
+    )
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())