bmad-module-skill-forge 3.0.0 → 4.0.0

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

@@ -18,7 +18,8 @@ CLI:
   uv run skf-extraction-snapshot.py build --source-root <dir> --tier <tier> \\
       --date <timestamp> [--source-path <recorded root>] \\
       [--provenance-map <map>] [--extraction <runner.json>] \\
-      [--details <by-eye.json>]... -o <extraction-snapshot.json>
+      [--details <by-eye.json>]... [--scope-type <type>] \\
+      -o <extraction-snapshot.json>
   uv run skf-extraction-snapshot.py relocate <extraction-snapshot.json> \\
       --diff <structural-diff.json> --extraction <runner.json>
 
@@ -66,6 +67,24 @@ build
   map gives a library (`source_library_by_file`) carries it as
   `source_library`, which step 3's `--group-by source_library` diff reads.
 
+  Public surface (--scope-type public-api, in any case). Each export of a
+  language family whose entry points are a barrel is marked `public`, true
+  or false, by skf-extraction-inventory.py's public-surface rule
+  (`public_surface` over the runner's JSON, with the scope type this flag
+  gives, and `public(name, file, language)`, the language of the runner's
+  export of that name and file, else the file's extension): the rule
+  create-skill keeps a public-api skill's provenance map to, and
+  update-skill's change manifest too. Every export stays in the snapshot,
+  so a map entry off the surface is never reported removed; step 3's diff
+  lists an export marked false that pairs with no map entry under
+  `not_public[]`, not `added[]`. With no surface the rule can read (no
+  runner JSON, as at Quick tier, a runner that could not run, an
+  incomplete run, one with errors, or an entry point the runner could not
+  trace) nothing is marked, and `public_surface.problem` says why. Any
+  other scope type, and no flag, mark nothing and give `public_surface`
+  null; only --scope-type public-api loads skf-extraction-inventory.py,
+  from beside this script.
+
   Details file: {"files": [paths read by eye], "exports": [export objects]}
   (either key may be absent). Give --details once per file: one per worker.
 
@@ -87,7 +106,8 @@ build
                           "hash-tracked": N, "missing": N,
                           "parse-failed": N, "unread": N},
       "ast_fallback_files": ["<file>", ...],
-      "extraction_gaps": [{"name", "file", "line", "entry"}, ...],
+      "extraction_gaps": [{"name", "file", "line", "entry",
+                           "export_type"?}, ...],
       "truncated": bool,               # a recipe hit the runner's head cap
       "cap_hits": ["<recipe id>", ...],
       "outside_scope": [{"path": "<file>", "names": [...],
@@ -96,7 +116,9 @@ build
                  "t1": N, "t1_low": N},
       "exports": [{"name", "type", "signature", "file", "line",
                    "confidence", "extraction_method", "ast_node_type",
-                   "source_library"?}, ...],
+                   "source_library"?, "public"?}, ...],
+      "public_surface": {"problem": "<why no surface was read>" | null,
+                         "marked_not_public": N} | null,
       "relocations": [{"name", "file", "line"}, ...],   # relocate's
       "warnings": ["..."]
     }
@@ -106,7 +128,27 @@ build
   ["all files (ast-grep unavailable)"], and [] at the Quick tier.
   `extraction_gaps` lists the names a package entry point exports that no
   recipe found (the runner's `entry_point_diff.extraction_gaps`), less the
-  ones an export of the snapshot now holds: read them by eye.
+  ones an export of the snapshot now holds, then, with --provenance-map,
+  the baseline gaps: each entry of the map the snapshot lacks whose file
+  still declares it (the runner leaves out an underscore name such as
+  `__version__`, and a module), which would otherwise read as removed. A
+  baseline gap gives the line that declares the name, `entry` null and,
+  when the entry has one, its `export_type`. It is checked only for an
+  entry whose file is `extracted` or `read-by-eye`, whose name is not
+  dotted, and that the snapshot holds neither under its name nor under
+  its `reexported_as` target at that file. The selection and the
+  declaration are skf-verify-provenance-completeness.py's (`baseline_gaps`,
+  by `declared_line`), loaded from beside this script, the rule
+  update-skill's Category B applies through skf-build-change-manifest.py
+  baseline-gaps: a line at column 0 of a Python or TS/JS file that the
+  definition-line rules match with imports left out (an alias that
+  renames counts; a plain or star import and a re-export never do),
+  and for a `module` or `package` entry the module or package so named
+  (at its line 1). An entry no rule can check (its file neither Python
+  nor TS/JS, a file the lookup does not read, such as a test file or one
+  with a symlink on its path, or a dotted `module` or `package` name) is
+  named in one warning, as `name (file)`. Each name and file is listed
+  once, and each file is read once. Read them by eye.
   `outside_scope` groups the runner's `entry_point_diff.outside_scope` by
   the file that defines each name: public API a package entry point exports
   from a file the skill does not cover, which the drift report lists under
@@ -115,8 +157,8 @@ build
   Prints {"status": "ok", "output", "runner_status", "complete",
   "to_read": [{"file", "status", "issue"}, ...] (the `parse-failed` and
   `unread` files), "extraction_gaps", "ast_fallback_files",
-  "files_by_status", "counts"} on stdout: what step 2 acts on, so it never
-  opens the runner's JSON.
+  "files_by_status", "counts", "public_surface"} on stdout: what step 2
+  acts on, so it never opens the runner's JSON.
 
 relocate
 
@@ -130,9 +172,9 @@ relocate
   "names": [...]}; added 0 changes nothing.
 
 Exit codes: 0 the file was written (or relocate found nothing to add); 2
-an input that cannot be read or parsed, or an output that cannot be
-written ({"status": "error", "error"} on stdout), or a usage error
-(argparse, on stderr).
+an input that cannot be read or parsed, a helper beside this script that
+cannot be loaded, or an output that cannot be written ({"status":
+"error", "error"} on stdout), or a usage error (argparse, on stderr).
 """
 
 from __future__ import annotations
@@ -147,7 +189,11 @@ from pathlib import Path
 STATUSES = ("extracted", "read-by-eye", "hash-tracked", "missing", "parse-failed", "unread")
 TO_READ = ("parse-failed", "unread")
 RUNNER_READ = frozenset({"ok", "incomplete"})
+# The files whose provenance entries a baseline gap checks: the ones read.
+BASELINE_GAP_STATUSES = ("extracted", "read-by-eye")
 AST_GREP_UNAVAILABLE = "all files (ast-grep unavailable)"
+# The scope type whose exports are marked by the public-surface rule.
+PUBLIC_API = "public-api"
 EXIT_ERROR = 2
 
 
@@ -155,24 +201,72 @@ class SnapshotError(Exception):
     """An input or output the helper cannot use (exit 2)."""
 
 
-_PROVENANCE = None
+_SIBLINGS: dict[str, object] = {}
 
 
-def _provenance():
-    """skf-load-provenance.py, installed beside this script, loaded once."""
-    global _PROVENANCE
-    if _PROVENANCE is None:
-        path = Path(__file__).resolve().parent / "skf-load-provenance.py"
-        spec = importlib.util.spec_from_file_location("skf_load_provenance", path)
-        if spec is None or spec.loader is None:
-            raise SnapshotError(f"cannot load skf-load-provenance.py beside {Path(__file__).name}")
-        module = importlib.util.module_from_spec(spec)
+def _sibling(filename: str, *needs: str):
+    """A script installed beside this one, loaded once. Any failure to load
+    it, or a script without each name `needs` lists, is a SnapshotError
+    (exit 2)."""
+    if filename not in _SIBLINGS:
+        path = Path(__file__).resolve().parent / filename
         try:
+            spec = importlib.util.spec_from_file_location(filename[:-3].replace("-", "_"), path)
+            if spec is None or spec.loader is None:
+                raise ImportError(f"no loader for {path}")
+            module = importlib.util.module_from_spec(spec)
             spec.loader.exec_module(module)
-        except (OSError, ImportError, SyntaxError) as exc:
-            raise SnapshotError(f"cannot load skf-load-provenance.py: {exc}") from exc
-        _PROVENANCE = module
-    return _PROVENANCE
+        except Exception as exc:  # whatever the script raises, the build reports it
+            raise SnapshotError(f"cannot load {filename} beside {Path(__file__).name}: {exc}") from exc
+        missing = [need for need in needs if getattr(module, need, None) is None]
+        if missing:
+            raise SnapshotError(f"cannot load {filename} beside {Path(__file__).name}: "
+                                f"it has no {', '.join(missing)}")
+        _SIBLINGS[filename] = module
+    return _SIBLINGS[filename]
+
+
+def _provenance():
+    """skf-load-provenance.py, for the scan list and the libraries (the
+    verifier's `baseline_gaps` reads the re-export map itself)."""
+    return _sibling("skf-load-provenance.py", "bounded_scan_files", "source_library_by_file")
+
+
+def _verifier():
+    """skf-verify-provenance-completeness.py, for its baseline gaps
+    (`baseline_gaps`, by its declaration rule `declared_line`)."""
+    return _sibling("skf-verify-provenance-completeness.py", "baseline_gaps", "declared_line")
+
+
+def _public_api(scope_type: str | None) -> bool:
+    return isinstance(scope_type, str) and scope_type.strip().lower() == PUBLIC_API
+
+
+def _public_surface(runner: dict, scope_type: str):
+    """(surface, problem) by skf-extraction-inventory.py's `public_surface` over the runner's JSON with the scope
+    type --scope-type gives (an empty one when no runner ran, so the rule names its own problem)."""
+    scope = runner.get("scope") if isinstance(runner.get("scope"), dict) else {}
+    extraction = {**runner, "scope": {**scope, "type": scope_type}}
+    return _sibling("skf-extraction-inventory.py", "public_surface").public_surface(extraction)
+
+
+def _mark_public(exports: list[dict], runner: dict, scope_type: str | None) -> dict | None:
+    """Mark each export `public` by the public-surface rule for a public-api scope type; the snapshot's
+    `public_surface` (None for any other scope type)."""
+    if not _public_api(scope_type):
+        return None
+    surface, problem = _public_surface(runner, scope_type)
+    marked_not_public = 0
+    if surface is not None:
+        languages = {(e.get("export_name"), _posix(str(e.get("source_file") or ""))): e.get("language")
+                     for e in runner.get("exports") or [] if isinstance(e, dict)}
+        for record in exports:
+            mark = surface.public(record["name"], record["file"], languages.get((record["name"], record["file"])))
+            if mark is not None:
+                record["public"] = mark
+                if mark is False:
+                    marked_not_public += 1
+    return {"problem": problem, "marked_not_public": marked_not_public}
 
 
 def _posix(path: str) -> str:
@@ -278,20 +372,33 @@ def _outside_scope(runner: dict) -> list[dict]:
 
 
 def _extraction_gaps(runner: dict, exports: list[dict]) -> list[dict]:
-    """The runner's extraction gaps no export of the snapshot holds yet."""
+    """The runner's extraction gaps no export of the snapshot holds yet, one
+    per name and file."""
     held = {(e["name"], e["file"]) for e in exports}
     names = {e["name"] for e in exports}
-    gaps = []
+    gaps: dict[tuple, dict] = {}
     for item in _entry_point_diff(runner).get("extraction_gaps") or []:
         if not isinstance(item, dict) or not isinstance(item.get("name"), str) or not item["name"]:
             continue
         file = _posix(item["file"]) if isinstance(item.get("file"), str) else None
         if (item["name"], file) in held or (file is None and item["name"] in names):
             continue
-        gap = {"name": item["name"], "file": file, "line": item.get("line"), "entry": item.get("entry")}
-        if gap not in gaps:
-            gaps.append(gap)
-    return gaps
+        gaps.setdefault((item["name"], file),
+                        {"name": item["name"], "file": file, "line": item.get("line"), "entry": item.get("entry")})
+    return list(gaps.values())
+
+
+def _baseline_gaps(provenance: dict, source_root: Path, statuses: dict[str, str], exports: list[dict],
+                   listed: set[tuple]) -> tuple[list[dict], list[str]]:
+    """The provenance entries the snapshot lacks whose cited file still
+    declares them, and the entries no rule can check, by the verifier's
+    `baseline_gaps` (the selection and the declaration rule both live
+    there, beside `declared_line`, for update-skill's `baseline-gaps` too):
+    the entries of the files `extracted` or `read-by-eye`, against the
+    snapshot's exports, less the gaps `listed` already holds."""
+    files = {file for file, status in statuses.items() if status in BASELINE_GAP_STATUSES}
+    held = {(e["name"], e["file"]) for e in exports}
+    return _verifier().baseline_gaps(provenance, source_root, held, files, listed)
 
 
 def _ordered(exports) -> list[dict]:
@@ -306,7 +413,8 @@ def _counts(exports: list[dict]) -> dict:
 
 
 def build(source_root: Path, tier: str, date: str, provenance: dict | None, runner: dict | None,
-          details_files: list[str], details_exports: list[dict], root_text: str | None = None) -> dict:
+          details_files: list[str], details_exports: list[dict], root_text: str | None = None,
+          scope_type: str | None = None) -> dict:
     """The snapshot (see the module docstring)."""
     warnings: list[str] = []
     runner = runner or {}
@@ -378,6 +486,7 @@ def build(source_root: Path, tier: str, date: str, provenance: dict | None, runn
                       "fallback": ran and runner_said in TO_READ, "exports": per_file[rel]})
 
     ordered = _ordered(exports.values())
+    surface_state = _mark_public(ordered, runner, scope_type)
     for record in ordered:
         library = libraries.get(record["file"])
         if library is not None:
@@ -389,6 +498,17 @@ def build(source_root: Path, tier: str, date: str, provenance: dict | None, runn
         fallback_files = [f["file"] for f in files if f["fallback"]]
     else:
         fallback_files = [] if tier.strip().lower() == "quick" else [AST_GREP_UNAVAILABLE]
+    gaps = _extraction_gaps(runner, ordered) if ran else []
+    if provenance is not None:
+        baseline, unchecked = _baseline_gaps(provenance, source_root, {f["file"]: f["status"] for f in files},
+                                             ordered, {(g["name"], g["file"]) for g in gaps})
+        gaps += baseline
+        if unchecked:
+            warnings.append(f"{len(unchecked)} map entr{'y' if len(unchecked) == 1 else 'ies'} the snapshot "
+                            f"lacks that no rule can check (in a file neither Python nor TS/JS, a file the "
+                            f"declaration lookup does not read, or a dotted module name), so step 3 may report "
+                            f"{'it' if len(unchecked) == 1 else 'them'} removed: "
+                            + ", ".join(f"{u['name']} ({u['file']})" for u in unchecked))
     return {
         "extraction_date": date,
         "confidence_tier": tier,
@@ -402,12 +522,13 @@ def build(source_root: Path, tier: str, date: str, provenance: dict | None, runn
         "files": files,
         "files_by_status": {status: by_status[status] for status in STATUSES},
         "ast_fallback_files": fallback_files,
-        "extraction_gaps": _extraction_gaps(runner, ordered) if ran else [],
+        "extraction_gaps": gaps,
         "truncated": bool(runner.get("truncated")) or bool(cap_hits),
         "cap_hits": cap_hits,
         "outside_scope": _outside_scope(runner) if ran else [],
         "counts": _counts(ordered),
         "exports": ordered,
+        "public_surface": surface_state,
         "relocations": [],
         "warnings": warnings,
     }
@@ -471,14 +592,15 @@ def _cmd_build(args: argparse.Namespace) -> dict:
         details_files += files
         details_exports += exports
     snapshot = build(root, args.tier, args.date, provenance, runner, details_files, details_exports,
-                     root_text=args.source_path or args.source_root)
+                     root_text=args.source_path or args.source_root, scope_type=args.scope_type)
     _write(Path(args.output), snapshot)
     return {"status": "ok", "output": args.output, "runner_status": snapshot["runner_status"],
             "complete": snapshot["complete"],
             "to_read": [{"file": f["file"], "status": f["status"], "issue": f["issue"]}
                         for f in snapshot["files"] if f["status"] in TO_READ],
             "extraction_gaps": snapshot["extraction_gaps"], "ast_fallback_files": snapshot["ast_fallback_files"],
-            "files_by_status": snapshot["files_by_status"], "counts": snapshot["counts"]}
+            "files_by_status": snapshot["files_by_status"], "counts": snapshot["counts"],
+            "public_surface": snapshot["public_surface"]}
 
 
 def _cmd_relocate(args: argparse.Namespace) -> dict:
@@ -514,6 +636,9 @@ def _build_parser() -> argparse.ArgumentParser:
     snap.add_argument("--extraction", help="the JSON skf-extract-public-api.py --mode full wrote")
     snap.add_argument("--details", action="append",
                       help="the exports read by eye: {\"files\": [...], \"exports\": [...]}; repeat per file")
+    snap.add_argument("--scope-type",
+                      help="the skill's scope type: public-api marks each export `public` by the public-surface "
+                           "rule; any other marks nothing")
     snap.add_argument("-o", "--output", required=True, help="the snapshot to write")
     snap.set_defaults(func=_cmd_build)
     move = sub.add_parser("relocate", help="add the exports the runner found under removed names elsewhere")

package/src/shared/scripts/skf-forge-tier-rw.py

@@ -106,7 +106,9 @@ that cannot be taken, 3 when another call held the registry lock for the
 whole --lock-timeout; nothing was written).
 
 Cross-platform: pure stdlib + PyYAML. Atomic writes via temp + rename
-mirror skf-atomic-write.py's pattern.
+mirror skf-atomic-write.py's pattern. On Windows, which refuses to rename
+over a file another process has open, a refused rename is retried for up
+to 5 seconds before the write fails.
 
 Registry lock: every subcommand that rewrites forge-tier.yaml
 (write-tools, register-qmd-collection, remove-qmd-collection,
@@ -148,6 +150,7 @@ import json
 import math
 import os
 import sys
+import time
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -160,6 +163,16 @@ REGISTRY_LOCK_WAIT_SEC = 30.0
 # A call holds the registry lock for milliseconds; one this old was killed.
 REGISTRY_LOCK_STALE_SEC = 15.0
 EXIT_LOCK_BUSY = 3
+# Windows refuses to replace a file another process has open, even one that
+# only reads its attributes: a call about to take the lock checks the file
+# exists, a `read` call opens it with no lock, and a virus scanner may open a
+# just-written file for a moment. _atomic_write retries the rename there for
+# up to this long before failing.
+# The retry runs while the registry lock is held, so it stays well under
+# REGISTRY_LOCK_STALE_SEC, after which a waiting call takes the lock as stale.
+_IS_WINDOWS = os.name == "nt"
+_REPLACE_WAIT_SECONDS = 5.0
+_REPLACE_POLL_SECONDS = 0.02
 # The tool keys write-tools records, in forge-tier.yaml order.
 TOOL_KEYS = ("ast_grep", "gh_cli", "qmd", "ccc")
 
@@ -192,7 +205,9 @@ def _read_yaml(path: Path) -> dict | None:
 
 
 def _atomic_write(target: Path, content: str) -> None:
-    """Crash-safe write via temp + fsync + rename. Mirrors skf-atomic-write.py."""
+    """Crash-safe write via temp + fsync + rename, as skf-atomic-write.py does.
+    On Windows, a rename refused while another process has the file open is
+    retried for up to _REPLACE_WAIT_SECONDS."""
     target.parent.mkdir(parents=True, exist_ok=True)
     tmp = target.with_name(target.name + ".skf-tmp")
     # O_BINARY (Windows only; 0 elsewhere) suppresses the text-mode \n -> \r\n
@@ -205,7 +220,15 @@ def _atomic_write(target: Path, content: str) -> None:
             os.fsync(fd)
         finally:
             os.close(fd)
-        os.replace(tmp, target)
+        deadline = time.monotonic() + _REPLACE_WAIT_SECONDS
+        while True:
+            try:
+                os.replace(tmp, target)
+                break
+            except PermissionError:
+                if not _IS_WINDOWS or time.monotonic() >= deadline:
+                    raise
+                time.sleep(_REPLACE_POLL_SECONDS)
     except OSError as e:
         if tmp.exists():
             try:

package/src/shared/scripts/skf-github-probe.py

@@ -15,7 +15,7 @@ repository, and otherwise names the cause.
 CLI:
   uv run skf-github-probe.py repo --repo <repo> [--timeout <seconds>]
   uv run skf-github-probe.py tags --repo <repo> [--want <tag>]... \\
-      [--version <version> [--name <name>]] [--limit <n>] \\
+      [--version <version> [--name <name>]] [--limit <n>] [--ref <ref>] \\
       [--timeout <seconds>]
   uv run skf-github-probe.py tree --repo <repo> [--ref <ref>] \\
       [--out <file>] [--timeout <seconds>]
@@ -71,9 +71,15 @@ Output (one ASCII JSON line; every key of the command is always present):
          that names --version, else null), found ({tag: commit} for the
          --want tags that exist), missing (the --want tags the listing
          lacks), nearest (with --version, up to five tags that sort next
-         to it by version, newest first, else empty). When the listing
-         could not be read, found, missing and nearest are empty: only a
-         listing says a tag is absent.
+         to it by version, newest first, else empty), release (the tag a
+         version is read from, {"tag", "version"}, the version being the
+         tag's name less a leading `v`, else null: at --ref HEAD, the
+         default, the newest tag whose name is a release version, X.Y.Z
+         with no pre-release or build; at another --ref, that ref when the
+         listing holds it as a tag whose name is a version, a pre-release
+         included, so a branch or a commit names none). When the listing
+         could not be read, found, missing and nearest are empty and
+         release is null: only a listing says a tag is absent.
          A tag names --version in the forms skf-source-tree.py's
          match_tags tries, in its order: the version as given,
          `v<version>` and, with --name, `<name>@<v>`,
@@ -453,7 +459,7 @@ class Probe:
 # found and missing stay empty then, since no listing says a tag is absent.
 _EMPTY = {
     "repo": {"private": None, "default_branch": None},
-    "tags": {"tags": [], "count": 0, "match": None, "found": {}, "missing": [], "nearest": []},
+    "tags": {"tags": [], "count": 0, "match": None, "found": {}, "missing": [], "nearest": [], "release": None},
     "tree": {"ref": "HEAD", "tree": [], "count": 0, "truncated": False},
 }
 
@@ -501,8 +507,38 @@ def _sorted_tags(names) -> list[str]:
     return [name for _key, name in versioned] + sorted(name for _key, name in other)
 
 
+# A tag whose name is a version (`v1.2.3`, `1.2.3-rc.1`), and one whose name
+# is a release version (X.Y.Z, no pre-release or build); a leading v is not
+# part of the version.
+_VERSION_TAG_RE = re.compile(r"v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)")
+_RELEASE_TAG_RE = re.compile(r"v?(\d+\.\d+\.\d+)")
+
+
+def tag_version(name: str, release: bool = False) -> str | None:
+    """The version a tag's name is, less a leading `v` (`v1.2.3` gives
+    1.2.3), else None; with `release`, a pre-release or a build is none."""
+    m = (_RELEASE_TAG_RE if release else _VERSION_TAG_RE).fullmatch(name)
+    return m.group(1) if m else None
+
+
+def release_of(ordered: list[str], ref: str | None) -> dict | None:
+    """The tag a version is read from at `ref`, as {"tag", "version"}: at
+    HEAD the newest of `ordered` (newest version first) whose name is a
+    release version; at another ref, that ref when `ordered` holds it and
+    its name is a version; else None."""
+    ref = _tree_ref(ref)
+    if ref != "HEAD":
+        version = tag_version(ref) if ref in ordered else None
+        return {"tag": ref, "version": version} if version else None
+    for name in ordered:
+        version = tag_version(name, release=True)
+        if version:
+            return {"tag": name, "version": version}
+    return None
+
+
 def probe_tags(owner: str, repo: str, wants: list[str], limit: int, version: str | None = None,
-               package: str | None = None) -> dict:
+               package: str | None = None, ref: str | None = None) -> dict:
     p = Probe(owner, repo)
     tags: dict[str, str | None] | None = None
     via = None
@@ -544,7 +580,8 @@ def probe_tags(owner: str, repo: str, wants: list[str], limit: int, version: str
     return p.output("ok", via, tags=ordered[:limit] if limit > 0 else ordered, count=len(ordered),
                     match=next((tag for tag in (*wanted, *named) if tag in tags), None), found=found,
                     missing=[tag for tag in wanted if tag not in tags],
-                    nearest=_sibling().nearest_tags(tags, version) if version else [])
+                    nearest=_sibling().nearest_tags(tags, version) if version else [],
+                    release=release_of(ordered, ref))
 
 
 def _tree_ref(value: str | None) -> str:
@@ -621,6 +658,8 @@ def _build_parser() -> argparse.ArgumentParser:
     p_tags.add_argument("--name", help="with --version: the package name a monorepo's tags carry")
     p_tags.add_argument("--limit", type=int, default=DEFAULT_TAG_LIMIT,
                         help="tags to list, newest first (default 20; 0 for all)")
+    p_tags.add_argument("--ref", default="HEAD",
+                        help="the ref `release` reads a version at (default HEAD: the newest release tag)")
     p_tree = sub.add_parser("tree", help="list the repository's files at a ref")
     common(p_tree)
     p_tree.add_argument("--ref", default="HEAD", help="branch, tag or commit (default: the default branch)")
@@ -644,7 +683,7 @@ def main(argv: list[str] | None = None) -> int:
         elif args.cmd == "repo":
             out = probe_repo(*parsed)
         elif args.cmd == "tags":
-            out = probe_tags(*parsed, args.want, args.limit, args.version, args.name)
+            out = probe_tags(*parsed, args.want, args.limit, args.version, args.name, args.ref)
         else:
             out = probe_tree(*parsed, args.ref)
         if args.cmd == "tree" and args.out:

package/src/shared/scripts/skf-hash-content.py

@@ -17,7 +17,8 @@ Two patterns recur across the update-skill workflow's stage prose:
      content hash, compare against stored hash" and classify entries as
      MODIFIED_FILE / DELETED_FILE / (UNCHANGED). Same hashing primitive,
      iterated, plus a stat-and-compare. NEW_FILE detection is intentionally
-     out of scope here — that lives in `skf-detect-scripts-assets.py`.
+     out of scope here: that lives in `skf-detect-scripts-assets.py`,
+     piped into update-skill's `skf-new-file-diff.py`.
 
   3. **[MANUAL]-section integrity** — the update-skill workflow's headline
      Workflow Rule is "[MANUAL] sections survive regeneration with zero
@@ -49,7 +50,11 @@ Subcommands:
           "stats": {"total": N, "unchanged": U, "modified": M, "deleted": D}
         }
       The provenance file must contain `file_entries` as a top-level array
-      OR be the array itself (handles both schemas).
+      OR be the array itself (handles both schemas). A map with no
+      `file_entries` field, or a null one, tracks no file (a skill with no
+      script, asset or promoted document, or a map written before the
+      field existed): it compares no row. A `file_entries` that is neither
+      null nor an array is an error.
 
   manual-inventory <skill-md>
       Extract every `<!-- [MANUAL:name] --> … <!-- [/MANUAL:name] -->` block
@@ -238,11 +243,14 @@ def load_file_entries(provenance_path: Path) -> list[dict]:
     """Extract the file_entries list from a provenance file.
 
     Accepts two shapes:
-      - top-level object with a `file_entries` key (canonical)
+      - top-level object with a `file_entries` key (canonical); with no
+        such key, or a null one, the map tracks no file and the list is
+        empty
       - top-level array of entries (already-extracted)
 
-    Returns a copy of the list. Raises ValueError on malformed JSON or
-    missing key.
+    Returns a copy of the list. Raises ValueError on malformed JSON, a
+    `file_entries` that is not an array, or a top level that is neither
+    an object nor an array.
     """
     try:
         data = json.loads(provenance_path.read_text(encoding="utf-8"))
@@ -254,9 +262,7 @@ def load_file_entries(provenance_path: Path) -> list[dict]:
     if isinstance(data, dict):
         entries = data.get("file_entries")
         if entries is None:
-            raise ValueError(
-                f"provenance file {provenance_path} has no `file_entries` field"
-            )
+            return []  # no tracked file: a map without (or with a null) file_entries
         if not isinstance(entries, list):
             raise ValueError(
                 f"`file_entries` in {provenance_path} is not an array"

package/src/shared/scripts/skf-load-provenance.py

@@ -23,7 +23,9 @@ skf-structural-diff.py derives the re-export map from the provenance map
 itself and applies the quote-style, stdlib-prefix and re-export transforms
 on both sides (structural-diff.md §1), so no step carries `reexport_map`
 from here; the field stays for a caller that passes it to the diff as
-`--reexport-map`.
+`--reexport-map`. The diff also takes a semantic kind a by-eye read
+records as the runner's base kind for the same declaration (its
+export-type comparison).
 
 The transforms here are pure projections — no I/O against the source tree,
 no comparisons. The script reads one JSON, emits one JSON.