bmad-module-skill-forge 6.0.0 → 8.0.0

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

@@ -21,12 +21,15 @@ reading files and writing one JSON object:
   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
+            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
+            everything from the first `(`, `<` or `[` are cut, so
+            `Meta<T>`, `App[P, R]`, `fetch(url): Promise<T>` and
+            `new Client(opts)` give `Meta`, `App`, `fetch` and `Client`;
+            an empty `[]` at the cut (a TS array type, `Foo[]`) gives
+            none. 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):
@@ -71,11 +74,74 @@ reading files and writing one JSON object:
                            `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"}]}], "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.
+            "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
@@ -371,6 +437,23 @@ 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$]*")
@@ -533,12 +616,16 @@ def census(skill_dir: str) -> dict:
 
 
 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."""
+    """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 and an array type (`Foo[]`, an empty `[]` at the cut)
+    among them."""
     text = text.strip()
     if text.startswith("new "):
         text = text[4:]
-    text = re.split(r"[(<]", text, maxsplit=1)[0].strip()
+    cut = re.match(r"([^(<\[]*)(\[\s*\])?", text)
+    if cut.group(2):
+        return None
+    text = cut.group(1).strip()
     return text if PLAIN_IDENTIFIER_RE.fullmatch(text) else None
 
 
@@ -650,6 +737,144 @@ def _declared_names(lines: list[str], language: str, js_family) -> list[tuple[in
     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)
@@ -670,10 +895,14 @@ def floor(skill_dir: str) -> dict:
              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) -> None:
+    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):
@@ -689,12 +918,13 @@ def floor(skill_dir: str) -> dict:
             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)
+                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")
+                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)
@@ -703,7 +933,10 @@ def floor(skill_dir: str) -> dict:
                 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")
+                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)
@@ -713,7 +946,10 @@ def floor(skill_dir: str) -> dict:
         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})
+                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})

package/src/skf-test-skill/scripts/score-signatures.py

@@ -245,7 +245,6 @@ from pathlib import Path, PurePosixPath
 # Surface kinds that count toward total_types. A Rust struct is a class and a
 # trait an interface; `type` is a type alias.
 TYPE_KINDS = frozenset({"interface", "type", "enum", "class", "struct", "trait"})
-SIGNATURE_FIELDS = ("params", "return_type", "usage_signature")
 MISMATCH_FIELDS = ("name", "line", "source_sig", "documented_sig", "issue")
 # The optional `difference` a judge tags a mismatch with, defined in
 # references/signature-comparison-rules.md (Difference tags): only the
@@ -518,7 +517,7 @@ def _has_signature(entry: dict) -> bool:
         return True
     return any(
         isinstance(entry.get(f), list) or (isinstance(entry.get(f), str) and entry[f].strip())
-        for f in SIGNATURE_FIELDS
+        for f in _inventory().SIGNATURE_FIELDS
     )
 
 
@@ -552,26 +551,23 @@ def _rank(fields: dict) -> tuple[bool, bool, bool]:
 
 def _form(entry: dict) -> dict:
     """The documented signature fields of one inventory entry, with its `signature_form` when it has one."""
-    fields = {f: entry[f] for f in SIGNATURE_FIELDS if f in entry}
+    fields = {f: entry[f] for f in _inventory().SIGNATURE_FIELDS if f in entry}
     if entry.get("signature_form") is not None:
         fields["signature_form"] = entry["signature_form"]
     return fields
 
 
 def _field_text(value: object) -> str:
-    """A signature field as one text: a list's items joined with `, `, whitespace runs as one space, "" for null."""
-    if value is None:
-        return ""
-    if isinstance(value, list):
-        value = ", ".join(v if isinstance(v, str) else json.dumps(v, sort_keys=True) for v in value)
-    return " ".join(value.split()) if isinstance(value, str) else json.dumps(value, sort_keys=True)
+    """A signature field as one text (validate-inventory.py's field_text, which the floor check reads too): a
+    list's items joined with `, `, whitespace runs as one space, "" for null."""
+    return _inventory().field_text(value)
 
 
 def _form_key(fields: dict) -> tuple:
-    """What a form says, for telling two entries apart (_field_text), a
-    null, blank or empty key read as absent, and the `signature_form` label
-    left out (documented_forms keeps the full one)."""
-    return tuple((f, _field_text(fields[f])) for f in SIGNATURE_FIELDS if f in fields and _field_text(fields[f]))
+    """What a form says, for telling two entries apart (validate-inventory.py's form_key, which the floor check
+    reads too): a null, blank or empty key read as absent, and the `signature_form` label left out
+    (documented_forms keeps the full one)."""
+    return _inventory().form_key(fields)
 
 
 def documented_forms(inventory: list[dict]) -> dict[str, list[dict]]:

package/src/skf-test-skill/scripts/validate-inventory.py

@@ -53,7 +53,19 @@ kept when any inventory entry has that name, whatever its kind: kinds stay
 the reader's. Each checked name not
 kept is a violation naming its first checked origin, and the inventory is
 invalid, as for a fabricated name, so the prompt re-dispatches the subagent
-with the names it left out.
+with the names it left out. A checked origin that carries a `signature`
+(#888: the `params` and `return_type` the skill writes there in a fixed
+form) is carried when an entry of that name, whatever its kind, reads as it
+does: each of `params` and `return_type` the signature pins non-blank gives
+the same field_text (whitespace runs as one space, a list's items joined
+with `, `, a null field as blank), and a `params` that opens with the shared
+text the contract has several names' entries carry, then `; `, carries the
+pinned one after it. A field the signature leaves blank, and the entry's
+other fields, a `usage_signature` among them, are not read.
+Each checked origin no entry carries is a violation naming the origin and
+its signature, for a name left out too, and the inventory is invalid: the
+form is never overwritten, so the re-dispatched subagent copies it as
+given.
 
 An entry's optional `signature_form` says how the skill presents its
 signature: `partial` only when the skill labels the form partial (a
@@ -86,7 +98,10 @@ directly in references/ writes it as a fixed string, case-sensitive, never
 inside a longer identifier (the Export match rule of
 skf-scan-skill-md-structure.py usage-scope): on a side where the name ends
 in a letter, digit, `_` or `$`, the next character may not be one of those.
-So `get` is found in `get(url)` but not in `target` or `getAll`.
+So `get` is found in `get(url)` but not in `target` or `getAll`. The form
+helpers `field_text` and `form_key` are shared too: score-signatures.py
+tells an entry's forms apart with them, and the floor check reads a floor
+origin's `signature` with `field_text`.
 
 The skill-citation scan is shared too: `_skill_cited_files` (with
 `_cited_path`, `skill_markdown_files` and `_SKILL_CITATION_RE`) gives the
@@ -145,12 +160,15 @@ Output (stdout, one object):
   }
 
 Exit codes:
-  0  inventory valid (every sampled name found, every checked floor name kept)
+  0  inventory valid (every sampled name found, every checked floor name
+     kept and every checked floor signature carried)
   1  no input provided, the --input file cannot be read, the
      --skill-package folder holds no readable SKILL.md, or the --floor file
-     cannot be read or is not a floor (usage error)
+     cannot be read or is not a floor, a malformed `signature` among them
+     (usage error)
   2  inventory invalid (parse failure, schema violation, a sampled name
-     absent or a floor name left out; result JSON emitted)
+     absent, a floor name left out or a floor signature no entry carries;
+     result JSON emitted)
 """
 
 from __future__ import annotations
@@ -207,6 +225,13 @@ OTHER_SIDE_SHAPES = (
 # be complete (the docs-only Export Coverage rule).
 SIGNATURE_KINDS = ("function", "method")
 
+# An entry's signature fields, the ones form_key reads (score-signatures.py reads them from here).
+SIGNATURE_FIELDS = ("params", "return_type", "usage_signature")
+
+# The fields of a floor origin's `signature` (#888), each a string, and the
+# ones the floor check compares with an entry's.
+FLOOR_SIGNATURE_FIELDS = ("params", "return_type")
+
 # Characters that continue an identifier in the languages SKF documents
 # (`$` for JS/TS names such as `$state`).
 IDENT_CHARS = r"\w$"
@@ -409,6 +434,25 @@ def spot_check(inventory, skill_package_path):
     }
 
 
+# --- Signature forms ----------------------------------------------------------
+
+
+def field_text(value: object) -> str:
+    """A signature field as one text: a list's items joined with `, `, whitespace runs as one space, "" for null."""
+    if value is None:
+        return ""
+    if isinstance(value, list):
+        value = ", ".join(v if isinstance(v, str) else json.dumps(v, sort_keys=True) for v in value)
+    return " ".join(value.split()) if isinstance(value, str) else json.dumps(value, sort_keys=True)
+
+
+def form_key(fields: dict) -> tuple:
+    """What a form says, for telling two entries apart (field_text), a
+    null, blank or empty key read as absent, and the `signature_form` label
+    left out (score-signatures.py's documented_forms keeps the full one)."""
+    return tuple((f, field_text(fields[f])) for f in SIGNATURE_FIELDS if f in fields and field_text(fields[f]))
+
+
 # --- Floor ------------------------------------------------------------------
 
 
@@ -416,10 +460,17 @@ class FloorError(Exception):
     """The --floor file cannot be read or is not a floor: exit 1."""
 
 
+def _is_signature(value):
+    """A floor origin's `signature`: an object of exactly the strings `params` and `return_type`."""
+    return (isinstance(value, dict) and sorted(value) == sorted(FLOOR_SIGNATURE_FIELDS)
+            and all(isinstance(value[f], str) for f in FLOOR_SIGNATURE_FIELDS))
+
+
 def _is_origin(origin):
     return (isinstance(origin, dict) and isinstance(origin.get("file"), str) and bool(origin["file"])
             and isinstance(origin.get("line"), int) and not isinstance(origin["line"], bool)
-            and isinstance(origin.get("form"), str))
+            and isinstance(origin.get("form"), str)
+            and ("signature" not in origin or _is_signature(origin["signature"])))
 
 
 def read_floor(path):
@@ -436,7 +487,8 @@ def read_floor(path):
             and isinstance(item.get("origins"), list) and all(_is_origin(o) for o in item["origins"])
             for item in names):
         raise FloorError(f"{path} is not a floor: `names` must give each name's `name` and `origins` "
-                         "(each a file, a line and a form)")
+                         "(each a file, a line and a form, and an optional `signature` of the strings "
+                         "`params` and `return_type`)")
     return data
 
 
@@ -450,33 +502,60 @@ def _listed_path(ref, skill_package_path):
     return _cited_path(ref)
 
 
+def _carries(entry, signature):
+    """Whether an entry carries a floor origin's signature: each field it pins non-blank has the same field_text
+    there, a `params` that opens with members the skill states once for several names (the contract's shared
+    text, then `; `) included."""
+    for field in FLOOR_SIGNATURE_FIELDS:
+        wanted, given = field_text(signature[field]), field_text(entry.get(field))
+        if wanted and given != wanted and not (field == "params" and given.endswith("; " + wanted)):
+            return False
+    return True
+
+
 def floor_check(inventory, floor, skill_package_path=None):
-    """The floor names the inventory leaves out: (the `floor` result, its violations).
+    """The floor names and signatures the inventory leaves out: (the `floor` result, its violations).
 
     A floor name is checked when one of its origins is SKILL.md or a file
     the inventory's `references` lists (the spot-check's files, an absolute
     path inside `skill_package_path` matched by its path relative to it),
     and kept when any inventory entry has that name, whatever its kind. A
-    name left out is a violation naming its first checked origin.
+    name left out is a violation naming its first checked origin. Then each
+    checked origin with a `signature` is carried when an entry of that name,
+    whatever its kind, gives the same field_text to each field the
+    signature pins non-blank (a blank pinned `return_type` leaves the
+    entry's free; a `params` may open with shared text and `; `, _carries);
+    one no entry carries is a violation naming the origin and the
+    signature, for a name left out too.
     """
     listed = inventory.get("references")
     files = {"SKILL.md"} | {_listed_path(ref, skill_package_path)
                             for ref in (listed if isinstance(listed, list) else [])
                             if isinstance(ref, str) and ref.strip()}
-    kept = {e.get("name") for e in inventory.get("exports") or [] if isinstance(e, dict)}
+    entries = [e for e in inventory.get("exports") or [] if isinstance(e, dict)]
+    kept = {e.get("name") for e in entries}
     names = floor.get("names") or []
-    checked, absent, violations = 0, [], []
+    checked, absent, violations, signed = 0, [], [], []
     for item in names:
         origins = [o for o in item["origins"] if _cited_path(o["file"]) in files]
         if not origins:
             continue
         checked += 1
         name = item["name"]
+        signed += [(name, o) for o in origins if "signature" in o]
         if name in kept:
             continue
         absent.append(name)
         where = f"{origins[0]['file']}:{origins[0]['line']} ({origins[0]['form']})"
         violations.append(f"floor: `{name}` is documented at {where}, but no inventory entry lists it")
+    for name, origin in signed:
+        signature = {f: origin["signature"][f] for f in FLOOR_SIGNATURE_FIELDS}
+        if any(_carries(e, signature) for e in entries if e.get("name") == name):
+            continue
+        where = f"{origin['file']}:{origin['line']} ({origin['form']})"
+        violations.append(f"floor: `{name}` is documented at {where} with the signature "
+                          f"{json.dumps(signature, ensure_ascii=False)}, but no inventory entry of that name "
+                          "carries it; copy it as given")
     return {"names": len(names), "checked": checked, "absent": absent}, violations
 
 
@@ -782,7 +861,7 @@ def _build_parser():
     parser.add_argument(
         "--floor",
         metavar="PATH",
-        help="Check the inventory keeps the names of this load-coverage-inputs.py floor file.",
+        help="Check the inventory keeps the names and signatures of this load-coverage-inputs.py floor file.",
     )
     return parser
 

package/src/skf-update-skill/customize.toml

@@ -52,7 +52,7 @@ persistent_facts = [
 # command is called as:
 #   <on_complete> --result-path=<{forge_version}/update-skill-result-latest.json>
 # It is not called for --detect-only or --dry-run, which write no result
-# file, nor when a run halts.
+# file, nor when a run halts or did not write its -latest copy.
 # Useful for Slack notifications, dashboard ingest, CI hooks, or chaining a
 # downstream skill (audit, export, test). A failure is reported to the user
 # in one line and never fails the workflow; it does not reach the result

package/src/skf-update-skill/references/gap-driven.md

@@ -99,7 +99,7 @@ Read the gaps of the test report at `{test_report_path}` and translate them into
 
 - `stale-documentation` (the skill documents a name the source's enumerated surface lacks and that is not a documented extra, an Info `observation`): the source has no line to repair the name from, so a person removes its documentation when the name is gone from the source, fixes the brief's scope when the surface missed it, or, when the source still declares the name, keeps the documentation and re-runs Test Skill at a tier that classifies it.
 - `metadata-drift` (divergent export counts in the metadata): update-skill recounts `stats.exports_public_api`, `stats.exports_documented` and `stats.effective_denominator` each time it writes metadata.json, so a metadata patch to them does not hold (under `--allow-workspace-drift` and for a docs-only skill it keeps the recorded public API counts and `stats.effective_denominator` instead); Create Skill rebuilds diverging barrel counts from the source and recounts a `stats.effective_denominator` the brief's `scope.tier_a_include` set disagrees with (denominator drift), a person fixes denominator deflation on a brief with no tier A list by adding `scope.tier_a_include` to it, and documented-surface counts that differ by the `Type::method` entries the named-export count leaves out need no fix.
-- `provenance-unverified`: the line-check rules could not verify the line, or the recorded line is not a number, so a person checks by hand which line defines the export and, when it is not the recorded one, sets its provenance `source_line` to that line.
+- `provenance-unverified`: the line-check rules could not verify the line, or the recorded line is not a number, so a person checks by hand which line defines the export and, when it is not the recorded one, sets its provenance `source_line` to that line; when the gap names an alias, no line of the cited file defines the export, so a person records the rename in its provenance entry (`export_name` the name the alias renames, `reexported_as` the export) only when no other entry has that `export_name` and the alias does not rename a default export, and otherwise cites the alias line, as the remediation says.
 - `denominator-inflation`: it concerns the brief's scope and the count design, which a person decides in the skill brief, as the gap's remediation says.
 - `brief-scope-stale`: a person edits the brief's scope globs by hand so each matches the files it meant, since update-skill does not rewrite them.
 - `multi-denominator`: no fix is needed, since the barrel and the documented surface measure different sets by design and the report records both counts.

package/src/skf-update-skill/references/invocation-contract.md

@@ -9,4 +9,4 @@ The argument set, gate map, outputs and headless result line of `skf-update-skil
 | **Gates** | step 1: init.md §4's degraded-rebuild gate [D]/[X] when no provenance map is found (headless: halts, or takes [D] under `--allow-degraded`; a gap-driven run halts `blocked` there instead); init.md §4b's [G]/[S] test-report offer, interactive only (headless warns `unconsumed-test-report`); Confirm Gate [C] (init.md §8) | step 2, each only when triggered: detect-changes.md §1b's promote prompt and §1c's scope-expansion prompt [P]/[S]/[U] (headless: defers each candidate to a person), §2.2's deletion-ratio gate [C]/[B]/[A] (headless: [C]) | step 2g (gap-driven): gap-driven.md §1 rule R1's [D]/[R] for each gap whose remediation names removal (headless: [D], or [R] only when the export is internal or `#[doc(hidden)]`) | step 4: Confirm Gate [C] only after the user resolved [MANUAL] conflicts (merge.md §4); a clean merge auto-proceeds, and a headless run with conflicts halts `halted-for-manual-mismatch` before anything is written |
 | **Outputs** | A new version folder `{skill_group}/{new_version}/` and its forge folder, beside the unchanged previous version (a gap-driven repair writes the current version in place), and a finished run's `update-skill-result-{YYYYMMDD-HHmmss}.json` and `update-skill-result-latest.json` in that version's forge folder (a run that found no change: the current one's). `--detect-only` and `--dry-run` write none of these, nor the skill brief. Run state goes to a run folder under `{project-root}/_bmad-output/.skf-run/` that step 7 removes; a halt keeps it |
 | **Concurrency** | A second real update of the same skill halts `halted-for-concurrent-run` while the first holds its run lock (init.md §1b); `--detect-only` and `--dry-run` take no lock. write.md §8 halts with the same status when another flip of the `active` link holds its lock for 5 seconds. A remote skill is read from a private tree, and no mode writes to the shared workspace clone before write.md §9. |
-| **Headless** | No gate prompts: each resolves as the Gates row says, and the run records the decision. One `SKF_UPDATE_RESULT_JSON` line (report.md §5b), at step 6 or at a HALT, printed by the shared emitter and checked against `shared/scripts/schemas/skf-update-result-envelope.v1.json`. It is the run's last line: the shared health check displays it after everything else; a HALT displays its line and stops. Pipelines branch on `skf_update.status`: `success`, `no-changes`, `detect-only` and `dry-run` are successful exits. A caller reads the run's own `SKF_UPDATE_RESULT_JSON` line. A run that printed no envelope line has no result to read, whatever the process exit code: it was cut off, or could not write its result, and `update-skill-result-latest.json` may then describe an earlier run, so it is never read in its place. |
+| **Headless** | No gate prompts: each resolves as the Gates row says, and the run records the decision. One `SKF_UPDATE_RESULT_JSON` line (report.md §5b), at step 6 or at a HALT, printed by the shared emitter and checked against `shared/scripts/schemas/skf-update-result-envelope.v1.json`. It is the run's last line: the shared health check displays it after everything else; a HALT displays its line and stops. Pipelines branch on `skf_update.status`: `success`, `no-changes`, `detect-only` and `dry-run` are successful exits. A headless run whose emitter refused its result line for good ends on a `halted-for-write-failure` line instead, with `error.phase` `report:result-contract` and an `error.reason` that starts `result-contract-not-written`, and nothing it wrote is undone. A caller reads the run's own `SKF_UPDATE_RESULT_JSON` line. A run that printed no envelope line has no result to read, whatever the process exit code: it was cut off, or could not write its result, and `update-skill-result-latest.json` may then describe an earlier run, so it is never read in its place. |

package/src/skf-update-skill/references/merge.md

@@ -299,7 +299,7 @@ uv run {runLockHelper} acquire \
    ```
 
    It renames the staged folder to `{skill_group}/{new_version}/` in one step, so no reader ever sees a half-copied version.
-6. **Create the forge folder** `{forge_data_folder}/{skill_name}/{new_version}/` and copy `provenance-map.json`, `evidence-report.md` and `extraction-rules.yaml` from `{forge_version}` into it, each when it exists: step 5 updates the provenance map and appends this update to the evidence report there, and audit-skill reads the extraction rules there. Test reports, drift reports and result files belong to the version they were made for and stay where they are.
+6. **Create the forge folder** `{forge_data_folder}/{skill_name}/{new_version}/` and copy into it each of `provenance-map.json`, `evidence-report.md` and `extraction-rules.yaml`: from `{forge_version}` when it is there, else from `{forge_data_folder}/{skill_name}/` when it is there and init.md §4 bound `{provenance_map_path}` to that flat folder's map (an older skill's flat forge data, `knowledge/version-paths.md`). Copy, never move: the previous version's files and the flat ones stay as they are. Step 5 updates the provenance map and appends this update to the evidence report there; the extraction rules record how the skill was extracted. Test reports, drift reports and result files belong to the version they were made for and stay where they are.
 7. **Rebind** `{skill_package}` ← `{skill_group}/{new_version}/{skill_name}` and `{forge_version}` ← `{forge_data_folder}/{skill_name}/{new_version}`. Every later step reads and writes the new version there; `{manual_inventory}` keeps the amended path §4 bound.
 
 If no `{atomicWriteProbeOrder}` candidate resolves, or the stage, copy, write, publish or forge-folder step fails, HALT with status `halted-for-write-failure`, naming the failed step (for a missing helper: "skf-atomic-write.py is missing; re-install SKF"). The halt procedure takes `phase: "merge:new-version-folder"`, `path: "{skill_group}/{new_version}"`, `reason: "<the failed step>: <its error>"`; its rollback removes what this section created, `{version_staging}`, `{skill_group}/{new_version}/` and `{forge_data_folder}/{skill_name}/{new_version}/`, none of which existed before `begin` recorded them. The previous version is unchanged.