bmad-module-skill-forge 6.0.0 → 7.0.0

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

@@ -21,8 +21,9 @@ 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`,
@@ -71,11 +72,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 +435,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$]*")
@@ -650,6 +731,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 +889,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 +912,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 +927,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 +940,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/report.md

@@ -267,20 +267,27 @@ It writes the per-run record `{forge_version}/update-skill-result-{YYYYMMDD-HHmm
 SKF_UPDATE_RESULT_JSON: {"skf_update": {"status": "success", "skill_name": ..., "version": ..., "previous_version": ..., "update_mode": ..., "files_written": [...], "headless_decisions": [...], "warnings": [...], "error": null}}
 ```
 
-In `{headless_mode}`, bind `{result_envelope_line}` to that line and do not display it here: the shared health check displays it verbatim as the run's last line. An interactive run runs the command for its result files and need not show the line. When the emitter exits non-zero and its `message` names the payload, fix the payload once and run it again; a write it could not make adds `result_file_write_failed` to the line's `warnings[]`.
+In `{headless_mode}`, bind `{result_envelope_line}` to that line and do not display it here: the shared health check displays it verbatim as the run's last line. An interactive run runs the command for its result files and need not show the line. When the emitter exits non-zero and its `message` names the payload, fix the payload once and run it again; a write it could not make adds `result_file_write_failed` to the line's `warnings[]`. When the emitter exits non-zero and no retry applies, or fails again, or no path resolved for `{emitEnvelopeHelper}`, this run has no result contract: display its `message` (or that the emitter is missing), bind no `{result_envelope_line}`, and skip the hook as below.
 
 - `status`: `"success"` here; §1 stages `"no-changes"`, §1a `"detect-only"` and §1b `"dry-run"`; a halt prints its own `halted-for-*` or `blocked` line through its step's halt procedure and never reaches this step. The full enum lives in the schema.
 - `files_written[]`: `references` stands for every `references/*.md` file of the package this run wrote, added or removed, one value however many: merge.md §6b's merge, at any priority, write.md §6's provenance fixes and write.md §7's body split. Read it from the files on disk, never from memory: a `references/` path in the `files_written[]` write.md §6's provenance `fix` printed; a file the `Body split` row lists in this run's `## Update Operation` section of `{forge_version}/evidence-report.md`, the one write.md §4 appended, never an earlier update's; outside gap-driven mode, a `references/*.md` file that `{skill_package}` and the previous version's package (`{skill_group}/{baseline_version}/{skill_name}/references/`) do not hold alike, one lacking it or the two differing; in gap-driven mode, which repairs the version in place, a file in `{run_dir}/references/`, where merge.md §6b staged each one it wrote, or a path `{run_dir}/references-removed.txt` lists.
 - `headless_decisions[]`: every gate's record in the run's decision log (init.md §4 degraded-rebuild and §8 confirmation, detect-changes.md §1b / §1c / §2.2, gap-driven.md §1 rule R1, merge.md §8). Each entry `{gate, default_action, taken_action, reason, evidence?}`. Empty when no gate auto-resolved.
 - `error`: null on every exit this step prints. A halt's line carries `{phase, path?, reason}`, and pipelines branch on `error !== null` for non-zero exit semantics.
-- `warnings[]`: every entry the run recorded, among them `source-tree:`, `source-not-fetched`, `file-diff-unavailable`, `no-baseline-time`, `moved-check-skipped` and `unknown-language` (detect-changes.md §2.1 Category A), `new-files-not-checked` (Category D: a skill with no brief, so no new script or asset was looked for), `source-version-lower`, `unconsumed-test-report` (init.md §4b), `interrupted-run-cleaned` and `interrupted-run-not-cleaned` (init.md §1b), `test-report:` entries (what the test report's helpers could not read, and `test-report: not routed: {id} ({category}): {reason}` for each gap gap-driven.md §1 did not route), `proposed-amendment:` (a read-only run's brief decisions, not written), `doc-fetch-failed`, `doc-not-hashed` and `doc-drift-not-checked` (a docs-only skill's documents), `workspace-clone-not-updated`, `target-ref-not-recorded`, `workspace_drift_overridden` (gap-driven.md §3), `run-state-not-finished`, `public-api-counted-by-hand:` (write.md §2: the recipe runner exited 2, so the public names were found without it; it quotes the runner's error line) and `provenance:` entries (write.md §3 and §6: provenance findings left for a person, and spot-check entries §3 left for a person to decide).
+- `warnings[]`: every entry the run recorded, among them `source-tree:`, `source-not-fetched`, `file-diff-unavailable`, `no-baseline-time`, `moved-check-skipped` and `unknown-language` (detect-changes.md §2.1 Category A), `new-files-not-checked` (Category D: a skill with no brief, so no new script or asset was looked for), `source-version-lower`, `unconsumed-test-report` (init.md §4b), `interrupted-run-cleaned` and `interrupted-run-not-cleaned` (init.md §1b), `test-report:` entries (what the test report's helpers could not read, and `test-report: not routed: {id} ({category}): {reason}` for each gap gap-driven.md §1 did not route), `proposed-amendment:` (a read-only run's brief decisions, not written), `doc-fetch-failed`, `doc-not-hashed` and `doc-drift-not-checked` (a docs-only skill's documents), `workspace-clone-not-updated`, `target-ref-not-recorded`, `workspace_drift_overridden` (gap-driven.md §3), `run-state-not-finished`, `result_file_write_failed` (a result file the emitter could not write; the hook then does not run), `public-api-counted-by-hand:` (write.md §2: the recipe runner exited 2, so the public names were found without it; it quotes the runner's error line) and `provenance:` entries (write.md §3 and §6: provenance findings left for a person, and spot-check entries §3 left for a person to decide).
 
-**Post-finalization hook.** A finished run, this one or §1's no-change exit, fires the hook; `--detect-only`, `--dry-run` and a halt never do (customize.toml says so). If `{onCompleteCommand}` (resolved in SKILL.md On Activation §4 from `workflow.on_complete`) is non-empty, invoke it after the emitter wrote both result files:
+**Post-finalization hook.** A finished run, this one or §1's no-change exit, fires the hook; `--detect-only`, `--dry-run` and a halt never do (customize.toml says so). If `{onCompleteCommand}` (resolved in SKILL.md On Activation §4 from `workflow.on_complete`) is non-empty, the emitter exited 0 and the line's `warnings[]` hold no entry that starts with `result_file_write_failed` (the emitter wrote both result files), invoke it:
 
 ```bash
 {onCompleteCommand} --result-path={forge_version}/update-skill-result-latest.json
 ```
 
+The line has no `result_path`: any `result_file_write_failed` entry means this run's `update-skill-result-latest.json` was not written, since the emitter stops at the first write that fails. An interactive run reads the line for this check without displaying it. When `{onCompleteCommand}` is non-empty but the hook does not run, skip it and say why:
+
+- The run has no result contract (above): "on_complete skipped: no result contract was written ({the reason})".
+- The line holds such an entry: "on_complete skipped: `update-skill-result-latest.json` was not written."
+
+The hook never gets a `-latest` copy this run failed to write.
+
 Run it with a bounded timeout (default 60s). On success, log an Info note and continue; on non-zero exit, timeout, or any failure, tell the user in one line with the reason (the line and the result files are written before the hook runs, so they cannot carry its failure) and continue. The hook must never fail the workflow: it is integration glue (notify a CI router, chain audit/export/test) orthogonal to the update outcome. Empty `{onCompleteCommand}` = no-op, no log entry.
 
 ### 6. Chain to Health Check

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

@@ -461,7 +461,7 @@ Do not rely on per-call ad-hoc preservation logic: use the helper.
 
 **If skill-check is available:**
 
-- Run `npx skill-check check "{skill_package}" --fix --format json` **inside the §0 guard**. One call validates the package against the spec, scores it, fixes what has one answer and runs the security scan (on unless `--no-security-scan` is passed). Read the JSON, not the exit code: the quality score (`scores[].score`, the entry matching the skill, or a top-level `qualityScore` on an older skill-check), the remaining `diagnostics[]`, `fixed[]` and the security findings. When the scan could not run (no `SNYK_TOKEN`), record `Security: SKIP (SNYK_TOKEN not configured)`.
+- Run `npx skill-check check "{skill_package}" --fix --format json` **inside the §0 guard**. One call validates the package against the spec, scores it, fixes what has one answer and runs the security scan (on unless `--no-security-scan` is passed). Read the JSON, not the exit code: the quality score (`scores[].score`, the entry matching the skill, or a top-level `qualityScore` on an older skill-check), the remaining `diagnostics[]`, `fixed[]` and the security findings. When the scan could not run (no `SNYK_TOKEN`: skill-check exits non-zero and its stderr names `SNYK_TOKEN`), record `Security: SKIP (SNYK_TOKEN not configured)`.
 - **Context sync after --fix:** if `fixed[]` is non-empty, re-read the SKILL.md `--fix` changed into the in-context copy, so the report does not work from a copy that differs from the file on disk. The §0 guard has already restored `description` if it diverged.
 - If `body.max_lines` or `body.max_tokens` is reported, split the body selectively with `{shardBodyHelper}` (resolve it ← first existing path in `{shardBodyProbeOrder}`), **inside the §0 guard**: from `{project-root}`, run `uv run {shardBodyHelper} "{skill_package}/SKILL.md" --budget 400 --word-budget 4500 --skip-manual`, with `--budget 500` in place of `--budget 400` when only `body.max_tokens` is reported. It moves the largest Tier 2 (`## Full`) sections to `references/`, each replaced by a `> See` pointer to a file it never overwrites, until the body is within that many lines and 4,500 words, the same headroom under skill-check's 5,000 that 400 lines leave under its 500, and keeps Tier 1 inline (inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval). **Never move a section that holds a `[MANUAL]` block:** init.md §5 inventories SKILL.md only, so a block moved to `references/` would leave the next update's inventory; `--skip-manual` keeps the helper off every section a block reaches into. No Tier 1 content is trimmed, and `split-body` never runs after the helper. Add each WARN below to `warnings[]` as well. Act on its report:
   - **Exit 1 or 2, or no JSON:** HALT with status `blocked` (halt procedure: `phase: "write:body-split"`, `path: "{skill_package}/SKILL.md"`, `reason: "body split failed: {its stderr line}"`). On exit 2 that line ends `already written: {each references/*.md file it wrote before the failure, or none}`: name each of those files in the halt message.