bmad-module-skill-forge 3.0.0 → 5.0.0

package/src/shared/scripts/skf-extraction-inventory.py

@@ -1,6 +1,6 @@
 # /// script
 # requires-python = ">=3.11"
-# dependencies = []
+# dependencies = ["pyyaml"]
 # ///
 """SKF Extraction Inventory: write, extend and read create-skill's extraction inventory on disk.
 
@@ -12,8 +12,9 @@ runner's JSON and the script/asset detector's JSON, so the model never
 types a record those tools already wrote; the model then sends only what it
 produced itself (`patch`, `add`, `set`). Step 3c adds the T3 items it
 extracts from fetched documentation, step 4 the T2 annotations it finds in
-QMD, and step 7 writes `extraction-rules.yaml` from it (`rules`). Every
-write goes through a temporary file and one rename.
+QMD, compile writes the provenance map (`provenance`) and metadata.json
+(`metadata`) from it, and step 7 writes `extraction-rules.yaml` from it
+(`rules`). Every write goes through a temporary file and one rename.
 
 Subcommands:
 
@@ -32,6 +33,33 @@ Subcommands:
            file_issues[] file, each files_without_recipes extension, each
            warnings[] entry). From --detected (skf-detect-scripts-assets.py
            detect): scripts_inventory and assets_inventory.
+           Public surface. When the runner's scope.type is public-api (in
+           any case) and its entry-point diff can be read, each export of a
+           language family whose entry_points.by_language status is
+           `barrel` is marked `public: true` when its name and file are a
+           pair of the diff's `public` or `other_definitions` (each other
+           in-scope definition of a public name, #830; its name, or the
+           name `local` gives it in that file) or `extraction_gaps`, or
+           when a `public` item of its name and family has no file;
+           `public: false` otherwise. A
+           `public` item with `via` namespace and a `members` list (what
+           the submodule passes on, which users reach as `pkg.sub.name`)
+           gives its members' pairs (each member's name, or its `local`
+           one, and its file; a member with no file its name) in place of
+           its own; one whose `members` is null (a module the runner could
+           not read), or that has no `members` key (an older runner's),
+           gives its own pair, as any item does. It is the rule
+           skf-build-change-manifest.py's `records` marks an update's
+           exports by (that script loads it from here). The rule's inputs
+           are kept as `public_surface`, so `add` marks an export read by
+           eye the same way. Any other scope type, and a family with no
+           barrel, mark nothing. A public-api run with no entry-point diff,
+           an incomplete one, one with errors or one whose
+           entry_points.unresolved is not empty marks nothing either
+           (`public_surface` null), with one warning that says why: every
+           export is then documented. One warning names the exports marked
+           `public: false`, each as `name (file)` (the first ten, then how
+           many more).
 
   add      --inventory <file> --field exports|t2_annotations|t3_items|warnings
            Read a JSON list on stdin (objects; strings for warnings) and
@@ -40,7 +68,16 @@ Subcommands:
            added twice and counts in `duplicates`. An exports entry needs an
            export_name; a missing confidence, extraction_method,
            ast_node_type or ast_recipe defaults to T1-low, source-read,
-           null and null (an export read by eye). A t3_items entry whose
+           null and null (an export read by eye). Its source_file is
+           relative to the source root, written and compared with `/`
+           separators and no leading `./`, as the runner writes its files
+           (`./pkg/api.py` and `pkg\\api.py` are `pkg/api.py`); an absolute
+           one (a leading `/` or a drive letter) is refused, and the call
+           adds nothing. An exports entry is
+           marked `public` by the inventory's `public_surface`, as `init`
+           marks the runner's (a `public` key the payload sends is not
+           kept), and the warning naming the exports marked `public: false`
+           is written again, in its place. A t3_items entry whose
            export_name names an export the inventory already holds is
            dropped, not added: T3 content never overrides a T1, T1-low or
            T2 entry for the same export.
@@ -54,7 +91,8 @@ Subcommands:
            in `unmatched`, one that matches several in `ambiguous`; neither
            changes anything. params lists each parameter as the runner
            records one, {name, type, default, optional}, or as a typed
-           string ('userId: string').
+           string ('userId: string'). The source_file is compared as `add`
+           compares it: `./pkg/api.py` matches the export at `pkg/api.py`.
 
   set      --inventory <file>
            Read a JSON object on stdin and set each of its keys: top_exports,
@@ -64,7 +102,9 @@ Subcommands:
            and intent_mapping. intent_mapping maps `scripts` and `assets`
            to {"intent": "<free text>", "kept": [source_file, ...]}: the
            inventory keeps only the kept entries of that list and records
-           the others in the mapping's `left_out`.
+           the others in the mapping's `left_out`. A top_exports name every
+           export of which is marked `public: false` is not kept and is
+           listed in `dropped`.
 
   provenance --inventory <file> --target <provenance-map.json> [--add-entries]
            Write the provenance map to --target, so compile never types an
@@ -74,7 +114,9 @@ Subcommands:
            "2.0"), skill_name (default the inventory's), skill_type
            (default "single") and generated_at (default now, ISO-8601
            UTC); any other key is refused. entries[] holds the entry of
-           every export of the inventory, in its order: export_name,
+           every export of the inventory, in its order, but one marked
+           `public: false` (off a public-api skill's public surface, which
+           neither entries[] nor `unsigned` lists): export_name,
            export_type, params, return_type, source_file, source_line,
            confidence, extraction_method, ast_node_type and
            signature_source, labeled by the tool that found it. An export
@@ -97,7 +139,52 @@ Subcommands:
            T3) and the file entries. An entry whose export_name and
            source_file the map already holds, or a file entry whose
            file_name it holds, is not added and counts in `duplicates`, so
-           an inventory export's entry is never replaced.
+           an inventory export's entry is never replaced. An entry whose
+           export_name and source_file are an inventory export's marked
+           `public: false` is not added either and is listed in
+           `not_public`, so the map never holds an export off the surface.
+
+  metadata --inventory <file> --brief <skill-brief.yaml> --stats <file>
+           --skf-root <dir> --target <metadata.json>
+           Write the skill's metadata.json to --target, so compile types
+           only the fields it decides. stdin holds them, a JSON object:
+           version and language (non-empty strings), source_root,
+           source_commit, source_ref and qmd_version (strings or null),
+           each required, and ast_grep_version (a string or null, default
+           null) and stats_extra (an object, default {}); any other key is
+           refused. The rest comes from the files:
+           name, scope_type (the brief's scope.type, verbatim), source_repo
+           and source_authority (default "community") from --brief;
+           description from the frontmatter of the SKILL.md beside
+           --target (compile's staged one); confidence_tier (the
+           inventory's tier); exports[], the names of the inventory's
+           exports but one marked `internal: true` or `public: false`,
+           each once, in its order (a docs-only inventory's t3_items
+           names; none for a reference-app brief); ast_node_count and
+           tool_versions.ast_grep, only when ast-grep ran: when the
+           runner ran it (extraction_rules.ast_grep_version is set), the
+           runner's aggregates.exports and that version; otherwise, when
+           exports carry extraction_method ast-grep (the recipes run
+           without the runner), their number and stdin's
+           ast_grep_version, else "unknown" with a warning (stdin's
+           ast_grep_version is read in that case only);
+           tool_versions.ast_grep is null when ast-grep did not run, and
+           ast_node_count left out; scripts[] and assets[], {file:
+           scripts/<name> or assets/<name>, purpose, source_file,
+           confidence} per scripts_inventory or assets_inventory entry,
+           left out when it is empty; and stats and
+           confidence_distribution verbatim from --stats (the JSON
+           skf-render-metadata-stats.py wrote), with stats_extra's keys
+           added: a component-library brief's own stats, or a
+           reference-app brief's notes alone (another scope type takes
+           none, and a key the stats helper wrote is refused). It stamps
+           generation_date (UTC, to the second), reads tool_versions.skf
+           under --skf-root (the installed module) as
+           skf-render-quick-metadata.py does (package.json's version, else
+           the VERSION file's first line, else "unknown", with a warning),
+           and writes skill_type "single", spec_version "1.3",
+           generated_by "create-skill", dependencies [] and compatibility
+           "". The inventory is not changed.
 
   rules    --inventory <file> --language <language> --target <file>
            Write extraction-rules.yaml (the skill, its language, tier and
@@ -105,7 +192,9 @@ Subcommands:
            --target. The inventory is not changed.
 
   summary  --inventory <file>
-           Print the inventory's counts without changing it.
+           Print the inventory's counts without changing it, and in
+           `not_public` each export marked `public: false` ({name, file}),
+           which the evidence report lists.
 
 Inventory shape (the keys this helper reads or writes):
 
@@ -120,49 +209,69 @@ Inventory shape (the keys this helper reads or writes):
     "co_imports": [...], "promoted_docs": [...],
     "authoritative_files_scan": {...} | null,
     "extraction_rules": {"recipe_set", "recipes", "scope", "ast_grep_version"},
+    "public_surface": {"by_language": {...}, "public": [...],
+                       "other_definitions": [...],
+                       "extraction_gaps": [...]} | null,
     "t2_annotations": [...], "t3_items": [...], "warnings": ["..."]
   }
 
-Output (stdout, exit 0), for every subcommand but rules and provenance:
+An export may carry `internal: true` (the runner's entry_point_diff.internal
+lists it) and `public: true` or `public: false` (see init's Public surface).
+
+Output (stdout, exit 0), for every subcommand but rules, provenance and
+metadata:
 
   {
     "status": "ok",
     "inventory": "<path, / separators>",
     "extraction_mode": "...",
-    "counts": {"files_scanned": N | null, "exports": N, "t1": N,
-               "t1_low": N, "by_type": {"<export_type>": N, ...},
+    "counts": {"files_scanned": N | null, "exports": N, "not_public": N,
+               "t1": N, "t1_low": N, "by_type": {"<export_type>": N, ...},
                "top_exports": N, "co_imports": N, "scripts": N,
                "assets": N, "t2_annotations": N, "t2_past": N,
                "t2_future": N, "functions_enriched": N, "t3_items": N,
                "items": N},
     "added": N, "duplicates": N, "dropped": ["name"],   # add
     "patched": N, "unmatched": [...], "ambiguous": [...],  # patch
-    "set": ["key", ...]                                 # set
+    "set": ["key", ...], "dropped": ["name"],           # set
+    "not_public": [{"name", "file"}, ...]               # summary
   }
 
-`items` is exports plus t3_items: what compile can document. t1 and t1_low
-count the exports by their `confidence`, by_type by their `export_type`.
+not_public counts the exports marked `public: false`, which the provenance
+map leaves out: when it equals `exports`, the map holds no export. `items`
+is exports plus t3_items, less not_public: what compile can document. t1
+and t1_low count the exports by their `confidence`, by_type by their
+`export_type`.
 t2_past and t2_future count the T2 annotations by their `temporal`, and
-functions_enriched the distinct export_name values among them. rules
+functions_enriched the distinct export_name values among them; an
+annotation of a name every export of which is marked `public: false`
+counts in none of t2_annotations, t2_past, t2_future and
+functions_enriched. rules
 prints {"status": "ok", "target": "<path>", "bytes": N}, provenance
 {"status": "ok", "target": "<path>", "entries": N, "unsigned": ["name
 (file)", ...]}, and provenance --add-entries {"status": "ok", "target":
-"<path>", "entries": N, "file_entries": N, "added": N, "duplicates": N},
-the counts of the map after the merge.
+"<path>", "entries": N, "file_entries": N, "added": N, "duplicates": N,
+"not_public": [{"name", "file"}, ...]}, the counts of the map after the
+merge, and metadata {"status": "ok", "target": "<path>", "exports": N,
+"commit_short": "<source_commit's first 8 characters, or unknown>",
+"tool_versions": {...}, "warnings": [...]}.
 
 Exit codes:
   0  success
   1  input error, nothing changed: an inventory that is missing, not JSON
-     or has no exports list, an --extraction or --detected file that
-     cannot be read, a provenance map at --target that --add-entries
-     cannot read, a stdin payload of the wrong shape, an unknown key or a
-     kept file the inventory does not list, or a write that failed
+     or has no exports list, an --extraction, --detected, --brief or
+     --stats file that cannot be read, a provenance map at --target that
+     --add-entries cannot read, a staged SKILL.md with no frontmatter
+     description, a stdin payload of the wrong shape, an exports entry
+     whose source_file is absolute, an unknown key or a kept file the
+     inventory does not list, or a write that failed
   2  usage error (argparse)
 """
 
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import json
 import os
 import re
@@ -219,9 +328,27 @@ def _read_json(path: Path, label: str):
         raise InventoryError(f"cannot read the {label} {path.as_posix()}: {exc}") from exc
 
 
+def _off_surface_names(data: dict) -> set[str]:
+    """The export names every inventory export of which is marked `public: false`."""
+    marks: dict[str, bool] = {}
+    for export in data.get("exports") or []:
+        if isinstance(export, dict) and isinstance(export.get("export_name"), str):
+            name = export["export_name"]
+            marks[name] = marks.get(name, True) and export.get("public") is False
+    return {name for name, off in marks.items() if off}
+
+
+def _not_public(data: dict) -> list[dict]:
+    """{name, file} of each export marked `public: false`, in the inventory's order."""
+    return [{"name": e.get("export_name"), "file": e.get("source_file")} for e in data.get("exports") or []
+            if isinstance(e, dict) and e.get("public") is False]
+
+
 def counts(data: dict) -> dict:
     exports = [e for e in data["exports"] if isinstance(e, dict)]
-    notes = [n for n in data.get("t2_annotations") or [] if isinstance(n, dict)]
+    off = _off_surface_names(data)
+    raw_notes = [n for n in data.get("t2_annotations") or [] if isinstance(n, dict)]
+    notes = [n for n in raw_notes if not (isinstance(n.get("export_name"), str) and n["export_name"] in off)]
 
     def _length(key: str) -> int:
         value = data.get(key)
@@ -233,9 +360,11 @@ def counts(data: dict) -> dict:
         if isinstance(kind, str) and kind:
             by_type[kind] = by_type.get(kind, 0) + 1
     files = data.get("files_scanned")
+    not_public = sum(1 for e in exports if e.get("public") is False)
     return {
         "files_scanned": files if isinstance(files, int) else None,
         "exports": len(data["exports"]),
+        "not_public": not_public,
         "t1": sum(1 for e in exports if e.get("confidence") == "T1"),
         "t1_low": sum(1 for e in exports if e.get("confidence") == "T1-low"),
         "by_type": dict(sorted(by_type.items())),
@@ -243,12 +372,12 @@ def counts(data: dict) -> dict:
         "co_imports": _length("co_imports"),
         "scripts": _length("scripts_inventory"),
         "assets": _length("assets_inventory"),
-        "t2_annotations": _length("t2_annotations"),
+        "t2_annotations": _length("t2_annotations") - (len(raw_notes) - len(notes)),
         "t2_past": sum(1 for n in notes if n.get("temporal") == "T2-past"),
         "t2_future": sum(1 for n in notes if n.get("temporal") == "T2-future"),
         "functions_enriched": len({n["export_name"] for n in notes if isinstance(n.get("export_name"), str)}),
         "t3_items": _length("t3_items"),
-        "items": len(data["exports"]) + _length("t3_items"),
+        "items": len(data["exports"]) - not_public + _length("t3_items"),
     }
 
 
@@ -264,7 +393,7 @@ def runner_warnings(extraction: dict) -> list[str]:
     for error in extraction.get("errors") or []:
         if isinstance(error, dict):
             lines.append(f"ast-grep did not finish on {error.get('files')} files from `{error.get('first_file')}` "
-                         f"({error.get('detail')}): exports in them may be missing")
+                         f"({error.get('detail')}): their exports are read by eye")
     for issue in extraction.get("file_issues") or []:
         if isinstance(issue, dict):
             lines.append(f"`{issue.get('file')}` ({issue.get('issue')}): its exports are read by eye")
@@ -276,13 +405,180 @@ def runner_warnings(extraction: dict) -> list[str]:
     return lines
 
 
+# --------------------------------------------------------------------------
+# The public surface of a public-api skill (see init's "Public surface"):
+# one rule, which skf-build-change-manifest.py loads from here for update-skill
+# --------------------------------------------------------------------------
+
+
+def _norm_path(path: object) -> str | None:
+    """A file path compared as structural-diff compares it: `/` separators, no leading `./`."""
+    if not isinstance(path, str) or not path.strip():
+        return None
+    text = path.strip().replace("\\", "/")
+    while text.startswith("./"):
+        text = text[2:]
+    return text
+
+
+def _relative_source(entry: dict) -> bool:
+    """Write an exports entry's source_file in _norm_path's form, the runner's; False for an absolute one."""
+    path = _norm_path(entry.get("source_file"))
+    if path is None:
+        return True
+    if path.startswith("/") or re.match(r"[A-Za-z]:/", path):
+        return False
+    entry["source_file"] = path
+    return True
+
+
+PUBLIC_API = "public-api"
+# A record's language family, the one whose entry points declare its names: skf-extract-public-api.py's FAMILY_OF,
+# by the record's `language`, else by its file's extension (that script's EXTENSION_LANGUAGES).
+_FAMILY_OF_LANGUAGE = {"python": "python", "typescript": "javascript", "tsx": "javascript",
+                       "javascript": "javascript", "vue": "javascript", "rust": "rust", "go": "go"}
+_FAMILY_OF_EXTENSION = {".py": "python", ".pyi": "python", ".rs": "rust", ".go": "go",
+                        **dict.fromkeys((".ts", ".mts", ".cts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".vue"),
+                                        "javascript")}
+
+
+class _PublicSurface:
+    """The public surface of a public-api skill's extraction (see init's "Public surface" in the module
+    docstring)."""
+
+    def __init__(self, diff: dict, statuses: dict):
+        self.barrels = {family for family, status in statuses.items() if status == "barrel"}
+        self.pairs: set[tuple[str, str]] = set()
+        self.unfiled: set[tuple[object, str]] = set()  # (family, name) of a public name no file defines
+        for key in ("public", "other_definitions", "extraction_gaps"):
+            for item in diff.get(key) or []:
+                if not isinstance(item, dict) or not isinstance(item.get("name"), str) or not item["name"]:
+                    continue
+                family = item.get("language")
+                members = item.get("members") if key == "public" and item.get("via") == "namespace" else None
+                if isinstance(members, list):
+                    # a namespace whose module the runner read: its members, in place of the module itself
+                    for member in members:
+                        if isinstance(member, dict) and isinstance(member.get("name"), str) and member["name"]:
+                            self._add(family, member["name"], member.get("local"), member.get("file"), True)
+                    continue
+                self._add(family, item["name"], item.get("local") if key != "extraction_gaps" else None,
+                          item.get("file"), key == "public")
+
+    def _add(self, family: object, name: str, local: object, path: object, listed_public: bool) -> None:
+        """The pairs one public name (or gap) gives: (name, file) and (local, file), or, with no file, its
+        (family, name) when `public` lists it."""
+        file = _norm_path(path)
+        if not file:
+            if listed_public:
+                self.unfiled.add((family, name))
+            return
+        self.pairs.update((n, file) for n in (name, local) if isinstance(n, str) and n)
+
+    def public(self, name: str, path: str, language: object = None) -> bool | None:
+        """Whether the export is on the public surface; None (no mark) when its family's entry points are no
+        barrel."""
+        family = _FAMILY_OF_LANGUAGE.get(language) if isinstance(language, str) else None
+        if family is None:
+            family = _FAMILY_OF_EXTENSION.get(os.path.splitext(path)[1].lower())
+        if family not in self.barrels:
+            return None
+        return (name, path) in self.pairs or (family, name) in self.unfiled
+
+
+def public_surface(extraction: object) -> tuple[_PublicSurface | None, str | None]:
+    """(the public surface, None) of the recipe runner's output when its scope type is public-api; (None, why the
+    surface cannot be read from it) for a public-api run with no entry-point diff, an incomplete one, one with
+    errors or one whose entry points name a module the trace could not follow; (None, None) for any other scope
+    type. With no surface every export is kept, as before."""
+    if not isinstance(extraction, dict):
+        return None, None
+    scope, diff, points = extraction.get("scope"), extraction.get("entry_point_diff"), extraction.get("entry_points")
+    kind = scope.get("type") if isinstance(scope, dict) else None
+    if not (isinstance(kind, str) and kind.strip().lower() == PUBLIC_API):
+        return None, None
+    statuses = points.get("by_language") if isinstance(points, dict) else None
+    if not isinstance(diff, dict) or not isinstance(statuses, dict):
+        return None, "the recipe runner gave no entry-point diff (Quick tier, or a run that could not read the tree)"
+    if extraction.get("status") == "incomplete" or extraction.get("errors"):
+        return None, "the recipe runner's run is incomplete"
+    if points.get("unresolved"):
+        return None, "an entry point names a module the runner could not trace (entry_points.unresolved)"
+    return _PublicSurface(diff, statuses), None
+
+
+# The fields of an entry_point_diff item the rule reads, which the inventory's public_surface keeps for `add`, and
+# those of each member of a namespace item.
+SURFACE_FIELDS = {"public": ("name", "language", "file", "local", "via", "members"),
+                  "other_definitions": ("name", "language", "file", "local"),
+                  "extraction_gaps": ("name", "language", "file")}
+MEMBER_FIELDS = ("name", "local", "file")
+NOT_PUBLIC_NAMED = 10  # the names the not-public warning spells out, as update-skill's apply does
+NOT_PUBLIC_LEAD = "Off the public surface: "
+
+
+def _surface_state(extraction: dict) -> dict:
+    """The parts of the runner's JSON the rule reads (public_surface found a surface in it)."""
+    diff = extraction["entry_point_diff"]
+    state: dict = {"by_language": dict(extraction["entry_points"]["by_language"])}
+    for key, fields in SURFACE_FIELDS.items():
+        state[key] = [{field: item[field] for field in fields if field in item}
+                      for item in diff.get(key) or [] if isinstance(item, dict)]
+    for item in state["public"]:
+        if isinstance(item.get("members"), list):
+            item["members"] = [{field: m[field] for field in MEMBER_FIELDS if field in m}
+                               for m in item["members"] if isinstance(m, dict)]
+    return state
+
+
+def _stored_surface(data: dict) -> _PublicSurface | None:
+    """The public surface the inventory's public_surface keeps, or None when init kept none."""
+    state = data.get("public_surface")
+    if not isinstance(state, dict) or not isinstance(state.get("by_language"), dict):
+        return None
+    return _PublicSurface(state, state["by_language"])
+
+
+def _mark(surface: _PublicSurface | None, export: dict) -> None:
+    """Set the export's `public` mark by the rule; no other `public` value is kept."""
+    export.pop("public", None)
+    name, path = export.get("export_name"), _norm_path(export.get("source_file"))
+    if surface is None or not isinstance(name, str) or not name or path is None:
+        return
+    mark = surface.public(name, path, export.get("language"))
+    if mark is not None:
+        export["public"] = mark
+
+
+def _not_public_warning(names: list[str]) -> str:
+    """The one warning naming the exports marked `public: false` (`name (file)`), for Gate 2 and the evidence
+    report."""
+    shown = ", ".join(names[:NOT_PUBLIC_NAMED])
+    more = f" and {len(names) - NOT_PUBLIC_NAMED} more" if len(names) > NOT_PUBLIC_NAMED else ""
+    return (f"{NOT_PUBLIC_LEAD}{len(names)} export(s) of this public-api skill are left out of the provenance map, "
+            f"SKILL.md, references/, the context snippet and metadata.json's exports[] (each is marked "
+            f"`public: false` in the inventory, and `summary` lists them all): {shown}{more}")
+
+
+def _write_not_public_warning(data: dict) -> None:
+    """Write the not-public warning in place of the one an earlier call wrote (else at the end), or drop it when
+    no export is marked `public: false`."""
+    names = [f"{item['name']} ({item['file']})" for item in _not_public(data)]
+    warnings = data.setdefault("warnings", [])
+    at = next((i for i, w in enumerate(warnings) if isinstance(w, str) and w.startswith(NOT_PUBLIC_LEAD)), None)
+    if at is not None:
+        del warnings[at]
+    if names:
+        warnings.insert(len(warnings) if at is None else at, _not_public_warning(names))
+
+
 def init(skill: str, mode: str, tier: str, extraction: dict | None = None, detected: dict | None = None) -> dict:
     """A new inventory, seeded from the runner's JSON and the detector's JSON."""
     data: dict = {
         "skill_name": skill, "extraction_mode": mode, "tier": tier, "files_scanned": None,
         "exports": [], "top_exports": [], "aggregates": {}, "counts": {}, "arms": {},
         "scripts_inventory": [], "assets_inventory": [], "intent_mapping": {}, "co_imports": [],
-        "promoted_docs": [], "authoritative_files_scan": None, "extraction_rules": {},
+        "promoted_docs": [], "authoritative_files_scan": None, "extraction_rules": {}, "public_surface": None,
         "t2_annotations": [], "t3_items": [], "warnings": [],
     }
     if extraction is not None:
@@ -291,6 +587,7 @@ def init(skill: str, mode: str, tier: str, extraction: dict | None = None, detec
         diff = extraction.get("entry_point_diff")
         internal = {(i.get("name"), i.get("source_file"))
                     for i in (diff.get("internal") or [] if isinstance(diff, dict) else []) if isinstance(i, dict)}
+        surface, problem = public_surface(extraction)
         for record in extraction.get("exports") or []:
             if not isinstance(record, dict):
                 continue
@@ -299,6 +596,7 @@ def init(skill: str, mode: str, tier: str, extraction: dict | None = None, detec
             export.setdefault("extraction_method", "ast-grep")
             if (export.get("export_name"), export.get("source_file")) in internal:
                 export["internal"] = True
+            _mark(surface, export)
             data["exports"].append(export)
         files = extraction.get("files_in_scope")
         data["files_scanned"] = files if isinstance(files, int) else None
@@ -313,6 +611,12 @@ def init(skill: str, mode: str, tier: str, extraction: dict | None = None, detec
             "ast_grep_version": ast_grep.get("version") if isinstance(ast_grep, dict) else None,
         }
         data["warnings"] = runner_warnings(extraction)
+        if problem:
+            data["warnings"].append(f"The public surface of this public-api skill could not be applied ({problem}): "
+                                    "no export is marked `public: false`, so every export found is documented")
+        if surface is not None:
+            data["public_surface"] = _surface_state(extraction)
+            _write_not_public_warning(data)
     if detected is not None:
         if not isinstance(detected, dict):
             raise InventoryError("the --detected file is not a JSON object")
@@ -335,10 +639,20 @@ def add(data: dict, field: str, entries: list) -> tuple[int, int, list[str]]:
     kind = str if field == "warnings" else dict
     if not isinstance(entries, list) or not all(isinstance(e, kind) for e in entries):
         raise InventoryError(f"stdin must hold a JSON list of {'strings' if kind is str else 'objects'}")
+    surface = _stored_surface(data) if field == "exports" else None
     if field == "exports":
         if not all(isinstance(e.get("export_name"), str) and e["export_name"] for e in entries):
             raise InventoryError("every exports entry needs an export_name")
         entries = [{**BY_EYE_DEFAULTS, **e} for e in entries]
+        absolute = [e for e in entries if not _relative_source(e)]
+        if absolute:
+            sent = ", ".join(f"{e['export_name']}: source_file {e['source_file']}" for e in absolute[:10])
+            sent += f" and {len(absolute) - 10} more" if len(absolute) > 10 else ""
+            verb, them = ("is", "it") if len(absolute) == 1 else ("are", "them")
+            raise InventoryError(f"{sent} {verb} absolute; send {them} relative to the source root, with / "
+                                 "separators, as the runner writes its files")
+        for entry in entries:
+            _mark(surface, entry)
     target = data.setdefault(field, [])
     known = {e.get("export_name") for e in data["exports"] if isinstance(e, dict)} - {None}
     added = duplicates = 0
@@ -348,8 +662,8 @@ def add(data: dict, field: str, entries: list) -> tuple[int, int, list[str]]:
             dropped.append(entry["export_name"])
             continue
         if field == "exports":
-            key = (entry["export_name"], entry.get("source_file"))
-            repeat = any(isinstance(e, dict) and (e.get("export_name"), e.get("source_file")) == key
+            key = (entry["export_name"], _norm_path(entry.get("source_file")))
+            repeat = any(isinstance(e, dict) and (e.get("export_name"), _norm_path(e.get("source_file"))) == key
                          for e in target)
         else:
             repeat = any(_same(entry, e) for e in target)
@@ -358,6 +672,8 @@ def add(data: dict, field: str, entries: list) -> tuple[int, int, list[str]]:
             continue
         target.append(entry)
         added += 1
+    if surface is not None:
+        _write_not_public_warning(data)
     return added, duplicates, dropped
 
 
@@ -378,7 +694,7 @@ def patch(data: dict, entries: list) -> tuple[int, list[str], list[str]]:
     for entry in entries:
         name, source = entry["export_name"], entry.get("source_file")
         found = [e for e in data["exports"] if isinstance(e, dict) and e.get("export_name") == name
-                 and (source is None or e.get("source_file") == source)]
+                 and (source is None or _norm_path(e.get("source_file")) == _norm_path(source))]
         label = name if source is None else f"{name} ({source})"
         if not found:
             unmatched.append(label)
@@ -390,8 +706,9 @@ def patch(data: dict, entries: list) -> tuple[int, list[str], list[str]]:
     return patched, unmatched, ambiguous
 
 
-def set_fields(data: dict, values: dict) -> list[str]:
-    """Set the keys of `values` on the inventory (see the module docstring); return the keys set."""
+def set_fields(data: dict, values: dict) -> tuple[list[str], list[str]]:
+    """Set the keys of `values` on the inventory (see the module docstring); return (the keys set, the top_exports
+    names dropped as off the public surface)."""
     if not isinstance(values, dict):
         raise InventoryError("stdin must hold a JSON object")
     unknown = sorted(set(values) - set(SETTABLE))
@@ -403,6 +720,11 @@ def set_fields(data: dict, values: dict) -> list[str]:
             names = " or ".join("null" if t is type(None) else t.__name__ for t in types)
             raise InventoryError(f"{key} must be {names}")
     mapping = _intent_mapping(data, values["intent_mapping"]) if "intent_mapping" in values else {}
+    dropped: list[str] = []
+    if "top_exports" in values:
+        off = _off_surface_names(data)
+        dropped = [n for n in values["top_exports"] if isinstance(n, str) and n in off]
+        values = {**values, "top_exports": [n for n in values["top_exports"] if not (isinstance(n, str) and n in off)]}
     for key, value in values.items():
         if key == "intent_mapping":
             data["intent_mapping"] = {**(data.get("intent_mapping") or {}), **mapping}
@@ -410,7 +732,7 @@ def set_fields(data: dict, values: dict) -> list[str]:
             data[key] = {**(data.get(key) if isinstance(data.get(key), dict) else {}), **value}
         else:
             data[key] = value
-    return list(values)
+    return list(values), dropped
 
 
 def _intent_mapping(data: dict, mapping: dict) -> dict:
@@ -488,11 +810,12 @@ def _labels(export: dict) -> dict:
 
 
 def provenance_entries(data: dict) -> tuple[list[dict], list[str]]:
-    """(the provenance map entry of every export, the functions among them with no params)."""
+    """(the provenance map entry of every export but one marked `public: false`, the functions among them with no
+    params)."""
     entries: list[dict] = []
     unsigned: list[str] = []
     for export in data.get("exports") or []:
-        if not isinstance(export, dict):
+        if not isinstance(export, dict) or export.get("public") is False:
             continue
         raw = export.get("params")
         params = None
@@ -512,6 +835,11 @@ def provenance_entries(data: dict) -> tuple[list[dict], list[str]]:
     return entries, unsigned
 
 
+def _utc_now() -> str:
+    """Now, in UTC, to the second (ISO-8601)."""
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
 def map_header(data: dict, given) -> dict:
     """The provenance map's header: stdin's keys over the defaults."""
     if not isinstance(given, dict):
@@ -522,8 +850,7 @@ def map_header(data: dict, given) -> dict:
     missing = [key for key, default in MAP_HEADER.items() if default is REQUIRED and key not in given]
     if missing:
         raise InventoryError(f"the map's header needs {', '.join(missing)} (null when unknown)")
-    defaults = {"skill_name": data.get("skill_name"),
-                "generated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())}
+    defaults = {"skill_name": data.get("skill_name"), "generated_at": _utc_now()}
     return {key: given[key] if key in given else defaults.get(key, default) for key, default in MAP_HEADER.items()}
 
 
@@ -533,12 +860,15 @@ def provenance_map(data: dict, header) -> tuple[dict, list[str]]:
     return {**map_header(data, header), "entries": entries}, unsigned
 
 
-def add_map_entries(provenance: dict, payload) -> tuple[int, int]:
-    """Append stdin's `entries` and `file_entries` to the map; return (added, duplicates)."""
+def add_map_entries(provenance: dict, payload, off: frozenset = frozenset()) -> tuple[int, int, list[dict]]:
+    """Append stdin's `entries` and `file_entries` to the map; return (added, duplicates, {name, file} of each entry
+    not added because `off`, the (export_name, source_file) of the inventory's exports marked `public: false`,
+    holds it)."""
     if not isinstance(payload, dict) or not payload or set(payload) - {"entries", "file_entries"}:
         raise InventoryError('stdin must hold {"entries": [...], "file_entries": [...]} (either list, or both)')
     keys = {"entries": ("export_name", "source_file"), "file_entries": ("file_name",)}
     added = duplicates = 0
+    not_public: list[dict] = []
     for field, items in payload.items():
         if not isinstance(items, list) or not all(isinstance(e, dict) for e in items):
             raise InventoryError(f"{field} must be a list of objects")
@@ -551,13 +881,197 @@ def add_map_entries(provenance: dict, payload) -> tuple[int, int]:
         held = {tuple(e.get(k) for k in keys[field]) for e in target if isinstance(e, dict)}
         for item in items:
             key = tuple(item.get(k) for k in keys[field])
+            if field == "entries" and (item.get("export_name"), _norm_path(item.get("source_file"))) in off:
+                not_public.append({"name": item.get("export_name"), "file": item.get("source_file")})
+                continue
             if key in held:
                 duplicates += 1
                 continue
             held.add(key)
             target.append(item)
             added += 1
-    return added, duplicates
+    return added, duplicates, not_public
+
+
+_SIBLINGS: dict = {}
+
+
+def _sibling(filename: str):
+    """A helper installed beside this script, loaded once as a module: skf-resolve-authoritative-files.py (the
+    brief's YAML), skf-render-quick-metadata.py (the installed SKF's version) and skf-description-guard.py (the
+    staged SKILL.md's description)."""
+    if filename not in _SIBLINGS:
+        path = Path(__file__).resolve().parent / filename
+        spec = importlib.util.spec_from_file_location("skf_" + filename[4:-3].replace("-", "_"), path)
+        if spec is None or spec.loader is None:
+            raise InventoryError(f"cannot load {filename} beside {Path(__file__).name}")
+        module = importlib.util.module_from_spec(spec)
+        try:
+            spec.loader.exec_module(module)
+        except ImportError as exc:
+            raise InventoryError(f"cannot load {filename} ({exc}): run this helper with `uv run`") from exc
+        except (OSError, SyntaxError) as exc:
+            raise InventoryError(f"cannot load {filename} beside {Path(__file__).name}: {exc}") from exc
+        _SIBLINGS[filename] = module
+    return _SIBLINGS[filename]
+
+
+def read_brief(path: Path) -> dict:
+    """The skill brief, a YAML mapping."""
+    module = _sibling("skf-resolve-authoritative-files.py")
+    try:
+        brief = module.parse_brief_yaml(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError) as exc:
+        raise InventoryError(f"cannot read the brief {path.as_posix()}: {exc}") from exc
+    except module.yaml.YAMLError as exc:
+        raise InventoryError(f"the brief {path.as_posix()} is not valid YAML: {exc}") from exc
+    if not isinstance(brief, dict):
+        raise InventoryError(f"the brief {path.as_posix()} is not a YAML mapping")
+    return brief
+
+
+# metadata: the stdin keys, each with the JSON types it takes; METADATA_REQUIRED have no default.
+METADATA_INPUT = {
+    "version": (str,), "language": (str,),
+    "source_root": (str, type(None)), "source_commit": (str, type(None)), "source_ref": (str, type(None)),
+    "qmd_version": (str, type(None)), "ast_grep_version": (str, type(None)), "stats_extra": (dict,),
+}
+METADATA_REQUIRED = ("version", "language", "source_root", "source_commit", "source_ref", "qmd_version")
+NON_EMPTY = ("version", "language")
+REFERENCE_APP = "reference-app"
+COMPONENT_LIBRARY = "component-library"
+
+
+def _metadata_input(given) -> dict:
+    """stdin's fields, checked, with the defaults of the optional ones."""
+    if not isinstance(given, dict):
+        raise InventoryError("stdin must hold a JSON object with " + ", ".join(METADATA_REQUIRED))
+    unknown = sorted(set(given) - set(METADATA_INPUT))
+    if unknown:
+        raise InventoryError(f"metadata takes only {', '.join(METADATA_INPUT)}; not {', '.join(unknown)}")
+    missing = [key for key in METADATA_REQUIRED if key not in given]
+    if missing:
+        raise InventoryError(f"metadata needs {', '.join(missing)} (null when unknown, but for "
+                             f"{', '.join(NON_EMPTY)})")
+    for key, value in given.items():
+        if not isinstance(value, METADATA_INPUT[key]) or (key in NON_EMPTY and not value.strip()):
+            names = " or ".join("null" if t is type(None) else t.__name__ for t in METADATA_INPUT[key])
+            raise InventoryError(f"{key} must be {'a non-empty ' if key in NON_EMPTY else ''}{names}")
+    return {"ast_grep_version": None, "stats_extra": {}, **given}
+
+
+def read_description(skill_md: Path) -> str:
+    """The `description` of the staged SKILL.md's frontmatter, which compile §2a wrote."""
+    module = _sibling("skf-description-guard.py")
+    try:
+        description, _hash = module.read_description(skill_md)
+    except (OSError, UnicodeDecodeError, ValueError) as exc:
+        raise InventoryError(f"cannot read the description of the staged SKILL.md: {exc} (write SKILL.md, "
+                             "compile §2, before metadata.json)") from exc
+    if not description.strip():
+        raise InventoryError(f"the description of {skill_md.as_posix()} is empty")
+    return description
+
+
+def metadata_exports(data: dict, scope_type: object) -> list[str]:
+    """metadata.json's exports[]: the names of the inventory's exports but one marked internal or not public, each
+    once (a docs-only inventory's t3_items names; none for a reference app)."""
+    if scope_type == REFERENCE_APP:
+        return []
+    if data.get("extraction_mode") == "docs-only":
+        items = [i for i in data.get("t3_items") or [] if isinstance(i, dict)]
+    else:
+        items = [e for e in data["exports"] if isinstance(e, dict) and e.get("internal") is not True
+                 and e.get("public") is not False]
+    names = (i.get("export_name") for i in items)
+    return list(dict.fromkeys(n for n in names if isinstance(n, str) and n))
+
+
+def _file_rows(entries: object, folder: str) -> list[dict]:
+    """The scripts[] or assets[] rows of a scripts_inventory or assets_inventory."""
+    rows = []
+    for entry in entries if isinstance(entries, list) else []:
+        if not isinstance(entry, dict):
+            continue
+        source = entry.get("source_file")
+        name = entry.get("name") or (Path(str(source)).name if source else None)
+        rows.append({"file": f"{folder}/{name}", "purpose": entry.get("purpose") or "", "source_file": source,
+                     "confidence": entry.get("confidence") or "T1-low"})
+    return rows
+
+
+def _ast_grep_run(data: dict, given_version: str | None) -> tuple[str | None, int | None, list[str]]:
+    """(tool_versions.ast_grep, ast_node_count, warnings): the runner's version and match count when it ran
+    ast-grep, else the number of exports labeled ast-grep (the recipes run without the runner) and the version
+    stdin gave, else (None, None) when ast-grep did not run."""
+    rules = data.get("extraction_rules") if isinstance(data.get("extraction_rules"), dict) else {}
+    version = rules.get("ast_grep_version")
+    if isinstance(version, str) and version:
+        aggregates = data.get("aggregates") if isinstance(data.get("aggregates"), dict) else {}
+        matched = aggregates.get("exports")
+        return version, matched if isinstance(matched, int) and not isinstance(matched, bool) else None, []
+    matched = sum(1 for e in data["exports"] if isinstance(e, dict) and e.get("extraction_method") == "ast-grep")
+    if not matched:
+        return None, None, []
+    if given_version and given_version.strip():
+        return given_version.strip(), matched, []
+    return "unknown", matched, [f"tool_versions.ast_grep is unknown: ast-grep matched {matched} exports without "
+                                "the recipe runner, and stdin gave no ast_grep_version"]
+
+
+def build_metadata(data: dict, brief: dict, stats: object, given, skf_version: str,
+                   description: str) -> tuple[dict, list[str]]:
+    """(the skill's metadata.json, its warnings) (see `metadata` in the module docstring)."""
+    fields = _metadata_input(given)
+    if not isinstance(stats, dict) or not isinstance(stats.get("stats"), dict) \
+            or not isinstance(stats.get("confidence_distribution"), dict):
+        raise InventoryError("the --stats file must hold the stats helper's JSON: a stats and a "
+                             "confidence_distribution object")
+    clash = sorted(set(fields["stats_extra"]) & set(stats["stats"]))
+    if clash:
+        raise InventoryError(f"stats_extra may not set {', '.join(clash)}: the stats helper writes it")
+    scope = brief.get("scope") if isinstance(brief.get("scope"), dict) else {}
+    scope_type = scope.get("type")
+    if not isinstance(scope_type, str) or not scope_type:
+        raise InventoryError("the brief has no scope.type, which metadata.json records as scope_type")
+    extra = sorted(fields["stats_extra"])
+    if scope_type == REFERENCE_APP and set(extra) - {"notes"}:
+        raise InventoryError(f"a reference app's stats_extra holds only notes, not {', '.join(extra)}: the stats "
+                             "helper writes pattern_surfaces_documented")
+    if extra and scope_type not in (REFERENCE_APP, COMPONENT_LIBRARY):
+        raise InventoryError(f"a {scope_type} skill takes no stats_extra (only a component library or a "
+                             "reference app adds stats)")
+    ast_grep, node_count, warnings = _ast_grep_run(data, fields["ast_grep_version"])
+    metadata = {
+        "name": brief.get("name") or data.get("skill_name"),
+        "version": fields["version"],
+        "skill_type": "single",
+        "scope_type": scope_type,
+        "source_authority": brief.get("source_authority") or "community",
+        "source_repo": brief.get("source_repo"),
+        "source_root": fields["source_root"],
+        "source_commit": fields["source_commit"],
+        "source_ref": fields["source_ref"],
+        "confidence_tier": data.get("tier"),
+        "spec_version": "1.3",
+        "generation_date": _utc_now(),
+        "description": description,
+        "language": fields["language"],
+    }
+    if node_count is not None:
+        metadata["ast_node_count"] = node_count
+    metadata["exports"] = metadata_exports(data, scope_type)
+    metadata["tool_versions"] = {"ast_grep": ast_grep, "qmd": fields["qmd_version"], "skf": skf_version}
+    metadata["confidence_distribution"] = stats["confidence_distribution"]
+    metadata["stats"] = {**stats["stats"], **fields["stats_extra"]}
+    for key, folder in (("scripts_inventory", "scripts"), ("assets_inventory", "assets")):
+        rows = _file_rows(data.get(key), folder)
+        if rows:
+            metadata[folder] = rows
+    metadata["generated_by"] = "create-skill"
+    metadata["dependencies"] = []
+    metadata["compatibility"] = ""
+    return metadata, warnings
 
 
 def rules_yaml(data: dict, language: str) -> str:
@@ -669,6 +1183,16 @@ def _build_parser() -> argparse.ArgumentParser:
     p_prov.add_argument("--target", required=True, type=Path, help="the provenance-map.json to write")
     p_prov.add_argument("--add-entries", action="store_true",
                         help="append stdin's entries and file_entries to the map at --target instead")
+    p_meta = sub.add_parser("metadata", help="write metadata.json from the inventory, the brief and the stats, "
+                                             "the fields compile decides on stdin")
+    p_meta.add_argument("--inventory", required=True, type=Path, help=inventory_help)
+    p_meta.add_argument("--brief", required=True, type=Path, help="the skill-brief.yaml")
+    p_meta.add_argument("--stats", required=True, type=Path,
+                        help="the JSON skf-render-metadata-stats.py wrote (its -o file)")
+    p_meta.add_argument("--skf-root", required=True, type=Path,
+                        help="the installed SKF module folder ({project-root}/_bmad/skf), for tool_versions.skf")
+    p_meta.add_argument("--target", required=True, type=Path,
+                        help="the metadata.json to write, beside the staged SKILL.md it reads the description of")
     p_summary = sub.add_parser("summary", help="print the inventory's counts")
     p_summary.add_argument("--inventory", required=True, type=Path, help=inventory_help)
     return parser
@@ -685,21 +1209,35 @@ def main(argv: list[str] | None = None) -> int:
             write(path, data)
             result = _result(path, data)
         elif args.command == "provenance" and args.add_entries:
-            load(path)
+            data = load(path)
             provenance = _read_json(args.target, "provenance map")
             if not isinstance(provenance, dict) or not isinstance(provenance.get("entries"), list):
                 raise InventoryError(f"the provenance map {args.target.as_posix()} has no entries list: "
                                      "run provenance without --add-entries first")
-            added, duplicates = add_map_entries(provenance, _stdin_json())
+            off = frozenset((item["name"], _norm_path(item["file"])) for item in _not_public(data))
+            added, duplicates, not_public = add_map_entries(provenance, _stdin_json(), off)
             write(args.target, provenance)
             result = {"status": "ok", "target": args.target.as_posix(), "entries": len(provenance["entries"]),
                       "file_entries": len(provenance.get("file_entries") or []), "added": added,
-                      "duplicates": duplicates}
+                      "duplicates": duplicates, "not_public": not_public}
         elif args.command == "provenance":
             provenance, unsigned = provenance_map(load(path), _stdin_json())
             write(args.target, provenance)
             result = {"status": "ok", "target": args.target.as_posix(), "entries": len(provenance["entries"]),
                       "unsigned": unsigned}
+        elif args.command == "metadata":
+            skf_version = _sibling("skf-render-quick-metadata.py").probe_skf_version(args.skf_root)
+            metadata, warnings = build_metadata(load(path), read_brief(args.brief),
+                                                _read_json(args.stats, "stats JSON"), _stdin_json(), skf_version,
+                                                read_description(args.target.parent / "SKILL.md"))
+            write(args.target, metadata)
+            commit = metadata["source_commit"]
+            if skf_version == "unknown":
+                warnings.append(f"tool_versions.skf is unknown: {args.skf_root.as_posix()} holds no package.json "
+                                "or VERSION file with a version")
+            result = {"status": "ok", "target": args.target.as_posix(), "exports": len(metadata["exports"]),
+                      "commit_short": commit[:8] if commit else "unknown",
+                      "tool_versions": metadata["tool_versions"], "warnings": warnings}
         elif args.command == "rules":
             text = rules_yaml(load(path), args.language)
             write(args.target, text)
@@ -707,7 +1245,7 @@ def main(argv: list[str] | None = None) -> int:
         else:
             data = load(path)
             if args.command == "summary":
-                result = _result(path, data)
+                result = _result(path, data, not_public=_not_public(data))
             elif args.command == "add":
                 payload = _stdin_json()
                 added, duplicates, dropped = add(data, args.field, [] if payload is None else payload)
@@ -720,9 +1258,9 @@ def main(argv: list[str] | None = None) -> int:
                 result = _result(path, data, patched=patched, unmatched=unmatched, ambiguous=ambiguous)
             else:
                 payload = _stdin_json()
-                keys = set_fields(data, {} if payload is None else payload)
+                keys, dropped = set_fields(data, {} if payload is None else payload)
                 write(path, data)
-                result = _result(path, data, set=keys)
+                result = _result(path, data, set=keys, dropped=dropped)
     except InventoryError as exc:
         print(json.dumps({"status": "error", "message": str(exc)}), file=sys.stderr)
         return 1