bmad-module-skill-forge 5.0.0 → 6.0.0

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

@@ -16,17 +16,27 @@ ratios and the gap records of the wrong signatures.
   plan   the comparisons to make. For each documented export with a
          signature (an inventory entry of any kind but `method` that carries
          `params`, `return_type` or `usage_signature`; a function's `params`
-         counts when empty, its form for one that takes none) in the
-         signature universe, grouped by source file, with the line that
-         defines it in the source and the documented signature (with the
-         entry's `signature_form` when it has one; of several entries of one
-         name, one that lists parameters or gives a usage form before one
-         that does neither, then a full one before a partial one, then, of
-         two full or two partial forms, one that lists parameters before one
-         that gives only a usage form, else the first). The signature
-         universe is the surface's `all` set plus every name on its export
-         records, so the names of a Python sub-package load-coverage-inputs.py
-         keeps out of `all` (excluded.nestedEntries) keep their checks. A check sits at the
+         counts when empty, its form for one that takes none; a `constant`
+         holding a component carries the form the skill writes as
+         `usage_signature`, references/inventory-contract.md says, and a data
+         constant none) in the signature universe, grouped by source file,
+         with the line that defines it in the source, the documented
+         signature (with the entry's `signature_form` when it has one; of
+         several entries of one name, one that lists parameters or gives a
+         usage form before one that does neither, then a full one before a
+         partial one, then, of two full or two partial forms, one that lists
+         parameters before one that gives only a usage form, else the first)
+         and, as `alternatives`, the name's other distinct forms that list
+         parameters or give a usage form, in that order: the judge compares
+         the declaration with each, by its own reading rules, and reports a
+         mismatch for each form that does not match, naming it as `form`. A
+         form that lists no member is never an alternative, and two entries
+         that say the same thing are one form (a `full` label and none, a
+         list and its items joined with `, `, whitespace runs; of two that
+         differ only by the partial label, the full one). The signature universe is the
+         surface's `all` set plus every name on its export records, so the
+         names of a Python sub-package load-coverage-inputs.py keeps out of
+         `all` (excluded.nestedEntries) keep their checks. A check sits at the
          name's first surface record (one with a file before one with none
          or a blank one). For a name the surface records in more than one
          file, --skill-dir (the skill package) picks the record whose file
@@ -34,8 +44,8 @@ ratios and the gap records of the wrong signatures.
          (validate-inventory.py's _skill_cited_files) when exactly one of
          those files is cited; otherwise the check stays at the first record
          and lists every record with a file as `candidates` for the judge to
-         read. Also the whole documented-signature map, for the fallback scan
-         that has no surface lines yet.
+         read. Also the whole documented-signature map, and each name's
+         alternatives, for the fallback scan that has no surface lines yet.
   score  the categories. Reads every subagent result, checks its schema,
          and computes:
            Signature Accuracy = matching / compared * 100, where compared is
@@ -51,8 +61,13 @@ ratios and the gap records of the wrong signatures.
              interface) and documented types those the inventory documents
          A category with nothing to compare scores 100 (nothing documented
          is wrong) and says so in `warnings`. Each signature mismatch of a
-         compared name is graded (grade()) and becomes a record in the gap
-         ledger's record format (gap-ledger.py append --input reads
+         compared name is graded (grade()) against the documented form its
+         `form` names (0, or none, the check's `documented`; n its nth
+         `alternatives` entry; an index past the name's forms is listed in
+         `warnings` and graded against `documented`), by that form's own
+         `signature_form`. With --plan the forms are the plan's (a name whose
+         forms differ from the inventory's is listed in `warnings`). Each
+         becomes a record in the gap ledger's record format (gap-ledger.py append --input reads
          --gaps-output). The judge's `difference` tag alone never lowers a
          grade: the script checks the fact each one rests on.
            Low `signature-mismatch`  `difference` "parameter-name" reported
@@ -65,6 +80,58 @@ ratios and the gap records of the wrong signatures.
            Info `observation`, titled `Partial signature: {name}`
              `difference` "omitted-optional" on a documented signature whose
              inventory entry is `signature_form` "partial"
+           Info `observation`, titled `Annotation contradicted: {name}`
+             `difference` "annotation-contradicted" (the documented return
+             type is the one the body returns, the declared annotation says
+             otherwise) whose facts check: the documented entry states a
+             return type (a non-blank `return_type`, or a `documented_sig`
+             that writes one); `documented_sig` and `source_sig` write the
+             same parameters as signature-comparison-rules.md reads them
+             (_parameter_difference, below); `evidence_line` comes after the
+             declaration line (of the name's surface records at the
+             mismatch's file, the closest at or before the mismatch's
+             `line`, else the first; with none, the mismatch's `line`) and
+             before the next surface record in that file; and, with
+             --source-root, that line of the file under it starts with
+             `return`, or is the declaration line itself with its
+             expression body after its parameters (an arrow function's
+             `=> expr`, a Python `def ...: return x`). The parameters are
+             read from each one's parameter group, past a decorator's, a Go
+             receiver's or a C++ `operator()`'s group (a qualifier such as
+             `noexcept(...)` after a group leaves it the parameter group),
+             and compared by name and in order, by name alone after a `*`
+             marker; by type wherever both write one, with the common
+             Equivalent spellings (_type_key), a documented type that names
+             some members of the source's union included, and, in a TS/JS
+             file, with a literal default's type for a source parameter
+             that writes none; by optionality when the documented list
+             states one for some member; and by the type parameters both
+             write before the group. A list of bare names need not write an
+             optional parameter (unless leaving it out shifts a caller's
+             positions in a POSITIONAL_EXTENSIONS file), and one holding an
+             ellipsis claims nothing about what it stands for. A keyword or
+             name before the group, a default's value, a `*` or `/` marker,
+             the names of `*args` and `**kwargs`, and a leading receiver the
+             source writes (`self`, `cls`, `&self`, `this: T`) are never
+             compared; the documented list's own receiver is dropped only
+             when the source's list leads with one too, so a module-level
+             function whose first parameter is named `self` or `cls` is read
+             as a method. A signature with no group, on either side, is
+             compared by the text before its return. Still refused, on the
+             strict side, where the rules would read the two as one: type
+             variables renamed consistently, a type alias against the type
+             it names, an overload set, a union of callables against one
+             callable returning the union, a call example's `name=value`
+             (read as a default, so its list claims to be complete) or
+             positional literal (`RecursiveSplitter(512)`, read as a name),
+             a destructured parameter (compared as one name, so the order of
+             its properties and the ones it leaves out count), a parameter
+             in another language's order (Go's `id string`, C's `int n`,
+             read as one name), and a `;`-joined text, read as written. Its
+             remediation changes nothing in the skill: the annotation is
+             reported upstream. A tagged mismatch whose facts do not check is
+             graded as an untagged one, and `warnings` names the fact that
+             failed
            Critical `signature-mismatch`  every other mismatch
          A mismatch's `file` (normalized: `/` separated, no `./`) is the file
          it is graded and recorded at (the gap's Source) when the plan
@@ -74,10 +141,19 @@ ratios and the gap records of the wrong signatures.
          the result's `file` stands, as it does when there is none. Results
          that report one declaration (name, file and line) more than once
          keep its most severe grade: Critical, then Low, then Info. Of the
-         mismatches of a check that offered several files, the least severe
-         stands (the closest candidate), the first by file and line on a
-         tie: one documented signature, one gap. A Low or an Info mismatch
-         still counts as matching. A mismatch a result reports for any
+         mismatches of one form of a check that offered several files, the
+         least severe stands (the closest candidate), the first by file and
+         line on a tie: one documented form, one gap. Each form's mismatch
+         stands on its own (each usage of a `usage_signature` list too: the
+         mismatch's `documented_sig` is part of the declaration's key), and
+         a gap of a name with several forms names its form, counted from 1,
+         in its title (`Signature mismatch: {name} (form n of m)`) and its
+         Issue. For such a name the form's own label lowers a grade only when
+         the mismatch's `documented_sig` is that form's text (whitespace runs
+         as one, outer parentheses off, a list joined): otherwise `warnings`
+         says so and the mismatch is graded against the form it quotes, or
+         `documented` when it quotes none. A Low or an Info mismatch still
+         counts as matching. A mismatch a result reports for any
          other name (one the skill does not document, or the surface lacks)
          is listed in `warnings` instead, and no gap.
 
@@ -96,44 +172,62 @@ Inputs, all files in the run folder:
                   "types_found": ["..."],       (fallback scan only)
                   "signature_mismatches": [
                     {"name", "line", "source_sig", "documented_sig", "issue",
-                     "difference", "file"}]}  (difference optional: one of
+                     "difference", "file", "evidence_line", "form"}]}
+                                      (difference optional: one of
                                        DIFFERENCES, absent or null for none;
                                        file optional: the candidate the
                                        mismatch was found at, a non-empty
                                        string, absent or null for the
-                                       result's `file`)
+                                       result's `file`; evidence_line, the
+                                       body line that returns the documented
+                                       type, an integer from 1, required
+                                       with "annotation-contradicted" and
+                                       refused with any other difference;
+                                       form optional: the index of the
+                                       documented form the mismatch is
+                                       reported for, an integer from 0
+                                       (`documented`; n the check's nth
+                                       `alternatives` entry), absent or null
+                                       for 0)
   --skill-dir  plan only: the skill package under test (the folder that
                holds SKILL.md), whose citations pick the declaration of a
                name the surface records in several files
   --plan       score only: the plan's output, whose checks name the files a
                mismatch of each name may be recorded at
+  --source-root  score only: the local source tree the judges read (a
+               drifted workspace included), where an annotation-contradicted
+               mismatch's `evidence_line` is checked in its file
 
 Rounding is compute-score.py's (JS-compatible half-up, two decimals).
 
 Usage:
   uv run score-signatures.py plan --inventory <file> [--surface <file>] [--skill-dir <dir>] [--output <file>]
   uv run score-signatures.py score --inventory <file> --surface <file> [--surface-set <set>] [--plan <file>] \\
-      --results <file> [--results <file> ...] [--output <file>] [--gaps-output <file>]
+      [--source-root <dir>] --results <file> [--results <file> ...] [--output <file>] [--gaps-output <file>]
 
 Output (stdout; --output also writes it, --gaps-output writes the records):
   plan:  {"compared": N, "files": [{"file", "checks": [{"name", "line",
-          "signatureLine", "documented": {...}, "candidates": [{"file",
-          "line", "signatureLine"}] (only when the citation does not settle
-          the declaration)}]}], "documentedSignatures": {...}}
+          "signatureLine", "documented": {...}, "alternatives": [{...}]
+          (only when the name has another form that lists members),
+          "candidates": [{"file", "line", "signatureLine"}] (only when the
+          citation does not settle the declaration)}]}],
+          "documentedSignatures": {...}, "documentedAlternatives": {name:
+          [{...}], for each name with alternatives}}
   score: {"valid": true, "signatureAccuracy", "matchingSignatures",
           "totalDocumented", "comparedNames": [the names compared],
           "typeCoverage", "documentedTypes", "totalTypes",
           "missingTypes": [...], "mismatches": [{"name", "file", "line",
           "source_sig", "documented_sig", "issue", "difference" (null for
-          none), "severity" (Critical, Low or Info)}], "gapRecords": [...],
+          none), "evidence_line" (with "annotation-contradicted" alone),
+          "severity" (Critical, Low or Info)}], "gapRecords": [...],
           "warnings": [...]}
          or {"valid": false, "violations": [...]} when a result breaks the schema
 
 Exit codes:
   0  the result was printed
   1  an input file cannot be read or is not the JSON it should be, the
-     surface has no --surface-set set, or the --skill-dir folder holds no
-     readable SKILL.md
+     surface has no --surface-set set, the --skill-dir folder holds no
+     readable SKILL.md, or the --source-root folder does not exist
   2  a subagent result breaks the schema (violations[] names each breach;
      nothing is written to --output or --gaps-output)
 """
@@ -144,6 +238,7 @@ import argparse
 import importlib.util
 import json
 import math
+import re
 import sys
 from pathlib import Path, PurePosixPath
 
@@ -152,10 +247,63 @@ from pathlib import Path, PurePosixPath
 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 (coverage-check.md
-# section 2): only the parameter names differ, or only members the documented
-# form leaves out that the source marks optional.
-DIFFERENCES = ("parameter-name", "omitted-optional")
+# The optional `difference` a judge tags a mismatch with, defined in
+# references/signature-comparison-rules.md (Difference tags): only the
+# parameter names differ, only members the documented form leaves out that
+# the source marks optional, or only a return annotation the body contradicts
+# (the body returns the documented type at the mismatch's `evidence_line`).
+DIFFERENCES = ("parameter-name", "omitted-optional", "annotation-contradicted")
+CONTRADICTED = "annotation-contradicted"
+# grade()'s default: an annotation-contradicted mismatch whose facts no one checked stays Critical.
+UNCHECKED = "its facts were not checked"
+# A body line that returns starts with the `return` keyword. The declaration
+# line itself returns when its expression body follows its parameters: an
+# arrow function assigned with `=` or `export default` (`=> expr`, not a
+# `{` block), or a Python `def ...: return x`. A `type` alias's arrow is a type.
+RETURN_START_RE = re.compile(r"return(?![\w$])")
+ARROW_OPENER_RE = re.compile(r"(?:=|\bdefault)\s*(?:async\s*)?(?:<[^()]*>\s*)?\(")
+ARROW_BODY_RE = re.compile(r"\s*(?::[^=]*)?=>\s*[^\s{]")
+PYTHON_DEF_RE = re.compile(r"(?:async\s+)?def\s+\w+\s*\(")
+PYTHON_BODY_RE = re.compile(r"\s*(?:->[^:]*)?:\s*return(?![\w$])")
+TYPE_DECLARATION_RE = re.compile(r"(?:export\s+)?(?:declare\s+)?type\s")
+# Where a signature's return type starts, with no parenthesized parameters.
+RETURN_ARROW_RE = re.compile(r"->|=>|→")
+# The prefixes a type is compared without, as signature-comparison-rules.md's Equivalent spellings reads a name
+# with or without one: `typing.List[int]` is `List[int]`, `React.ReactNode` is `ReactNode`.
+TYPE_PREFIX_RE = re.compile(r"(?<![\w.$])(?:typing|collections\.abc|React)\.")
+# The `typing` names Equivalent spellings reads as the builtins they alias.
+TYPING_ALIASES = {"List": "list", "Dict": "dict", "Tuple": "tuple", "Set": "set", "FrozenSet": "frozenset",
+                  "Type": "type"}
+# A quoted forward reference (`"Node"`), read as the type it quotes.
+FORWARD_REFERENCE_RE = re.compile(r"(['\"])([A-Za-z_][^'\"]*)\1")
+# The name a type starts with, before its type arguments (`dict[str, Any]`, `Promise<T>`).
+TYPE_NAME_RE = re.compile(r"[A-Za-z_$][\w.$]*")
+# A Rust lifetime's `'a`, followed by whitespace, `,`, `>`, `+`, `)` or the end (_lifetime says where it stands).
+LIFETIME_RE = re.compile(r"'[A-Za-z_]\w*(?=[\s,>+)]|$)")
+# Each closing bracket and the opening one it closes (_levels: a `>` closes only a `<`).
+CLOSERS = {")": "(", "]": "[", "}": "{"}
+OPENERS = {"(": ")", "[": "]", "{": "}", "<": ">"}
+# A group a decorator or a Java annotation writes: the text before it ends with `@name`.
+DECORATED_RE = re.compile(r"@[\w.$]+\s*$")
+# What follows a prefix group: another `(` with no space between (C++ `operator()(int x)`), or a name and a `(`
+# after whitespace (a Go receiver, `func (s *Server) Start(port int)`), the name no C or C++ qualifier that takes
+# arguments after a parameter group (`f(int x) noexcept(true)`).
+PREFIX_GROUP_RE = re.compile(r"\(|\s+(?!(?:noexcept|throw|__attribute__|requires|decltype)\b)[A-Za-z_$][\w$]*\s*\(")
+# A receiver a method's parameter list may lead with: Python's `self` and `cls`, Rust's `self`, `&self`,
+# `&mut self` and `mut self` (with a lifetime too, `&'a self`), and TS's `this: T` (_parameter_difference).
+RECEIVER_RE = re.compile(r"self|cls|this|mut self|&(?:'\w+ )?(?:mut )?self")
+# An ellipsis item, standing for parameters a form does not show (a TS/JS rest `...name` is none).
+ELLIPSES = ("...", "…")
+# The TS/JS source files, where a parameter with no type and a literal default has that literal's type.
+TS_JS_EXTENSIONS = frozenset({".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"})
+# A literal default's type (signature-comparison-rules.md, Annotations): a bigint, a number, a string or template
+# literal, a boolean.
+LITERAL_TYPES = (
+    (re.compile(r"[-+]?(?:0[xob][\da-f_]+|\d[\d_]*)n", re.I), "bigint"),
+    (re.compile(r"[-+]?(?:0[xob][\da-f_]+|(?:\d[\d_]*(?:\.[\d_]*)?|\.\d[\d_]*)(?:e[-+]?\d+)?)", re.I), "number"),
+    (re.compile(r"(['\"`]).*\1", re.S), "string"),
+    (re.compile(r"true|false"), "boolean"),
+)
 # Source files of the languages with no keyword arguments, where a caller
 # never writes a parameter's name: TS/JS, Go, Rust, Java, C and C++. Not
 # Python, which has keyword arguments (the script cannot see which
@@ -260,6 +408,26 @@ def load_plan(path: str) -> dict[str, list[str]]:
     return offered
 
 
+def load_plan_forms(path: str) -> dict[str, list[dict]]:
+    """{name: the documented forms plan offered it, `documented` first, then
+    its `alternatives`} from plan's output: its documentedSignatures and
+    documentedAlternatives maps (the fallback scan's), then each check's."""
+    data = _read_json(path, "--plan")
+    data = data if isinstance(data, dict) else {}
+    signatures, alternatives = data.get("documentedSignatures"), data.get("documentedAlternatives")
+    alternatives = alternatives if isinstance(alternatives, dict) else {}
+    pairs = [(n, d, alternatives.get(n)) for n, d in (signatures.items() if isinstance(signatures, dict) else [])]
+    for group in data.get("files") if isinstance(data.get("files"), list) else []:
+        checks = group.get("checks") if isinstance(group, dict) else None
+        pairs += [(c.get("name"), c.get("documented"), c.get("alternatives"))
+                  for c in (checks if isinstance(checks, list) else []) if isinstance(c, dict)]
+    forms: dict[str, list[dict]] = {}
+    for name, documented, others in pairs:
+        if isinstance(name, str) and isinstance(documented, dict):
+            forms[name] = [documented, *(f for f in (others if isinstance(others, list) else []) if isinstance(f, dict))]
+    return forms
+
+
 def check_result(item: object, where: str) -> list[str]:
     """The schema breaches of one per-file result object."""
     if not isinstance(item, dict):
@@ -293,9 +461,22 @@ def check_result(item: object, where: str) -> list[str]:
         if entry.get("difference") is not None and entry["difference"] not in DIFFERENCES:
             errors.append(f"{at}: `difference` must be one of {', '.join(DIFFERENCES)} when present, "
                           f"not {json.dumps(entry['difference'])}")
+        # The body line that returns the documented type: the fact an annotation-contradicted mismatch rests on.
+        evidence = entry.get("evidence_line")
+        if entry.get("difference") == CONTRADICTED:
+            if isinstance(evidence, bool) or not isinstance(evidence, int) or evidence < 1:
+                errors.append(f"{at}: `evidence_line` must be a line number (an integer from 1) with `difference` "
+                              f"{CONTRADICTED}, not {json.dumps(evidence)}")
+        elif evidence is not None:
+            errors.append(f"{at}: `evidence_line` is given only with `difference` {CONTRADICTED}, "
+                          f"not {json.dumps(entry.get('difference'))}")
         # The candidate a mismatch was found at, when the plan handed the judge several.
         if entry.get("file") is not None and not (isinstance(entry["file"], str) and entry["file"].strip()):
             errors.append(f"{at}: `file` must be a non-empty string when present, not {json.dumps(entry['file'])}")
+        # The documented form a mismatch is reported for, when the check offered `alternatives`.
+        form = entry.get("form")
+        if form is not None and (isinstance(form, bool) or not isinstance(form, int) or form < 0):
+            errors.append(f"{at}: `form` must be an index (an integer from 0) when present, not {json.dumps(form)}")
     return errors
 
 
@@ -369,29 +550,72 @@ def _rank(fields: dict) -> tuple[bool, bool, bool]:
     return not _lists_members(fields), _partial(fields), not _lists_params(fields)
 
 
-def documented_signatures(inventory: list[dict]) -> dict[str, dict]:
-    """{name: its documented signature fields} for each documented export
-    with one, with the entry's `signature_form` when it has one. Of several
-    entries of one name, one that lists parameters or gives a usage form
-    (_lists_members) is compared before one that does neither (empty or no
-    `params` and no usage form: it never hides one that says what the name
-    takes), then a full one (no `signature_form`, or `full`) before a
-    partial one (a form the skill also gives in full is held to it), then,
-    of two full or two partial forms, one that lists parameters is
-    compared before one that gives only a usage form, else the first."""
-    out: dict[str, dict] = {}
+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}
+    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)
+
+
+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]))
+
+
+def documented_forms(inventory: list[dict]) -> dict[str, list[dict]]:
+    """{name: [its documented signature, *its alternatives]} for each
+    documented export with a signature: its distinct forms (_form), ranked.
+    Of several entries of one name, one that lists parameters or gives a
+    usage form (_lists_members) is compared before one that does neither
+    (empty or no `params` and no usage form: it never hides one that says
+    what the name takes), then a full one (no `signature_form`, or `full`)
+    before a partial one (a form the skill also gives in full is held to
+    it), then, of two full or two partial forms, one that lists parameters
+    is compared before one that gives only a usage form, else the first.
+    The first is the documented signature; the others that list members
+    follow it, in that order, as the alternatives the judge compares too (a
+    skill that documents a name briefly in one place and in full in
+    another). A form that lists no member is never an alternative. Two
+    entries that say the same thing (_form_key) are one form; of two that
+    differ only by the partial label, the full one (the stricter) stands."""
+    entries: dict[str, list[dict]] = {}
     for entry in inventory:
         name = entry.get("name")
         if entry.get("kind") == "method" or not (isinstance(name, str) and name) or not _has_signature(entry):
             continue
-        fields = {f: entry[f] for f in SIGNATURE_FIELDS if f in entry}
-        if entry.get("signature_form") is not None:
-            fields["signature_form"] = entry["signature_form"]
-        if name not in out or _rank(fields) < _rank(out[name]):
-            out[name] = fields
+        forms, fields = entries.setdefault(name, []), _form(entry)
+        same = next((i for i, f in enumerate(forms) if _form_key(f) == _form_key(fields)), None)
+        if same is None:
+            forms.append(fields)
+        elif _partial(forms[same]) and not _partial(fields):
+            # in the inventory order the full entry has, as the rank would have ordered it
+            del forms[same]
+            forms.append(fields)
+    out: dict[str, list[dict]] = {}
+    for name, forms in entries.items():
+        first, *others = sorted(forms, key=_rank)  # stable: of forms that rank alike, inventory order
+        out[name] = [first, *(f for f in others if _lists_members(f))]
     return out
 
 
+def documented_signatures(inventory: list[dict]) -> dict[str, dict]:
+    """{name: its documented signature fields}: the first of its
+    documented_forms, the one a check holds as `documented`."""
+    return {name: forms[0] for name, forms in documented_forms(inventory).items()}
+
+
 def documented_names(inventory: list[dict]) -> set[str]:
     return {e["name"] for e in inventory
             if isinstance(e.get("name"), str) and e["name"] and e.get("kind") != "method"}
@@ -451,29 +675,35 @@ def plan(inventory: list[dict], names: list[str] | None, exports: list[dict], sk
     """The comparisons over the signature universe of `names` (the `all`
     set) and `exports`; none without a surface (`names` None). `skill_dir`,
     the skill package, settles which declaration a name the surface records
-    in several files is compared with (_check_at)."""
-    signatures = documented_signatures(inventory)
+    in several files is compared with (_check_at). A name documented in
+    several forms carries the others that list members as `alternatives`
+    (documented_forms)."""
+    forms = documented_forms(inventory)
     files: dict[str, list[dict]] = {}
     compared = 0
     if names is not None:
         by_name = _records_by_name(exports)
         texts = _inventory().skill_markdown_lines(Path(skill_dir)) if skill_dir is not None else None
-        for name in sorted(signature_universe(names, exports) & set(signatures)):
+        for name in sorted(signature_universe(names, exports) & set(forms)):
             record, candidates = _check_at(name, by_name.get(name) or [], skill_dir, texts)
             compared += 1
             check = {
                 "name": name,
                 "line": record.get("line"),
                 "signatureLine": record.get("signatureLine"),
-                "documented": signatures[name],
+                "documented": forms[name][0],
             }
+            if len(forms[name]) > 1:
+                check["alternatives"] = forms[name][1:]
             if candidates:
                 check["candidates"] = candidates
             files.setdefault(_record_file(record), []).append(check)
     return {
         "compared": compared,
         "files": [{"file": f, "checks": checks} for f, checks in sorted(files.items())],
-        "documentedSignatures": signatures,
+        "documentedSignatures": documented_signatures(inventory),
+        # The fallback scan's alternatives: a name's form n is its nth entry here, as in a check's `alternatives`.
+        "documentedAlternatives": {name: fs[1:] for name, fs in forms.items() if len(fs) > 1},
     }
 
 
@@ -502,20 +732,545 @@ def _is_offered_file(files: list[str], file: str) -> bool:
     return _path(file) in {_path(f) for f in files}
 
 
-def grade(difference: str | None, file: str, documented: dict, declared: str | None = None) -> str:
+def _is_line(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool) and value >= 1
+
+
+def _lines_in(exports: list[dict], file: str) -> list[int]:
+    """The lines of the surface records in `file`, however either writes its path."""
+    return [r["line"] for r in exports
+            if _record_file(r) and _path(_record_file(r)) == _path(file) and _is_line(r.get("line"))]
+
+
+def _declaration_line(by_name: dict[str, list[dict]], name: str, file: str, line: int) -> int:
+    """The line `name` is declared at in `file`: of its surface records there
+    (the plan's check, or the candidate it offered), the closest one at or
+    before the mismatch's `line` (a name declared twice in one file), else
+    the first; with none there, the mismatch's own `line`."""
+    lines = _lines_in(by_name.get(name) or [], file)
+    before = [at for at in lines if at <= line]
+    return max(before) if before else min(lines, default=line)
+
+
+def _next_declaration(exports: list[dict], file: str, line: int) -> int | None:
+    """The line of the first surface record in `file` after `line`, None when there is none."""
+    return min((at for at in _lines_in(exports, file) if at > line), default=None)
+
+
+def _source_lines(source_root: str, file: str) -> list[str] | None:
+    """The lines of `file` under `source_root`, None when it is no readable
+    file there (a path that leaves the root included)."""
+    root = Path(source_root).resolve()
+    path = (root / file).resolve()
+    try:
+        path.relative_to(root)
+        return path.read_bytes().decode("utf-8-sig", errors="replace").splitlines()
+    except (ValueError, OSError):
+        return None
+
+
+def _after_parens(text: str, start: int) -> int:
+    """The index past the `)` that closes the `(` at `start`, -1 when none does."""
+    depth = 0
+    for i in range(start, len(text)):
+        depth += {"(": 1, ")": -1}.get(text[i], 0)
+        if depth == 0:
+            return i + 1
+    return -1
+
+
+def _string_end(text: str, start: int) -> int:
+    """The index past the string literal whose quote is at `start`: up to the same quote not escaped, the end of
+    `text` when none closes it."""
+    quote, i = text[start], start + 1
+    while i < len(text):
+        if text[i] == "\\":
+            i += 2
+        elif text[i] == quote:
+            return i + 1
+        else:
+            i += 1
+    return len(text)
+
+
+def _lifetime(text: str, i: int, in_angle: bool, extension: str) -> bool:
+    """Whether the `'` at `i` starts a Rust lifetime: only in a `.rs` file, `'ident` followed by whitespace, `,`,
+    `>`, `+`, `)` or the end, coming after a `&` or a `+` (whitespace aside) or inside a `<...>` (`in_angle`), as
+    in `&'a str`, `impl Tr + 'a` and `<'a>`. Any other `'` opens a string, so a TS `Omit<P, 'a,b'>` holds one."""
+    return (extension == ".rs" and bool(LIFETIME_RE.match(text, i))
+            and (in_angle or text[:i].rstrip()[-1:] in ("&", "+")))
+
+
+def _opens(text: str, i: int, extension: str) -> bool:
+    """Whether the `<` at `i` opens a pair: it follows a letter, a digit, `_`, `$`, `.`, `]` or `>` with no
+    whitespace between (`Map<`, `f<T>`, `obj.get<T>`), and a `>` that is not part of `->` or `=>` closes it
+    before the bracket pair around it closes or the text ends. Any other `<` is an operator (`x < y`, `1 << 20`,
+    `x<3)`)."""
+    if i == 0 or not (text[i - 1].isalnum() or text[i - 1] in "_$.]>"):
+        return False
+    depth, j = 0, i + 1
+    while j < len(text):
+        ch = text[j]
+        if ch in "\"`" or (ch == "'" and not _lifetime(text, j, depth == 0, extension)):
+            j = _string_end(text, j)
+            continue
+        if ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            if depth == 0:
+                return False
+            depth -= 1
+        elif ch == ">" and depth == 0 and text[j - 1] not in "-=":
+            return True
+        j += 1
+    return False
+
+
+def _levels(text: str, extension: str = "") -> list[int | None]:
+    """For each character of `text`, in a file of `extension`, the number of bracket pairs open around it, None
+    inside a string literal (its quotes included). `(`, `[` and `{` open a pair, and a `<` opens one only when it
+    follows a name, a `.`, a `]` or a `>` with no whitespace between and a `>` that is not part of `->` or `=>`
+    closes it before the bracket pair around it closes or the text ends (_opens); any other `<` is an operator
+    and nests nothing, so `(path, size=1 << 20, mode)` holds three parameters,
+    `(a: boolean = x < y, b: Map<string, number>)` two, and `Map<string, number>` keeps its comma. An opening
+    bracket and the one that closes it stand at the level outside them. A closing bracket closes the pair it
+    matches and any `<` left open inside it, and a `>` closes only a `<`, never as part of `->` or `=>`. A `"`, a
+    backquote or a `'` opens a string (_string_end), except the `'` of a Rust lifetime in a `.rs` file
+    (_lifetime)."""
+    levels: list[int | None] = []
+    stack: list[str] = []
+    i = 0
+    while i < len(text):
+        ch = text[i]
+        if ch in "\"`" or (ch == "'" and not _lifetime(text, i, bool(stack) and stack[-1] == "<", extension)):
+            end = _string_end(text, i)
+            levels.extend([None] * (end - i))
+            i = end
+            continue
+        if ch in "([{" or (ch == "<" and _opens(text, i, extension)):
+            levels.append(len(stack))
+            stack.append(ch)
+        elif ch in CLOSERS and CLOSERS[ch] in stack:
+            while stack.pop() != CLOSERS[ch]:
+                pass
+            levels.append(len(stack))
+        elif ch == ">" and stack and stack[-1] == "<" and text[i - 1:i] not in ("-", "="):
+            stack.pop()
+            levels.append(len(stack))
+        else:
+            levels.append(len(stack))
+        i += 1
+    return levels
+
+
+def _split(text: str, separator: str, extension: str = "") -> list[str]:
+    """`text` cut at each `separator` outside every bracket pair and string (_levels)."""
+    levels = _levels(text, extension)
+    cuts = [-1, *(i for i, ch in enumerate(text) if ch == separator and levels[i] == 0), len(text)]
+    return [text[a + 1:b] for a, b in zip(cuts, cuts[1:])]
+
+
+def _encloses(text: str, start: int, extension: str = "") -> bool:
+    """Whether the bracket at `start` of `text` opens a pair that the last character of `text` closes."""
+    levels = _levels(text, extension)
+    return (OPENERS.get(text[start]) == text[-1] and levels[start] == 0 == levels[-1] and len(text) - start > 1
+            and all(level is None or level > 0 for level in levels[start + 1:-1]))
+
+
+def _group(text: str, extension: str = "") -> tuple[int, int] | None:
+    """The indices of the `(` and the `)` of the parameter group of `text`: the first pair of parentheses outside
+    every bracket pair and string (_levels), before any return arrow there, that is no prefix group. A prefix group
+    is one a decorator or a Java annotation writes (the text before it ends with `@name`:
+    `@lru_cache(maxsize=None) def f(x)`), one directly followed by another `(` (C++ `operator()(int x)`), or one
+    followed, after whitespace, by a name and a `(` (a Go receiver, `func (s *Server) Start(port int)`), unless
+    that name is a C or C++ qualifier (`noexcept`, `throw`, `__attribute__`, `requires`, `decltype`: `f(int x)
+    noexcept(true)` keeps its group). A `(` after a space is no prefix either (Go's result list,
+    `Start(port int) (int, error)`). So a keyword, a name or type parameters before the group are never part of
+    it. None when there is no such group: no `(` comes before the return arrow (`make -> X`), or a group does not
+    close."""
+    levels = _levels(text, extension)
+    i = 0
+    while i < len(text):
+        if levels[i] == 0 and RETURN_ARROW_RE.match(text, i):
+            return None
+        if text[i] == "(" and levels[i] == 0:
+            end = next((j for j in range(i + 1, len(text)) if text[j] == ")" and levels[j] == 0), None)
+            if end is None:
+                return None
+            if not (DECORATED_RE.search(text, 0, i) or PREFIX_GROUP_RE.match(text, end + 1)):
+                return i, end
+            i = end
+        i += 1
+    return None
+
+
+def _signature_parts(sig: str, extension: str = "") -> tuple[str, str]:
+    """(the text before the return, its whitespace runs read as one space; the return type it writes, "" for
+    none) of a signature, in a file of `extension`. The return follows the parameter group (_group, the one
+    _parameters reads), after a `->`, `=>`, `→` or `:`, or, with no group, the first such arrow. A `;` is read as
+    any other character."""
+    text = sig.strip()
+    group = _group(text, extension)
+    if group is None:
+        arrow = RETURN_ARROW_RE.search(text)
+        head, tail = (text[:arrow.start()], text[arrow.end():]) if arrow else (text, "")
+    else:
+        head, tail = text[:group[1] + 1], re.sub(r"^\s*(?:->|=>|→|:)", "", text[group[1] + 1:])
+    return " ".join(head.split()), tail.strip().rstrip("{:").strip()
+
+
+def _compact(text: str) -> str:
+    """`text` with its whitespace runs read as one space, and none beside a character that is no letter, digit
+    or `_`, so `{ title }` is `{title}` and `dict[str, Any]` is `dict[str,Any]`."""
+    return re.sub(r"\s*([^\w\s])\s*", r"\1", " ".join(text.split()))
+
+
+def _type_parameters(sig: str, extension: str = "") -> str:
+    """The type parameters a signature writes between its name and its parameter group (`<T extends X>`, or
+    Python's `[T: int]`), compacted and without a trailing comma; "" for none, or no group."""
+    text = sig.strip()
+    group = _group(text, extension)
+    if group is None:
+        return ""
+    levels = _levels(text, extension)
+    k = len(text[:group[0]].rstrip()) - 1
+    if k < 1 or text[k] not in ">]" or levels[k] is None:
+        return ""
+    j = next((j for j in range(k - 1, -1, -1) if levels[j] is not None and levels[j] <= levels[k]), None)
+    if j is None or OPENERS.get(text[j]) != text[k] or levels[j] != levels[k]:
+        return ""
+    return _compact(text[j + 1:k]).rstrip(",")
+
+
+def _parameter(text: str, extension: str = "") -> dict:
+    """One parameter as _parameters reads it, but for its "by_name" and "receiver": its name is the text before
+    the `:` of its type and the `=` of its default (each outside every bracket pair and string; the `=` of `==`,
+    `=>`, `<=`, `>=` or `!=` is no default), the whole text when it writes neither, so a parameter in another
+    language's order (Go's `id string`) or a destructured one (`{ a, b }`) is read as one name."""
+    levels = _levels(text, extension)
+    at = next((i for i, ch in enumerate(text) if ch == "=" and levels[i] == 0
+               and text[i + 1:i + 2] not in ("=", ">") and text[i - 1:i] not in ("=", "!", "<", ">")), None)
+    head = text if at is None else text[:at]
+    colon = next((i for i, ch in enumerate(head) if ch == ":" and levels[i] == 0), None)
+    name = _compact(head if colon is None else head[:colon])
+    optional = at is not None or name.endswith("?")
+    name = name.rstrip("?")
+    key = "**" if name.startswith("**") else "*" if name.startswith("*") else name
+    return {"key": key, "name": name, "type": "" if colon is None else _compact(head[colon + 1:]),
+            "default": None if at is None else text[at + 1:].strip(), "optional": optional,
+            "variadic": key in ("*", "**") or (name.startswith("...") and name not in ELLIPSES),
+            "ellipsis": name in ELLIPSES and colon is None and at is None}
+
+
+def _parameters(sig: str, extension: str = "") -> list[dict] | None:
+    """The parameters the group of `sig` writes (_group), in a file of `extension`, None when it has no group:
+    the group split at its commas outside every bracket pair and string (_levels), so a comma inside a nested
+    type, a callback's parameters or a default's string splits nothing, without a bare `*` or `/` marker. Each is
+    {"key": its name (_parameter), `*` for any `*args` and `**` for any `**kwargs`, whose names are never
+    compared; "name": its name as written; "type": the type it writes, compacted, "" for none; "default": the text
+    of its default, None for none; "optional": whether a default or a `?` on its name marks it optional;
+    "variadic": whether it is a `*args`, a `**kwargs` or a TS/JS rest `...name`; "ellipsis": whether it is an
+    ellipsis item (`...`, `…`) standing for members it does not show; "by_name": whether it comes after a `*`
+    marker, a bare `*` or a `*args`; "receiver": whether it is the group's first item and a receiver
+    (RECEIVER_RE: `self`, `cls`, `&self`, `&mut self`, `mut self`, `this: T`), which _parameter_difference
+    drops}. A `sig` that holds a `;` outside every bracket pair and string (shared text before a name's own
+    members, an overload set or a usage list joined by `;`) has none either, so it is compared as text, read as
+    written: its first group may be a call inside the shared text."""
+    text = sig.strip()
+    group = _group(text, extension)
+    if group is None or len(_split(text, ";", extension)) > 1:
+        return None
+    params: list[dict] = []
+    by_name = False
+    for index, item in enumerate(_split(text[group[0] + 1:group[1]], ",", extension)):
+        item = item.strip()
+        if item in ("", "/"):
+            continue
+        if item == "*":
+            by_name = True
+            continue
+        param = _parameter(item, extension)
+        param.update(by_name=by_name, receiver=index == 0 and bool(RECEIVER_RE.fullmatch(param["name"])))
+        by_name = by_name or param["key"] == "*"
+        params.append(param)
+    return params
+
+
+def _type_key(text: str, extension: str = "") -> frozenset:
+    """A written type, in a file of `extension`, as signature-comparison-rules.md's Equivalent spellings commonly
+    reads it: the set of its union's members (cut at each `|` outside every bracket pair and string), each (its
+    base name, the keys of its type arguments, None when it writes none), so `Optional[X]`, `Union[X, None]` and
+    `X | None` are one key, and so are `Union[A, B]`, `A | B` and `B | A`. A `typing.`, `collections.abc.` or
+    `React.` prefix is dropped, `typing`'s `List`, `Dict`, `Tuple`, `Set`, `FrozenSet` and `Type` are the
+    builtins they alias, a quoted forward reference is the type it quotes outside a TS/JS file (where a quoted
+    type is a string literal type), `Array<T>` is `T[]`, `ReadonlyArray<T>` is `readonly T[]`, and a
+    parenthesized type is the type inside. A type it reads no other way (a callable's arrow, a literal) is one
+    member, its compacted text. Type variables renamed consistently, a type alias against the type it names and a
+    union of callables against one callable returning the union are different keys: the script cannot see them
+    as one."""
+    members: set = set()
+    for part in _split(TYPE_PREFIX_RE.sub("", _compact(text)), "|", extension):
+        members |= _member_keys(part.strip(), extension)
+    return frozenset(members)
+
+
+def _member_keys(text: str, extension: str = "") -> frozenset:
+    """The union members (_type_key) one part of a type with no `|` outside brackets stands for."""
+    quoted = FORWARD_REFERENCE_RE.fullmatch(text) if extension not in TS_JS_EXTENSIONS else None
+    if quoted:
+        return _type_key(quoted.group(2), extension)
+    if text.startswith("(") and _encloses(text, 0, extension):
+        return _type_key(text[1:-1], extension)
+    if text.endswith("[]") and len(text) > 2:
+        inner = text[:-2].strip()
+        if inner.startswith("readonly "):
+            return frozenset({("ReadonlyArray", (_type_key(inner[len("readonly "):], extension),))})
+        return frozenset({("Array", (_type_key(inner, extension),))})
+    name = TYPE_NAME_RE.match(text)
+    if name and name.end() == len(text):
+        return frozenset({(TYPING_ALIASES.get(text, text), None)})
+    if name and text[name.end()] in "[<" and _encloses(text, name.end(), extension):
+        args = tuple(_type_key(arg, extension) for arg in _split(text[name.end() + 1:-1], ",", extension)
+                     if arg.strip())
+        base = TYPING_ALIASES.get(name.group(), name.group())
+        if base == "Optional" and len(args) == 1:
+            return args[0] | {("None", None)}
+        if base == "Union" and args:
+            return frozenset().union(*args)
+        return frozenset({(base, args)})
+    return frozenset({(text, None)})
+
+
+def _members_match(documented: tuple, source: tuple) -> bool:
+    """Whether two union members (_type_key) are one type: one base name and, unless either side leaves its type
+    arguments out (`dict` against `dict[str, Any]`, which compares the base alone), as many arguments, each pair
+    one type (_types_match)."""
+    (base, args), (other_base, other_args) = documented, source
+    if base != other_base:
+        return False
+    if args is None or other_args is None:
+        return True
+    return len(args) == len(other_args) and all(_types_match(a, b) for a, b in zip(args, other_args))
+
+
+def _types_match(documented: frozenset, source: frozenset, subset: bool = False) -> bool:
+    """Whether every documented member is a source member (_members_match) and, unless `subset`, every source
+    member a documented one. A parameter's own type is compared with `subset`: a documented type that names some
+    of the members of the source's union is no difference, one that names a member the source lacks is."""
+    if not all(any(_members_match(d, s) for s in source) for d in documented):
+        return False
+    return subset or all(any(_members_match(d, s) for d in documented) for s in source)
+
+
+def _literal_type(default: str | None) -> str:
+    """The type of a TS/JS literal default (LITERAL_TYPES: `number`, `string`, `boolean` or `bigint`), "" for any
+    other default."""
+    if default is None:
+        return ""
+    return next((name for pattern, name in LITERAL_TYPES if pattern.fullmatch(default)), "")
+
+
+def _count(n: int) -> str:
+    return f"{n} parameter" if n == 1 else f"{n} parameters"
+
+
+def _pair_difference(documented: dict, source: dict, stated: bool, extension: str) -> str | None:
+    """Why a documented parameter differs from the source parameter it pairs with, None when it does not: its
+    type, where both write one (_types_match with `subset`), or, when the documented list states optionality for
+    any member (`stated`), its optionality, a rest or variadic member's aside."""
+    if documented["type"] and source["type"] and not _types_match(
+            _type_key(documented["type"], extension), _type_key(source["type"], extension), subset=True):
+        return (f"`{documented['name']}` is typed `{documented['type']}` in the documented list, "
+                f"`{source['type']}` in the source")
+    if stated and not documented["variadic"] and documented["optional"] != source["optional"]:
+        def word(optional: bool) -> str:
+            return "optional" if optional else "required"
+        return (f"`{documented['name']}` is {word(documented['optional'])} in the documented list, "
+                f"{word(source['optional'])} in the source")
+    return None
+
+
+def _complete_difference(documented: list[dict], source: list[dict], stated: bool, extension: str) -> str | None:
+    """Why a documented list that claims to be complete (it writes a type, a default or a `?` for some member)
+    differs from the source's, None when it does not: it must write as many parameters, paired in order up to the
+    first that either list writes after a `*` marker and by name from there, each pair with one name and no
+    _pair_difference."""
+    if len(documented) != len(source):
+        return f"the documented list writes {_count(len(documented))}, the source {_count(len(source))}"
+    first = min(next((i for i, p in enumerate(params) if p["by_name"]), len(params)) for params in (documented, source))
+    for n, (d, s) in enumerate(zip(documented[:first], source[:first]), 1):
+        if d["key"] != s["key"]:
+            return f"parameter {n} is `{d['name']}` in the documented list, `{s['name']}` in the source"
+        reason = _pair_difference(d, s, stated, extension)
+        if reason:
+            return f"parameter {n}: {reason}"
+    named = [{p["key"]: p for p in params[first:]} for params in (documented, source)]
+    if any(len(keys) != len(documented) - first for keys in named):
+        return "a parameter is written twice"
+    for key, d in named[0].items():
+        if key not in named[1]:
+            return f"`{d['name']}`, written after a `*` marker, is not a source parameter"
+        reason = _pair_difference(d, named[1][key], stated, extension)
+        if reason:
+            return reason
+    return None
+
+
+def _partial_difference(documented: list[dict], source: list[dict], stated: bool, bare: bool,
+                        extension: str) -> str | None:
+    """Why a documented list that does not claim to be complete differs from the source's, None when it does
+    not: each member it writes must be a source parameter (`*args` and `**kwargs` by kind), in the source's order
+    (a member after a `*` marker on either side by name alone), with no _pair_difference. A list of bare names
+    (`bare`) must also leave out only optional source parameters (a default, a `?`, `*args`, `**kwargs`, a rest),
+    and, in a file of a language without keyword arguments (POSITIONAL_EXTENSIONS), none before one it writes,
+    which shifts a caller's positions. A list holding an ellipsis claims nothing about what it stands for."""
+    used: list[int] = []
+    last = -1
+    for d in documented:
+        at = next((i for i, s in enumerate(source) if i not in used and s["key"] == d["key"]), None)
+        if at is None:
+            return f"`{d['name']}` is not a source parameter"
+        if not (d["by_name"] or source[at]["by_name"]):
+            if at < last:
+                return (f"`{d['name']}` comes before `{source[last]['name']}` in the source, after it in the "
+                        "documented list")
+            last = at
+        used.append(at)
+        reason = _pair_difference(d, source[at], stated, extension)
+        if reason:
+            return reason
+    if not bare:
+        return None
+    for i, s in enumerate(source):
+        if i in used:
+            continue
+        if not (s["optional"] or s["variadic"]):
+            return f"the required source parameter `{s['name']}` is left out"
+        later = min((j for j in used if j > i), default=None)
+        if extension in POSITIONAL_EXTENSIONS and later is not None:
+            return (f"the optional `{s['name']}`, left out before `{source[later]['name']}`, shifts a caller's "
+                    f"positions in a `{extension}` file")
+    return None
+
+
+def _parameter_difference(documented_sig: str, source_sig: str, extension: str = "") -> str | None:
+    """Why `documented_sig` and `source_sig` do not write the same parameters as signature-comparison-rules.md
+    reads them in a file of `extension`, None when they do. When either has no parameter group (_parameters; a
+    `;`-joined text has none), the texts before their returns (_signature_parts) are compared, and the reason says
+    which side has none.
+    Otherwise: the source's leading receiver is dropped, and the documented list's only when the source leads
+    with one too, so a documented `(self, a)` against `def f(a)` differs; type parameters both write between the
+    name and the group (_type_parameters) must be one text; in a TS/JS file (TS_JS_EXTENSIONS) a source parameter
+    with no type and a literal default has that literal's type (_literal_type); a list of bare names (no type,
+    default or `?` for any member) or one holding an ellipsis need not write every parameter
+    (_partial_difference), and any other list claims to be complete (_complete_difference). A keyword or name
+    before the group, a type only one side writes, a default's value, a `*` or `/` marker and the names of `*args`
+    and `**kwargs` are never compared. The reason names the count, or the parameter (by position or by name) and
+    the fact that differs: its name, its order, its type, its optionality, or the type parameters."""
+    documented, source = _parameters(documented_sig, extension), _parameters(source_sig, extension)
+    if documented is None or source is None:
+        if _signature_parts(documented_sig, extension)[0] == _signature_parts(source_sig, extension)[0]:
+            return None
+        side = ("neither signature has a" if documented is None and source is None
+                else "the documented signature has no" if documented is None else "the source signature has no")
+        return f"{side} parameter group, so the texts before the return are compared"
+    if source and source[0]["receiver"]:
+        source = source[1:]
+        if documented and documented[0]["receiver"]:
+            documented = documented[1:]
+    written, other = _type_parameters(documented_sig, extension), _type_parameters(source_sig, extension)
+    if written and other and written != other:
+        return f"the type parameters differ: documented `{written}`, source `{other}`"
+    if extension in TS_JS_EXTENSIONS:
+        source = [{**p, "type": _literal_type(p["default"])} if not p["type"] else p for p in source]
+    stated = any(p["optional"] for p in documented if not p["variadic"])
+    members = [p for p in documented if not p["ellipsis"]]
+    bare = not any(p["type"] or p["optional"] for p in documented)
+    if bare or len(members) < len(documented):
+        return _partial_difference(members, source, stated, bare and len(members) == len(documented), extension)
+    return _complete_difference(documented, source, stated, extension)
+
+
+def _returns(lines: list[str], number: int, declaration_line: int) -> bool:
+    """Whether line `number` (from 1) of `lines` returns: a line after the
+    declaration whose text starts with the `return` keyword, or the
+    declaration line itself when its own expression body follows its
+    parameters there (an arrow function's `=> expr`, a Python
+    `def ...: return x`). A type arrow, a callback parameter, a match arm, a
+    string or a comment never does."""
+    code = lines[number - 1].strip()
+    if number != declaration_line:
+        return bool(RETURN_START_RE.match(code))
+    if TYPE_DECLARATION_RE.match(code):
+        return False
+    for opener, body in ((PYTHON_DEF_RE.match(code), PYTHON_BODY_RE), (ARROW_OPENER_RE.search(code), ARROW_BODY_RE)):
+        end = _after_parens(code, opener.end() - 1) if opener else -1
+        if end != -1 and body.match(code, end):
+            return True
+    return False
+
+
+def contradiction_fact(entry: dict, documented: dict, file: str, declaration_line: int,
+                       next_line: int | None = None, source_root: str | None = None) -> str | None:
+    """The first fact an annotation-contradicted mismatch rests on that does
+    not check, None when each does: the documented entry states a return
+    type (a non-blank `return_type`, or a `documented_sig` that writes one);
+    `documented_sig` and `source_sig` write the same parameters, as the
+    comparison rules read them in a file of `file`'s language
+    (_parameter_difference, which compares the texts before the return when
+    either has no parameter group); `evidence_line` comes
+    after the declaration line and before `next_line`, the next surface
+    record in the file; and, with `source_root`, that line of `file` under it
+    returns (_returns), which alone lets the declaration line itself stand.
+    A failed parameter fact quotes the text before each one's return
+    (_signature_parts), then says why the two differ."""
+    evidence = entry.get("evidence_line")
+    extension = _extension(file)
+    documented_params, documented_return = _signature_parts(entry["documented_sig"], extension)
+    source_params, _ = _signature_parts(entry["source_sig"], extension)
+    return_type = documented.get("return_type")
+    if not (isinstance(return_type, str) and return_type.strip()) and not documented_return:
+        return "the documented signature states no return type"
+    difference = _parameter_difference(entry["documented_sig"], entry["source_sig"], extension)
+    if difference is not None:
+        return f"its parameters differ: documented `{documented_params}`, source `{source_params}`: {difference}"
+    if not _is_line(evidence) or evidence < declaration_line:
+        return f"evidence_line {json.dumps(evidence)} is before the declaration"
+    if next_line is not None and evidence >= next_line:
+        return f"evidence_line {evidence} is not before the next declaration in the file, at line {next_line}"
+    if source_root is None:
+        return None if evidence > declaration_line else (
+            f"evidence_line {evidence} is the declaration line, which only --source-root can check")
+    lines = _source_lines(source_root, file)
+    if lines is None:
+        return f"evidence_line {evidence} is in no readable file under --source-root"
+    if evidence > len(lines):
+        return f"evidence_line {evidence} is past the end of the file ({len(lines)} lines)"
+    if not _returns(lines, evidence, declaration_line):
+        if evidence == declaration_line:
+            return f"evidence_line {evidence}, the declaration line, has no expression body after its parameters"
+        return f"evidence_line {evidence} does not start with `return`"
+    return None
+
+
+def grade(difference: str | None, file: str, documented: dict, declared: str | None = None,
+          contradiction: str | None = UNCHECKED) -> str:
     """The severity of one mismatch the result reports at `file`. The judge's
     `difference` lowers it only where the script confirms the fact it rests
     on: a parameter-name difference is Low when `declared`, the file the
     plan offered the check at (else `file`), is the mismatch's file and of a
     language with no keyword arguments; an omitted-optional difference on a
-    form the inventory marks partial is Info; every other mismatch is
-    Critical."""
+    form the inventory marks partial is Info; an annotation-contradicted
+    difference is Info when `contradiction`, the fact contradiction_fact
+    found failing, is None; every other mismatch is Critical."""
     if difference == "parameter-name":
         at = file if declared is None else declared
         if at.replace("\\", "/") == file.replace("\\", "/") and _extension(at) in POSITIONAL_EXTENSIONS:
             return "Low"
     if difference == "omitted-optional" and _partial(documented):
         return "Info"
+    if difference == CONTRADICTED and contradiction is None:
+        return "Info"
     return "Critical"
 
 
@@ -524,6 +1279,19 @@ def _gap_record(m: dict) -> dict:
     issue = f"documented `{m['documented_sig']}`, source `{m['source_sig']}`: {m['issue']}"
     remediation = (f"Update the documented signature of `{name}` from `{m['documented_sig']}` "
                    f"to `{m['source_sig']}`, the signature the source defines at `{where}`.")
+    if m["severity"] == "Info" and m["difference"] == CONTRADICTED:
+        body = f"{m['file']}:{m['evidence_line']}"
+        return {
+            "severity": "Info",
+            "category": "observation",
+            "title": f"Annotation contradicted: {name}",
+            "source": where,
+            "export": name,
+            "issue": (f"the source annotates the return of `{name}` otherwise than the skill documents, and its "
+                      f"body returns the documented type at `{body}`: {issue}"),
+            "remediation": (f"No change to the skill: it documents what `{name}` returns, as `{body}` shows. "
+                            f"Report the return annotation at `{where}` upstream, since the body contradicts it."),
+        }
     if m["severity"] == "Info":
         return {
             "severity": "Info",
@@ -550,21 +1318,72 @@ def _gap_record(m: dict) -> dict:
     }
 
 
+def _form_text(form: dict) -> str:
+    """A documented form on one line: its usage form, else its parameters and return type."""
+    def text(value: object, sep: str = ", ") -> str:
+        return sep.join(str(v) for v in value) if isinstance(value, list) else str(value)
+    if _gives_usage(form):
+        return text(form["usage_signature"], "; ")
+    return_type = form.get("return_type")
+    tail = f" -> {text(return_type)}" if isinstance(return_type, (str, list)) and text(return_type).strip() else ""
+    return f"({text(form.get('params', ''))}){tail}"
+
+
+def _sig_text(text: str) -> str:
+    """A signature as a mismatch's `documented_sig` and a form compare: whitespace runs as one space, outer parentheses off."""
+    text = " ".join(text.split())
+    while text.startswith("(") and _after_parens(text, 0) == len(text):
+        text = text[1:-1].strip()
+    return text
+
+
+def _quotes(documented_sig: str, form: dict) -> bool:
+    """Whether `documented_sig` is the text of `form`: its parameters (a list joined), or one of its usages, whole
+    or before the return type it writes."""
+    usage = form.get("usage_signature")
+    texts = {_sig_text(_field_text(form.get("params")))} | {
+        _sig_text(u) for u in (usage if isinstance(usage, list) else [usage]) if isinstance(u, str)}
+    texts.discard("")
+    return bool({_sig_text(documented_sig), _sig_text(_signature_parts(documented_sig)[0])} & texts)
+
+
+def _form_gap_record(m: dict, index: int, forms: list[dict]) -> dict:
+    """_gap_record's record. For a name with several forms its title and Issue name the documented form the mismatch
+    concerns, counted from 1, so the ledger keeps one gap per form (its dedupe reads the title, never the Issue)."""
+    record = _gap_record(m)
+    if len(forms) > 1:
+        record["title"] += f" (form {index + 1} of {len(forms)})"
+        record["issue"] += f" (documented form {index + 1} of {len(forms)}: `{_form_text(forms[index])}`)"
+    return record
+
+
 def score(inventory: list[dict], names: list[str], exports: list[dict], results: list[dict],
-          type_names: list[str] | None = None, offered: dict[str, list[str]] | None = None) -> dict:
+          type_names: list[str] | None = None, offered: dict[str, list[str]] | None = None,
+          source_root: str | None = None, planned: dict[str, list[dict]] | None = None) -> dict:
     """The two categories: Signature Accuracy over the signature universe of
     `names` (the `all` set) and `exports`, Type Coverage over `type_names`
     when given, else over `names`. A fallback scan's exports_found join the
     universe, and `names` when no `type_names` is given. `offered` (read
-    from --plan) names the files the plan offered each check at."""
+    from --plan) names the files the plan offered each check at;
+    `source_root` (--source-root) is the local tree an
+    annotation-contradicted mismatch's `evidence_line` is checked in. A
+    mismatch is graded against the documented form its `form` names: of
+    documented_forms, or of `planned` (read from --plan) for a name it
+    holds, with a warning where the two differ."""
     by_name = _records_by_name(exports)
     # A fallback scan reports its own names and types.
     fallback_types = {n for r in results for n in r.get("types_found") or []}
     surface = set(names) | {n for r in results for n in r.get("exports_found") or []}
     documented = documented_names(inventory)
-    signatures = documented_signatures(inventory)
-    compared = (surface | signature_universe(names, exports)) & set(signatures)
+    forms = documented_forms(inventory)
+    compared = (surface | signature_universe(names, exports)) & set(forms)
     warnings = []
+    for name in sorted(set(forms) & set(planned or {})):
+        if planned[name] != forms[name]:
+            differ = (f"{len(planned[name])} documented form(s), not the {len(forms[name])} the inventory gives"
+                      if len(planned[name]) != len(forms[name]) else "different forms than the inventory gives")
+            warnings.append(f"`{name}`: the plan offered {differ}: graded against the plan's")
+            forms[name] = planned[name]
 
     graded: dict[tuple, dict] = {}
     seen = set()
@@ -582,32 +1401,71 @@ def score(inventory: list[dict], names: list[str], exports: list[dict], results:
                                     f"`{entry['file']}`, no file the plan offered its check at: recorded at "
                                     "the result's file")
             file = _path(file)
-            key = (name, file, entry["line"])
             if name not in compared:
-                if key not in seen:
+                if (name, file, entry["line"]) not in seen:
                     warnings.append(f"{file}:{entry['line']}: a signature mismatch for "
                                     f"`{name}`, which is no documented signature on the source surface: "
                                     "not scored, no gap")
-                seen.add(key)
+                seen.add((name, file, entry["line"]))
                 continue
+            # The documented form the mismatch is reported for: 0 is `documented`, n the check's nth alternative.
+            index = entry.get("form") or 0
+            if index >= len(forms[name]):
+                warning = (f"{file}:{entry['line']}: a signature mismatch for `{name}` names `form` {index}, no "
+                           f"form its check offered (0 to {len(forms[name]) - 1}): graded against `documented`")
+                if warning not in warnings:
+                    warnings.append(warning)
+                index = 0
+            # A form's own label lowers a grade only for the form the mismatch quotes as `documented_sig`.
+            if len(forms[name]) > 1 and not _quotes(entry["documented_sig"], forms[name][index]):
+                quoted = next((j for j, f in enumerate(forms[name]) if _quotes(entry["documented_sig"], f)), None)
+                if quoted is not None or index != 0:
+                    target = "documented" if quoted is None else f"form {quoted}, the one it quotes"
+                    warning = (f"{file}:{entry['line']}: a signature mismatch for `{name}` names `form` {index}, whose "
+                               f"text its `documented_sig` is not: graded against {target}")
+                    if warning not in warnings:
+                        warnings.append(warning)
+                    index = quoted or 0
+            form = forms[name][index]
+            # Each usage of a list is a form of its own: one key per documented text.
+            key = (name, file, entry["line"], index, _sig_text(entry["documented_sig"]))
             difference = entry.get("difference")
             # Graded at the file only when the plan offered it: never Low at a namesake it did not offer.
             declared = (file if _is_offered_file(files, file) else files[0]) if files else None
-            severity = grade(difference, file, signatures[name], declared)
-            # Every entry is graded: one declaration reported twice keeps its most severe grade.
+            # The facts of an annotation-contradicted mismatch, checked once and handed to grade().
+            fact = None
+            if difference == CONTRADICTED:
+                at_line = _declaration_line(by_name, name, file, entry["line"])
+                fact = contradiction_fact(entry, form, file, at_line,
+                                          _next_declaration(exports, file, at_line), source_root)
+                warning = (f"{file}:{at_line}: the mismatch for `{name}` is tagged {CONTRADICTED}, but {fact}: "
+                           "graded as an untagged mismatch (Critical)")
+                if fact is not None and warning not in warnings:
+                    warnings.append(warning)
+            severity = grade(difference, file, form, declared, fact)
+            # Every entry is graded: one declaration reported twice against one form keeps its most severe grade.
             if key in graded and GRADES.index(graded[key]["severity"]) <= GRADES.index(severity):
                 continue
             graded[key] = {"name": name, "file": file, "line": entry["line"],
                            "source_sig": entry["source_sig"], "documented_sig": entry["documented_sig"],
                            "issue": entry["issue"], "difference": difference, "severity": severity}
-    # A check that offered several files keeps one mismatch, its least severe (the closest candidate).
-    mismatches, closest = [], {}
-    for m in sorted(graded.values(), key=lambda m: (m["file"], m["line"], m["name"])):
+            if difference == CONTRADICTED:
+                graded[key]["evidence_line"] = entry.get("evidence_line")
+    # A check that offered several files keeps one mismatch per form, its least severe (the closest candidate).
+    # Each form's mismatch stands on its own.
+    def order(item: tuple) -> tuple:
+        (_, _, _, index, text), m = item
+        return m["file"], m["line"], m["name"], index, text
+
+    kept, closest = [], {}
+    for key, m in sorted(graded.items(), key=order):
+        bucket = (m["name"], key[3], key[4])
         if len({_path(f) for f in _offered_files(offered, by_name, m["name"])}) < 2:
-            mismatches.append(m)
-        elif m["name"] not in closest or GRADES.index(m["severity"]) > GRADES.index(closest[m["name"]]["severity"]):
-            closest[m["name"]] = m
-    mismatches = sorted(mismatches + list(closest.values()), key=lambda m: (m["file"], m["line"], m["name"]))
+            kept.append((key, m))
+        elif bucket not in closest or GRADES.index(m["severity"]) > GRADES.index(closest[bucket][1]["severity"]):
+            closest[bucket] = (key, m)
+    kept = sorted(kept + list(closest.values()), key=order)
+    mismatches = [m for _, m in kept]
 
     # A Low or an Info mismatch is a caller-invisible difference: it still matches.
     wrong = {m["name"] for m in mismatches if m["severity"] == "Critical"}
@@ -643,7 +1501,7 @@ def score(inventory: list[dict], names: list[str], exports: list[dict], results:
         "totalTypes": len(types),
         "missingTypes": sorted(types - documented),
         "mismatches": mismatches,
-        "gapRecords": [_gap_record(m) for m in mismatches],
+        "gapRecords": [_form_gap_record(m, key[3], forms[m["name"]]) for key, m in kept],
         "warnings": warnings,
     }
 
@@ -675,6 +1533,8 @@ def _cmd_plan(args: argparse.Namespace) -> tuple[dict, int]:
 
 
 def _cmd_score(args: argparse.Namespace) -> tuple[dict, int]:
+    if args.source_root is not None and not (args.source_root.strip() and Path(args.source_root).is_dir()):
+        raise InputError(f"--source-root {args.source_root!r} is no folder: pass the local source tree the judges read")
     inventory = load_inventory(args.inventory)
     chosen, exports, names = load_surface(args.surface, args.surface_set)
     results, violations = load_results(args.results or [])
@@ -684,7 +1544,9 @@ def _cmd_score(args: argparse.Namespace) -> tuple[dict, int]:
                 Path(path).unlink(missing_ok=True)
         return {"valid": False, "violations": violations}, 2
     offered = load_plan(args.plan) if args.plan is not None else None
-    out = score(inventory, names, exports, results, None if args.surface_set == "all" else chosen, offered)
+    planned = load_plan_forms(args.plan) if args.plan is not None else None
+    out = score(inventory, names, exports, results, None if args.surface_set == "all" else chosen, offered,
+                args.source_root, planned)
     if args.output:
         _write_json(args.output, out)
     if args.gaps_output:
@@ -716,6 +1578,9 @@ def _build_parser() -> argparse.ArgumentParser:
     p.add_argument("--surface-set", default="all",
                    help="the surface name set Type Coverage counts (default: all)")
     p.add_argument("--plan", help="the plan's output: the files each check offered a mismatch at")
+    p.add_argument("--source-root", help="the local source tree the judges read: an annotation-contradicted "
+                                         "mismatch's evidence_line must start with `return` there, or be the "
+                                         "declaration line with its expression body")
     p.add_argument("--results", action="append", help="a subagent result file (repeatable)")
     p.add_argument("--output", help="also write the scores to this file")
     p.add_argument("--gaps-output", help="write the gap ledger records to this file")