bmad-module-skill-forge 5.0.0 → 6.0.0

package/src/skf-test-skill/scripts/load-coverage-inputs.py

@@ -9,7 +9,7 @@ coverage-check.md decides whether a bookkeeping variant is a real export,
 and makes the judgments the denominator clause needs where no file holds
 them (--pattern-reference-intent, and --curated-subset and --barrel where
 the extraction does not say); the clause, everything it counts, folds or
-unions on the way runs here, so no count is made by hand. Three subcommands, each
+unions on the way runs here, so no count is made by hand. Four subcommands, each
 reading files and writing one JSON object:
 
   census    docs-only detection. Counts the citations SKILL.md and each .md
@@ -18,6 +18,65 @@ reading files and writing one JSON object:
             (`[QMD:` and `[DOC:` are counted and decide nothing). A skill is
             docs-only when it cites `[EXT:` and no local form.
 
+  floor     the documented inventory's floor (#790): every name SKILL.md
+            and each .md file directly in references/ (a subfolder is not
+            read) write in a fixed form, which validate-inventory.py --floor
+            refuses an inventory for leaving out. It owns names only: no
+            kind is mapped and no signature read. A name is a plain
+            identifier (`[A-Za-z_$][\\w$]*`) once a leading `new ` and
+            everything from the first `(` or `<` are cut, so `Meta<T>`,
+            `fetch(url): Promise<T>` and `new Client(opts)` give `Meta`,
+            `fetch` and `Client`. A dotted or `::` name gives none, so a
+            namespace-style skill such as zod (`z.object`) gets no table
+            floor. The forms, read outside the frontmatter and HTML
+            comments (a table row or heading inside fenced code gives none):
+              table-row    each inline code span in the first cell of a
+                           table row (cells split on an unescaped `|`)
+                           whose header row's first cell is, in any case,
+                           singular or plural and bare or wrapped in `**`
+                           or `__`, Export, Symbol, Function, Class,
+                           Interface, Type, Hook, Component, Helper,
+                           Constant, Enum or API (a Name, Method, Prop,
+                           Param, Import or Subpath table gives none). The
+                           row's Kind cell, as written, is the name's
+                           `kindLabel`: the skill's own label, never mapped
+                           to a kind (the first in origin order when two
+                           rows label the name differently; null with no
+                           Kind column)
+              heading      an ATX heading whose whole text is one code
+                           span, as in ``### `Meta<T>` `` (a heading with
+                           other words, ``## Testing with `mount` ``, gives
+                           none)
+              declaration  a column-0 public declaration in a fenced block
+                           whose first non-blank line is a comment (`//`,
+                           `#`, `/* */`, `--`, `<!-- -->` or `;`) holding an
+                           `[AST:` or `[SRC:` citation, or naming a path one
+                           such citation of the skill names (its `:12`,
+                           `:L12` or `:12-30` left out). A citation counts
+                           only with its `:L<n>` (`[AST:src/a.ts:L12]`, not
+                           `[AST:src/a.ts]`), and one on the line above the
+                           fence heads nothing. Comments and strings are
+                           masked first. TS/JS (not Svelte, whose `export
+                           let` is a prop): `export` then `function`,
+                           `const`, `let`, `var`, `class`, `interface`,
+                           `type` or `enum` (`declare`, `abstract` and
+                           `async` may come between), or `export default
+                           function` or `class` with a name; Python: `def`,
+                           `async def` or `class`, a name not starting with
+                           `_`; Rust: a `pub` (not `pub(crate)`) `fn`,
+                           `struct`, `enum`, `trait`, `type`, `const` or
+                           `static`, and a `macro_rules!` under
+                           `#[macro_export]`; Go: `func`, `type`, `var` or
+                           `const` with a capitalized name, each name of a
+                           `type (`, `var (` or `const (` group too. A
+                           block in another language, an untagged one or a
+                           data block (json, yaml, text...) gives none.
+            Output: {"files": [...], "names": [{"name", "kindLabel",
+            "origins": [{"file", "line", "form"}]}], "summary": {"names",
+            "byForm"}}, names sorted, each one's origins in file order then
+            line, `byForm` counting the origins of each form; the same skill
+            gives the same bytes.
+
   metadata  the metadata.json and provenance-map counts. Cluster A
             (`stats.exports_public_api`, the `exports[]` length) and Cluster
             B (`stats.exports_documented`, the provenance entry names, the
@@ -54,7 +113,10 @@ reading files and writing one JSON object:
                             glob that matches it (`excludeGlob`) or no
                             scope.include glob covering it
                             (`outsideInclude`); exports[] only gives each name's
-                            kind, line and signature line, looked up by the
+                            kind, line and signature line (a local export
+                            list's item: its binding's declaration_line and
+                            declaration_signature_line, when the extractor
+                            records them), looked up by the
                             name its defining file gives it (an aliased
                             re-export's `local`) and that file.
                             extraction_gaps are listed to read by eye, and
@@ -142,7 +204,13 @@ reconcile-coverage.py and score-signatures.py --surface-set pick one.
 
 Candidates and guards (with an extraction, --brief or --metadata): each
 set's count, the metadata `stats.effective_denominator` (--metadata), and
-the extractor's own effective_denominator and its basis. Both guards run
+the extractor's own effective_denominator and its basis; for the
+Denominator annotations, `tierAIncludeFiles` and `scopeIncludeFiles` (the
+distinct files the set's names sit at: the files that define them when
+each name sits at its defining file) and `subpathEntries` (an extraction's
+distinct in-scope non-root, non-wildcard subpaths, each package's subpath
+once however many files it names), each null when its set is absent.
+Both guards run
 only on a surface read from the source. The deflation guard compares a
 re-derived set with `stats.effective_denominator` and names it in `basis`.
 It is the tier_a_include set (`tier_a_include`) when the clause's ladder
@@ -253,6 +321,7 @@ a stylesheet, holds nothing to read and is in neither list.
 
 Usage:
   uv run load-coverage-inputs.py census --skill-dir <dir> [--output <file>]
+  uv run load-coverage-inputs.py floor --skill-dir <dir> [--output <file>]
   uv run load-coverage-inputs.py metadata --metadata <metadata.json> \\
       [--provenance <provenance-map.json>] [--output <file>]
   uv run load-coverage-inputs.py surface [--extraction <file>] [--quick <file>]... \\
@@ -264,7 +333,8 @@ Usage:
 Exit codes:
   0  the result was printed (and written to --output)
   1  an input file is missing, unreadable or not the JSON (or the YAML
-     brief) it should be (one line on stderr)
+     brief) it should be, or the --skill-dir holds no SKILL.md or a skill
+     file that is not UTF-8 (one line on stderr)
   2  a per-file result breaks the schema: {"valid": false, "violations":
      [...]} names each breach and nothing is written to --output; or a
      usage error (argparse)
@@ -294,6 +364,40 @@ CITATION_FORMS = {
     "DOC": "[DOC:",
 }
 LOCAL_FORMS = ("AST", "SRC", "from skill")
+# floor: the forms a documented name takes, in the order an origin on one line sorts by.
+FLOOR_FORMS = ("table-row", "heading", "declaration")
+# The first header cells (lower case, singular or plural) of a table whose first column names exports.
+FLOOR_TABLE_HEADERS = frozenset({
+    "export", "exports", "symbol", "symbols", "function", "functions", "class", "classes", "interface", "interfaces",
+    "type", "types", "hook", "hooks", "component", "components", "helper", "helpers", "constant", "constants",
+    "enum", "enums", "api", "apis"})
+# A header cell wrapped in `**` or `__` (group 2 its text).
+EMPHASIS_RE = re.compile(r"(\*\*|__)(.+)\1")
+PLAIN_IDENTIFIER_RE = re.compile(r"[A-Za-z_$][\w$]*")
+TABLE_CELL_RE = re.compile(r"(?<!\\)\|")
+# A comment's opening marker: `//`, `#`, `/*`, `--`, `<!--` or `;`.
+COMMENT_MARKER_RE = re.compile(r"[ \t]*(?://+|#+|/\*+|--|<!--|;+)")
+# A cited path's line suffix: `:12`, `:L12`, `:12-30` or `:L12-L30`.
+LINE_SUFFIX_RE = re.compile(r":L?\d+(?:-L?\d+)?$")
+PYTHON_LANGUAGES = frozenset({"python", "py", "python3"})
+RUST_LANGUAGES = frozenset({"rust", "rs"})
+GO_LANGUAGES = frozenset({"go", "golang"})
+# Column-0 public declarations (group 1 the name), matched on the block with comments and strings masked.
+JS_DECLARATION_RE = re.compile(
+    r"export\s+(?:default\s+(?:abstract\s+)?(?:async\s+)?(?:function(?:\s*\*\s*|\s+)|class\s+)"
+    r"|(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?"
+    r"(?:function(?:\s*\*\s*|\s+)|const\s+enum\s+|const\s+|let\s+|var\s+|class\s+|interface\s+|type\s+|enum\s+))"
+    r"(?!(?:extends|implements)(?![\w$]))([A-Za-z_$][\w$]*)")
+PYTHON_DECLARATION_RE = re.compile(r"(?:async\s+def|def|class)\s+([A-Za-z_]\w*)")
+RUST_DECLARATION_RE = re.compile(
+    r"pub\s+(?:(?:async|unsafe|const|extern)\s+)*(?:fn|struct|enum|trait|type|const|static)\s+(?:mut\s+)?"
+    r"([A-Za-z_]\w*)")
+RUST_MACRO_EXPORT_RE = re.compile(r"#\[macro_export\]")
+RUST_MACRO_RE = re.compile(r"(?:#\[[^\]]*\][ \t]*)*macro_rules![ \t]*([A-Za-z_]\w*)")
+# Go: a single declaration (group 1 its keyword, group 2 its names) or a group's opening line (group 1).
+GO_DECLARATION_RE = re.compile(r"(func|type|var|const)[ \t]+([A-Za-z_]\w*(?:[ \t]*,[ \t]*[A-Za-z_]\w*)*)")
+GO_GROUP_RE = re.compile(r"(type|var|const)[ \t]*\([ \t]*$")
+GO_GROUP_NAMES_RE = re.compile(r"[ \t]+([A-Za-z_]\w*(?:[ \t]*,[ \t]*[A-Za-z_]\w*)*)")
 # Bookkeeping variants folded to their base name, in rule order.
 FOLD_SUFFIXES = ("_def", "_exact")
 FOLD_PREFIX = "a11y_"
@@ -334,7 +438,9 @@ SHARED_SCRIPTS = Path(__file__).resolve().parent.parent.parent / "shared" / "scr
 
 def _sibling(filename: str, folder: Path | None = None):
     """A script beside this one, loaded once: validate-inventory.py (the doc
-    text) and score-signatures.py (the per-file result schema); or, with
+    text, and the skill citations floor reads), locate-export-segments.py
+    (the line model floor reads the skill with) and score-signatures.py (the
+    per-file result schema); or, with
     `folder`, one in that folder: SHARED_SCRIPTS'
     skf-resolve-authoritative-files.py (a skill brief's YAML)."""
     module = _SIBLINGS.get(filename)
@@ -421,6 +527,199 @@ def census(skill_dir: str) -> dict:
     }
 
 
+# --------------------------------------------------------------------------
+# floor
+# --------------------------------------------------------------------------
+
+
+def _floor_name(text: str) -> str | None:
+    """The plain identifier `text` writes once a leading `new ` and everything from the first `(` or `<` are
+    cut; None for any other text, a dotted or `::` name among them."""
+    text = text.strip()
+    if text.startswith("new "):
+        text = text[4:]
+    text = re.split(r"[(<]", text, maxsplit=1)[0].strip()
+    return text if PLAIN_IDENTIFIER_RE.fullmatch(text) else None
+
+
+def _header_word(cell: str) -> str:
+    """A header cell's word, lower case, unwrapped from `**` or `__`."""
+    m = EMPHASIS_RE.fullmatch(cell)
+    return (m.group(2) if m else cell).strip().lower()
+
+
+def _cells(row: str) -> list[str]:
+    """A table row's cells, split on each unescaped `|`, each stripped."""
+    row = row.strip()
+    if row.startswith("|"):
+        row = row[1:]
+    if row.endswith("|") and not row.endswith("\\|"):
+        row = row[:-1]
+    return [cell.strip() for cell in TABLE_CELL_RE.split(row)]
+
+
+def _whole_span(text: str, segments) -> str | None:
+    """The code span `text` is, when the whole of it is one; else None."""
+    spans = segments._inline_code(text)
+    if len(spans) != 1:
+        return None
+    run = len(text) - len(text.lstrip("`"))
+    return spans[0] if text == "`" * run + spans[0] + "`" * run else None
+
+
+def _comment_text(line: str) -> str | None:
+    """A comment line's text, its markers stripped (`// x`, `# x`, `/* x */`, `-- x`, `<!-- x -->`, `; x`);
+    None for a line that is no comment. Linear in the line's length."""
+    m = COMMENT_MARKER_RE.match(line)
+    if not m:
+        return None
+    text = line[m.end():].strip()
+    if text.endswith("-->"):
+        text = text[:-3]
+    elif text.endswith("*/"):
+        text = text[:-2].rstrip("*")
+    return text.strip()
+
+
+def _headed(lines: list[str], opening: int, closing: int, cited: set[str], inventory) -> bool:
+    """Whether a source citation heads the fenced block opening at `opening`: its first non-blank line is a
+    comment holding a citation, or naming a path the skill cites (a `:12`, `:L12` or `:12-30` suffix left
+    out). A citation on the line above the fence heads nothing."""
+    first = next((lines[i] for i in range(opening + 1, closing) if lines[i].strip()), None)
+    text = _comment_text(first) if first is not None else None
+    if not text:
+        return False
+    if inventory._SKILL_CITATION_RE.search(text):
+        return True
+    suffix = LINE_SUFFIX_RE.search(text)
+    path = text[:suffix.start()] if suffix else text
+    return bool(path) and not any(c.isspace() for c in path) and inventory._cited_path(path) in cited
+
+
+def _html_comment_lines(lines: list[str], start: int, code: list[bool]) -> set[int]:
+    """The lines inside an HTML comment, the fenced lines it holds included, read as _prose reads one: a line
+    outside fenced code that starts `<!--` opens it, the next such line holding `-->` closes it."""
+    inside, open_ = set(), False
+    for i in range(start, len(lines)):
+        if open_:
+            inside.add(i)
+            open_ = code[i] or "-->" not in lines[i]
+        elif not code[i] and lines[i].strip().startswith("<!--"):
+            inside.add(i)
+            open_ = "-->" not in lines[i].strip()[4:]
+    return inside
+
+
+def _names(text: str) -> list[str]:
+    return [name.strip() for name in text.split(",")]
+
+
+def _declared_names(lines: list[str], language: str, js_family) -> list[tuple[int, str]]:
+    """(offset, name) of each column-0 public declaration in a block's masked lines, by its language."""
+    found: list[tuple[int, str]] = []
+    if language in js_family:
+        found = [(i, m.group(1)) for i, line in enumerate(lines) if (m := JS_DECLARATION_RE.match(line))]
+    elif language in PYTHON_LANGUAGES:
+        found = [(i, m.group(1)) for i, line in enumerate(lines)
+                 if (m := PYTHON_DECLARATION_RE.match(line)) and not m.group(1).startswith("_")]
+    elif language in RUST_LANGUAGES:
+        exported = False  # a `#[macro_export]` above, with only blank or attribute lines between
+        for i, line in enumerate(lines):
+            if m := RUST_DECLARATION_RE.match(line):
+                found.append((i, m.group(1)))
+            exported = exported or bool(RUST_MACRO_EXPORT_RE.match(line))
+            macro = RUST_MACRO_RE.match(line)
+            if macro and exported:
+                found.append((i, macro.group(1)))
+            if macro or (line.strip() and not line.startswith("#[")):
+                exported = False
+    elif language in GO_LANGUAGES:
+        group, depth = False, 0  # inside a `type (`, `var (` or `const (` group, and its bracket depth there
+        for i, line in enumerate(lines):
+            if group:
+                if depth == 0 and line.lstrip().startswith(")"):
+                    group = False
+                    continue
+                if depth == 0 and (m := GO_GROUP_NAMES_RE.match(line)):
+                    found += [(i, name) for name in _names(m.group(1)) if name[0].isupper()]
+                depth = max(0, depth + sum(map(line.count, "{([")) - sum(map(line.count, "})]")))
+            elif GO_GROUP_RE.match(line):
+                group, depth = True, 0
+            elif m := GO_DECLARATION_RE.match(line):
+                found += [(i, name) for name in _names(m.group(2)) if name[0].isupper()]
+    return found
+
+
+def floor(skill_dir: str) -> dict:
+    """The names the skill documents in a fixed form, each with its origins (see the module docstring)."""
+    root = Path(skill_dir)
+    if not (root / "SKILL.md").is_file():
+        raise InputError(f"--skill-dir {skill_dir} holds no SKILL.md")
+    segments = _sibling("locate-export-segments.py")
+    inventory = _sibling("validate-inventory.py")
+    refs = root / "references"
+    files = ["SKILL.md"] + ([f"references/{p.name}" for p in sorted(refs.glob("*.md")) if p.is_file()]
+                           if refs.is_dir() else [])
+    texts = []
+    for rel in files:
+        try:
+            texts.append(segments._split_lines((root / rel).read_bytes().decode("utf-8-sig")))
+        except (OSError, UnicodeDecodeError) as exc:
+            raise InputError(f"cannot read {rel} under {skill_dir}: {exc}") from exc
+    cited = {inventory._cited_path(m.group(2))
+             for lines in texts for line in lines for m in inventory._SKILL_CITATION_RE.finditer(line)}
+
+    found: dict[str, set[tuple[int, int, str, str | None]]] = {}
+
+    def add(name: str | None, file_index: int, index: int, form: str, label: str | None = None) -> None:
+        if name:
+            found.setdefault(name, set()).add((file_index, index + 1, form, label))
+
+    js_family = segments.JS_FAMILY - {"svelte"}  # a Svelte block's `export let` is a component prop
+    for file_index, lines in enumerate(texts):
+        start = segments._frontmatter_end(lines)
+        blocks, code = segments._fenced_blocks(lines, start)
+        headings, prose = segments._prose(lines, start, code)
+        for block in prose:
+            if block["kind"] != "table-row" or block["header"] is None:
+                continue
+            header = _cells(block["header"])
+            if _header_word(header[0]) not in FLOOR_TABLE_HEADERS:
+                continue
+            row = _cells(lines[block["start"]])
+            kind_at = next((i for i, cell in enumerate(header) if _header_word(cell) == "kind"), None)
+            label = row[kind_at] if kind_at is not None and kind_at < len(row) and row[kind_at] else None
+            for span in segments._inline_code(row[0]):
+                add(_floor_name(span), file_index, block["start"], "table-row", label)
+        for index, _level, text, _above in headings:
+            span = _whole_span(text, segments)
+            if span is not None:
+                add(_floor_name(span), file_index, index, "heading")
+        comments = _html_comment_lines(lines, start, code)
+        for opening, closing, info in blocks:
+            language = segments._language(info)
+            if (opening in comments or language in segments.DATA_LANGUAGES
+                    or not _headed(lines, opening, closing, cited, inventory)):
+                continue
+            masked = segments.mask_code("\n".join(lines[opening + 1:closing]), language).split("\n")
+            for offset, name in _declared_names(masked, language, js_family):
+                add(name, file_index, opening + 1 + offset, "declaration")
+
+    names = []
+    by_form = dict.fromkeys(FLOOR_FORMS, 0)
+    for name in sorted(found):
+        origins = sorted(found[name], key=lambda o: (o[0], o[1], FLOOR_FORMS.index(o[2]), o[3] or ""))
+        seen, kept = set(), []
+        for file_index, line, form, _label in origins:
+            if (file_index, line, form) not in seen:
+                seen.add((file_index, line, form))
+                kept.append({"file": files[file_index], "line": line, "form": form})
+                by_form[form] += 1
+        label = next((o[3] for o in origins if o[2] == "table-row" and o[3]), None)
+        names.append({"name": name, "kindLabel": label, "origins": kept})
+    return {"files": files, "names": names, "summary": {"names": len(names), "byForm": by_form}}
+
+
 # --------------------------------------------------------------------------
 # metadata
 # --------------------------------------------------------------------------
@@ -577,6 +876,14 @@ def matching(records: list[dict], globs: list[str], excludes: list[str]) -> list
                    and not any(glob_match(_norm(r["file"]), g) for g in excludes)})
 
 
+def matching_files(records: list[dict], globs: list[str], excludes: list[str]) -> list[str]:
+    """The distinct files `matching` takes its names from: each record's file one of `globs` matches and no
+    exclude glob does."""
+    return sorted({r["file"] for r in records if r.get("file")
+                   and any(glob_match(_norm(r["file"]), g) for g in globs)
+                   and not any(glob_match(_norm(r["file"]), g) for g in excludes)})
+
+
 def _apart(a: str, b: str) -> bool:
     """True when, before either has a `*` or `?`, the two globs spell a different segment at the same
     place, so no file can match both. Any other pair counts as overlapping, even one no file can match
@@ -735,7 +1042,7 @@ def from_extraction(data: dict, language: str | None = None, brief: dict | None
                 "staleScope": {"unmatchedInclude": unmatched, "unmatchedTierAInclude": unmatched_tier_a,
                                "restored": []},
                 "gaps": [], "scope": scope, "scopeType": recorded.get("type"), "umbrella": dict(NO_UMBRELLA),
-                "extraction": extraction}
+                "subpathEntries": None, "extraction": extraction}
 
     diff = data.get("entry_point_diff") if isinstance(data.get("entry_point_diff"), dict) else {}
     # Each in-scope definition of a public name is a record of its own (#830): the runner's other
@@ -760,6 +1067,11 @@ def from_extraction(data: dict, language: str | None = None, brief: dict | None
     subpath_files = {e.get("file") for e in entry_files
                      if e.get("subpath") not in ROOT_SUBPATHS and "*" not in str(e.get("subpath"))}
     root_files = {e.get("file") for e in entry_files if e.get("subpath") in ROOT_SUBPATHS} - set(nested)
+    # The distinct in-scope subpaths of those (a package's subpath once, however many files its conditions
+    # name), for the multi-entry annotation.
+    subpath_entries = {(e.get("package"), e.get("subpath")) for e in entry_files
+                       if e.get("subpath") not in ROOT_SUBPATHS and "*" not in str(e.get("subpath"))
+                       and e.get("in_scope") is not False}
 
     # A scope.include glob that matches no file: the brief predates the
     # source, so a root export defined in a file no glob covers comes back,
@@ -790,10 +1102,16 @@ def from_extraction(data: dict, language: str | None = None, brief: dict | None
         # under the name its defining file gives it, `local`.
         found = index.get((info.get("local") or name, file)) or index.get((name, file))
         kind = found.get("export_type") if found else None
+        # A local `export { ... }` list's item is planned at the declaration it
+        # names (#836): the line and the signature line both come from that pair.
+        if found and isinstance(found.get("declaration_line"), int):
+            line, signature_line = found["declaration_line"], found.get("declaration_signature_line")
+        elif found:
+            line, signature_line = found.get("source_line"), found.get("signature_line")
+        else:
+            line, signature_line = info.get("line"), None
         (nested_records if info.get("entry") in nested else records).append(
-            _record(name, None if kind == "re-export" else kind, file,
-                    found.get("source_line") if found else info.get("line"),
-                    found.get("signature_line") if found else None, "extraction"))
+            _record(name, None if kind == "re-export" else kind, file, line, signature_line, "extraction"))
 
     # The umbrella ratio reads the public rows alone: an other definition is no root barrel name there.
     root_names = [p for p in _members_in_place(rows["public"]) if p.get("entry") in root_files]
@@ -824,6 +1142,8 @@ def from_extraction(data: dict, language: str | None = None, brief: dict | None
             "ratio": round2(len(reexported) / len(root_names)) if root_names else None,
             "umbrella": bool(root_names) and len(reexported) / len(root_names) > UMBRELLA_RATIO,
         },
+        # The in-scope subpaths the `subpaths` set reads (None when there is no such set).
+        "subpathEntries": len(subpath_entries) if subpath_files else None,
         "extraction": extraction,
     }
 
@@ -1065,13 +1385,17 @@ def surface(args: argparse.Namespace) -> dict:
               and not (scope["include"] and all(_apart(g, i) for i in scope["include"]))
               and not any(_inside(g, e) for e in scope["exclude"])]
     filed = [r for r in records if r["file"]]
+    # The files each scope set's names sit at, for the Denominator annotations' file counts.
+    set_files: dict[str, list[str]] = {}
     if filed and scope["include"]:
         sets["scope.include"] = matching(filed, scope["include"], scope["exclude"])
+        set_files["scope.include"] = matching_files(filed, scope["include"], scope["exclude"])
     in_include = [r for r in filed if not scope["include"]
                   or any(glob_match(_norm(r["file"]), g) for g in scope["include"])]
     tier_a_names = matching(in_include, tier_a, scope["exclude"]) if tier_a else []
     if tier_a_names:
         sets["tier_a_include"] = tier_a_names
+        set_files["tier_a_include"] = matching_files(in_include, tier_a, scope["exclude"])
 
     # The clause: an extraction's entry-point status (one the per-file scan replaces says only that it found no
     # entry point), else a quick output's (an export is a barrel; none, and no warning, an empty one), else what
@@ -1119,7 +1443,10 @@ def surface(args: argparse.Namespace) -> dict:
             "statsEffectiveDenominator": stats_eff,
             "tierAIncludeUnion": len(sets["tier_a_include"]) if "tier_a_include" in sets else None,
             "scopeIncludeUnion": len(sets["scope.include"]) if "scope.include" in sets else None,
+            "tierAIncludeFiles": len(set_files["tier_a_include"]) if "tier_a_include" in sets else None,
+            "scopeIncludeFiles": len(set_files["scope.include"]) if "scope.include" in sets else None,
             "subpathUnion": len(sets["subpaths"]) if "subpaths" in sets else None,
+            "subpathEntries": extracted["subpathEntries"] if extracted is not None else None,
             "rootBarrel": len(sets["root"]) if "root" in sets else None,
             "extractorEffectiveDenominator": extraction.get("effectiveDenominator"),
             "extractorBasis": extraction.get("effectiveDenominatorBasis"),
@@ -1201,6 +1528,10 @@ def _cmd_census(args: argparse.Namespace) -> dict:
     return census(args.skill_dir)
 
 
+def _cmd_floor(args: argparse.Namespace) -> dict:
+    return floor(args.skill_dir)
+
+
 def _cmd_metadata(args: argparse.Namespace) -> dict:
     meta = _object(args.metadata, "--metadata")
     provenance = _object(args.provenance, "--provenance") if args.provenance else None
@@ -1219,6 +1550,11 @@ def _build_parser() -> argparse.ArgumentParser:
     p.add_argument("--output", help="also write the result to this file")
     p.set_defaults(func=_cmd_census)
 
+    p = sub.add_parser("floor", help="the names the skill documents in a fixed form, which the inventory keeps")
+    p.add_argument("--skill-dir", required=True, help="the skill package: SKILL.md and references/")
+    p.add_argument("--output", help="also write the result to this file")
+    p.set_defaults(func=_cmd_floor)
+
     p = sub.add_parser("metadata", help="the metadata.json and provenance-map counts")
     p.add_argument("--metadata", required=True, help="the skill's metadata.json")
     p.add_argument("--provenance", help="the provenance map, when there is one")