bmad-module-skill-forge 5.0.0 → 7.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-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
@@ -1788,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")
@@ -1808,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}")
 
@@ -1975,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):
@@ -1992,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.")

package/src/shared/scripts/skf-extract-public-api.py

@@ -385,7 +385,11 @@ the line cap, say), which the caller then reads by eye. An item of a local `expo
 list takes instead the type of the top-level binding it names in its file:
 what the recipes record for that declaration exported in place (a const
 bound to an arrow function or a function expression is a function), or
-`re-export` for an import.
+`re-export` for an import. When that binding is declared in the file (not
+an import or a destructured name), the item also gets `declaration_line`
+and `declaration_signature_line`, its `$NAME` line and the source line
+holding it (an overload set's first signature); its `source_line`,
+`signature_line` and `citation` stay at the list.
 
 Entry points. The export surface each package declares: every subpath of a
 package.json `exports` map (committed .d.ts/.d.mts targets outside src/
@@ -551,7 +555,10 @@ Output JSON (stdout, or -o):
                  "citation": "[AST:<file>:L<line>]", "ast_recipe",
                  "ast_node_type", "export_type", "language",
                  "from": "<module>" | null, "from_file": "<file>" | null,
-                 "confidence": "T1", "extraction_method": "ast-grep"}, ...],
+                 "confidence": "T1", "extraction_method": "ast-grep",
+                 # only on a local export list item whose binding is
+                 # declared in the file:
+                 "declaration_line": N, "declaration_signature_line": "<line>"}, ...],
     "aggregates": {"exports": N, "by_type": {"function": N, ...},
                    "t1": N, "t1_low": 0},
     "entry_points": {"status": "barrel" | "empty-barrel" | "no-entry-point"
@@ -2009,18 +2016,22 @@ def _binding_rules(language: str) -> list[dict]:
     return rules + [r for r in _trace_rules(language) if r["id"] in IMPORT_RULES]
 
 
-def _binding_types(matches: list[dict]) -> dict[tuple[str, str], str]:
-    """(file, name) -> the export type of the top-level binding `name` has
-    in that file, from the matches of _binding_rules."""
+def _bindings(matches: list[dict]) -> dict[tuple[str, str], dict]:
+    """(file, name) -> the top-level binding `name` has in that file, from
+    the matches of _binding_rules: its form, the export type BINDING_TYPES
+    gives it (`type`), and the `line` and `signature_line` of its match. Of
+    several matches of the winning form (an overload set's signatures), the
+    lowest line wins, the line merge_exports keeps for a name."""
     rank = list(BINDING_TYPES)
-    best: dict[tuple[str, str], str] = {}
+    best: dict[tuple[str, str], tuple[tuple[int, int], dict]] = {}
     for m in matches:
         form = "import" if m["rule"] in IMPORT_RULES else m["rule"].removeprefix(f"{BINDING_RULE}-")
         if form in BINDING_TYPES and m["name"]:
-            key = (m["file"], m["name"])
-            if key not in best or rank.index(form) < rank.index(best[key]):
-                best[key] = form
-    return {key: BINDING_TYPES[form] for key, form in best.items()}
+            key, order = (m["file"], m["name"]), (rank.index(form), m["line"])
+            if key not in best or order < best[key][0]:
+                best[key] = (order, {"form": form, "type": BINDING_TYPES[form], "line": m["line"],
+                                     "signature_line": m["signature_line"]})
+    return {key: binding for key, (_, binding) in best.items()}
 
 
 # --------------------------------------------------------------------------
@@ -2743,7 +2754,10 @@ def _type_list_items(exe: str, root: Path, folder: Path, matches: list[dict], ex
     export_specifier with no `from`) the type of the top-level binding it
     names in its file, as BINDING_TYPES has it; the recipe's own
     export_type stays when no such binding has the name (a destructured
-    one)."""
+    one). A binding declared in the file (not an import) also gives the
+    item `declaration_line` and `declaration_signature_line`, its line and
+    source line; the item's own `source_line`, `signature_line` and
+    citation stay at the list."""
     items = [e for e in exports if e["ast_node_type"] == "export_specifier" and e["from"] is None]
     if not items:
         return
@@ -2755,10 +2769,16 @@ def _type_list_items(exe: str, root: Path, folder: Path, matches: list[dict], ex
     languages = sorted({lang for f in files for lang in _rule_languages(_file_language(f) or "")}
                        & set(RECIPE_LANGUAGES))
     rules = [rule for language in languages for rule in _binding_rules(language)]
-    types = _binding_types(_scan(exe, root, folder, rules, files, errors, clock))
+    bindings = _bindings(_scan(exe, root, folder, rules, files, errors, clock))
     for e in items:
         name = local.get((e["source_file"], e["ast_recipe"], e["export_name"]), e["export_name"])
-        e["export_type"] = types.get((e["source_file"], name), e["export_type"])
+        binding = bindings.get((e["source_file"], name))
+        if binding is None:
+            continue
+        e["export_type"] = binding["type"]
+        if binding["form"] != "import":
+            e["declaration_line"] = binding["line"]
+            e["declaration_signature_line"] = binding["signature_line"]
 
 
 # --------------------------------------------------------------------------

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

@@ -1021,8 +1021,9 @@ NOT_ROUTED_REASONS = {
         "`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"),
+        "the line-check rules could not verify the line, or the recorded line is not a number, so a person checks "
+        "by hand which line defines the export and, when it is not the recorded one, 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"),

package/src/shared/scripts/skf-quick-batch.py

@@ -124,6 +124,15 @@ summarize
   "succeeded", "failed", "status", "fail_fast_triggered", "exit_code",
   "summary_path"}, with "warnings" when a summary file could not be
   written. A batch already summarized prints its event again.
+  The batch's result is that event and the file its summary_path names
+  (with summary_path null, when the per-batch file could not be written,
+  the event and batch.jsonl; a summary_write_failed warning beside a set
+  summary_path means only the copy failed): <stem>-latest.json holds the
+  last batch summary written, which may be another batch's, so it never
+  stands for this batch, and a batch cut off before summarize leaves it in
+  place. A summarize on a run folder that is gone (a batch whose targets
+  all succeeded, summarized and removed) exits 1, naming the per-batch
+  file whose input_file (or input_briefs) is this batch's.
 
 The batch file is one JSON object per line, so a write cut short spoils at
 most its own line, which is skipped when read: the next write ends that
@@ -628,10 +637,14 @@ def summary_event(summary: dict) -> dict:
 
 def cmd_summarize(run_dir: Path, output_dir: Path) -> dict:
     if not (run_dir / BATCH_FILE).exists() and not run_dir.exists():
-        stem = SUMMARY_STEMS[CREATE_WORKFLOW if run_dir.name.startswith(f"{CREATE_WORKFLOW}-") else WORKFLOW]
+        create = run_dir.name.startswith(f"{CREATE_WORKFLOW}-")
+        stem = SUMMARY_STEMS[CREATE_WORKFLOW if create else WORKFLOW]
+        names = "input_briefs name its briefs" if create else "input_file names its batch file"
         raise BatchError(f"no batch in {run_dir.as_posix()}: a batch whose targets all succeeded removes its "
-                         f"run folder once summarized; its summary is "
-                         f"{(output_dir / f'{stem}-latest.json').as_posix()}")
+                         f"run folder once summarized; its summary is the {stem}-<YYYYMMDD-HHmmss>.json in "
+                         f"{output_dir.as_posix()} whose {names}, and "
+                         f"{(output_dir / f'{stem}-latest.json').as_posix()} holds the last batch summary "
+                         f"written, which may be another batch's")
     state = load(run_dir)
     name = workflow(state)
     if state["summary"] is not None: