bmad-module-skill-forge 5.0.0 → 7.0.0

package/src/shared/scripts/skf-build-change-manifest.py

@@ -1,6 +1,6 @@
 # /// script
 # requires-python = ">=3.11"
-# dependencies = []
+# dependencies = ["pyyaml"]
 # ///
 """SKF Build Change Manifest — aggregate category A/B/C/D detection results.
 
@@ -81,14 +81,18 @@ Subcommands:
       (the exports marked public: false), "warnings"}.
 
   gap-records --manifest <file> --provenance-map <file> [--source-root <dir>]
-              [--drift-status ok|skipped|overridden] [--judgments <file>]
-              [--remediation-records <file>] [--evidence <file> --tier <tier>]
+              [--brief <file>] [--drift-status ok|skipped|overridden]
+              [--judgments <file>] [--remediation-records <file>]
+              [--evidence <file> --tier <tier>]
               (--plan [--files-out <file>] | -o <file>)
       A gap-driven repair's spot-checks, routing and verification records
       (see "Gap records" below): --plan prints what to answer and which
       files §4a's extraction scans (targeted re-extraction, and the
       signatures of the exports a spot-check located); without it, the
       records are written to -o through a temporary file and a rename.
+      With --brief (the skill brief), no file a gap cites or its
+      Remediation names that the brief's scope leaves out is checked,
+      scanned or repaired from.
 
   baseline-gaps --provenance-map <file> --extraction <file> --files <file>
                 --source-root <dir> -o <file>
@@ -325,8 +329,8 @@ Apply (update-skill write.md §3):
   export_name, gap_category, severity, verification, in_map (the map holds
   an entry of that name), map_entry ({source_file, source_line} of the one
   entry the spot-check took, else null), source_citation, new_location,
-  unknown_reason, citation_check, map_locations (see "Gap records"),
-  pinned_definition_lines, reachability, and the located
+  unknown_reason, citation_check, map_locations, outside_scope (see "Gap
+  records"), pinned_definition_lines, reachability, and the located
   export's export_type, params, return_type, extraction_method and
   ast_node_type (from §4a's record at its line, see "Gap records"; null
   when none holds it). It finds an export's entry by its name, else by the
@@ -351,6 +355,20 @@ Apply (update-skill write.md §3):
                             per name and file, with the signature (below)
                             and the source-read labels whatever its record's
                             tool
+    unknown, outside-scope  unchanged and no entry added, whatever its
+                            severity (never refused), with a warning that
+                            names its gap_id, its unknown_reason and its
+                            words, its outside_scope (the files the brief's
+                            scope leaves out), the cause its citation_check
+                            keeps for a citation the scope takes (with its
+                            words) and the fix: when the skill covers that
+                            file, change the brief's scope so it takes it
+                            (its scope.include or scope.exclude), then
+                            re-run update-skill; otherwise re-run Test
+                            Skill (the test compared a declaration the
+                            skill does not cover). A citation_check that
+                            read nothing (UNREAD) takes its own fix in
+                            their place, as below
     unknown, not in_map, a NEW_EXPORT or MODIFIED_EXPORT, a Medium, Low or
     Info severity           an entry from --merge-records with no
                             source_file or source_line
@@ -371,6 +389,12 @@ Apply (update-skill write.md §3):
                             any other, fix the entry by hand (its
                             source_file and source_line), since the
                             re-run checks the same entry again. A
+                            missing MOVED_EXPORT, whatever its severity,
+                            takes that warning too (the gone file and
+                            the hand fix): rule R5 moves a line, never
+                            a file. A MOVED_EXPORT's warning names the
+                            pinned_definition_lines only when the test
+                            report listed any. A
                             cited-elsewhere one, whatever its severity,
                             takes in their place a warning that names
                             its gap_id, its source_citation, its
@@ -385,6 +409,12 @@ Apply (update-skill write.md §3):
                             moved, fix the entry by hand (with several
                             map_locations, whichever of those entries
                             moved), then re-run update-skill. A
+                            citation_check outside-scope (no check ran:
+                            the brief's scope leaves the cited file out)
+                            takes no advice to exclude it, and its fix
+                            for a move is to change the brief's scope so
+                            it takes that file (its scope.include or
+                            scope.exclude) and fix the entry by hand. A
                             citation_check that read nothing (UNREAD:
                             no-source-root, verifier-missing,
                             spot-check-failed) takes its own fix in
@@ -570,7 +600,25 @@ Gap records (update-skill gap-driven.md §3, §4 and §4a):
   STRUCTURAL_FIX and metadata update entries are forwarded to merge as
   they are (`forwarded`); every other entry is export-bearing. A severity
   is blocking unless it is Medium, Low or Info (NON_BLOCKING), compared
-  case-insensitively, so a missing one is blocking. In order:
+  case-insensitively, so a missing one is blocking.
+
+  The brief's scope (--brief, the skill brief) bounds the repair (#824),
+  by skf-classify-changed-files.py's load_scope and Scope.takes, loaded
+  from this folder (Category A's in-scope test: an exclude wins over an
+  include, and an empty include takes only a path with the suffix of a
+  path the gaps or the map's entries name or of the brief's language,
+  so a file with no suffix is not taken), with Category A's
+  rule that a file the map's entries[] cite is always taken. Each path is
+  tested relative to --source-root, POSIX, its `.` and `..` parts
+  resolved (an absolute path under the root loses the root's prefix).
+  An entry's outside_scope is its cited file and each of its
+  resolved_paths the scope leaves out: none of them is checked, scanned
+  or repaired from, so a declaration of another package the skill does
+  not cover is never read for it. A map entry's own file is checked
+  wherever it sits (found and MOVED_EXPORT routing does not test it).
+  Without --brief (a skill with no brief) there is no scope test and
+  nothing is left out. A --brief that names no file or cannot be read
+  is an input error (exit 1). In order:
 
   1. Drift gate (--drift-status overridden): each export-bearing entry
      but a MOVED_EXPORT needs the tree, with the first reason that fits:
@@ -579,8 +627,11 @@ Gap records (update-skill gap-driven.md §3, §4 and §4a):
      whose map_match is not-found with no candidate that has a
      source_file "a line and a signature from the tree", any other (a
      not-found with such a candidate, a citation of another file than
-     the map's entries, among them) "a signature from the tree". Any
-     such entry: {"status":
+     the map's entries, among them) "a signature from the tree". An
+     entry the brief's scope keeps from a repair before anything is read
+     for it (step 3 records it outside-scope, or cited-elsewhere with
+     citation_check outside-scope, with no check run and nothing to
+     scan) passes. Any other such entry: {"status":
      "drift-blocked", "drift_blocked": [{gap_id, name, change_category,
      severity, reason}]}, and no spot-check runs.
   2. A DELETED_EXPORT without a `rescope` that holds its `amendment` and
@@ -589,7 +640,10 @@ Gap records (update-skill gap-driven.md §3, §4 and §4a):
      lines rules, loaded from this folder, under --source-root:
        DELETED_EXPORT         rescoped, no check
        MOVED_EXPORT           checked at its map entry when map_match is
-                              found (unknown otherwise); under the
+                              found (unknown otherwise), a bookkeeping
+                              variant its file never names against its
+                              base (the verifier's fold; no other
+                              category folds); under the
                               override a `moved` becomes unknown with
                               unknown_reason drift-override; its
                               pinned_definition_lines are the numbers of
@@ -599,7 +653,15 @@ Gap records (update-skill gap-driven.md §3, §4 and §4a):
          ambiguous            unknown, unknown_reason ambiguous (several
                               map entries of its name: no check runs)
          not-found            checked at its source_citation (no export
-                              type) when it has one. When the map holds
+                              type) when it has one, but never at a
+                              cited file its outside_scope holds: no
+                              check runs there, and it is unknown,
+                              unknown_reason cited-elsewhere with
+                              citation_check outside-scope when the map
+                              holds entries of its name with a
+                              source_file (never re-extracted), else
+                              unknown_reason outside-scope, routed on
+                              as below. When the map holds
                               entries of its name (in_map, which a
                               not-found has only for a citation of
                               another file than theirs), one of them
@@ -613,17 +675,29 @@ Gap records (update-skill gap-driven.md §3, §4 and §4a):
                               check's cause (missing, or its
                               unknown_reason) and its map_locations the
                               `file:line` (or file) of each candidate
-                              with a source_file, both null on any other
-                              record. Candidates with no source_file
-                              (placeholders) do not count. Otherwise,
-                              when that pins no line
+                              with a source_file, the map_locations null
+                              on any other record. Candidates with no
+                              source_file (placeholders) do not count.
+                              Otherwise,
+                              when its outside_scope is not empty and
+                              the scope takes none of its
+                              resolved_paths: unknown, unknown_reason
+                              outside-scope, whatever its severity, with
+                              nothing to scan (never in the plan); its
+                              citation_check keeps the cause of a check
+                              at a citation the scope takes (missing, or
+                              its unknown_reason), null with none. The
+                              citation_check is null on every record but
+                              a cited-elsewhere or outside-scope one.
+                              Otherwise, when that pins no line
                               (unknown or missing), or with no
                               citation: targeted re-extraction (§4a) for a
                               provenance_completeness entry with a source
                               root, for a blocking one whatever its
                               resolved_paths, and for a missing-export or
                               missing-type one with resolved_paths; else
-                              unknown
+                              unknown. Targeted re-extraction scans only
+                              the resolved_paths the scope takes
      A check gives `verified` (the line is a definition line, or a module
      or package entry whose file exists), `moved` (one definition line,
      not the recorded one: new_location), `missing` (no such file) or
@@ -646,19 +720,24 @@ Gap records (update-skill gap-driven.md §3, §4 and §4a):
      candidate that has a source_file) never goes to targeted
      re-extraction, whatever its severity: one that ends missing or
      unknown keeps its map entries unchanged and adds none, and apply
-     warns (see "Apply").
+     warns (see "Apply"). One recorded unknown, outside-scope (its record's
+     outside_scope lists the files the scope leaves out) adds no entry
+     either, a placeholder included, whatever its severity, and apply
+     warns.
      A NEW_EXPORT or MODIFIED_EXPORT a check gives verified or moved, at
      its map entry or at a citation the map holds no entry of its name
      for, is located: its signature_at is the checked file and the
      recorded line (verified) or the new one (moved). One whose citation
      names another file than the map's entries of its name is not (apply
      warns, as before), nor one whose file is absolute or outside
-     --source-root, links resolved, nor a NEW_EXPORT --judgments answers
-     internal-unreachable (one not yet answered is located, so its scan
-     may go unused).
+     --source-root, links resolved (a cited file the brief's scope leaves
+     out is never checked, so never located), nor a NEW_EXPORT
+     --judgments answers internal-unreachable (one not yet answered is
+     located, so its scan may go unused).
   --plan stops here: {"status": "planned", "reextract": {"entries":
-  [{gap_id, name, severity, resolved_paths}], "files": [the union of
-  their resolved_paths, then of the located exports' files],
+  [{gap_id, name, severity, resolved_paths (those the scope takes)}],
+  "files": [the union of their resolved_paths, then of the located
+  exports' files],
   "signatures": [{gap_id, name, file, line} of each located export]},
   "warnings"}, the files also written to --files-out as a JSON array.
   4. Targeted re-extraction (--remediation-records, `records`' output
@@ -677,7 +756,10 @@ Gap records (update-skill gap-driven.md §3, §4 and §4a):
      a renamed re-export by its public name matches no record.
      An entry with no match, or no path to scan, is unresolved, except a
      missing-export or missing-type one that is not blocking, which is
-     unknown. Any unresolved entry: {"status": "unresolved",
+     unknown. An entry with no match whose outside_scope is not empty is
+     unknown, unknown_reason outside-scope (a file the scope leaves out
+     may define it), whatever its severity and category, never
+     unresolved. Any unresolved entry: {"status": "unresolved",
      "unresolved": [{gap_id, name, severity, remediation_paths,
      rejected_paths, files_scanned, exports_found_in_scan}]}.
      Each located export takes the one record of its name (or of its map
@@ -713,8 +795,10 @@ Gap records (update-skill gap-driven.md §3, §4 and §4a):
   [one record per export-bearing entry: gap_id, export_name,
   gap_category, severity, verification, in_map, map_entry,
   provenance_citation, source_citation, new_location, unknown_reason,
-  citation_check, map_locations, pinned_definition_lines,
-  resolution_source, reachability, and
+  citation_check, map_locations, outside_scope (the files a gap cites or
+  its Remediation names that the brief's scope leaves out, whatever the
+  record's outcome; null when it leaves out none, or with no --brief),
+  pinned_definition_lines, resolution_source, reachability, and
   export_type, params, return_type, extraction_method and ast_node_type
   (a located export's record's, step 4; else null, and apply takes the
   signature of an entry it adds from merge.md's merge-records.json)],
@@ -773,6 +857,7 @@ import hashlib
 import importlib.util
 import json
 import os
+import posixpath
 import re
 import subprocess
 import sys
@@ -1999,17 +2084,22 @@ def _apply_gap_driven(pmap: _Map, records: dict, merge_records: dict | None, dri
             and reason in UNKNOWN_REASONS else ""
 
     def unchecked(r: dict) -> str | None:
-        """The warning for a blocking NEW_EXPORT or MODIFIED_EXPORT the map holds that its spot-check could not
-        locate (missing, or unknown for a cause its unknown_reason names), which stays unchanged: the gap, the
+        """The warning for an export the map holds that its spot-check could not locate, which stays unchanged: a
+        blocking NEW_EXPORT or MODIFIED_EXPORT (missing, or unknown for a cause its unknown_reason names), or a
+        MOVED_EXPORT whose map entry's file is gone (missing, rule R5), whatever its severity. It gives the gap, the
         export, the outcome, its cause and the one fix a re-run acts on; None for any other record."""
-        outcome = r.get("verification")
-        if outcome not in ("missing", "unknown") or not in_map(r) or not _blocking(r.get("severity")) \
-                or r.get("gap_category") not in ("NEW_EXPORT", "MODIFIED_EXPORT"):
+        outcome, category = r.get("verification"), r.get("gap_category")
+        gone = outcome == "missing" and category == "MOVED_EXPORT"  # R5 cannot point an entry at another file
+        if not in_map(r) or not gone and (
+                outcome not in ("missing", "unknown") or not _blocking(r.get("severity"))
+                or category not in ("NEW_EXPORT", "MODIFIED_EXPORT")):
             return None
         name, gap = _name_of(r), r.get("gap_id")
         path = _location(r.get("map_entry"))[0]
         cause = f"its map entry's file{f' {path}' if path else ''} is gone" if outcome == "missing" else why(r)
-        detail = "; ".join(part for part in (cause, note) if part)
+        lines = r.get("pinned_definition_lines") if gone else None
+        detail = "; ".join(part for part in (
+            cause, note, f"definition lines per the test report: {lines}" if lines else "") if part)
         if r.get("unknown_reason") == "ambiguous":  # a Source at the definition lets the re-run's lookup pick one
             fix = ("its entries are left unchanged. Fix its entries by hand, or give the gap a `file:line` Source at "
                    "its definition when that file holds only one of them, then re-run update-skill")
@@ -2028,7 +2118,8 @@ def _apply_gap_driven(pmap: _Map, records: dict, merge_records: dict | None, dri
         cited_file, cited_line = _location(r.get("source_citation"))
         cited = _where(cited_file, cited_line) or cited_file
         check = r.get("citation_check") if isinstance(r.get("citation_check"), str) else None
-        words = "no such file" if check == "missing" else UNKNOWN_REASONS.get(check or "")
+        words = "no such file" if check == "missing" else OUTSIDE_SCOPE_CHECK if check == "outside-scope" \
+            else UNKNOWN_REASONS.get(check or "")
         where = [w for w in r.get("map_locations") or [] if isinstance(w, str) and w]
         detail = "; ".join(part for part in (
             why(r), f"it cites {cited}" if cited else "",
@@ -2040,16 +2131,49 @@ def _apply_gap_driven(pmap: _Map, records: dict, merge_records: dict | None, dri
             "re-extracted for it."
         if check in UNREAD:  # nothing was read at the cited file: make the check read it first
             return f"{head} Nothing was read at the cited file: {UNREAD[check]}, then re-run update-skill"
-        moved = "when an export moved, fix by hand whichever of those entries moved" if several \
-            else "when the export moved, fix the map entry by hand"
-        scope = "" if check == "missing" else (", and if the gap comes back, exclude the cited file in the brief's "
-                                               "scope when the skill does not cover it")
+        if check == "outside-scope":  # the scope already leaves the cited file out: only a move there brings it in
+            moved = f"when an export moved there, {TAKE_FILE} and fix by hand whichever of those entries moved" \
+                if several else f"when the export moved there, {TAKE_FILE} and fix the map entry by hand"
+        else:
+            moved = "when an export moved, fix by hand whichever of those entries moved" if several \
+                else "when the export moved, fix the map entry by hand"
+        scope = "" if check in ("missing", "outside-scope") else (
+            ", and if the gap comes back, exclude the cited file in the brief's scope when the skill does not cover it")
         return (f"{head} When the map is right, re-run Test Skill, since the test compared another file's "
                 f"declaration{scope}; {moved} (set its source_file and source_line to the line that defines it), "
                 f"then re-run update-skill")
 
+    def scoped_out(r: dict) -> bool:
+        """True for an `unknown` record whose gap the brief's scope keeps from a repair (outside-scope)."""
+        return r.get("verification") == "unknown" and r.get("unknown_reason") == "outside-scope"
+
+    def outside(r: dict) -> str | None:
+        """The warning for a NEW_EXPORT or MODIFIED_EXPORT recorded unknown, outside-scope, whatever its severity: the
+        gap, the export, the files the brief's scope leaves out and the fix for each case; None for any other
+        record."""
+        if not scoped_out(r):
+            return None
+        name, gap = _name_of(r), r.get("gap_id")
+        left = [p for p in r.get("outside_scope") or [] if isinstance(p, str) and p]
+        # the cause of a check at an in-scope citation that pinned no line (its file the scope takes)
+        check = r.get("citation_check") if isinstance(r.get("citation_check"), str) else None
+        words = "no such file" if check == "missing" else UNKNOWN_REASONS.get(check or "")
+        cited = _where(*_location(r.get("source_citation"))) or _location(r.get("source_citation"))[0]
+        checked = f"its check there: {check}{f' ({words})' if words else ''}" if check else ""
+        detail = "; ".join(part for part in (
+            why(r), f"left out: {', '.join(left)}" if left else "", f"it cites {cited}" if check and cited else "",
+            checked, note) if part)
+        head = f"provenance: {name}{f' ({gap})' if gap else ''}: unknown ({detail}); nothing is added or re-extracted " \
+            "for it."
+        if check in UNREAD:  # nothing was read at the cited file the scope takes: make the check read it first
+            return f"{head} Nothing was read at the cited file: {UNREAD[check]}, then re-run update-skill"
+        covers = "When the skill covers one of those files, change the brief's scope so it takes it" if len(left) > 1 \
+            else "When the skill covers that file, change the brief's scope so it takes it"
+        return (f"{head} {covers} (its scope.include or scope.exclude), then re-run update-skill; otherwise re-run "
+                "Test Skill, since the test compared a declaration the skill does not cover")
+
     blocking = [{"export_name": _name_of(r), "severity": r.get("severity")} for r in verification
-                if r.get("verification") == "unknown" and not in_map(r)
+                if r.get("verification") == "unknown" and not in_map(r) and not scoped_out(r)
                 and r.get("gap_category") in ("NEW_EXPORT", "MODIFIED_EXPORT") and _blocking(r.get("severity"))]
     if blocking:
         return blocking
@@ -2059,7 +2183,8 @@ def _apply_gap_driven(pmap: _Map, records: dict, merge_records: dict | None, dri
         entry_file, entry_line = _location(r.get("map_entry"))
         index = pmap.find(name, entry_file, entry_line, reexport=True) if r.get("map_entry") else None
         lines = r.get("pinned_definition_lines")
-        r5 = f"; definition lines per the test report: {lines}" if category == "MOVED_EXPORT" else ""
+        # rule R5's lines, only when the test report listed any (a citation that did not resolve lists none)
+        r5 = f"; definition lines per the test report: {lines}" if category == "MOVED_EXPORT" and lines else ""
         if outcome == "rescoped":
             if index is not None:
                 pmap.remove([index])
@@ -2101,14 +2226,15 @@ def _apply_gap_driven(pmap: _Map, records: dict, merge_records: dict | None, dri
                 "export_name": name, **signature(r)[0],
                 "source_file": path, "source_line": line, **_labels("source-read", None)},
                 keep=("ast_node_type",)), pmap.library_for(path, name)))
-        elif outcome == "unknown" and not in_map(r) and category in ("NEW_EXPORT", "MODIFIED_EXPORT"):
+        elif outcome == "unknown" and not in_map(r) and category in ("NEW_EXPORT", "MODIFIED_EXPORT") \
+                and not scoped_out(r):  # an outside-scope one takes no placeholder: it may be another package's
             pmap.add(_new_entry(_without_none({
                 "export_name": name, **signature(r)[0],
                 **_labels("source-read", None)}, keep=("ast_node_type",)), pmap.library_for(None, name)))
         else:
             if r.get("unknown_reason") == "drift-override":
                 warnings.append(f"provenance: {name}: unknown ({note}; no line taken from HEAD{r5})")
-            elif (warning := elsewhere(r) or unchecked(r)) is not None:
+            elif (warning := elsewhere(r) or outside(r) or unchecked(r)) is not None:
                 warnings.append(warning)
             elif drift:
                 warnings.append(f"provenance: {name}: {outcome} ({why(r) + '; ' if why(r) else ''}{note}{r5})")
@@ -2765,7 +2891,13 @@ UNKNOWN_REASONS = {
     "no-source-root": "no source tree to check",
     "drift-override": "the drift override kept its line from being moved",
     "cited-elsewhere": "the gap cites another file than the provenance map's entries of its name",
+    "outside-scope": "the brief's scope leaves out a file the gap cites or its Remediation names, so the export is "
+                     "not read there",
 }
+# A cited-elsewhere entry's citation_check when the brief's scope leaves the cited file out, so no check ran there.
+OUTSIDE_SCOPE_CHECK = "not run: the brief's scope leaves it out"
+# The fix for a file the brief's scope leaves out that the skill covers: an include may miss it, or an exclude take it.
+TAKE_FILE = "change the brief's scope so it takes that file (its scope.include or scope.exclude)"
 # A cited-elsewhere entry's citation_check that read nothing at the cited file, with the fix that lets a re-run read it.
 UNREAD = {
     "no-source-root": "give update-skill the source tree",
@@ -2795,6 +2927,95 @@ def _verifier():
     return _VERIFIER or None
 
 
+CLASSIFIER_FILE = "skf-classify-changed-files.py"  # load_scope: the brief's scope (--brief)
+
+
+def _brief_scope(path: Path, cited: set[str] | frozenset = frozenset()):
+    """The skill brief's scope by skf-classify-changed-files.py's load_scope, loaded from this folder: its
+    takes(path) is Category A's in-scope test (an exclude wins over an include; an empty include takes a path only
+    when its suffix is the suffix of a `cited` path, the files the gaps and the map's entries name, or of the brief's
+    language, so a file with no suffix is never taken, and an exclude still leaves a path out).
+    Raises ValueError, on one line, for a brief that names no file or cannot be read, and for a scope test that
+    cannot be loaded."""
+    try:
+        spec = importlib.util.spec_from_file_location(
+            "skf_classify_changed_files_for_gap_records", Path(__file__).resolve().parent / CLASSIFIER_FILE)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"{CLASSIFIER_FILE} not found")
+        classifier = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(classifier)
+    except Exception as exc:  # noqa: BLE001 - a classifier (or the resolver it loads) missing or failing
+        raise ValueError(f"cannot load the brief's scope test, {CLASSIFIER_FILE} beside "
+                         f"{Path(__file__).name}: {exc}; re-install SKF") from exc
+    try:
+        return classifier.load_scope(path, cited)
+    except ValueError as exc:  # a brief it cannot find or read (a YAML error spans several lines)
+        raise ValueError(re.sub(r"\s*[\r\n]\s*", " ", str(exc).strip())) from exc
+    except Exception as exc:  # noqa: BLE001 - an out-of-date classifier, or a resolver beside it that fails
+        raise ValueError(f"cannot load the brief's scope test, {CLASSIFIER_FILE} beside "
+                         f"{Path(__file__).name}: {exc}; re-install SKF") from exc
+
+
+def _takes(scope, path: str) -> bool:
+    """True when the brief's scope takes `path`. Raises ValueError when its test fails (the resolver it calls cannot
+    be loaded or is out of date)."""
+    try:
+        return bool(scope.takes(path))
+    except Exception as exc:  # noqa: BLE001 - whatever the scope test raises, the run reports it on one line
+        raise ValueError(f"the brief's scope test failed on {path}: {exc}; re-install SKF") from exc
+
+
+def _scope_rel(path: object, root: Path | None) -> str | None:
+    """`path` as the scope test reads it: POSIX, relative to the source root (an absolute path under it loses the
+    root's prefix), its `.` and `..` parts resolved lexically (posixpath.normpath); None for no path."""
+    text = _norm_path(path)
+    if text is None:
+        return None
+    if root is not None:
+        bases = [root.as_posix()]
+        try:
+            bases.append(root.resolve().as_posix())
+        except OSError:
+            pass
+        for base in dict.fromkeys(b.rstrip("/") for b in bases if b.rstrip("/")):
+            if text.startswith(base + "/"):
+                text = text[len(base) + 1:]
+                break
+    return posixpath.normpath(text)
+
+
+def _scope_test(scope, provenance: dict | None, root: Path | None):
+    """The test gap-records applies to each file a gap cites or its Remediation names: True for a file the
+    provenance map's entries[] cite (Category A takes each file the map tracks whatever the scope says) and for one
+    the brief's scope takes, each path read by _scope_rel."""
+    tracked = {_scope_rel(_file_of(e), root) for e in _entries_of(provenance)} - {None}
+
+    def takes(path: str) -> bool:
+        rel = _scope_rel(path, root)
+        return rel is not None and (rel in tracked or _takes(scope, rel))
+
+    return takes
+
+
+def _map_paths(provenance: object) -> set[str]:
+    """The files the provenance map's entries[] cite (load_scope's `cited`, with the gaps' paths)."""
+    return {p for p in (_file_of(e) for e in _entries_of(provenance)) if p}
+
+
+def _gap_paths(manifest: object) -> set[str]:
+    """Every file a manifest's entries name: each citation's file and resolved path (load_scope's `cited`)."""
+    entries = manifest.get("entries") if isinstance(manifest, dict) else None
+    paths = set()
+    for entry in entries if isinstance(entries, list) else []:
+        if not isinstance(entry, dict):
+            continue
+        citation = entry.get("source_citation") if isinstance(entry.get("source_citation"), dict) else {}
+        for path in [citation.get("file"), *(entry.get("resolved_paths") or [])]:
+            if _norm_path(path):
+                paths.add(_norm_path(path))
+    return paths
+
+
 def _blocking(severity: object) -> bool:
     return str(severity or "").strip().lower() not in NON_BLOCKING
 
@@ -2832,9 +3053,11 @@ def _drift_reason(entry: dict) -> str | None:
 
 
 def _spot_check(root: Path | None, path: str | None, name: str, line: int | None, export_type: object,
-                answers: dict) -> tuple[str, int | None, bool, str | None, str | None]:
+                answers: dict, fold: bool = False) -> tuple[str, int | None, bool, str | None, str | None]:
     """(outcome, the line a `moved` export moves to, whether it waits on a `declaring_line` answer, why the
-    check failed, why it is `unknown`: an UNKNOWN_REASONS key)."""
+    check failed, why it is `unknown`: an UNKNOWN_REASONS key). `fold` (rule R5's MOVED_EXPORT only) checks a
+    bookkeeping variant its file never names against its base; any other gap judges the name as written, so a
+    fabricated variant is never located at its base's line."""
     if root is None:
         return "unknown", None, False, None, "no-source-root"
     verifier = _verifier()
@@ -2844,7 +3067,7 @@ def _spot_check(root: Path | None, path: str | None, name: str, line: int | None
         return "unknown", None, False, None, "no-line"
     try:
         report = verifier.definition_lines_report(path, name, root, line,
-                                                  export_type if isinstance(export_type, str) else None)
+                                                  export_type if isinstance(export_type, str) else None, fold)
     except Exception as exc:  # noqa: BLE001 - a file it cannot read, or any verifier failure: this entry only
         return "unknown", None, False, f"{type(exc).__name__}: {exc}", "spot-check-failed"
     check = report.get("line_check")
@@ -2894,7 +3117,7 @@ def _where(path: object, line: object) -> str | None:
 class _GapEntry:
     """One export-bearing manifest entry as gap-records routes it."""
 
-    def __init__(self, entry: dict, answers: dict):
+    def __init__(self, entry: dict, answers: dict, takes=None):
         self.entry = entry
         self.answers = answers
         self.name = _name_of(entry) or ""
@@ -2912,9 +3135,17 @@ class _GapEntry:
         self.map_locations = list(dict.fromkeys(
             _where(c.get("source_file"), c.get("source_line")) or _norm_path(c.get("source_file"))
             for c in match.get("candidates") or [] if isinstance(c, dict) and _norm_path(c.get("source_file"))))
-        self.citation_check: str | None = None  # a cited-elsewhere entry's citation check: missing, or its reason
+        # a cited-elsewhere or outside-scope entry's citation check: missing, its reason, or outside-scope
+        self.citation_check: str | None = None
+        self.cited_cause: str | None = None  # why a check at an in-scope citation pinned no line: missing, its reason
         citation = entry.get("source_citation")
         self.citation = citation if isinstance(citation, dict) else None
+        self.cited_file = _norm_path(self.citation.get("file")) if self.citation else None
+        # the cited file and each resolved path the brief's scope leaves out (#824): none is checked, scanned or
+        # repaired from; with no brief there is no scope test (`takes` None), and nothing is left out
+        self.outside_scope: list[str] = [] if takes is None else list(dict.fromkeys(
+            p for p in (self.cited_file, *(_norm_path(p) for p in entry.get("resolved_paths") or []))
+            if p and not takes(p)))
         self.recorded: tuple[str | None, int | None] = (None, None)  # the file and line a check read
         self.outcome: str | None = None
         self.new_line: int | None = None
@@ -2930,14 +3161,31 @@ class _GapEntry:
     def blocking(self) -> bool:
         return _blocking(self.entry.get("severity"))
 
+    @property
+    def scoped_out(self) -> bool:
+        """True for an entry route() records outside-scope (or cited-elsewhere with citation_check outside-scope)
+        before anything is read for it: no in-scope citation to check and no in-scope file to scan. The drift gate
+        passes it, since nothing it writes comes from the tree."""
+        if self.category not in ("NEW_EXPORT", "MODIFIED_EXPORT") or self.match_status != "not-found":
+            return False
+        cited_out = self.cited_file is not None and self.cited_file in self.outside_scope
+        if self.citation and not cited_out:  # an in-scope citation is checked
+            return False
+        if self.map_locations:  # with the cited file left out: cited-elsewhere, never checked; with none, as before
+            return cited_out
+        return bool(self.outside_scope) and not self.paths
+
     @property
     def paths(self) -> list[str]:
-        return [p for p in (_norm_path(p) for p in self.entry.get("resolved_paths") or []) if p]
+        """The resolved paths targeted re-extraction scans: each one the brief's scope takes."""
+        return [p for p in (_norm_path(p) for p in self.entry.get("resolved_paths") or [])
+                if p and p not in self.outside_scope]
 
     def check(self, root: Path | None, path: object, line: object, export_type: object) -> None:
         self.recorded = (_norm_path(path), _line_of(line))
         self.outcome, self.new_line, self.waits, self.failure, self.unknown_reason = _spot_check(
-            root, self.recorded[0], self.declared, self.recorded[1], export_type, self.answers)
+            root, self.recorded[0], self.declared, self.recorded[1], export_type, self.answers,
+            self.category == "MOVED_EXPORT")
 
     def locate(self, root: Path | None) -> None:
         """Record where a check located the export (the checked file, at the recorded line or the one it moved
@@ -2978,18 +3226,31 @@ class _GapEntry:
         if self.match_status == "ambiguous":  # several map entries of its name: no check, apply warns
             self.outcome, self.unknown_reason = "unknown", "ambiguous"
             return
-        if self.citation:
+        if self.citation and self.cited_file is not None and self.cited_file in self.outside_scope:
+            # the brief's scope leaves the cited file out: the skill does not cover its declaration, so no check runs
+            # there (#824); the fallbacks below scan only the files the scope takes
+            if self.map_locations:  # the map holds its name at other files: cited elsewhere, and never checked
+                self.outcome, self.unknown_reason, self.citation_check = "unknown", "cited-elsewhere", "outside-scope"
+                return
+            self.outcome, self.unknown_reason = "unknown", "outside-scope"
+        elif self.citation:
             self.check(root, self.citation.get("file"), self.citation.get("line"), None)
             if self.waits or self.outcome in ("verified", "moved"):
                 if not self.in_map:  # a citation of another file than the map's entries of its name takes none
                     self.locate(root)
                 return
+            self.cited_cause = "missing" if self.outcome == "missing" else self.unknown_reason
         if self.match_status == "not-found" and self.map_locations:
             # the map holds its name at other files: the cited file's declaration may be another package's, so it is
             # never re-extracted there (#824); the record keeps the check's cause, and apply warns with what to fix
             self.citation_check = "missing" if self.outcome == "missing" else self.unknown_reason
             self.outcome, self.unknown_reason = "unknown", "cited-elsewhere"
             return
+        if self.outside_scope and not self.paths:
+            # no file the brief's scope takes is left to scan: never in the plan (#824); the record keeps the cause of
+            # a check at an in-scope citation, which apply's warning names
+            self.outcome, self.unknown_reason, self.citation_check = "unknown", "outside-scope", self.cited_cause
+            return
         if self.entry.get("provenance_completeness") and root is not None:
             self.reextract = True
         elif self.blocking:
@@ -3050,6 +3311,7 @@ class _GapEntry:
         signed = self.signature() or {}
         recorded = _where(*self.recorded)
         elsewhere = self.outcome == "unknown" and self.unknown_reason == "cited-elsewhere"
+        outside = self.outcome == "unknown" and self.unknown_reason == "outside-scope"
         if self.outcome == "re-extracted":
             citation = self.new_location()
         elif self.outcome in ("verified", "moved", "missing", "rescoped") and recorded:
@@ -3067,8 +3329,9 @@ class _GapEntry:
             "source_citation": self.citation,
             "new_location": self.new_location(),
             "unknown_reason": self.unknown_reason if self.outcome == "unknown" else None,
-            "citation_check": self.citation_check if elsewhere else None,
+            "citation_check": self.citation_check if elsewhere or outside else None,
             "map_locations": self.map_locations if elsewhere else None,
+            "outside_scope": self.outside_scope or None,  # whatever the outcome: each file the scope left out
             "pinned_definition_lines": _pinned_lines(self.entry.get("remediation"))
             if self.category == "MOVED_EXPORT" else None,
             "resolution_source": "remediation-paths" if self.outcome == "re-extracted" else None,
@@ -3106,8 +3369,9 @@ class _GapEntry:
 
 def gap_records(manifest: dict, provenance: dict | None, *, source_root: Path | None, drift_status: str = "ok",
                 judgments: dict | None = None, remediation: dict | None = None, plan: bool = False,
-                tier: str | None = None) -> tuple[dict | None, dict]:
-    """(reextract-records.json or None, the summary): see "Gap records" in the module docstring."""
+                tier: str | None = None, scope=None) -> tuple[dict | None, dict]:
+    """(reextract-records.json or None, the summary): see "Gap records" in the module docstring. `scope` is the
+    brief's (_brief_scope), or None for a skill with no brief."""
     if not isinstance(manifest, dict) or not isinstance(manifest.get("entries"), list):
         raise ValueError("the change manifest has no `entries` array: is it translate's output?")
     entries = [e for e in manifest["entries"] if isinstance(e, dict)]
@@ -3115,13 +3379,14 @@ def gap_records(manifest: dict, provenance: dict | None, *, source_root: Path |
     root = source_root if source_root is not None and source_root.is_dir() else None
     forwarded = [{"gap_id": e.get("gap_id"), "change_category": e.get("change_category")}
                  for e in entries if e.get("change_category") not in EXPORT_CATEGORIES]
-    routed = [_GapEntry(e, judgments.get(e.get("gap_id")) or {}) for e in entries
+    takes = None if scope is None else _scope_test(scope, provenance, source_root)
+    routed = [_GapEntry(e, judgments.get(e.get("gap_id")) or {}, takes) for e in entries
               if e.get("change_category") in EXPORT_CATEGORIES]
     drift = drift_status == "overridden"
     if drift:
         blocked = [{"gap_id": g.entry.get("gap_id"), "name": g.name, "change_category": g.category,
                     "severity": g.entry.get("severity"), "reason": _drift_reason(g.entry)}
-                   for g in routed if _drift_reason(g.entry)]
+                   for g in routed if _drift_reason(g.entry) and not g.scoped_out]  # nothing is read for it
         if blocked:
             return None, {"status": "drift-blocked", "drift_blocked": blocked}
     bare = [g.name for g in routed if g.category == "DELETED_EXPORT" and not (
@@ -3168,6 +3433,9 @@ def gap_records(manifest: dict, provenance: dict | None, *, source_root: Path |
         files_scanned, found = g.match(blocks)
         if g.record is not None:
             continue
+        if g.outside_scope:  # none of the files the scope takes holds it, and a file it leaves out may (#824)
+            g.outcome, g.unknown_reason, g.citation_check = "unknown", "outside-scope", g.cited_cause
+            continue
         if not g.blocking and g.entry.get("category") in DOCUMENT_CATEGORIES:
             g.outcome = "unknown"
             continue
@@ -3572,15 +3840,22 @@ def _cmd_gap_records(args: argparse.Namespace) -> int:
             raise ValueError("--evidence and --tier go together")
         judgments = _gap_judgments(_load_json_file(Path(args.judgments), "--judgments file")) \
             if args.judgments else {}
+        manifest = _load_json_file(Path(args.manifest), "--manifest file")
+        provenance = _load_json_file(Path(args.provenance_map), "--provenance-map file")
+        if args.brief is not None and not args.brief.strip():
+            raise ValueError("--brief is empty (an unbound brief path?): pass the skill brief, or leave --brief out")
+        scope = _brief_scope(Path(args.brief), _gap_paths(manifest) | _map_paths(provenance)) \
+            if args.brief is not None else None
         records, summary = gap_records(
-            _load_json_file(Path(args.manifest), "--manifest file"),
-            _load_json_file(Path(args.provenance_map), "--provenance-map file"),
+            manifest,
+            provenance,
             source_root=Path(args.source_root) if args.source_root else None,
             drift_status=args.drift_status,
             judgments=judgments,
             remediation=_optional_json(args.remediation_records, "--remediation-records file"),
             plan=args.plan,
             tier=args.tier,
+            scope=scope,
         )
         if summary["status"] == "planned" and args.files_out:
             _write_json_atomic(Path(args.files_out), summary["reextract"]["files"])
@@ -3803,6 +4078,9 @@ def _build_parser() -> argparse.ArgumentParser:
     p_gap.add_argument("--manifest", required=True, metavar="FILE", help="skf-parse-gaps.py translate's manifest")
     p_gap.add_argument("--provenance-map", required=True, metavar="FILE", help="the map the repair starts from")
     p_gap.add_argument("--source-root", metavar="DIR", help="the source tree the spot-checks read")
+    p_gap.add_argument("--brief", metavar="FILE",
+                       help="the skill brief (skill-brief.yaml): no file a gap cites or its Remediation names that its "
+                            "scope leaves out is checked, scanned or repaired from; without it there is no scope test")
     p_gap.add_argument("--drift-status", choices=DRIFT_STATUSES, default="ok",
                        help="the workspace drift check's status; overridden runs the drift gate")
     p_gap.add_argument("--judgments", metavar="FILE", help="the answers to its needs_judgment[], keyed by gap id")