bmad-module-skill-forge 3.0.0 → 4.0.0

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

@@ -5,10 +5,12 @@
 # ///
 """SKF test-skill coverage inputs: the counts, name sets and candidates coverage-check reads.
 
-coverage-check.md decides which denominator clause applies to a skill and
-whether a bookkeeping variant is a real export; everything it counts, folds
-or unions on the way runs here, so no count is made by hand. Three
-subcommands, each reading files and writing one JSON object:
+coverage-check.md decides whether a bookkeeping variant is a real export,
+and makes the judgments the denominator clause needs where no file holds
+them (--pattern-reference-intent, and --curated-subset and --barrel where
+the extraction does not say); the clause, everything it counts, folds or
+unions on the way runs here, so no count is made by hand. Three subcommands, each
+reading files and writing one JSON object:
 
   census    docs-only detection. Counts the citations SKILL.md and each .md
             file directly in references/ write, by form: `[EXT:` against
@@ -22,7 +24,10 @@ subcommands, each reading files and writing one JSON object:
             `confidence_distribution`) under the keys
             check-metadata-coherence.py reads; the provenance named exports
             (`::` impl-block methods left out); the inflation signature
-            (`stats.exports_documented` equals `stats.effective_denominator`)
+            (`stats.exports_documented` equals `stats.effective_denominator`,
+            or, for a map with a named entry and no `::` entry, its distinct
+            entry names do: the stored count counts each name once, the map
+            holds a name passed on from two files twice)
             with the declared names verify-declared-numerator.py looks up
             (the `exports[]` names, else the provenance named exports); and,
             for a stack, its composition surface: the distinct provenance
@@ -34,17 +39,55 @@ subcommands, each reading files and writing one JSON object:
   surface   the enumerated source surface, from every input given (their
             union):
               --extraction  skf-extract-public-api.py --mode full output:
-                            the names in entry_point_diff.public, less the
-                            outside_scope names (defined in a file the brief
-                            scopes out); exports[] only gives each name's
+                            the names in entry_point_diff.public, a
+                            namespace with a `members` list given as its
+                            members (the names its module passes on, each
+                            at its file, once with a public name of the
+                            same name and file), less the outside_scope
+                            names (defined in a file the brief scopes
+                            out); exports[] only gives each name's
                             kind, line and signature line, looked up by the
                             name its defining file gives it (an aliased
                             re-export's `local`) and that file.
-                            extraction_gaps are listed to read by eye.
-              --quick       skf-extract-public-api.py --mode quick output
+                            extraction_gaps are listed to read by eye, and
+                            the runner's warnings join `warnings`. A Python
+                            top __init__.py inside the folder of another top
+                            that exports a public name (a sub-package
+                            behind a folder with no __init__.py) is no
+                            barrel, unless scope.include or tier_a_include
+                            lists its file: its names leave `all`, `root`
+                            and the umbrella ratio and are listed in
+                            `excluded.nestedEntries`, but keep their records
+                            (so the scope.include and tier_a_include sets)
+                            and their outside_scope and extraction_gaps
+                            rows. When the runner lists an
+                            include glob that matches no file
+                            (scope.unmatched_include: a brief older than the
+                            source), each outside_scope name a root entry
+                            point exports is restored, with the file and
+                            line of its outside_scope row, when no include,
+                            exclude or declined scope-expansion amendment
+                            (latest action skipped or demoted-include, from
+                            --brief) matches its file. A tier_a_include glob
+                            the runner lists as matching no file
+                            (scope.unmatched_tier_a_include, [] when the key
+                            is absent) counts no name. An extraction the
+                            per-file scan replaces (extraction.fallback.needed)
+                            gives no name and no set: only its scope, its
+                            stale globs and its `extraction` object, so the
+                            fallback scan passes it beside its results.
+              --quick       skf-extract-public-api.py --mode quick output,
+                            each name at its defined_in (the file that
+                            defines it), else at its source_file
               --per-file    a subagent's per-file result (exports_found and
                             types_found), schema-checked as
                             score-signatures.py checks it
+              --fallback-scan
+                            the --per-file results are the fallback
+                            per-file scan's, each at the file that defines
+                            its names (a Quick-tier or State 4 result is at
+                            its entry file): as with an extraction, no
+                            tier_a_include set is no tier A list
               --name        a name read by eye whose file is not known
               --provenance  the provenance entries' named exports (State 2)
               --metadata    the metadata.json exports[] names (States 2, 3)
@@ -58,34 +101,111 @@ subcommands, each reading files and writing one JSON object:
             names to their base name (`X_def`, `X_exact`, `a11y_X`, and
             `<prefix>X` for each --fold-prefix when `X` is itself a name)
             unless --keep names the variant as a real export, and
-            `canonical` gives the provenance map's fold summary. --brief
-            gives the skill brief's scope and language; an extraction's
-            recorded scope wins over it.
-
-Name sets (surface `sets`, each sorted): `all` (the union above);
+            `canonical` gives the provenance map's fold summary; a map
+            whose distinct named exports number
+            `stats.effective_denominator` (--metadata) is already canonical
+            and is not folded (`canonical.skipped`), and `residual` is the
+            canonical count less that stored count. --brief gives the
+            skill brief's scope, scope type, language and scope-expansion
+            amendments; an extraction's recorded scope wins over its scope.
+
+Name sets (surface `sets`, each sorted): `all` (the union above, less a
+nested Python top's names);
 `scope.include` and `tier_a_include` when the scope has those globs and a
 record names a file: the names whose file (an extraction's definition file,
-the quick output's source_file, a per-file result's file, a provenance
-entry's source_file) matches a glob of the list and no scope.exclude glob,
-so a name with no file is in `all` only; and, from an extraction only,
-`subpaths` (the names a non-root `exports` map subpath without `*` reaches)
-and `root` (the names the root entry points reach). reconcile-coverage.py
-and score-signatures.py --surface-set pick one.
+the quick output's defined_in, else its source_file, a per-file result's
+file, a provenance entry's source_file) matches a glob of the list and no
+scope.exclude glob,
+and for `tier_a_include` a scope.include glob too when the scope has one,
+so a name with no file is in `all` only and a restored name is in no
+tier_a_include set (a tier_a_include glob an extraction lists as matching
+no file is left out of the list, and so is one whose folder or file
+differs from every scope.include glob's before any `*` or `?`, such as
+`gen/**` beside `src/**`, and so is one a scope.exclude glob covers
+segment by segment, such as `src/gen/**` or `src/gen/extra.ts` beside an
+exclude of `src/gen/**`; a list that counts no name, each glob left out
+or matching only excluded files, files scope.include leaves out or files
+no record names, gives no tier_a_include set); and, from an
+extraction only, `subpaths` (the names a non-root `exports` map subpath
+without `*` reaches) and `root` (the names the root entry points reach).
+reconcile-coverage.py and score-signatures.py --surface-set pick one.
 
 Candidates and guards (with an extraction, --brief or --metadata): each
 set's count, the metadata `stats.effective_denominator` (--metadata), and
 the extractor's own effective_denominator and its basis. Both guards run
 only on a surface read from the source. The deflation guard compares the
 re-derived scope.include set (the `all` set without one) with
-`stats.effective_denominator` and fires above DEFLATION_PCT when the scope
-has no tier_a_include; the inflation guard compares the scope.include set
-with the provenance entry count (--provenance) and fires above
-INFLATION_PCT when the scope has no tier_a_include; the umbrella ratio (an
+`stats.effective_denominator` and fires above DEFLATION_PCT when there is
+no tier A list (with an extraction or --fallback-scan, no tier_a_include
+set; otherwise no tier_a_include glob left in the list, since a name read
+by eye at Quick tier or State 4, and a quick name with no defined_in,
+carries its entry file, not the file that defines it); a stored 0 is
+deflation, not a
+denominator (`pct` null), and fires under that condition when any name is
+re-derived. The inflation guard compares the scope.include set with the
+provenance entry count (--provenance) and fires above INFLATION_PCT under
+the same condition; `guards.tierAInclude` lists the scope's
+tier_a_include globs ([] when it has none) for gap-ledger.py's wording;
+the umbrella ratio (an
 extraction only) is the share of the root entry points' names that are
-re-exports, and above UMBRELLA_RATIO the barrel is an umbrella. Globs follow
+re-exports (a namespace with `members` counting as its members there
+too, each a re-export), and above UMBRELLA_RATIO the barrel is an
+umbrella; the
+stale-scope guard (an extraction with scope.include or tier_a_include only)
+fires when the runner lists an include or tier_a_include glob that matches
+no file, and lists those globs (`unmatchedInclude`,
+`unmatchedTierAInclude`) and the names restored for the include globs, each
+with its file and line (`restored`). Globs follow
 skf-extract-public-api.py: `**` spans any number of path segments, none
 included, and `*` and `?` stay inside one.
 
+Denominator (surface `denominator`): the Source API Surface Definition's
+clause (source-access-protocol.md), the branch reconcile-coverage.py takes
+and the set it and score-signatures.py --surface-set read: {clause, branch,
+surfaceSet, ladderStep, absentSet, rebuild, barrel}. The inputs: the scope
+type (the brief's, else the extraction's, else metadata.json's
+`scope_type`), metadata.json's `skill_type` and `stats.effective_denominator`,
+the extraction's `arms`, the deflation guard, and:
+  monorepo  --monorepo (the workspace layout skf-detect-workspaces.py
+            found), or the extraction's `arms.monorepo`.
+  curated   the extraction's `counts.curated_subset` (the rule Create Skill
+            stores the count by), else --curated-subset (the workflow's
+            judgment that a monorepo's scope.include lists a curated subset).
+  barrel    (`barrel`: "barrel", "empty-barrel", "no-entry-point" or null)
+            a complete extraction's `entry_points.status`; for one the
+            per-file scan replaces, "no-entry-point" when it read a file in
+            scope and found no entry point (`entry_points.files` empty), as
+            a complete run says; a quick output's (an export is a barrel,
+            none and no warning an empty one); else --barrel (`barrel`,
+            `empty` or `none`, what the workflow read); else null.
+  --pattern-reference-intent  the workflow's judgment that scope.notes
+            flags pattern-reference intent.
+The first clause that applies:
+  stack             skill_type stack: branch `stack`, no set.
+  pattern-reference not a monorepo, no non-empty barrel, a scope type other
+                    than specific-modules, component-library, docs-only and
+                    reference-app, not public-api with a multi-subpath
+                    `exports` map, and either the intent flag or no entry
+                    point at all with no such map: the tier_a_include set,
+                    else `all` with `rebuild` `provenance-fold` on a surface
+                    read from the source (build it again from the provenance
+                    map alone, folded), `all` on one that is not.
+  empty-barrel      an empty barrel: the scope.include set.
+  stratified-scope  --monorepo and --curated-subset, not full-library.
+  specific-modules  scope type specific-modules, not --monorepo.
+  multi-entry       arms.multi_subpath_exports, not --monorepo, a
+                    full-library or public-api scope.
+  standard-barrel   any other: the `all` set.
+The last three walk a ladder, `ladderStep` naming the rung taken: rung 1,
+`stats.effective_denominator` when metadata.json has one above 0 (a stored
+0 is no denominator), is the `scalar` branch, whose `surfaceSet` (the set score-signatures.py scores) is
+tier_a_include, else scope.include, else all, unless the deflation guard
+fires: then the barrel branch over scope.include. The next rungs are sets,
+each taken when the surface has it, the last taken in any case:
+tier_a_include then scope.include (stratified-scope), scope.include
+(specific-modules), tier_a_include then subpaths (multi-entry). A set the
+surface lacks is counted as `all`, and `absentSet` names it.
+
 Fallback verdict: `extraction.fallback.needed` is true when the extractor
 found no ast-grep (`no-ast-grep`), read no file in scope, read files only
 in languages it has no recipe for (`files_without_recipes` and no export),
@@ -100,9 +220,10 @@ Usage:
   uv run load-coverage-inputs.py metadata --metadata <metadata.json> \\
       [--provenance <provenance-map.json>] [--output <file>]
   uv run load-coverage-inputs.py surface [--extraction <file>] [--quick <file>]... \\
-      [--per-file <file>]... [--name <name>]... [--provenance <file>] [--metadata <file>] \\
-      [--brief <skill-brief.yaml>] [--fold] [--fold-prefix <prefix>]... [--keep <name>]... \\
-      [--output <file>]
+      [--per-file <file>]... [--fallback-scan] [--name <name>]... [--provenance <file>] \\
+      [--metadata <file>] [--brief <skill-brief.yaml>] [--fold] [--fold-prefix <prefix>]... \\
+      [--keep <name>]... [--monorepo] [--pattern-reference-intent] [--curated-subset] \\
+      [--barrel barrel|empty|none] [--output <file>]
 
 Exit codes:
   0  the result was printed (and written to --output)
@@ -119,6 +240,7 @@ import argparse
 import importlib.util
 import json
 import math
+import posixpath
 import re
 import sys
 from pathlib import Path
@@ -140,6 +262,19 @@ LOCAL_FORMS = ("AST", "SRC", "from skill")
 FOLD_SUFFIXES = ("_def", "_exact")
 FOLD_PREFIX = "a11y_"
 ROOT_SUBPATHS = (None, ".")
+# The latest action of a scope-expansion amendment that keeps its path out of scope.
+DECLINED_ACTIONS = ("skipped", "demoted-include")
+# The rungs each laddered clause tries in order, `scalar` being stats.effective_denominator.
+CLAUSE_LADDERS = {
+    "stratified-scope": ("scalar", "tier_a_include", "scope.include"),
+    "specific-modules": ("scalar", "scope.include"),
+    "multi-entry": ("scalar", "tier_a_include", "subpaths"),
+}
+# --barrel: what the workflow read of the entry points, where surface cannot tell -> the extractor's status.
+BARREL_FLAG = {"barrel": "barrel", "empty": "empty-barrel", "none": "no-entry-point"}
+# The scope types the pattern-reference clause never applies to (a reference app's brief carries its own
+# pattern-surface denominator).
+NOT_PATTERN_REFERENCE = frozenset({"specific-modules", "component-library", "docs-only", "reference-app"})
 # The languages skf-extract-public-api.py's recipes read (its LANGUAGE_FAMILIES).
 RECIPE_LANGUAGES = frozenset({"python", "rust", "go", "golang", "typescript", "ts", "tsx", "javascript", "js",
                               "jsx", "vue"})
@@ -158,17 +293,21 @@ class SchemaError(Exception):
 
 
 _SIBLINGS: dict[str, object] = {}
+SHARED_SCRIPTS = Path(__file__).resolve().parent.parent.parent / "shared" / "scripts"
 
 
-def _sibling(filename: str):
+def _sibling(filename: str, folder: Path | None = None):
     """A script beside this one, loaded once: validate-inventory.py (the doc
-    text) and score-signatures.py (the per-file result schema)."""
+    text) and score-signatures.py (the per-file result schema); or, with
+    `folder`, one in that folder: SHARED_SCRIPTS'
+    skf-resolve-authoritative-files.py (a skill brief's YAML)."""
     module = _SIBLINGS.get(filename)
     if module is None:
-        path = Path(__file__).resolve().parent / filename
+        path = (folder or Path(__file__).resolve().parent) / 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 InputError(f"{filename} not found beside {Path(__file__).name}")
+            where = f"in {folder}" if folder else f"beside {Path(__file__).name}"
+            raise InputError(f"{filename} not found {where}")
         module = importlib.util.module_from_spec(spec)
         spec.loader.exec_module(module)
         _SIBLINGS[filename] = module
@@ -306,7 +445,13 @@ def metadata_inputs(meta: dict, provenance: dict | None) -> dict:
         "confidenceDistribution": dist or None,
         "namedExports": {"count": len(named), "names": named} if entry_names is not None else None,
         "effectiveDenominator": effective,
-        "inflationSignature": documented is not None and effective is not None and documented == effective,
+        # The stored count counts each name once, while the map (so stats.exports_documented) holds an entry for
+        # each name and file: a name the entry points pass on from two files is two entries, one name. Only a map
+        # with no `::` entry takes that arm: the stored count holds no method, so a map with methods could match it
+        # only by chance, and its methods would stand in for an undocumented name.
+        "inflationSignature": effective is not None and (
+            documented == effective or (bool(entry_names) and not any(METHOD_SEPARATOR in n for n in entry_names)
+                                        and len(set(entry_names)) == effective)),
         "declaredNames": sorted(set(names)) if names else named,
         "stack": stack,
     }
@@ -359,13 +504,16 @@ def _scope(include, exclude, tier_a_include) -> dict:
 
 
 def read_brief(path: str) -> dict:
-    """A skill brief's scope globs and language, the fields skf-extract-public-api.py reads."""
+    """A skill brief's scope globs, scope type and language, the fields skf-extract-public-api.py reads, and the
+    latest action of each scope-expansion amendment by its path (`amendments`), a legacy headless skip
+    read as a deferral as skf-resolve-authoritative-files.py reads it."""
     try:
         import yaml  # --brief only; `uv run` installs it from the header
     except ImportError as exc:
         raise InputError("--brief is read with PyYAML: run the script with `uv run`") from exc
+    resolver = _sibling("skf-resolve-authoritative-files.py", SHARED_SCRIPTS)
     try:
-        data = yaml.safe_load(Path(path).read_bytes().decode("utf-8-sig"))
+        data = resolver.parse_brief_yaml(Path(path).read_bytes().decode("utf-8-sig"))
     except (OSError, UnicodeDecodeError) as exc:
         raise InputError(f"cannot read --brief {path}: {exc}") from exc
     except yaml.YAMLError as exc:
@@ -373,8 +521,17 @@ def read_brief(path: str) -> dict:
     if not isinstance(data, dict):
         raise InputError(f"--brief {path} is not a YAML mapping")
     scope = data.get("scope") if isinstance(data.get("scope"), dict) else {}
+    amendments: dict[str, str] = {}
+    for amend in scope.get("amendments") if isinstance(scope.get("amendments"), list) else []:
+        if isinstance(amend, dict) and amend.get("category") == "scope-expansion":
+            amended = _norm(amend["path"]) if isinstance(amend.get("path"), str) else ""
+            action = resolver._amendment_action(amend)
+            if amended and action is not None:
+                amendments[amended] = action
     return {"scope": _scope(scope.get("include"), scope.get("exclude"), scope.get("tier_a_include")),
-            "language": data.get("language") if isinstance(data.get("language"), str) else None}
+            "type": scope.get("type") if isinstance(scope.get("type"), str) else None,
+            "language": data.get("language") if isinstance(data.get("language"), str) else None,
+            "amendments": amendments}
 
 
 def matching(records: list[dict], globs: list[str], excludes: list[str]) -> list[str]:
@@ -384,37 +541,196 @@ def matching(records: list[dict], globs: list[str], excludes: list[str]) -> list
                    and not any(glob_match(_norm(r["file"]), g) for g in excludes)})
 
 
-def from_extraction(data: dict, language: str | None = None) -> dict:
-    """The public surface of an extraction, less what lies outside scope."""
+def _apart(a: str, b: str) -> bool:
+    """True when, before either has a `*` or `?`, the two globs spell a different segment at the same
+    place, so no file can match both. Any other pair counts as overlapping, even one no file can match
+    both of (`src` beside `src/index.ts`), so this never parts two that can share a file."""
+    for x, y in zip(a.split("/"), b.split("/")):
+        if any(c in x or c in y for c in "*?"):
+            return False
+        if x != y:
+            return True
+    return False
+
+
+def _inside(a: str, b: str) -> bool:
+    """True when glob `b` matches every path glob `a` can match: segment by segment each of `b`'s is
+    `**`, the same as `a`'s, or `*` beside one of `a`'s that is not `**`, and `a` has as many segments
+    as `b`, or more when `b` ends in `**`. Any other pair counts as not inside, even one where `b`
+    does cover `a` (`gen/**` in `**/gen/**`), so this never drops a glob that can count a name."""
+    xs, ys = a.split("/"), b.split("/")
+    if len(xs) < len(ys) or (len(xs) > len(ys) and ys[-1] != "**"):
+        return False
+    return all(y == "**" or x == y or (y == "*" and x != "**") for x, y in zip(xs, ys))
+
+
+def _nested_tops(entry_files: list[dict], named: set[str], exporting: set[str]) -> dict[str, str]:
+    """{top: the outermost top whose folder holds it} for each Python top
+    __init__.py inside the folder of another top that `exporting` lists (one
+    that exports at least one public name), a sub-package behind a folder
+    with no __init__.py, unless `named` lists its file. A top that exports
+    nothing (a stray __init__.py at the source root, say) nests no other."""
+    tops = sorted({e["file"] for e in entry_files
+                   if e.get("language") == "python" and isinstance(e.get("file"), str) and e["file"]})
+    nested = {}
+    for top in tops:
+        folder = posixpath.dirname(top)
+        outer = [o for o in tops if o != top and o in exporting
+                 and (not posixpath.dirname(o) or folder.startswith(posixpath.dirname(o) + "/"))]
+        if outer and _norm(top) not in named:
+            nested[top] = min(outer, key=lambda o: (o.count("/"), o))
+    return nested
+
+
+def _members_in_place(public: list[dict]) -> list[dict]:
+    """The public names, a namespace item with a `members` list (the names
+    its module passes on, `pkg.sub.name`) given as its members, each with
+    the namespace's entry and language and `via: namespace`. A member whose
+    name and file another public name, or an earlier member, has is left
+    out; a namespace whose members the runner could not read (null), or one
+    from a runner that lists none, stays itself."""
+    expanded = [p for p in public if not (p.get("via") == "namespace" and isinstance(p.get("members"), list))]
+    seen = {(p["name"], p.get("file")) for p in expanded}
+    for item in public:
+        if item.get("via") != "namespace" or not isinstance(item.get("members"), list):
+            continue
+        for member in item["members"]:
+            if not isinstance(member, dict) or not isinstance(member.get("name"), str) or not member["name"]:
+                continue
+            key = (member["name"], member.get("file"))
+            if key in seen:
+                continue
+            seen.add(key)
+            expanded.append({"name": member["name"], "language": item.get("language"), "entry": item.get("entry"),
+                             "via": "namespace", "local": member.get("local"), "file": member.get("file"),
+                             "line": member.get("line")})
+    return expanded
+
+
+def _extraction_summary(data: dict, language: str | None) -> dict:
+    """The surface's `extraction` object: the runner's status and counts,
+    the files to read by eye and the fallback verdict."""
+    counts = data.get("counts") if isinstance(data.get("counts"), dict) else {}
+    arms = data.get("arms") if isinstance(data.get("arms"), dict) else {}
+    entry_points = data.get("entry_points") if isinstance(data.get("entry_points"), dict) else {}
+    without = data.get("files_without_recipes") if isinstance(data.get("files_without_recipes"), dict) else {}
+    status = data.get("status")
+    reason = None
+    if status == "no-ast-grep":
+        reason = "no ast-grep the runner can run"
+    elif not data.get("files_in_scope"):
+        reason = "no file in scope"
+    elif without and not data.get("exports"):
+        reason = f"no recipe reads the files in scope ({', '.join(sorted(without))})"
+    elif without and language and language.strip().lower() not in RECIPE_LANGUAGES:
+        reason = (f"no recipe reads the skill's language, {language} "
+                  f"({', '.join(sorted(without))} in scope)")
+    errors = [e for e in data.get("errors") or [] if isinstance(e, dict)]
+    read_by_eye = sorted({str(i["file"]) for i in data.get("file_issues") or []
+                          if isinstance(i, dict) and i.get("file") and i.get("issue") != "no-recipes"}
+                         | {str(e["first_file"]) for e in errors if e.get("first_file")}
+                         | {str(f) for e in errors if isinstance(e.get("unread"), list) for f in e["unread"] if f})
+    return {
+        "status": status,
+        "filesInScope": data.get("files_in_scope"),
+        "truncated": data.get("truncated"),
+        "effectiveDenominator": _count(counts.get("effective_denominator")),
+        "effectiveDenominatorBasis": counts.get("effective_denominator_basis"),
+        "exportsPublicApi": _count(counts.get("exports_public_api")),
+        "arms": arms,
+        "curatedSubset": counts.get("curated_subset") if isinstance(counts.get("curated_subset"), bool) else None,
+        "entryPointStatus": entry_points.get("status"),
+        # A run that read a file in scope and found no entry point says so whether or not ast-grep ran.
+        "entryPointsFound": (bool(entry_points["files"]) if isinstance(entry_points.get("files"), list)
+                             and data.get("files_in_scope") else None),
+        "readByEye": read_by_eye,
+        "fallback": {"needed": reason is not None, "reason": reason},
+    }
+
+
+NO_UMBRELLA = {"entries": [], "names": 0, "reexported": 0, "ratio": None, "umbrella": False}
+
+
+def from_extraction(data: dict, language: str | None = None, brief: dict | None = None) -> dict:
+    """The public surface of an extraction, less what lies outside scope,
+    plus the root exports a stale scope.include glob left out. A nested
+    Python top's records come apart (`nestedRecords`): they count in the
+    scope sets, not in `all`. An extraction the per-file scan replaces
+    (`extraction.fallback.needed`) gives only its scope, its stale globs and
+    its `extraction` object: no name and no set."""
     if data.get("mode") != "full":
         raise InputError("--extraction is not skf-extract-public-api.py --mode full output")
+
+    # The scope: the one the extractor recorded, else the brief's.
+    recorded = data.get("scope") if isinstance(data.get("scope"), dict) else {}
+    scope = _scope(recorded.get("include"), recorded.get("exclude"), recorded.get("tier_a_include"))
+    if not any(scope.values()) and brief is not None:
+        scope = brief["scope"]
+    unmatched = _globs(recorded.get("unmatched_include"))
+    # A tier A glob that matches no file: the runner's list, never re-matched here.
+    unmatched_tier_a = _globs(recorded.get("unmatched_tier_a_include"))
+    extraction = _extraction_summary(data, language)
+    if extraction["fallback"]["needed"]:
+        return {"records": [], "nestedRecords": [], "sets": {}, "outside": [], "nested": [],
+                "staleScope": {"unmatchedInclude": unmatched, "unmatchedTierAInclude": unmatched_tier_a,
+                               "restored": []},
+                "gaps": [], "scope": scope, "scopeType": recorded.get("type"), "umbrella": dict(NO_UMBRELLA),
+                "extraction": extraction}
+
     diff = data.get("entry_point_diff") if isinstance(data.get("entry_point_diff"), dict) else {}
-    public = [p for p in diff.get("public") or [] if isinstance(p, dict) and isinstance(p.get("name"), str)]
+    public = _members_in_place([p for p in diff.get("public") or []
+                                if isinstance(p, dict) and isinstance(p.get("name"), str)])
     outside = [o for o in diff.get("outside_scope") or [] if isinstance(o, dict)]
     gaps = [g for g in diff.get("extraction_gaps") or [] if isinstance(g, dict)]
+
+    entry_points = data.get("entry_points") if isinstance(data.get("entry_points"), dict) else {}
+    entry_files = [e for e in entry_points.get("files") or [] if isinstance(e, dict)]
+    # A Python top nested in another that exports a name is no barrel: its
+    # names leave `all`, `root` and the umbrella ratio, and keep their
+    # records (so the scope sets a specific-modules or stratified brief
+    # counts) and their outside_scope and extraction_gaps rows.
+    nested = _nested_tops(entry_files, set(scope["include"]) | set(scope["tier_a_include"]),
+                          {p.get("entry") for p in public})
+    nested_names = {top: sorted({p["name"] for p in public if p.get("entry") == top}) for top in nested}
+
+    subpath_files = {e.get("file") for e in entry_files
+                     if e.get("subpath") not in ROOT_SUBPATHS and "*" not in str(e.get("subpath"))}
+    root_files = {e.get("file") for e in entry_files if e.get("subpath") in ROOT_SUBPATHS} - set(nested)
+
+    # A scope.include glob that matches no file: the brief predates the
+    # source, so a root export defined in a file no glob covers comes back,
+    # unless the brief excludes or declined that file.
+    declined = [path for path, action in ((brief or {}).get("amendments") or {}).items()
+                if action in DECLINED_ACTIONS]
+    restored = [o for o in outside if unmatched and o.get("entry") in root_files
+                and isinstance(o.get("name"), str) and isinstance(o.get("file"), str) and o["file"]
+                and not any(glob_match(_norm(o["file"]), g)
+                            for g in scope["include"] + scope["exclude"] + declined)]
+    restored_at = {(o["name"], o["file"]): o.get("line") for o in restored}
+    outside = [o for o in outside if (o.get("name"), o.get("file")) not in restored_at]
+
     outside_keys = {(o.get("name"), o.get("file")) for o in outside}
     index = {(e.get("export_name"), e.get("source_file")): e
              for e in data.get("exports") or [] if isinstance(e, dict)}
-    records = []
+    records, nested_records = [], []
     for info in public:
         name, file = info["name"], info.get("file")
         if (name, file) in outside_keys:
             continue
+        if (name, file) in restored_at:
+            # No recipe reads a file out of scope, so its kind is unknown: the
+            # name carries the file and line of its outside_scope row.
+            records.append(_record(name, None, file, restored_at[(name, file)], None, "restored"))
+            continue
         # An aliased re-export (`export { Options as Config }`) is recorded
         # under the name its defining file gives it, `local`.
         found = index.get((info.get("local") or name, file)) or index.get((name, file))
         kind = found.get("export_type") if found else None
-        records.append(_record(name, None if kind == "re-export" else kind, file,
-                               found.get("source_line") if found else info.get("line"),
-                               found.get("signature_line") if found else None, "extraction"))
-
-    scope = data.get("scope") if isinstance(data.get("scope"), dict) else {}
+        (nested_records if info.get("entry") in nested else records).append(
+            _record(name, None if kind == "re-export" else kind, file,
+                    found.get("source_line") if found else info.get("line"),
+                    found.get("signature_line") if found else None, "extraction"))
 
-    entry_points = data.get("entry_points") if isinstance(data.get("entry_points"), dict) else {}
-    entry_files = [e for e in entry_points.get("files") or [] if isinstance(e, dict)]
-    subpath_files = {e.get("file") for e in entry_files
-                     if e.get("subpath") not in ROOT_SUBPATHS and "*" not in str(e.get("subpath"))}
-    root_files = {e.get("file") for e in entry_files if e.get("subpath") in ROOT_SUBPATHS}
     root_names = [p for p in public if p.get("entry") in root_files]
     reexported = [p for p in root_names if p.get("via") not in (None, "declaration")]
 
@@ -424,30 +740,18 @@ def from_extraction(data: dict, language: str | None = None) -> dict:
     if root_files:
         sets["root"] = sorted({p["name"] for p in root_names})
 
-    counts = data.get("counts") if isinstance(data.get("counts"), dict) else {}
-    arms = data.get("arms") if isinstance(data.get("arms"), dict) else {}
-    without = data.get("files_without_recipes") if isinstance(data.get("files_without_recipes"), dict) else {}
-    status = data.get("status")
-    reason = None
-    if status == "no-ast-grep":
-        reason = "no ast-grep the runner can run"
-    elif not data.get("files_in_scope"):
-        reason = "no file in scope"
-    elif without and not data.get("exports"):
-        reason = f"no recipe reads the files in scope ({', '.join(sorted(without))})"
-    elif without and language and language.strip().lower() not in RECIPE_LANGUAGES:
-        reason = (f"no recipe reads the skill's language, {language} "
-                  f"({', '.join(sorted(without))} in scope)")
-    read_by_eye = sorted({str(i["file"]) for i in data.get("file_issues") or []
-                          if isinstance(i, dict) and i.get("file") and i.get("issue") != "no-recipes"}
-                         | {str(e["first_file"]) for e in data.get("errors") or []
-                            if isinstance(e, dict) and e.get("first_file")})
     return {
         "records": records,
+        "nestedRecords": nested_records,
         "sets": sets,
         "outside": [{"name": o.get("name"), "file": o.get("file")} for o in outside],
+        "nested": [{"entry": top, "within": nested[top], "names": nested_names[top]} for top in sorted(nested)],
+        "staleScope": {"unmatchedInclude": unmatched, "unmatchedTierAInclude": unmatched_tier_a,
+                       "restored": [{"name": o["name"], "file": o["file"], "line": o.get("line")}
+                                    for o in sorted(restored, key=lambda o: (o["name"], o["file"]))]},
         "gaps": [{"name": g.get("name"), "file": g.get("file"), "line": g.get("line")} for g in gaps],
-        "scope": _scope(scope.get("include"), scope.get("exclude"), scope.get("tier_a_include")),
+        "scope": scope,
+        "scopeType": recorded.get("type") if isinstance(recorded.get("type"), str) else None,
         "umbrella": {
             "entries": sorted(f for f in root_files if f),
             "names": len(root_names),
@@ -455,17 +759,7 @@ def from_extraction(data: dict, language: str | None = None) -> dict:
             "ratio": round2(len(reexported) / len(root_names)) if root_names else None,
             "umbrella": bool(root_names) and len(reexported) / len(root_names) > UMBRELLA_RATIO,
         },
-        "extraction": {
-            "status": status,
-            "filesInScope": data.get("files_in_scope"),
-            "truncated": data.get("truncated"),
-            "effectiveDenominator": _count(counts.get("effective_denominator")),
-            "effectiveDenominatorBasis": counts.get("effective_denominator_basis"),
-            "exportsPublicApi": _count(counts.get("exports_public_api")),
-            "arms": arms,
-            "readByEye": read_by_eye,
-            "fallback": {"needed": reason is not None, "reason": reason},
-        },
+        "extraction": extraction,
     }
 
 
@@ -473,7 +767,7 @@ def from_quick(data: dict) -> list[dict]:
     exports = data.get("exports")
     if not isinstance(exports, list):
         raise InputError("--quick is not skf-extract-public-api.py --mode quick output (no exports list)")
-    return [_record(e["name"], e.get("type"), e.get("source_file"), None, None, "quick")
+    return [_record(e["name"], e.get("type"), e.get("defined_in") or e.get("source_file"), None, None, "quick")
             for e in exports if isinstance(e, dict) and isinstance(e.get("name"), str) and e["name"]]
 
 
@@ -525,15 +819,68 @@ def fold_names(names: list[str], prefixes: list[str], keep: set[str],
     return variants, tally
 
 
-NO_UMBRELLA = {"entries": [], "names": 0, "reexported": 0, "ratio": None, "umbrella": False}
+def _over(clause: str, sets: dict, name: str, step: int | None, rebuild: str | None = None) -> dict:
+    """The barrel branch over set `name`, the `all` set when the surface lacks it."""
+    present = name in sets
+    return {"clause": clause, "branch": "barrel", "surfaceSet": name if present else "all", "ladderStep": step,
+            "absentSet": None if present else name, "rebuild": rebuild}
+
+
+def pick_denominator(sets: dict, stats_eff: int | None, deflation_fires: bool, barrel: str | None, arms: dict,
+                     scope_type: str | None, skill_type: str | None, monorepo: bool, pattern_reference: bool,
+                     curated: bool, source_read: bool) -> dict:
+    """The Source API Surface Definition's clause for a skill, with the branch
+    and the name set reconcile-coverage.py and score-signatures.py read, and
+    the entry points' state it was picked by (see "Denominator" above)."""
+    return {**_pick(sets, stats_eff, deflation_fires, barrel, arms, scope_type, skill_type, monorepo,
+                    pattern_reference, curated, source_read), "barrel": barrel}
+
+
+def _pick(sets: dict, stats_eff: int | None, deflation_fires: bool, barrel: str | None, arms: dict,
+          scope_type: str | None, skill_type: str | None, monorepo: bool, pattern_reference: bool,
+          curated: bool, source_read: bool) -> dict:
+    if skill_type == "stack":
+        return {"clause": "stack", "branch": "stack", "surfaceSet": None, "ladderStep": None, "absentSet": None,
+                "rebuild": None}
+    multi = bool(arms.get("multi_subpath_exports"))
+    if (not monorepo and barrel != "barrel" and scope_type not in NOT_PATTERN_REFERENCE
+            and not (multi and scope_type == "public-api")
+            and (pattern_reference or (barrel == "no-entry-point" and not multi))):
+        if "tier_a_include" in sets:
+            return _over("pattern-reference", sets, "tier_a_include", None)
+        # The canonicalized provenance map: a surface read from the source is built again from the map alone.
+        return _over("pattern-reference", sets, "all", None, "provenance-fold" if source_read else None)
+    if barrel == "empty-barrel":
+        return _over("empty-barrel", sets, "scope.include", None)
+    if monorepo and curated and scope_type != "full-library":
+        clause = "stratified-scope"
+    elif scope_type == "specific-modules" and not monorepo:
+        clause = "specific-modules"
+    elif multi and not monorepo and scope_type in ("full-library", "public-api"):
+        clause = "multi-entry"
+    else:
+        return _over("standard-barrel", sets, "all", None)
+    ladder = CLAUSE_LADDERS[clause]
+    for step, rung in enumerate(ladder, 1):
+        if rung != "scalar":
+            if rung in sets or step == len(ladder):
+                return _over(clause, sets, rung, step)
+        elif stats_eff:
+            # A stored 0 is no denominator: the next rung.
+            if deflation_fires:
+                return _over(clause, sets, "scope.include", step)
+            scored = next((name for name in ("tier_a_include", "scope.include") if name in sets), "all")
+            return {"clause": clause, "branch": "scalar", "surfaceSet": scored, "ladderStep": step,
+                    "absentSet": None, "rebuild": None}
+    raise AssertionError(f"the {clause} ladder ends on a set")
 
 
 def surface(args: argparse.Namespace) -> dict:
     records: list[dict] = []
     sets: dict[str, list[str]] = {}
     warnings: list[str] = []
-    out: dict = {"candidates": None, "guards": None, "state2": None, "canonical": None,
-                 "extraction": None, "extractionGaps": [], "excluded": {"outsideScope": []}}
+    out: dict = {"candidates": None, "guards": None, "denominator": None, "state2": None, "canonical": None,
+                 "extraction": None, "extractionGaps": [], "excluded": {"outsideScope": [], "nestedEntries": []}}
 
     meta = _object(args.metadata, "--metadata") if args.metadata else None
     provenance = _object(args.provenance, "--provenance") if args.provenance else None
@@ -541,17 +888,23 @@ def surface(args: argparse.Namespace) -> dict:
     language = (brief or {}).get("language")
     if not language and meta is not None and isinstance(meta.get("language"), str):
         language = meta["language"]
+    stats = meta.get("stats") if isinstance(meta, dict) and isinstance(meta.get("stats"), dict) else {}
+    stats_eff = _count(stats.get("effective_denominator"))
 
     extracted = None
     if args.extraction:
-        extracted = from_extraction(_object(args.extraction, "--extraction"), language)
+        data = _object(args.extraction, "--extraction")
+        extracted = from_extraction(data, language, brief)
         records += extracted["records"]
         sets.update(extracted["sets"])
         out["extraction"] = extracted["extraction"]
         out["extractionGaps"] = extracted["gaps"]
-        out["excluded"]["outsideScope"] = extracted["outside"]
+        out["excluded"] = {"outsideScope": extracted["outside"], "nestedEntries": extracted["nested"]}
+        warnings += [f"{Path(args.extraction).name}: {w}" for w in data.get("warnings") or [] if isinstance(w, str)]
+    quick_outputs = []
     for path in args.quick or []:
         data = _object(path, "--quick")
+        quick_outputs.append(data)
         records += from_quick(data)
         warnings += [f"{Path(path).name}: {w}" for w in data.get("warnings") or [] if isinstance(w, str)]
     violations: list[str] = []
@@ -574,11 +927,15 @@ def surface(args: argparse.Namespace) -> dict:
         exports = meta.get("exports") if meta is not None else None
         meta_names = sorted({n for n in (_export_name(e) for e in exports) if n}) if isinstance(exports, list) else []
         base_of: dict[str, str] = {}
+        # A map whose raw count is the stored effective_denominator is already canonical: no fold.
+        skipped = bool(args.fold) and provenance is not None and stats_eff == len(prov_names)
         if args.fold:
             # One fold over both lists, so a variant folded out of the map
             # never comes back through metadata.json.
             base_of, tally = fold_names(sorted(set(prov_names) | set(meta_names)), args.fold_prefix or [],
                                         set(args.keep or []), tallied=set(prov_names))
+            if skipped:
+                base_of, tally = {}, dict.fromkeys(tally, 0)
             if provenance is not None:
                 canonical = sorted({base_of.get(n, n) for n in prov_names})
                 out["canonical"] = {
@@ -586,10 +943,14 @@ def surface(args: argparse.Namespace) -> dict:
                     "canonical": len(canonical),
                     "folded": tally,
                     "variants": {n: base_of[n] for n in prov_names if n in base_of},
+                    "skipped": skipped,
+                    "residual": None if stats_eff is None else len(canonical) - stats_eff,
                     "summary": (f"Provenance-map canonicalization: {len(prov_names)} raw entries → "
                                 f"{len(canonical)} canonical bases ({len(prov_names) - len(canonical)} "
                                 f"bookkeeping variants folded: _def×{tally['_def']}, _exact×{tally['_exact']}, "
-                                f"a11y_×{tally[FOLD_PREFIX]}, other×{tally['other']})"),
+                                f"a11y_×{tally[FOLD_PREFIX]}, other×{tally['other']})"
+                                + (": the raw count equals `stats.effective_denominator`, so the map is already "
+                                   "canonical" if skipped else "")),
                 }
         seen = set()
         for e in named:
@@ -609,22 +970,39 @@ def surface(args: argparse.Namespace) -> dict:
                 "metadataOnly": sorted(set(meta_bases) - seen),
             }
 
-    records.sort(key=lambda r: (r["name"], str(r["file"] or ""), r["origin"]))
     sets["all"] = sorted({r["name"] for r in records})
+    # A nested Python top's records count in the scope sets, never in `all`.
+    records += extracted["nestedRecords"] if extracted is not None else []
+    records.sort(key=lambda r: (r["name"], str(r["file"] or ""), r["origin"]))
 
     # The scope: the one the extractor recorded, else the brief's.
     scope = extracted["scope"] if extracted is not None and any(extracted["scope"].values()) else None
     if scope is None:
         scope = brief["scope"] if brief is not None else _scope(None, None, None)
+    # A tier A glob the runner lists as matching no file counts no name, and
+    # so does one whose folder or file differs from every scope.include
+    # glob's before any `*` or `?` (`gen/**` beside `src/**`) or one a
+    # scope.exclude glob covers segment by segment (`src/gen/**` beside an
+    # exclude of `src/gen/**`), whatever the tree holds: the set comes from
+    # the other globs, over the names whose file a scope.include glob matches
+    # too (any file with none), so a restored name is in no set. A tier A
+    # list that counts no name (every glob stale, or matching only excluded
+    # files, files scope.include leaves out or files that define no name)
+    # narrows nothing: there is no set.
+    stale_tier_a = set(extracted["staleScope"]["unmatchedTierAInclude"]) if extracted is not None else set()
+    tier_a = [g for g in scope["tier_a_include"] if g not in stale_tier_a
+              and not (scope["include"] and all(_apart(g, i) for i in scope["include"]))
+              and not any(_inside(g, e) for e in scope["exclude"])]
     filed = [r for r in records if r["file"]]
     if filed and scope["include"]:
         sets["scope.include"] = matching(filed, scope["include"], scope["exclude"])
-    if filed and scope["tier_a_include"]:
-        sets["tier_a_include"] = matching(filed, scope["tier_a_include"], scope["exclude"])
+    in_include = [r for r in filed if not scope["include"]
+                  or any(glob_match(_norm(r["file"]), g) for g in scope["include"])]
+    tier_a_names = matching(in_include, tier_a, scope["exclude"]) if tier_a else []
+    if tier_a_names:
+        sets["tier_a_include"] = tier_a_names
 
     if extracted is not None or brief is not None or meta is not None:
-        stats = meta.get("stats") if isinstance(meta, dict) and isinstance(meta.get("stats"), dict) else {}
-        stats_eff = _count(stats.get("effective_denominator"))
         include_union = len(sets["scope.include"]) if "scope.include" in sets else len(sets["all"])
         extraction = extracted["extraction"] if extracted is not None else {}
         out["candidates"] = {
@@ -636,12 +1014,21 @@ def surface(args: argparse.Namespace) -> dict:
             "extractorEffectiveDenominator": extraction.get("effectiveDenominator"),
             "extractorBasis": extraction.get("effectiveDenominatorBasis"),
         }
-        no_tier_a = not scope["tier_a_include"]
-        deflation = {"applicable": source_read and bool(stats_eff), "effectiveDenominator": stats_eff,
+        # With an extraction or the fallback scan's results (each at the file
+        # that defines its names), no tier A set is no tier A list; otherwise
+        # the globs left in the list decide (a name read by eye at Quick tier
+        # or State 4, and a quick name with no defined_in, carries its entry
+        # file, not the file that defines it).
+        no_tier_a = ("tier_a_include" not in sets if extracted is not None or args.fallback_scan
+                     else not tier_a)
+        deflation = {"applicable": source_read and stats_eff is not None, "effectiveDenominator": stats_eff,
                      "rederived": include_union if source_read else None, "pct": None, "fires": False}
-        if deflation["applicable"]:
+        if deflation["applicable"] and stats_eff:
             deflation["pct"] = round2((include_union - stats_eff) / stats_eff * 100)
             deflation["fires"] = no_tier_a and deflation["pct"] > DEFLATION_PCT
+        elif deflation["applicable"]:
+            # A stored 0 is deflation, not a denominator, once a name is re-derived.
+            deflation["fires"] = no_tier_a and include_union > 0
         entry_count = len(_entries(provenance)) if provenance is not None else 0
         inflation = {"applicable": source_read and no_tier_a and bool(scope["include"]) and entry_count > 0,
                      "scopeIncludeUnion": include_union if scope["include"] else None,
@@ -650,14 +1037,47 @@ def surface(args: argparse.Namespace) -> dict:
         if inflation["applicable"]:
             inflation["pct"] = round2((include_union - entry_count) / entry_count * 100)
             inflation["fires"] = inflation["pct"] > INFLATION_PCT
+        stale_scope = {"applicable": extracted is not None and bool(scope["include"] or scope["tier_a_include"]),
+                       "fires": False, "unmatchedInclude": [], "unmatchedTierAInclude": [], "restored": []}
+        if stale_scope["applicable"]:
+            stale_scope.update(extracted["staleScope"])
+            stale_scope["fires"] = bool(stale_scope["unmatchedInclude"] or stale_scope["unmatchedTierAInclude"])
         out["guards"] = {
             "deflation": deflation,
             "inflation": inflation,
+            "staleScope": stale_scope,
+            "tierAInclude": list(scope["tier_a_include"]),
             "umbrella": extracted["umbrella"] if extracted is not None else dict(NO_UMBRELLA),
             "thresholds": {"deflationPct": DEFLATION_PCT, "inflationPct": INFLATION_PCT,
                            "umbrellaRatio": UMBRELLA_RATIO},
         }
 
+    # The clause: an extraction's entry-point status (one the per-file scan replaces says only that it found no
+    # entry point), else a quick output's (an export is a barrel; none, and no warning, an empty one), else what
+    # the workflow read (--barrel).
+    barrel = None
+    summary = extracted["extraction"] if extracted is not None else None
+    if summary is not None and not summary["fallback"]["needed"]:
+        barrel = summary["entryPointStatus"]
+    elif summary is not None and summary["entryPointsFound"] is False:
+        barrel = "no-entry-point"
+    elif quick_outputs:
+        barrel = "barrel" if any(q["exports"] for q in quick_outputs) else (
+            None if any(q.get("warnings") for q in quick_outputs) else "empty-barrel")
+    if barrel is None and args.barrel:
+        barrel = BARREL_FLAG[args.barrel]
+    recorded_type = extracted["scopeType"] if extracted is not None else None
+    meta_type = meta.get("scope_type") if isinstance(meta, dict) and isinstance(meta.get("scope_type"), str) else None
+    arms = summary["arms"] if summary is not None else {}
+    # The extraction's verdict, the rule Create Skill stores the count by, else the workflow's judgment.
+    curated = summary["curatedSubset"] if summary is not None and summary["curatedSubset"] is not None \
+        else bool(args.curated_subset)
+    out["denominator"] = pick_denominator(
+        sets, stats_eff, bool((out["guards"] or {}).get("deflation", {}).get("fires")), barrel, arms,
+        (brief or {}).get("type") or recorded_type or meta_type,
+        meta.get("skill_type") if isinstance(meta, dict) else None, bool(args.monorepo or arms.get("monorepo")),
+        bool(args.pattern_reference_intent), curated, source_read)
+
     return {
         "inputs": {
             "extraction": args.extraction, "quick": args.quick or [], "perFile": args.per_file or [],
@@ -708,6 +1128,13 @@ def _build_parser() -> argparse.ArgumentParser:
     p.add_argument("--extraction", help="skf-extract-public-api.py --mode full output")
     p.add_argument("--quick", action="append", help="skf-extract-public-api.py --mode quick output (repeatable)")
     p.add_argument("--per-file", action="append", help="a subagent per-file result (repeatable)")
+    p.add_argument("--fallback-scan", action="store_true",
+                   help="the --per-file results are the fallback scan's, each at the file that defines its "
+                        "names: as with --extraction, no tier_a_include set is no tier A list, so the deflation "
+                        "and inflation guards run; without either, a tier_a_include glob keeps them off unless "
+                        "its folder or file differs from every scope.include glob's before any wildcard "
+                        "(gen/** beside src/**) or a scope.exclude glob covers it segment by segment "
+                        "(src/gen/** beside an exclude of src/gen/**)")
     p.add_argument("--name", action="append", help="a name read by eye whose file is not known (repeatable)")
     p.add_argument("--provenance", help="the provenance map: its named exports")
     p.add_argument("--metadata", help="metadata.json: its exports[] names, stats and language")
@@ -715,6 +1142,17 @@ def _build_parser() -> argparse.ArgumentParser:
     p.add_argument("--fold", action="store_true", help="fold the provenance and metadata bookkeeping variants")
     p.add_argument("--fold-prefix", action="append", help="a renderer prefix to fold (repeatable)")
     p.add_argument("--keep", action="append", help="a variant that is a real export (repeatable)")
+    p.add_argument("--monorepo", action="store_true",
+                   help="the source is a monorepo (skf-detect-workspaces.py's is_monorepo)")
+    p.add_argument("--pattern-reference-intent", action="store_true",
+                   help="the brief's scope.notes flags pattern-reference intent (your judgment)")
+    p.add_argument("--curated-subset", action="store_true",
+                   help="with --monorepo: the brief's scope.include lists a curated subset rather than the full "
+                        "workspace (your judgment; an extraction's counts.curated_subset wins)")
+    p.add_argument("--barrel", choices=tuple(BARREL_FLAG),
+                   help="the entry points as you read them, where no extraction or quick output tells: none (no "
+                        "barrel file at any recognized entry-point path), empty (the primary one exports nothing) "
+                        "or barrel")
     p.add_argument("--output", help="also write the result to this file")
     p.set_defaults(func=surface)
     return parser