bmad-module-skill-forge 5.0.0 → 7.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,129 @@ 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. No kind is mapped, and a
+            signature is read only where the place writes it in a fixed
+            form (Signatures, below). 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.
+            Signatures (#888): an origin whose place writes the name's
+            signature in a fixed form that is surely complete also carries
+            it as `signature`, {"params", "return_type"}, two strings, each
+            one's whitespace runs read as one space, which
+            validate-inventory.py --floor refuses an inventory for
+            changing; any other place pins nothing, since a wrong pin would
+            be forced into the inventory. `params` is the text inside the
+            parameter group (score-signatures.py's _group: the first pair
+            of parentheses outside every bracket pair and string), and
+            `return_type` the type written after it (score-signatures.py's
+            _signature_parts), "" for none. A form that writes neither
+            (`f()`, `useQuery<T>()`) gives none, so an empty call claims no
+            form. A span (a table cell's or a heading's) is complete when
+            it is the name (or no name, as a Signature cell's `(x: A) =>
+            B`), its type parameters, one parameter group, then nothing or
+            a return separator (`->`, `=>`, `→` or `:`) and the return, with
+            nothing else: `useQuery(key).data`, `f(a) / f(a, b)`, a
+            trailing comment, a `;` or `,` outside the return's brackets,
+            an unclosed bracket, `Meta<T>` (no group) and `new Client(opts)`
+            give none. By form:
+              table-row    a row whose first cell names one name (a row
+                           naming several gives none), each cell's `\\|`
+                           read as `|`: the leading code span of its
+                           Signature or Signatures cell, else, when that
+                           span writes no parameter group (`Typed<X>`),
+                           the one span of its first cell that gives the
+                           name (another export's span there, as in
+                           `fetch` (same as `http.request(opts)`), gives
+                           nothing). A Signature span with a group that is
+                           no complete form (`client.get(k) -> str`,
+                           `new Client(opts)`) gives none, so a shorter
+                           first-cell call never stands in for it. A header
+                           cell matches whole, so a labelled one is not a
+                           Signature column, and a Props, Params or
+                           Parameters cell is never read (its shared
+                           members and usage forms stay the reader's).
+              heading      its code span
+              declaration  a function's (`function`, `def`, `fn` or Go's
+                           `func` before its name; a `const` holding an
+                           arrow gives none): its lines as one, as
+                           skf-extract-public-api.py's
+                           _declaration_signature joins them (a parameter
+                           list split over lines joined, line comments
+                           left out), the body cut off first, at the first
+                           `:` (Python) or `{`, `;` or ` where ` (any other
+                           language) outside every bracket pair and string
+                           after the parameter group, a `{` directly after
+                           a TS return `:` opening the return type
+                           (`(): { a: T } {` returns `{ a: T }`). None for
+                           one with anything but type parameters between
+                           its name and the group (a Go `func(...)`
+                           return), one whose opener follows, or whose
+                           uncut text ends with, `interface`, `struct`,
+                           `is`, `keyof`, `|`, `&`, `?`, `:`, `\\`, `=>` or
+                           `->` (the opener or the line end is inside the
+                           return type: Go's `interface{}`, a TS `asserts
+                           x is {...}`, `() => {...}` or conditional type,
+                           `): Promise<A> |`), or one whose brackets or
+                           strings do not all close.
+            A form written only in prose is never read: it stays the
+            reader's. Each origin keeps the first signature its place
+            writes.
+            Output: {"files": [...], "names": [{"name", "kindLabel",
+            "origins": [{"file", "line", "form", "signature"?}]}],
+            "summary": {"names", "byForm"}}, names sorted, each one's
+            origins in file order then line, `signature` only on an origin
+            that has one, `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 +177,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 +268,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 +385,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 +397,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 +428,57 @@ 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"})
+# The header words (as _header_word reads them, whole) of a floor table's column that writes the row's signature
+# (#888); a labelled header, such as `Signature (simplified)`, is not one.
+FLOOR_SIGNATURE_HEADERS = frozenset({"signature", "signatures"})
+# A complete form's name, before its type parameters and parameter group (group 1, absent for none).
+SPAN_NAME_RE = re.compile(r"\s*([A-Za-z_$][\w$]*)?\s*")
+# What a complete form writes after its parameter group before its return: `->`, `=>`, `→` or `:` (not `::`).
+RETURN_SEPARATOR_RE = re.compile(r"\s*(?:->|=>|→|:(?!:))")
+# A declaration that gets a form: a function keyword before its name, on its masked line.
+FUNCTION_KEYWORD_RE = re.compile(r"(?<![\w$])(?:function|def|fn|func)(?![\w$])")
+# After a declaration's parameter group: the `:` a TS return type follows (a `{` right after it opens the type, not
+# the body), and a Rust `where` clause, which the body comes after.
+RETURN_COLON_RE = re.compile(r"\s*:\s*")
+WHERE_CLAUSE_RE = re.compile(r"\s+where(?![\w$])")
+# A declaration's text that ends in the middle of its return type: a body opener after one of these is part of that
+# type, cut short (Go's `interface{}` and `struct{...}`, a TS union, intersection, `asserts x is {...}`, `keyof {...}`,
+# conditional or function type), and so is a declaration that ends with one (`): Promise<A> |`, Python's `\`).
+OPENER_IN_TYPE_RE = re.compile(r"(?:(?<![\w$])(?:interface|struct|is|keyof)|[|&?:\\]|=>|->)\s*$")
+# 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 +519,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 +608,348 @@ 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 _form(text: str, group: tuple[int, int], extension: str = "") -> dict | None:
+    """{"params", "return_type"} of a form whose parameter group is `group`, whitespace runs read as one space: the
+    text inside the group, and the return after it (score-signatures.py's _signature_parts), "" for none; None for a
+    form that writes neither (`f()`)."""
+    form = {"params": " ".join(text[group[0] + 1:group[1]].split()),
+            "return_type": " ".join(_sibling("score-signatures.py")._signature_parts(text, extension)[1].split())}
+    return form if form["params"] or form["return_type"] else None
+
+
+def _type_parameters_only(text: str) -> bool:
+    """Whether `text` is empty or one `<...>` or `[...]` pair, the type parameters a form writes before its group."""
+    text = text.strip()
+    if not text:
+        return True
+    if text[0] not in "<[" or text[-1] != {"<": ">", "[": "]"}[text[0]]:
+        return False
+    depth = 0
+    for i, ch in enumerate(text):
+        if ch in "<[(":
+            depth += 1
+        elif ch in ">])" and not (ch == ">" and text[i - 1:i] in ("-", "=")):
+            depth -= 1
+            if depth == 0 and i != len(text) - 1:
+                return False
+    return depth == 0
+
+
+def _call_form(span: str, name: str | None) -> dict | None:
+    """The signature a span writes when it is a complete form (_form): `name` or no name (a Signature cell's
+    `(x: A) => B`), its type parameters, one parameter group (score-signatures.py's _group), then nothing, or a
+    return separator (`->`, `=>`, `→` or `:`) and the return, with nothing else: no other text after the group
+    (`useQuery(key).data`, `f(a) / f(a, b)`, a trailing comment), no `;`, `,`, `#`, `//` or `/*` in the return
+    outside its brackets and strings, and every bracket and string closed. None for any other span, a constructor
+    call (`new Client(opts)`) and a span with no parameter group (`Meta<T>`) among them."""
+    scorer = _sibling("score-signatures.py")
+    text = span.strip()
+    group = scorer._group(text)
+    if group is None or text.startswith("new ") or scorer._levels(text + " ")[-1] != 0:
+        return None
+    head = SPAN_NAME_RE.match(text, 0, group[0])
+    if head.group(1) not in (None, name) or not _type_parameters_only(text[head.end():group[0]]):
+        return None
+    tail = text[group[1] + 1:]
+    separator = RETURN_SEPARATOR_RE.match(tail)
+    returned = tail[separator.end():] if separator else ""
+    if (separator is None and tail.strip()) or (separator is not None and not returned.strip()):
+        return None
+    levels = scorer._levels(returned)
+    if any(levels[i] == 0 and (ch in ";,#" or returned.startswith(("//", "/*"), i)) for i, ch in enumerate(returned)):
+        return None
+    return _form(text, group)
+
+
+def _leading_span(cell: str) -> str | None:
+    """The code span a table cell opens with, None when it opens with none."""
+    run = len(cell) - len(cell.lstrip("`"))
+    spans = _sibling("locate-export-segments.py")._inline_code(cell) if run else []
+    return spans[0] if spans and cell.startswith("`" * run + spans[0] + "`" * run) else None
+
+
+def _row_form(header: list[str], row: list[str]) -> dict | None:
+    """The signature a floor table's row writes for the one name its first cell names (a row naming several gives
+    none), each cell's `\\|` read as `|`: the leading code span of its Signature or Signatures cell, else, when that
+    span writes no parameter group, the one span of its first cell that gives that name (another export's span there
+    gives nothing), each a complete form (_call_form). A Signature span with a group that is no complete form gives
+    none. A Props, Params or Parameters cell is never read."""
+    segments = _sibling("locate-export-segments.py")
+    names = {name for name in map(_floor_name, segments._inline_code(row[0])) if name}
+    if len(names) != 1:
+        return None
+    [name] = names
+    cells = [cell.replace("\\|", "|") for cell in row]
+    at = next((i for i, cell in enumerate(header) if _header_word(cell) in FLOOR_SIGNATURE_HEADERS), None)
+    span = _leading_span(cells[at]) if at is not None and at < len(cells) else None
+    if span is not None and (form := _call_form(span, name)):
+        return form
+    if span is not None and _sibling("score-signatures.py")._group(span.strip()) is not None:
+        return None  # the cell writes a call the floor cannot pin: a shorter first-cell form would hide it
+    own = [span for span in segments._inline_code(cells[0]) if _floor_name(span) == name]
+    return _call_form(own[0], name) if len(own) == 1 else None
+
+
+def _function_declaration(line: str, language: str, js_family) -> int | None:
+    """Where the name ends on a block's masked line, one _declared_names reads, that declares a function (`function`,
+    `def`, `fn` or Go's `func` before its name); None for a line that declares no function."""
+    if language in js_family:
+        m, at = JS_DECLARATION_RE.match(line), 1
+    elif language in PYTHON_LANGUAGES:
+        m, at = PYTHON_DECLARATION_RE.match(line), 1
+    elif language in RUST_LANGUAGES:
+        m, at = RUST_DECLARATION_RE.match(line), 1
+    elif language in GO_LANGUAGES:
+        m, at = GO_DECLARATION_RE.match(line), 2
+    else:
+        return False
+    return m.end(at) if m and FUNCTION_KEYWORD_RE.search(line, 0, m.start(at)) else None
+
+
+def _declaration_form(rows: list[str], offset: int, language: str, name_end: int) -> dict | None:
+    """The signature the function declaration at `offset` of a block's unmasked `rows` writes: the declaration on one
+    line (skf-extract-public-api.py's _declaration_signature: a parameter list split over lines joined, line comments
+    left out), its body cut at the first `:` (Python) or `{`, `;` or ` where ` (any other language) outside every
+    bracket pair and string after the parameter group, a `{` directly after a TS return `:` opening the return type,
+    then read as _form reads it. None when anything but type parameters sits between the name's end (`name_end`,
+    the masked line's offset, which masking keeps) and the group (a Go `func(...)` return read as the group), when
+    the opener follows, or the uncut text ends with, `interface`, `struct`, `is`, `keyof`, `|`, `&`, `?`, `:`, `\\`,
+    `=>` or `->` (it is inside the return type: Go's `interface{}`, a TS `asserts x is {...}`, `() => {...}` or
+    conditional type, a line that ends mid-type), or a bracket or string it opens does not close."""
+    scorer = _sibling("score-signatures.py")
+    extractor = _sibling("skf-extract-public-api.py", SHARED_SCRIPTS)
+    python, rust = language in PYTHON_LANGUAGES, language in RUST_LANGUAGES
+    extension = ".rs" if rust else ""
+    text = extractor._declaration_signature(rows, offset, "python" if python else "rust" if rust else language)
+    group = scorer._group(text, extension)
+    if group is None or not _type_parameters_only(text[name_end:group[0]]):
+        return None
+    levels = scorer._levels(text, extension)
+    for i in range(group[1] + 1, len(text)):
+        if levels[i] != 0:
+            continue
+        if python:
+            body = text[i] == ":"
+        else:
+            body = (text[i] == ";" or bool(WHERE_CLAUSE_RE.match(text, i))
+                    or (text[i] == "{" and not RETURN_COLON_RE.fullmatch(text, group[1] + 1, i)))
+        if body:
+            if OPENER_IN_TYPE_RE.search(text, 0, i):
+                return None
+            text = text[:i]
+            break
+    else:
+        if OPENER_IN_TYPE_RE.search(text):
+            return None
+    if scorer._levels(text + " ", extension)[-1] != 0:
+        return None
+    return _form(text, group, extension)
+
+
+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]]] = {}
+    signatures: dict[tuple[str, int, int, str], dict] = {}  # the first per (name, file, line, form), in span order
+
+    def add(name: str | None, file_index: int, index: int, form: str, label: str | None = None,
+            signature: dict | None = None) -> None:
+        if name:
+            found.setdefault(name, set()).add((file_index, index + 1, form, label))
+            if signature is not None:
+                signatures.setdefault((name, file_index, index + 1, form), signature)
+
+    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
+            signature = _row_form(header, row)
+            for span in segments._inline_code(row[0]):
+                add(_floor_name(span), file_index, block["start"], "table-row", label, signature)
+        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", None, _call_form(span, _floor_name(span)))
+        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):
+                name_end = _function_declaration(masked[offset], language, js_family)
+                signature = (_declaration_form(lines[opening + 1:closing], offset, language, name_end)
+                             if name_end is not None else None)
+                add(name, file_index, opening + 1 + offset, "declaration", None, signature)
+
+    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))
+                origin = {"file": files[file_index], "line": line, "form": form}
+                if (name, file_index, line, form) in signatures:
+                    origin["signature"] = signatures[(name, file_index, line, form)]
+                kept.append(origin)
+                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 +1106,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 +1272,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 +1297,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 +1332,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 +1372,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 +1615,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 +1673,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 +1758,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 +1780,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")