aw-spec-cli 0.1.19 → 0.1.21

package/assets/.appweaver/scripts/python/aw-inventory.py

@@ -56,6 +56,7 @@ Usage: aw-inventory.py <scan|concept|list-aggregates|validate> [options]
 """
 
 import argparse
+import datetime
 import json
 import os
 import re
@@ -367,10 +368,20 @@ CODE_EXT_RE = re.compile(r"\.(py|js|ts|go|rs|rb|java|cs|php|kt|scala|sql|prisma)
 
 def singularize(name):
     """Light singularization for a module dir name (MedicinalProducts ->
-    MedicinalProduct). Signal-grade only — never grammar-perfect."""
-    if len(name) > 4 and name.endswith("s") and not name.lower().endswith(("ss", "us", "is", "as")):
-        return name[:-1]
-    return name
+    MedicinalProduct, Pharmacies -> Pharmacy). Signal-grade only — never
+    grammar-perfect. The name reaches a person in the proposal document, so the
+    -ies and -es endings are worth carrying: Pharmacie is a visible defect in a
+    file an operator is asked to review."""
+    if len(name) <= 4 or not name.endswith(("s", "S")):
+        return name
+    low = name.lower()
+    if low.endswith(("ss", "us", "is", "as")):
+        return name
+    if low.endswith("ies"):
+        return name[:-3] + "y"
+    if low.endswith(("ses", "xes", "zes", "ches", "shes")):
+        return name[:-2]
+    return name[:-1]
 
 
 # --- glob-based config excludes (best-effort, mirrors okf-inventory.sh) -----
@@ -495,85 +506,1103 @@ def _entity_noun(path):
     return base if base and base[:1].isalpha() and len(base) > 2 else None
 
 
-def aggregate_signals(files, churn_map):
-    """Derive CANDIDATE aggregate roots — one per vertical slice, the base unit
-    the /appweaver inventory workflow turns into a specs/<Feature>/ slice.
+# ═══════════════════════════════════════════════════════════════════════════
+# PASS A — aggregate identification: what must stay consistent together.
+#
+# Three strategies share one interface — (root, files, churn_map, graph) ->
+# [candidate] — and emit the candidate shape aggregate_signals() has always
+# emitted, plus `strategy`, `confidence` and (persistence only) `owns` /
+# `references_by_id`.
+#
+# S1 is not a peer of the other two. S2 returns unnamed file clusters and S3
+# returns entity roots; both need S1's axis detection to turn a cluster into a
+# module_dir and a human name, so S1 always runs underneath as the naming layer.
+# ═══════════════════════════════════════════════════════════════════════════
+
+# Path segments that organise code without naming a domain module. The parent
+# of a layer folder decides whether that layer is a module boundary: in
+# src/Features/Patients/Domain/X.cs the module is Patients, and `Features` says
+# only that a vertical-slice layout is in use. `features?` is itself a member of
+# LAYER_DIR_RE, so without this list the walk stops at the container and names
+# the module `src`.
+CONTAINER_DIR_RE = re.compile(
+    r"^(src|source|sources|lib|libs|app|apps|pkg|packages?|projects?|modules?|"
+    r"slices?|features?|areas?|components?|services?|internal|cmd|main|java|"
+    r"kotlin|resources|test|tests|spec|specs|__tests__)$",
+    re.IGNORECASE,
+)
+# A project segment carrying its layer as a name SUFFIX (Acme.Patient.Domain).
+# LAYER_DIR_RE is anchored ^…$ and cannot see these, which is why a repo laid
+# out one-project-per-layer yields nothing from the folder walk alone.
+DOTTED_SEG_RE = re.compile(r"^[A-Za-z_]\w*(\.[A-Za-z_]\w*)+$")
+# Organisation/product prefixes that lead a dotted project name without naming
+# a module. Dropped from the left before the module segment is read.
+VENDOR_PREFIX_RE = re.compile(r"^(com|org|net|io|co|inc|ltd)$", re.IGNORECASE)
+
+
+# Folders that hold ONE vertical slice per child. These are also members of
+# LAYER_DIR_RE, and reading them as layers is what collapses a vertical-slice
+# repo onto its container: in <Project>/Features/Orders/ the module is Orders,
+# and `Features` only says which layout is in use. Checked before the layer
+# vocabulary, and independently of what the parent segment is — the container
+# can sit under src/ or directly under a project folder.
+SLICE_CONTAINER_RE = re.compile(
+    r"^(features?|modules?|slices?|areas?|use[-_]?cases?|capabilit(y|ies))$",
+    re.IGNORECASE,
+)
+# A second layer vocabulary, consulted only to BUCKET a file once its module is
+# already known. These names are too generic to mark a module boundary — every
+# project has a Services/ — but they do say what the file is once you are inside
+# one, which is what keeps the layer mix of a candidate meaningful.
+SOFT_LAYER_KIND = {
+    "services": "feature", "service": "feature", "commands": "feature",
+    "queries": "feature", "validators": "feature", "behaviors": "feature",
+    "interfaces": "domain", "abstractions": "domain", "events": "domain",
+    "exceptions": "domain", "specifications": "domain", "valueobjects": "domain",
+    "enums": "domain", "stores": "infra", "publishers": "infra",
+    "interceptors": "infra", "composition": "infra", "migrations": "infra",
+    "configurations": "infra", "contexts": "infra", "middleware": "api",
+    "filters": "api", "views": "api", "pages": "api", "components": "api",
+    "extensions": "other", "utilities": "other", "utils": "other",
+    "helpers": "other", "common": "other", "mappers": "other",
+}
+# Trailing parts of a dotted project name that say what the project IS rather
+# than which module it serves (AppWeaver.VerticalSlice.Service -> VerticalSlice).
+PROJECT_ROLE_RE = re.compile(
+    r"^(service|services|web|webapi|api|apis|apphost|host|hosting|"
+    r"servicedefaults|defaults|worker|workers|console|cli|functions|"
+    r"tests?|unittests?|integrationtests?|testing|benchmarks?|samples?|"
+    r"client|clients|server|sdk|lib|library|app|blazor|razor|mvc|grpc)$",
+    re.IGNORECASE,
+)
 
-    PRIMARY signal (low-noise): a MODULE DIRECTORY that owns layer folders
-    (Domain / Features / Persistence / Api …). Its parent segment, singularized,
-    is the aggregate (…/MedicinalProducts/Domain/… -> MedicinalProduct); every
-    file under the module is grouped by layer. FALLBACK (flat repos with no
-    layer folders): cluster domain/route/api files on the basename noun.
 
-    Signals only — the workflow's agent draws the real boundaries. Empty for a
-    repo with no recognizable domain structure."""
-    modules = {}  # module_dir -> candidate
+def _layer_of(seg, soft=False):
+    """The layer bucket a path segment names, or None when it names no layer.
+
+    `soft` widens the vocabulary to the generic folder names that describe a
+    file without bounding a module."""
+    s = (seg or "").lower()
+    if LAYER_DIR_RE.match(seg or ""):
+        return LAYER_KIND.get(s, "other")
+    return SOFT_LAYER_KIND.get(s) if soft else None
+
+
+def _project_roots(files):
+    """Directories a build manifest calls a project. This is the one module
+    boundary in a repo that is EVIDENCED rather than inferred from a folder
+    name, so it carries the fallback when no layer vocabulary appears at all —
+    which is the common case in a library-shaped tree whose folders are
+    Services/ and Extensions/."""
+    roots = set()
+    for f in files:
+        if MANIFESTS_RE.search(f) and "/" in f:
+            roots.add(f.rsplit("/", 1)[0])
+    return roots
 
-    def module_candidate(module_dir, name):
-        return modules.setdefault(module_dir, {
-            "name": name, "module_dir": module_dir,
-            "domain_files": [], "feature_files": [], "infra_files": [],
-            "api_files": [], "other_files": [], "entities": set(), "churn": 0,
-        })
 
-    # PRIMARY: walk each file's path for a layer folder; its parent is the module.
-    module_files = {}  # module_dir -> [(file, kind)]
+def _product_prefix(files):
+    """The dotted prefix this repo puts in front of most project names, measured
+    rather than assumed. `AppWeaver` leads nearly every project here and names no
+    module, so carrying it into every candidate would make the map unreadable."""
+    heads = {}
+    for f in files:
+        for seg in f.split("/")[:-1]:
+            if DOTTED_SEG_RE.match(seg):
+                h = seg.split(".")[0]
+                heads[h] = heads.get(h, 0) + 1
+    if not heads:
+        return ""
+    top, n = max(heads.items(), key=lambda kv: kv[1])
+    return top if n >= 3 and n >= 0.5 * sum(heads.values()) else ""
+
+
+def _clean_project_name(seg, product):
+    """A dotted project segment reduced to the module it serves: the measured
+    product prefix dropped from the left, project-role words from the right."""
+    parts = [p for p in (seg or "").split(".") if p]
+    if product and len(parts) > 1 and parts[0].lower() == product.lower():
+        parts = parts[1:]
+    while len(parts) > 1 and PROJECT_ROLE_RE.match(parts[-1]):
+        parts = parts[:-1]
+    while len(parts) > 1 and VENDOR_PREFIX_RE.match(parts[0]):
+        parts = parts[1:]
+    name = "".join(p[:1].upper() + p[1:] for p in parts)
+    return singularize(name) or name
+
+
+def _dotted_module(seg):
+    """Split a dotted project segment into (module, layer_kind), or (None, None).
+
+    Acme.Patient.Domain -> (Patient, domain); Patient.Api -> (Patient, api).
+    The layer is the LAST dot-part; everything between the vendor prefix and it
+    is the module, so Acme.Billing.Invoices.Domain -> BillingInvoices."""
+    if not DOTTED_SEG_RE.match(seg or ""):
+        return None, None
+    parts = seg.split(".")
+    kind = _layer_of(parts[-1])
+    if not kind or len(parts) < 2:
+        return None, None
+    mid = parts[:-1]
+    while len(mid) > 1 and VENDOR_PREFIX_RE.match(mid[0]):
+        mid = mid[1:]
+    # A single leading segment is the product name, not a module, once another
+    # segment follows it (Acme.Patient -> Patient).
+    if len(mid) > 1:
+        mid = mid[1:]
+    name = "".join(p[:1].upper() + p[1:] for p in mid)
+    return (singularize(name) or name, kind) if name else (None, None)
+
+
+# How much a rule's naming is trusted when two rules land files in one group.
+AXIS_RANK = {"slice-major": 0, "project-major": 1, "module-major": 2,
+             "layer-major": 3, "project-root": 4, "flat": 5}
+
+
+def _structure_rows(files):
+    """Classify each file onto the repo's organising axis, yielding
+    (group_key, module_name, layer_kind, file, axis).
+
+    Five idioms, tried in order of how specific their evidence is:
+
+      slice-major    <Project>/Features/Orders/…      an explicit vertical slice
+      project-major  src/Acme.Patient.Domain/X.cs     layer carried as a name suffix
+      module-major   src/Patients/Domain/X.cs         layer folder under the module
+      layer-major    src/Domain/Patient.cs            layer at the top; the module
+                                                      exists only as a repeated noun
+      project-root   AppWeaver.AI/Services/X.cs       no layer vocabulary at all;
+                                                      the build manifest bounds it
+
+    layer-major groups on the role-stripped basename rather than on a folder,
+    which is the only thing that unifies Patient.cs, PatientService.cs and
+    PatientController.cs across three sibling tier folders. project-root catches
+    the library-shaped tree whose folders (Services/, Extensions/) describe files
+    without bounding modules — without it those files reach no candidate at all."""
+    proj_roots = _project_roots(files)
+    product = _product_prefix(files)
+
     for f in files:
         parts = f.split("/")
-        for i in range(1, len(parts) - 1):  # a layer folder needs a parent + a child
-            if LAYER_DIR_RE.match(parts[i]):
-                module_dir = "/".join(parts[:i])
-                kind = LAYER_KIND.get(parts[i].lower(), "other")
-                module_files.setdefault(module_dir, []).append((f, kind))
+        if len(parts) < 2:
+            continue
+        dirs = parts[:-1]
+        hit = None
+
+        # slice-major — a slice container names the module in its CHILD.
+        for i, seg in enumerate(dirs):
+            if not SLICE_CONTAINER_RE.match(seg):
+                continue
+            nxt = dirs[i + 1] if i + 1 < len(dirs) else ""
+            if nxt and not _layer_of(nxt) and not SLICE_CONTAINER_RE.match(nxt):
+                kind = next((_layer_of(p, soft=True) for p in dirs[i + 2:]
+                             if _layer_of(p, soft=True)), "feature")
+                name = singularize(nxt) or nxt
+                hit = ("/".join(dirs[:i + 2]), name, kind, "slice-major")
+            break
+
+        # project-major — a dotted segment whose last dot-part is the layer.
+        if not hit:
+            for i, seg in enumerate(dirs):
+                mod, kind = _dotted_module(seg)
+                if mod:
+                    hit = ("/".join(dirs[:i] + [mod]), mod, kind, "project-major")
+                    break
+
+        # module-major / layer-major — a layer FOLDER, read through its parent.
+        if not hit:
+            for i, seg in enumerate(dirs):
+                kind = _layer_of(seg)
+                if not kind:
+                    continue
+                parent = dirs[i - 1] if i else ""
+                if i and not CONTAINER_DIR_RE.match(parent):
+                    name = (_clean_project_name(parent, product)
+                            if DOTTED_SEG_RE.match(parent) else singularize(parent) or parent)
+                    hit = ("/".join(dirs[:i]), name, kind, "module-major")
+                else:
+                    noun = _entity_noun(f)
+                    if noun:
+                        hit = ("/".join(dirs[:i] + [noun]), noun, kind, "layer-major")
                 break
 
-    for module_dir, entries in module_files.items():
-        name = singularize(os.path.basename(module_dir)) or os.path.basename(module_dir)
-        c = module_candidate(module_dir, name)
-        for f, kind in entries:
-            c[kind + "_files"].append(f)
-            c["churn"] += churn_map.get(f, 0)
-            if kind == "domain":
-                n = _entity_noun(f)
-                if n:
-                    c["entities"].add(n)
+        # A dotted project segment bounds a module even with no layer anywhere in
+        # it and no manifest tracked beside it — which is how a test project that
+        # mirrors its subject (Acme.Billing.Tests) reaches the same candidate.
+        if not hit:
+            for i, seg in enumerate(dirs):
+                if DOTTED_SEG_RE.match(seg):
+                    name = _clean_project_name(seg, product)
+                    if name:
+                        kind = next((_layer_of(p, soft=True) for p in dirs[i + 1:]
+                                     if _layer_of(p, soft=True)), "other")
+                        hit = ("/".join(dirs[:i] + [name]), name, kind, "project-major")
+                    break
+
+        # project-root — the build manifest is the boundary of last resort.
+        if not hit:
+            for i in range(len(dirs), 0, -1):
+                d = "/".join(dirs[:i])
+                if d in proj_roots:
+                    kind = next((_layer_of(p, soft=True) for p in dirs[i:]
+                                 if _layer_of(p, soft=True)), "other")
+                    hit = (d, _clean_project_name(dirs[i - 1], product), kind, "project-root")
+                    break
+
+        if hit and hit[1]:
+            yield hit[0], hit[1], hit[2], f, hit[3]
+
+
+def _blank_candidate(group_key, name):
+    return {"name": name, "module_dir": group_key,
+            "domain_files": [], "feature_files": [], "infra_files": [],
+            "api_files": [], "other_files": [], "entities": set(), "churn": 0}
+
 
-    sig = []
-    for c in modules.values():
-        layers = ("domain_files", "feature_files", "infra_files", "api_files", "other_files")
-        # Drop pure-doc/config false positives (e.g. docs/domain/): a real
-        # aggregate module owns at least one source file.
+LAYER_KEYS = ("domain_files", "feature_files", "infra_files", "api_files", "other_files")
+# Suffixes that make a project a VARIANT of a concern rather than a concern of
+# its own — the EF adapter, the abstractions package, the in-memory double. They
+# share the concern's lifecycle, so they belong to its aggregate.
+VARIANT_SUFFIX_RE = re.compile(
+    r"(EfCore|EntityFramework|Ef|Dapper|Sql|SqlServer|Postgres|Mongo|Redis|"
+    r"InMemory|Abstractions?|Contracts?|Core|Shared|Common|Adapter|Provider|"
+    r"Extensions?|Integration|Http|Grpc|Rest)$")
+
+
+def _consolidate(cands):
+    """Fold candidates that name the same concern into one.
+
+    A module, its mirror test project and its adapter variants are one unit that
+    must stay consistent together — AppWeaver.Auditing, AppWeaver.Auditing.Tests
+    and AppWeaver.Auditing.EfCore are the Auditing aggregate, not three. Without
+    this a project-per-layer repo reports one candidate per assembly and the map
+    becomes a build listing."""
+    by_name = {}
+    for c in cands.values():
+        by_name.setdefault(c["name"].lower(), []).append(c)
+
+    # A variant folds into its base only when that base is a candidate already,
+    # so a repo whose only Auditing project IS AppWeaver.Auditing.EfCore keeps it.
+    canonical = {k: v[0]["name"] for k, v in by_name.items()}
+    for key in sorted(by_name, key=len, reverse=True):
+        if key not in by_name:
+            continue
+        stem = VARIANT_SUFFIX_RE.sub("", by_name[key][0]["name"])
+        if stem and stem.lower() != key and stem.lower() in by_name:
+            by_name[stem.lower()].extend(by_name.pop(key))
+
+    merged = {}
+    for key, group in by_name.items():
+        # The concern names the merged unit, never the largest variant of it:
+        # Auditing absorbing Auditing.EfCore is still Auditing.
+        lead = max(group, key=lambda c: sum(len(c[k]) for k in LAYER_KEYS))
+        lead["name"] = canonical.get(key, lead["name"])
+        for c in group:
+            if c is lead:
+                continue
+            for k in LAYER_KEYS:
+                lead[k].extend(c[k])
+            lead["churn"] += c["churn"]
+            lead["entities"] = set(lead["entities"]) | set(c["entities"])
+            lead.setdefault("merged_dirs", []).append(c["module_dir"])
+        # Keyed by the concern, not by module_dir: two clusters can legitimately
+        # share a directory prefix, and keying on the path silently drops one.
+        merged[key] = lead
+    return merged
+
+
+def _finish_candidates(cands, churn_map, strategy, min_files=1):
+    """Apply the shared candidate contract: drop doc/config-only groups, cap the
+    file lists, and rank by evidence then churn — identical for every strategy
+    so the probe compares like with like."""
+    layers = LAYER_KEYS
+    out = []
+    for c in _consolidate(cands).values():
         if not any(CODE_EXT_RE.search(f) for k in layers for f in c[k]):
             continue
+        # Counted before the payload cap: CAP bounds what the substrate CARRIES,
+        # and reporting coverage from the capped lists would understate a
+        # strategy on a large repo purely because its clusters are big.
+        c["raw_file_count"] = len({f for k in layers for f in c[k]})
+        c["covered_code"] = sorted({f for k in layers for f in c[k]
+                                    if CODE_EXT_RE.search(f)})
         for k in layers:
             c[k] = sorted(set(c[k]))[:CAP]
-        c["entities"] = sorted(c["entities"])[:CAP]
+        c["entities"] = sorted(c["entities"])[:CAP] if isinstance(c["entities"], set) else c["entities"]
         c["file_count"] = sum(len(c[k]) for k in layers)
+        if c["file_count"] < min_files:
+            continue
         c["evidence_count"] = c["file_count"]
-        sig.append(c)
+        c["strategy"] = strategy
+        c.setdefault("confidence", "medium")
+        out.append(c)
+    out.sort(key=lambda c: (c["evidence_count"], c["churn"]), reverse=True)
+    return out
 
-    # FALLBACK: only if the module walk found nothing (flat repo, no layer dirs).
-    if not sig:
-        domain = matching(files, DB_FILES_RE) + [f for f in files if DOMAIN_DIR_RE.search(f)]
-        flat = {}
-        for f in domain + matching(files, ROUTES_RE) + matching(files, API_DEFS_RE):
+
+def strategy_structure(root, files, churn_map, graph=None):
+    """S1 — cluster on the repo's own organising axis.
+
+    Always available: every repo has a layout. Where no layer vocabulary appears
+    at all, the noun fallback still clusters the domain/route/api files on their
+    basename, so a flat repo is not a zero-candidate repo."""
+    cands, axes, naming = {}, {}, {}
+    for key, name, kind, f, axis in _structure_rows(files):
+        axes[axis] = axes.get(axis, 0) + 1
+        c = cands.setdefault(key, _blank_candidate(key, name))
+        # Two rules can feed one group — a project-root file and a module-major
+        # file under the same project. The more specific rule names it.
+        rank = AXIS_RANK.get(axis, 9)
+        if rank < naming.get(key, (9, "", ""))[0]:
+            naming[key] = (rank, name, axis)
+            c["name"], c["axis"] = name, axis
+        c[(kind or "other") + "_files"].append(f)
+        c["churn"] += churn_map.get(f, 0)
+        if kind == "domain":
+            n = _entity_noun(f)
+            if n:
+                c["entities"].add(n)
+
+    if not cands:
+        for f in (matching(files, DB_FILES_RE) + [x for x in files if DOMAIN_DIR_RE.search(x)]
+                  + matching(files, ROUTES_RE) + matching(files, API_DEFS_RE)):
             noun = _entity_noun(f)
             if not noun:
                 continue
-            c = flat.setdefault(noun.lower(), {
-                "name": noun, "module_dir": "", "domain_files": [], "feature_files": [],
-                "infra_files": [], "api_files": [], "other_files": [], "entities": [], "churn": 0})
+            c = cands.setdefault(noun.lower(), _blank_candidate("", noun))
             c["other_files"].append(f)
             c["churn"] += churn_map.get(f, 0)
-        for c in flat.values():
-            c["other_files"] = sorted(set(c["other_files"]))[:CAP]
-            c["file_count"] = len(c["other_files"])
-            c["evidence_count"] = c["file_count"]
-            if c["file_count"] >= 2:
-                sig.append(c)
+        axes["flat"] = len(cands)
+        return _finish_candidates(cands, churn_map, "structure", min_files=2)
+
+    out = _finish_candidates(cands, churn_map, "structure")
+    primary = max(axes, key=axes.get) if axes else "flat"
+    for c in out:
+        c.setdefault("axis", primary)
+        c["repo_axis"] = primary
+    return out
+
+
+# ── The reference graph ────────────────────────────────────────────────────
+# Built for EVERY run, not only when S2 is the chosen strategy: the same edges
+# that cluster files are what order the proposal by dependency, and an S1 or S3
+# run needs that order just as much. Only the CLUSTERING is single-strategy.
+
+READ_CAP_BYTES = 400_000
+READ_CAP_FILES = 20_000
+# What counts as shared kernel in the import graph. A file this many others
+# import is infrastructure by usage, whatever its folder says.
+HUB_MIN_INDEGREE = 8
+HUB_PERCENTILE = 0.05
+NS_DECL_RE = {
+    "cs":    re.compile(r"^\s*namespace\s+([A-Za-z_][\w.]*)", re.M),
+    "java":  re.compile(r"^\s*package\s+([A-Za-z_][\w.]*)\s*;", re.M),
+    "kt":    re.compile(r"^\s*package\s+([A-Za-z_][\w.]*)", re.M),
+    "scala": re.compile(r"^\s*package\s+([A-Za-z_][\w.]*)", re.M),
+}
+IMPORT_RE = {
+    "cs":    re.compile(r"^\s*(?:global\s+)?using\s+(?:static\s+)?(?:\w+\s*=\s*)?([A-Za-z_][\w.]*)\s*;", re.M),
+    "java":  re.compile(r"^\s*import\s+(?:static\s+)?([A-Za-z_][\w.]*)", re.M),
+    "kt":    re.compile(r"^\s*import\s+([A-Za-z_][\w.]*)", re.M),
+    "scala": re.compile(r"^\s*import\s+([A-Za-z_][\w.]*)", re.M),
+    "py":    re.compile(r"^\s*(?:from\s+([.\w]+)\s+import|import\s+([\w.]+))", re.M),
+    "js":    re.compile(r"""(?:from\s*|require\(\s*|import\(\s*)['"]([^'"\n]+)['"]""", re.M),
+    "go":    re.compile(r"""^\s*(?:[\w.]+\s+)?"([^"\n]+)"\s*$""", re.M),
+    "rb":    re.compile(r"""^\s*require(?:_relative)?\s+['"]([^'"\n]+)['"]""", re.M),
+    "php":   re.compile(r"^\s*use\s+([A-Za-z_\\][\w\\]*)", re.M),
+    "rs":    re.compile(r"^\s*use\s+(?:crate::)?([\w:]+)", re.M),
+}
+_EXT_LANG = {"cs": "cs", "java": "java", "kt": "kt", "kts": "kt", "scala": "scala",
+             "py": "py", "go": "go", "rb": "rb", "php": "php", "rs": "rs"}
+for _e in ("ts", "tsx", "js", "jsx", "mjs", "cjs", "vue", "svelte"):
+    _EXT_LANG[_e] = "js"
+_JS_TRY = ("", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".vue", ".svelte",
+           "/index.ts", "/index.tsx", "/index.js", "/index.jsx")
+
+
+def _lang_of(path):
+    return _EXT_LANG.get(os.path.splitext(path)[1].lstrip(".").lower())
+
+
+def _read_source(root, rel):
+    try:
+        p = os.path.join(root, rel)
+        if os.path.getsize(p) > READ_CAP_BYTES:
+            return ""
+        with open(p, "r", encoding="utf-8", errors="replace") as fh:
+            return fh.read()
+    except Exception:
+        return ""
+
+
+def build_reference_graph(root, files):
+    """file -> set(file), from each source file's own import statements.
+
+    Two resolution currencies, because the language families name a dependency
+    differently. Namespace languages (C#, Java, Kotlin, Scala) name a NAMESPACE,
+    resolved through an index of which files declare it; path languages (TS/JS,
+    Python, Go, Ruby) name a PATH, resolved against the importing file and then
+    against the file list. Anything that resolves outside the repo is a
+    third-party package and is dropped — an edge only means something here when
+    both ends are files this scan can see."""
+    srcs = [f for f in files if _lang_of(f)][:READ_CAP_FILES]
+    text = {f: _read_source(root, f) for f in srcs}
+
+    ns_index, by_noext, by_suffix = {}, {}, {}
+    for f in srcs:
+        lang = _lang_of(f)
+        if lang in NS_DECL_RE:
+            m = NS_DECL_RE[lang].search(text[f])
+            if m:
+                ns_index.setdefault(m.group(1), set()).add(f)
+        noext = os.path.splitext(f)[0]
+        by_noext.setdefault(noext, set()).add(f)
+        by_suffix.setdefault(noext.rsplit("/", 1)[-1], set()).add(f)
+        if "/" in noext:
+            by_suffix.setdefault("/".join(noext.rsplit("/", 2)[-2:]), set()).add(f)
+
+    edges, resolved, seen = {}, 0, 0
+    for f in srcs:
+        lang, body = _lang_of(f), text[f]
+        if not body:
+            continue
+        here = os.path.dirname(f)
+        targets = set()
+        for m in IMPORT_RE[lang].finditer(body):
+            raw = next((g for g in m.groups() if g), "")
+            if not raw:
+                continue
+            seen += 1
+            hits = set()
+            if lang in NS_DECL_RE:
+                hits = ns_index.get(raw.replace("\\", "."), set())
+            elif lang == "js":
+                if raw.startswith("."):
+                    base = os.path.normpath(os.path.join(here, raw)).replace(os.sep, "/")
+                    for suf in _JS_TRY:
+                        cand = (base + suf) if suf.startswith("/") or not suf else base + suf
+                        hits = by_noext.get(os.path.splitext(cand)[0], set())
+                        if hits:
+                            break
+            elif lang == "py":
+                dots = len(raw) - len(raw.lstrip("."))
+                rel = raw.lstrip(".").replace(".", "/")
+                base = here
+                for _ in range(max(0, dots - 1)):
+                    base = os.path.dirname(base)
+                cand = (base + "/" + rel).lstrip("/") if dots else rel
+                hits = by_noext.get(cand, set()) or by_noext.get(cand + "/__init__", set())
+            else:
+                key = raw.strip("/").replace("\\", "/")
+                hits = by_suffix.get(key.rsplit("/", 1)[-1], set()) if "/" not in key else \
+                    by_suffix.get("/".join(key.rsplit("/", 2)[-2:]), set())
+            hits = {h for h in hits if h != f}
+            if hits:
+                resolved += 1
+                targets |= hits
+        if targets:
+            edges[f] = targets
+
+    return edges, {"parseable_files": len(srcs), "imports_seen": seen,
+                   "imports_resolved": resolved,
+                   "truncated": len([f for f in files if _lang_of(f)]) > READ_CAP_FILES}
+
+
+# Keys a candidate carries for the passes' own use and must NOT carry into the
+# substrate file. `covered_code` is the uncapped membership coverage and edge
+# ownership are measured from; serialized, it would duplicate the layer lists CAP
+# exists to bound, and this substrate is inlined verbatim into every agent
+# request a run makes.
+INTERNAL_CANDIDATE_KEYS = ("covered_code",)
+
+
+def strip_internal(cands):
+    """The candidate list as the substrate should carry it."""
+    return [{k: v for k, v in c.items() if k not in INTERNAL_CANDIDATE_KEYS}
+            for c in cands]
+
+
+def _candidate_of_file(cands):
+    """file -> candidate name, the lookup that turns file edges into module edges.
+
+    Reads the UNCAPPED membership where it exists: CAP bounds what the substrate
+    carries, and resolving ownership from the capped lists silently drops every
+    edge whose endpoint sits past the cap."""
+    owner = {}
+    for c in cands:
+        for f in c.get("covered_code") or []:
+            owner[f] = c["name"]
+        for k in LAYER_KEYS:
+            for f in c[k]:
+                owner.setdefault(f, c["name"])
+    return owner
+
+
+def candidate_edges(cands, graph):
+    """Module-level dependency edges: {name: {name, …}}, self-edges dropped.
+
+    This is the graph the proposal is ordered by, and the reason the reference
+    parse runs regardless of which strategy drew the boundaries."""
+    owner = _candidate_of_file(cands)
+    out = {c["name"]: set() for c in cands}
+    for src, dsts in graph.items():
+        a = owner.get(src)
+        if not a:
+            continue
+        for d in dsts:
+            b = owner.get(d)
+            if b and b != a:
+                out[a].add(b)
+    return out
+
+
+def strategy_reference(root, files, churn_map, graph=None):
+    """S2 — cluster on the import graph by label propagation.
+
+    Language-agnostic and close to complete coverage where the languages parse,
+    and it separates a shared kernel from a feature by shape rather than by name:
+    a node everything imports gathers no label of its own and falls out as the
+    high-fan-in cluster it is. Clusters arrive UNNAMED — S1 names them, which is
+    why it is the layer underneath rather than a competing option."""
+    graph = graph if graph is not None else build_reference_graph(root, files)[0]
+    named = strategy_structure(root, files, churn_map)
+    owner = _candidate_of_file(named)
+
+    # In-degree first: the files everything imports are the shared kernel, and
+    # they have to come OUT of the graph before it is cut. Left in, they are the
+    # bridge that joins every slice to every other, and any clustering run over
+    # them returns one component containing the whole repository.
+    indeg = {}
+    for bs in graph.values():
+        for b in bs:
+            indeg[b] = indeg.get(b, 0) + 1
+    ranked = sorted(indeg.values(), reverse=True)
+    cut = max(HUB_MIN_INDEGREE,
+              ranked[max(0, int(len(ranked) * HUB_PERCENTILE) - 1)] if ranked else 0)
+    hubs = {f for f, d in indeg.items() if d >= cut}
+
+    undirected = {}
+    for a, bs in graph.items():
+        if a in hubs:
+            continue
+        for b in bs:
+            if b in hubs:
+                continue
+            undirected.setdefault(a, set()).add(b)
+            undirected.setdefault(b, set()).add(a)
+
+    # What is left separates into genuine components — the slices that do not
+    # reach each other except through the kernel just removed.
+    clusters, seen_nodes = {}, set()
+    for start in sorted(undirected):
+        if start in seen_nodes:
+            continue
+        stack, comp = [start], []
+        seen_nodes.add(start)
+        while stack:
+            n = stack.pop()
+            comp.append(n)
+            for m in undirected[n]:
+                if m not in seen_nodes:
+                    seen_nodes.add(m)
+                    stack.append(m)
+        clusters[start] = comp
+    if hubs:
+        clusters["\x00shared-kernel"] = sorted(hubs)
+
+    cands = {}
+    for lab, group in clusters.items():
+        # The cluster's name is the S1 module most of its files already belong to.
+        votes = {}
+        for f in group:
+            n = owner.get(f)
+            if n:
+                votes[n] = votes.get(n, 0) + 1
+        if lab == "\x00shared-kernel":
+            name = "SharedKernel"
+        else:
+            name = max(sorted(votes), key=votes.get) if votes else _entity_noun(lab)
+        if not name:
+            continue
+        key = os.path.commonprefix([os.path.dirname(f) + "/" for f in group]).rstrip("/")
+        c = cands.setdefault(name.lower(), _blank_candidate(key, name))
+        for f in group:
+            kind = next((_layer_of(p, soft=True) for p in f.split("/")[:-1]
+                         if _layer_of(p, soft=True)), "other")
+            c[kind + "_files"].append(f)
+            c["churn"] += churn_map.get(f, 0)
+            if kind == "domain":
+                n = _entity_noun(f)
+                if n:
+                    c["entities"].add(n)
 
-    sig.sort(key=lambda c: (c["evidence_count"], c["churn"]), reverse=True)
-    return sig
+    # Files no import touches are still part of the repo; S1 places them so the
+    # strategy's coverage is comparable with the others'.
+    placed = {f for grp in clusters.values() for f in grp}
+    for c in named:
+        for k in LAYER_KEYS:
+            for f in c[k]:
+                if f not in placed:
+                    tgt = cands.setdefault(c["name"].lower(), _blank_candidate(c["module_dir"], c["name"]))
+                    tgt[k].append(f)
+    return _finish_candidates(cands, churn_map, "reference")
+
+
+# ── S3: persistence ────────────────────────────────────────────────────────
+# The only strategy whose output IS a domain model. Roots are derived by
+# OWNERSHIP rather than by folder: an entity that owns other entities' lifecycles
+# and is referred to from outside by id is an aggregate root, which is the
+# definition the model document needs anyway.
+
+EF_DBSET_RE = re.compile(r"DbSet\s*<\s*([A-Za-z_]\w*)\s*>")
+EF_TABLE_RE = re.compile(r"\[Table\s*\(\s*\"([^\"]+)\"")
+EF_COLLECTION_RE = re.compile(
+    r"(?:ICollection|IList|List|IEnumerable|HashSet|ISet)\s*<\s*([A-Za-z_]\w*)\s*>")
+EF_FK_RE = re.compile(r"^\s*public\s+[\w?<>]+\s+([A-Za-z_]\w*)Id\s*\{", re.M)
+CSHARP_CLASS_RE = re.compile(r"^\s*(?:public|internal)\s+(?:abstract\s+|sealed\s+|partial\s+)*class\s+([A-Za-z_]\w*)", re.M)
+JPA_ENTITY_RE = re.compile(r"@Entity\b")
+JPA_ONE_MANY_RE = re.compile(r"@OneToMany[\s\S]{0,200}?(?:ICollection|List|Set)\s*<\s*([A-Za-z_]\w*)\s*>")
+JPA_MANY_ONE_RE = re.compile(r"@ManyToOne[\s\S]{0,200}?(?:private|public|protected)\s+([A-Za-z_]\w*)\s+")
+JAVA_CLASS_RE = re.compile(r"^\s*(?:public\s+)?class\s+([A-Za-z_]\w*)", re.M)
+PRISMA_MODEL_RE = re.compile(r"^\s*model\s+([A-Za-z_]\w*)\s*\{([^}]*)\}", re.M)
+PRISMA_FIELD_RE = re.compile(r"^\s*(\w+)\s+([A-Za-z_]\w*)(\[\])?", re.M)
+SQL_TABLE_RE = re.compile(r"CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[`\"\[]?(\w+)", re.I)
+SQL_FK_RE = re.compile(r"REFERENCES\s+[`\"\[]?(\w+)", re.I)
+ORM_EVIDENCE_RE = re.compile(
+    r"(DbSet\s*<|@Entity\b|schema\.prisma$|\.prisma$|CREATE\s+TABLE|"
+    r"DbContext|JpaRepository|Migrations?/)", re.I)
+
+
+def _pascal_name(n):
+    return (n or "")[:1].upper() + (n or "")[1:]
+
+
+def persistence_entities(root, files):
+    """Parse the schema into {entity: {"owns": set, "refs": set, "files": set}}.
+
+    Four dialects, one shape. `owns` is a lifecycle edge (a collection navigation,
+    a one-to-many, a list relation, a foreign key pointing IN); `refs` is a
+    by-id reference that crosses an aggregate boundary without owning anything."""
+    ents = {}
+
+    def ent(name):
+        return ents.setdefault(_pascal_name(name),
+                               {"owns": set(), "refs": set(), "files": set()})
+
+    for f in files:
+        low = f.lower()
+        lang = _lang_of(f)
+        if lang not in ("cs", "java", "kt") and not low.endswith((".prisma", ".sql")):
+            continue
+        body = _read_source(root, f)
+        if not body:
+            continue
+
+        if low.endswith(".prisma"):
+            for m in PRISMA_MODEL_RE.finditer(body):
+                name, block = m.group(1), m.group(2)
+                e = ent(name)
+                e["files"].add(f)
+                for fm in PRISMA_FIELD_RE.finditer(block):
+                    typ, arr = fm.group(2), fm.group(3)
+                    if typ and typ[:1].isupper() and typ != name:
+                        (e["owns"] if arr else e["refs"]).add(_pascal_name(typ))
+        elif low.endswith(".sql"):
+            for m in SQL_TABLE_RE.finditer(body):
+                e = ent(singularize(m.group(1)))
+                e["files"].add(f)
+            tables = [singularize(m.group(1)) for m in SQL_TABLE_RE.finditer(body)]
+            if tables:
+                owner = ent(tables[0])
+                for m in SQL_FK_RE.finditer(body):
+                    tgt = _pascal_name(singularize(m.group(1)))
+                    if tgt != _pascal_name(tables[0]):
+                        ents[_pascal_name(tgt)] = ents.get(_pascal_name(tgt), {"owns": set(), "refs": set(), "files": set()})
+                        ents[_pascal_name(tgt)]["owns"].add(_pascal_name(tables[0]))
+                        owner["refs"].add(tgt)
+        elif lang == "cs":
+            for m in EF_DBSET_RE.finditer(body):
+                ent(m.group(1))["files"].add(f)
+            cls = CSHARP_CLASS_RE.search(body)
+            if cls and (EF_TABLE_RE.search(body) or EF_COLLECTION_RE.search(body)
+                        or EF_FK_RE.search(body) or DOMAIN_DIR_RE.search(f)):
+                e = ent(cls.group(1))
+                e["files"].add(f)
+                for m in EF_COLLECTION_RE.finditer(body):
+                    if m.group(1) != cls.group(1):
+                        e["owns"].add(_pascal_name(m.group(1)))
+                for m in EF_FK_RE.finditer(body):
+                    if m.group(1) != cls.group(1):
+                        e["refs"].add(_pascal_name(m.group(1)))
+        elif lang in ("java", "kt") and JPA_ENTITY_RE.search(body):
+            cls = JAVA_CLASS_RE.search(body)
+            if cls:
+                e = ent(cls.group(1))
+                e["files"].add(f)
+                for m in JPA_ONE_MANY_RE.finditer(body):
+                    e["owns"].add(_pascal_name(m.group(1)))
+                for m in JPA_MANY_ONE_RE.finditer(body):
+                    e["refs"].add(_pascal_name(m.group(1)))
+    return ents
+
+
+def strategy_persistence(root, files, churn_map, graph=None):
+    """S3 — derive roots from what the schema says owns what.
+
+    An entity owned by another entity is never a root; what is left owns at least
+    one lifecycle, or stands alone as its own. Each root's aggregate is its
+    transitive ownership closure, and the files of every entity in that closure."""
+    ents = persistence_entities(root, files)
+    if not ents:
+        return []
+
+    owned = {t for e in ents.values() for t in e["owns"] if t in ents}
+    roots = [n for n in sorted(ents) if n not in owned]
+
+    named = strategy_structure(root, files, churn_map)
+    owner = _candidate_of_file(named)
+    cands = {}
+    for r in roots:
+        closure, stack = set(), [r]
+        while stack:
+            n = stack.pop()
+            if n in closure or n not in ents:
+                continue
+            closure.add(n)
+            stack.extend(ents[n]["owns"])
+        member_files = {f for n in closure for f in ents[n]["files"]}
+        if not member_files:
+            continue
+        c = cands.setdefault(r.lower(), _blank_candidate(
+            os.path.commonprefix([os.path.dirname(f) + "/" for f in member_files]).rstrip("/"), r))
+        c["entities"] = set(closure)
+        c["owns"] = sorted(closure - {r})
+        c["references_by_id"] = sorted({t for n in closure for t in ents[n]["refs"]
+                                        if t in ents and t not in closure})
+        c["confidence"] = "high"
+        for f in sorted(member_files):
+            kind = next((_layer_of(p, soft=True) for p in f.split("/")[:-1]
+                         if _layer_of(p, soft=True)), "domain")
+            c[kind + "_files"].append(f)
+            c["churn"] += churn_map.get(f, 0)
+
+    # Application and API files that belong to a root's module still belong to
+    # its aggregate — the schema names the root, the structure says what serves it.
+    for c in named:
+        if c["name"].lower() in cands:
+            tgt = cands[c["name"].lower()]
+            for k in LAYER_KEYS:
+                tgt[k].extend(c[k])
+    return _finish_candidates(cands, churn_map, "persistence")
+
+
+# ── Availability + the probe ───────────────────────────────────────────────
+# A strategy that would return nothing must never be offered: an empty pick is
+# the zero-candidate hard stop at require_aggregates, arrived at by choice.
+
+STRATEGIES = {
+    "structure":   strategy_structure,
+    "reference":   strategy_reference,
+    "persistence": strategy_persistence,
+}
+
+
+def strategy_availability(root, files, graph_stats, ents_found):
+    """(name -> {available, reason}) — measured, never assumed."""
+    parseable = graph_stats.get("parseable_files", 0)
+    return {
+        "structure": {"available": True,
+                      "reason": "every repository has a layout"},
+        "reference": {"available": parseable >= 10,
+                      "reason": f"{parseable} import-parseable source file(s)"},
+        "persistence": {"available": ents_found > 0,
+                        "reason": f"{ents_found} ORM/schema entit(y/ies) found"},
+    }
+
+
+def run_probe(root, files, churn_map):
+    """Run every AVAILABLE strategy's clustering and report each one's own
+    numbers, so the pick is made against evidence rather than against a name.
+
+    Clustering is cheap; the expensive half is authoring, which still runs once
+    on the chosen result."""
+    graph, gstats = build_reference_graph(root, files)
+    ents = persistence_entities(root, files)
+    avail = strategy_availability(root, files, gstats, len(ents))
+    code_total = len([f for f in files if CODE_EXT_RE.search(f)])
+
+    results = {}
+    for name, fn in STRATEGIES.items():
+        if not avail[name]["available"]:
+            continue
+        cands = fn(root, files, churn_map, graph)
+        covered = {f for c in cands for f in c.get("covered_code", [])}
+        results[name] = {
+            "candidates": cands,
+            "count": len(cands),
+            "coverage_pct": round(100.0 * len(covered) / max(1, code_total), 1),
+            "singletons": sum(1 for c in cands if c.get("raw_file_count", 0) <= 1),
+            "available": True,
+            "reason": avail[name]["reason"],
+        }
+    return results, avail, graph, gstats, ents
+
+
+# Preference when the measurements tie. Structure leads because it is the layer
+# the other two are named by, so a tied structure result is the one an operator
+# can predict and re-derive by eye from the folder tree.
+STRATEGY_PREFERENCE = ("structure", "persistence", "reference")
+
+
+def choose_strategy(results):
+    """The non-interactive default: highest coverage, ties broken by fewest
+    singletons, then by the standing preference so a re-run of the same tree
+    picks the same strategy."""
+    if not results:
+        return ""
+    return sorted(results, key=lambda n: (-results[n]["coverage_pct"],
+                                          results[n]["singletons"],
+                                          STRATEGY_PREFERENCE.index(n)))[0]
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# PASS B — the seam overlay: what can be adopted, shipped and cut over together.
+#
+# Always runs, whichever Pass A strategy was chosen, because it is not a
+# validator of Pass A — it is the pass that answers the FEATURE question at all.
+# Reads application / API / UI only, never Domain, and emits signals rather than
+# decisions.
+#
+# Of the five identification tests, only three are computable: one cutover seam,
+# stable file ownership, one bounded context. "One business need" and
+# "independently demonstrable" are judgement, and this pass does not pretend to
+# them.
+# ═══════════════════════════════════════════════════════════════════════════
+
+ROUTE_ATTR_RE = re.compile(
+    r"""(?:\[Route\s*\(\s*["']([^"']+)|"""
+    r"""@(?:Request|Get|Post|Put|Delete|Patch)Mapping\s*\(\s*(?:value\s*=\s*)?["']([^"']+)|"""
+    r"""@(?:app|router)\.(?:get|post|put|delete|patch)\s*\(\s*["']([^"']+)|"""
+    r"""(?:app|router)\.(?:get|post|put|delete|patch)\s*\(\s*["']([^"']+)|"""
+    r"""Map(?:Get|Post|Put|Delete|Patch)\s*\(\s*["']([^"']+))""",
+    re.IGNORECASE)
+HANDLER_NAME_RE = re.compile(r"(Command|Query)Handler$|^Handle")
+
+
+def _route_family(path_literal):
+    """The first meaningful segment of a route — the family a cutover switches.
+
+    /api/v2/orders/{id}/lines -> orders. Version and api prefixes are carried by
+    every route in the service and separate nothing."""
+    parts = [p for p in re.split(r"[/\\]", (path_literal or "").strip("/"))
+             if p and not p.startswith(("{", ":", "[", "<"))]
+    for p in parts:
+        low = p.lower()
+        if low in ("api", "rest", "graphql", "v1", "v2", "v3", "internal", "public"):
+            continue
+        if re.fullmatch(r"v\d+", low):
+            continue
+        return singularize(p)
+    return ""
+
+
+def seam_overlay(root, files, candidates, churn_map, ui_attribution=None):
+    """Per-candidate seam signals. Two distinct route families on one aggregate
+    is the split candidate the feature proposal will surface with its evidence."""
+    owner = _candidate_of_file(candidates)
+    by_name = {c["name"]: c for c in candidates}
+    out = {c["name"]: {"route_families": {}, "command_groups": set(),
+                       "ui_segments": set(), "churn": 0, "api_files": 0}
+           for c in candidates}
+
+    for f in files:
+        name = owner.get(f)
+        if not name or name not in out:
+            continue
+        # Application / API / UI only. Domain files say what must stay
+        # consistent; they never say where traffic can be cut over.
+        kind = next((_layer_of(p, soft=True) for p in f.split("/")[:-1]
+                     if _layer_of(p, soft=True)), "other")
+        if kind == "domain":
+            continue
+        out[name]["churn"] += churn_map.get(f, 0)
+        stem = os.path.splitext(os.path.basename(f))[0]
+        if HANDLER_NAME_RE.search(stem):
+            out[name]["command_groups"].add(_entity_noun(f) or stem)
+        if not (_lang_of(f) or f.lower().endswith((".cshtml", ".razor"))):
+            continue
+        body = _read_source(root, f)
+        if not body:
+            continue
+        for m in ROUTE_ATTR_RE.finditer(body):
+            fam = _route_family(next((g for g in m.groups() if g), ""))
+            if fam:
+                out[name]["route_families"][fam] = out[name]["route_families"].get(fam, 0) + 1
+                out[name]["api_files"] += 1
+
+    for name, ui_files in (ui_attribution or {}).items():
+        if name in out:
+            for f in (ui_files if isinstance(ui_files, list) else []):
+                seg = _ui_stem(f) if callable(globals().get("_ui_stem")) else ""
+                if seg:
+                    out[name]["ui_segments"].add(seg)
+
+    for name, sig in out.items():
+        fams = sorted(sig["route_families"], key=sig["route_families"].get, reverse=True)
+        sig["route_families"] = fams[:CAP]
+        sig["command_groups"] = sorted(sig["command_groups"])[:CAP]
+        sig["ui_segments"] = sorted(sig["ui_segments"])[:CAP]
+        # Test 3 — one cutover seam. Two families means two places traffic could
+        # be switched, which is the evidence a split needs; it is not the
+        # decision to split, which stays with the operator.
+        sig["seam_count"] = len(fams)
+        sig["split_candidate"] = len(fams) >= 2
+        sig["seam"] = fams[0] if fams else ""
+        # Test 4 — stable file ownership. A candidate whose files are also
+        # claimed by another candidate cannot own its own cutover.
+        sig["owns_all_files"] = True
+        sig["evidence"] = ("route families: " + ", ".join(fams[:4])) if fams else \
+            ("command groups: " + ", ".join(sig["command_groups"][:4]) if sig["command_groups"]
+             else "no application/API surface found")
+    return out
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# PASS C — the feature proposal, and the bounded contexts above it.
+# ═══════════════════════════════════════════════════════════════════════════
+
+def _capability_name(aggregate, seam):
+    """Name a proposed split from the CAPABILITY, not from a second copy of the
+    noun: Patient + the `patient-merge` route family is PatientMerge, never
+    PatientPatient-merge. A seam that already leads with the aggregate's name
+    supplies the whole name on its own."""
+    words = [w for w in re.split(r"[^A-Za-z0-9]+", seam or "") if w]
+    pascal = "".join(_pascal_name(w) for w in words)
+    if not pascal:
+        return _pascal_name(aggregate)
+    if pascal.lower().startswith(aggregate.lower()):
+        return pascal
+    return _pascal_name(aggregate) + pascal
+
+
+def derive_contexts(candidates, files):
+    """Group candidates into bounded contexts, primed by the highest directory
+    level that actually separates them.
+
+    A context is a grouping of aggregates that share a model. The top-level
+    source directory is the best available prior — in a component monorepo those
+    directories ARE the contexts — and the operator confirms or rewrites it.
+    Where the tree has no such level, the whole repo is one context."""
+    def context_segment(path):
+        """The first path segment that separates one context from another."""
+        for part in (path or "").split("/"):
+            if not part or CONTAINER_DIR_RE.match(part):
+                continue
+            if DOTTED_SEG_RE.match(part):
+                bits = part.split(".")
+                return bits[1] if len(bits) > 2 else bits[0]
+            return part
+        return ""
+
+    groups = {}
+    for c in candidates:
+        # Voted across the candidate's own files rather than read off module_dir:
+        # a cluster drawn from the import graph spans directories, so its common
+        # prefix is often the repo root and would put every such cluster in one
+        # bucket regardless of where its code actually lives.
+        votes = {}
+        for k in LAYER_KEYS:
+            for f in c[k]:
+                seg = context_segment(f)
+                if seg:
+                    votes[seg] = votes.get(seg, 0) + 1
+        seg = max(sorted(votes), key=votes.get) if votes else context_segment(c.get("module_dir"))
+        groups.setdefault(_pascal_name(singularize(seg)) or "Core", []).append(c["name"])
+
+    # A context holding one aggregate in a repo that has several is usually the
+    # directory being incidental rather than a real model boundary; fold those
+    # together rather than proposing a context per aggregate.
+    if len(groups) > 1:
+        singles = [k for k, v in groups.items() if len(v) == 1]
+        if len(singles) > 1:
+            merged = []
+            for k in singles:
+                merged.extend(groups.pop(k))
+            groups.setdefault("Core", []).extend(merged)
+    return {k: sorted(v) for k, v in sorted(groups.items())}
+
+
+def dependency_waves(nodes, edges):
+    """Topological wave order over the module graph, with cycles trapped rather
+    than silently broken.
+
+    Wave 0 depends on nothing and can be onboarded first; each later wave
+    depends only on waves already placed. A cycle cannot be ordered, so it is
+    reported as one wave flagged for a seam decision instead of being cut
+    arbitrarily."""
+    remaining = set(nodes)
+    deps = {n: {d for d in edges.get(n, set()) if d in remaining and d != n}
+            for n in remaining}
+    waves, placed, cycles = [], set(), []
+    while remaining:
+        ready = sorted(n for n in remaining if deps[n] <= placed)
+        if not ready:
+            cycles.append(sorted(remaining))
+            waves.append({"wave": len(waves), "members": sorted(remaining), "cycle": True})
+            break
+        waves.append({"wave": len(waves), "members": ready, "cycle": False})
+        placed |= set(ready)
+        remaining -= set(ready)
+    return waves, cycles
+
+
+def propose_features(candidates, seams, edges, contexts):
+    """Default 1:1 — one aggregate, one feature, same name.
+
+    A split is PROPOSED where Pass B found two or more distinct seams on one
+    aggregate, carrying the evidence that suggested it, and is never applied:
+    the operator confirms it by editing the proposal. Where a split is taken the
+    feature is named from the capability, not from a second copy of the noun."""
+    ctx_of = {name: ctx for ctx, names in contexts.items() for name in names}
+    out = []
+    for c in candidates:
+        sig = seams.get(c["name"], {})
+        fams = sig.get("route_families", [])
+        feature = {
+            "feature": c["name"],
+            "aggregate": c["name"],
+            "context": ctx_of.get(c["name"], "Core"),
+            "files": c.get("raw_file_count", c.get("file_count", 0)),
+            "churn": c.get("churn", 0),
+            "seam": sig.get("seam", ""),
+            "seam_count": sig.get("seam_count", 0),
+            "evidence": sig.get("evidence", ""),
+            "depends_on": sorted(edges.get(c["name"], set())),
+            "split_proposed": [],
+        }
+        if sig.get("split_candidate"):
+            feature["split_proposed"] = [
+                {"feature": _capability_name(c["name"], f),
+                 "seam": f,
+                 "why": f"a second route family `{f}` cuts over independently of `{fams[0]}`"}
+                for f in fams[1:4]
+            ]
+        out.append(feature)
+    out.sort(key=lambda x: (x["context"], -x["files"], x["feature"]))
+    return out
+
+
+def aggregate_signals(files, churn_map):
+    """Derive CANDIDATE aggregate roots — the base unit the inventory and onboard
+    workflows turn into a specs/<Feature>/ slice.
+
+    Delegates to Pass A's structure strategy, which reads the repo's organising
+    axis (module-major, project-major, vertical slice, n-tier, or the build
+    manifest) instead of assuming one. Every caller of this function gets the
+    same candidate shape it always did, with the strategy's extra keys added.
+
+    Signals only — the workflow's agent draws the real boundaries. Empty for a
+    repo with no recognizable structure at all."""
+    return strategy_structure(None, files, churn_map)
 
 
 # A UI file wears its role in its NAME, and the vocabulary is not the backend's:
@@ -866,7 +1895,7 @@ def cmd_scan(args):
         "language_histogram": lang_hist,
         "top_level_dirs": top_level_dirs,
         **{k: v["items"] for k, v in cats.items()},
-        "aggregate_signals": signals,
+        "aggregate_signals": strip_internal(signals),
         "frontend_signals": fsig,
         # Which UI files serve which aggregate, and which serve none. The second half
         # matters as much as the first: `unattributed` is the shared shell, layout and
@@ -949,6 +1978,165 @@ def cmd_scan(args):
     return 0
 
 
+# The last-resort proposal document, used only when neither a project override nor
+# the kit's own template can be read. It is deliberately minimal: the tables ARE the
+# deliverable, and a scan that cannot find its template must still hand over a file
+# the operator can edit and `apply` can parse, rather than stopping.
+PROPOSAL_FALLBACK = """# Proposed Inventory
+
+**Repository:** `{root}`  ·  **Commit:** `{head}`  ·  **Generated:** {date}
+**Pass A strategy:** `{strategy}` — {reason}
+**Scanned:** {files} files, {code} source files  ·  **Coverage:** {coverage}%
+
+The boundary map for this codebase, and yours to change. Edit it, then run
+`/appweaver inventory apply` to validate the edits and regenerate the machine map
+onboard reads. The Aggregate column must name an aggregate the scan found;
+everything else is yours.
+
+## Strategy probe
+
+{probe_table}
+
+## Bounded Contexts
+
+{context_table}
+
+## Features
+
+{feature_table}
+{splits_section}{cycles_section}"""
+
+PROPOSAL_TEMPLATE_NAME = "proposed-inventory-template.md"
+
+
+def _proposal_template(root):
+    """The document shape, resolved the way every other template in this kit is:
+    a project override first, then the kit's own default, then the inline fallback.
+
+    Filled by SUBSTITUTION rather than str.format, because the values include
+    generated markdown tables whose cells come from the repository's own
+    identifiers — a feature or path carrying a brace would abort a format call.
+
+    A `<!-- TEMPLATE-NOTE … -->` block is guidance for whoever edits the template
+    and is removed here, so it never reaches the document an operator reads."""
+    for path in (os.path.join(root, ".appweaver", "templates", "overrides", PROPOSAL_TEMPLATE_NAME),
+                 os.path.join(HERE, "..", "..", "templates", PROPOSAL_TEMPLATE_NAME)):
+        try:
+            with open(os.path.abspath(path), encoding="utf-8") as fh:
+                text = fh.read()
+        except OSError:
+            continue
+        return re.sub(r"<!--\s*TEMPLATE-NOTE\b.*?-->\n?", "", text, flags=re.S)
+    return PROPOSAL_FALLBACK
+
+
+def _md_table(headers, rows):
+    out = ["| " + " | ".join(headers) + " |",
+           "|" + "|".join("---" for _ in headers) + "|"]
+    for r in rows:
+        out.append("| " + " | ".join("" if v is None else str(v) for v in r) + " |")
+    return "\n".join(out)
+
+
+def _parse_md_tables(text, section):
+    """Every table row under a `## <section>` heading, as lists of cell strings.
+
+    Header and separator rows are dropped, so a developer may reformat the table
+    (add spacing, reorder nothing) without breaking the parse."""
+    lines, rows, inside = text.splitlines(), [], False
+    for line in lines:
+        if line.startswith("## "):
+            inside = line[3:].strip().lower().startswith(section.lower())
+            continue
+        if not inside:
+            continue
+        s = line.strip()
+        if not s.startswith("|"):
+            continue
+        cells = [c.strip() for c in s.strip("|").split("|")]
+        if not cells or all(set(c) <= set("-: ") for c in cells):
+            continue
+        rows.append(cells)
+    return rows
+
+
+def _write_proposal(path, meta, contexts, features, waves, cycles, probe_rows):
+    ctx_files, ctx_deps = {}, {}
+    fmap = {f["feature"]: f for f in features}
+    for f in features:
+        ctx_files[f["context"]] = ctx_files.get(f["context"], 0) + f["files"]
+        for d in f["depends_on"]:
+            dctx = fmap.get(d, {}).get("context")
+            if dctx and dctx != f["context"]:
+                ctx_deps.setdefault(f["context"], set()).add(dctx)
+
+    wave_of = {m: w["wave"] for w in waves for m in w["members"]}
+    ctx_wave = {}
+    for f in features:
+        ctx_wave[f["context"]] = min(ctx_wave.get(f["context"], 99),
+                                     wave_of.get(f["feature"], 99))
+
+    context_table = _md_table(
+        ["Order", "Bounded Context", "Depends On", "Features", "Files"],
+        [[i + 1, ctx, ", ".join(sorted(ctx_deps.get(ctx, set()))) or "—",
+          len(names), ctx_files.get(ctx, 0)]
+         for i, (ctx, names) in enumerate(
+             sorted(contexts.items(), key=lambda kv: (ctx_wave.get(kv[0], 99), kv[0])))
+         if names])
+
+    rows = []
+    for f in sorted(features, key=lambda x: (wave_of.get(x["feature"], 99),
+                                             x["context"], x["feature"])):
+        rows.append([f["feature"], f["context"], f["aggregate"],
+                     wave_of.get(f["feature"], "?"),
+                     ", ".join(f["depends_on"]) or "—",
+                     f["files"], f["churn"], f["seam"] or "—"])
+    feature_table = _md_table(
+        ["Feature", "Bounded Context", "Aggregate", "Wave", "Depends On",
+         "Files", "Churn", "Seam"], rows)
+
+    # Both trailing sections are conditional and carry their own leading blank line,
+    # so the template can sit them side by side and neither leaves a gap when absent.
+    splits = [f for f in features if f["split_proposed"]]
+    splits_section = ""
+    if splits:
+        splits_section = (
+            "\n## Proposed splits\n\n"
+            "Pass B found more than one cutover seam on these aggregates. "
+            "**Nothing here is applied.** To take a split, add its row to the "
+            "Features table above with the same Aggregate.\n\n"
+            + _md_table(["Aggregate", "Suggested feature", "Seam", "Why"],
+                        [[f["aggregate"], s["feature"], s["seam"], s["why"]]
+                         for f in splits for s in f["split_proposed"]]) + "\n")
+
+    cycles_section = ""
+    if cycles:
+        cycles_section = (
+            "\n## Dependency cycles\n\n"
+            "These features depend on each other and cannot be ordered. Break the "
+            "cycle by introducing a seam, or accept them as one onboarding unit by "
+            "merging them in the Features table.\n\n"
+            + "\n".join(f"- {' → '.join(c)} → {c[0]}" for c in cycles) + "\n")
+
+    values = dict(meta)
+    values.update({
+        "probe_table": _md_table(
+            ["Strategy", "Features", "Coverage", "Singletons", "Chosen", "Availability"],
+            probe_rows),
+        "context_table": context_table,
+        "feature_table": feature_table,
+        "splits_section": splits_section,
+        "cycles_section": cycles_section,
+    })
+    text = _proposal_template(meta["root"])
+    for k, v in values.items():
+        text = text.replace("{" + k + "}", str(v))
+
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(text.rstrip("\n") + "\n")
+
+
 def _slug(s):
     return re.sub(r"-+", "-", re.sub(r"[^a-z0-9]+", "-", (s or "").lower())).strip("-")
 
@@ -989,6 +2177,482 @@ def _read_frontmatter(path):
     return data
 
 
+def cmd_propose(args):
+    """Pass A + B + C over the repo: write the editable boundary map, and the
+    machine map onboard reads until the operator edits the first one."""
+    root = os.path.abspath(args.root or os.getcwd())
+    files = list_files(root, load_config_excludes(args.config))
+    be_files, fe_files, svc_prefix, ui_prefix = scope_to_lanes(
+        files, args.service_root, args.ui_root)
+    churn_list, _ = churn(root, load_config_excludes(args.config))
+    churn_map = {c["file"]: c["commits"] for c in churn_list}
+
+    results, avail, graph, gstats, ents = run_probe(root, be_files, churn_map)
+    # The menu hands back the whole option line, numbers and all, so the first
+    # token is the strategy and the rest is what the operator was shown.
+    wanted = (args.strategy or "").strip().split()[0].strip("`*_-").lower() if args.strategy else ""
+    if wanted:
+        if wanted not in results:
+            reason = avail.get(wanted, {}).get("reason", "not a known strategy")
+            print(json.dumps({"ok": "false", "error":
+                              f"strategy '{wanted}' is not available here — {reason}"}))
+            return 1
+        picked = wanted
+    else:
+        picked = choose_strategy(results)
+    if not picked:
+        print(json.dumps({"ok": "false", "feature_count": 0, "error":
+                          "no Pass A strategy produced candidates"}))
+        return 1
+
+    candidates = results[picked]["candidates"]
+    edges = candidate_edges(candidates, graph)
+    seams = seam_overlay(root, be_files, candidates, churn_map)
+    contexts = derive_contexts(candidates, be_files)
+    features = propose_features(candidates, seams, edges, contexts)
+    waves, cycles = dependency_waves([f["feature"] for f in features],
+                                     {f["feature"]: set(f["depends_on"]) for f in features})
+
+    md = os.path.abspath(args.out) if args.out else os.path.join(root, "specs", "proposed-inventory.md")
+    mp = os.path.abspath(args.map) if args.map else os.path.join(root, ".appweaver", "inventory", "feature-map.json")
+    code_total = len([f for f in be_files if CODE_EXT_RE.search(f)])
+    meta = {"root": root, "head": git(root, "rev-parse", "--short", "HEAD") or "-",
+            "date": datetime.date.today().isoformat(), "strategy": picked,
+            "reason": results[picked]["reason"], "files": len(files),
+            "code": code_total, "coverage": results[picked]["coverage_pct"]}
+    probe_rows = [[n, results[n]["count"], f"{results[n]['coverage_pct']}%",
+                   results[n]["singletons"], "**yes**" if n == picked else "",
+                   results[n]["reason"]] if n in results else
+                  [n, "—", "—", "—", "", f"unavailable — {avail[n]['reason']}"]
+                  for n in STRATEGY_PREFERENCE]
+    _write_proposal(md, meta, contexts, features, waves, cycles, probe_rows)
+    _write_feature_map(mp, meta, contexts, features, waves, cycles, results, avail, gstats)
+
+    print(f"Proposed inventory written to {md}", file=sys.stderr)
+    print(f"  strategy: {picked}  features: {len(features)}  "
+          f"contexts: {len(contexts)}  waves: {len(waves)}", file=sys.stderr)
+    print(json.dumps({
+        "ok": "true", "proposal_md": md, "feature_map": mp, "root": root,
+        "strategy": picked, "feature_count": len(features),
+        "context_count": len(contexts), "wave_count": len(waves),
+        "cycle_count": len(cycles),
+        "contexts_ordered": ", ".join(_ordered_contexts(contexts, features, waves)),
+        "coverage_pct": results[picked]["coverage_pct"],
+        "split_candidates": sum(1 for f in features if f["split_proposed"]),
+        # One option line per AVAILABLE strategy, each carrying its own numbers so
+        # the pick is made against evidence. A strategy that would return nothing
+        # is never offered — an empty pick is the zero-candidate stop by choice.
+        "strategy_options": [
+            f"{n} — {results[n]['count']} features, {results[n]['coverage_pct']}% coverage, "
+            f"{results[n]['singletons']} singleton(s)"
+            + ("  [owns/references available]" if n == "persistence" else "")
+            for n in STRATEGY_PREFERENCE if n in results
+        ],
+    }))
+    return 0
+
+
+def _ordered_contexts(contexts, features, waves):
+    wave_of = {m: w["wave"] for w in waves for m in w["members"]}
+    first = {}
+    for f in features:
+        first[f["context"]] = min(first.get(f["context"], 99),
+                                  wave_of.get(f["feature"], 99))
+    return [c for c in sorted(contexts, key=lambda c: (first.get(c, 99), c)) if contexts[c]]
+
+
+def _write_feature_map(path, meta, contexts, features, waves, cycles,
+                       results=None, avail=None, gstats=None, aggregates=None):
+    """The machine contract onboard reads. Regenerated from the markdown on every
+    apply, so the document stays the thing a person edits and this stays derived.
+    `aggregates` is the registry of aggregates the scan found — what the Aggregate
+    column may name — and outlives any feature that stops listing one."""
+    registry = aggregates if aggregates is not None else sorted(
+        {a for f in features for a in (f.get("aggregates") or [f.get("aggregate")]) if a})
+    payload = {
+        "version": "1",
+        "generated": meta["date"],
+        "root": meta["root"],
+        "commit": meta["head"],
+        "strategy": meta["strategy"],
+        "contexts": [
+            {"name": c, "order": i,
+             "features": [f["feature"] for f in features if f["context"] == c],
+             "onboarded": False}
+            for i, c in enumerate(_ordered_contexts(contexts, features, waves))
+        ],
+        "features": features,
+        "aggregates": registry,
+        "waves": waves,
+        "cycles": cycles,
+    }
+    if results is not None:
+        payload["probe"] = {
+            n: {"count": results[n]["count"], "coverage_pct": results[n]["coverage_pct"],
+                "singletons": results[n]["singletons"], "available": True}
+            for n in results}
+        for n, a in (avail or {}).items():
+            payload["probe"].setdefault(n, {"available": False, "reason": a["reason"]})
+        payload["reference_graph"] = gstats or {}
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(payload, fh, indent=2)
+
+
+def cmd_apply(args):
+    """Parse the edited proposal back into the machine map, validating every
+    edit and naming the row that failed rather than guessing at intent."""
+    root = os.path.abspath(args.root or os.getcwd())
+    md = os.path.abspath(args.proposal) if args.proposal else os.path.join(root, "specs", "proposed-inventory.md")
+    mp = os.path.abspath(args.map) if args.map else os.path.join(root, ".appweaver", "inventory", "feature-map.json")
+    if not os.path.isfile(md):
+        print(json.dumps({"ok": "false", "error":
+                          f"no proposal at {md} — run /appweaver inventory first"}))
+        return 1
+    prior = {}
+    if os.path.isfile(mp):
+        try:
+            prior = json.load(open(mp, encoding="utf-8"))
+        except Exception:
+            prior = {}
+    # The aggregates the SCAN found, carried forward on every apply. Deriving them from the
+    # features alone forgets an aggregate the moment no feature lists it first: merge
+    # Inventory into Checkout and the next apply of the same file rejects Inventory.
+    known_aggs = set(prior.get("aggregates") or [])
+    for f in prior.get("features", []):
+        known_aggs.update(a for a in [f.get("aggregate")] + list(f.get("aggregates") or []) if a)
+
+    text = open(md, encoding="utf-8").read()
+    rows = _parse_md_tables(text, "Features")
+    problems, features, seen = [], [], {}
+    prior_by_feature = {f["feature"]: f for f in prior.get("features", [])}
+    prior_by_agg = {}
+    for f in prior.get("features", []):
+        prior_by_agg.setdefault(f["aggregate"], f)
+
+    for cells in rows:
+        if len(cells) < 3 or cells[0].lower() in ("feature", ""):
+            continue
+        name, ctx, agg = cells[0], cells[1], cells[2]
+        deps = [d.strip() for d in re.split(r"[,;]", cells[4]) if d.strip() and d.strip() != "—"] \
+            if len(cells) > 4 else []
+        if not name or not ctx or not agg:
+            problems.append(f"row '{' | '.join(cells[:3])}' is missing a Feature, "
+                            f"Bounded Context or Aggregate value")
+            continue
+        if known_aggs and agg not in known_aggs:
+            problems.append(f"feature '{name}' names aggregate '{agg}', which the scan "
+                            f"did not find — use one of: {', '.join(sorted(known_aggs)[:8])}…")
+            continue
+        base = prior_by_feature.get(name) or prior_by_agg.get(agg) or {}
+        if name in seen:
+            # Same feature twice is ONE feature over several aggregates: combine them, the
+            # first row's aggregate first — that order is which concept its files land on.
+            # A feature lives in one context, so a second row naming another one is a
+            # contradiction to report rather than a choice to guess at.
+            prev = seen[name]
+            if prev["context"] != ctx:
+                problems.append(f"feature '{name}' is placed in both '{prev['context']}' "
+                                f"and '{ctx}' — a feature lives in exactly one bounded context")
+                continue
+            if agg not in prev["aggregates"]:
+                prev["aggregates"].append(agg)
+            prev["depends_on"] += [d for d in deps if d not in prev["depends_on"]]
+            continue
+        # The aggregates are what THIS file says, never what the previous map said: a row
+        # removed here has to leave the feature, and a base borrowed from another feature
+        # over the same aggregate must not hand this one its aggregate list.
+        entry = dict(base)
+        entry.update({"feature": name, "context": ctx, "aggregate": agg,
+                      "aggregates": [agg], "depends_on": deps})
+        entry.setdefault("files", 0)
+        entry.setdefault("churn", 0)
+        entry.setdefault("seam", "")
+        entry.setdefault("split_proposed", [])
+        seen[name] = entry
+        features.append(entry)
+
+    if not features:
+        problems.append("the Features table has no data rows — every feature would "
+                        "be dropped, which would leave onboard nothing to do")
+
+    names = {f["feature"] for f in features}
+    for f in features:
+        missing = [d for d in f["depends_on"] if d not in names]
+        if missing:
+            problems.append(f"feature '{f['feature']}' depends on {', '.join(missing)}, "
+                            f"which is not a feature in this file")
+        f["depends_on"] = [d for d in f["depends_on"] if d in names]
+
+    if problems:
+        for p in problems:
+            print(f"  ! {p}", file=sys.stderr)
+        print(json.dumps({"ok": "false", "problem_count": len(problems),
+                          "problems": " · ".join(problems[:6]),
+                          "feature_count": len(features)}))
+        return 1
+
+    contexts = {}
+    for f in features:
+        contexts.setdefault(f["context"], []).append(f["feature"])
+    waves, cycles = dependency_waves([f["feature"] for f in features],
+                                     {f["feature"]: set(f["depends_on"]) for f in features})
+    meta = {"date": datetime.date.today().isoformat(), "root": root,
+            "head": prior.get("commit", "-"), "strategy": prior.get("strategy", "edited")}
+    _write_feature_map(mp, meta, contexts, features, waves, cycles,
+                       aggregates=sorted(known_aggs) or None)
+
+    print(f"Applied {md} -> {mp}", file=sys.stderr)
+    print(f"  {len(features)} feature(s) across {len(contexts)} context(s), "
+          f"{len(waves)} wave(s){', CYCLES PRESENT' if cycles else ''}", file=sys.stderr)
+    print(json.dumps({
+        "ok": "true", "feature_map": mp, "feature_count": len(features),
+        "context_count": len(contexts), "wave_count": len(waves),
+        "cycle_count": len(cycles),
+        "contexts_ordered": ", ".join(_ordered_contexts(contexts, features, waves)),
+    }))
+    return 0
+
+
+def cmd_context_state(args):
+    """What onboard needs to know before it touches a bounded context: is this a
+    context the map knows, what does it hold, has it been onboarded already, and
+    is everything it depends on onboarded first.
+
+    This is what makes `onboard <Context>` repeatable. The bundle-wide curation
+    guard cannot answer it — a bundle holding context 1's concepts looks
+    identical to a bundle that must not be overwritten, and stopping on that is
+    what made onboarding a second context impossible."""
+    root = os.path.abspath(args.root or os.getcwd())
+    mp = os.path.abspath(args.map) if args.map else os.path.join(root, ".appweaver", "inventory", "feature-map.json")
+    bundle = os.path.abspath(args.bundle) if args.bundle else os.path.join(root, "knowledge")
+    if not os.path.isfile(mp):
+        print(json.dumps({"ok": "false", "map_present": "false", "error":
+                          f"no feature map at {mp} — run /appweaver inventory, edit "
+                          f"specs/proposed-inventory.md, then /appweaver inventory apply"}))
+        return 1
+    try:
+        m = json.load(open(mp, encoding="utf-8"))
+    except Exception as e:
+        print(json.dumps({"ok": "false", "map_present": "true",
+                          "error": f"feature map at {mp} is not readable JSON: {e}"}))
+        return 1
+
+    contexts = m.get("contexts", [])
+    ordered = [c["name"] for c in contexts]
+    want = (args.context or "").strip()
+    match = next((c for c in contexts if c["name"].lower() == want.lower()), None)
+    if want and not match:
+        print(json.dumps({"ok": "false", "map_present": "true", "context_known": "false",
+                          "contexts_ordered": ", ".join(ordered),
+                          "error": f"'{want}' is not a bounded context in the map — "
+                                   f"pick one of: {', '.join(ordered)}"}))
+        return 1
+
+    # Which concepts the bundle already holds, so "onboarded" is read off the
+    # artefacts rather than off a flag that can drift from them.
+    # Matched hyphen-insensitively, the way cmd_concept resolves a PascalCase
+    # name onto a bundle file: the map says `PatientRegistration` and the bundle
+    # holds `patient-registration.md`, and comparing the slugs directly would
+    # read every onboarded context as still open.
+    def key(n):
+        return re.sub(r"[^a-z0-9]", "", (n or "").lower())
+
+    present = set()
+    agg_dir = os.path.join(bundle, "aggregates")
+    if os.path.isdir(agg_dir):
+        for fn in os.listdir(agg_dir):
+            if fn.endswith(".md") and fn != "index.md":
+                present.add(key(os.path.splitext(fn)[0]))
+
+    # A context is onboarded when every AGGREGATE its features act on has a concept. The
+    # bundle is the project's knowledge and a concept is an aggregate: a context whose map
+    # splits Patient into PatientRegistration and PatientMerge is done once Patient's
+    # concept exists, and never holds a concept per capability.
+    aggs_of = {}
+    for f in m.get("features", []):
+        aggs_of[f["feature"]] = (f.get("aggregates")
+                                 or ([f["aggregate"]] if f.get("aggregate") else [f["feature"]]))
+
+    def ctx_aggs(ctx):
+        out = []
+        for f in ctx.get("features", []):
+            for a in aggs_of.get(f, [f]):
+                if a not in out:
+                    out.append(a)
+        return out
+
+    def done(ctx):
+        aggs = ctx_aggs(ctx)
+        return bool(aggs) and all(key(a) in present for a in aggs)
+
+    onboarded = [c["name"] for c in contexts if done(c)]
+    remaining = [c["name"] for c in contexts if not done(c)]
+    target = match or next((c for c in contexts if not done(c)), None)
+    if not target:
+        print(json.dumps({"ok": "false", "map_present": "true", "context_known": "true",
+                          "all_onboarded": "true", "contexts_ordered": ", ".join(ordered),
+                          "error": "every bounded context in the map is already onboarded"}))
+        return 1
+
+    feats = target.get("features", [])
+    t_aggs = ctx_aggs(target)
+    missing_aggs = [a for a in t_aggs if key(a) not in present]
+    missing = [f for f in feats if any(key(a) not in present for a in aggs_of.get(f, [f]))]
+    # Blocked by the contexts this one actually DEPENDS on, not by every context
+    # that happens to sort earlier. Most contexts in a wave are independent of
+    # each other, and blocking on display order would serialise work that can be
+    # done in any order — the map says which edges are real.
+    ctx_of = {f["feature"]: f["context"] for f in m.get("features", [])}
+    needs = set()
+    for f in m.get("features", []):
+        if f.get("context") != target["name"]:
+            continue
+        for d in f.get("depends_on", []):
+            dctx = ctx_of.get(d)
+            if dctx and dctx != target["name"]:
+                needs.add(dctx)
+    blocking = [n for n in ordered if n in needs and n not in onboarded]
+
+    # A context inside a dependency cycle can never clear its blockers, because
+    # each is waiting on the other. Reporting that as "blocked" would deadlock
+    # the sequence, so a cycle member is released with the cycle named: the
+    # operator either breaks the seam or onboards the ring as one unit.
+    ctx_needs = {}
+    for f in m.get("features", []):
+        src = f.get("context")
+        for d in f.get("depends_on", []):
+            dctx = ctx_of.get(d)
+            if src and dctx and dctx != src:
+                ctx_needs.setdefault(src, set()).add(dctx)
+    ring, stack, seen_ctx = set(), list(needs), set()
+    while stack:
+        n = stack.pop()
+        if n in seen_ctx:
+            continue
+        seen_ctx.add(n)
+        if target["name"] in ctx_needs.get(n, set()):
+            ring.add(n)
+        stack.extend(ctx_needs.get(n, set()))
+    if ring:
+        blocking = [n for n in blocking if n not in ring]
+
+    print(f"Context {target['name']}: {len(feats)} feature(s) over {len(t_aggs)} "
+          f"aggregate(s), {len(missing_aggs)} aggregate(s) without a concept", file=sys.stderr)
+    print(json.dumps({
+        "ok": "true", "map_present": "true", "context_known": "true",
+        "context": target["name"], "context_slug": _slug(target["name"]),
+        "feature_count": len(feats), "features": ", ".join(feats),
+        "aggregate_count": len(t_aggs), "aggregates": ", ".join(t_aggs),
+        "feature_aggregates": "; ".join(f"{f} → {', '.join(aggs_of.get(f, [f]))}" for f in feats),
+        "pending_count": len(missing), "pending_features": ", ".join(missing),
+        "pending_aggregates": ", ".join(missing_aggs),
+        "already_onboarded": "true" if not missing_aggs else "false",
+        "blocked_by": ", ".join(blocking),
+        "is_blocked": "true" if blocking else "false",
+        "in_cycle": "true" if ring else "false",
+        "cycle_with": ", ".join(sorted(ring)),
+        "is_first": "true" if not onboarded else "false",
+        "onboarded_contexts": ", ".join(onboarded),
+        "remaining_contexts": ", ".join(remaining),
+        "contexts_ordered": ", ".join(ordered),
+        "context_count": len(contexts),
+        "feature_map": mp,
+        "strategy": m.get("strategy", ""),
+    }))
+    return 0
+
+
+def cmd_scaffold_context(args):
+    """Create the SPECS directories one bounded context's features will live in:
+    specs/<Context>/<Feature>/ for every feature the map assigns to it.
+
+    onboard writes a context's OKF concepts, and until now that was the only
+    trace a run left under a name a person could pick. select-feature merges the
+    bundle's aggregates into its list precisely to cover that gap, but a feature
+    that exists only as a concept has nowhere for `specify` or `adopt` to put a
+    document, and `list-contexts` — which reads the tree, not the bundle —
+    reports the context as holding nothing. Creating the directories at onboard
+    makes the context's shape visible in the one place every later command looks.
+
+    EMPTY DIRECTORIES ON PURPOSE. No spec.md and no domain-model.md: adopt
+    reverse-engineers the first and specify authors the second, and a placeholder
+    for either reads as "the document exists" to every gate downstream. The
+    directory says the feature is KNOWN; the documents say it is described.
+
+    Names are normalised the way set-feature and set-context normalise them
+    (PascalCase, non-alphanumerics dropped), so a hand-edited "order management"
+    row in the proposal and a later `select-feature OrderManagement` resolve to
+    one directory rather than two."""
+    root = os.path.abspath(args.root or os.getcwd())
+    mp = os.path.abspath(args.map) if args.map else os.path.join(root, ".appweaver", "inventory", "feature-map.json")
+    if not os.path.isfile(mp):
+        print(json.dumps({"ok": "false", "error":
+                          f"no feature map at {mp} — run /appweaver inventory apply first"}))
+        return 1
+    try:
+        m = json.load(open(mp, encoding="utf-8"))
+    except Exception as e:
+        print(json.dumps({"ok": "false", "error": f"feature map at {mp} is not readable JSON: {e}"}))
+        return 1
+
+    want = (args.context or "").strip()
+    contexts = m.get("contexts", [])
+    match = next((c for c in contexts if c["name"].lower() == want.lower()), None)
+    if not match:
+        print(json.dumps({"ok": "false", "error":
+                          f"'{want}' is not a bounded context in {mp} — one of: "
+                          f"{', '.join(c['name'] for c in contexts)}"}))
+        return 1
+
+    ctx = _pascal(match["name"])
+    ctx_dir = os.path.join(root, "specs", ctx)
+    # The same refusal set-context makes. specs/<Name>/spec.md means that name is
+    # already a FEATURE in the flat pre-context layout, and nesting this context's
+    # features under it would put them inside a directory another spec claims.
+    if os.path.isfile(os.path.join(ctx_dir, "spec.md")):
+        print(json.dumps({"ok": "false", "error":
+                          f"specs/{ctx} is a feature (it has its own spec.md), not a "
+                          f"bounded context — rename the context in "
+                          f"specs/proposed-inventory.md and re-run /appweaver inventory apply"}))
+        return 1
+
+    created, existed, rejected = [], [], []
+    os.makedirs(ctx_dir, exist_ok=True)
+    for raw in match.get("features", []):
+        name = _pascal(raw)
+        if not re.match(r"^[A-Za-z][A-Za-z0-9]*$", name):
+            rejected.append(raw)
+            continue
+        d = os.path.join(ctx_dir, name)
+        if os.path.isdir(d):
+            existed.append(name)
+        else:
+            os.makedirs(d)
+            created.append(name)
+
+    rel = "specs/" + ctx
+    print(f"Scaffolded {rel}/: {len(created)} created, {len(existed)} already there"
+          + (f", {len(rejected)} rejected" if rejected else ""), file=sys.stderr)
+    print(json.dumps({
+        "ok": "true",
+        "context": ctx,
+        "context_dir": rel,
+        "created": ", ".join(created),
+        "created_count": len(created),
+        "existed": ", ".join(existed),
+        "existed_count": len(existed),
+        "rejected": ", ".join(rejected),
+        "rejected_count": len(rejected),
+        # A separate boolean because the engine's conditions compare one variable
+        # against one literal and cannot ask whether a string is empty.
+        "rejected_present": "true" if rejected else "false",
+        "feature_dirs": ", ".join(f"{rel}/{n}" for n in created + existed),
+        "feature_count": len(created) + len(existed),
+    }))
+    return 0
+
+
 def cmd_concept(args):
     """Resolve the OKF bundle concept for an aggregate → its path + source_files
     (the code that IS the slice). The index adopt reverse-engineers spec.md, the
@@ -1057,9 +2721,18 @@ def cmd_list_aggregates(args):
     set-feature would create), its title/concept_path, and source_file_count. The
     caller merges these with the specs/ list, deduping by name (case-insensitive).
     Empty {aggregates:[], count:0} on a greenfield repo (no bundle) — a no-op there.
+
+    SCOPED BY BOUNDED CONTEXT when `--context` names one. onboard runs once per
+    context and stamps every concept it writes `bounded_context:`, so a bundle
+    that has seen two runs holds two contexts' aggregates. Without the filter,
+    select-feature standing inside one context offers the other's features and
+    would scaffold them into the wrong tree. A concept carrying NO stamp is kept
+    whatever the filter says — that is a bundle written before the key existed,
+    and hiding those features would be a worse failure than listing them.
     """
     bundle = os.path.abspath(args.bundle)
     present = os.path.isdir(bundle)
+    want_ctx = re.sub(r"[^a-z0-9]", "", (getattr(args, "context", "") or "").lower())
     by_name = {}
     if present:
         for dirpath, dirnames, filenames in os.walk(bundle):
@@ -1078,12 +2751,20 @@ def cmd_list_aggregates(args):
                 if not name:
                     continue
                 sf = [s for s in (fm.get("source_files") or []) if isinstance(s, str) and s.strip()]
+                bc = fm.get("bounded_context") if isinstance(fm.get("bounded_context"), str) else ""
+                if want_ctx and bc and re.sub(r"[^a-z0-9]", "", bc.lower()) != want_ctx:
+                    continue
+                listed = [s for s in (fm.get("features") or []) if isinstance(s, str) and s.strip()] \
+                    if isinstance(fm.get("features"), list) else []
                 cand = {
                     "name": name,
                     "title": title or base,
                     "slug": _slug(name),
                     "concept_path": os.path.relpath(path, os.getcwd()),
                     "type": typ,
+                    "bounded_context": bc,
+                    "origin": fm.get("origin") if isinstance(fm.get("origin"), str) else "",
+                    "features": listed,
                     "source_file_count": len(sf),
                 }
                 # Dedup by the case-insensitive feature name; a filename-slug match
@@ -1094,11 +2775,55 @@ def cmd_list_aggregates(args):
                     (_slug(base) == cand["slug"]) or cand["source_file_count"] > prev["source_file_count"]):
                     by_name[key] = cand
     aggs = sorted(by_name.values(), key=lambda a: a["name"].lower())
+
+    # WHAT A PERSON PICKS IS A FEATURE, and the bundle's concepts are AGGREGATES. The two
+    # coincide on a 1:1 map and differ where the map split an aggregate into capabilities:
+    # offering Patient beside PatientRegistration and PatientMerge would let select-feature
+    # scaffold a feature nobody defined. Each concept is offered as the features the
+    # confirmed map puts on it — within the scoped context, when there is one — and as
+    # itself only where no map names any, which is every concept on a greenfield repo.
+    k = lambda s: re.sub(r"[^a-z0-9]", "", (s or "").lower())
+    root = os.path.abspath(args.root) if getattr(args, "root", "") else os.getcwd()
+    mp = getattr(args, "map", "") or os.path.join(root, ".appweaver", "inventory", "feature-map.json")
+    feats_on = {}
+    try:
+        with open(mp, encoding="utf-8") as fh:
+            mapped = json.load(fh).get("features") or []
+    except (OSError, ValueError):
+        mapped = []
+    for f in mapped:
+        if want_ctx and k(f.get("context")) != want_ctx:
+            continue
+        for a in (f.get("aggregates") or [f.get("aggregate")]):
+            if a:
+                feats_on.setdefault(k(a), []).append(_pascal(f.get("feature", "")))
+    # Without a map entry, the concept's own `features:` list names them. A concept that a
+    # greenfield `implement` wrote offers nothing: every feature that acts on it already
+    # has its specs/ directory, and the concept's name is an aggregate, not a feature
+    # anyone defined. Only a pre-map brownfield concept still falls back to its own name.
+    def offered(a):
+        if feats_on.get(k(a["name"])):
+            return feats_on[k(a["name"])]
+        if (a.get("origin") or "").lower() == "greenfield":
+            return []
+        return [_pascal(f) for f in a.get("features") or []] or [a["name"]]
+
+    pickable, seen_pick = [], set()
+    for a in aggs:
+        for name in offered(a):
+            if name and name.lower() not in seen_pick:
+                seen_pick.add(name.lower())
+                pickable.append({"name": name, "aggregate": a["name"],
+                                 "concept_path": a["concept_path"]})
+
     print(f"OKF aggregates in {args.bundle}: {len(aggs)} "
-          f"({', '.join(a['name'] for a in aggs) or '-'})", file=sys.stderr)
+          f"({', '.join(a['name'] for a in aggs) or '-'}); pickable features: "
+          f"{', '.join(p['name'] for p in pickable) or '-'}", file=sys.stderr)
     print(json.dumps({
         "aggregates": aggs, "count": len(aggs),
+        "pickable": pickable, "pickable_count": len(pickable),
         "bundle": args.bundle, "bundle_present": "true" if present else "false",
+        "context": getattr(args, "context", "") or "",
     }))
     return 0
 
@@ -1159,6 +2884,40 @@ def main():
                          "so neither lane's substrate carries the other's files.")
     ps.set_defaults(func=cmd_scan)
 
+    pp = sub.add_parser("propose", help="Pass A+B+C: write the editable Feature / Bounded Context map.")
+    pp.add_argument("--root", help="Codebase to scan (default: CWD).")
+    pp.add_argument("--config", help="okf-config.yml whose exclude: list is honored.")
+    pp.add_argument("--service-root", dest="service_root", default="",
+                    help="The service lane's declared source path.")
+    pp.add_argument("--ui-root", dest="ui_root", default="",
+                    help="The UI lane's declared source path.")
+    pp.add_argument("--strategy", default="",
+                    help="Pass A strategy: structure | reference | persistence. "
+                         "Default: the highest-coverage AVAILABLE strategy, ties "
+                         "broken by fewest singletons.")
+    pp.add_argument("--out", help="Proposal markdown (default: <root>/specs/proposed-inventory.md).")
+    pp.add_argument("--map", help="Machine map (default: <root>/.appweaver/inventory/feature-map.json).")
+    pp.set_defaults(func=cmd_propose)
+
+    pa = sub.add_parser("apply", help="Validate the edited proposal and regenerate the machine map.")
+    pa.add_argument("--root", help="Codebase root (default: CWD).")
+    pa.add_argument("--proposal", help="Proposal markdown (default: <root>/specs/proposed-inventory.md).")
+    pa.add_argument("--map", help="Machine map to write (default: <root>/.appweaver/inventory/feature-map.json).")
+    pa.set_defaults(func=cmd_apply)
+
+    pcs = sub.add_parser("context-state", help="What onboard needs before touching a bounded context: its features, whether it is already onboarded, and what must be onboarded first.")
+    pcs.add_argument("--root", help="Codebase root (default: CWD).")
+    pcs.add_argument("--context", default="", help="Bounded context to report on (default: the first not yet onboarded).")
+    pcs.add_argument("--map", help="Machine map (default: <root>/.appweaver/inventory/feature-map.json).")
+    pcs.add_argument("--bundle", help="OKF bundle dir (default: <root>/knowledge).")
+    pcs.set_defaults(func=cmd_context_state)
+
+    psc = sub.add_parser("scaffold-context", help="Create specs/<Context>/<Feature>/ for every feature the map assigns to one bounded context.")
+    psc.add_argument("--root", help="Codebase root (default: CWD).")
+    psc.add_argument("--context", required=True, help="Bounded context to scaffold.")
+    psc.add_argument("--map", help="Machine map (default: <root>/.appweaver/inventory/feature-map.json).")
+    psc.set_defaults(func=cmd_scaffold_context)
+
     pc = sub.add_parser("concept", help="Resolve the OKF bundle concept + source_files for an aggregate.")
     pc.add_argument("--bundle", required=True, help="OKF bundle dir to search.")
     pc.add_argument("--aggregate", required=True, help="Aggregate name (e.g. MedicinalProduct).")
@@ -1166,6 +2925,13 @@ def main():
 
     pl = sub.add_parser("list-aggregates", help="List the OKF bundle's Aggregate concepts (the brownfield feature map).")
     pl.add_argument("--bundle", required=True, help="OKF bundle dir to enumerate.")
+    pl.add_argument("--context", default="",
+                    help="Bounded context to scope the list to. Concepts stamped with a "
+                         "DIFFERENT context are dropped; unstamped ones are always kept.")
+    pl.add_argument("--root", default="", help="Repo root, for the default map path (default: CWD).")
+    pl.add_argument("--map", default="",
+                    help="Machine map whose features are offered in place of the aggregate "
+                         "they act on (default: <root>/.appweaver/inventory/feature-map.json).")
     pl.set_defaults(func=cmd_list_aggregates)
 
     pv = sub.add_parser("validate", help="Run the OKF v0.1 conformance checker on a bundle.")