bmad-module-skill-forge 3.0.0 → 4.0.0

package/src/skf-test-skill/scripts/reconcile-coverage.py

@@ -19,7 +19,7 @@ It covers the four branches §2c enumerates:
     Missing = barrel_set − documented_set, Stale = documented_set − barrel_set,
     Export Coverage = |Documented| / |barrel_set| * 100.
 
-  * "scalar"  (§2b priority-1 effective_denominator, no enumerated name set):
+  * "scalar"  (§2b's scalar branch, stats.effective_denominator, no enumerated name set):
     look each documented name up in SKILL.md ∪ references/*.md;
     Documented = count present, denominator = effective_denominator,
     Missing = max(0, denominator − Documented), Stale not enumerable (empty),
@@ -98,6 +98,7 @@ Output (stdout, one object):
     "denominatorSource": "barrel" | "scalar" | "stack" | "docsOnly",
     "denominator": <int>,
     "documented": <int>,
+    "documentedNames": [names],  # enumerated only: the documented names the denominator counts
     "missing": [names],          # enumerated: source names not documented; others: []
     "missingCount": <int>,       # always present; never negative
     "stale": [names],            # enumerated: documented names not in source; others: []
@@ -115,6 +116,43 @@ Exit codes:
   0  reconciliation emitted successfully
   1  no input, input that does not parse as JSON, or an input file that cannot be read
   2  input parsed but schema/semantics invalid (error object emitted as JSON)
+
+Subcommand render (coverage-check.md §5 writes its output unchanged):
+  uv run reconcile-coverage.py render --coverage <coverage.json>
+      [--surface <surface.json>] [--signatures <signatures.json>]
+
+prints the Markdown of the Coverage Analysis section that follows its
+header lines, from the run files:
+  **Files Analyzed:**  the distinct files the --surface export records name
+                       (N/A without --surface: a docs-only run has none)
+  ### Export Coverage  on the enumerated branch, one row per name the
+                       denominator counts, per stale name and per name whose
+                       signature mismatches, by name:
+      Type             the first kind the surface records for the name, else -
+      Documented       no for a missing name, else yes
+      Signature        no for a mismatch, yes for a compared name that
+                       matches, unverified for a documented name when no
+                       --signatures was given, - otherwise
+      Source Location  the file:line the surface records for the name, a
+                       record with a line preferred (gap-ledger.py's rule
+                       for a missing export's Source), else -
+      Status           FAIL for a signature mismatch, WARN for a missing or
+                       stale name, PASS otherwise
+                       The scalar and stack branches count without naming
+                       the exports, and a docs-only run has no source
+                       surface: one line says so instead (NO_TABLE).
+  ### Coverage Summary the --coverage counts, the --signatures mismatch count
+                       and warnings, the numerator surplus when the ratio
+                       was capped, and the names the --surface leaves out
+                       or puts back: `excluded.outsideScope` (scoped out
+                       by the brief), `excluded.nestedEntries` (a nested
+                       Python entry point's names) and
+                       `guards.staleScope.restored`, each line only when
+                       it names one
+  ### Category Scores  Export Coverage, and Signature Accuracy and Type
+                       Coverage from --signatures (N/A without it)
+Exit 0 when it printed; 1 when an input cannot be read or is not the
+result of the script that writes it (one line on stderr); 2 a usage error.
 """
 
 from __future__ import annotations
@@ -286,6 +324,7 @@ def reconcile(inp, doc_text=None):
             "denominatorSource": source,
             "denominator": denominator,
             "documented": documented,
+            "documentedNames": sorted(documented_names),
             "missing": missing,
             "missingCount": len(missing),
             "stale": stale,
@@ -350,6 +389,235 @@ def reconcile(inp, doc_text=None):
     return result
 
 
+# --- The Coverage Analysis section (render) -----------------------------------
+
+BRANCHES = ("enumerated", "scalar", "stack", "docsOnly")
+# Why a branch names no export: the line it writes in place of the table, and its stale count.
+NO_NAMES = {
+    "scalar": "the scalar denominator (`stats.effective_denominator`) counts the exports without naming them",
+    "stack": "the stack denominator counts the composition surface without naming each export",
+    "docsOnly": "a docs-only run has no source surface",
+}
+NO_TABLE = {
+    "scalar": f"No per-export table: {NO_NAMES['scalar']}. The summary below gives the counts.",
+    "stack": f"No per-export table: {NO_NAMES['stack']}. The summary below gives the counts.",
+    "docsOnly": f"No per-export table: {NO_NAMES['docsOnly']} to compare against. The summary below gives its "
+                "documentation completeness.",
+}
+
+_GAP_LEDGER_MODULE = None
+
+
+class RenderError(Exception):
+    """A render input that is not the result of the script that writes it."""
+
+
+def _gap_ledger():
+    """gap-ledger.py beside this script: its rule for a missing export's Source gives the Source Location."""
+    global _GAP_LEDGER_MODULE
+    if _GAP_LEDGER_MODULE is None:
+        sibling = Path(__file__).resolve().parent / "gap-ledger.py"
+        spec = importlib.util.spec_from_file_location("skf_gap_ledger_render", sibling)
+        if spec is None or spec.loader is None or not sibling.is_file():
+            raise RenderError(f"gap-ledger.py not found beside {Path(__file__).name}")
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        _GAP_LEDGER_MODULE = module
+    return _GAP_LEDGER_MODULE
+
+
+def _pct(value):
+    """A score as the report writes it.
+
+    >>> _pct(60.0), _pct(66.67), _pct(None)
+    ('60%', '66.67%', 'N/A')
+    """
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return "N/A"
+    return f"{int(value)}%" if float(value).is_integer() else f"{value}%"
+
+
+def _cell(text):
+    """A table cell: a `|` would end it."""
+    return str(text).replace("|", "\\|")
+
+
+def _string_list(data, key, label):
+    value = data.get(key)
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        raise RenderError(f"{label}: `{key}` is not a list")
+    return [v for v in value if isinstance(v, str) and v]
+
+
+def _incomplete(item):
+    """A docs-only item and the fields it lacks.
+
+    >>> _incomplete({"name": "load", "kind": "function", "missing": ["params", "return_type"]})
+    '`load` (function) lacks `params`, `return_type`'
+    """
+    fields = ", ".join(f"`{field}`" for field in item.get("missing") or [])
+    return f"`{item.get('name')}` ({item.get('kind')}) lacks {fields}"
+
+
+def _left_out(surface):
+    """The Coverage Summary lines for the names the surface leaves out or puts back, each only when it names one.
+
+    >>> for line in _left_out({
+    ...         "excluded": {"outsideScope": [{"name": "gen", "file": "src/gen.ts"}],
+    ...                      "nestedEntries": [{"entry": "pkg/api/__init__.py", "within": "pkg/__init__.py",
+    ...                                         "names": ["router"]}]},
+    ...         "guards": {"staleScope": {"restored": [{"name": "old", "file": "src/old.ts", "line": 4}]}}}):
+    ...     print(line)
+    - **Scoped Out by the Brief:** `gen` (src/gen.ts)
+    - **Nested Entry Points:** `pkg/api/__init__.py` inside `pkg/__init__.py`: `router`
+    - **Restored by the Stale-Scope Guard:** `old` (src/old.ts:4)
+    >>> _left_out({"excluded": {"outsideScope": [], "nestedEntries": []}, "guards": None})
+    []
+    """
+    def items(value):
+        return [i for i in value if isinstance(i, dict)] if isinstance(value, list) else []
+
+    def where(item):
+        file, line = item.get("file"), item.get("line")
+        if not isinstance(file, str) or not file:
+            return ""
+        return f" ({file}:{line})" if isinstance(line, int) and not isinstance(line, bool) else f" ({file})"
+
+    excluded = surface.get("excluded") if isinstance(surface.get("excluded"), dict) else {}
+    guards = surface.get("guards") if isinstance(surface.get("guards"), dict) else {}
+    stale_scope = guards.get("staleScope") if isinstance(guards.get("staleScope"), dict) else {}
+    lines = []
+    scoped = [f"`{i['name']}`{where(i)}" for i in items(excluded.get("outsideScope"))
+              if isinstance(i.get("name"), str)]
+    if scoped:
+        lines.append(f"- **Scoped Out by the Brief:** {', '.join(scoped)}")
+    nested = [f"`{i['entry']}` inside `{i.get('within')}`: "
+              + ", ".join(f"`{n}`" for n in i.get("names") or [] if isinstance(n, str))
+              for i in items(excluded.get("nestedEntries")) if isinstance(i.get("entry"), str)]
+    if nested:
+        lines.append(f"- **Nested Entry Points:** {'; '.join(nested)}")
+    restored = [f"`{i['name']}`{where(i)}" for i in items(stale_scope.get("restored"))
+                if isinstance(i.get("name"), str)]
+    if restored:
+        lines.append(f"- **Restored by the Stale-Scope Guard:** {', '.join(restored)}")
+    return lines
+
+
+def _rows(coverage, surface, signatures):
+    """The Export Coverage table of the enumerated branch."""
+    if "documentedNames" not in coverage:
+        raise RenderError("--coverage has no `documentedNames`: write it again with this reconcile-coverage.py")
+    documented = set(_string_list(coverage, "documentedNames", "--coverage"))
+    missing = set(_string_list(coverage, "missing", "--coverage"))
+    stale = set(_string_list(coverage, "stale", "--coverage"))
+    mismatched, compared = set(), set()
+    if signatures is not None:
+        mismatched = {m["name"] for m in signatures.get("mismatches") or []
+                      if isinstance(m, dict) and isinstance(m.get("name"), str)}
+        compared = set(_string_list(signatures, "comparedNames", "--signatures"))
+    kinds, sources = {}, {}
+    if surface is not None:
+        for record in surface["exports"]:
+            if isinstance(record, dict) and isinstance(record.get("name"), str) and record.get("kind"):
+                kinds.setdefault(record["name"], str(record["kind"]))
+        sources = _gap_ledger()._surface_sources(surface)
+    rows = ["| Export | Type | Documented | Signature | Source Location | Status |",
+            "|--------|------|------------|-----------|-----------------|--------|"]
+    for name in sorted(documented | missing | stale | mismatched):
+        if name in mismatched:
+            signature = "no"
+        elif name in compared:
+            signature = "yes"
+        elif signatures is None and name not in missing:
+            signature = "unverified"
+        else:
+            signature = "-"
+        status = "FAIL" if name in mismatched else "WARN" if name in missing or name in stale else "PASS"
+        rows.append(f"| `{_cell(name)}` | {_cell(kinds.get(name, '-'))} | {'no' if name in missing else 'yes'} "
+                    f"| {signature} | {_cell(sources.get(name, '-'))} | {status} |")
+    return rows
+
+
+def render(coverage, surface=None, signatures=None):
+    """The Coverage Analysis section after its header lines, as Markdown (see the module docstring)."""
+    if not isinstance(coverage, dict) or coverage.get("branch") not in BRANCHES:
+        raise RenderError("--coverage is not reconcile-coverage.py's result (no known `branch`)")
+    if surface is not None and not (isinstance(surface, dict) and isinstance(surface.get("exports"), list)):
+        raise RenderError("--surface is not load-coverage-inputs.py surface's result (no `exports` list)")
+    if signatures is not None and not (isinstance(signatures, dict) and signatures.get("valid") is True):
+        raise RenderError("--signatures is not score-signatures.py score's result (no `valid: true`)")
+    branch = coverage["branch"]
+    docs_only = branch == "docsOnly"
+
+    if surface is None:
+        files = "N/A: no source surface"
+    else:
+        files = len({r["file"] for r in surface["exports"]
+                     if isinstance(r, dict) and isinstance(r.get("file"), str) and r["file"]})
+    lines = [f"**Files Analyzed:** {files}", "", "### Export Coverage", ""]
+    lines += _rows(coverage, surface, signatures) if branch == "enumerated" else [NO_TABLE[branch]]
+
+    denominator, documented = coverage.get("denominator"), coverage.get("documented")
+    missing_count, coverage_pct = coverage.get("missingCount"), _pct(coverage.get("exportCoverage"))
+    lines += ["", "### Coverage Summary", ""]
+    if docs_only:
+        incomplete = [_incomplete(item) for item in coverage.get("incomplete") or [] if isinstance(item, dict)]
+        lines += [f"- **Exports Found:** {denominator} documented items",
+                  f"- **Documented:** {documented} complete ({coverage_pct})",
+                  f"- **Missing Documentation:** {missing_count} incomplete"
+                  + (f": {'; '.join(incomplete)}" if incomplete else "")]
+    else:
+        capped = coverage.get("coverageCapped")
+        floored = " (a floored residual: the numerator exceeds the denominator)" if capped else ""
+        lines += [f"- **Exports Found:** {denominator}",
+                  f"- **Documented:** {documented} ({coverage_pct})",
+                  f"- **Missing Documentation:** {missing_count}{floored}"]
+    mismatches = signatures.get("mismatches") if signatures is not None else None
+    lines.append(f"- **Signature Mismatches:** {len(mismatches) if isinstance(mismatches, list) else 'N/A'}")
+    if coverage.get("staleApplicable"):
+        lines.append(f"- **Stale Documentation:** {coverage.get('staleCount')}, documented extras included")
+    else:
+        lines.append(f"- **Stale Documentation:** N/A: {NO_NAMES.get(branch, 'the denominator names no stale export')}")
+    warnings = _string_list(signatures, "warnings", "--signatures") if signatures is not None else []
+    if warnings:
+        lines.append("- **Scoring Warnings:**")
+        lines += [f"  - {w}" for w in warnings]
+    if coverage.get("coverageCapped"):
+        lines.append(f"- **Numerator Surplus:** {coverage.get('numeratorSurplus')}, uncapped coverage "
+                     f"{_pct(coverage.get('coverageUncapped'))}")
+    if surface is not None:
+        lines += _left_out(surface)
+
+    scores = signatures or {}
+    lines += ["", "### Category Scores", "", "| Category | Score |", "|----------|-------|",
+              f"| Export Coverage | {coverage_pct} |",
+              f"| Signature Accuracy | {_pct(scores.get('signatureAccuracy'))} |",
+              f"| Type Coverage | {_pct(scores.get('typeCoverage'))} |"]
+    return "\n".join(lines) + "\n"
+
+
+def _render_main(argv):
+    parser = argparse.ArgumentParser(
+        prog="reconcile-coverage render",
+        description="Print the Coverage Analysis section's Markdown from the run files (coverage-check.md §5).",
+    )
+    parser.add_argument("--coverage", required=True, metavar="PATH", help="this script's result (coverage.json)")
+    parser.add_argument("--surface", metavar="PATH", help="load-coverage-inputs.py surface output (surface.json)")
+    parser.add_argument("--signatures", metavar="PATH", help="score-signatures.py score output (signatures.json)")
+    args = parser.parse_args(argv)
+    try:
+        text = render(_read_json_file(args.coverage, "--coverage"),
+                      _read_json_file(args.surface, "--surface") if args.surface else None,
+                      _read_json_file(args.signatures, "--signatures") if args.signatures else None)
+    except (InputFileError, RenderError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    sys.stdout.write(text)
+    return 0
+
+
 # --- Run-folder inputs --------------------------------------------------------
 
 
@@ -432,7 +700,10 @@ def _build_parser():
         epilog=(
             "Example (barrel branch):\n"
             "  uv run reconcile-coverage.py --denominator-source barrel "
-            "--inventory run/inventory.json --surface run/surface.json --output run/coverage.json"
+            "--inventory run/inventory.json --surface run/surface.json --output run/coverage.json\n"
+            "Render the Coverage Analysis section (see `render --help`):\n"
+            "  uv run reconcile-coverage.py render --coverage run/coverage.json "
+            "[--surface run/surface.json] [--signatures run/signatures.json]"
         ),
     )
     src = parser.add_mutually_exclusive_group()
@@ -492,6 +763,9 @@ def _write_output(path, result):
 
 
 def main(argv=None):
+    argv = sys.argv[1:] if argv is None else list(argv)
+    if argv[:1] == ["render"]:
+        return _render_main(argv[1:])
     parser = _build_parser()
     args = parser.parse_args(argv)
     raw = _resolve_input(args)

package/src/skf-test-skill/scripts/score-signatures.py

@@ -15,18 +15,21 @@ ratios and the gap records of the wrong signatures.
 
   plan   the comparisons to make. For each documented export with a
          signature (an inventory entry of any kind but `method` that carries
-         `params`, `return_type` or `usage_signature`) that the source
-         surface lists, grouped by source file, with the line that defines
-         it in the source and the documented signature. Also the whole
+         `params`, `return_type` or `usage_signature`) in the signature
+         universe, grouped by source file, with the line that defines it in
+         the source and the documented signature. The signature universe is
+         the surface's `all` set plus every name on its export records, so
+         the names of a Python sub-package load-coverage-inputs.py keeps out
+         of `all` (excluded.nestedEntries) keep their checks. Also the whole
          documented-signature map, for the fallback scan that has no surface
          lines yet.
   score  the categories. Reads every subagent result, checks its schema,
          and computes:
            Signature Accuracy = matching / compared * 100, where compared is
-             the documented signatures the whole surface lists (the `all`
-             set, with a fallback scan's exports_found) and matching those
-             no result names in signature_mismatches[]: a wrong signature is
-             wrong whichever set the denominator counts
+             the documented signatures of the signature universe (with a
+             fallback scan's exports_found) and matching those no result
+             names in signature_mismatches[]: a wrong signature is wrong
+             whichever set the denominator counts
            Type Coverage = documented types / total types * 100, where
              total types counts the names of the --surface-set set (the
              denominator set coverage-check section 2b picked) whose kind is
@@ -45,8 +48,9 @@ Inputs, all files in the run folder:
   --inventory  the validated inventory validate-inventory.py wrote (--output)
   --surface    load-coverage-inputs.py surface output: `exports[]` (name,
                kind, file, line, signatureLine) and the name `sets`;
-               --surface-set picks the set (default "all"): plan's
-               comparisons and score's Type Coverage
+               --surface-set picks the set (default "all") score's Type
+               Coverage counts, while plan and Signature Accuracy compare
+               the signature universe whichever set it picks
   --results    a subagent result, as the subagent returned it (a wrapping
                markdown fence is stripped), repeatable. One object, or a
                list of them:
@@ -67,7 +71,8 @@ Output (stdout; --output also writes it, --gaps-output writes the records):
   plan:  {"compared": N, "files": [{"file", "checks": [{"name", "line",
           "signatureLine", "documented": {...}}]}], "documentedSignatures": {...}}
   score: {"valid": true, "signatureAccuracy", "matchingSignatures",
-          "totalDocumented", "typeCoverage", "documentedTypes", "totalTypes",
+          "totalDocumented", "comparedNames": [the names compared],
+          "typeCoverage", "documentedTypes", "totalTypes",
           "missingTypes": [...], "mismatches": [...], "gapRecords": [...],
           "warnings": [...]}
          or {"valid": false, "violations": [...]} when a result breaks the schema
@@ -259,13 +264,23 @@ def _records_by_name(exports: list[dict]) -> dict[str, list[dict]]:
     return by_name
 
 
+def signature_universe(names: list[str], exports: list[dict]) -> set[str]:
+    """The names whose documented signature is compared: the `all` set
+    (`names`) plus every name on the surface's export records. A nested
+    Python top's names leave `all` but keep their records, so a documented
+    one still has its signature checked."""
+    return set(names) | set(_records_by_name(exports))
+
+
 def plan(inventory: list[dict], names: list[str] | None, exports: list[dict]) -> dict:
+    """The comparisons over the signature universe of `names` (the `all`
+    set) and `exports`; none without a surface (`names` None)."""
     signatures = documented_signatures(inventory)
     files: dict[str, list[dict]] = {}
     compared = 0
     if names is not None:
         by_name = _records_by_name(exports)
-        for name in sorted(set(names) & set(signatures)):
+        for name in sorted(signature_universe(names, exports) & set(signatures)):
             record = (by_name.get(name) or [{}])[0]
             compared += 1
             files.setdefault(str(record.get("file") or ""), []).append({
@@ -297,15 +312,17 @@ def _gap_record(m: dict) -> dict:
 
 def score(inventory: list[dict], names: list[str], exports: list[dict], results: list[dict],
           type_names: list[str] | None = None) -> dict:
-    """The two categories: Signature Accuracy over `names` (the whole surface),
-    Type Coverage over `type_names` when given, else over `names` too."""
+    """The two categories: Signature Accuracy over the signature universe of
+    `names` (the `all` set) and `exports`, Type Coverage over `type_names`
+    when given, else over `names`. A fallback scan's exports_found join the
+    universe, and `names` when no `type_names` is given."""
     by_name = _records_by_name(exports)
     # A fallback scan reports its own names and types.
     fallback_types = {n for r in results for n in r.get("types_found") or []}
     surface = set(names) | {n for r in results for n in r.get("exports_found") or []}
     documented = documented_names(inventory)
     signatures = documented_signatures(inventory)
-    compared = surface & set(signatures)
+    compared = (surface | signature_universe(names, exports)) & set(signatures)
     warnings = []
 
     mismatches = []
@@ -353,6 +370,7 @@ def score(inventory: list[dict], names: list[str], exports: list[dict], results:
         "signatureAccuracy": signature_accuracy,
         "matchingSignatures": len(compared) - len(wrong),
         "totalDocumented": len(compared),
+        "comparedNames": sorted(compared),
         "typeCoverage": type_coverage,
         "documentedTypes": len(documented_types),
         "totalTypes": len(types),
@@ -378,7 +396,7 @@ def _cmd_plan(args: argparse.Namespace) -> tuple[dict, int]:
     inventory = load_inventory(args.inventory)
     names, exports = (None, [])
     if args.surface is not None:
-        names, exports, _ = load_surface(args.surface, args.surface_set)
+        _, exports, names = load_surface(args.surface, args.surface_set)
     out = plan(inventory, names, exports)
     if args.output:
         _write_json(args.output, out)
@@ -412,7 +430,9 @@ def _build_parser() -> argparse.ArgumentParser:
     p = sub.add_parser("plan", help="the signature comparisons for the subagents to make")
     p.add_argument("--inventory", required=True, help="the validated inventory file")
     p.add_argument("--surface", help="load-coverage-inputs.py surface output")
-    p.add_argument("--surface-set", default="all", help="the surface name set (default: all)")
+    p.add_argument("--surface-set", default="all",
+                   help="a surface name set, which must exist (default: all); the plan compares the signature "
+                        "universe whichever set it names")
     p.add_argument("--output", help="also write the plan to this file")
     p.set_defaults(func=_cmd_plan)
 

package/src/skf-test-skill/scripts/verify-declared-numerator.py

@@ -8,11 +8,13 @@
 Lookup-and-count helper for the SKF test-skill workflow (coverage-check.md
 §2b, its "Numerator ground truth" paragraph; §4b records the gap). It fires
 only on the inflation signature
-(`stats.exports_documented == effective_denominator` exactly): the numerator
-equals the denominator, the tell of a documented count padded to force 100%
-coverage. On that signature the declared count is not trusted: every declared
-export name is looked up in the skill's documentation surface and only the
-names that actually appear count toward coverage.
+(`stats.exports_documented == effective_denominator` exactly, or, for a
+provenance map with no `::` entry, its distinct entry names number
+`effective_denominator`): the numerator equals the denominator, the tell of a
+documented count padded to force 100% coverage. On that signature the declared
+count is not trusted: every declared export name is looked up in the skill's
+documentation surface and only the names that actually appear count toward
+coverage.
 
 Distinct from reconcile-coverage.py (whose scalar/stack branches look up the §1
 inventory names and return only a residual missing *count*): this script looks

package/src/skf-update-skill/references/detect-changes.md

@@ -7,8 +7,8 @@ hashContentProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-hash-content.py'
   - '{project-root}/src/shared/scripts/skf-hash-content.py'
 # `{buildChangeManifestHelper}`: §3's `build` (and §1's for a docs-only
-# skill), §2.2's `deletion-ratio` and Category C's `rename-candidates`. HALT
-# if neither exists.
+# skill), §2.2's `deletion-ratio`, Category B's `baseline-gaps` and Category
+# C's `rename-candidates`. HALT if neither exists.
 buildChangeManifestProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-build-change-manifest.py'
   - '{project-root}/src/shared/scripts/skf-build-change-manifest.py'
@@ -17,13 +17,13 @@ buildChangeManifestProbeOrder:
 provenanceGapDispatchProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-provenance-gap-dispatch.py'
   - '{project-root}/src/shared/scripts/skf-provenance-gap-dispatch.py'
-# `{detectScriptsAssetsHelper}`: Category D's script and asset walk, as
-# create-skill's. HALT if neither exists.
+# `{detectScriptsAssetsHelper}`: Category D's script and asset walk, the
+# detector create-skill runs, over the whole source. HALT if neither exists.
 detectScriptsAssetsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-detect-scripts-assets.py'
   - '{project-root}/src/shared/scripts/skf-detect-scripts-assets.py'
-# `{newFileDiffHelper}`: Category D's NEW_FILE set difference, bundled with
-# this skill.
+# `{newFileDiffHelper}`: Category D's NEW_FILE set difference, kept to the
+# skill brief's scope, bundled with this skill.
 newFileDiffHelper: 'scripts/skf-new-file-diff.py'
 # `{resolveAuthoritativeFilesHelper}`: §1b's mirror. HALT if neither exists.
 resolveAuthoritativeFilesProbeOrder:
@@ -103,6 +103,8 @@ It writes `{"mode": "docs-only", "no_changes", "changed_urls", "fetch_failed", "
 
 **The brief this run reads.** Bind `{brief_path}` ← `{forge_data_folder}/{skill_name}/skill-brief.yaml`. When `detect_only_mode` or `dry_run_mode` is true and that file exists, copy it to `{run_dir}/skill-brief.yaml` and bind `{brief_path}` to the copy: §1b and §1c write each decision there, Category A reads the scope from there, and the brief itself stays as it was. Each amendment a read-only run writes to the copy is a proposed one: add `proposed-amendment: {action} {path} ({category}); not written: {--dry-run or --detect-only}` to `warnings[]` as you write it, and step 6 lists them with the change manifest.
 
+**The scope type this run reads.** Bind `{scope_type}` ← the `scope_type` metadata.json records (init.md §2), else the `scope.type` of `{brief_path}` when that file exists and names one: a skill whose metadata.json records no scope type updates under its brief's. Category B's runner takes it as `--scope-type` and writes it to `{run_dir}/extraction.json` as `scope.type`, where step 3's `records` and step 5's `apply` read it: under `public-api`, a normal-mode update neither documents nor adds to the provenance map a new export off the runner's public surface (re-extract.md §4, write.md §3).
+
 ### 1b. Discovered Authoritative Files Protocol (Mirror)
 
 **Purpose:** mirror `skf-create-skill` §2a into update-skill. `skf-create-skill` §2a catches authoritative AI documentation files (`llms.txt`, `AGENTS.md`, `.cursorrules`, etc.) during **creation**, but a project may add these files *after* the skill was created. Without this mirror, update-skill would either miss the new file entirely (if it doesn't match the provenance map's file patterns) or classify it as a generic ADDED file in §2 Category A with no authoritative-file treatment. The mirror surfaces the discovery with the same P/S/U prompt create-skill uses, honoring any prior amendments.
@@ -309,9 +311,22 @@ Pass `--provenance-map` whenever init.md §4 found one; `--brief` (as §1c left
        -o "{run_dir}/extraction.json"
    ```
 
-   Pass `--language` and `--scope-type` when metadata.json records them. It takes no `--brief`: Category A applied the scope, and a tracked file the brief's scope leaves out (gap-driven.md §1's rule R1 excludes a rescoped export's file) keeps its exports. `--head-cap 0` keeps every match, since a dropped one would read as a deleted export. Step 3 reads this file and never runs the runner again. **Exit 1** (`incomplete`): run it once more; when still incomplete, step 2 below reads by eye each listed file with no export in `exports[]`. **Exit 2 or 3, no JSON, no candidate resolves, or Quick tier:** write `{"exports": []}` to `{run_dir}/extraction.json`; step 2 reads every listed file by eye (at Quick tier, by text pattern). Tell the user which files were read by eye.
+   Pass `--language` when metadata.json records it, and `--scope-type` when §1 bound `{scope_type}`. It takes no `--brief`: Category A applied the scope, and a tracked file the brief's scope leaves out (gap-driven.md §1's rule R1 excludes a rescoped export's file) keeps its exports. `--head-cap 0` keeps every match, since a dropped one would read as a deleted export. Step 3 reads this file and never runs the runner again. **Exit 1** (`incomplete`, its JSON written): run it once more; when still incomplete, step 2 below reads by eye each listed file with no export in `exports[]` or that an `errors[]` item lists in `unread`, and tells the user which files were read by eye. **Exit 2** (an input error, such as a file list it cannot read, or a failure it did not foresee, named in one stderr line with no JSON; `uv` failing to start it exits 2 too): HALT with status `blocked` (halt procedure: `phase: "detect-changes:category-b"`, the stderr line that holds `error:` as `reason`). No by-eye read stands in for it: the skill is not written yet, and reading every file by eye would hide the error. **Exit 3 (`no-ast-grep`), no JSON on another exit, no candidate resolves, or Quick tier:** write `{"exports": []}` to `{run_dir}/extraction.json`, with `"scope": {"type": "{scope_type}"}` when §1 bound `{scope_type}`, so step 5's `apply` can warn that a `public-api` surface was not applied; step 2 reads every listed file by eye (at Quick tier, by text pattern). Tell the user which files were read by eye.
+
+   Then, at every tier (in degraded mode there is no map: skip it), list the map's entries the runner left out that their file still declares: the runner never reports a module, an alias that renames, a dunder such as `__version__` or another underscore name, and step 3's diff would read each as a deleted export. From `{project-root}`, run:
+
+   ```bash
+   uv run {buildChangeManifestHelper} baseline-gaps \
+       --provenance-map "{provenance_map_path}" \
+       --extraction "{run_dir}/extraction.json" \
+       --files "{run_dir}/modified-files.json" \
+       --source-root "{source_root}" \
+       -o "{run_dir}/baseline-gaps.json"
+   ```
+
+   It writes `{"gaps": [{name, file, line, entry, export_type}], "unchecked": [{name, file, export_type}]}`: in `gaps[]` each entry of a modified file that no export of `{run_dir}/extraction.json` holds and whose file still declares it, at the line that declares it, by the verifier's rule (audit-skill's extraction snapshot applies the same one), and in `unchecked[]` each such entry no rule can check (its file neither Python nor TS/JS, a file the rule will not read, such as a test file or one with a symlink on its path, or a dotted module name), which step 2 reads by eye. Never add a gap or drop one by eye. On exit 1 (an input it cannot read, or a `skf-verify-provenance-completeness.py` beside it that cannot be loaded), no JSON, or no candidate resolves: HALT with status `blocked` (halt procedure: `phase: "detect-changes:category-b"`, its stderr as `reason`): without it, every name the runner leaves out would read as deleted.
 
-2. **What the recipes do not record.** Workers, in parallel batches (Pattern 4) when the list is long, read the modified and added files and each return ONLY `{"exports": [...]}`, with no prose and no fences. For each function export the runner found whose `params` it left null (it could not read the signature): `export_name` and `source_file` as it wrote them, with `params` (each parameter as the source writes it, `name: type`, the form the provenance map's `params` hold) and `return_type` (null when there is none), read at its `source_line`. For each export it could not find (a name `entry_point_diff.extraction_gaps[]` lists, a form Known Limitation #11 in `{extractionPatternsData}` lists, an export of a file `file_issues[]` names or that was read by eye): the same, plus `export_type`, `source_line`, `confidence: T1-low` and `extraction_method: source-read`. Write the union of their `exports` arrays to `{run_dir}/export-details.json`.
+2. **What the recipes do not record.** Workers, in parallel batches (Pattern 4) when the list is long, read the modified and added files and each return ONLY `{"exports": [...]}`, with no prose and no fences. For each function export the runner found whose `params` it left null (it could not read the signature): `export_name` and `source_file` as it wrote them, with `params` (each parameter as the source writes it, `name: type`, the form the provenance map's `params` hold) and `return_type` (null when there is none), read at its `source_line`. For each export it could not find (a name `entry_point_diff.extraction_gaps[]` lists, a name `{run_dir}/baseline-gaps.json` lists in `gaps[]`, a form Known Limitation #11 in `{extractionPatternsData}` lists, an export of a file `file_issues[]` names or that was read by eye): the same, plus `export_type`, `source_line`, `confidence: T1-low` and `extraction_method: source-read`. Record a baseline gap at its `file` and `line` (`source_line`), with, as `export_type`, its `export_type` while the declaration there still has that kind, else the kind it has now (a `variable` now declared by a `def` is a `function`, which step 3 reports as a changed kind), and the declaration's kind when the gap gives none; `params` and `return_type` as the declaration writes them, null when it has none (a module, an alias or a variable). For each `unchecked[]` entry, read its file by eye and record it the same way, at the line that declares it, only when the file still declares it. Record each name and file once: when a file read by eye whole (at Quick tier, or when the runner could not run or left the file unread) holds a name a gap or an `unchecked[]` entry lists, that read's record stands and the gap adds none. Write the union of their `exports` arrays to `{run_dir}/export-details.json`.
 
 3. **The diff.** Resolve `{structuralDiffHelper}` ← first existing path in `{structuralDiffProbeOrder}` and, from `{project-root}`, run:
 
@@ -368,15 +383,19 @@ The helper emits:
 }
 ```
 
-The compare helper reports only tracked files; NEW_FILE detection (a file present in source but absent from the provenance map) is a set-difference, so it runs through a script rather than the prompt. Pipe the same deterministic detector create-skill step 3 §4c uses (resolved via `detectScriptsAssetsProbeOrder`) into `{newFileDiffHelper}`, which subtracts the provenance map's `file_entries[].source_file` and sets aside user-authored `[MANUAL]` paths:
+A map with no `file_entries` field, or a null one (a skill with no script, asset or promoted document, or a map written before the field existed), tracks no file: the comparison lists no row and the set difference below subtracts nothing.
+
+The compare helper reports only tracked files; NEW_FILE detection (a file present in source but absent from the provenance map) is a set-difference, so it runs through a script rather than the prompt. **When `{brief_path}` does not exist** (a skill built without a brief, such as a quick skill), skip it: with no scope to keep to, the walk would read every script and asset of the repository as new. Add `new-files-not-checked: no skill brief, so no new script or asset was looked for` to `warnings[]`, write no `{run_dir}/new-files.json`, and leave `--new-files` out of §3's `build` and step 5's `apply`. Otherwise pipe the detector create-skill step 3 §4c runs (resolved via `detectScriptsAssetsProbeOrder`), which walks the whole source, into `{newFileDiffHelper}`, which keeps what the brief takes and subtracts what the map tracks:
 
 ```bash
 uv run {detectScriptsAssetsHelper} detect "{source_root}" \
-    | uv run {newFileDiffHelper} "{provenance_map_path}" \
+    | uv run {newFileDiffHelper} "{provenance_map_path}" [--brief "{brief_path}"] \
     > "{run_dir}/new-files.json"
 ```
 
-It writes `{"new_files":[{source_file, kind}], "skipped_manual":[...], "already_tracked":[...], "stats":{...}}`. §3's `build` reads both files, typing each compare row by its `file_entries[]` row's `file_type` and each new file by its `kind`: sort no row by hand. `skipped_manual[]` are user-authored files under `scripts/[MANUAL]/` or `assets/[MANUAL]/`, preserved and not touched; `already_tracked[]` were handled by the compare above.
+Pass `--brief` as Category A does, `{brief_path}` as §1c left it (in a read-only run, its copy in `{run_dir}`). On exit 2 (the detector's JSON, the map or the brief it cannot read, named in its JSON `error` on stderr, which also catches a detector that printed nothing), no JSON, or no candidate resolves: HALT with status `blocked` (halt procedure: `phase: "detect-changes:category-d"`, its `error` as `reason`).
+
+It writes `{"new_files":[{source_file, kind}], "skipped_manual":[...], "already_tracked":[...], "tracked_code":[...], "out_of_scope":[...], "intent_none":[...], "stats":{...}}`. §3's `build` reads both files, typing each compare row by its `file_entries[]` row's `file_type` and each new file by its `kind`: sort no row by hand. `skipped_manual[]` are user-authored files under `scripts/[MANUAL]/` or `assets/[MANUAL]/`, preserved and not touched; `already_tracked[]` were handled by the compare above; `tracked_code[]` are code files the map's `entries[]` cite, which Categories A and B compare; `out_of_scope[]` are paths the brief's scope leaves out, by Category A's in-scope test; `intent_none[]` are paths of a kind whose `scripts_intent` or `assets_intent` is `none` (an absent or free-text intent detects). A path in these lists is no new file and no `stats` count, so step 6's report counts each of the three lists from this file, where it shows Category D: a brief scoped wrongly shows as many paths out of scope. A new file Category A lists too stays a new file: Category A lists every changed in-scope file, a genuine script included.
 
 **Write the category JSON** to `{run_dir}/categories.json`, where §2.2 and §3 read it beside the helper files: the two flags, `degraded_mode` and `update_mode: "normal"`. Category C stays in the files its steps wrote, which §2.2, §3 and step 5's `apply` take as `--category-c` and `--ccc-pairs`:
 
@@ -488,13 +507,13 @@ The helper emits the unified manifest envelope:
   "total_export_changes": N,
   "per_file": [
     {"file_path": "...", "status": "MODIFIED|ADDED|DELETED|MOVED",
-     "exports_affected": [{name, change_type, old_line, new_line}, ...]}
+     "exports_affected": [{name, change_type, old_line, new_line, old_file?}, ...]}
   ],
   "category_d": {"scripts_modified": [...], ..., "docs_deleted": [...]}
 }
 ```
 
-`per_file` entries are sorted MODIFIED → ADDED → DELETED → MOVED, then alphabetically within each status group, so downstream stages can rely on stable ordering. MOVED entries include an extra `old_path` field. `category_d` lists the paths behind the `scripts_*`, `assets_*` and `docs_*` counts: a `docs_*` path is a tracked document, which only Category D detects, so a change to one alone is a change. `{run_dir}/change-manifest.json` is the change manifest: step 3, step 6 and step 5's `apply` read it there, so it survives a compacted context.
+`per_file` entries are sorted MODIFIED → ADDED → DELETED → MOVED, then alphabetically within each status group, so downstream stages can rely on stable ordering. MOVED entries include an extra `old_path` field, and a `MOVED_EXPORT` across files an `old_file`, the file it left, where `apply` finds its entry. `category_d` lists the paths behind the `scripts_*`, `assets_*` and `docs_*` counts: a `docs_*` path is a tracked document, which only Category D detects, so a change to one alone is a change. `{run_dir}/change-manifest.json` is the change manifest: step 3, step 6 and step 5's `apply` read it there, so it survives a compacted context.
 
 ### 4. Check for No-Change Shortcut
 

package/src/skf-update-skill/references/gap-driven.md

@@ -88,14 +88,14 @@ Read the gaps of the test report at `{test_report_path}` and translate them into
 |------------|-------------------------------------------|-----------------|
 | `missing-export`, `missing-type` | Missing export, type or interface documentation | NEW_EXPORT (an undocumented public export or type), unless the remediation says the export is internal or out of scope: then DELETED_EXPORT (rescope), see rule R1 |
 | `split-body-mismatch` | Split-body inconsistency: the SKILL.md body and a `references/*.md` file document one export differently, with a `Source:` inside the skill package | STRUCTURAL_FIX, see rule R2 (for an older report, this row takes precedence over the Signature mismatch row below) |
-| `signature-mismatch`, `fabricated-signature`, `stale-documentation` | Signature mismatch; stale documentation (the skill documents an export the source no longer has) | MODIFIED_EXPORT (the documentation needs updating from source) |
+| `signature-mismatch`, `fabricated-signature`, `stale-documentation` | Signature mismatch; stale documentation (the skill documents an export the source's enumerated surface lacks and that is not a documented extra, an Info `observation` this table never routes) | MODIFIED_EXPORT (the documentation needs updating from source) |
 | `structural`, `broken-reference`, `inaccurate-reference`, `reference-escape`, `integration-pattern`, `migration-section`, `scripts-assets` | Structural or coherence drift in the output files only, no source change | STRUCTURAL_FIX, see rule R2 |
 | `provenance-completeness` | Export documented in SKILL.md/references but **missing from the provenance-map** | NEW_EXPORT (provenance-completeness), see rule R3 |
 | `provenance-line` | Provenance line is not the export's definition | MOVED_EXPORT (provenance line), see rule R5 |
 | `metadata-drift`, `metadata` | Divergent export counts in the metadata; missing metadata or examples | metadata update, see rule R4 |
 | any other | any other gap | not routed |
 
-**Not routed:** update-skill has no repair for the other categories. `provenance-unverified` asks for a check by hand, `denominator-inflation` and `multi-denominator` concern the brief's scope and the count design, and `numerator-inflation`, `scripts-assets-provenance`, `observation`, `discovery`, `description` and `external-validator` need a person or another workflow. Such a gap takes no manifest entry (bullet 3 lists it).
+**Not routed:** update-skill has no repair for the other categories. `provenance-unverified` asks for a check by hand, `denominator-inflation`, `brief-scope-stale` and `multi-denominator` concern the brief's scope and the count design, and `numerator-inflation`, `scripts-assets-provenance`, `observation`, `discovery`, `description` and `external-validator` need a person or another workflow. Such a gap takes no manifest entry (bullet 3 lists it).
 
 **Translation rules (referenced by the table above):**
 
@@ -310,7 +310,7 @@ Spot-check each gap's citation instead of re-extracting the files: confirm each
        -o "{run_dir}/remediation-exports.json"
    ```
 
-   Pass `--scope-type` when step 1 read a `scope_type` from metadata.json, so a component library runs its recipe set. It takes no `--brief`: a test report can name a file the brief's scope leaves out as an export's home, and the runner would skip it. On exit 1 (`incomplete`) run it once more; on exit 2 or 3, no JSON, or no candidate resolves, or at Quick tier, read the files by eye (by text pattern). Read by eye only what the recipes leave out: an export a file defines in a form Known Limitation #11 in `{extractionPatternsData}` lists, a file `file_issues[]` names and a name `entry_point_diff.extraction_gaps[]` lists. Write each export read by eye, and the `params` and `return_type` of each function export whose `params` the runner left null, in the shape detect-changes.md §2.1 Category B step 2 gives them, to `{run_dir}/remediation-details.json` as `{"exports": [...]}`. Launch subprocesses in parallel (Pattern 4) when available; sequential fallback otherwise. Follow the tier-degradation rules in `{tierDegradationRulesData}` when AST tools fail on individual files. Then, from `{project-root}`, build the file set's records:
+   Pass `--scope-type` when step 1 read a `scope_type` from metadata.json, so a component library runs its recipe set. It takes no `--brief`: a test report can name a file the brief's scope leaves out as an export's home, and the runner would skip it. On exit 1 (`incomplete`, its JSON written) run it once more. When it is still incomplete, read by eye each file of the file set that has no export in `exports[]` or that an `errors[]` item lists in `unread`, and tell the user which files were read by eye. On exit 2 (an input error, such as a file list it cannot read, or a failure it did not foresee, named in one stderr line with no JSON; `uv` failing to start it exits 2 too), HALT with status `blocked` (halt procedure: `phase: "re-extract:records"`, the stderr line that holds `error:` as `reason`): no by-eye read stands in for it, since this step has written nothing to the skill and reading the files by eye would hide the error. On exit 3, no JSON on another exit, or no candidate resolves, or at Quick tier, read the files by eye (by text pattern). Read by eye only what the recipes leave out: an export a file defines in a form Known Limitation #11 in `{extractionPatternsData}` lists, a file `file_issues[]` names, a name `entry_point_diff.extraction_gaps[]` lists and a file the rule above reads after a still-incomplete run. Write each export read by eye, and the `params` and `return_type` of each function export whose `params` the runner left null, in the shape detect-changes.md §2.1 Category B step 2 gives them, to `{run_dir}/remediation-details.json` as `{"exports": [...]}`. Launch subprocesses in parallel (Pattern 4) when available; sequential fallback otherwise. Follow the tier-degradation rules in `{tierDegradationRulesData}` when AST tools fail on individual files. Then, from `{project-root}`, build the file set's records:
 
    ```bash
    uv run {buildChangeManifestHelper} records \