bmad-module-skill-forge 5.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-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-verify-provenance-completeness.py

@@ -71,8 +71,15 @@ not read as a missing public export nor as an orphan.
 Definition lines: after a citation resolves (the file exists and the line
 is in range, so the older reasons win), the line must define the entry's
 export. NAME is the raw `export_name` (not canonicalized); for a dotted
-name (`App.update`) it is the last segment. The rules follow the
-`source_file` extension:
+name (`App.update`) it is the last segment. A bookkeeping variant
+(`X_def`, `X_exact`, `a11y_X`, test-skill's Source Access Protocol fold
+without `--fold-prefix` or `--keep`) that the cited file never names (no
+whole identifier in its text) is checked against its base `X` instead,
+its finding carries `folded_to`, and `summary.line_check_folded` counts
+it; the raw name always comes first, so an export really named
+`parse_exact`, or bound in a shape the rules do not cover, is judged as
+written. classify-stale never folds. The rules
+follow the `source_file` extension:
 
   - Python (`.py`, `.pyi`): the `def` / `async def` / `class NAME` line
     itself (a decorator line above it does not count); an assignment
@@ -262,7 +269,9 @@ Subcommands:
            "source_line": <int|null>,
            "reason": "file-missing" | "line-out-of-bounds" | "line-invalid"
                      | "line-not-definition",
-           "definition_lines": [<int>, ...]},   # line-not-definition only
+           "definition_lines": [<int>, ...],    # line-not-definition only
+           "folded_to": "<base name>"},         # line-not-definition only,
+                                                # a variant checked as its base
           ...
         ],
         "citations": [
@@ -302,6 +311,7 @@ Subcommands:
           "stale_count":      <int>,
           "citations_checked": <int>,  # entries whose citation was resolved
           "line_check_skipped": <int>, # resolved entries with no line rule
+          "line_check_folded": <int>,  # variants checked against their base
           "stale_check": "checked" | "skipped-no-source-root",
           "skill_citations_scanned": <int>,  # [AST:]/[SRC:] with a line
           "skill_citations_matched": <int>,  # of those, citing an entry
@@ -413,12 +423,15 @@ Subcommands:
                       | "skipped-language",
         "definition_lines": [<int>, ...] | null,   # checked only
         "source_line": <int> | null,               # --line
-        "line_is_definition": <bool> | null        # --line, checked only
+        "line_is_definition": <bool> | null,       # --line, checked only
+        "folded_to": "<base name>"                 # a folded variant only
       }
 
     With `--line`, a recorded line that is an indented match the column-0
     rule dropped joins `definition_lines`, and one that misses a Python
-    `@overload` group gives its first line alone, as in `verify`.
+    `@overload` group gives its first line alone, as in `verify`. A
+    bookkeeping variant the file never names is checked against its base,
+    as in `verify`, and only then does the key `folded_to` appear.
 
   classify-stale --names <coverage.json> --provenance <provenance-map.json>
                  --source-root <path> [--inventory <inventory.json>]
@@ -428,7 +441,8 @@ Subcommands:
     documented name the enumerated source surface lacks): the
     definition-lines rules above, run for every provenance entry whose raw
     `export_name` is the name, at its `source_file` and `source_line`, with
-    its `export_type`. `--names` holds reconcile-coverage.py's result (its
+    its `export_type`, and with no bookkeeping-variant fold (the name is
+    judged as written). `--names` holds reconcile-coverage.py's result (its
     `stale` names) or a JSON array of names. `--inventory` holds the
     documented inventory, validate-inventory.py's `--output` file or its
     whole result: the `kind` it gives each name decides the module rule
@@ -1046,6 +1060,28 @@ def definition_name(export_name: str) -> str:
     return export_name.rsplit(".", 1)[-1]
 
 
+# Bookkeeping variants folded to their base name, in rule order: test-skill's
+# Source Access Protocol defines the fold (`X_def`, `X_exact`, `a11y_X` -> `X`).
+# Keep identical to FOLD_SUFFIXES and FOLD_PREFIX in load-coverage-inputs.py.
+FOLD_SUFFIXES = ("_def", "_exact")
+FOLD_PREFIX = "a11y_"
+
+
+def fold_base(export_name: str) -> str | None:
+    """The base name a bookkeeping variant folds to, None for a name that is
+    no variant: a suffix in FOLD_SUFFIXES first, else FOLD_PREFIX, never the
+    whole name (`_def` alone is no variant). The rules of
+    load-coverage-inputs.py `fold_names`, without `--fold-prefix` or
+    `--keep`: the line check tries the raw name first, so a real export
+    named like a variant is never folded."""
+    for suffix in FOLD_SUFFIXES:
+        if export_name.endswith(suffix) and len(export_name) > len(suffix):
+            return export_name[: -len(suffix)]
+    if export_name.startswith(FOLD_PREFIX) and len(export_name) > len(FOLD_PREFIX):
+        return export_name[len(FOLD_PREFIX):]
+    return None
+
+
 def _read_lines(path: Path) -> list[str] | None:
     """Read a text file as lines numbered like `check_citation` counts them
     (universal newlines; a UTF-8 BOM is dropped so it never hides line 1).
@@ -2135,6 +2171,42 @@ def _definition_matches(
     return _line_matches(suffix, path, lines, export_name, cache, declarations_only)
 
 
+def _folded_matches(
+    source_file: str,
+    export_name: str,
+    source_root: Path,
+    cache: _SourceCache | None = None,
+) -> tuple[tuple[list[int], set[int]] | None, str | None]:
+    """(`_definition_matches` of the name the line check judges, the base
+    name a bookkeeping variant was folded to, else None).
+
+    The raw name comes first. Only when the file never names it (no whole
+    identifier in its text, so no shape the rules miss can define it) and
+    `fold_base` gives a base that some line matches are the base's matches
+    returned, with the base; otherwise the raw name's, with None. So a real
+    export named like a variant (`parse_exact` defined as itself, or bound
+    in a shape the rules do not cover) is judged as written, and
+    classify-stale, which never folds, does not call this.
+    """
+    cache = cache if cache is not None else _SourceCache()
+    matches = _definition_matches(source_file, export_name, source_root, cache)
+    if matches is None or matches[1]:
+        return matches, None
+    base = fold_base(export_name)
+    if base is None:
+        return matches, None
+    # the variant's own identifiers: `mockChannel_def`, or `a11y_App` of `a11y_App.update`
+    own = sorted(set(export_name.split(".")) - set(base.split(".")))
+    named = re.compile(r"(?<![\w$])(?:" + "|".join(map(re.escape, own)) + r")(?![\w$])")
+    lines = cache.lines((source_root / source_file.strip().replace("\\", "/")).resolve())
+    if not own or lines is None or any(named.search(text) for text in lines):
+        return matches, None
+    folded = _definition_matches(source_file, base, source_root, cache)
+    if folded is None or not folded[1]:
+        return matches, None
+    return folded, base
+
+
 def _line_matches(
     suffix: str,
     path: Path,
@@ -2223,6 +2295,7 @@ def definition_lines_report(
     source_root: Path,
     line: int | None = None,
     export_type: str | None = None,
+    fold: bool = True,
 ) -> dict:
     """What `verify` would say about one entry's line (the definition-lines
     subcommand). Raises ValueError when the file exists but cannot be read.
@@ -2234,6 +2307,12 @@ def definition_lines_report(
     (`_missed_definition_lines`): an indented match the column-0 rule
     dropped joins `definition_lines`, so the answer carries several lines,
     and a Python `@overload` group gives its first line alone.
+
+    With `fold` (the default, as `verify` checks), a bookkeeping variant the
+    file never names is checked against its base name (`_folded_matches`),
+    and the report gains `folded_to`, the base, only when it folded.
+    classify-stale passes `fold=False`: the fabricated-signature test judges
+    the documented name as written.
     """
     report: dict = {
         "source_file": source_file,
@@ -2253,15 +2332,21 @@ def definition_lines_report(
         report["line_check"] = "skipped-export-type" if covered else "skipped-language"
         return report
     cache = _SourceCache()
-    matches = _definition_matches(source_file, export_name, source_root, cache)
+    if fold:
+        matches, folded_to = _folded_matches(source_file, export_name, source_root, cache)
+    else:
+        matches, folded_to = _definition_matches(source_file, export_name, source_root, cache), None
     if matches is None:
         raise ValueError(f"failed to read source file {source_root / rel}")
+    if folded_to is not None:
+        report["folded_to"] = folded_to
+    judged = folded_to or export_name
     defs, every = matches
     if line is not None:
         report["line_is_definition"] = line in defs
         if line not in defs:
             defs = _missed_definition_lines(
-                source_file, export_name, source_root, cache, line, defs, every
+                source_file, judged, source_root, cache, line, defs, every
             )
     report["definition_lines"] = defs
     return report
@@ -2307,7 +2392,10 @@ def _entry_citation(entry: dict) -> str | None:
 def _stale_line_check(
     entry: dict, name: str, source_root: Path
 ) -> tuple[str, list[int] | None]:
-    """(line_check, definition_lines) of one provenance entry of a stale name."""
+    """(line_check, definition_lines) of one provenance entry of a stale name.
+
+    The documented name is judged as written, with no bookkeeping-variant
+    fold: a variant the cited file never defines stays fabricated."""
     source_file = _entry_file(entry)
     if source_file is None:
         # no file to check: it neither proves the name fabricated nor clears it
@@ -2321,6 +2409,7 @@ def _stale_line_check(
             source_root,
             line if isinstance(line, int) else None,
             export_type if isinstance(export_type, str) else None,
+            fold=False,
         )
     except ValueError:
         # the file exists but cannot be read: nothing proves it
@@ -3677,6 +3766,7 @@ def verify(
     stale: list[dict] = []
     citations_checked = 0
     line_check_skipped = 0
+    line_check_folded = 0
     if source_root is not None:
         cache = _SourceCache()
         entries = prov.get("entries")
@@ -3717,10 +3807,14 @@ def verify(
                 if not line_rule_applies(sf, entry.get("export_type")):
                     line_check_skipped += 1
                     continue
-                matches = _definition_matches(sf, name, source_root, cache)
+                # A bookkeeping variant the file never names is checked
+                # against its base name (`folded_to`).
+                matches, folded_to = _folded_matches(sf, name, source_root, cache)
                 if matches is None:
                     line_check_skipped += 1
                     continue
+                if folded_to is not None:
+                    line_check_folded += 1
                 defs, every = matches
                 if line not in defs:
                     # An indented match the column-0 rule dropped joins
@@ -3728,8 +3822,10 @@ def verify(
                     # group gives its first line alone, the move target.
                     item["reason"] = STALE_LINE_NOT_DEFINITION
                     item["definition_lines"] = _missed_definition_lines(
-                        sf, name, source_root, cache, line, defs, every
+                        sf, folded_to or name, source_root, cache, line, defs, every
                     )
+                    if folded_to is not None:
+                        item["folded_to"] = folded_to
                     stale.append(item)
         stale.sort(key=lambda s: (s["export_name"], s.get("source_file") or ""))
 
@@ -3771,6 +3867,7 @@ def verify(
         "stale_count": len(stale),
         "citations_checked": citations_checked,
         "line_check_skipped": line_check_skipped,
+        "line_check_folded": line_check_folded,
         "stale_check": "checked"
         if source_root is not None
         else "skipped-no-source-root",

package/src/skf-analyze-source/SKILL.md

@@ -28,6 +28,7 @@ You are a source code analyst and decomposition architect collaborating with a d
 These rules apply to every step in this workflow:
 
 - Only load one step file at a time — never preload future steps
+- Run every subagent in the foreground (parallel ones as several calls in one message, never with `run_in_background`) and wait for every long-running command to exit before the next instruction; in a headless run, never end a turn while either still runs, since under `claude -p` a run stops when its turn ends.
 - Always communicate in `{communication_language}`; the text persisted into `skill-brief.yaml` (each recommendation's `description` and `scope.notes`) is written in `{document_output_language}`
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action, and record each one in the run sink as the gate says
 

package/src/skf-analyze-source/references/generate-briefs.md

@@ -287,7 +287,7 @@ The shared emitter writes the result files and prints the envelope; this section
 uv run {emitEnvelopeHelper} emit --workflow skf-analyze-source --run-dir "{run_dir}" --result-dir "{forge_data_folder}" < "{run_dir}/result-context.json"
 ```
 
-The emitter stamps the UTC time and the run id into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy (the stable path pipeline consumers read), and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout (field rules in `references/headless-contract.md`). When `{headless_mode}` is true, display the line verbatim: it is the success signal of a headless run. A result file that could not be written leaves the line's `result_path` null and a `result_file_write_failed` warning in it, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `generate-briefs:9`, path `{forge_data_folder}`, with `brief_paths` and `unit_counts` from the payload): "The result contract could not be written: {its message}."
+The emitter stamps the UTC time and the run id into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy (the record of the last run whose emitter wrote this copy, at a stable path; a caller reads its own run's `SKF_ANALYZE_RESULT_JSON` line), and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout (field rules in `references/headless-contract.md`). When `{headless_mode}` is true, display the line verbatim: it is the success signal of a headless run. A result file that could not be written leaves the line's `result_path` null and a `result_file_write_failed` warning in it, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `generate-briefs:9`, path `{forge_data_folder}`, with `brief_paths` and `unit_counts` from the payload): "The result contract could not be written: {its message}."
 
 ### 9b. On-Complete Hook (pipeline integration)
 

package/src/skf-analyze-source/references/headless-contract.md

@@ -4,7 +4,7 @@ Canonical headless/pipeline contract for skf-analyze-source. The shared emitter,
 
 ## Result Envelope
 
-The step that ends a run (step 6 §9, step 1a §9, or the docs-only branch §5) prints the envelope on **stdout** before chaining to step 7, and displays it when `{headless_mode}` is true. Every HARD HALT of a headless run prints it on **stderr** with `status: "error"`, so an automator branches on the failure class without grepping message text.
+The step that ends a run (step 6 §9, step 1a §9, or the docs-only branch §5) prints the envelope on **stdout** before chaining to step 7, and displays it when `{headless_mode}` is true. Every HARD HALT of a headless run prints it on **stderr** with `status: "error"`, so an automator branches on the failure class without grepping message text. A caller reads the run's own `SKF_ANALYZE_RESULT_JSON` line. A run that printed no envelope line has no result to read, whatever the process exit code: it was cut off, or could not write its result, and `analyze-source-result-latest.json` may then describe an earlier run, so it is never read in its place.
 
 ```
 SKF_ANALYZE_RESULT_JSON: {"status":"success|error|redirect|skipped","report_path":"…|null","brief_paths":["…"],"unit_counts":{"confirmed":N,"skipped":N,"maybe":N},"exit_code":0,"halt_reason":null,"mode":"interactive|auto","result_path":"…|null"}

package/src/skf-audit-skill/SKILL.md

@@ -28,6 +28,7 @@ You are a skill auditor in Ferris Audit mode: a deterministic drift-detection wo
 
 - Never fabricate findings — all data must trace to source code with file:line citations
 - Only load one step file at a time — never preload future steps
+- Run every subagent in the foreground (parallel ones as several calls in one message, never with `run_in_background`) and wait for every long-running command to exit before the next instruction; in a headless run, never end a turn while either still runs, since under `claude -p` a run stops when its turn ends.
 - Update `stepsCompleted` in output file frontmatter before loading next step
 - Always communicate in `{communication_language}`
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision; step 1's gates (manifest-vs-link, upstream-drift, baseline confirm) also record theirs in the run sink as they decide
@@ -59,7 +60,7 @@ Stage 1b returns to init.md at §5b's **Record for report**, then §6. Step 1 §
 | **Inputs** | `skill_name` [required], `skill_path` [optional: the skill folder, bypassing manifest/symlink resolution], `tier_override` [optional: Quick / Forge / Forge+ / Deep, in place of the detected tier], `upstream_drift_choice` [optional: C / S / X; answers the upstream-drift gate in references/upstream-checkout.md; C, auditing the upstream ref from a private tree, when unset] |
 | **Gates** | step 1: Manifest-vs-Symlink Gate [N/M/X] · Upstream-Drift Gate [C/S/X] (references/upstream-checkout.md, only when upstream moved) · Baseline Confirm Gate [C/X] (only on a doubt: the forge tier is below the compile tier, or the provenance map is more than 90 days old) |
 | **Outputs** | The drift report, the JSON it was built from and the result contract, in `{forge_version}/` (the audited version's folder): `references/headless-contract.md` names each file |
-| **Headless** | Every gate takes its default action, a pre-supplied `upstream_drift_choice` answers the upstream-drift gate, `tier_override` sets the tier (step 1 §2), and each gate's decision lands in the envelope's `headless_decisions` |
+| **Headless** | Every gate takes its default action, a pre-supplied `upstream_drift_choice` answers the upstream-drift gate, `tier_override` sets the tier (step 1 §2), and each gate's decision lands in the envelope's `headless_decisions`. A caller reads the run's own `SKF_AUDIT_RESULT_JSON` line. A run that printed no envelope line has no result to read, whatever the process exit code: it was cut off, or could not write its result, and `audit-skill-result-latest.json` may then describe an earlier run, so it is never read in its place. |
 | **Exit codes** | `references/headless-contract.md`: each halt class's exit code and `halt_reason`, and the `SKF_AUDIT_RESULT_JSON` envelope |
 
 ## On Activation

package/src/skf-audit-skill/references/report.md

@@ -196,7 +196,7 @@ When On Activation step 3 fell back to the bundled `customize.toml`, add `"custo
 uv run {emitEnvelopeHelper} emit --workflow skf-audit-skill --run-dir "{run_dir}" --result-dir "{forge_version}" < "{run_dir}/result-context.json"
 ```
 
-It writes `{forge_version}/audit-skill-result-{YYYYMMDD-HHmmss}.json` (UTC; it picks the name) and its `audit-skill-result-latest.json` copy (stable path for pipeline consumers: a copy, not a symlink), stamps the timestamp, `run_id`, `headless_decisions` and `warnings` into both, and prints the `SKF_AUDIT_RESULT_JSON:` line on stdout. When `{headless_mode}` is true, bind `{result_envelope_line}` ← the line and do not display it here: the shared health check displays it verbatim as the run's last line, so a `claude -p` caller reads `drift_score`, `report_path`, `next_workflow`, `upstream_moved` and `upstream_ref` from the final message. A result file that could not be written leaves `result_path` null and a `result_file_write_failed` warning in the line, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HALT with **exit 4**, `halt_reason: "write-failed"`, phase `report:result-contract`: the run's result contract could not be written.
+It writes `{forge_version}/audit-skill-result-{YYYYMMDD-HHmmss}.json` (UTC; it picks the name) and its `audit-skill-result-latest.json` copy (the record of the last run whose emitter wrote this copy, at a stable path: a copy, not a symlink; a caller reads its own run's `SKF_AUDIT_RESULT_JSON` line), stamps the timestamp, `run_id`, `headless_decisions` and `warnings` into both, and prints the `SKF_AUDIT_RESULT_JSON:` line on stdout. When `{headless_mode}` is true, bind `{result_envelope_line}` ← the line and do not display it here: the shared health check displays it verbatim as the run's last line, so a `claude -p` caller reads `drift_score`, `report_path`, `next_workflow`, `upstream_moved` and `upstream_ref` from the final message. A result file that could not be written leaves `result_path` null and a `result_file_write_failed` warning in the line, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HALT with **exit 4**, `halt_reason: "write-failed"`, phase `report:result-contract`: the run's result contract could not be written.
 
 **Hard-halt envelope (headless only).** Every hard halt prints its envelope through the emitter on **stderr** with `status: "error"` and the `exit_code` / `halt_reason` for its failure class, as each step's **Halt envelope** paragraph shows: it is the only failure signal a wrapping pipeline receives. `drift_score` carries its last known value (`null` if classification never ran); `report_path` is `null` when the report write failed.
 

package/src/skf-brief-skill/SKILL.md

@@ -32,6 +32,7 @@ You are a skill scoping architect collaborating with a developer who wants to cr
 These rules apply to every step in this workflow:
 
 - Only load one step file at a time — never preload future steps
+- Run every subagent in the foreground (parallel ones as several calls in one message, never with `run_in_background`) and wait for every long-running command to exit before the next instruction; in a headless run, never end a turn while either still runs, since under `claude -p` a run stops when its turn ends.
 - **Lazy-load references and assets:** `references/*.md` and `assets/*.md` files are loaded inside the section that needs them, not at step entry. If a section is skipped (e.g. `version-resolution.md` when step 2's extractor ran, `scope-templates.md` for the `docs-only` branch that bypasses §2c), do not load that file. Each unnecessary load costs context (~5-10 KB per reference) and biases the LLM toward consulting material the current path does not need.
 - Always communicate in `{communication_language}` (the language for user-facing prose). Written artifact text — the `description`, `notes`, and other free-form fields persisted into `skill-brief.yaml` — is in `{document_output_language}`; per-step rules call this out where it applies (see step 5). The two values may be the same.
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision

package/src/skf-brief-skill/references/invocation-contract.md

@@ -9,8 +9,8 @@ Full argument set, gate map, exit codes, and headless result envelope for `skf-b
 | **Inputs** | The headless arguments, each with its default and the halt it can raise, are the Arguments table of `references/headless-args.md`, which `skf-validate-brief-inputs.py` enforces: `target_repo` and `skill_name` are required, every other one is optional. Two of them route the run elsewhere: `from_brief` [optional: path to a pre-authored `skill-brief.yaml` to *ratify*: when supplied it is the source of truth, `target_repo`/`skill_name` become optional/derived-from-brief, and the run mirrors the interactive §3.1a ratify path: schema-validate, skip analyze-target/scope-definition, write through the canonical writer to `{forge_data_folder}/{name}/skill-brief.yaml`: no `force` needed when the brief already lives at that path; otherwise `force` applies as on the derive route], `[auto]` [optional: bracket modifier passed via pipeline context: when present, BS loads the upstream brief from `brief_path` in pipeline data, enriches it with doc detection, and writes through the canonical writer; requires `brief_path` from AN's `SKF_ANALYZE_RESULT_JSON`] |
 | **Gates** | step 1: Input Gate [use args] (`references/headless-args.md`) | step 1 ratify: Choice Gate [R] | step 2: Choice Gate [P] (a truncated GitHub tree), and the workspace of a monorepo [the repo root, or the workspace an `include` glob names] | step 3: Choice Gate [the `scope_type` argument, else the recommendation] | step 3: Input Gate [the `include` and `exclude` arguments, else the scope type's boundary default; a `reference-app` scope, or a `specific-modules` `scope_type` argument naming no module, halts] | step 3: Confirm Gate [C] | step 4: Confirm Gate [C] | step 5: Overwrite Gate [Y/N] (the brief exists; headless halts `overwrite-cancelled` unless `force` was supplied) |
 | **Outputs** | `skill-brief.yaml` at `{forge_data_folder}/{skill-name}/skill-brief.yaml`; one `SKF_BRIEF_RESULT_JSON` line on stdout at the end of a successful run when `{headless_mode}` is true or the run is in `[auto]` mode (see Result Contract below); for the run itself, a scratch folder under `{project-root}/_bmad-output/.skf-run/` holding what it hands its helpers (the repository's file list, fetched files, JSON payloads), which the run deletes once the brief is written or the user cancels (any other halt leaves it in place, less a clone of the repository) |
-| **Headless** | All gates auto-resolve with heuristic-driven or default action when `{headless_mode}` is true; step 1's input gate (`references/headless-args.md`) validates the pre-supplied inputs before any stage uses them, and the gates that would otherwise prompt consume them; absent `source_authority` and `scope_type` are resolved by signal-driven detection (see `references/headless-args.md`); with no `include`, step 3 takes the scope type's boundary default and names it in the envelope's `warnings` (a `specific-modules` recommendation that only the module count made becomes `full-library`), while a `reference-app` scope, or a `specific-modules` `scope_type` argument whose `intent` and `scope_hint` name no module, halts with `input-missing`; existing briefs are preserved unless `--force` was supplied (HALT with `overwrite-cancelled` otherwise); supplying `from_brief <path>` instead routes step 1 to the ratify path described in the `from_brief` Inputs cell (schema-validate, skip analyze/scope, write to the forge path: no `force` needed when the brief already lives at that path; otherwise `force` applies as on the derive route) rather than deriving a new brief |
-| **Transient-failure retry** | This workflow does **not** auto-retry network or subprocess failures. A failed call the run can go on without (a doc URL that does not answer, a failed doc detection or QMD step, an extraction script that falls back to the prompt path) is logged, added to the run's warnings and reported in the result envelope's `warnings`, and the workflow continues with whatever signal it has; a failure it cannot go on without, such as step 2 unable to read the target, is a HARD HALT. Headless pipelines that want retry semantics should wrap the invocation at their orchestrator level (e.g. CI re-runner on non-zero exit). Rationale: brief-skill is read-mostly with one terminal write (the YAML at step 5); a partial-signal retry has more failure modes than just re-running the whole workflow, which is cheap. |
+| **Headless** | All gates auto-resolve with heuristic-driven or default action when `{headless_mode}` is true; step 1's input gate (`references/headless-args.md`) validates the pre-supplied inputs before any stage uses them, and the gates that would otherwise prompt consume them; absent `source_authority` and `scope_type` are resolved by signal-driven detection (see `references/headless-args.md`); with no `include`, step 3 takes the scope type's boundary default and names it in the envelope's `warnings` (a `specific-modules` recommendation that only the module count made becomes `full-library`), while a `reference-app` scope, or a `specific-modules` `scope_type` argument whose `intent` and `scope_hint` name no module, halts with `input-missing`; existing briefs are preserved unless `--force` was supplied (HALT with `overwrite-cancelled` otherwise); supplying `from_brief <path>` instead routes step 1 to the ratify path described in the `from_brief` Inputs cell (schema-validate, skip analyze/scope, write to the forge path: no `force` needed when the brief already lives at that path; otherwise `force` applies as on the derive route) rather than deriving a new brief. A caller reads the run's own `SKF_BRIEF_RESULT_JSON` line. A run that printed no envelope line has no result to read, whatever the process exit code: it was cut off, or could not write its result. |
+| **Transient-failure retry** | This workflow does **not** auto-retry network or subprocess failures. A failed call the run can go on without (a doc URL that does not answer, a failed doc detection or QMD step, an extraction script that falls back to the prompt path) is logged, added to the run's warnings and reported in the result envelope's `warnings`, and the workflow continues with whatever signal it has; a failure it cannot go on without, such as step 2 unable to read the target, is a HARD HALT. Headless pipelines that want retry semantics should wrap the invocation at their orchestrator level (e.g. a CI re-runner on an error envelope, or on a run that printed none). Rationale: brief-skill is read-mostly with one terminal write (the YAML at step 5); a partial-signal retry has more failure modes than just re-running the whole workflow, which is cheap. |
 | **Exit codes** | See "Exit Codes" below |
 
 ## Exit Codes

package/src/skf-campaign/SKILL.md

@@ -73,6 +73,7 @@ These rules apply to every step in this workflow:
 - Validate `_campaign-state.yaml` on every load by running `uv run scripts/campaign-validate-state.py --state-file {stateFile}` and HALT (exit code 3, `invalid-state`) on non-zero; never hand-validate the schema
 - Zero memory dependency: campaign state is 100% recoverable from disk; never rely on conversation context for progress tracking
 - A sub-skill's result is what the step that runs it reads (an `SKF_*_RESULT_JSON` envelope or a verdict): a missing, unparseable or error result is a sub-skill failure, and never write partial state from an unparsed envelope
+- Run every subagent in the foreground (parallel ones as several calls in one message, never with `run_in_background`) and wait for every long-running command to exit before the next instruction; in a headless run, never end a turn while either still runs, since under `claude -p` a run stops when its turn ends.
 - Log every operator decision, headless default and event (skip/force, overwrite, export cancel/proceed, `.bak` recovery, user-cancel, a failed skill) as one typed entry in the append-only `{campaignWorkspacePath}/_campaign-decision-log.md` through `campaign-state.py log` (`references/campaign-contracts.md`), so rationale survives compaction and resume
 - **Universal cancel affordance:** at any interactive gate between Setup and the Export gate, `cancel`/`exit`/`:q` triggers a HARD HALT with **exit code 12 (`user-cancelled`)**: log it and leave state intact and resumable. Exception: the Export gate's own `[C]ancel` stays exit code 11 (`export-cancelled`); never also emit 12 there, so an automator's exit-code branch stays deterministic.
 - Always communicate in `{communication_language}`