aw-spec-cli 0.1.19 → 0.1.21

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

@@ -14,8 +14,8 @@ Edges are DERIVED deterministically from the using aggregate's design.md — the
 domain/data-model section's "References (by id, not owned)" (+ `id<Other>` attribute
 types) for entity-ref edges, and the External Integrations table (located by heading
 keyword, so it works for both the forward and brownfield design layouts) for contract
-edges — resolved against the project's KNOWN aggregates (a specs/<Y>/ dir or an
-existing bundle concept). A
+edges — resolved against the project's KNOWN aggregates (one a feature's spec says it
+acts on, or an existing bundle concept). A
 target that is not a known aggregate (an external system, an owned child entity)
 is never written. Writers are greenfield `implement` and brownfield `adopt`; the
 reader is the CR loop (finalize-delta gates on the Cross-References blast radius).
@@ -224,6 +224,14 @@ def _slug(s):
     return re.sub(r"-{2,}", "-", s).strip("-")
 
 
+def _key(s):
+    """A name with case and every separator dropped. The bundle holds one name in three
+    spellings — a PascalCase id (MedicinalProduct), an OKF kebab file name
+    (medicinal-product.md) and a human title (Medicinal Product) — and a slug only
+    matches the last two to each other, so a lookup by id finds neither."""
+    return re.sub(r"[^a-z0-9]", "", (s or "").lower())
+
+
 def _read(path):
     try:
         with open(path, encoding="utf-8", errors="replace") as fh:
@@ -332,12 +340,24 @@ def _today(arg_date):
     return datetime.date.today().isoformat()
 
 
-def _agg_from_feature_dir(fd):
-    """The aggregate name = the feature dir's basename (feature = aggregate). The
-    workflow passes {{feature_dir}} (absolute); feature-paths carries no name field."""
+def _feature_from_dir(fd):
+    """The feature name = the feature directory's basename. The workflow passes
+    {{feature_dir}} (absolute); feature-paths carries no name field."""
     return os.path.basename(os.path.normpath(fd)) if fd else ""
 
 
+def _agg_from_feature_dir(fd, root=None):
+    """The CONCEPT a feature directory's OKF operations belong to: the aggregate the
+    feature answers for, not the feature. The bundle is the project's knowledge and a
+    concept is an aggregate, so a feature that is one capability over a shared aggregate
+    (PatientRegistration over Patient) reads and writes Patient's concept and never gets
+    one of its own. A 1:1 feature resolves to its own name — what every caller keyed on
+    before features and aggregates could differ."""
+    if not fd:
+        return ""
+    return _resolve_feature(fd, root or os.getcwd())["primary"]
+
+
 def _parse_source_files(raw, root):
     """Accept the files a generate step owns, as EITHER a JSON array (how the engine
     renders a list var: `["a.cs","b.cs"]`) OR a comma-separated string. Relativise any
@@ -430,7 +450,8 @@ def _read_fm(text):
 
 
 def _render_fm(fm):
-    order = ["type", "title", "description", "origin", "source_files", "ui_source_files"]
+    order = ["type", "title", "description", "origin", "bounded_context", "features",
+             "source_files", "ui_source_files"]
     keys = [k for k in order if k in fm] + [k for k in fm if k not in order]
     out = ["---"]
     for k in keys:
@@ -545,9 +566,10 @@ def _canonical_concept_path(bundle_abs, name):
 
 
 def _resolve_concept(name, bundle_abs):
-    """Find name's concept (mirrors aw-inventory.py concept): match title/base slug,
-    prefer a type containing 'aggregate'. Return abspath or None."""
-    want = _slug(name)
+    """Find name's concept (mirrors aw-inventory.py concept): match title or file name
+    with case and separators ignored, prefer a type containing 'aggregate'. Return
+    abspath or None."""
+    want = _key(name)
     best, best_score = None, -1
     if not os.path.isdir(bundle_abs):
         return None
@@ -560,21 +582,22 @@ def _resolve_concept(name, bundle_abs):
             fm, _ = _read_fm(_read(path))
             title = fm.get("title") if isinstance(fm.get("title"), str) else ""
             base = os.path.splitext(fn)[0]
-            if want not in (_slug(title), _slug(base)):
+            if want not in (_key(title), _key(base)):
                 continue
             typ = fm.get("type") if isinstance(fm.get("type"), str) else ""
-            score = (2 if "aggregate" in typ.lower() else 0) + (1 if _slug(base) == want else 0)
+            score = (2 if "aggregate" in typ.lower() else 0) + (1 if _key(base) == want else 0)
             if score > best_score:
                 best, best_score = path, score
     return best
 
 
-def _skeleton_concept(name, origin, source_files, description):
+def _skeleton_concept(name, origin, source_files, description, features=None):
     fm = {
         "type": "aggregate",
         "title": name,
         "description": description or f"{name} aggregate.",
         "origin": origin or "greenfield",
+        "features": list(features or []),
         "source_files": list(source_files or []),
     }
     overview = f"[overview of the {name} aggregate]"
@@ -595,14 +618,15 @@ def _ensure_dir_index(concept_path, name):
         _write(idx, f"# {name}\n\n- [{name}](./{base}.md)\n")   # NO frontmatter (OKF E3)
 
 
-def _get_or_stub_concept(name, bundle_abs, origin, stubbed):
-    """Return the concept path for name, creating a stub (+ dir/root index) if missing."""
+def _get_or_stub_concept(name, bundle_abs, origin, stubbed, features=None):
+    """Return the concept path for name, creating a stub (+ dir/root index) if missing.
+    A stub starts out listing the features already known to act on the aggregate."""
     path = _resolve_concept(name, bundle_abs)
     if path:
         return path
     _ensure_bundle(bundle_abs)
     path = _canonical_concept_path(bundle_abs, name)
-    _write(path, _skeleton_concept(name, origin, [], ""))
+    _write(path, _skeleton_concept(name, origin, [], "", features))
     _ensure_dir_index(path, name)
     stubbed.append(name)
     return path
@@ -623,14 +647,14 @@ def _section(text, start_pat, end_pat):
 
 
 def _known_aggregates(root, specs, bundle_abs):
-    """The project's aggregate registry: specs/<dir> names ∪ bundle concept titles/dirs.
-    Returns {slug: display_name}."""
+    """The project's aggregate registry: the aggregates every feature acts on (its spec's
+    Acts-on line, the boundary map, or its name when neither says) ∪ bundle concept
+    titles. A specs/ directory name is a feature or a bounded context, never an
+    aggregate by itself. Returns {slug: display_name}."""
     known = {}
-    specs_dir = os.path.join(root, specs)
-    if os.path.isdir(specs_dir):
-        for name in os.listdir(specs_dir):
-            if os.path.isdir(os.path.join(specs_dir, name)):
-                known.setdefault(_slug(name), name)
+    for v in _feature_index(root, specs).values():
+        for a in v["aggregates"]:
+            known.setdefault(_slug(a), a)
     if os.path.isdir(bundle_abs):
         for dirpath, dirnames, filenames in os.walk(bundle_abs):
             dirnames[:] = [d for d in dirnames if not d.startswith(".")]
@@ -772,17 +796,53 @@ def _all_concepts(bundle_abs):
     return out
 
 
+def _plan_path(fd):
+    """A feature's backend plan, under its current name or the pre-lane-split one."""
+    for n in ("backend-plan.md", "design.md"):
+        p = os.path.join(fd, n)
+        if os.path.isfile(p):
+            return p
+    return ""
+
+
+def _sibling_feature_dirs(root, specs, aggregate, exclude_fd):
+    """The OTHER feature directories that answer for `aggregate` and have a plan to
+    read — specs/<Feature>/ and specs/<Context>/<Feature>/ alike. Ownership is decided by
+    the same rule feature-aggregates applies, so a sibling is exactly what the resolver
+    says owns that aggregate."""
+    skip = ""
+    if exclude_fd:
+        skip = os.path.realpath(exclude_fd if os.path.isabs(exclude_fd)
+                                else os.path.join(root, exclude_fd))
+    want = _key(aggregate)
+    return [d for d in _feature_dirs(root, specs)
+            if os.path.realpath(d) != skip and _plan_path(d)
+            and want in {_key(x) for x in _resolve_feature(d, root)["owned"]}]
+
+
 # ─────────────────────────────── commands ──────────────────────────────────
 def cmd_record(args):
     root = _root(args.root)
     bundle_abs = os.path.join(root, args.bundle)
     date = _today(args.date)
-    using = args.using or _agg_from_feature_dir(args.feature_dir)
-    if not using:
+    # The concept a slice's edges belong to is the AGGREGATE it answers for, never the
+    # feature. A feature that answers for several aggregates records under each of them,
+    # and a feature that shares an aggregate records beside every other feature that
+    # answers for it — which is why each aggregate's edge set is the union over all of
+    # them rather than this feature's alone. An explicit --using names the aggregate itself.
+    one_to_one, own_keys = True, set()
+    if args.using:
+        usings = [args.using]
+    elif args.feature_dir:
+        r = _resolve_feature(args.feature_dir, root)
+        usings, one_to_one = list(r["owned"]), r["one_to_one"] == "true"
+        own_keys = {_key(a) for a in r["owned"]}
+    else:
+        usings = []
+    if not usings:
         print("[xref] record: --using or --feature-dir required", file=sys.stderr)
         _emit({"error": "using-required", "root": root})
         return 2
-    using_slug = _slug(using)
 
     design_arg = args.design or (os.path.join(args.feature_dir, "design.md") if args.feature_dir else "")
     if not design_arg:
@@ -795,9 +855,61 @@ def cmd_record(args):
     if origin == "auto":
         origin = _detect_origin(design_path)
 
-    known = _known_aggregates(root, args.specs, bundle_abs)
+    known_all = _known_aggregates(root, args.specs, bundle_abs)
+    feature = _feature_from_dir(args.feature_dir) if args.feature_dir else ""
+    results = [_record_one(root, bundle_abs, args, u, design_path, feature, own_keys,
+                           one_to_one, known_all, origin, date) for u in usings]
+
+    edges, wrote, stubbed, owners = [], [], [], []
+    for res in results:
+        edges.extend(dict(e, using=res["using"]) for e in res["edges"])
+        wrote.extend(res["wrote"])
+        stubbed.extend(s for s in res["stubbed"] if s not in stubbed)
+        owners.extend(o for o in res["owners"] if o not in owners)
+    pruned = sum(res["pruned"] for res in results)
+    print(f"[xref] recorded {', '.join(usings)} → {len(edges)} edge(s); "
+          f"stubbed {len(stubbed)}, pruned {pruned} stale row(s)", file=sys.stderr)
+    _emit({"using": usings[0], "usings": usings, "origin": origin, "edges": edges,
+           "edge_count": len(edges), "wrote": wrote, "stubbed": stubbed, "pruned": pruned,
+           "owners": owners, "one_to_one": "true" if one_to_one else "false",
+           "concept": results[0]["concept"], "root": root})
+    return 0
+
+
+def _record_one(root, bundle_abs, args, using, design_path, feature, own_keys,
+                one_to_one, known_all, origin, date):
+    """Reconcile ONE aggregate's edges: this feature's plan plus, where the aggregate is
+    shared, every other feature's plan that answers for it."""
+    using_slug = _slug(using)
+    known = dict(known_all)
     known.pop(using_slug, None)
-    edges = _design_edges(_read(design_path), using, known)
+
+    # An aggregate a feature itself answers for is never a dependency of another one it
+    # answers for: the reference between them is that one feature's code, not a boundary
+    # the model draws. Recorded, it would make a feature over Order + Inventory put each
+    # aggregate on the other's blast radius — a cycle no wave ordering can break.
+    def plan_edges(text, exclude):
+        return [e for e in _design_edges(text, using, known) if _key(e["target"]) not in exclude]
+
+    edges = plan_edges(_read(design_path), own_keys)
+
+    # A SHARED AGGREGATE'S EDGES ARE EVERY FEATURE'S. The delete phase below strips every
+    # row recorded under this aggregate and the add phase writes back only what it is
+    # handed, so recording one feature from its own plan would erase the edges the others
+    # recorded. Each other feature's CURRENT plan is read instead and the rows written are
+    # the union, which keeps reconcile-on-write self-healing for all of them. A feature
+    # that alone answers for the aggregate has no one to union with.
+    owners = [feature or using]
+    if not one_to_one:
+        seen_e = {(e["target"], e["via"], e["kind"]) for e in edges}
+        for sd in _sibling_feature_dirs(root, args.specs, using, args.feature_dir):
+            sr = _resolve_feature(sd, root)
+            owners.append(sr["feature"])
+            for e in plan_edges(_read(_plan_path(sd)), {_key(a) for a in sr["owned"]}):
+                k3 = (e["target"], e["via"], e["kind"])
+                if k3 not in seen_e:
+                    seen_e.add(k3)
+                    edges.append(e)
 
     # RECONCILE-ON-WRITE, delete phase: strip every row this slice authored, anywhere.
     # The ROWS are what this rewrites, so the lock has to span reading them and writing
@@ -818,7 +930,8 @@ def cmd_record(args):
     # same lock, spanning the read and the write.
     wrote, stubbed = [], []
     for e in edges:
-        ypath = _get_or_stub_concept(e["target"], bundle_abs, origin, stubbed)
+        ypath = _get_or_stub_concept(e["target"], bundle_abs, origin, stubbed,
+                                     _features_on(root, e["target"], specs=args.specs))
         with _lock(ypath):
             rows = _read_xref_rows(ypath)
             rows = [r for r in rows if not (_slug(r[0]) == using_slug and (len(r) > 1 and r[1] == e["via"]))]
@@ -827,40 +940,49 @@ def cmd_record(args):
         wrote.append({"target": e["target"], "concept": _rel(ypath, root), "via": e["via"], "kind": e["kind"]})
 
     # Rewrite this slice's own Depends-On (forward prune index) — stub self if needed.
-    xpath = _get_or_stub_concept(using, bundle_abs, origin, stubbed)
+    xpath = _get_or_stub_concept(using, bundle_abs, origin, stubbed,
+                                 _features_on(root, using, specs=args.specs))
     _write_deps_rows(xpath, [[e["target"], e["via"], e["kind"]] for e in edges])
-
-    print(f"[xref] recorded {using} → {len(edges)} edge(s); "
-          f"stubbed {len(stubbed)}, pruned {pruned} stale row(s)", file=sys.stderr)
-    _emit({"using": using, "origin": origin, "edges": edges, "edge_count": len(edges),
-           "wrote": wrote, "stubbed": stubbed, "pruned": pruned,
-           "concept": _rel(xpath, root), "root": root})
-    return 0
+    return {"using": using, "edges": edges, "wrote": wrote, "stubbed": stubbed,
+            "pruned": pruned, "owners": owners, "concept": _rel(xpath, root)}
 
 
 def cmd_list(args):
     root = _root(args.root)
     bundle_abs = os.path.join(root, args.bundle)
-    aggregate = args.aggregate or _agg_from_feature_dir(args.feature_dir)
-    if not aggregate:
+    # A feature's blast radius is that of EVERY aggregate it answers for: a change to a
+    # feature over Order and Inventory can ripple into whatever uses either of them.
+    if args.aggregate:
+        aggregates = [args.aggregate]
+    elif args.feature_dir:
+        aggregates = list(_resolve_feature(args.feature_dir, root)["owned"])
+    else:
+        aggregates = []
+    if not aggregates:
         print("[xref] list: --aggregate or --feature-dir required", file=sys.stderr)
         _emit({"error": "aggregate-required", "root": root})
         return 2
+    aggregate = aggregates[0]
     path = _resolve_concept(aggregate, bundle_abs)
-    users = []
-    if path:
-        for r in _read_xref_rows(path):
-            users.append({
+    users, seen_u = [], set()
+    for agg in aggregates:
+        apath = _resolve_concept(agg, bundle_abs)
+        for r in (_read_xref_rows(apath) if apath else []):
+            u = {
                 "using": r[0],
                 "via": r[1] if len(r) > 1 else "",
                 "kind": r[2] if len(r) > 2 else "",
                 "origin": r[3] if len(r) > 3 else "",
                 "recorded": r[4] if len(r) > 4 else "",
-            })
+            }
+            k3 = (u["using"], u["via"], u["kind"])
+            if k3 not in seen_u:
+                seen_u.add(k3)
+                users.append(u)
     out_rel = ""
     if args.out:
         out_path = args.out if os.path.isabs(args.out) else os.path.join(root, args.out)
-        _write(out_path, _render_impact_md(aggregate, users))
+        _write(out_path, _render_impact_md(", ".join(aggregates), users))
         out_rel = _rel(out_path, root)
     # Direct referrers (identifier-clean, de-duped) + the transitive closure — the
     # integrity blast radius a caller runs tests over. count/users stay as-is for
@@ -870,10 +992,13 @@ def cmd_list(args):
         name = (u["using"] or "").strip()
         if _IDENT_RE.match(name) and name not in seen_d:
             seen_d.add(name); direct.append(name)
-    closure = _referrer_closure(aggregate, bundle_abs)
-    print(f"[xref] {aggregate}: {len(users)} downstream user(s) "
+    closure = []
+    for agg in aggregates:
+        closure.extend(c for c in _referrer_closure(agg, bundle_abs) if c not in closure)
+    print(f"[xref] {', '.join(aggregates)}: {len(users)} downstream user(s) "
           f"— {', '.join(sorted({u['using'] for u in users})) or '(none)'}", file=sys.stderr)
-    _emit({"aggregate": aggregate, "concept": _rel(path, root) if path else "",
+    _emit({"aggregate": aggregate, "aggregates": aggregates,
+           "concept": _rel(path, root) if path else "",
            "users": users, "count": len(users), "impact_report": out_rel, "root": root,
            "referrers": direct, "referrers_csv": ",".join(direct),
            "referrer_closure": closure, "referrer_closure_csv": ",".join(closure),
@@ -886,19 +1011,29 @@ def cmd_concept_upsert(args):
     root = _root(args.root)
     bundle_abs = os.path.join(root, args.bundle)
     origin = args.origin or "greenfield"
-    aggregate = args.aggregate or _agg_from_feature_dir(args.feature_dir)
+    aggregate = args.aggregate or _agg_from_feature_dir(args.feature_dir, root)
     if not aggregate:
         print("[xref] concept-upsert: --aggregate or --feature-dir required", file=sys.stderr)
         _emit({"error": "aggregate-required", "root": root})
         return 2
     source_files = _parse_source_files(args.source_files, root)
+    # THE CONCEPT KNOWS ITS FEATURES. A concept is an aggregate, and several features may
+    # act on one — so each concept lists, under `features:`, every feature known to act on
+    # it. The files land on ONE concept (the aggregate this feature answers for first, so
+    # a file has one home); the feature is linked on every aggregate it acts on.
+    feature, acted = "", []
+    if args.feature_dir and not args.aggregate:
+        fr = _resolve_feature(args.feature_dir, root)
+        feature, acted = fr["feature"], fr["aggregates"]
 
     path = _resolve_concept(aggregate, bundle_abs)
     created = path is None
     if created:
         _ensure_bundle(bundle_abs)
         path = _canonical_concept_path(bundle_abs, aggregate)
-        _write(path, _skeleton_concept(aggregate, origin, source_files, args.description or ""))
+        _write(path, _skeleton_concept(aggregate, origin, source_files, args.description or "",
+                                       _merge_features(_features_on(root, aggregate),
+                                                       [feature])))
         _ensure_dir_index(path, aggregate)
     else:
         # Update frontmatter ONLY (source_files/description/origin); PRESERVE the body,
@@ -929,19 +1064,61 @@ def cmd_concept_upsert(args):
             elif "description" not in fm:
                 fm["description"] = f"{aggregate} aggregate."
             fm.setdefault("origin", origin)
-            rebuilt = (_render_fm(fm) + "\n" + body if body.startswith("\n")
-                       else _render_fm(fm) + "\n\n" + body.lstrip("\n"))
-            _write(path, rebuilt.rstrip("\n") + "\n")   # _read_fm's split drops the final newline
+            if feature:
+                fm["features"] = _merge_features(fm.get("features"), [feature])
+            _write(path, _rebuild_concept(fm, body))
         _ensure_bundle(bundle_abs)
         _ensure_dir_index(path, aggregate)
 
+    # Every OTHER aggregate this feature acts on lists it too, where that aggregate has a
+    # concept already. One with no concept yet picks the feature up when it is created:
+    # creation seeds the list from every feature known to act on the aggregate.
+    linked = [aggregate] if feature else []
+    for a in acted:
+        apath = _resolve_concept(a, bundle_abs) if _key(a) != _key(aggregate) else None
+        if apath:
+            _link_feature(apath, feature)
+            linked.append(a)
+
     print(f"[xref] concept {aggregate}: {'created' if created else 'updated'} "
-          f"({len(source_files)} source file(s)) — {_rel(path, root)}", file=sys.stderr)
+          f"({len(source_files)} source file(s)) — {_rel(path, root)}"
+          + (f"; {feature} listed on {', '.join(linked)}" if feature else ""), file=sys.stderr)
     _emit({"aggregate": aggregate, "concept": _rel(path, root), "created": "true" if created else "false",
-           "source_file_count": len(source_files), "root": root})
+           "source_file_count": len(source_files), "feature": feature,
+           "features_linked": linked, "root": root})
     return 0
 
 
+def _merge_features(existing, names):
+    """`existing` plus each of `names` not already listed, compared case- and
+    punctuation-insensitively. Never drops an entry: a concept's feature list only grows,
+    the same as adopt extends a concept additively."""
+    out = [x for x in (existing if isinstance(existing, list) else []) if x]
+    keys = {_key(x) for x in out}
+    for n in names:
+        if n and _key(n) not in keys:
+            keys.add(_key(n))
+            out.append(n)
+    return out
+
+
+def _rebuild_concept(fm, body):
+    rebuilt = (_render_fm(fm) + "\n" + body if body.startswith("\n")
+               else _render_fm(fm) + "\n\n" + body.lstrip("\n"))
+    return rebuilt.rstrip("\n") + "\n"   # _read_fm's split drops the final newline
+
+
+def _link_feature(path, feature):
+    """Add `feature` to a concept's `features:` list, under the concept's lock, touching
+    nothing else in the file."""
+    with _lock(path):
+        fm, body = _read_fm(_read(path))
+        merged = _merge_features(fm.get("features"), [feature])
+        if merged != fm.get("features"):
+            fm["features"] = merged
+            _write(path, _rebuild_concept(fm, body))
+
+
 def cmd_concept_overview(args):
     """Splice model-authored PROSE into the concept's `## Overview` — the one section a
     deterministic script cannot write. Section-scoped on purpose: the model never owns
@@ -949,7 +1126,7 @@ def cmd_concept_overview(args):
     Runs AFTER concept-upsert (which owns creation + frontmatter)."""
     root = _root(args.root)
     bundle_abs = os.path.join(root, args.bundle)
-    aggregate = args.aggregate or _agg_from_feature_dir(args.feature_dir)
+    aggregate = args.aggregate or _agg_from_feature_dir(args.feature_dir, root)
     if not aggregate:
         print("[xref] concept-overview: --aggregate or --feature-dir required", file=sys.stderr)
         _emit({"error": "aggregate-required", "root": root})
@@ -1011,7 +1188,7 @@ def cmd_concept_paths(args):
     than swallowed."""
     root = _root(args.root)
     bundle_abs = os.path.join(root, args.bundle)
-    aggregate = args.aggregate or _agg_from_feature_dir(args.feature_dir)
+    aggregate = args.aggregate or _agg_from_feature_dir(args.feature_dir, root)
     if not aggregate:
         print("[xref] concept-paths: --aggregate or --feature-dir required", file=sys.stderr)
         _emit({"error": "aggregate-required", "root": root})
@@ -1035,18 +1212,255 @@ def cmd_concept_paths(args):
             target = s if os.path.isabs(s) else os.path.join(root, s)
             (existing if os.path.isfile(target) else missing).append(s)
 
+    # A feature that is one capability over a shared aggregate is made of ITS files, not
+    # the aggregate's: the concept lists every capability's code, and a fix loop handed a
+    # sibling's files will edit them. The source-map adopt writes is the per-feature
+    # list. Without one — a capability adopt has not reached yet — the aggregate's list
+    # stands: over-inclusive, but never missing a file this feature does own.
+    scope = "aggregate"
+    if args.feature_dir and not args.aggregate:
+        r = _resolve_feature(args.feature_dir, root)
+        if r["one_to_one"] == "false":
+            mapped = _source_map_files(os.path.join(r["feature_dir"], "source-map.md"))
+            if mapped:
+                declared = mapped
+                existing = [s for s in mapped
+                            if os.path.isfile(s if os.path.isabs(s) else os.path.join(root, s))]
+                missing = [s for s in mapped if s not in existing]
+                scope = "feature"
+
     note = "" if path else " — no concept recorded yet"
     drift = f", {len(missing)} declared-but-missing" if missing else ""
-    print(f"[xref] concept-paths {aggregate}: {len(existing)} file(s) on disk{drift}{note}",
-          file=sys.stderr)
+    print(f"[xref] concept-paths {aggregate}: {len(existing)} file(s) on disk{drift}{note}"
+          f" (scope: {scope})", file=sys.stderr)
     _emit({"aggregate": aggregate, "concept": _rel(path, root) if path else "",
-           "found": bool(path), "paths": existing, "count": len(existing),
+           "found": bool(path), "scope": scope, "paths": existing, "count": len(existing),
            "csv": ",".join(existing), "declared": declared,
            "declared_count": len(declared), "missing": missing,
            "missing_count": len(missing), "root": root})
     return 0
 
 
+# A source-map's Artefact → spec/design table row: `| SM-nnn | `<artefact>` | …`.
+_SM_ROW_RE = re.compile(r"^\|\s*SM-\d+\s*\|\s*`([^`]+)`\s*\|", re.M)
+
+
+def _source_map_files(path):
+    """The legacy FILES a feature's source-map maps — the per-feature file list. Only
+    the Artefact → spec/design table counts, and only rows naming a path: tables,
+    endpoints and jobs share that table and are not files. The Unmapped / open section
+    is exactly what the feature does NOT own, so it is never read."""
+    out = []
+    for p in _SM_ROW_RE.findall(_read(path) or ""):
+        p = p.strip().replace(os.sep, "/")
+        if ("/" in p or re.search(r"\.[A-Za-z0-9]{1,6}$", p)) and p not in out:
+            out.append(p)
+    return out
+
+
+# ──────────────────── feature-aggregates (read-only) ───────────────────────
+# The spec template's Domain Model Reference line. Only what precedes the "— see …"
+# pointer names aggregates; the pointer itself names the model file.
+_ACTS_ON_RE = re.compile(r"^\s*[-*]?\s*\*\*Acts on aggregate\(s\)\*\*\s*:\s*(.*)$", re.I | re.M)
+_AGG_NAME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9]*$")
+
+
+def _acts_on_from_spec(spec_path):
+    """The aggregate names a spec's `**Acts on aggregate(s)**:` line gives, in order.
+    Backticked names are read first; a line written without backticks falls back to
+    comma-separated bare names. A bracketed template token such as `[Root]` is not a
+    name — a scaffolded spec that nobody has filled yet answers nothing here."""
+    m = _ACTS_ON_RE.search(_read(spec_path) or "")
+    if not m:
+        return []
+    head = re.split(r"\s+[—–]\s+see\b|\s+-\s+see\b", m.group(1), maxsplit=1)[0]
+    names = re.findall(r"`([^`]+)`", head) or re.split(r"\s*[,;]\s*|\s+and\s+", head)
+    out = []
+    for n in names:
+        n = (n or "").strip().strip("*").strip()
+        if n and "[" not in n and _AGG_NAME_RE.match(n) and n not in out:
+            out.append(n)
+    return out
+
+
+def _aggregates_from_map(root, feature):
+    """The aggregate(s) the confirmed boundary map assigns to a feature. Matched with
+    case and punctuation ignored, because the map carries the name as the operator
+    typed it ("care plan") and the directory carries it normalised (CarePlan)."""
+    try:
+        with open(os.path.join(root, ".appweaver", "inventory", "feature-map.json"),
+                  encoding="utf-8") as fh:
+            m = json.load(fh)
+    except (OSError, ValueError):
+        return []
+    key = lambda s: re.sub(r"[^a-z0-9]", "", (s or "").lower())
+    for f in m.get("features", []) or []:
+        if key(f.get("feature")) == key(feature):
+            aggs = f.get("aggregates") or ([f.get("aggregate")] if f.get("aggregate") else [])
+            return [a for a in dict.fromkeys(aggs) if a]
+    return []
+
+
+def _raw_aggregates(fd_abs, root, feature):
+    """(aggregates, source) for one feature directory — the spec's Acts-on line, then
+    the boundary map, then the feature name. No ownership is decided here."""
+    aggs, source = _acts_on_from_spec(os.path.join(fd_abs, "spec.md")), "spec"
+    if not aggs:
+        aggs, source = _aggregates_from_map(root, feature), "feature-map"
+    if not aggs:
+        aggs, source = [feature], "feature-name"
+    return aggs, source
+
+
+def _home(feature, aggs):
+    """The one aggregate a feature is ABOUT, when it has one: the aggregate it is named
+    after, or the only aggregate it acts on. Every other aggregate a feature with a home
+    names is one it merely touches. A feature over several aggregates named after none
+    of them has no home — it is a capability across all of them."""
+    mine = [a for a in aggs if _key(a) == _key(feature)]
+    return mine[:1] or (list(aggs[:1]) if len(aggs) == 1 else [])
+
+
+def _pascal_name(s):
+    return "".join(w[:1].upper() + w[1:] for w in re.split(r"[^A-Za-z0-9]+", s or "") if w)
+
+
+def _feature_dirs(root, specs="specs"):
+    """Every feature directory in the specs tree: specs/<Feature>/ in a flat layout and
+    specs/<Context>/<Feature>/ inside a bounded context. A top-level directory with no
+    spec.md of its own that holds a domain-model.md or sub-directories is a context, and
+    every child of a context is a feature, specified or not."""
+    base = os.path.join(root, specs)
+    out = []
+    if not os.path.isdir(base):
+        return out
+    for a in sorted(os.listdir(base)):
+        d = os.path.join(base, a)
+        if a.startswith(".") or not os.path.isdir(d):
+            continue
+        subs = [b for b in sorted(os.listdir(d))
+                if not b.startswith(".") and os.path.isdir(os.path.join(d, b))]
+        if not os.path.isfile(os.path.join(d, "spec.md")) and (
+                os.path.isfile(os.path.join(d, "domain-model.md")) or subs):
+            out.extend(os.path.join(d, b) for b in subs)
+        else:
+            out.append(d)
+    return out
+
+
+_INDEX_CACHE = {}
+
+
+def _feature_index(root, specs="specs"):
+    """Every feature the project defines — the specs tree ∪ the confirmed boundary map —
+    with the aggregates it acts on and the ones it CLAIMS (answers for). A feature with a
+    home claims only its home; a capability claims every aggregate it acts on. Keyed by
+    the normalised feature name. Read once per process: nothing here writes the tree."""
+    ck = (os.path.realpath(root), specs)
+    if ck in _INDEX_CACHE:
+        return _INDEX_CACHE[ck]
+    idx = {}
+    for d in _feature_dirs(root, specs):
+        name = _feature_from_dir(d)
+        aggs, _ = _raw_aggregates(d, root, name)
+        idx[_key(name)] = {"feature": name, "dir": d, "aggregates": aggs,
+                           "claims": _home(name, aggs) or aggs}
+    try:
+        with open(os.path.join(root, ".appweaver", "inventory", "feature-map.json"),
+                  encoding="utf-8") as fh:
+            mapped = json.load(fh).get("features") or []
+    except (OSError, ValueError):
+        mapped = []
+    for f in mapped:
+        name = _pascal_name(f.get("feature", ""))
+        if not name or _key(name) in idx:
+            continue
+        aggs = [a for a in dict.fromkeys(f.get("aggregates") or [f.get("aggregate")]) if a]
+        if aggs:
+            idx[_key(name)] = {"feature": name, "dir": "", "aggregates": aggs,
+                               "claims": _home(name, aggs) or aggs}
+    _INDEX_CACHE[ck] = idx
+    return idx
+
+
+def _features_on(root, aggregate, field="aggregates", specs="specs"):
+    """The features that act on (field="aggregates") or answer for (field="claims") an
+    aggregate, in name order."""
+    k = _key(aggregate)
+    return sorted((v["feature"] for v in _feature_index(root, specs).values()
+                   if k in {_key(a) for a in v[field]}), key=str.lower)
+
+
+def _resolve_feature(fd, root):
+    """What feature-aggregates reports, as a dict — shared with every concept operation
+    that is handed a feature directory, so all of them agree on which concept it is."""
+    feature = _feature_from_dir(fd)
+    fd_abs = fd if os.path.isabs(fd) else os.path.join(root, fd)
+    aggs, source = _raw_aggregates(fd_abs, root, feature)
+    # OWNERSHIP IS DECIDED BY WHO ELSE ANSWERS FOR THE AGGREGATE, NEVER BY THE NAME. A
+    # feature answers outright for its home only while no other feature claims that
+    # aggregate too; the moment a second one does, both are capabilities over a shared
+    # aggregate. A name that matches the aggregate is the developer's naming choice,
+    # not a claim that no other feature will ever act on it.
+    home = _home(feature, aggs)
+    owned = home or aggs
+    own_keys = {_key(a) for a in owned}
+    shared_with = [v["feature"] for v in _feature_index(root).values()
+                   if _key(v["feature"]) != _key(feature)
+                   and own_keys & {_key(a) for a in v["claims"]}]
+    shared_with = sorted(dict.fromkeys(shared_with), key=str.lower)
+    one_to_one = bool(home) and not shared_with
+    fmt = lambda xs: ", ".join(f"`## Aggregate: {a}`" for a in xs)
+    return {"feature": feature, "feature_dir": fd_abs, "source": source,
+            "aggregates": aggs, "aggregates_csv": ", ".join(aggs), "sections": fmt(aggs),
+            "owned": owned, "owned_csv": ", ".join(owned), "owned_sections": fmt(owned),
+            "primary": owned[0], "one_to_one": "true" if one_to_one else "false",
+            "shared_with": shared_with, "shared_with_csv": ", ".join(shared_with)}
+
+
+def cmd_feature_aggregates(args):
+    """WHICH AGGREGATE(S) A FEATURE ACTS ON — the name every command that reads the
+    bounded context's domain-model.md needs, because the model is organised by
+    aggregate (`## Aggregate: <Name>`) and the specs tree by feature.
+
+    For most features the two names are the same, and every caller used the feature
+    name as the section heading. That stops being true the moment one aggregate
+    carries two capabilities — PatientRegistration and PatientMerge over Patient —
+    and a lookup by feature name then finds no section. The failure is silent in the
+    worst place: a conformance gate scoring "the BR-nnn under this feature's section"
+    finds none and passes.
+
+    Three sources, most authoritative first:
+      1. spec     — the spec's own `**Acts on aggregate(s)**:` line. The document-level
+                    answer once a spec exists, and the one a change updates.
+      2. map      — the confirmed boundary map (.appweaver/inventory/feature-map.json),
+                    which /appweaver inventory writes and the operator edits. Covers a
+                    brownfield feature before its spec exists, which is exactly when
+                    adopt needs to know.
+      3. feature  — the feature name itself: the 1:1 default, and the only answer a
+                    greenfield feature with no spec yet can have. Every caller behaves
+                    exactly as it did before this resolver existed.
+
+    Two answers come back. `aggregates` is everything the feature acts on. `owned` is
+    the part of the model it answers for: its own section when it is itself one of
+    those aggregates — the 1:1 case, even where the spec also names an aggregate it
+    merely touches — and otherwise every aggregate it names.
+
+    STRICTLY READ-ONLY and never empty: source 3 always answers, so a caller never has
+    to branch on a missing result."""
+    root = _root(args.root)
+    if not _feature_from_dir(args.feature_dir):
+        print("[xref] feature-aggregates: --feature-dir required", file=sys.stderr)
+        _emit({"error": "feature-dir-required", "root": root})
+        return 2
+    r = _resolve_feature(args.feature_dir, root)
+    print(f"[xref] feature-aggregates {r['feature']}: acts on {r['aggregates_csv']} "
+          f"(from {r['source']}); owns {r['owned_csv']}", file=sys.stderr)
+    r["root"] = root
+    _emit(r)
+    return 0
+
+
 # ─────────────────────────────── validate ──────────────────────────────────
 def cmd_validate(args):
     """Cross-reference drift check (the safety net BEYOND reconcile-on-write). Pairs the
@@ -1196,28 +1610,28 @@ def cmd_tree(args):
             "xrefs": [r[0] for r in xref_rows if len(r) >= 1]
         }
 
-    # 2. Check specs/ directory for features
-    if os.path.isdir(specs_abs):
-        for entry in os.listdir(specs_abs):
-            entry_path = os.path.join(specs_abs, entry)
-            if os.path.isdir(entry_path) and not entry.startswith("."):
-                slug = _slug(entry)
-                if slug not in aggregates:
-                    design_p = os.path.join(entry_path, "design.md")
-                    spec_p = os.path.join(entry_path, "spec.md")
-                    if os.path.exists(design_p) or os.path.exists(spec_p):
-                        dep_targets = []
-                        if os.path.exists(design_p):
-                            known_map = {s: s for s in aggregates}
-                            edges = _design_edges(_read(design_p), entry, known_map)
-                            dep_targets = [e["target"] for e in edges]
-                        aggregates[slug] = {
-                            "name": entry,
-                            "slug": slug,
-                            "concept_path": _rel(spec_p if os.path.exists(spec_p) else entry_path, root),
-                            "deps": list(set(dep_targets)),
-                            "xrefs": []
-                        }
+    # 2. Aggregates the specs tree knows that have no concept yet. A specs/ directory is a
+    #    feature or a bounded context, never an aggregate: each feature contributes the
+    #    aggregates it answers for, with the edges its plan declares.
+    for fd in _feature_dirs(root, args.specs):
+        spec_p, plan_p = os.path.join(fd, "spec.md"), _plan_path(fd)
+        if not plan_p and not os.path.isfile(spec_p):
+            continue
+        for agg in _resolve_feature(fd, root)["owned"]:
+            slug = _slug(agg)
+            if slug in aggregates:
+                continue
+            dep_targets = []
+            if plan_p:
+                known_map = {s: s for s in aggregates}
+                dep_targets = [e["target"] for e in _design_edges(_read(plan_p), agg, known_map)]
+            aggregates[slug] = {
+                "name": agg,
+                "slug": slug,
+                "concept_path": _rel(spec_p if os.path.isfile(spec_p) else fd, root),
+                "deps": list(set(dep_targets)),
+                "xrefs": []
+            }
 
     # 3. Fallback scan src/ directory if no aggregates in bundle/specs
     if not aggregates:
@@ -1416,6 +1830,11 @@ def main(argv):
     cp.add_argument("--bundle", default="knowledge")
     cp.set_defaults(func=cmd_concept_paths)
 
+    fa = sub.add_parser("feature-aggregates", help="read-only: the aggregate(s) a feature acts on — spec, then the boundary map, then the feature name")
+    fa.add_argument("--feature-dir", dest="feature_dir", default="")
+    fa.add_argument("--root", default="")
+    fa.set_defaults(func=cmd_feature_aggregates)
+
     vv = sub.add_parser("validate", help="report cross-reference drift (orphan rows)")
     vv.add_argument("--prune", action="store_true", help="remove stale reverse orphans (safe self-heal)")
     vv.add_argument("--root", default="")