bmad-module-skill-forge 7.0.0 → 8.1.0

package/src/skf-test-skill/scripts/gap-ledger.py

@@ -115,25 +115,51 @@ cites (never read; default `metadata.json`):
             name it (outside the citations), or on the next non-blank line
             after one, cite exactly one of those files: the gap
             is at that file's `declared_in` item, and two cited or none
-            leave it Medium. The documented extra's issue names the line
-            that documents it (with --skill-dir) and its remediation asks no
+            leave it Medium. The documented extra's remediation asks no
             change (update-skill never routes it) and says whether signature
             scoring compared its documented signature (a name the
             --signatures result lists in `comparedNames`). `excluded` is
             read once a stale name that is not fabricated needs it, and a
             malformed one is then INVALID_INPUT. Any other is a Medium `stale-documentation` gap
-            `Stale documentation: {name}` at the first line of SKILL.md,
-            then of references/*.md in path order, that writes the name
-            (validate-inventory.py's match, with --skill-dir), else
-            `SKILL.md`. One whose `excluded.outsideScope` row says the brief
+            `Stale documentation: {name}` at the line that documents the
+            name (with --skill-dir), else `SKILL.md`. That line is the
+            first that writes it as an export, the first tier that holds
+            the name winning: (1) its first origin in the documented
+            inventory's floor (load-coverage-inputs.py floor); (2) a
+            heading, or the first cell of a table whose header's first
+            cell names exports (floor's table headers), whose text is the
+            name or holds a code span floor reads as the name; (3) a line
+            whose inline code span is the name, or the name directly
+            followed by `(`; (4) a column-0 declaration of it in a fenced
+            block of a language floor's `_declared_names` reads (JS/TS,
+            Python, Rust, Go), cited or not, so a def an example writes
+            under the name is cited only when nothing above documents it;
+            (5) a line of a fenced block that holds the name as a whole
+            quoted string (`"name"` or `'name'`), such as an `__all__` item.
+            Tiers 2 to 5 read SKILL.md, then every .md file under
+            references/, subfolders included, in path order, outside the
+            frontmatter (2 and 3 outside fenced code and HTML comments, 4
+            and 5 inside a fence outside an HTML comment and a data block
+            (json, yaml...)); within a tier the first file, then its lowest
+            line, wins. A bare word, a span that holds the name among other
+            words (`uitripled add`), or a quoted string outside a fence or
+            holding other words too (`"add x"`) documents nothing; with no
+            such line, or without --skill-dir, the Source is `SKILL.md`.
+            Floor's InputError (no SKILL.md, or a top-level file it cannot
+            read or decode) leaves tier 1 empty, and a skill file that
+            cannot be read leaves tiers 2 to 5 empty. One whose
+            `excluded.outsideScope` row says the brief
             scopes its file out (`excludeGlob`, the `scope.exclude` glob
             that matches it, or `outsideInclude`, no `scope.include` glob
             covering it) has its own issue, naming the entry point and the
             file and line, and remediation: to keep the documentation,
             narrow that exclude glob (a removal needs a `demoted-exclude`
             amendment) or widen `scope.include`, else remove it. A row the
-            brief does not explain keeps the wording above. Scalar and
-            stack branches: a
+            brief does not explain keeps the wording above. Every stale
+            name's issue (fabricated, documented extra, stale documentation
+            or scoped out) opens with the line that documents it, as
+            `file:line` (with --skill-dir), else with `the skill`, whatever
+            its Source. Scalar and stack branches: a
             `missingCount` above 0 is one Medium `missing-export` gap
             `{missingCount} of {denominator} exports not documented` at
             `{meta}`, except that a scalar count taken from the verified
@@ -194,15 +220,26 @@ cites (never read; default `metadata.json`):
             entries its counts differ by; a barrel one sends the fix to
             Create Skill, which rebuilds `exports[]` from the source.
   provenance-line
-            --input skf-verify-provenance-completeness.py verify's result.
+            --input skf-verify-provenance-completeness.py verify's result;
+            --stale.
             Each `stale[]` item, at its `{source_file}:{source_line}` with
             `export`, by `reason`: `line-not-definition` is a Low
             `provenance-line` gap `Provenance line is not the definition of
             {export_name}` when `definition_lines` holds a line, else an Info
             `provenance-unverified` gap `Provenance line not verified for
             {export_name}`, and its issue names the base of a `folded_to`
-            variant; `file-missing` is a Low `provenance-line` gap
-            `Provenance file is missing for {export_name}`;
+            variant. When the --stale result (classify-stale) marks
+            `{export_name}` `aliased` with a `file:line` `defined_at`, that
+            Info gap's issue and remediation name the alias at `defined_at`,
+            and the remediation asks first to record the rename if no other
+            entry already has its `export_name` (`export_name` the item's
+            `renames`, else "a name a cited file declares", `reexported_as`
+            the export), else to cite the alias, moving the citations either
+            way; when `renames` is `default`, which the map keys on
+            `export_name` and so holds once, it asks only to cite the alias.
+            A --stale result that is not a list is INVALID_INPUT.
+            `file-missing` is a Low `provenance-line`
+            gap `Provenance file is missing for {export_name}`;
             `line-out-of-bounds` a Low `provenance-line` gap `Provenance line
             is out of range for {export_name}`; `line-invalid` an Info
             `provenance-unverified` gap `Provenance line not verified for
@@ -374,6 +411,9 @@ EFFORT = {
 _ID_RE = re.compile(r"^GAP-(\d{3,})$")
 _STAGE_RE = re.compile(r"^[a-z][a-z0-9-]*$")
 _RUN_ID_FROM_NAME = re.compile(r"^test-findings-(.+)\.json$")
+# A whole quoted string, `"name"` or `'name'`. The lookahead lets matches overlap, so an apostrophe earlier on the
+# line (`don't 'add'`) does not swallow the next string; the text between two strings is a harmless extra key.
+_QUOTED_RE = re.compile(r"""(?=(["'])([^"'\n]+)\1)""")
 
 
 class LedgerError(Exception):
@@ -747,7 +787,7 @@ ADAPTER_OPTIONS: dict[str, frozenset[str]] = {
     "guards": frozenset({"metadata"}),
     "numerator": frozenset({"metadata"}),
     "metadata-coherence": frozenset({"metadata"}),
-    "provenance-line": frozenset(),
+    "provenance-line": frozenset({"stale"}),
     "coherence": frozenset(),
     "structure": frozenset({"served"}),
 }
@@ -776,8 +816,10 @@ _SIBLINGS: dict[str, object] = {}
 
 def _sibling(filename: str):
     """A script beside this one, loaded once: validate-inventory.py (the
-    documented-name match the stale-documentation Source uses, and the
-    skill-citation scan the homonym pick reads)."""
+    skill-citation scan the homonym pick reads), load-coverage-inputs.py
+    (the documented inventory's floor, and its fence and table readers)
+    and locate-export-segments.py (the skill's files and line model), the
+    last two for the line that documents a stale name."""
     module = _SIBLINGS.get(filename)
     if module is None:
         path = Path(__file__).resolve().parent / filename
@@ -872,21 +914,102 @@ def _provenance_sources(provenance: dict | None) -> dict[str, str]:
     return sources
 
 
+def _documenting_lines(skill_dir: Path) -> dict[str, str]:
+    """name -> the `file:line` that documents it as an export, the first tier
+    that holds the name winning:
+
+      1. its first origin in the documented inventory's floor
+         (load-coverage-inputs.py `floor`: SKILL.md and the top-level
+         references/*.md);
+      2. a heading, or the first cell of a table whose header's first cell is
+         one of floor's `FLOOR_TABLE_HEADERS`, whose stripped text is the name
+         or holds a code span floor's `_floor_name` reads as the name;
+      3. a line whose inline code span, stripped, is the name, or the name
+         directly followed by `(`;
+      4. a column-0 public declaration of it in a fenced code block (floor's
+         `_declared_names`), cited or not, so a def an example writes under
+         the name (a connector author's own `mount_table_target`) is cited
+         only when nothing above documents it;
+      5. a raw (unmasked) line of a fenced code block that holds the name as a
+         whole quoted string (`"name"` or `'name'`), such as an `__all__`
+         item; it only replaces the bare `SKILL.md` fallback.
+
+    Tiers 2 to 5 read SKILL.md, then every .md file under references/,
+    subfolders included, in path order (locate-export-segments.py
+    `skill_files`), never the frontmatter: tiers 2 and 3 outside fenced code
+    and HTML comments, tiers 4 and 5 inside a fence outside an HTML comment
+    and a data block (json, yaml...). Within a tier the first file, then its
+    lowest line, wins. A bare word, a span that holds the name among other
+    words (`uitripled add`), or a quoted string outside a fence or holding
+    other words too (`"add x"`) documents nothing. An input a tier cannot
+    read is skipped: floor's InputError (no SKILL.md, a file that is not
+    UTF-8) leaves tier 1 empty, an unreadable file tiers 2 to 5."""
+    coverage = _sibling("load-coverage-inputs.py")
+    segments = _sibling("locate-export-segments.py")
+    # In merge order: floor, heading or export-table cell, code span, fenced declaration, quoted string.
+    tiers: list[dict[str, str]] = [{}, {}, {}, {}, {}]
+    try:
+        for entry in coverage.floor(str(skill_dir))["names"]:
+            origin = entry["origins"][0]
+            tiers[0].setdefault(entry["name"], f"{origin['file']}:{origin['line']}")
+    except coverage.InputError:
+        pass
+    try:
+        files = segments.skill_files(skill_dir)
+    except OSError:
+        files = []
+    # floor's fence filter: a fence in an HTML comment or a data block declares and quotes nothing, and a Svelte
+    # block's `export let` is a component prop. Unlike floor, an unheaded fence counts; a Svelte, shell or untagged
+    # fence's quoted strings count too.
+    js_family = segments.JS_FAMILY - {"svelte"}
+    for rel, lines in files:
+        start = segments._frontmatter_end(lines)
+        blocks, code = segments._fenced_blocks(lines, start)
+        comments = coverage._html_comment_lines(lines, start, code)
+        for opening, closing, info in blocks:
+            language = segments._language(info)
+            if opening in comments or language in segments.DATA_LANGUAGES:
+                continue
+            raw = lines[opening + 1:closing]
+            masked = segments.mask_code("\n".join(raw), language).split("\n")
+            for offset, declared in coverage._declared_names(masked, language, js_family):
+                tiers[3].setdefault(declared, f"{rel}:{opening + offset + 2}")
+            for offset, line in enumerate(raw):
+                for match in _QUOTED_RE.finditer(line):
+                    tiers[4].setdefault(match.group(2), f"{rel}:{opening + offset + 2}")
+        headings, prose = segments._prose(lines, start, code)
+        shaped = [(index, text) for index, _level, text, _above in headings]
+        written = list(shaped)
+        for block in prose:
+            written += [(i, lines[i]) for i in range(block["start"], block["end"] + 1)]
+            if block["kind"] == "table-row" and block["header"] is not None:
+                if coverage._header_word(coverage._cells(block["header"])[0]) in coverage.FLOOR_TABLE_HEADERS:
+                    shaped.append((block["start"], coverage._cells(lines[block["start"]])[0]))
+        for index, text in sorted(shaped):
+            for key in [text.strip()] + [coverage._floor_name(span) for span in segments._inline_code(text)]:
+                if key:
+                    tiers[1].setdefault(key, f"{rel}:{index + 1}")
+        for index, text in sorted(written):
+            for span in map(str.strip, segments._inline_code(text)):
+                for key in (span, span.split("(", 1)[0] if "(" in span else None):
+                    if key:
+                        tiers[2].setdefault(key, f"{rel}:{index + 1}")
+    found: dict[str, str] = {}
+    for tier in tiers:
+        for key, line in tier.items():
+            found.setdefault(key, line)
+    return found
+
+
 def _documenting_line(skill_dir: Path, name: str) -> str | None:
-    """The first line of SKILL.md, then of references/*.md in path order,
-    that writes `name` (validate-inventory.py's match), as `file:line`."""
-    pattern = _sibling("validate-inventory.py").name_pattern(name)
-    refs = skill_dir / "references"
-    files = [skill_dir / "SKILL.md"] + (sorted(refs.glob("*.md")) if refs.is_dir() else [])
-    for path in files:
-        try:
-            text = path.read_bytes().decode("utf-8-sig", errors="replace")
-        except OSError:
-            continue
-        for number, line in enumerate(text.split("\n"), start=1):
-            if pattern.search(line):
-                return f"{path.relative_to(skill_dir).as_posix()}:{number}"
-    return None
+    """The `file:line` that documents `name` as an export in the skill at
+    `skill_dir` (`_documenting_lines`), else None."""
+    return _documenting_lines(skill_dir).get(name)
+
+
+def _documents(doc: str | None, name: str) -> str:
+    """The subject of a stale name's Issue: the line that documents it, else the skill."""
+    return f"{f'`{doc}`' if doc else 'the skill'} documents `{name}`"
 
 
 def _scoped_out_by(row: dict) -> bool:
@@ -1069,8 +1192,8 @@ def _scoped_out_gap(name: str, row: dict, doc: str | None, brief: str) -> dict:
         f"Decide whether `{name}` belongs on the surface: `{brief}` scopes out `{at}`, where it is defined, since "
         f"{' and '.join(causes)}. To keep its documentation, {' and '.join(fixes)}; else remove the documentation "
         f"of `{name}` at {doc or 'SKILL.md'}.",
-        issue=f"{f'`{doc}`' if doc else 'SKILL.md'} documents `{name}`, which {who} exports and `{at}` defines, a "
-              f"file `{brief}` scopes out (`excluded.outsideScope`)",
+        issue=f"{_documents(doc, name)}, which {who} exports and `{at}` defines, a file `{brief}` scopes out "
+              "(`excluded.outsideScope`)",
         export=name)
 
 
@@ -1113,9 +1236,13 @@ def _stale_gaps(cov: dict, surface: dict | None, stale: object, scored: set[str]
         if not isinstance(stale, list):
             raise AdapterError("--stale is not classify-stale JSON (a list)")
         classified = {i["name"]: i for i in stale if isinstance(i, dict) and isinstance(i.get("name"), str)}
-    for name in _names(cov, "stale", "--input"):
+    names = _names(cov, "stale", "--input")
+    # the lines that document each name, read once for every stale name
+    documenting = _documenting_lines(Path(skill_dir)) if skill_dir and names else {}
+    for name in names:
         item = classified.get(name) or {}
         cited = item.get("source")
+        doc = documenting.get(name)
         if item.get("fabricated") is True:
             if not isinstance(cited, str) or not cited:
                 # a Critical gap needs the line it cites: never downgrade it
@@ -1124,14 +1251,13 @@ def _stale_gaps(cov: dict, surface: dict | None, stale: object, scored: set[str]
                 "Critical", "fabricated-signature", f"Fabricated signature: {name}", cited,
                 f"Remove `{name}` from SKILL.md and references/, or correct it to the export the source "
                 f"defines: no file its provenance cites defines it (`{cited}`).",
-                issue=f"SKILL.md documents `{name}`, which the source API surface lacks and the cited "
-                      "file does not define",
+                issue=f"{_documents(doc, name)}, which the source API surface lacks and the cited file does "
+                      "not define",
                 export=name))
             continue
         if not outside_read:
             outside, outside_read = _outside_scope(surface), True
         extra = _documented_extra_at(name, item, outside, skill_dir)
-        doc = _documenting_line(Path(skill_dir), name) if skill_dir else None
         if extra:
             declared, among = extra
             # a homonym: the one declaring file the skill's own citations name
@@ -1146,8 +1272,8 @@ def _stale_gaps(cov: dict, surface: dict | None, stale: object, scored: set[str]
                 "Info", "observation", f"Documented extra: {name}", declared,
                 f"No change: `{name}` is a documented extra, a name the source still declares at "
                 f"`{declared}` outside the enumerated surface, and its documentation stays. {checked}",
-                issue=f"{f'`{doc}`' if doc else 'the skill'} documents `{name}`, which the enumerated source API "
-                      f"surface lacks and the source still declares{picked}",
+                issue=f"{_documents(doc, name)}, which the enumerated source API surface lacks and the source "
+                      f"still declares{picked}",
                 export=name))
             continue
         if outside is not None and name in outside and _scoped_out_by(outside[name]):
@@ -1158,7 +1284,7 @@ def _stale_gaps(cov: dict, surface: dict | None, stale: object, scored: set[str]
             "Medium", "stale-documentation", f"Stale documentation: {name}", doc or "SKILL.md",
             f"Check `{name}` against the source and update or remove its documentation at "
             f"{doc or 'SKILL.md'}: the enumerated source surface does not export it.",
-            issue=f"SKILL.md documents `{name}`, which the enumerated source API surface lacks",
+            issue=f"{_documents(doc, name)}, which the enumerated source API surface lacks",
             export=name))
     return records
 
@@ -1448,10 +1574,50 @@ def from_metadata_coherence(result: object, metadata: str | None = None) -> list
     return records
 
 
-def from_provenance_line(result: object) -> list[dict]:
+def _aliased_items(stale: object) -> dict[str, dict]:
+    """name -> its classify-stale item (`--stale`) when it is `aliased` with a `file:line` `defined_at`: a rename
+    elsewhere declares the name, so a provenance line gap of it names the alias. Raises AdapterError, as the
+    coverage adapter does, when the result is not a list."""
+    if stale is None:
+        return {}
+    if not isinstance(stale, list):
+        raise AdapterError("--stale is not classify-stale JSON (a list)")
+    return {i["name"]: i for i in stale
+            if isinstance(i, dict) and isinstance(i.get("name"), str) and i.get("reason") == "aliased"
+            and isinstance(i.get("defined_at"), str) and i["defined_at"].rpartition(":")[0]
+            and i["defined_at"].rpartition(":")[2].isdigit()}
+
+
+def _alias_fix(name: str, file: str, item: dict) -> str:
+    """The remediation of an unverified provenance line of a name classify-stale found `aliased` (`item`): record
+    the rename if no other entry already has its `export_name`, else cite the alias. The map keys on
+    `export_name`, so it holds one `default` entry at most (a barrel of `export { default as X }` lines renames
+    several): a rename of `default` takes the alias alone. It never says which cited file declares the renamed
+    name: any checked entry's may."""
+    alias, local = item["defined_at"], item.get("renames")
+    alias_file, _, alias_line = alias.rpartition(":")
+    named = isinstance(local, str) and bool(local)
+    renamed = f"`{local}`" if named else "a name a cited file declares"
+    of = f"{renamed}, which a cited file declares" if named else renamed
+    head = (f"`{name}` is an alias of {of}; the source declares the alias at `{alias}`, and no line of `{file}` "
+            f"defines `{name}`. ")
+    cite = (f"the alias: set `source_file` to `{alias_file}` and `source_line` to `{alias_line}`, and move the "
+            f"citations of `{name}` there.")
+    if local == "default":
+        return f"{head}Cite {cite}"
+    guard = f"`export_name` {renamed}" if named else "that name as its `export_name`"
+    return (f"{head}If no other entry already has {guard}, record the rename in this provenance entry: set "
+            f"`export_name` to {renamed}, add `reexported_as` `{name}`, cite the line that declares {renamed} and "
+            f"move the citations of `{name}` to that line. Or cite {cite}")
+
+
+def from_provenance_line(result: object, stale: object = None) -> list[dict]:
     """verify's `stale[]` items: provenance line gaps, one per citation that does not resolve or is not the
-    definition line."""
+    definition line. `stale` (classify-stale's result, `--stale`, or None) gives the names a rename declares: an
+    unverified line of one names the alias and, unless the name it renames is `default`, how to record the rename
+    (#911)."""
     result = _object(result, "--input (skf-verify-provenance-completeness.py verify)", "stale")
+    aliased = _aliased_items(stale)
     records: list[dict] = []
     for item in _list(result, "stale", "--input"):
         if not isinstance(item, dict):
@@ -1506,12 +1672,16 @@ def from_provenance_line(result: object) -> list[dict]:
                       f"it; the lines that define it are {lines}.{folded}",
                 export=name))
         else:
-            records.append(_gap(
-                "Info", "provenance-unverified", f"Provenance line not verified for {name}", where,
+            alias = aliased[name] if isinstance(name, str) and name in aliased else None
+            fix = _alias_fix(name, file, alias) if alias else (
                 f"Open `{file}` and confirm that line {line} defines `{base or name}`; if another line does, set "
-                "the provenance `source_line` to it.",
-                issue=f"the line-check rules found no definition line for `{name}` in `{file}`; check by hand"
-                      + (f".{folded}" if folded else ""),
+                "the provenance `source_line` to it.")
+            issue = (f"no line of `{file}` defines `{name}`: the source declares it only as the alias at "
+                     f"`{alias['defined_at']}`" if alias else
+                     f"the line-check rules found no definition line for `{name}` in `{file}`; check by hand")
+            records.append(_gap(
+                "Info", "provenance-unverified", f"Provenance line not verified for {name}", where, fix,
+                issue=issue + (f".{folded}" if folded else ""),
                 export=name))
     return records
 
@@ -1680,7 +1850,8 @@ def build_records(args: argparse.Namespace) -> list[dict]:
     if kind == "metadata-coherence":
         return from_metadata_coherence(data, args.metadata)
     if kind == "provenance-line":
-        return from_provenance_line(data)
+        stale = read_result(args.stale, "--stale") if args.stale is not None else None
+        return from_provenance_line(data, stale)
     return from_coherence(data)
 
 
@@ -1897,7 +2068,8 @@ def _build_parser() -> argparse.ArgumentParser:
                                      "the names outside scope)")
     p.add_argument("--signatures", help="coverage: score-signatures.py score's result (missingTypes)")
     p.add_argument("--numerator", help="coverage: verify-declared-numerator.py's result (absent names)")
-    p.add_argument("--stale", help="coverage: classify-stale's result (fabricated signatures, documented extras)")
+    p.add_argument("--stale", help="coverage: classify-stale's result (fabricated signatures, documented extras); "
+                                   "provenance-line: the same (the names a rename declares)")
     p.add_argument("--provenance", help="coverage: the provenance map (an absent name's Source)")
     p.add_argument("--skill-dir", help="coverage: the skill package (a stale name's documenting line)")
     p.add_argument("--metadata", help="the metadata.json path a record cites as its Source (not read)")

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

@@ -25,9 +25,11 @@ reading files and writing one JSON object:
             signature is read only where the place writes it in a fixed
             form (Signatures, below). A name is a plain
             identifier (`[A-Za-z_$][\\w$]*`) once a leading `new ` and
-            everything from the first `(` or `<` are cut, so `Meta<T>`,
-            `fetch(url): Promise<T>` and `new Client(opts)` give `Meta`,
-            `fetch` and `Client`. A dotted or `::` name gives none, so a
+            everything from the first `(`, `<` or `[` are cut, so
+            `Meta<T>`, `App[P, R]`, `fetch(url): Promise<T>` and
+            `new Client(opts)` give `Meta`, `App`, `fetch` and `Client`;
+            an empty `[]` at the cut (a TS array type, `Foo[]`) gives
+            none. A dotted or `::` name gives none, so a
             namespace-style skill such as zod (`z.object`) gets no table
             floor. The forms, read outside the frontmatter and HTML
             comments (a table row or heading inside fenced code gives none):
@@ -614,12 +616,16 @@ def census(skill_dir: str) -> dict:
 
 
 def _floor_name(text: str) -> str | None:
-    """The plain identifier `text` writes once a leading `new ` and everything from the first `(` or `<` are
-    cut; None for any other text, a dotted or `::` name among them."""
+    """The plain identifier `text` writes once a leading `new ` and everything from the first `(`, `<` or `[` are
+    cut; None for any other text, a dotted or `::` name and an array type (`Foo[]`, an empty `[]` at the cut)
+    among them."""
     text = text.strip()
     if text.startswith("new "):
         text = text[4:]
-    text = re.split(r"[(<]", text, maxsplit=1)[0].strip()
+    cut = re.match(r"([^(<\[]*)(\[\s*\])?", text)
+    if cut.group(2):
+        return None
+    text = cut.group(1).strip()
     return text if PLAIN_IDENTIFIER_RE.fullmatch(text) else None
 
 

package/src/skf-test-skill/templates/test-report-template.md

@@ -25,9 +25,10 @@ nextWorkflow: ''
 Each stage writes its section in place of the heading below that it owns and
 the placeholder comment under that heading, so every heading occurs once.
 Before the result files are written, report.md §4c checks that each heading
-occurs exactly once and that no placeholder comment is left: a stage that
-skipped its section stops the run there. Do not reorder or delete the
-headings or their placeholder comments.
+occurs exactly once, that no placeholder comment is left and that the title
+above names the skill (init.md §6c fills it): a stage that skipped its
+section stops the run there. Do not change the title line, and do not
+reorder or delete the headings or their placeholder comments.
 
 Heading / owning step:
   Test Summary        → detect-mode §2

package/src/skf-update-skill/SKILL.md

@@ -86,7 +86,7 @@ Headless callers: the inputs, flags, gate map, outputs and the `SKF_UPDATE_RESUL
    uv run {resolveCustomizationHelper} --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-update-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. Record the warning in the run log at once: write `customization_resolver_unavailable: <reason>` to `{run_dir}/resolver-warning.txt` with a file write (a resolver error can hold quotes or `$( )`, so never echo it or type it into an argument), then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/resolver-warning.txt")"` from `{project-root}`.
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-update-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `SKF helper skf-resolve-customization.py not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. Record the warning in the run log at once: write `customization_resolver_unavailable: <reason>` to `{run_dir}/resolver-warning.txt` with a file write (a resolver error can hold quotes or `$( )`, so never echo it or type it into an argument), then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/resolver-warning.txt")"` from `{project-root}`.
 
    Apply the resolved values so no surface is a silent no-op: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (entries prefixed `file:` are paths or globs whose contents load as facts: the bundled default loads every `project-context.md` under `{project-root}`; an entry prefixed `!` drops each earlier entry it names and loads nothing itself, so an override's `"!file:{project-root}/**/project-context.md"` turns that default off); resolve `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string, and stash it in workflow context (`references/report.md` §5b runs it after a finished run's result files, never in `--detect-only`, `--dry-run` or a halt; empty = no-op). After activation completes, execute each entry in `workflow.activation_steps_append` in order before `init.md` runs.
 

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

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

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

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

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

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

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

@@ -246,18 +246,19 @@ When `{run_dir}/warnings.jsonl` holds a `workspace-clone-not-updated:` line, add
 
 ### 5b. Result Contract
 
-The shared emitter writes the result contract and prints the line; never type either. Stage the payload in the run folder, from the files this run wrote rather than from memory (`{run_dir}/change-manifest.json` for the counts, the artifacts write.md wrote for `files_written`, the Validation Summary §3 read for `validation_status`):
+The shared emitter writes the result contract and prints the line; never type either. Stage the payload in the run folder, from the files this run wrote rather than from memory (`{run_dir}/change-manifest.json` for the counts, the artifacts write.md wrote for `files_written`, the Validation Summary §3 read for `validation_status` and for `security_result`, the first word of its `Security` row with `PASS` as `pass`, `WARN` as `warn` and `SKIP` as `skipped`, left out of the payload and its `summary` when that row is missing or starts with another word; §1, §1a and §1b run no scan and leave `security_result` out):
 
 ```bash
 cat > "{run_dir}/result-context.json" <<'SKF_JSON'
-{"status": "success", "skill_name": "{skill_name}", "version": "{new_version}", "previous_version": "{baseline_version}", "update_mode": "{update_mode}", "files_written": [<each artifact write.md wrote and verified: SKILL.md, references (when this run wrote, added or removed a references/*.md file, as the files on disk show), metadata.json, provenance-map.json, evidence-report.md, context-snippet.md, active-symlink>], "error": null,
- "result_contract": {"skill": "skf-update-skill", "status": "success", "outputs": [{"type": "skill", "path": "<each modified file's path>"}], "summary": {"update_status": "success", "exports_affected": <total_export_changes, or the gap count in gap-driven mode>, "files_modified": <the files written>, "validation_status": "<passed, warnings or failures>"}}}
+{"status": "success", "skill_name": "{skill_name}", "version": "{new_version}", "previous_version": "{baseline_version}", "update_mode": "{update_mode}", "security_result": "<pass, warn or skipped>", "files_written": [<each artifact write.md wrote and verified: SKILL.md, references (when this run wrote, added or removed a references/*.md file, as the files on disk show), metadata.json, provenance-map.json, evidence-report.md, context-snippet.md, active-symlink>], "error": null,
+ "result_contract": {"skill": "skf-update-skill", "status": "success", "outputs": [{"type": "skill", "path": "<each modified file's path>"}], "summary": {"update_status": "success", "exports_affected": <total_export_changes, or the gap count in gap-driven mode>, "files_modified": <the files written>, "validation_status": "<passed, warnings or failures>", "security_result": "<pass, warn or skipped>"}}}
 SKF_JSON
 ```
 
-Then, from `{project-root}`, run the emitter with the run folder and the new version's forge folder:
+Then, from `{project-root}`, create the version's forge folder and run the emitter with the run folder and that folder. The emitter writes result files only into a folder that exists, and §1's no-change exit may find none when the skill's provenance map is still flat; a folder that cannot be created leaves a `result_file_write_failed` warning, so the hook does not run:
 
 ```bash
+mkdir -p "{forge_version}" || uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning 'result_file_write_failed: cannot create the version forge folder'
 uv run {emitEnvelopeHelper} emit --workflow skf-update-skill --run-dir "{run_dir}" --result-dir "{forge_version}" < "{run_dir}/result-context.json"
 ```
 
@@ -267,12 +268,22 @@ 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[]`. 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.
+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}` when the run is interactive, when no emitter resolved or when the failure line below fails too, 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.
+A headless run whose emitter resolved then prints a failure line in place of the result line, so a pipeline learns why the run has none. From `{project-root}`, run `emit-halt` with the values staged in `{run_dir}/result-context.json` and with no `--result-dir` (with one, `emit-halt` would overwrite `update-skill-result-latest.json`):
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-update-skill --run-dir "{run_dir}" <<'SKF_JSON'
+{"status": "halted-for-write-failure", "phase": "report:result-contract", "path": "{forge_version}", "reason": "result-contract-not-written: <the emitter's message>", "skill_name": "{skill_name}", "version": "<the staged version>", "previous_version": "<the staged previous_version>", "update_mode": "<the staged update_mode>", "files_written": [<the staged files_written>]}
+SKF_JSON
+```
+
+Leave `files_written` out when the emitter's message names it (the line then holds `[]`), and write each value as a JSON string, as init.md's halt procedure does: escape `"` and `\`, and write every path with `/`. Bind `{result_envelope_line}` to the line it prints and do not display it here: the shared health check displays it as the run's last line. When it exits non-zero or prints no line, bind nothing. Either way the run has no result contract (`emit-halt` writes none, even when it exits 0): skip the hook with the no-result-contract line below, then go on to §6. The failure line undoes nothing: what this run wrote stays in place.
+
+- `status`: `"success"` here; §1 stages `"no-changes"`, §1a `"detect-only"` and §1b `"dry-run"`; the failure line above prints `"halted-for-write-failure"` at `error.phase` `report:result-contract`; 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.
+- `error`: null on every exit this step prints except the failure line above, which carries `{phase: "report:result-contract", path, reason}`. 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`, `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, 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: