bmad-module-skill-forge 3.0.0 → 4.0.0

package/src/shared/scripts/skf-merge-doc-urls.py

@@ -1,18 +1,25 @@
 # /// script
 # requires-python = ">=3.11"
-# dependencies = []
+# dependencies = ["pyyaml"]
 # ///
 """SKF Merge Doc URLs — merge corpora-seeded + detected docs for a skill brief.
 
 Deterministic merge of an upstream brief's `doc_urls` (registry-seeded
 companion corpora, source: language-registry) with the docs freshly
 discovered by `skf-detect-docs.py` (mapped to the brief `{url, label, source}`
-contract). Replaces the prose dedup/suppression that lived inline in
-`skf-brief-skill/references/step-auto-brief.md` §3 — that logic is fiddly
+contract). Replaces the prose mapping, dedup and suppression that lived inline
+in `skf-brief-skill/references/step-auto-brief.md` §3. That logic is fiddly
 (normalized-URL collisions, non-corpus path segments, locale duplicates) and
 must behave identically on every run, so it belongs in a tested script.
 
-Three operations, in order:
+With --detected-file, each skf-detect-docs.py entry {url, detected_via,
+content_type} is first mapped to {url, label, source}: `source` from
+`detected_via` and `label` from `content_type`, by the two tables below (a
+content_type they do not list gives the label ""). An entry whose
+`detected_via` they do not list is never merged: `suppressed` lists it with
+reason unknown-detected-via.
+
+Three merge operations, in order:
 
   1. Normalized-URL dedup — lowercase host, strip a trailing `/index.html`
      and any trailing `/` before comparing, so a seeded `…/book/` and a
@@ -41,10 +48,18 @@ DEGRADED case is intentionally out of scope (there is no canonical corpus host
 to anchor suppression against).
 
 CLI:
+  uv run src/shared/scripts/skf-merge-doc-urls.py --scope-type <type> \
+      --detected-file <detect-docs.json> --existing-brief <skill-brief.yaml>
   echo '{"scope_type": "...", "existing": [...], "detected": [...]}' \
     | uv run src/shared/scripts/skf-merge-doc-urls.py
 
-Input (JSON object on stdin):
+Files form (stdin is not read): --detected-file holds skf-detect-docs.py's
+JSON array, mapped as above; --existing-brief is a skill-brief.yaml whose
+`doc_urls` are the existing entries (none when it has no doc_urls), read as
+skf-resolve-authoritative-files.py reads a brief; --scope-type is the scope
+type. Each flag is optional: an absent one gives no entries (or "").
+
+Input of the stdin form (a JSON object), whose entries are merged as given:
   {
     "scope_type": "full-library",
     "existing":   [{"url": "...", "label": "...", "source": "language-registry"}, ...],
@@ -54,22 +69,42 @@ Input (JSON object on stdin):
 Output (JSON object on stdout):
   {
     "doc_urls":   [{"url": "...", "label": "...", "source": "..."}, ...],
-    "suppressed": [{"url": "...", "reason": "non-corpus-segment|non-primary-locale-dup"}, ...]
+    "suppressed": [{"url": "...", "reason":
+                    "unknown-detected-via|non-corpus-segment|non-primary-locale-dup"}, ...]
   }
 
 Exit codes:
   0  success (merged list emitted)
-  2  error (bad JSON, wrong input shape)
+  2  error (bad JSON, wrong input shape, a file that cannot be read, a brief
+     that is not a YAML mapping)
 """
 
 from __future__ import annotations
 
+import argparse
+import importlib.util
 import json
 import re
 import sys
+from pathlib import Path
 from typing import Any
 from urllib.parse import urlsplit
 
+# skf-detect-docs.py's `detected_via` -> the brief's coarse provenance, the
+# skill-brief.v1.json doc_urls[].source enum (a test pins it to the schema).
+_SOURCE_BY_DETECTED_VIA = {
+    "homepageUrl": "homepage",
+    "readme_link": "readme-detection",
+    "pages_api": "pages-api",
+    "docs_folder": "docs-folder",
+}
+# skf-detect-docs.py's `content_type` -> the entry's display label.
+_LABEL_BY_CONTENT_TYPE = {
+    "api-docs": "API Documentation",
+    "guide": "Guide",
+    "reference": "Reference",
+}
+
 # Path components (case-insensitive) that mark a non-corpus page on a doc host:
 # changelogs/news, contribution guides, wikis. Matched as whole path components
 # (or component + a separator), never as a bare substring.
@@ -153,6 +188,28 @@ def _matches_non_corpus_segment(path: str) -> bool:
     return False
 
 
+def map_detected(raw: list[Any]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """skf-detect-docs.py entries as brief doc_urls entries {url, label, source}.
+
+    Returns (mapped, suppressed): an entry whose detected_via maps to no
+    source is suppressed with reason unknown-detected-via; one with no url is
+    skipped, as the merge skips it.
+    """
+    mapped: list[dict[str, Any]] = []
+    suppressed: list[dict[str, Any]] = []
+    for d in raw:
+        if not isinstance(d, dict) or not d.get("url"):
+            continue
+        via, content_type = d.get("detected_via"), d.get("content_type")
+        source = _SOURCE_BY_DETECTED_VIA.get(via) if isinstance(via, str) else None
+        if source is None:
+            suppressed.append({"url": d["url"], "reason": "unknown-detected-via"})
+            continue
+        label = _LABEL_BY_CONTENT_TYPE.get(content_type, "") if isinstance(content_type, str) else ""
+        mapped.append({"url": d["url"], "label": label, "source": source})
+    return mapped, suppressed
+
+
 def merge_doc_urls(
     scope_type: str,
     existing: list[dict[str, Any]],
@@ -232,30 +289,96 @@ def _force_utf8(*streams) -> None:
                 stream.reconfigure(encoding="utf-8", errors=errors)
 
 
-def main() -> int:
-    _force_utf8(sys.stdin, sys.stdout)
+class InputError(Exception):
+    """An input the merge cannot read (exit 2)."""
+
+
+def _read_detected(path: str) -> list[Any]:
+    """The JSON array skf-detect-docs.py wrote to `path`."""
+    try:
+        data = json.loads(Path(path).read_bytes().decode("utf-8-sig"))
+    except OSError as exc:
+        raise InputError(f"cannot read --detected-file {path}: {exc.strerror or exc}") from exc
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise InputError(f"--detected-file {path} is not JSON: {exc}") from exc
+    if not isinstance(data, list):
+        raise InputError(f"--detected-file {path} must hold a JSON array (skf-detect-docs.py output)")
+    return data
+
+
+def _brief_doc_urls(path: str) -> list[Any]:
+    """The doc_urls of the skill brief at `path`, read by
+    skf-resolve-authoritative-files.py's parse_brief_yaml (beside this file)."""
+    resolver_path = Path(__file__).resolve().parent / "skf-resolve-authoritative-files.py"
+    spec = importlib.util.spec_from_file_location("skf_resolve_authoritative_files", resolver_path)
+    if spec is None or spec.loader is None:
+        raise InputError(f"cannot load {resolver_path.name} beside {Path(__file__).name}")
+    resolver = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(resolver)
+    except (OSError, ImportError, SyntaxError) as exc:
+        raise InputError(f"cannot load {resolver_path.name} beside {Path(__file__).name}: {exc}") from exc
+    try:
+        brief = resolver.parse_brief_yaml(Path(path).read_bytes().decode("utf-8-sig"))
+    except OSError as exc:
+        raise InputError(f"cannot read --existing-brief {path}: {exc.strerror or exc}") from exc
+    except (UnicodeDecodeError, resolver.yaml.YAMLError) as exc:
+        raise InputError(f"--existing-brief {path} is not YAML: {exc}") from exc
+    if not isinstance(brief, dict):
+        raise InputError(f"--existing-brief {path} holds no brief mapping")
+    doc_urls = brief.get("doc_urls") or []
+    if not isinstance(doc_urls, list):
+        raise InputError(f"the doc_urls of --existing-brief {path} must be a list")
+    return doc_urls
+
+
+def _stdin_payload() -> tuple[str, list[Any], list[Any]]:
+    """(scope_type, existing, detected) of the stdin form."""
     raw = sys.stdin.read()
     if not raw or not raw.strip():
-        sys.stderr.write("skf-merge-doc-urls: empty stdin (expected JSON object)\n")
-        return 2
+        raise InputError("empty stdin (expected JSON object)")
     try:
         payload = json.loads(raw)
     except json.JSONDecodeError as exc:
-        sys.stderr.write(f"skf-merge-doc-urls: invalid JSON on stdin: {exc}\n")
-        return 2
+        raise InputError(f"invalid JSON on stdin: {exc}") from exc
     if not isinstance(payload, dict):
-        sys.stderr.write("skf-merge-doc-urls: input must be a JSON object\n")
-        return 2
-
-    scope_type = payload.get("scope_type") or ""
+        raise InputError("input must be a JSON object")
     existing = payload.get("existing") or []
     detected = payload.get("detected") or []
     if not isinstance(existing, list) or not isinstance(detected, list):
-        sys.stderr.write("skf-merge-doc-urls: 'existing' and 'detected' must be arrays\n")
+        raise InputError("'existing' and 'detected' must be arrays")
+    return payload.get("scope_type") or "", existing, detected
+
+
+def main(argv: list[str] | None = None) -> int:
+    _force_utf8(sys.stdin, sys.stdout)
+    parser = argparse.ArgumentParser(
+        prog="skf-merge-doc-urls",
+        description="Merge a brief's doc_urls with the docs skf-detect-docs.py found. With no flag, read the "
+                    "{scope_type, existing, detected} JSON object on stdin.",
+    )
+    parser.add_argument("--detected-file", metavar="PATH",
+                        help="skf-detect-docs.py's JSON array, mapped to {url, label, source}")
+    parser.add_argument("--existing-brief", metavar="PATH",
+                        help="the skill-brief.yaml whose doc_urls are the existing entries")
+    parser.add_argument("--scope-type", metavar="TYPE", help="the brief's scope.type")
+    args = parser.parse_args(argv)
+    unknown: list[dict[str, Any]] = []
+    try:
+        if args.detected_file is None and args.existing_brief is None and args.scope_type is None:
+            scope_type, existing, detected = _stdin_payload()
+        else:
+            scope_type = args.scope_type or ""
+            existing = _brief_doc_urls(args.existing_brief) if args.existing_brief is not None else []
+            detected = []
+            if args.detected_file is not None:
+                detected, unknown = map_detected(_read_detected(args.detected_file))
+    except InputError as exc:
+        sys.stderr.write(f"skf-merge-doc-urls: {exc}\n")
         return 2
 
     doc_urls, suppressed = merge_doc_urls(scope_type, existing, detected)
-    json.dump({"doc_urls": doc_urls, "suppressed": suppressed}, sys.stdout, ensure_ascii=False)
+    json.dump({"doc_urls": doc_urls, "suppressed": unknown + suppressed}, sys.stdout, ensure_ascii=False)
     sys.stdout.write("\n")
     return 0
 

package/src/shared/scripts/skf-preflight.py

@@ -49,6 +49,7 @@ SIDECAR_MISSING.
 
 from __future__ import annotations
 
+import datetime
 import json
 import re
 import stat
@@ -82,6 +83,19 @@ PLACEHOLDER_RE = re.compile(r"\{[^{}]*\}")
 FOLDER_KEYS = ("output_folder", "skills_output_folder", "forge_data_folder")
 
 
+def _json_default(value):
+    """Print a date or time as ISO 8601.
+
+    YAML reads an unquoted timestamp as a date or datetime object. SKF 1.x
+    wrote ``tier_detected_at`` and ``ccc_index.last_indexed`` in
+    forge-tier.yaml unquoted, so a sidecar from before 2.0.0 holds them; any
+    other value json cannot print is still an error.
+    """
+    if isinstance(value, (datetime.date, datetime.time)):
+        return value.isoformat()
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+
 def load_yaml_file(path):
     """Load a YAML mapping, returning (data, None) or (None, error_string).
 
@@ -304,5 +318,5 @@ if __name__ == "__main__":
             cfg_path = sys.argv[idx + 1]
 
     result = run_preflight(proj_root, cfg_path, allow_missing_sidecar="--allow-missing-sidecar" in sys.argv)
-    print(json.dumps(result, indent=2))
+    print(json.dumps(result, indent=2, default=_json_default))
     sys.exit(1 if result["status"] == "hard-halt" else 0)

package/src/shared/scripts/skf-provenance-gap-dispatch.py

@@ -78,6 +78,7 @@ Exit codes:
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import json
 import re
 import sys
@@ -256,14 +257,37 @@ _DEFERRED = "deferred-headless"
 _LEGACY_HEADLESS_REASON = "headless: no user to prompt"
 
 
+_RESOLVER = None
+
+
+def _resolver():
+    """skf-resolve-authoritative-files.py from this folder, loaded once: its
+    parse_brief_yaml reads a brief's YAML, an SKF 1.x brief's trailing `---`
+    included. Raises ValueError when it cannot be loaded."""
+    global _RESOLVER
+    if _RESOLVER is None:
+        path = Path(__file__).resolve().parent / "skf-resolve-authoritative-files.py"
+        spec = importlib.util.spec_from_file_location("skf_resolve_authoritative_files", path)
+        if spec is None or spec.loader is None:
+            raise ValueError(f"cannot load {path.name} beside {Path(__file__).name}")
+        module = importlib.util.module_from_spec(spec)
+        try:
+            spec.loader.exec_module(module)
+        except (OSError, ImportError, SyntaxError) as exc:
+            raise ValueError(f"cannot load {path.name} beside {Path(__file__).name}: {exc}") from exc
+        _RESOLVER = module
+    return _RESOLVER
+
+
 def load_brief(brief_path: Path) -> dict:
     """Parse a skill-brief.yaml file. Raises ValueError on load failure."""
     try:
         text = brief_path.read_text(encoding="utf-8")
     except OSError as exc:
         raise ValueError(f"cannot read brief at {brief_path}: {exc}") from exc
+    parse_brief_yaml = _resolver().parse_brief_yaml
     try:
-        brief = yaml.safe_load(text)
+        brief = parse_brief_yaml(text)
     except yaml.YAMLError as exc:
         raise ValueError(f"brief at {brief_path} is not valid YAML: {exc}") from exc
     if not isinstance(brief, dict):

package/src/shared/scripts/skf-resolve-authoritative-files.py

@@ -109,8 +109,17 @@ import yaml
 
 # skf-classify-changed-files.py loads this file for load_brief,
 # extract_scope, glob_match, scope_match, normalize_rel_path and
-# EXCLUDED_DIR_NAMES, and skf-detect-registry.py for glob_match, load_brief
-# and extract_scope: keep those names and what they take and return.
+# EXCLUDED_DIR_NAMES (its load_scope, the brief-scope test that
+# skf-new-file-diff.py, skf-detect-scripts-assets.py --brief and
+# skf-compare-file-hashes.py --brief load from it, reads the brief through
+# them), skf-detect-registry.py for glob_match, load_brief
+# and extract_scope, skf-extract-public-api.py for glob_match and
+# parse_brief_yaml, and every other script that reads a skill brief
+# (skf-validate-brief-schema.py, skf-provenance-gap-dispatch.py,
+# skf-derive-assembly-shape.py, skf-write-skill-brief.py and skf-test-skill's
+# load-coverage-inputs.py) for parse_brief_yaml, load-coverage-inputs.py
+# also for _amendment_action: keep those names and what they take and
+# return.
 
 
 # --------------------------------------------------------------------------
@@ -270,13 +279,30 @@ def scope_match(
 # --------------------------------------------------------------------------
 
 
+def parse_brief_yaml(text: str):
+    """The one document a skill brief's YAML text holds, or None when it holds none.
+
+    SKF 1.x closed every brief with a trailing `---`, which YAML reads as a
+    second, empty document, so `yaml.safe_load` refuses such a brief. A
+    document that holds no value (empty, or an explicit null such as `~`) is
+    skipped wherever it stands; more than one document that holds a value is
+    refused with yaml.YAMLError, as is text that is not YAML.
+    """
+    documents = [doc for doc in yaml.safe_load_all(text) if doc is not None]
+    if len(documents) > 1:
+        raise yaml.YAMLError(
+            f"a skill brief is a single document; this text holds {len(documents)}"
+        )
+    return documents[0] if documents else None
+
+
 def load_brief(brief_path: Path) -> dict:
     try:
         text = brief_path.read_text(encoding="utf-8")
     except OSError as exc:
         raise ValueError(f"cannot read brief at {brief_path}: {exc}") from exc
     try:
-        brief = yaml.safe_load(text)
+        brief = parse_brief_yaml(text)
     except yaml.YAMLError as exc:
         raise ValueError(
             f"brief at {brief_path} is not valid YAML: {exc}"

package/src/shared/scripts/skf-structural-diff.py

@@ -63,6 +63,20 @@ Matching:
   listed in ambiguous_names[] with the files on each side, for a reviewer
   to judge.
 
+Public surface:
+  A current entry may carry `public`, true or false: the mark
+  skf-extraction-snapshot.py build --scope-type public-api gives each
+  export by the public-surface rule a public-api skill's provenance map is
+  kept to. After the pairing above, a current entry marked false that
+  pairs with none (no baseline entry of its name and file, and no move)
+  goes to not_public[], not added[]: create-skill and update-skill never
+  document an export off the surface, so it is no drift. One whose name is
+  in ambiguous_names[] stays in added[], where a reviewer pairs it. A
+  matched or moved entry is compared whatever its mark, so a baseline
+  entry off the surface is never reported removed. An entry with no mark
+  (any other scope type, a family with no barrel, an older snapshot) is
+  added as before. not_public[] never counts toward the exit code.
+
 File scope (--files FILE):
   For a caller that re-extracted only the files that changed (update-skill's
   Category B), --files limits the diff to the exports of the files FILE
@@ -116,12 +130,27 @@ Canonicalization (applied symmetrically to BOTH sides before matching):
   ` = default`), so a runner's export compares with the map's entry.
 
 Change detection:
-  The diffed fields are type, signature, params, return_type and line. A
-  field is only compared when present (non-null) on BOTH sides: a field
-  absent on one side means "insufficient data", never an asserted change.
+  The diffed fields are type (compared through export-type, below),
+  signature, params, return_type and line. A field is only compared when
+  present (non-null) on BOTH sides: a field absent on one side means
+  "insufficient data", never an asserted change.
   This avoids false positives when the two inventories carry different
   metadata. The line of a moved export is not compared: a move changes it.
 
+  export-type: no record is rewritten, but when a matched export's two
+  types differ, a semantic kind a by-eye read records is the base kind
+  the recipe runner records for the same declaration when the base-kind
+  side's canonical signature shows that form: `async_function` is
+  `function` for an `async def`, `async function`, `async fn` or
+  `async unsafe fn`, or a `const`, `let` or `var` bound to an `async`
+  arrow or function (after `export`, `default`, `declare` or `pub`);
+  `decorator` is `function` for a Python `def` or `async def`; `enum` is
+  `class` for a Python class with a stdlib `Enum`, `IntEnum`, `StrEnum`,
+  `ReprEnum`, `Flag` or `IntFlag` base. Either side may hold the by-eye
+  kind; with no signature on the base-kind side the types differ. Each
+  export whose types it takes as one counts once as `export-type` in
+  applied_transforms.
+
   A signature has two parts, the parameters and the return type. A side
   carries the parameters as params or in its signature, and the return
   type as return_type or in its signature. When both sides carry a part
@@ -145,7 +174,7 @@ Output:
   JSON object:
     summary:            { added, removed, changed, moved, unchanged,
                           label_changes, ambiguous_names,
-                          signature_unverified }
+                          signature_unverified, not_public }
     added:              list of entries present in current but not baseline
     removed:            list of entries present in baseline but not current
     changed:            list of { name, field, baseline_value, current_value,
@@ -168,17 +197,26 @@ Output:
                         params and return_type each side carries.
                         Informational: never a change, never in the exit
                         code
+    not_public:         list of current entries marked `public: false`
+                        that pair with no baseline entry and whose name is
+                        not ambiguous (see Public surface): exports off a
+                        public-api skill's public surface, left out of
+                        added[]. Not drift, never in the exit code
     unchanged_count:    number of entries that matched with no field change
                         (a label change or an unverified signature alone
                         leaves an entry unchanged)
     applied_transforms: list of { transform, count }: which canonicalization
-                        transforms actually fired and how many values each
-                        touched (empty when none fired). Surfaced by audit
+                        transforms, and the export-type comparison,
+                        actually fired and how many values each touched
+                        (export-type: how many exports; empty when none
+                        fired). Surfaced by audit
                         step 6's Provenance section so a reviewer can tell
                         which differences the diff collapsed.
 
-  added[] and removed[] hold normalized records: name, type, signature,
-  params, return_type, file, line, confidence and extraction_method.
+  added[], removed[] and not_public[] hold normalized records: name, type,
+  signature, params, return_type, file, line, confidence and
+  extraction_method, and `public` when the entry carries a true or false
+  mark (see Public surface).
 
   With --group-by source_library, each side is split by its entries'
   source_library (a stack's libraries; an entry without one falls in a
@@ -208,8 +246,9 @@ Exit codes:
      inventory whose entries all lack the field while the other's have it,
      an output that cannot be written, or a usage error ({status: "error",
      error} on stdout, or argparse's usage on stderr)
-  Label differences (label_changes) and unverified signatures
-  (signature_unverified) do not count toward the exit code.
+  Label differences (label_changes), unverified signatures
+  (signature_unverified) and exports off the public surface (not_public) do
+  not count toward the exit code.
 """
 
 from __future__ import annotations
@@ -275,6 +314,37 @@ _STDLIB_PREFIX_RE = re.compile(
     r"(?<![\w.])(?:typing|dataclasses|collections\.abc|collections|enum)\."
 )
 
+# export-type: a semantic kind a by-eye read records, against the base kind
+# the recipe runner records for the same declaration, names one kind when
+# the base-kind side's canonical signature shows that form. Any other pair
+# of types, or a base-kind side with no signature, is compared as written.
+# An async form: `async def`, `async function`, `async fn` or `async unsafe
+# fn`, or a `const` / `let` / `var` bound to an `async` arrow or function
+# (`export const add = async (x) => x;`), after any `export`, `default`,
+# `declare` or `pub` modifier.
+_ASYNC_FORM_RE = re.compile(
+    r"^\s*(?:(?:export|default|declare|pub(?:\s*\([^()]*\))?)\s+)*"
+    r"(?:async\s+(?:unsafe\s+)?(?:def|function|fn)\b"
+    r"|(?:const|let|var)\s+[\w$]+\s*(?::(?:[^=]|=>)*)?=\s*async\b)"
+)
+_DEF_FORM_RE = re.compile(r"^\s*(?:async\s+)?def\s")
+_CLASS_BASES_RE = re.compile(r"^\s*class\s+\w+\s*\(([^()]*)\)")
+_ENUM_BASES = frozenset({"Enum", "IntEnum", "StrEnum", "ReprEnum", "Flag", "IntFlag"})
+
+
+def _enum_class_form(signature: str) -> bool:
+    """True when a Python class declaration lists a stdlib enum base."""
+    m = _CLASS_BASES_RE.match(signature)
+    return m is not None and any(base.strip() in _ENUM_BASES for base in m.group(1).split(","))
+
+
+# (by-eye kind, base kind) -> the test of the base-kind side's signature.
+EXPORT_TYPE_FORMS = {
+    ("async_function", "function"): lambda signature: _ASYNC_FORM_RE.match(signature) is not None,
+    ("decorator", "function"): lambda signature: _DEF_FORM_RE.match(signature) is not None,
+    ("enum", "class"): _enum_class_form,
+}
+
 
 # --------------------------------------------------------------------------
 # Loading
@@ -561,6 +631,10 @@ def _normalize_entries(
             "confidence": entry.get("confidence"),
             "extraction_method": entry.get("extraction_method"),
         }
+        # The snapshot's public-surface mark, kept only when it is one, so an
+        # unmarked inventory's records are as before.
+        if isinstance(entry.get("public"), bool):
+            record["public"] = entry["public"]
         key = (name, _file_key(record["file"]))
         kept = result.get(key)
         if kept is not None and not (
@@ -616,6 +690,21 @@ def _label_change(base_rec: dict, curr_rec: dict) -> dict | None:
     return None
 
 
+def _export_type_collapses(base_rec: dict, curr_rec: dict) -> bool:
+    """True when two matched records' types name one kind (EXPORT_TYPE_FORMS):
+    one side's by-eye kind against the other's base kind, whose canonical
+    signature shows that form. Either side may hold the by-eye kind."""
+    for by_eye, base in ((base_rec, curr_rec), (curr_rec, base_rec)):
+        kinds = (by_eye.get("type"), base.get("type"))
+        signature = base.get("signature")
+        if not all(isinstance(kind, str) for kind in kinds) or not isinstance(signature, str):
+            continue
+        form = EXPORT_TYPE_FORMS.get(kinds)
+        if form is not None and form(signature):
+            return True
+    return False
+
+
 def _signature_fields(rec: dict) -> list[str]:
     return [field for field in SIGNATURE_FIELDS if rec.get(field) is not None]
 
@@ -641,7 +730,8 @@ def _unverified_signature(base_rec: dict, curr_rec: dict) -> dict | None:
 # --------------------------------------------------------------------------
 
 
-LISTS = ["added", "removed", "changed", "moved", "ambiguous_names", "label_changes", "signature_unverified"]
+LISTS = ["added", "removed", "changed", "moved", "ambiguous_names", "label_changes", "signature_unverified",
+         "not_public"]
 
 
 def _key_order(key: tuple) -> tuple:
@@ -656,14 +746,18 @@ def _diff_records(
     baseline: dict[tuple, dict],
     current: dict[tuple, dict],
     unchanged_names: collections.Counter | None = None,
+    transform_counts: collections.Counter | None = None,
 ) -> dict:
     """Diff two (name, file)-keyed record sets: the LISTS, plus the counts
     unchanged_count and changed_exports (exports with a changed field).
 
     unchanged_names counts the names of exports left out of both sets as
     unchanged (--files): each counts on both sides when a move needs a name
-    unique on both sides.
+    unique on both sides. transform_counts gains one export-type for each
+    matched export whose types name one kind (_export_type_collapses).
     """
+    if transform_counts is None:
+        transform_counts = collections.Counter()
     removed_keys = sorted((k for k in baseline if k not in current), key=_key_order)
     added_keys = sorted((k for k in current if k not in baseline), key=_key_order)
 
@@ -697,8 +791,20 @@ def _diff_records(
 
     # Emit normalized entries (uniform shape) so added[] and removed[] render
     # into the same report table even though they originate from the
-    # snapshot and provenance-map shapes.
-    added = [current[k] for k in added_keys if k not in paired_curr]
+    # snapshot and provenance-map shapes. After the pairing, a leftover
+    # current entry marked off the public surface is no addition, unless its
+    # name is ambiguous: a reviewer may pair it as a move.
+    ambiguous = {item["name"] for item in ambiguous_names}
+    added: list[dict] = []
+    not_public: list[dict] = []
+    for key in added_keys:
+        if key in paired_curr:
+            continue
+        rec = current[key]
+        if rec.get("public") is False and rec["name"] not in ambiguous:
+            not_public.append(rec)
+        else:
+            added.append(rec)
     removed = [baseline[k] for k in removed_keys if k not in paired_base]
 
     changed: list[dict] = []
@@ -736,6 +842,11 @@ def _diff_records(
             if base_val is None or curr_val is None:
                 continue
             if base_val != curr_val:
+                # A by-eye kind and the runner's base kind of one declaration
+                # are one type: compared pairwise, never rewritten.
+                if field == "type" and _export_type_collapses(base_rec, curr_rec):
+                    transform_counts["export-type"] += 1
+                    continue
                 changed.append({
                     "name": curr_rec["name"],
                     "field": field,
@@ -771,6 +882,7 @@ def _diff_records(
         "ambiguous_names": ambiguous_names,
         "label_changes": label_changes,
         "signature_unverified": signature_unverified,
+        "not_public": not_public,
         "unchanged_count": unchanged_count,
         "changed_exports": changed_exports,
     }
@@ -786,6 +898,7 @@ def _summary(part: dict) -> dict:
         "label_changes": len(part["label_changes"]),
         "ambiguous_names": len(part["ambiguous_names"]),
         "signature_unverified": len(part["signature_unverified"]),
+        "not_public": len(part["not_public"]),
     }
 
 
@@ -813,10 +926,11 @@ def diff_inventories(
     """Compute the structural diff between two export inventories.
 
     Returns a dict with keys: summary, added, removed, changed, moved,
-    ambiguous_names, label_changes, signature_unverified, unchanged_count,
-    applied_transforms; with group_by, group_by and groups; and with files,
-    file_scope (see the module docstring). files limits the diff to the
-    exports of those files, and every other export is taken as unchanged.
+    ambiguous_names, label_changes, signature_unverified, not_public,
+    unchanged_count, applied_transforms; with group_by, group_by and
+    groups; and with files, file_scope (see the module docstring). files
+    limits the diff to the exports of those files, and every other export
+    is taken as unchanged.
 
     Raises ValueError when group_by is set and one side has entries but
     none with a group_by value while the other side has some; the message
@@ -869,6 +983,7 @@ def diff_inventories(
             _normalize_entries(base_part, reexport_map, transform_counts),
             _normalize_entries(curr_part, reexport_map, transform_counts),
             unchanged_names,
+            transform_counts,
         )
         if group_by:
             for name in LISTS: