bmad-module-skill-forge 4.0.0 → 6.0.0

package/src/shared/scripts/skf-classify-changed-files.py

@@ -103,16 +103,21 @@ Modes, from the statuses:
 
 An unknown --language value adds an `unknown-language` warning.
 
-Library use: the one brief-scope test for script and asset paths.
-skf-new-file-diff.py (update-skill Category D, --brief),
-skf-detect-scripts-assets.py detect --brief (create-skill) and
-skf-compare-file-hashes.py compare --brief (audit-skill) load this file by
-its path and call load_scope(brief_path, cited). It returns a Scope:
-takes(path) is the in-scope test above (`_in_scope`), with the brief's
-`scope.include` and `scope.exclude` normalized as classify normalizes them
-and, for an empty `scope.include`, the extensions of the `cited` paths
-(the provenance map's `entries[].source_file`) and of the brief's
-`language`; wants(kind) is False for a `script` or `asset` whose
+Library use: the one brief-scope test for script and asset paths, and for
+the files a gap-driven repair reads. skf-new-file-diff.py (update-skill
+Category D, --brief), skf-detect-scripts-assets.py detect --brief
+(create-skill), skf-compare-file-hashes.py compare --brief (audit-skill)
+and skf-build-change-manifest.py gap-records --brief (update-skill
+gap-driven, which passes as `cited` each file its gaps cite or their
+Remediation names and each `entries[].source_file` of the provenance
+map) load this file by its path and call load_scope(brief_path, cited).
+It returns a Scope: takes(path) is the in-scope test above
+(`_in_scope`), with the brief's `scope.include` and `scope.exclude`
+normalized as classify normalizes them and, for an empty
+`scope.include`, the extensions of the `cited` paths (the provenance
+map's `entries[].source_file` for the first three callers) and of the
+brief's `language`, so a path with no extension is not taken; wants(kind)
+is False for a `script` or `asset` whose
 `scripts_intent` or `assets_intent` is `none` (an absent or free-text
 intent detects). load_scope raises ValueError, `brief not found: <path>`
 for a path that names no file and load_brief's message for a brief it

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-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

@@ -44,10 +44,17 @@ Subcommands:
              that name: the envelope warns that the `_bmad/custom/`
              overrides were not applied.
 
-  record     Append one entry to the run's sink: --decision reads one
-             auto-decision (a JSON object) on stdin, --warning takes the
-             warning text. With --workflow a decision is checked against
-             that workflow's headless_decisions item schema first.
+  record     Append to the run's sink: --decision reads one auto-decision
+             (a JSON object) on stdin; --warning takes one warning's text,
+             and a repeated --warning records each; --warnings-file reads a
+             JSON file that holds the warnings, an array of strings or an
+             object whose `warnings` is one (a helper's saved stdout, such
+             as skf-parse-gaps.py translate's), and records each, in order.
+             A blank or non-string warning, an unreadable file or an object
+             with no `warnings` list exits 1 and writes nothing; an empty
+             list writes nothing and exits 0. With --workflow a decision is
+             checked against that workflow's headless_decisions item schema
+             first.
 
   validate   Read an envelope (without the prefix) as JSON on stdin and
              verify it against the workflow's schema (skf-setup's without
@@ -131,7 +138,8 @@ envelope field of the same name, except `result_contract` and
 
 Run sink. Every run owns a folder, `_bmad-output/.skf-run/<workflow>-<run_id>/`,
 passed as --run-dir. Each gate records its auto-decision there the moment
-it decides, and each warning as it is raised, with `record`:
+it decides, and each warning as it is raised, with `record` (one call can
+record several warnings: each line is appended in that one write):
 
   {run_dir}/headless-decisions.jsonl   one decision object per line
   {run_dir}/warnings.jsonl             one warning string per line
@@ -299,6 +307,7 @@ the first of `uv run`, `python3`, `python` and `py -3` that works.
   uv run skf-emit-result-envelope.py emit-blocked --phase "step 2:write-tools" --path "<path>" --reason "<message>" --stderr-from "{run_dir}/write-tools.err"
   echo '{"skf_setup":{...}}' | uv run skf-emit-result-envelope.py validate
   uv run skf-emit-result-envelope.py record --run-dir "{run_dir}" --warning "customization_resolver_unavailable: <reason>"
+  uv run skf-emit-result-envelope.py record --run-dir "{run_dir}" --warnings-file "{run_dir}/translate.json"
 
 Exit codes:
   0 success
@@ -423,11 +432,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:
@@ -1787,13 +1797,42 @@ def run_emit(workflow: str | None, *, halt: bool, label: str, run_dir: str | Non
     print(envelope_line(schema, envelope), file=sys.stderr if target == "stderr" else sys.stdout)
 
 
+def _warnings_to_record(args) -> list[str]:
+    """The warnings one `record` call appends: each --warning, or the --warnings-file's list (a JSON array of
+    strings, or an object whose `warnings` is one). A blank or non-string entry, an unreadable file or an
+    object with no `warnings` list exits 1 before anything is written."""
+    if args.warnings_file is None:
+        entries, label = list(args.warning), "--warning"
+    else:
+        label = f"--warnings-file {args.warnings_file}"
+        try:
+            data = json.loads(Path(args.warnings_file).read_bytes().decode("utf-8-sig"))
+        except (OSError, UnicodeDecodeError, json.JSONDecodeError) as e:
+            _die(1, f"record: cannot read {label}: {getattr(e, 'strerror', None) or e}")
+        if isinstance(data, dict):
+            if not isinstance(data.get("warnings"), list):
+                _die(1, f"record: {label} is an object with no `warnings` list")
+            entries = data["warnings"]
+        elif isinstance(data, list):
+            entries = data
+        else:
+            _die(1, f"record: {label} holds neither a JSON array nor an object with `warnings`")
+    out = []
+    for i, entry in enumerate(entries):
+        if not isinstance(entry, str) or not entry.strip():
+            where = "" if args.warnings_file is None and len(entries) == 1 else f" (entry {i})"
+            _die(1, f"record: {label} must be a non-empty string{where}")
+        out.append(entry.strip())
+    return out
+
+
 def cmd_record(args) -> None:
-    """Append one decision or one warning to the run's sink, one JSON value per line."""
+    """Append one decision, or each warning given, to the run's sink, one JSON value per line."""
     run_dir = Path(args.run_dir)
-    if args.warning is not None:
-        value = args.warning.strip()
-        if not value:
-            _die(1, "record: --warning must be a non-empty string")
+    if args.warning is not None or args.warnings_file is not None:
+        values = _warnings_to_record(args)
+        if not values:
+            return
         name = SINK_WARNINGS
     else:
         value = _read_stdin_json("record")
@@ -1807,14 +1846,15 @@ def cmd_record(args) -> None:
             errors = _validate_against_schema(value, item_schema)
             if errors:
                 _die(1, f"record: the decision fails {schema_path.name}: {'; '.join(errors)}")
+        values = [value]
         name = SINK_DECISIONS
     # ASCII only: a raw RAW_LINE_BREAKS character would split the line for a
-    # reader that breaks lines there.
-    line = json.dumps(value, separators=(",", ":"), ensure_ascii=True) + "\n"
+    # reader that breaks lines there. Every line goes out in one write.
+    lines = "".join(json.dumps(v, separators=(",", ":"), ensure_ascii=True) + "\n" for v in values)
     try:
         run_dir.mkdir(parents=True, exist_ok=True)
         with open(run_dir / name, "a", encoding="utf-8", newline="\n") as fh:
-            fh.write(line)
+            fh.write(lines)
     except OSError as e:
         _die(1, f"record: cannot append to {(run_dir / name).as_posix()}: {e.strerror or e}")
 
@@ -1974,7 +2014,7 @@ def main() -> None:
     p_emit = sub.add_parser("emit",          help="Build a run's envelope from its context payload (default).")
     p_halt = sub.add_parser("emit-halt",     help="Build a HARD HALT's envelope from its halt payload.")
     p_blocked = sub.add_parser("emit-blocked", help="Emit skf-setup's status='blocked' envelope for early-halt paths.")
-    p_record = sub.add_parser("record",      help="Append an auto-decision or a warning to the run's sink.")
+    p_record = sub.add_parser("record",      help="Append an auto-decision or warnings to the run's sink.")
     p_validate = sub.add_parser("validate",  help="Validate an envelope payload against the schema.")
     p_render = sub.add_parser("render-report", help="Print skf-setup's FORGE STATUS banner for its payload.")
     for p in (p_emit, p_halt):
@@ -1991,7 +2031,11 @@ def main() -> None:
                           help="Check a decision against this workflow's headless_decisions schema.")
     kind = p_record.add_mutually_exclusive_group(required=True)
     kind.add_argument("--decision", action="store_true", help="Read one decision object on stdin.")
-    kind.add_argument("--warning", default=None, help="The warning text.")
+    kind.add_argument("--warning", action="append", default=None,
+                      help="A warning's text (repeatable: each one is recorded).")
+    kind.add_argument("--warnings-file", default=None, metavar="FILE",
+                      help="A JSON file of warnings: an array of strings, or an object whose `warnings` is one "
+                           "(a helper's saved stdout).")
     p_validate.add_argument("--workflow", default=None,
                             help="Workflow folder name or schema stem (skf-setup when omitted).")
     p_render.add_argument("--run-dir", default=None, help="The setup run folder that holds the staged helper outputs.")