bmad-module-skill-forge 3.0.0 → 5.0.0

package/src/shared/scripts/skf-merge-doc-urls.py

@@ -1,18 +1,25 @@
 # /// script
 # requires-python = ">=3.11"
-# dependencies = []
+# dependencies = ["pyyaml"]
 # ///
 """SKF Merge Doc URLs — merge corpora-seeded + detected docs for a skill brief.
 
 Deterministic merge of an upstream brief's `doc_urls` (registry-seeded
 companion corpora, source: language-registry) with the docs freshly
 discovered by `skf-detect-docs.py` (mapped to the brief `{url, label, source}`
-contract). Replaces the prose dedup/suppression that lived inline in
-`skf-brief-skill/references/step-auto-brief.md` §3 — that logic is fiddly
+contract). Replaces the prose mapping, dedup and suppression that lived inline
+in `skf-brief-skill/references/step-auto-brief.md` §3. That logic is fiddly
 (normalized-URL collisions, non-corpus path segments, locale duplicates) and
 must behave identically on every run, so it belongs in a tested script.
 
-Three operations, in order:
+With --detected-file, each skf-detect-docs.py entry {url, detected_via,
+content_type} is first mapped to {url, label, source}: `source` from
+`detected_via` and `label` from `content_type`, by the two tables below (a
+content_type they do not list gives the label ""). An entry whose
+`detected_via` they do not list is never merged: `suppressed` lists it with
+reason unknown-detected-via.
+
+Three merge operations, in order:
 
   1. Normalized-URL dedup — lowercase host, strip a trailing `/index.html`
      and any trailing `/` before comparing, so a seeded `…/book/` and a
@@ -41,10 +48,18 @@ DEGRADED case is intentionally out of scope (there is no canonical corpus host
 to anchor suppression against).
 
 CLI:
+  uv run src/shared/scripts/skf-merge-doc-urls.py --scope-type <type> \
+      --detected-file <detect-docs.json> --existing-brief <skill-brief.yaml>
   echo '{"scope_type": "...", "existing": [...], "detected": [...]}' \
     | uv run src/shared/scripts/skf-merge-doc-urls.py
 
-Input (JSON object on stdin):
+Files form (stdin is not read): --detected-file holds skf-detect-docs.py's
+JSON array, mapped as above; --existing-brief is a skill-brief.yaml whose
+`doc_urls` are the existing entries (none when it has no doc_urls), read as
+skf-resolve-authoritative-files.py reads a brief; --scope-type is the scope
+type. Each flag is optional: an absent one gives no entries (or "").
+
+Input of the stdin form (a JSON object), whose entries are merged as given:
   {
     "scope_type": "full-library",
     "existing":   [{"url": "...", "label": "...", "source": "language-registry"}, ...],
@@ -54,22 +69,42 @@ Input (JSON object on stdin):
 Output (JSON object on stdout):
   {
     "doc_urls":   [{"url": "...", "label": "...", "source": "..."}, ...],
-    "suppressed": [{"url": "...", "reason": "non-corpus-segment|non-primary-locale-dup"}, ...]
+    "suppressed": [{"url": "...", "reason":
+                    "unknown-detected-via|non-corpus-segment|non-primary-locale-dup"}, ...]
   }
 
 Exit codes:
   0  success (merged list emitted)
-  2  error (bad JSON, wrong input shape)
+  2  error (bad JSON, wrong input shape, a file that cannot be read, a brief
+     that is not a YAML mapping)
 """
 
 from __future__ import annotations
 
+import argparse
+import importlib.util
 import json
 import re
 import sys
+from pathlib import Path
 from typing import Any
 from urllib.parse import urlsplit
 
+# skf-detect-docs.py's `detected_via` -> the brief's coarse provenance, the
+# skill-brief.v1.json doc_urls[].source enum (a test pins it to the schema).
+_SOURCE_BY_DETECTED_VIA = {
+    "homepageUrl": "homepage",
+    "readme_link": "readme-detection",
+    "pages_api": "pages-api",
+    "docs_folder": "docs-folder",
+}
+# skf-detect-docs.py's `content_type` -> the entry's display label.
+_LABEL_BY_CONTENT_TYPE = {
+    "api-docs": "API Documentation",
+    "guide": "Guide",
+    "reference": "Reference",
+}
+
 # Path components (case-insensitive) that mark a non-corpus page on a doc host:
 # changelogs/news, contribution guides, wikis. Matched as whole path components
 # (or component + a separator), never as a bare substring.
@@ -153,6 +188,28 @@ def _matches_non_corpus_segment(path: str) -> bool:
     return False
 
 
+def map_detected(raw: list[Any]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """skf-detect-docs.py entries as brief doc_urls entries {url, label, source}.
+
+    Returns (mapped, suppressed): an entry whose detected_via maps to no
+    source is suppressed with reason unknown-detected-via; one with no url is
+    skipped, as the merge skips it.
+    """
+    mapped: list[dict[str, Any]] = []
+    suppressed: list[dict[str, Any]] = []
+    for d in raw:
+        if not isinstance(d, dict) or not d.get("url"):
+            continue
+        via, content_type = d.get("detected_via"), d.get("content_type")
+        source = _SOURCE_BY_DETECTED_VIA.get(via) if isinstance(via, str) else None
+        if source is None:
+            suppressed.append({"url": d["url"], "reason": "unknown-detected-via"})
+            continue
+        label = _LABEL_BY_CONTENT_TYPE.get(content_type, "") if isinstance(content_type, str) else ""
+        mapped.append({"url": d["url"], "label": label, "source": source})
+    return mapped, suppressed
+
+
 def merge_doc_urls(
     scope_type: str,
     existing: list[dict[str, Any]],
@@ -232,30 +289,96 @@ def _force_utf8(*streams) -> None:
                 stream.reconfigure(encoding="utf-8", errors=errors)
 
 
-def main() -> int:
-    _force_utf8(sys.stdin, sys.stdout)
+class InputError(Exception):
+    """An input the merge cannot read (exit 2)."""
+
+
+def _read_detected(path: str) -> list[Any]:
+    """The JSON array skf-detect-docs.py wrote to `path`."""
+    try:
+        data = json.loads(Path(path).read_bytes().decode("utf-8-sig"))
+    except OSError as exc:
+        raise InputError(f"cannot read --detected-file {path}: {exc.strerror or exc}") from exc
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise InputError(f"--detected-file {path} is not JSON: {exc}") from exc
+    if not isinstance(data, list):
+        raise InputError(f"--detected-file {path} must hold a JSON array (skf-detect-docs.py output)")
+    return data
+
+
+def _brief_doc_urls(path: str) -> list[Any]:
+    """The doc_urls of the skill brief at `path`, read by
+    skf-resolve-authoritative-files.py's parse_brief_yaml (beside this file)."""
+    resolver_path = Path(__file__).resolve().parent / "skf-resolve-authoritative-files.py"
+    spec = importlib.util.spec_from_file_location("skf_resolve_authoritative_files", resolver_path)
+    if spec is None or spec.loader is None:
+        raise InputError(f"cannot load {resolver_path.name} beside {Path(__file__).name}")
+    resolver = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(resolver)
+    except (OSError, ImportError, SyntaxError) as exc:
+        raise InputError(f"cannot load {resolver_path.name} beside {Path(__file__).name}: {exc}") from exc
+    try:
+        brief = resolver.parse_brief_yaml(Path(path).read_bytes().decode("utf-8-sig"))
+    except OSError as exc:
+        raise InputError(f"cannot read --existing-brief {path}: {exc.strerror or exc}") from exc
+    except (UnicodeDecodeError, resolver.yaml.YAMLError) as exc:
+        raise InputError(f"--existing-brief {path} is not YAML: {exc}") from exc
+    if not isinstance(brief, dict):
+        raise InputError(f"--existing-brief {path} holds no brief mapping")
+    doc_urls = brief.get("doc_urls") or []
+    if not isinstance(doc_urls, list):
+        raise InputError(f"the doc_urls of --existing-brief {path} must be a list")
+    return doc_urls
+
+
+def _stdin_payload() -> tuple[str, list[Any], list[Any]]:
+    """(scope_type, existing, detected) of the stdin form."""
     raw = sys.stdin.read()
     if not raw or not raw.strip():
-        sys.stderr.write("skf-merge-doc-urls: empty stdin (expected JSON object)\n")
-        return 2
+        raise InputError("empty stdin (expected JSON object)")
     try:
         payload = json.loads(raw)
     except json.JSONDecodeError as exc:
-        sys.stderr.write(f"skf-merge-doc-urls: invalid JSON on stdin: {exc}\n")
-        return 2
+        raise InputError(f"invalid JSON on stdin: {exc}") from exc
     if not isinstance(payload, dict):
-        sys.stderr.write("skf-merge-doc-urls: input must be a JSON object\n")
-        return 2
-
-    scope_type = payload.get("scope_type") or ""
+        raise InputError("input must be a JSON object")
     existing = payload.get("existing") or []
     detected = payload.get("detected") or []
     if not isinstance(existing, list) or not isinstance(detected, list):
-        sys.stderr.write("skf-merge-doc-urls: 'existing' and 'detected' must be arrays\n")
+        raise InputError("'existing' and 'detected' must be arrays")
+    return payload.get("scope_type") or "", existing, detected
+
+
+def main(argv: list[str] | None = None) -> int:
+    _force_utf8(sys.stdin, sys.stdout)
+    parser = argparse.ArgumentParser(
+        prog="skf-merge-doc-urls",
+        description="Merge a brief's doc_urls with the docs skf-detect-docs.py found. With no flag, read the "
+                    "{scope_type, existing, detected} JSON object on stdin.",
+    )
+    parser.add_argument("--detected-file", metavar="PATH",
+                        help="skf-detect-docs.py's JSON array, mapped to {url, label, source}")
+    parser.add_argument("--existing-brief", metavar="PATH",
+                        help="the skill-brief.yaml whose doc_urls are the existing entries")
+    parser.add_argument("--scope-type", metavar="TYPE", help="the brief's scope.type")
+    args = parser.parse_args(argv)
+    unknown: list[dict[str, Any]] = []
+    try:
+        if args.detected_file is None and args.existing_brief is None and args.scope_type is None:
+            scope_type, existing, detected = _stdin_payload()
+        else:
+            scope_type = args.scope_type or ""
+            existing = _brief_doc_urls(args.existing_brief) if args.existing_brief is not None else []
+            detected = []
+            if args.detected_file is not None:
+                detected, unknown = map_detected(_read_detected(args.detected_file))
+    except InputError as exc:
+        sys.stderr.write(f"skf-merge-doc-urls: {exc}\n")
         return 2
 
     doc_urls, suppressed = merge_doc_urls(scope_type, existing, detected)
-    json.dump({"doc_urls": doc_urls, "suppressed": suppressed}, sys.stdout, ensure_ascii=False)
+    json.dump({"doc_urls": doc_urls, "suppressed": unknown + suppressed}, sys.stdout, ensure_ascii=False)
     sys.stdout.write("\n")
     return 0
 

package/src/shared/scripts/skf-parse-gaps.py

@@ -91,10 +91,13 @@ provenance map): for a gap with an `export` (null for one with none),
    "candidates": [{"source_file", "source_line", "export_type"}, ...]}
 
 `candidates` holds every entries[] row whose export_name is the export, in
-the map's order. With a `source_citation`, only the rows whose source_file
-is the citation's file count (both compared stripped, with backslashes read
-as `/` and no leading `./`), and of several such rows the one whose
-source_line is the citation's line. Without one, every candidate counts.
+the map's order; when no row has that export_name, every row whose
+`reexported_as` is the export (one the map holds under its declared name,
+which a gap names by the public name a re-export gives it), each view then
+adding the row's own `export_name`. With a `source_citation`, only the
+rows whose source_file is the citation's file count (both compared
+stripped, with backslashes read as `/` and no leading `./`), and of
+several such rows the one whose source_line is the citation's line. Without one, every candidate counts.
 One row left is `found` (its `entry`), several are `ambiguous` (a spot-check
 of the wrong one would move another export's line) and none is `not-found`.
 `match` prints {"status": "ok", "name", "citation", "map_match"} for a name
@@ -142,16 +145,34 @@ Translate (update-skill gap-driven.md §1): `translate` turns the gaps
 `parse` wrote (--gaps) into the change manifest, written to -o as
 {"mode": "gap-driven", "entries": [...]}. Each gap is routed by its
 `category` through CHANGE_CATEGORIES (gap-driven.md §1's table), never by
-its severity; a category the table does not hold is not routed. Each
-entry, in this key order:
+its severity; a category the table does not hold is not routed, and takes
+no entry, so nothing is written for it. A `stale-documentation` gap is not
+routed: the source has no line to repair the name from, and removing its
+documentation unchecked could delete a name the surface missed or one the
+source still declares. Nor is a `metadata-drift` gap: write.md §2's
+`metadata` call recounts the counts a patch would set (except under the
+drift override and for a docs-only skill, where it passes the counts
+metadata.json records), so no metadata patch holds. Each entry, in this
+key order:
 
   name                      the gap's `export`, else the answered `name`
   gap_id, category          the gap's `id`, its `category` (else the
                             answered one), `severity`
   severity
   source_citation           the gap's, left out when it is null or names a
-                            line inside the skill package (`SKILL.md` or a
-                            `references/*.md` file, under any folder)
+                            line inside the skill package: `SKILL.md` or a
+                            `.md` file under `references/`, written relative
+                            to the package, after `{skill_package}/`, or
+                            after the package folder of SKF's layout
+                            (`skills/{name}/{version}/{name}/` or
+                            `skills/{name}/`, after any leading folders)
+  package_citation          a `split-body-mismatch` gap's in-package
+                            citation, {"file", "line"}, its file relative to
+                            the package (`{skill_package}/` dropped): the
+                            file merge Priority 8 edits. Left out for any
+                            other gap, and for one whose category is a
+                            judgment's answer: an older report's Source may
+                            name the body it kept
   remediation_paths, resolved_paths, rejected_paths
                             the gap's ([] when parse had no --source-root);
                             a `provenance-completeness` gap with no
@@ -193,14 +214,20 @@ the gap's own text to judge from, each need one of:
                `provenance-completeness` gap with no path to scan
 
 --judgments answers them: a JSON object keyed by gap id, each value an
-object of `category` (a slug, or null: not routed), `name` (a string, or
+object of `category` (a slug, one the table does not route giving that
+category's reason, or null: not routed), `name` (a string, or
 null: not routed), `rescope` (true or false; given for any `missing-export`
 or `missing-type` gap, it is honoured) and `source_file` (a path relative
 to the source root, or null). Other keys are left for gap-records. With
 every need answered it writes the manifest and prints {"status":
 "written", "output", "gap_count", "not_routed": [{"id", "title",
-"category"}], "warnings": [...]}. `warnings` holds parse's warnings as
-`test-report: <warning>`, `test-report: not routed: <id> (<category>)` for
+"category", "reason"}], "warnings": [...]}. A not-routed gap's `reason`
+says why update-skill does not repair it and who does: NOT_ROUTED_REASONS
+gives one for each ledger category the table does not route (gap-driven.md
+§1's Not routed list), NO_REPAIR is the reason of a gap with no
+category or one no table holds, and NO_EXPORT that of a gap whose export
+is answered null. `warnings` holds parse's warnings as `test-report:
+<warning>`, `test-report: not routed: <id> (<category>): <reason>` for
 each gap not routed, and, with --read-only, `proposed-amendment: excluded
 <path> (scope-expansion); not written: --<mode>` for each rescope.
 
@@ -865,10 +892,16 @@ def _line_number(value: object) -> int | None:
 def map_match(entries: list, name: str, citation: dict | None) -> dict:
     """The provenance map entry an export names, keyed on its citation (see "Map match" in the module docstring)."""
     def view(entry: dict) -> dict:
-        return {key: entry.get(key) for key in ("source_file", "source_line", "export_type")}
+        out = {key: entry.get(key) for key in ("source_file", "source_line", "export_type")}
+        if entry["export_name"].strip() != name.strip():  # matched by its reexported_as: the name to check
+            out["export_name"] = entry["export_name"]
+        return out
 
-    named = [e for e in entries if isinstance(e, dict) and isinstance(e.get("export_name"), str)
-             and e["export_name"].strip() == name.strip()]
+    def named_by(key: str) -> list[dict]:
+        return [e for e in entries if isinstance(e, dict) and isinstance(e.get("export_name"), str)
+                and isinstance(e.get(key), str) and e[key].strip() == name.strip()]
+
+    named = named_by("export_name") or named_by("reexported_as")
     left = named
     if citation:
         cited = _norm_file(citation.get("file"))
@@ -959,7 +992,6 @@ CHANGE_CATEGORIES = {
     "provenance-completeness": "NEW_EXPORT",
     "signature-mismatch": "MODIFIED_EXPORT",
     "fabricated-signature": "MODIFIED_EXPORT",
-    "stale-documentation": "MODIFIED_EXPORT",
     "provenance-line": "MOVED_EXPORT",
     "split-body-mismatch": "STRUCTURAL_FIX",
     "structural": "STRUCTURAL_FIX",
@@ -969,9 +1001,50 @@ CHANGE_CATEGORIES = {
     "integration-pattern": "STRUCTURAL_FIX",
     "migration-section": "STRUCTURAL_FIX",
     "scripts-assets": "STRUCTURAL_FIX",
-    "metadata-drift": "metadata update",
     "metadata": "metadata update",
 }
+# gap-driven.md §1's Not routed list, word for word: why update-skill repairs no gap of each other ledger category,
+# and who does. A gap takes NO_REPAIR when it has no category or one no table holds, and NO_EXPORT when its export
+# is answered null.
+NOT_ROUTED_REASONS = {
+    "stale-documentation": (
+        "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": (
+        "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, so a person checks by hand that it defines the export and, "
+        "when another line does, sets its provenance `source_line` to that line"),
+    "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"),
+    "numerator-inflation": "a person documents the absent exports in SKILL.md or references/, reading each from "
+                           "the source",
+    "scripts-assets-provenance": "a person adds the file's row to the provenance map's `file_entries`, or removes "
+                                 "the file from the skill",
+    "observation": "a person applies it only when they agree, since it is advisory, and a documented extra needs no "
+                   "change",
+    "discovery": "a person improves the skill's description so realistic prompts route to it, or runs the discovery "
+                 "test Test Skill skipped",
+    "description": "a person edits the description in the SKILL.md frontmatter as the gap suggests",
+    "external-validator": "a person applies the skill-check diagnostic or Tessl Review suggestion to SKILL.md",
+}
+NO_REPAIR = "update-skill has no repair for this category, so a person follows the gap's remediation"
+NO_EXPORT = "it names no export for update-skill to repair, so a person follows the gap's remediation"
 EXPORT_CATEGORIES = ("NEW_EXPORT", "MODIFIED_EXPORT", "MOVED_EXPORT", "DELETED_EXPORT")
 RESCOPE_CATEGORIES = ("missing-export", "missing-type")  # rule R1
 COMPLETENESS = "provenance-completeness"  # rule R3
@@ -985,8 +1058,14 @@ _LEDGER_REMEDIATION = re.compile(
     r"|Find the \d+ exports the denominator counts that SKILL\.md and references/ do not name "
     r"\(`[^`\n]+` lists the exports\) and document each with its signature\."
 )
-# A citation of generated markdown: the skill's SKILL.md or a references/*.md file.
-_PACKAGE_FILE = re.compile(r"(?:^|/)(?:SKILL\.md|references/[^/]+\.md)$")
+# A citation of generated markdown: the skill's SKILL.md or a .md file under its references/, relative to the
+# package, after `{skill_package}/`, or after the package folder of SKF's layout as a project-relative path
+# (`skills/{name}/{version}/{name}/`, or the flat `skills/{name}/`, after any leading folders). A path under any
+# other folder (`docs/references/guide.md`) is source.
+_PACKAGE_FILE = re.compile(
+    r"(?:\{skill_package\}/|(?:[^/]+/)*skills/(?P<name>[^/]+)/(?:[^/]+/(?P=name)/)?)?"
+    r"(?P<file>SKILL\.md|references/(?:[^/]+/)*[^/]+\.md)")
+SPLIT_BODY = "split-body-mismatch"
 # The answers translate reads, with the JSON types each takes.
 _ANSWER_TYPES = {"category": (str, type(None)), "name": (str, type(None)), "rescope": (bool,),
                  "source_file": (str, type(None))}
@@ -994,14 +1073,38 @@ _IS_WINDOWS = os.name == "nt"
 _REPLACE_WAIT_SECONDS = 5.0
 
 
+def _package_path(citation: dict | None) -> str | None:
+    """The citation's file relative to the skill package, or None when it names no file of the package."""
+    path = _norm_file(citation.get("file")) if isinstance(citation, dict) else None
+    path = path.strip("`") if path else None
+    found = _PACKAGE_FILE.fullmatch(path) if path and ".." not in path.split("/") else None
+    return found.group("file") if found else None
+
+
 def in_skill_package(citation: dict | None) -> bool:
     """True when a citation names a line of generated markdown, not source.
 
-    >>> [in_skill_package({"file": f, "line": 1}) for f in ("SKILL.md", "{skill_package}/references/api.md", "src/a.ts")]
-    [True, True, False]
+    >>> [in_skill_package({"file": f, "line": 1}) for f in ("SKILL.md", "{skill_package}/references/api.md",
+    ...                                                     "references/integrations/a-b.md", "src/a.ts",
+    ...                                                     "skills/oms-cognee/0.5.8/oms-cognee/SKILL.md",
+    ...                                                     "docs/references/guide.md")]
+    [True, True, True, False, True, False]
     """
-    path = _norm_file(citation.get("file")) if isinstance(citation, dict) else None
-    return bool(path and _PACKAGE_FILE.search(path))
+    return _package_path(citation) is not None
+
+
+def package_citation(citation: dict | None) -> dict | None:
+    """An in-package citation with its file relative to the package, else None.
+
+    >>> for f in ("{skill_package}/references/api.md", "SKILL.md", "skills/lib/references/api.md", "src/a.ts"):
+    ...     print(package_citation({"file": f, "line": 3}))
+    {'file': 'references/api.md', 'line': 3}
+    {'file': 'SKILL.md', 'line': 3}
+    {'file': 'references/api.md', 'line': 3}
+    None
+    """
+    path = _package_path(citation)
+    return {"file": path, "line": citation.get("line")} if path else None
 
 
 def written_remediation(text: object) -> bool:
@@ -1051,9 +1154,10 @@ def translate_gaps(parsed: dict, map_entries: list, judgments: dict, *, read_onl
     entries: list[dict] = []
     not_routed: list[dict] = []
 
-    def skip(gap: dict, category: str | None) -> None:
-        not_routed.append({"id": gap["id"], "title": gap.get("title"), "category": category})
-        warnings.append(f"test-report: not routed: {gap['id']} ({category or 'no category'})")
+    def skip(gap: dict, category: str | None, reason: str | None = None) -> None:
+        reason = reason or NOT_ROUTED_REASONS.get(category or "", NO_REPAIR)
+        not_routed.append({"id": gap["id"], "title": gap.get("title"), "category": category, "reason": reason})
+        warnings.append(f"test-report: not routed: {gap['id']} ({category or 'no category'}): {reason}")
 
     def ask(gap: dict, category: str | None, want: list[str]) -> None:
         needs.append({"gap_id": gap["id"], "title": gap.get("title"), "category": category,
@@ -1079,11 +1183,14 @@ def translate_gaps(parsed: dict, map_entries: list, judgments: dict, *, read_onl
         name = export or _answer_text(answers.get("name"))
         if change in EXPORT_CATEGORIES and name is None:
             if "name" in answers:  # answered null: no export to repair
-                skip(gap, category)
+                skip(gap, category, NO_EXPORT)
             else:
                 ask(gap, category, ["name"])
             continue
         citation = gap.get("source_citation")
+        # the gap's own category, which the ledger recorded: a judged one is an older report's, whose Source may
+        # name the body that report still kept
+        package = package_citation(citation) if gap.get("category") == SPLIT_BODY else None
         if in_skill_package(citation):
             citation = None
         match = map_match(map_entries, name, citation) if name else None
@@ -1123,6 +1230,8 @@ def translate_gaps(parsed: dict, map_entries: list, judgments: dict, *, read_onl
         entry = {"name": name, "gap_id": gap["id"], "category": category, "severity": gap.get("severity")}
         if citation:
             entry["source_citation"] = citation
+        if package:
+            entry["package_citation"] = package
         entry["remediation_paths"] = list(gap.get("remediation_paths") or [])
         entry["resolved_paths"] = resolved
         entry["rejected_paths"] = rejected

package/src/shared/scripts/skf-preflight.py

@@ -49,6 +49,7 @@ SIDECAR_MISSING.
 
 from __future__ import annotations
 
+import datetime
 import json
 import re
 import stat
@@ -82,6 +83,19 @@ PLACEHOLDER_RE = re.compile(r"\{[^{}]*\}")
 FOLDER_KEYS = ("output_folder", "skills_output_folder", "forge_data_folder")
 
 
+def _json_default(value):
+    """Print a date or time as ISO 8601.
+
+    YAML reads an unquoted timestamp as a date or datetime object. SKF 1.x
+    wrote ``tier_detected_at`` and ``ccc_index.last_indexed`` in
+    forge-tier.yaml unquoted, so a sidecar from before 2.0.0 holds them; any
+    other value json cannot print is still an error.
+    """
+    if isinstance(value, (datetime.date, datetime.time)):
+        return value.isoformat()
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+
 def load_yaml_file(path):
     """Load a YAML mapping, returning (data, None) or (None, error_string).
 
@@ -304,5 +318,5 @@ if __name__ == "__main__":
             cfg_path = sys.argv[idx + 1]
 
     result = run_preflight(proj_root, cfg_path, allow_missing_sidecar="--allow-missing-sidecar" in sys.argv)
-    print(json.dumps(result, indent=2))
+    print(json.dumps(result, indent=2, default=_json_default))
     sys.exit(1 if result["status"] == "hard-halt" else 0)

package/src/shared/scripts/skf-provenance-gap-dispatch.py

@@ -78,6 +78,7 @@ Exit codes:
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import json
 import re
 import sys
@@ -256,14 +257,37 @@ _DEFERRED = "deferred-headless"
 _LEGACY_HEADLESS_REASON = "headless: no user to prompt"
 
 
+_RESOLVER = None
+
+
+def _resolver():
+    """skf-resolve-authoritative-files.py from this folder, loaded once: its
+    parse_brief_yaml reads a brief's YAML, an SKF 1.x brief's trailing `---`
+    included. Raises ValueError when it cannot be loaded."""
+    global _RESOLVER
+    if _RESOLVER is None:
+        path = Path(__file__).resolve().parent / "skf-resolve-authoritative-files.py"
+        spec = importlib.util.spec_from_file_location("skf_resolve_authoritative_files", path)
+        if spec is None or spec.loader is None:
+            raise ValueError(f"cannot load {path.name} beside {Path(__file__).name}")
+        module = importlib.util.module_from_spec(spec)
+        try:
+            spec.loader.exec_module(module)
+        except (OSError, ImportError, SyntaxError) as exc:
+            raise ValueError(f"cannot load {path.name} beside {Path(__file__).name}: {exc}") from exc
+        _RESOLVER = module
+    return _RESOLVER
+
+
 def load_brief(brief_path: Path) -> dict:
     """Parse a skill-brief.yaml file. Raises ValueError on load failure."""
     try:
         text = brief_path.read_text(encoding="utf-8")
     except OSError as exc:
         raise ValueError(f"cannot read brief at {brief_path}: {exc}") from exc
+    parse_brief_yaml = _resolver().parse_brief_yaml
     try:
-        brief = yaml.safe_load(text)
+        brief = parse_brief_yaml(text)
     except yaml.YAMLError as exc:
         raise ValueError(f"brief at {brief_path} is not valid YAML: {exc}") from exc
     if not isinstance(brief, dict):

package/src/shared/scripts/skf-render-metadata-stats.py

@@ -73,7 +73,7 @@ Judgment payload (stdin JSON, compute mode)::
 
     {
       "exports_public_api":  40,          # int  — public-entry-point export count (judgment)
-      "exports_internal":    19,          # int  — non-underscore internal export count (judgment)
+      "exports_internal":    19,          # int: internal export count, Python/Rust/Dart `_` names left out (judgment)
       "effective_denominator": 12,        # int|null — optional, curated-subset scopes only
       "pattern_surfaces_documented": 8,   # int  — reference-app only (exports_documented proxy)
       "exports_documented":  0,           # int  — stack only (own-barrel count, usually 0)

package/src/shared/scripts/skf-resolve-authoritative-files.py

@@ -109,8 +109,17 @@ import yaml
 
 # skf-classify-changed-files.py loads this file for load_brief,
 # extract_scope, glob_match, scope_match, normalize_rel_path and
-# EXCLUDED_DIR_NAMES, and skf-detect-registry.py for glob_match, load_brief
-# and extract_scope: keep those names and what they take and return.
+# EXCLUDED_DIR_NAMES (its load_scope, the brief-scope test that
+# skf-new-file-diff.py, skf-detect-scripts-assets.py --brief and
+# skf-compare-file-hashes.py --brief load from it, reads the brief through
+# them), skf-detect-registry.py for glob_match, load_brief
+# and extract_scope, skf-extract-public-api.py for glob_match and
+# parse_brief_yaml, and every other script that reads a skill brief
+# (skf-validate-brief-schema.py, skf-provenance-gap-dispatch.py,
+# skf-derive-assembly-shape.py, skf-write-skill-brief.py and skf-test-skill's
+# load-coverage-inputs.py) for parse_brief_yaml, load-coverage-inputs.py
+# also for _amendment_action: keep those names and what they take and
+# return.
 
 
 # --------------------------------------------------------------------------
@@ -270,13 +279,30 @@ def scope_match(
 # --------------------------------------------------------------------------
 
 
+def parse_brief_yaml(text: str):
+    """The one document a skill brief's YAML text holds, or None when it holds none.
+
+    SKF 1.x closed every brief with a trailing `---`, which YAML reads as a
+    second, empty document, so `yaml.safe_load` refuses such a brief. A
+    document that holds no value (empty, or an explicit null such as `~`) is
+    skipped wherever it stands; more than one document that holds a value is
+    refused with yaml.YAMLError, as is text that is not YAML.
+    """
+    documents = [doc for doc in yaml.safe_load_all(text) if doc is not None]
+    if len(documents) > 1:
+        raise yaml.YAMLError(
+            f"a skill brief is a single document; this text holds {len(documents)}"
+        )
+    return documents[0] if documents else None
+
+
 def load_brief(brief_path: Path) -> dict:
     try:
         text = brief_path.read_text(encoding="utf-8")
     except OSError as exc:
         raise ValueError(f"cannot read brief at {brief_path}: {exc}") from exc
     try:
-        brief = yaml.safe_load(text)
+        brief = parse_brief_yaml(text)
     except yaml.YAMLError as exc:
         raise ValueError(
             f"brief at {brief_path} is not valid YAML: {exc}"