bmad-module-skill-forge 5.0.0 → 7.0.0

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
@@ -441,7 +455,8 @@ Subcommands:
          "source": "<source_file>:<source_line>" | "<source_file>" | null,
          "defined_at": "<path>:<line>" | null,
          "declared_in": ["<path>:<line>", ...] | null,
-         "reason": "not-defined" | "defined" | "unchecked" | "no-entry",
+         "reason": "not-defined" | "aliased" | "defined" | "unchecked"
+                   | "no-entry",
          "entries": [{"source_file": "<as recorded>",
                       "source_line": <as recorded>,
                       "line_check": "checked" | "file-missing"
@@ -455,9 +470,30 @@ Subcommands:
     `fabricated` is true, with reason `not-defined`, when the name has an
     entry and every entry's `line_check` is `file-missing`, or `checked`
     with an empty `definition_lines`: the export is in neither the surface
-    nor the cited file. Otherwise the reason is `defined` (a cited file
-    defines the name), `unchecked` (no rule could check a cited file, and
-    none defines it) or `no-entry` (the map has no entry for the name).
+    nor the cited file, and no item of an export list or of a Python
+    `from X import` clause elsewhere renames to it a name that file
+    declares. Such an alias (`export { API_Entry as Entry }` or
+    `export type { ... }`, on one line or an item of a multi-line list;
+    `from X import L as NAME`, on one line or an item in parentheses or
+    after a backslash) gives the reason `aliased` and `fabricated` false:
+    the first of the name's declarations the lookup below finds (its
+    `declared_in`, else the cited file's) that is such an item
+    `L as NAME`, where a file of a `checked` entry of the name declares
+    `L` by the same rule (no module or package so named counting), is its
+    `defined_at`. A TS/JS line is read with its comments removed and its
+    one-line strings blanked, a Python line with its `#` comment cut.
+    Neither the rename's `from` module nor `L`'s own binding is resolved,
+    so an `L` that another file declares under the same name counts too.
+    Any other rename stays fabricated: `export { default as NAME }`,
+    `const NAME = L`, `type NAME = L`, an import then an export of NAME,
+    Python `NAME = L`, a TS type assertion (`x as NAME`) and `as NAME` in
+    a comment or a string; and so does a name whose cited file is the
+    module so named and itself the export (a column-0 `export default` or
+    `module.exports =`), which settles it at its line 1, so no walk looks
+    for an alias elsewhere.
+    Otherwise the reason is `defined` (a cited file defines the name),
+    `unchecked` (no rule could check a cited file, and none defines it) or
+    `no-entry` (the map has no entry for the name).
     An entry with no `source_file` (update-skill writes one for an
     `unknown` NEW_EXPORT) cites no file to check: its `line_check` is
     `no-file`, which, like a skipped or unreadable check, neither proves
@@ -469,7 +505,8 @@ Subcommands:
     `defined_at` is where the source declares a name that is not
     fabricated, so test-skill can tell a documented extra (a name outside
     the surface that the source still declares) from stale documentation;
-    a fabricated name is not looked up (null). A declaration is a line at
+    a fabricated name has none and no `declared_in` (both null), the
+    lookup reading it only for an alias. A declaration is a line at
     column 0 that the definition-line rules match with imports left out:
     a `def`, `class`, assignment, annotation, type alias, TS/JS
     declaration, `exports.NAME =`, or an alias that renames
@@ -484,9 +521,12 @@ Subcommands:
     `const NAME = require(...)`, `const { NAME } = require(...)`,
     `exports.NAME = require(...)`, `{ NAME: require(...) }`), an
     indented line and any line of a Python
-    file that does not tokenize never count. A module or package named
-    NAME (`NAME.py`, `NAME/__init__.py`, a TS/JS `NAME.<ext>` or
-    `NAME/index.<ext>`) declares NAME too: at its line 1 when no line of it
+    file that does not tokenize never count (an item of a multi-line list
+    counts at its own line, the list's opening line at column 0, so an
+    `aliased` name's `defined_at` is its rename's line). A module or
+    package named NAME (`NAME.py`, `NAME/__init__.py`, a TS/JS
+    `NAME.<ext>` or `NAME/index.<ext>`) declares NAME too: at its line 1
+    when no line of it
     declares NAME, unless `--inventory` gives NAME a `function`, `hook`,
     `class`, `interface`, `enum` or `type` kind (any of its kinds, when it
     gives several; a `method` kind is not read), no entry of NAME is a
@@ -510,10 +550,12 @@ Subcommands:
     and `defined_at` is the one item when the list has exactly one and no
     walked Python file that does not tokenize holds the name (a homonym,
     two files or more, gives null: test-skill decides it by the files the
-    skill cites). The walk reads, sorted by path, every file below the
-    walk root: the deepest folder that the files of the map's entries
-    share, widened to its package root (Python: the nearest folder at or
-    above it that holds `__init__.py`, then up while the parent holds
+    skill cites), save for an `aliased` name, whose `defined_at` is its
+    alias whatever the list holds. The walk reads, sorted by path, every
+    file below the walk root: the deepest folder that the files of the
+    map's entries share, widened to its package root (Python: the nearest
+    folder at or above it that holds `__init__.py`, then up while the
+    parent holds
     one, never the source root itself; TS/JS: the nearest folder at or
     above it that holds `package.json`), leaving out the entries whose
     file lies outside every package; the source root when none lies in
@@ -537,9 +579,12 @@ Subcommands:
     skips, those walk-only ones aside. The path is relative to the source
     root. A dotted name, or a map whose entries cite files
     but no Python or TS/JS one, is not looked up (`defined_at` and
-    `declared_in` null, as for a fabricated name), and a filesystem error
-    during the lookup gives every name null in both (the exit code stays
-    0).
+    `declared_in` null, as for a fabricated name). A filesystem error
+    during the lookup of the names that are not fabricated gives each of
+    them null in both (the exit code stays 0). The `not-defined` names are
+    looked up apart, after the others and whether or not that lookup
+    failed: an error in their walk or their alias check keeps only them
+    fabricated, and clears no other name's answer.
 
   kind-at --file <path> --line <n> --recipes <recipes>
           [--language <lang>] [--name <export_name>]
@@ -1046,6 +1091,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 +2202,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 +2326,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 +2338,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 +2363,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
@@ -2275,6 +2391,8 @@ STALE_NOT_DEFINED = "not-defined"
 STALE_DEFINED = "defined"
 STALE_UNCHECKED = "unchecked"
 STALE_NO_ENTRY = "no-entry"
+# a not-defined name a declaration renames to it from a name a cited file declares
+STALE_ALIASED = "aliased"
 
 
 def stale_names(data: object) -> list[str]:
@@ -2307,7 +2425,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 +2442,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
@@ -2656,6 +2778,68 @@ def baseline_gaps(
     return gaps, unchecked
 
 
+# A one-line TS/JS string literal, blanked before an export list is read.
+_JS_STRING_RE = re.compile(r"'(?:[^'\\]|\\.)*'|\"(?:[^\"\\]|\\.)*\"|`(?:[^`\\]|\\.)*`")
+_JS_IDENT_RE = re.compile(r"[A-Za-z_$][\w$]*")
+
+
+def _renamed_locals(lines: list[str], index: int, name: str, family: str) -> list[str]:
+    """The names line `index` (from 0) of a file renames to `name` as an item
+    of an export list (`export { L as NAME }` or `export type { ... }`, on
+    one line or an item of a multi-line list) or of a Python
+    `from X import` clause (on one line, or an item of one in parentheses
+    or continued with a backslash): each `L` an identifier other than
+    `name`, and in TS/JS other than `default` (`export { default as NAME }`
+    renames the default export, no declared name). A TS/JS line is read
+    with its `//` and `/* */` comments removed and each one-line string
+    blanked, a Python line with its `#` comment cut (a `from X import`
+    clause holds no string). The list opens at the nearest column-0
+    `export {` (`from X import`) at or above the line, and must not close
+    above it. Empty for any other line: `as NAME` in a comment or a string,
+    a TS type assertion (`const NAME = x as NAME`), `import { L as NAME }`
+    and Python's `import M as NAME` rename nothing here. Neither the `from`
+    module nor the binding of `L` is resolved: the caller takes `L` as
+    the name a cited file declares."""
+    if not 0 <= index < len(lines) or not re.search(
+        rf"(?<![\w$])as\s+{re.escape(name)}(?![\w$])", lines[index]
+    ):
+        return []
+    python = family == "python"
+    if python:
+        code = [line.split("#", 1)[0] for line in lines[: index + 1]]
+        opener, close, item_re = _PY_FROM_IMPORT_RE, ")", _PY_IMPORT_ITEM_RE
+    else:
+        code = [_JS_STRING_RE.sub('""', line) for line in _js_code_lines(lines[: index + 1])]
+        opener, close, item_re = _JS_EXPORT_LIST_RE, "}", _JS_EXPORT_ITEM_RE
+    for start in range(index, -1, -1):
+        opened = opener.match(code[start]) if _is_column_0(code[start]) else None
+        if opened is not None:
+            break
+        if start < index and close in code[start]:
+            return []  # a list that closes above the line holds it not
+    else:
+        return []
+    head = opened.group(1)
+    if start < index:
+        # an item of a list the opening line leaves open: in parentheses, or
+        # a Python clause each of whose lines above ends with a backslash
+        continued = all(line.rstrip().endswith("\\") for line in code[start:index])
+        if close in head or (python and not head.lstrip().startswith("(") and not continued):
+            return []
+        head = code[index]
+    locals_: list[str] = []
+    for item in head.split(close, 1)[0].replace("(", " ").replace("\\", " ").split(","):
+        found = item_re.match(item.strip())
+        if found is None or found.group(2) != name:
+            continue
+        local = found.group(1)
+        if local == name or (not python and local == "default"):
+            continue
+        if (_PY_IDENT_RE if python else _JS_IDENT_RE).fullmatch(local):
+            locals_.append(local)
+    return locals_
+
+
 class _DeclarationLookup:
     """Where the source declares the stale names (classify-stale's
     `defined_at`): a column-0 declaration, an alias that renames included, a
@@ -2677,7 +2861,10 @@ class _DeclarationLookup:
     on its path and the same skips but the walk-only ones, judged below the
     walk root when it lies there. The walk runs once for all the names no
     cited file settles: each file is read once, and only a file whose text
-    holds a name goes through the rules. Any error of the filesystem raises
+    holds a name goes through the rules. `renamed` then tells which of a
+    name's declarations is an alias of a name a cited file declares (an
+    item of an export list or of a Python `from X import` clause), from
+    the lines the lookup read. Any error of the filesystem raises
     (`_LOOKUP_ERRORS`)."""
 
     def __init__(self, entries: list[dict], source_root: Path) -> None:
@@ -2697,6 +2884,9 @@ class _DeclarationLookup:
         # the cited files read, kept for the walk: a few files at most
         self._cited: dict[tuple[str, ...], list[str] | None] = {}
         self._cited_cache = _SourceCache()
+        # during the suspects' pass only (`keep_declaring`): the lines of each
+        # file a declaration was found in, by path, which `renamed` reads
+        self._declaring: dict[str, list[str]] | None = None
 
     # -- the walk root ------------------------------------------------------
 
@@ -2832,8 +3022,8 @@ class _DeclarationLookup:
                     found.append((*below, filename))
         return sorted(found)
 
-    @staticmethod
     def _first(
+        self,
         parts: tuple[str, ...],
         lines: list[str],
         name: str,
@@ -2842,11 +3032,16 @@ class _DeclarationLookup:
     ) -> str | None:
         """`file:line` of the first line of a file that declares `name`, else,
         with `module_fallback`, its line 1 when it is the module or package
-        so named (`declared_line`)."""
+        so named (`declared_line`). After `keep_declaring`, the file's lines
+        are kept for `renamed`."""
         line = declared_line(
             parts, name, lines=lines, cache=cache, module_fallback=module_fallback
         )
-        return f"{'/'.join(parts)}:{line}" if line is not None else None
+        if line is None:
+            return None
+        if self._declaring is not None:
+            self._declaring['/'.join(parts)] = lines
+        return f"{'/'.join(parts)}:{line}"
 
     # -- the answer ---------------------------------------------------------
 
@@ -2929,6 +3124,36 @@ class _DeclarationLookup:
                     hits[name].append(hit)
         return {name: sorted(_without_stubs(h)) for name, h in hits.items()}, unsure
 
+    def keep_declaring(self) -> None:
+        """From now on, keep the lines of each file a declaration is found in,
+        for `renamed`: the suspects' pass, which comes last."""
+        self._declaring = {}
+
+    def renamed(self, name: str, hits: list[str], files: list[str]) -> str | None:
+        """The first of `hits` (`file:line` declarations of `name` the lookup
+        found, sorted) whose line renames to `name`, as an item of an export
+        list or of a Python `from X import` clause (`_renamed_locals`), a
+        name `L` one of `files` (source_file values, as recorded) declares:
+        `declared_line` gives `L` a line of that file, no module or package
+        so named counting. The lines are the ones the lookup read after
+        `keep_declaring` (`_first`), never read again. None when no hit is
+        such an alias."""
+        cited = list(dict.fromkeys(filter(None, map(_cited_parts, files))))
+        for hit in sorted(hits):
+            file, _, number = hit.rpartition(":")
+            lines, family = (self._declaring or {}).get(file), _rule_family(file)
+            if lines is None or family is None or not number.isdigit():
+                continue
+            for local in _renamed_locals(lines, int(number) - 1, name, family):
+                for parts in cited:
+                    source = self._cited_lines(parts)
+                    if source is not None and declared_line(
+                        parts, local, lines=source, cache=self._cited_cache,
+                        module_fallback=False,
+                    ) is not None:
+                        return hit
+        return None
+
 
 def inventory_kinds(data: object, path: str) -> dict[str, frozenset[str]]:
     """name -> the kinds a documented inventory gives it (`--inventory`):
@@ -2965,18 +3190,26 @@ def classify_stale(
     """The fabricated-signature test for each stale name: the definition-lines
     rules at every provenance entry whose raw `export_name` is the name, and
     for a name that is not fabricated, where the source declares it
-    (`defined_at`, and `declared_in` when the walk looked for it). The
-    classify-stale section of the module docstring gives each reason, what
-    a `no-file` entry means, which entry gives `source` and how
-    `defined_at` and `declared_in` are found. `kinds` (`inventory_kinds`,
-    None without `--inventory`) keeps a name of a `NO_MODULE_KINDS` kind
-    from a module or package so named, unless an entry of the name is a
-    `module` or `package` one.
+    (`defined_at`, and `declared_in` when the walk looked for it). A name
+    the cited files do not define is looked up too, after the others and
+    in a lookup of its own (an error there keeps it fabricated and clears
+    no other name), with no module or package so named counting unless it
+    is the export, and is `aliased`, not fabricated, when one of its
+    declarations is an export-list or `from X import` item renaming to it
+    a name a `checked` entry's file declares (`_DeclarationLookup.renamed`);
+    any other such name keeps both null. The classify-stale section of the
+    module docstring gives each reason, what a `no-file` entry means, which
+    entry gives `source` and how `defined_at` and `declared_in` are found.
+    `kinds` (`inventory_kinds`, None without `--inventory`) keeps a name of
+    a `NO_MODULE_KINDS` kind from a module or package so named, unless an
+    entry of the name is a `module` or `package` one.
     """
     entries = [e for e in prov.get("entries") or [] if isinstance(e, dict)]
     results: list[dict] = []
-    # the names to look up (never a fabricated one): name -> its cited files
+    # the names to look up that are not fabricated: name -> its cited files
     cited: dict[str, list[str]] = {}
+    # the not-defined names an alias may clear: name -> its checked entries' files
+    suspects: dict[str, list[str]] = {}
     # the names a module so named does not declare
     strict: set[str] = set()
     for name in names:
@@ -3008,7 +3241,12 @@ def classify_stale(
             reason = STALE_UNCHECKED
         source = next(filter(None, map(_entry_citation, mine)), None)
         fabricated = reason == STALE_NOT_DEFINED
-        if not fabricated:
+        if fabricated:
+            # a missing file declares nothing an alias could rename
+            checked = [c["source_file"] for c in checks if c["line_check"] == "checked"]
+            if checked:
+                suspects[name] = checked
+        else:
             cited[name] = [f for f in map(_entry_file, mine) if f is not None]
             documented = (kinds or {}).get(name, frozenset())
             if documented & NO_MODULE_KINDS and not any(map(_module_entry, mine)):
@@ -3024,16 +3262,43 @@ def classify_stale(
                 "entries": checks,
             }
         )
+    lookup: _DeclarationLookup | None = None
     try:
-        found, declared = _DeclarationLookup(entries, source_root).find(
-            cited, frozenset(strict)
-        )
+        lookup = _DeclarationLookup(entries, source_root)
+        found, declared = lookup.find(cited, frozenset(strict))
     except _LOOKUP_ERRORS:
         # a lookup that fails proves nothing: every name stays null
         found, declared = {}, {}
+    # the suspects' own lookup, after: an error there clears no name settled
+    # above, and keeps every suspect fabricated
+    aliased: dict[str, str] = {}
+    suspect_declared: dict[str, list[str]] = {}
+    if suspects and lookup is not None:
+        try:
+            # a suspect is strict: a cited module so named settles it before
+            # the walk only when it is the export
+            lookup.keep_declaring()
+            suspect_found, suspect_declared = lookup.find(suspects, frozenset(suspects))
+            for name, files in suspects.items():
+                hits = suspect_declared[name] if name in suspect_declared else (
+                    [suspect_found[name]] if name in suspect_found else []
+                )
+                hit = lookup.renamed(name, hits, files)
+                if hit is not None:
+                    aliased[name] = hit
+        except _LOOKUP_ERRORS:
+            aliased, suspect_declared = {}, {}
     for item in results:
-        item["defined_at"] = found.get(item["name"])
-        item["declared_in"] = declared.get(item["name"])
+        name = item["name"]
+        if name in suspects:
+            if name in aliased:
+                item.update(
+                    fabricated=False, reason=STALE_ALIASED,
+                    defined_at=aliased[name], declared_in=suspect_declared.get(name),
+                )
+            continue  # any other suspect stays fabricated, both null
+        item["defined_at"] = found.get(name)
+        item["declared_in"] = declared.get(name)
     return results
 
 
@@ -3677,6 +3942,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 +3983,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 +3998,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 +4043,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/customize.toml

@@ -59,8 +59,9 @@ analysis_report_template_path = "templates/analysis-report-template.md"
 # written the result files, at the end of every run that writes them
 # (generate-briefs.md, step-auto-scope.md and auto-docs-only.md), as:
 #   <on_complete> --result-path=<forge_data_folder>/analyze-source-result-latest.json
-# A run whose result file could not be written (result_path null in the
-# envelope) and a HALT call no hook. Useful for Slack notifications,
+# A HALT calls no hook, nor does a run whose result file or its -latest
+# copy could not be written (result_path null, or a result_file_write_failed
+# warning naming the copy, in the envelope). Useful for Slack notifications,
 # dashboard ingest, CI hooks, or chaining into a brief linter. A hook
 # failure is displayed and never fails the run.
 #

package/src/skf-analyze-source/references/auto-docs-only.md

@@ -145,9 +145,9 @@ Add `"coexistence": "alongside"` when `{coexistence_suffix}` is non-empty ([A]lo
 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, and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout. When `{headless_mode}` is true, display the line verbatim. 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 `auto-docs-only:5`, path `{forge_data_folder}`): "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, and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout. When `{headless_mode}` is true, display the line verbatim. A per-run record that could not be written leaves `result_path` null, and a `-latest` copy that could not be written leaves it set; either adds a `result_file_write_failed` warning to 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, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `auto-docs-only:5`, path `{forge_data_folder}`): "The result contract could not be written: {its message}."
 
-If `{onCompleteCommand}` is non-empty and the line's `result_path` is not null, invoke it now: `{onCompleteCommand} --result-path={forge_data_folder}/analyze-source-result-latest.json`. Display a hook failure; it never fails the run.
+If `{onCompleteCommand}` is non-empty, the line's `result_path` is not null and its `warnings` hold no `result_file_write_failed` entry naming `analyze-source-result-latest.json`, invoke it now: `{onCompleteCommand} --result-path={forge_data_folder}/analyze-source-result-latest.json`. Display a hook failure; it never fails the run. When `{onCompleteCommand}` is non-empty but `result_path` is null or a `result_file_write_failed` warning names `analyze-source-result-latest.json` (the copy alone failed), skip the hook and say so: "on_complete skipped: `analyze-source-result-latest.json` was not written."
 
 ### 6. Chain to health check