bmad-module-skill-forge 3.0.0 → 5.0.0

package/src/skf-test-skill/scripts/stage-helper-payload.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 # /// script
 # requires-python = ">=3.11"
-# dependencies = []
+# dependencies = ["pyyaml"]
 # ///
 """Print the stdin payload of a shared SKF helper, read from the files on disk.
 
@@ -13,7 +13,7 @@ This script reads the files and prints the payload, and the step pipes it
 into the helper:
 
   uv run stage-helper-payload.py detect-workspaces --source-root <dir> \\
-      | uv run skf-detect-workspaces.py
+      [--brief <skill-brief.yaml>] | uv run skf-detect-workspaces.py
 
 (The Quick-tier export scan needs no payload: skf-extract-public-api.py
 --mode quick reads its files itself, with --manifest-file and --entry-file.)
@@ -24,28 +24,48 @@ detect-workspaces prints {"tree": [...], "manifests": {...}}:
              it, sorted. Folders named in SKIPPED_DIRS (installed
              dependencies, virtual environments, build output, caches) and
              hidden folders (a name that starts with ".") are not read, and a
-             linked folder is not followed.
+             linked folder is not followed. With --brief, the tree is the
+             detector's scoped_tree of it under the brief's scope.exclude
+             globs (#780): a workspace member counts only through the files
+             the brief keeps, so excluding a member's source files drops it,
+             excluding only its manifest does not, every root manifest
+             stays, and a workspace with no member left is no workspace.
   manifests  the text of each file directly in --source-root that is not
              hidden, holds at most MAX_ROOT_FILE_BYTES and reads as UTF-8, by
-             its name. The detector reads the root manifests it knows
-             (package.json, pnpm-workspace.yaml, lerna.json, Cargo.toml ...)
-             and ignores the rest, so this script keeps no list of their
-             names to fall out of step with the detector's.
+             its name, whatever the brief excludes. The detector reads the
+             root manifests it knows (package.json, pnpm-workspace.yaml,
+             lerna.json, Cargo.toml ...) and ignores the rest, so this script
+             keeps no list of their names to fall out of step with the
+             detector's.
+
+--brief reads the brief with load-coverage-inputs.py's read_brief (the
+script beside this one, which loads skf-resolve-authoritative-files.py's
+parse_brief_yaml from the shared scripts folder), and matches each
+scope.exclude glob by its glob_match, skf-resolve-authoritative-files.py's
+rule (`**` spans any number of path segments, none included; `*` and `?`
+stay inside one), the rule skf-extract-public-api.py applies to the same
+brief. skf-detect-workspaces.py's scoped_tree, loaded from the shared
+scripts folder (SHARED_SCRIPTS), keeps the paths: the monorepo arm of
+skf-extract-public-api.py reads the same function.
 
 The payload is one line of ASCII JSON on stdout, so a pipe carries the same
 bytes on every platform.
 
 Exit codes:
   0  the payload is printed
-  1  --source-root is not a folder; one JSON line {"status": "error",
-     "error": ...} goes to stderr and nothing to stdout, so the helper the
-     payload was piped into reads no input and fails too
+  1  --source-root is not a folder, or --brief cannot be read (missing, not
+     UTF-8, not YAML, a value YAML cannot build such as an invalid date, not
+     a mapping, PyYAML not installed) or a script it loads is missing; one
+     JSON line {"status": "error", "error": ...} goes to stderr and nothing
+     to stdout, so the helper the payload was piped into reads no input and
+     fails too
   2  bad arguments (argparse: a missing or unknown argument, usage on stderr)
 """
 
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import json
 import os
 import sys
@@ -57,6 +77,9 @@ SKIPPED_DIRS = frozenset({
     "venv", "site-packages", "__pycache__", "target",
 })
 MAX_ROOT_FILE_BYTES = 1024 * 1024
+SCRIPTS = Path(__file__).resolve().parent
+# skf-detect-workspaces.py's folder, installed and in src/ alike.
+SHARED_SCRIPTS = SCRIPTS.parent.parent / "shared" / "scripts"
 
 
 class StageError(Exception):
@@ -70,6 +93,29 @@ def _source_root(value: str) -> Path:
     return root
 
 
+def _load(folder: Path, filename: str):
+    """A script in `folder`, loaded as a module, as load-coverage-inputs.py loads its siblings."""
+    path = folder / filename
+    spec = importlib.util.spec_from_file_location("skf_" + filename[:-3].replace("-", "_"), path)
+    if spec is None or spec.loader is None or not path.is_file():
+        raise StageError(f"{filename} not found in {folder}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def scoped_tree(tree: list[str], brief: str) -> list[str]:
+    """The paths of `tree` workspace detection reads under the brief at `brief`."""
+    inputs = _load(SCRIPTS, "load-coverage-inputs.py")
+    try:
+        excludes = inputs.read_brief(brief)["scope"]["exclude"]
+    except inputs.InputError as exc:
+        raise StageError(str(exc)) from exc
+    except ValueError as exc:  # a value YAML cannot build, such as an invalid date
+        raise StageError(f"--brief {brief} is not valid YAML: {' '.join(str(exc).split())}") from exc
+    return _load(SHARED_SCRIPTS, "skf-detect-workspaces.py").scoped_tree(tree, excludes, inputs.glob_match)
+
+
 # --------------------------------------------------------------------------
 # detect-workspaces
 # --------------------------------------------------------------------------
@@ -105,9 +151,13 @@ def root_texts(root: Path) -> dict[str, str]:
     return texts
 
 
-def workspaces_payload(source_root: str) -> dict:
+def workspaces_payload(source_root: str, brief: str | None = None) -> dict:
+    """The tree (with `brief`, the part of it the brief keeps) and the root files."""
     root = _source_root(source_root)
-    return {"tree": list_tree(root), "manifests": root_texts(root)}
+    tree = list_tree(root)
+    if brief is not None:
+        tree = scoped_tree(tree, brief)
+    return {"tree": tree, "manifests": root_texts(root)}
 
 
 # --------------------------------------------------------------------------
@@ -116,7 +166,7 @@ def workspaces_payload(source_root: str) -> dict:
 
 
 def _cmd_detect_workspaces(args: argparse.Namespace) -> dict:
-    return workspaces_payload(args.source_root)
+    return workspaces_payload(args.source_root, args.brief)
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -128,6 +178,7 @@ def _build_parser() -> argparse.ArgumentParser:
 
     p = sub.add_parser("detect-workspaces", help="the tree and root files for skf-detect-workspaces.py")
     p.add_argument("--source-root", required=True, help="the local source folder")
+    p.add_argument("--brief", help="the skill brief, whose scope.exclude globs leave paths out of the tree")
     p.set_defaults(func=_cmd_detect_workspaces)
 
     return parser

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

@@ -10,7 +10,8 @@ trust subagent output blindly: before any downstream step consumes the
 documented inventory, the shape is validated. That validation is pure
 structural checking — strip wrapping fences, parse JSON, assert required keys
 and types, assert each export entry is a dict with a non-empty `name` and a
-`kind` drawn from a fixed enum, and assert each cross-check mismatch carries its
+`kind` drawn from a fixed enum (and, when present, a `signature_form` of
+`partial` or `full`), and assert each cross-check mismatch carries its
 five fields — with exactly one correct pass/fail per input and no
 interpretation of meaning. It is therefore script work, not prompt work; the
 prompt reads this verdict and owns only the HALT decision.
@@ -26,6 +27,15 @@ violation, and the prompt re-dispatches the subagent with them, as it does
 for a schema violation. No grep runs in the prompt, so an export named
 `$state` or `a.b` is never a shell variable or a regex.
 
+An entry's optional `signature_form` says how the skill presents its
+signature: `partial` only when the skill labels the form partial (a
+simplified form, a key-parameter summary, a `...` that stands in for
+omitted members, not rest or variadic syntax), `full` otherwise.
+A JSON null counts as absent, and an absent one as `full`. Any other value
+is a violation naming the entry. score-signatures.py reads it: an optional
+member a partial form leaves out is an Info observation, not a wrong
+signature.
+
 Distinct from reconcile-coverage.py (coverage numerator arithmetic) and
 compute-score.py (weight tables): this script only validates the *shape* of the
 subagent inventory and, on success, echoes the fence-stripped parsed inventory
@@ -50,6 +60,14 @@ skf-scan-skill-md-structure.py usage-scope): on a side where the name ends
 in a letter, digit, `_` or `$`, the next character may not be one of those.
 So `get` is found in `get(url)` but not in `target` or `getAll`.
 
+The skill-citation scan is shared too: `_skill_cited_files` (with
+`_cited_path`, `skill_markdown_files` and `_SKILL_CITATION_RE`) gives the
+files the skill's `[AST:]` and `[SRC:]` citations name on a line of SKILL.md
+or references/**/*.md that writes a name with the match above, or on the
+next non-blank line. gap-ledger.py reads it to pick the declaration of a
+stale homonym, score-signatures.py to plan a signature check at the
+declaration the skill cites.
+
 CLI usage (mirrors reconcile-coverage.py):
   uv run validate-inventory.py --input <response file> [--output <inventory file>]
       [--skill-package <package folder>]
@@ -57,13 +75,16 @@ CLI usage (mirrors reconcile-coverage.py):
   uv run validate-inventory.py --json-input '<raw response>'    # explicit flag
   echo '<raw response>' | uv run validate-inventory.py --stdin  # piped input
 
---input reads the raw response from a file (UTF-8): coverage-check.md saves
-the subagent's response with the Write tool and passes its path, so a quote
-or an apostrophe in a description never meets a shell. --output writes the
-validated inventory object to a file (UTF-8 JSON) when it is valid, for
-the steps that read it by path; an invalid inventory removes a file left
-there by an earlier attempt. --skill-package names the skill package under
-test (the folder that holds SKILL.md) and adds the spot-check.
+--input reads the raw response from a file (UTF-8): the coverage-check.md §1
+subagent writes its response to the path it is given with the Write tool,
+and the parent saves it there with the Write tool when the subagent returned
+it instead or left the file absent or empty. coverage-check.md passes that
+path, so a quote or an apostrophe in a description never meets a shell.
+--output writes the validated inventory object to a file (UTF-8
+JSON) when it is valid, for the steps that read it by path; an invalid
+inventory removes a file left there by an earlier attempt. --skill-package
+names the skill package under test (the folder that holds SKILL.md) and
+adds the spot-check.
 
 Input: the subagent's RAW response text (JSON, optionally wrapped in a markdown
 code fence — a leading line of three backticks with an optional language tag and
@@ -73,7 +94,7 @@ Output (stdout, one object):
   {
     "valid": <bool>,             # true only when parse + every schema check pass
     "violations": [<str>, ...],  # human-readable failures; empty when valid
-    "rejectedCount": <int>,      # count of malformed exports[] entries
+    "rejectedCount": <int>,      # exports[] entries with no valid name or kind
     "exportsCount": <int>,       # len(exports) when parsed; 0 otherwise
     "inventory": {...} | null,   # fence-stripped parsed inventory when valid; null otherwise
     "completeness": {            # present when valid
@@ -102,6 +123,7 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import posixpath
 import re
 import sys
 from pathlib import Path
@@ -126,6 +148,10 @@ VALID_KINDS = (
     "adapter",
 )
 
+# The optional exports[].signature_form: `partial` only when the skill labels
+# the documented form partial, else `full` (or the key left out).
+SIGNATURE_FORMS = ("partial", "full")
+
 REQUIRED_MISMATCH_FIELDS = (
     "export",
     "skill_md_line",
@@ -208,6 +234,69 @@ def names_present(names, doc_text):
     return sorted(present)
 
 
+# --- Skill citations ----------------------------------------------------------
+
+# A source citation the skill writes, `[AST:path:L12]`, `[SRC:path:L12-34]` or `[SRC:path:L12-L34]` (one with no
+# `:L<n>` part is ignored). Groups: prefix, path, first line, the `L` of a range's end, the range's end.
+# Keep identical to _SKILL_CITATION_RE in skf-verify-provenance-completeness.py.
+_SKILL_CITATION_RE = re.compile(
+    r"\[(AST|SRC):([^\[\]\n]+?):L(\d+)(?:-(L?)(\d+))?\]"
+)
+# Any bracketed citation (`[AST:...]`, `[SRC:...]`, `[EXT:...]`): a line names a documented name outside them.
+_ANY_CITATION_RE = re.compile(r"\[[A-Z]+:[^\[\]\n]*\]")
+
+
+def _cited_path(path: str) -> str:
+    """A cited, `declared_in` or surface path as each compares: forward slashes, no `./`."""
+    path = path.strip().replace("\\", "/")
+    while path.startswith("./"):
+        path = path[2:]
+    return posixpath.normpath(path) if path else path
+
+
+def skill_markdown_files(skill_dir: Path) -> list[Path]:
+    """`SKILL.md` then every `references/**/*.md`, in a stable order.
+    Keep identical to skill_markdown_files in skf-verify-provenance-completeness.py."""
+    files: list[Path] = []
+    skill_md = skill_dir / "SKILL.md"
+    if skill_md.is_file():
+        files.append(skill_md)
+    refs = skill_dir / "references"
+    if refs.is_dir():
+        files.extend(sorted(p for p in refs.rglob("*.md") if p.is_file()))
+    return files
+
+
+def skill_markdown_lines(skill_dir: Path) -> list[list[str]]:
+    """The lines of each file skill_markdown_files lists (an unreadable one is
+    left out), read once for every name _skill_cited_files looks up."""
+    texts: list[list[str]] = []
+    for path in skill_markdown_files(skill_dir):
+        try:
+            texts.append(path.read_bytes().decode("utf-8-sig", errors="replace").split("\n"))
+        except OSError:
+            continue
+    return texts
+
+
+def _skill_cited_files(skill_dir: Path, name: str, texts: list[list[str]] | None = None) -> set[str]:
+    """The files the skill's `[AST:]` and `[SRC:]` citations name on a line of
+    SKILL.md or references/**/*.md that writes `name` outside its citations
+    (the documented-name match), or on the next non-blank line (a heading,
+    then its citation). `texts`, skill_markdown_lines(skill_dir) read once,
+    spares a caller that looks up many names reading the files again."""
+    pattern = name_pattern(name)
+    cited: set[str] = set()
+    for lines in skill_markdown_lines(skill_dir) if texts is None else texts:
+        for number, line in enumerate(lines):
+            if not pattern.search(_ANY_CITATION_RE.sub(" ", line)):
+                continue
+            following = next((ln for ln in lines[number + 1:] if ln.strip()), "")
+            for cited_line in (line, following):
+                cited.update(_cited_path(m.group(2)) for m in _SKILL_CITATION_RE.finditer(cited_line))
+    return cited
+
+
 # --- Spot-check -------------------------------------------------------------
 
 
@@ -392,6 +481,16 @@ def validate_inventory(raw, skill_package_path=None):
             f"{{{', '.join(VALID_KINDS)}}})"
         )
 
+    # The optional signature_form names one of two forms, or is left out.
+    for idx, entry in enumerate(exports):
+        if isinstance(entry, dict) and entry.get("signature_form") is not None \
+                and entry["signature_form"] not in SIGNATURE_FORMS:
+            label = f" (`{entry['name']}`)" if isinstance(entry.get("name"), str) and entry["name"] else ""
+            violations.append(
+                f"exports[{idx}]{label}: `signature_form` must be `partial` or `full` when present, "
+                f"not {json.dumps(entry['signature_form'])}"
+            )
+
     # Non-empty cross-check mismatch entries must carry all five fields.
     for idx, entry in enumerate(cross):
         if not isinstance(entry, dict):

package/src/skf-test-skill/scripts/verify-declared-numerator.py

@@ -8,11 +8,13 @@
 Lookup-and-count helper for the SKF test-skill workflow (coverage-check.md
 §2b, its "Numerator ground truth" paragraph; §4b records the gap). It fires
 only on the inflation signature
-(`stats.exports_documented == effective_denominator` exactly): the numerator
-equals the denominator, the tell of a documented count padded to force 100%
-coverage. On that signature the declared count is not trusted: every declared
-export name is looked up in the skill's documentation surface and only the
-names that actually appear count toward coverage.
+(`stats.exports_documented == effective_denominator` exactly, or, for a
+provenance map with no `::` entry, its distinct entry names number
+`effective_denominator`): the numerator equals the denominator, the tell of a
+documented count padded to force 100% coverage. On that signature the declared
+count is not trusted: every declared export name is looked up in the skill's
+documentation surface and only the names that actually appear count toward
+coverage.
 
 Distinct from reconcile-coverage.py (whose scalar/stack branches look up the §1
 inventory names and return only a residual missing *count*): this script looks

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

@@ -9,6 +9,7 @@ hardGate: ''
 testResult: ''
 score: ''
 threshold: ''
+thresholdSource: ''
 analysisConfidence: ''
 toolingStatus: ''
 workspaceDrift: ''

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

@@ -79,10 +79,10 @@ Headless callers: the inputs, flags, gate map, outputs and the `SKF_UPDATE_RESUL
    SKF_JSON
    ```
 
-4. **Resolve workflow customization.** Run:
+4. **Resolve workflow customization.** Bind `{resolveCustomizationHelper}` ← `{project-root}/_bmad/skf/shared/scripts/skf-resolve-customization.py`, else `{project-root}/src/shared/scripts/skf-resolve-customization.py` (the first that exists), and run:
 
    ```bash
-   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow
+   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}`.

package/src/skf-update-skill/references/detect-changes.md

@@ -7,8 +7,8 @@ hashContentProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-hash-content.py'
   - '{project-root}/src/shared/scripts/skf-hash-content.py'
 # `{buildChangeManifestHelper}`: §3's `build` (and §1's for a docs-only
-# skill), §2.2's `deletion-ratio` and Category C's `rename-candidates`. HALT
-# if neither exists.
+# skill), §2.2's `deletion-ratio`, Category B's `baseline-gaps` and Category
+# C's `rename-candidates`. HALT if neither exists.
 buildChangeManifestProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-build-change-manifest.py'
   - '{project-root}/src/shared/scripts/skf-build-change-manifest.py'
@@ -17,13 +17,13 @@ buildChangeManifestProbeOrder:
 provenanceGapDispatchProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-provenance-gap-dispatch.py'
   - '{project-root}/src/shared/scripts/skf-provenance-gap-dispatch.py'
-# `{detectScriptsAssetsHelper}`: Category D's script and asset walk, as
-# create-skill's. HALT if neither exists.
+# `{detectScriptsAssetsHelper}`: Category D's script and asset walk, the
+# detector create-skill runs, over the whole source. HALT if neither exists.
 detectScriptsAssetsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-detect-scripts-assets.py'
   - '{project-root}/src/shared/scripts/skf-detect-scripts-assets.py'
-# `{newFileDiffHelper}`: Category D's NEW_FILE set difference, bundled with
-# this skill.
+# `{newFileDiffHelper}`: Category D's NEW_FILE set difference, kept to the
+# skill brief's scope, bundled with this skill.
 newFileDiffHelper: 'scripts/skf-new-file-diff.py'
 # `{resolveAuthoritativeFilesHelper}`: §1b's mirror. HALT if neither exists.
 resolveAuthoritativeFilesProbeOrder:
@@ -103,6 +103,8 @@ It writes `{"mode": "docs-only", "no_changes", "changed_urls", "fetch_failed", "
 
 **The brief this run reads.** Bind `{brief_path}` ← `{forge_data_folder}/{skill_name}/skill-brief.yaml`. When `detect_only_mode` or `dry_run_mode` is true and that file exists, copy it to `{run_dir}/skill-brief.yaml` and bind `{brief_path}` to the copy: §1b and §1c write each decision there, Category A reads the scope from there, and the brief itself stays as it was. Each amendment a read-only run writes to the copy is a proposed one: add `proposed-amendment: {action} {path} ({category}); not written: {--dry-run or --detect-only}` to `warnings[]` as you write it, and step 6 lists them with the change manifest.
 
+**The scope type this run reads.** Bind `{scope_type}` ← the `scope_type` metadata.json records (init.md §2), else the `scope.type` of `{brief_path}` when that file exists and names one: a skill whose metadata.json records no scope type updates under its brief's. Category B's runner takes it as `--scope-type` and writes it to `{run_dir}/extraction.json` as `scope.type`, where step 3's `records` and step 5's `apply` read it: under `public-api`, a normal-mode update neither documents nor adds to the provenance map a new export off the runner's public surface (re-extract.md §4, write.md §3).
+
 ### 1b. Discovered Authoritative Files Protocol (Mirror)
 
 **Purpose:** mirror `skf-create-skill` §2a into update-skill. `skf-create-skill` §2a catches authoritative AI documentation files (`llms.txt`, `AGENTS.md`, `.cursorrules`, etc.) during **creation**, but a project may add these files *after* the skill was created. Without this mirror, update-skill would either miss the new file entirely (if it doesn't match the provenance map's file patterns) or classify it as a generic ADDED file in §2 Category A with no authoritative-file treatment. The mirror surfaces the discovery with the same P/S/U prompt create-skill uses, honoring any prior amendments.
@@ -309,9 +311,22 @@ Pass `--provenance-map` whenever init.md §4 found one; `--brief` (as §1c left
        -o "{run_dir}/extraction.json"
    ```
 
-   Pass `--language` and `--scope-type` when metadata.json records them. It takes no `--brief`: Category A applied the scope, and a tracked file the brief's scope leaves out (gap-driven.md §1's rule R1 excludes a rescoped export's file) keeps its exports. `--head-cap 0` keeps every match, since a dropped one would read as a deleted export. Step 3 reads this file and never runs the runner again. **Exit 1** (`incomplete`): run it once more; when still incomplete, step 2 below reads by eye each listed file with no export in `exports[]`. **Exit 2 or 3, no JSON, no candidate resolves, or Quick tier:** write `{"exports": []}` to `{run_dir}/extraction.json`; step 2 reads every listed file by eye (at Quick tier, by text pattern). Tell the user which files were read by eye.
+   Pass `--language` when metadata.json records it, and `--scope-type` when §1 bound `{scope_type}`. It takes no `--brief`: Category A applied the scope, and a tracked file the brief's scope leaves out (gap-driven.md §1's rule R1 excludes a rescoped export's file) keeps its exports. `--head-cap 0` keeps every match, since a dropped one would read as a deleted export. Step 3 reads this file and never runs the runner again. **Exit 1** (`incomplete`, its JSON written): run it once more; when still incomplete, step 2 below reads by eye each listed file with no export in `exports[]` or that an `errors[]` item lists in `unread`, and tells the user which files were read by eye. **Exit 2** (an input error, such as a file list it cannot read, or a failure it did not foresee, named in one stderr line with no JSON; `uv` failing to start it exits 2 too): HALT with status `blocked` (halt procedure: `phase: "detect-changes:category-b"`, the stderr line that holds `error:` as `reason`). No by-eye read stands in for it: the skill is not written yet, and reading every file by eye would hide the error. **Exit 3 (`no-ast-grep`), no JSON on another exit, no candidate resolves, or Quick tier:** write `{"exports": []}` to `{run_dir}/extraction.json`, with `"scope": {"type": "{scope_type}"}` when §1 bound `{scope_type}`, so step 5's `apply` can warn that a `public-api` surface was not applied; step 2 reads every listed file by eye (at Quick tier, by text pattern). Tell the user which files were read by eye.
+
+   Then, at every tier (in degraded mode there is no map: skip it), list the map's entries the runner left out that their file still declares: the runner never reports a module, an alias that renames, a dunder such as `__version__` or another Python or Rust underscore name, and step 3's diff would read each as a deleted export. From `{project-root}`, run:
+
+   ```bash
+   uv run {buildChangeManifestHelper} baseline-gaps \
+       --provenance-map "{provenance_map_path}" \
+       --extraction "{run_dir}/extraction.json" \
+       --files "{run_dir}/modified-files.json" \
+       --source-root "{source_root}" \
+       -o "{run_dir}/baseline-gaps.json"
+   ```
+
+   It writes `{"gaps": [{name, file, line, entry, export_type}], "unchecked": [{name, file, export_type}]}`: in `gaps[]` each entry of a modified file that no export of `{run_dir}/extraction.json` holds and whose file still declares it, at the line that declares it, by the verifier's rule (audit-skill's extraction snapshot applies the same one), and in `unchecked[]` each such entry no rule can check (its file neither Python nor TS/JS, a file the rule will not read, such as a test file or one with a symlink on its path, or a dotted module name), which step 2 reads by eye. Never add a gap or drop one by eye. On exit 1 (an input it cannot read, or a `skf-verify-provenance-completeness.py` beside it that cannot be loaded), no JSON, or no candidate resolves: HALT with status `blocked` (halt procedure: `phase: "detect-changes:category-b"`, its stderr as `reason`): without it, every name the runner leaves out would read as deleted.
 
-2. **What the recipes do not record.** Workers, in parallel batches (Pattern 4) when the list is long, read the modified and added files and each return ONLY `{"exports": [...]}`, with no prose and no fences. For each function export the runner found whose `params` it left null (it could not read the signature): `export_name` and `source_file` as it wrote them, with `params` (each parameter as the source writes it, `name: type`, the form the provenance map's `params` hold) and `return_type` (null when there is none), read at its `source_line`. For each export it could not find (a name `entry_point_diff.extraction_gaps[]` lists, a form Known Limitation #11 in `{extractionPatternsData}` lists, an export of a file `file_issues[]` names or that was read by eye): the same, plus `export_type`, `source_line`, `confidence: T1-low` and `extraction_method: source-read`. Write the union of their `exports` arrays to `{run_dir}/export-details.json`.
+2. **What the recipes do not record.** Workers, in parallel batches (Pattern 4) when the list is long, read the modified and added files and each return ONLY `{"exports": [...]}`, with no prose and no fences. For each function export the runner found whose `params` it left null (it could not read the signature): `export_name` and `source_file` as it wrote them, with `params` (each parameter as the source writes it, `name: type`, the form the provenance map's `params` hold) and `return_type` (null when there is none), read at its `source_line`. For each export it could not find (a name `entry_point_diff.extraction_gaps[]` lists, a name `{run_dir}/baseline-gaps.json` lists in `gaps[]`, a form Known Limitation #11 in `{extractionPatternsData}` lists, an export of a file `file_issues[]` names or that was read by eye): the same, plus `export_type`, `source_line`, `confidence: T1-low` and `extraction_method: source-read`. Record a baseline gap at its `file` and `line` (`source_line`), with, as `export_type`, its `export_type` while the declaration there still has that kind, else the kind it has now (a `variable` now declared by a `def` is a `function`, which step 3 reports as a changed kind), and the declaration's kind when the gap gives none; `params` and `return_type` as the declaration writes them, null when it has none (a module, an alias or a variable). For each `unchecked[]` entry, read its file by eye and record it the same way, at the line that declares it, only when the file still declares it. Record each name and file once: when a file read by eye whole (at Quick tier, or when the runner could not run or left the file unread) holds a name a gap or an `unchecked[]` entry lists, that read's record stands and the gap adds none. Write the union of their `exports` arrays to `{run_dir}/export-details.json`.
 
 3. **The diff.** Resolve `{structuralDiffHelper}` ← first existing path in `{structuralDiffProbeOrder}` and, from `{project-root}`, run:
 
@@ -368,15 +383,19 @@ The helper emits:
 }
 ```
 
-The compare helper reports only tracked files; NEW_FILE detection (a file present in source but absent from the provenance map) is a set-difference, so it runs through a script rather than the prompt. Pipe the same deterministic detector create-skill step 3 §4c uses (resolved via `detectScriptsAssetsProbeOrder`) into `{newFileDiffHelper}`, which subtracts the provenance map's `file_entries[].source_file` and sets aside user-authored `[MANUAL]` paths:
+A map with no `file_entries` field, or a null one (a skill with no script, asset or promoted document, or a map written before the field existed), tracks no file: the comparison lists no row and the set difference below subtracts nothing.
+
+The compare helper reports only tracked files; NEW_FILE detection (a file present in source but absent from the provenance map) is a set-difference, so it runs through a script rather than the prompt. **When `{brief_path}` does not exist** (a skill built without a brief, such as a quick skill), skip it: with no scope to keep to, the walk would read every script and asset of the repository as new. Add `new-files-not-checked: no skill brief, so no new script or asset was looked for` to `warnings[]`, write no `{run_dir}/new-files.json`, and leave `--new-files` out of §3's `build` and step 5's `apply`. Otherwise pipe the detector create-skill step 3 §4c runs (resolved via `detectScriptsAssetsProbeOrder`), which walks the whole source, into `{newFileDiffHelper}`, which keeps what the brief takes and subtracts what the map tracks:
 
 ```bash
 uv run {detectScriptsAssetsHelper} detect "{source_root}" \
-    | uv run {newFileDiffHelper} "{provenance_map_path}" \
+    | uv run {newFileDiffHelper} "{provenance_map_path}" [--brief "{brief_path}"] \
     > "{run_dir}/new-files.json"
 ```
 
-It writes `{"new_files":[{source_file, kind}], "skipped_manual":[...], "already_tracked":[...], "stats":{...}}`. §3's `build` reads both files, typing each compare row by its `file_entries[]` row's `file_type` and each new file by its `kind`: sort no row by hand. `skipped_manual[]` are user-authored files under `scripts/[MANUAL]/` or `assets/[MANUAL]/`, preserved and not touched; `already_tracked[]` were handled by the compare above.
+Pass `--brief` as Category A does, `{brief_path}` as §1c left it (in a read-only run, its copy in `{run_dir}`). On exit 2 (the detector's JSON, the map or the brief it cannot read, named in its JSON `error` on stderr, which also catches a detector that printed nothing), no JSON, or no candidate resolves: HALT with status `blocked` (halt procedure: `phase: "detect-changes:category-d"`, its `error` as `reason`).
+
+It writes `{"new_files":[{source_file, kind}], "skipped_manual":[...], "already_tracked":[...], "tracked_code":[...], "out_of_scope":[...], "intent_none":[...], "stats":{...}}`. §3's `build` reads both files, typing each compare row by its `file_entries[]` row's `file_type` and each new file by its `kind`: sort no row by hand. `skipped_manual[]` are user-authored files under `scripts/[MANUAL]/` or `assets/[MANUAL]/`, preserved and not touched; `already_tracked[]` were handled by the compare above; `tracked_code[]` are code files the map's `entries[]` cite, which Categories A and B compare; `out_of_scope[]` are paths the brief's scope leaves out, by Category A's in-scope test; `intent_none[]` are paths of a kind whose `scripts_intent` or `assets_intent` is `none` (an absent or free-text intent detects). A path in these lists is no new file and no `stats` count, so step 6's report counts each of the three lists from this file, where it shows Category D: a brief scoped wrongly shows as many paths out of scope. A new file Category A lists too stays a new file: Category A lists every changed in-scope file, a genuine script included.
 
 **Write the category JSON** to `{run_dir}/categories.json`, where §2.2 and §3 read it beside the helper files: the two flags, `degraded_mode` and `update_mode: "normal"`. Category C stays in the files its steps wrote, which §2.2, §3 and step 5's `apply` take as `--category-c` and `--ccc-pairs`:
 
@@ -488,13 +507,13 @@ The helper emits the unified manifest envelope:
   "total_export_changes": N,
   "per_file": [
     {"file_path": "...", "status": "MODIFIED|ADDED|DELETED|MOVED",
-     "exports_affected": [{name, change_type, old_line, new_line}, ...]}
+     "exports_affected": [{name, change_type, old_line, new_line, old_file?}, ...]}
   ],
   "category_d": {"scripts_modified": [...], ..., "docs_deleted": [...]}
 }
 ```
 
-`per_file` entries are sorted MODIFIED → ADDED → DELETED → MOVED, then alphabetically within each status group, so downstream stages can rely on stable ordering. MOVED entries include an extra `old_path` field. `category_d` lists the paths behind the `scripts_*`, `assets_*` and `docs_*` counts: a `docs_*` path is a tracked document, which only Category D detects, so a change to one alone is a change. `{run_dir}/change-manifest.json` is the change manifest: step 3, step 6 and step 5's `apply` read it there, so it survives a compacted context.
+`per_file` entries are sorted MODIFIED → ADDED → DELETED → MOVED, then alphabetically within each status group, so downstream stages can rely on stable ordering. MOVED entries include an extra `old_path` field, and a `MOVED_EXPORT` across files an `old_file`, the file it left, where `apply` finds its entry. `category_d` lists the paths behind the `scripts_*`, `assets_*` and `docs_*` counts: a `docs_*` path is a tracked document, which only Category D detects, so a change to one alone is a change. `{run_dir}/change-manifest.json` is the change manifest: step 3, step 6 and step 5's `apply` read it there, so it survives a compacted context.
 
 ### 4. Check for No-Change Shortcut