aw-spec-cli 0.1.8 → 0.1.9

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

@@ -0,0 +1,1180 @@
+#!/usr/bin/env python3
+"""aw-inventory.py — brownfield repository inventory for the aw-spec pipeline.
+
+The deterministic, model-free substrate for the Brownfield-Pipeline B0
+(Inventory) phase (see Brownfield-Pipeline.md).
+It scans an existing ("brownfield") codebase and emits a factual JSON substrate
+that the /appweaver inventory workflow's enrichment agent turns into an
+aggregate-organized OKF v0.1 knowledge bundle. The agent uses this so it never
+has to guess the repo layout.
+
+Ported from Reference/okf-inventory.sh (which was ~90% embedded python already)
+into a single cross-platform python core, with two brownfield additions:
+
+  * aggregate_signals — candidate DDD aggregate roots derived from domain /
+    entity / model / route file clustering, ranked by churn + evidence. These
+    are SIGNALS, not decisions: the workflow's agent draws the real aggregate
+    boundaries. This is the "inventory following aggregate root" the pipeline
+    needs — one aggregate ≈ one candidate specs/<Feature>/ vertical slice.
+  * frontend_signals — candidate FRONTEND LANE roots derived from component /
+    view / stylesheet clustering around frontend build configs. Like the
+    aggregate signals these are SIGNALS, not decisions, and they are what lets
+    /appweaver onboard answer "does this repo have a UI, and where" from the
+    code alone rather than from a stack profile or a project name.
+  * ui_attribution — which frontend files serve which aggregate, so a slice's OKF
+    concept carries its UI surface and not just its backend files. Needed because
+    the lane scoping below builds aggregate_signals from backend files ALONE.
+    Searches the FRONTEND SOURCE PATH only (declared root, else the roots the scan
+    found) and does not run at all where the repo has no frontend — a backend repo's
+    email templates and docs stylesheets are not its UI. Signals again: files
+    matching no aggregate are reported unattributed rather than forced into one.
+  * git history scoped to the scan subtree (not the whole monorepo), so the
+    inventory reflects only the code being adopted.
+
+Subcommands, all printing a single JSON object as the LAST stdout line (so the
+orchestrator's execute_script can bind it); human-readable summaries go to STDERR
+so they never corrupt the JSON contract:
+
+  scan     [--root <dir>] [--out <path>] [--bundle <dir>] [--config <yml>]
+           -> writes the full substrate JSON to --out; prints a compact summary
+              object {inventory_json, file_count, head, branch, aggregate_count,
+              frontend_present, frontend_separable, frontend_root_count,
+              frontend_roots, bundle_dir, bundle_present, bundle_md_count}
+  concept  --bundle <dir> --aggregate <name>
+           -> resolves ONE aggregate's OKF concept + source_files (the code that
+              IS the slice) — the index adopt reverse-engineers a feature from
+  list-aggregates --bundle <dir>
+           -> enumerates the bundle's Aggregate concepts (the brownfield feature
+              map) → {aggregates[{name,title,slug,concept_path,...}], count} — the
+              selectable feature list select-feature offers in a brownfield repo
+  validate --bundle <dir> [--repo-root <dir>]
+           -> runs the OKF v0.1 conformance checker (validate_okf.py, beside
+              this file) and re-emits {concepts, errors[], warnings[], result,
+              conformant}
+
+Usage: aw-inventory.py <scan|concept|list-aggregates|validate> [options]
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+# Default excludes, aligned with okf-inventory.sh / okf-config.template.yml.
+DEFAULT_EXCLUDE = re.compile(
+    r"^(node_modules|\.git|dist|build|vendor|\.specify|\.appweaver|specs|knowledge)/"
+    r"|(^|/)[^/]*\.min\.js$"
+)
+
+CAP = int(os.environ.get("OKF_INVENTORY_CAP", "150"))
+HIST_COMMITS = int(os.environ.get("OKF_HISTORY_COMMITS", "2000"))
+HIST_RECENT = int(os.environ.get("OKF_HISTORY_RECENT", "20"))
+CHURN_TOP = int(os.environ.get("OKF_CHURN_TOP", "30"))
+
+# --- category regexes (mirror okf-inventory.sh) ----------------------------
+MANIFESTS_RE = re.compile(
+    r"(^|/)(package\.json|pyproject\.toml|setup\.py|requirements[^/]*\.txt|"
+    r"go\.mod|Cargo\.toml|pom\.xml|build\.gradle(\.kts)?|Gemfile|composer\.json|"
+    r"[^/]*\.csproj)$"
+)
+ENTRYPOINTS_RE = re.compile(
+    r"(^|/)(main|app|index|server|cli|manage|__main__|Program)\.(py|js|ts|go|rs|rb|java|cs)$"
+)
+API_DEFS_RE = re.compile(
+    r"\.(proto|avsc|graphql|gql)$|(^|/)(openapi|swagger)[^/]*\.(ya?ml|json)$"
+)
+ROUTES_RE = re.compile(
+    r"(rout|controller|endpoint|handler|view|resource)s?[^/]*\.(py|js|ts|go|rb|java|cs|php)$",
+    re.IGNORECASE,
+)
+DB_FILES_RE = re.compile(
+    r"(^|/)(migrations?|alembic|db/migrate)/|"
+    r"(model|schema|entit|aggregat)[^/]*\.(py|js|ts|go|rb|java|cs|sql|prisma)$",
+    re.IGNORECASE,
+)
+OPS_FILES_RE = re.compile(
+    r"(^|/)(Dockerfile[^/]*|docker-compose[^/]*\.ya?ml|Makefile|Procfile|[^/]*\.tf|"
+    r"helm/.*|k8s/.*\.ya?ml|\.github/workflows/.*\.ya?ml|\.gitlab-ci\.yml|"
+    r"Jenkinsfile|cloudbuild\.ya?ml)$"
+)
+DOCS_RE = re.compile(
+    r"(^|/)(README[^/]*|CONTRIBUTING[^/]*|CHANGELOG[^/]*|ARCHITECTURE[^/]*|docs?/.*)"
+    r"\.(md|rst|txt)$"
+)
+CONFIGS_RE = re.compile(
+    r"(^|/)(config|settings|conf|appsettings)[^/]*\.(py|js|ts|ya?ml|json|toml|ini|env\.example)$",
+    re.IGNORECASE,
+)
+ADR_RE = re.compile(r"(^|/)(adr|adrs|decisions?|rfcs?)/|(^|/)(ADR|RFC)[-_0-9]", re.IGNORECASE)
+
+# --- frontend / UI detection (the lane signal) ------------------------------
+# Deterministic evidence that this repo has a USER INTERFACE, and where it lives.
+# The CODE is the whole oracle here: a lane is recognised from files that exist,
+# never from a stack profile, a manifest's dependency list, or a project's name.
+# Covers BOTH shapes a UI takes in a legacy repo — a separable client app with its
+# own build, and server-rendered views living inside the service tree with no root
+# of their own. SIGNALS, not decisions: the workflow's agent reads the real source
+# and draws the lane.
+UI_COMPONENT_RE = re.compile(
+    r"\.(jsx|tsx|vue|svelte|astro|razor|cshtml|vbhtml|aspx|ascx|master|jsp|jspx|"
+    r"erb|haml|slim|hbs|handlebars|mustache|twig|ejs|pug|jade|njk|xaml|axml)$"
+    r"|\.blade\.php$",
+    re.IGNORECASE,
+)
+UI_MARKUP_RE = re.compile(r"\.(html?|xhtml)$", re.IGNORECASE)
+UI_STYLE_RE = re.compile(r"\.(css|scss|sass|less|styl|pcss)$", re.IGNORECASE)
+# A build/tooling config only a frontend carries. The strongest separable-lane
+# signal there is: the directory holding one IS the lane root.
+UI_BUILD_CFG_RE = re.compile(
+    r"(^|/)(angular\.json|vite\.config\.[cm]?[jt]s|next\.config\.[cm]?[jt]s|"
+    r"nuxt\.config\.[cm]?[jt]s|svelte\.config\.[cm]?[jt]s|vue\.config\.[cm]?[jt]s|"
+    r"remix\.config\.[cm]?[jt]s|astro\.config\.[cm]?[jt]s|gatsby-config\.[cm]?[jt]s|"
+    r"tailwind\.config\.[cm]?[jt]s|postcss\.config\.[cm]?[jt]s|"
+    r"webpack\.config\.[cm]?[jt]s|rollup\.config\.[cm]?[jt]s|"
+    r"ember-cli-build\.js|craco\.config\.js|metro\.config\.js)$",
+    re.IGNORECASE,
+)
+PKG_JSON_RE = re.compile(r"(^|/)package\.json$")
+# Folders that mean "user interface" — reported only INSIDE a root that already
+# qualified on file evidence, so a backend `routes/` or `public/` cannot create one.
+UI_DIR_RE = re.compile(
+    r"(^|/)(components?|pages|views|screens|layouts|widgets|containers|templates|"
+    r"partials|wwwroot|styles?|themes?|stores?|hooks|composables)(/|$)",
+    re.IGNORECASE,
+)
+UI_ROUTE_RE = re.compile(
+    r"(^|/)(routes?|router|routing)[^/]*\.[cm]?[jt]sx?$|(^|/)app-routing\.module\.ts$",
+    re.IGNORECASE,
+)
+UI_STORE_RE = re.compile(
+    r"(^|/)(stores?|redux|vuex|pinia|ngrx)(/|[^/]*\.[cm]?[jt]sx?$)", re.IGNORECASE
+)
+# Evidence path -> the stack it indicates. A MARKER, never a decision: the agent
+# names the framework from the code. Ordered — the first match wins, so an explicit
+# build config outranks a bare file extension.
+FRAMEWORK_MARKERS = [
+    (re.compile(r"(^|/)angular\.json$", re.I), "angular"),
+    (re.compile(r"(^|/)next\.config\.", re.I), "next.js"),
+    (re.compile(r"(^|/)nuxt\.config\.", re.I), "nuxt"),
+    (re.compile(r"(^|/)remix\.config\.", re.I), "remix"),
+    (re.compile(r"(^|/)gatsby-config\.", re.I), "gatsby"),
+    (re.compile(r"(^|/)astro\.config\.", re.I), "astro"),
+    (re.compile(r"(^|/)metro\.config\.js$", re.I), "react-native"),
+    (re.compile(r"(^|/)svelte\.config\.", re.I), "svelte"),
+    (re.compile(r"(^|/)vue\.config\.", re.I), "vue"),
+    (re.compile(r"(^|/)vite\.config\.", re.I), "vite"),
+    (re.compile(r"(^|/)tailwind\.config\.", re.I), "tailwind"),
+    (re.compile(r"\.vue$", re.I), "vue"),
+    (re.compile(r"\.svelte$", re.I), "svelte"),
+    (re.compile(r"\.astro$", re.I), "astro"),
+    (re.compile(r"\.[jt]sx$", re.I), "jsx components"),
+    (re.compile(r"\.razor$", re.I), "blazor"),
+    (re.compile(r"\.(cshtml|vbhtml)$", re.I), "asp.net razor views"),
+    (re.compile(r"\.(aspx|ascx|master)$", re.I), "asp.net web forms"),
+    (re.compile(r"\.jspx?$", re.I), "jsp"),
+    (re.compile(r"\.erb$", re.I), "erb views"),
+    (re.compile(r"\.blade\.php$", re.I), "laravel blade"),
+    (re.compile(r"\.twig$", re.I), "twig"),
+    (re.compile(r"\.(hbs|handlebars|mustache)$", re.I), "handlebars/mustache"),
+    (re.compile(r"\.(pug|jade)$", re.I), "pug"),
+    (re.compile(r"\.ejs$", re.I), "ejs"),
+    (re.compile(r"\.(haml|slim)$", re.I), "haml/slim"),
+    (re.compile(r"\.njk$", re.I), "nunjucks"),
+    (re.compile(r"\.(xaml|axml)$", re.I), "xaml"),
+]
+# Component extensions that ship as a CLIENT app vs. ones RENDERED BY THE SERVER.
+# What separates them is whether the UI can own a root of its own — the ownership
+# rule binds generation, and a server-rendered view tree has no root to own.
+SPA_EXT_RE = re.compile(r"\.(jsx|tsx|vue|svelte|astro|razor)$", re.IGNORECASE)
+DESKTOP_EXT_RE = re.compile(r"\.(xaml|axml)$", re.IGNORECASE)
+# Component files below which a candidate is reported but not called a lane. A
+# missed lane costs a re-run; an invented one costs a ratified governance file for
+# a lane that does not exist, so a root with no build config must show a real view set.
+UI_STRONG_MIN = 5
+
+
+def frontend_signals(files, churn_map):
+    """Derive CANDIDATE frontend lane roots — the deterministic answer to "does
+    this repo have a UI, and where". Each root reports its evidence, what KIND of
+    UI it is, and whether it is SEPARABLE (owns a subtree) or server-rendered
+    inside the service tree.
+
+    `present` is true only where a root reaches lane strength: it holds a frontend
+    build config, or at least UI_STRONG_MIN component/view files. Weaker candidates
+    (a `wwwroot/` of loose scripts and stylesheets) are still LISTED, marked weak —
+    visible to the reader, but never enough on their own to author governance."""
+    comp = matching(files, UI_COMPONENT_RE)
+    styles = matching(files, UI_STYLE_RE)
+    markup = matching(files, UI_MARKUP_RE)
+    cfgs = matching(files, UI_BUILD_CFG_RE)
+    if not (comp or cfgs or styles or markup):
+        return {"present": False, "separable": False, "ui_file_count": 0, "roots": []}
+
+    # Anchors: the directory of every frontend build config or package.json, longest
+    # first, so a nested web/ app wins over a monorepo root that also has one.
+    anchor_set = {os.path.dirname(f) for f in cfgs + matching(files, PKG_JSON_RE)}
+    anchors = sorted(anchor_set, key=len, reverse=True)
+
+    def anchor_of(f):
+        for a in anchors:
+            if a == "" or f.startswith(a + "/"):
+                return a
+        return f.split("/", 1)[0] if "/" in f else ""
+
+    roots = {}
+
+    def root_rec(key):
+        return roots.setdefault(key, {
+            "root": (key + "/") if key else "./",
+            "component_files": [], "style_files": [], "markup_files": [],
+            "build_configs": [], "route_files": [], "store_files": [],
+            "ui_dirs": set(), "framework_markers": set(), "churn": 0,
+        })
+
+    for bucket, key in (
+        (comp, "component_files"), (styles, "style_files"),
+        (markup, "markup_files"), (cfgs, "build_configs"),
+    ):
+        for f in bucket:
+            r = root_rec(anchor_of(f))
+            r[key].append(f)
+            r["churn"] += churn_map.get(f, 0)
+            for rx, name in FRAMEWORK_MARKERS:
+                if rx.search(f):
+                    r["framework_markers"].add(name)
+                    break
+            d = os.path.dirname(f)
+            if d and UI_DIR_RE.search(d):
+                r["ui_dirs"].add(d)
+
+    # Routing + client state are reported only where a UI already lives, so a
+    # server-side `routes/` folder can never invent one.
+    for f in matching(files, UI_ROUTE_RE):
+        key = anchor_of(f)
+        if key in roots:
+            roots[key]["route_files"].append(f)
+    for f in matching(files, UI_STORE_RE):
+        key = anchor_of(f)
+        if key in roots:
+            roots[key]["store_files"].append(f)
+
+    # A root anchored on a build config keeps that config's directory — the project
+    # itself declares where it starts. An UNANCHORED root (a server-rendered view
+    # tree has no build config to anchor on) was bucketed by top-level directory,
+    # which is coarser than the truth, so narrow it to the directory its own UI
+    # files actually share: `src/` becomes `src/App/`, the web project.
+    for key, r in roots.items():
+        if key in anchor_set:
+            continue
+        dirs = [os.path.dirname(f) or "." for f in
+                r["component_files"] + r["style_files"] + r["markup_files"]]
+        if not dirs:
+            continue
+        common = os.path.commonpath(dirs) if len(dirs) > 1 else dirs[0]
+        if common not in (".", "", os.sep):
+            r["root"] = common + "/"
+
+    out = []
+    for r in roots.values():
+        comp_n = len(r["component_files"])
+        spa_n = sum(1 for f in r["component_files"] if SPA_EXT_RE.search(f))
+        desk_n = sum(1 for f in r["component_files"] if DESKTOP_EXT_RE.search(f))
+        srv_n = comp_n - spa_n - desk_n
+        if comp_n == 0:
+            kind = "assets-only"
+        elif desk_n > spa_n and desk_n > srv_n:
+            kind = "desktop"
+        elif srv_n > spa_n:
+            kind = "server-rendered"
+        else:
+            kind = "spa"
+        strong = bool(r["build_configs"]) or comp_n >= UI_STRONG_MIN
+        # A server-rendered view tree has no subtree to own; the ownership rule binds
+        # generation, not adoption, so such a lane is reversed in place.
+        separable = kind != "server-rendered" and r["root"] != "./"
+        for k in ("component_files", "style_files", "markup_files",
+                  "build_configs", "route_files", "store_files"):
+            r[k] = sorted(set(r[k]))[:CAP]
+        r["ui_dirs"] = sorted(r["ui_dirs"])[:CAP]
+        r["framework_markers"] = sorted(r["framework_markers"])
+        r["counts"] = {
+            "component": comp_n, "style": len(r["style_files"]),
+            "markup": len(r["markup_files"]),
+        }
+        r["kind"] = kind
+        r["confidence"] = "strong" if strong else "weak"
+        r["separable"] = separable
+        out.append(r)
+
+    out.sort(key=lambda r: (r["confidence"] == "strong", r["counts"]["component"],
+                            r["churn"]), reverse=True)
+    strong_roots = [r for r in out if r["confidence"] == "strong"]
+    return {
+        "present": bool(strong_roots),
+        "separable": any(r["separable"] for r in strong_roots),
+        "ui_file_count": len(comp) + len(styles) + len(markup),
+        "roots": out,
+    }
+
+# Directory / filename hints that a file participates in a domain aggregate.
+DOMAIN_DIR_RE = re.compile(r"(^|/)(domain|aggregates?|entit(y|ies)|models?)(/|$)", re.IGNORECASE)
+# Layer folders inside a vertical slice. The PARENT of any of these is an
+# aggregate-module candidate (e.g. .../MedicinalProducts/Domain/... -> the
+# aggregate module is MedicinalProducts). This mirrors the aw-spec
+# MinimalMonolith vertical-slice layout and is the strongest, lowest-noise
+# aggregate signal — far better than clustering on file basenames.
+LAYER_DIR_RE = re.compile(
+    r"^(domain|features?|application|use[-_]?cases?|handlers?|persistence|"
+    r"infrastructure|infra|data|repositor(y|ies)|api|endpoints?|controllers?|"
+    r"aggregates?|entit(y|ies)|models?|dtos?|contracts?)$",
+    re.IGNORECASE,
+)
+# Which bucket a layer folder maps to, for grouping a candidate's files.
+LAYER_KIND = {
+    "domain": "domain", "aggregate": "domain", "aggregates": "domain",
+    "entity": "domain", "entities": "domain", "model": "domain", "models": "domain",
+    "feature": "feature", "features": "feature", "application": "feature",
+    "usecase": "feature", "usecases": "feature", "use-case": "feature",
+    "use-cases": "feature", "use_case": "feature", "use_cases": "feature",
+    "handler": "feature", "handlers": "feature",
+    "persistence": "infra", "infrastructure": "infra", "infra": "infra",
+    "data": "infra", "repository": "infra", "repositories": "infra",
+    "api": "api", "endpoint": "api", "endpoints": "api",
+    "controller": "api", "controllers": "api",
+    "dto": "api", "dtos": "api", "contract": "api", "contracts": "api",
+}
+# Type-role suffixes stripped to recover the underlying aggregate/entity noun
+# (used only for the secondary within-aggregate "entities" hint, and for the
+# flat-repo fallback when there are no layer folders).
+ROLE_SUFFIX_RE = re.compile(
+    r"(Aggregate(Root)?|Root|Entity|Model|Repository|Repo|Controller|Service|"
+    r"Handler|Endpoint|Resource|Dto|DTO|Mapper|Schema|Table|Command|Query|"
+    r"Factory|Spec|Specification|View)$"
+)
+# Verb prefixes on CQRS command/use-case names, stripped so RegisterMedicinal…
+# resolves toward its aggregate rather than becoming its own candidate.
+VERB_PREFIX_RE = re.compile(
+    r"^(Register|Create|Add|Update|Modify|Change|Delete|Remove|Get|List|Find|"
+    r"Fetch|Set|Assign|Approve|Reject|Cancel|Submit|Publish|Archive|Restore|"
+    r"Enable|Disable|Activate|Deactivate|Send|Generate)"
+)
+CODE_EXT_RE = re.compile(r"\.(py|js|ts|go|rs|rb|java|cs|php|kt|scala|sql|prisma)$", re.IGNORECASE)
+
+
+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
+
+
+# --- glob-based config excludes (best-effort, mirrors okf-inventory.sh) -----
+def load_config_excludes(config_path):
+    if not config_path or not os.path.isfile(config_path):
+        return []
+    try:
+        with open(config_path, encoding="utf-8") as f:
+            lines = f.readlines()
+    except OSError:
+        return []
+    in_exclude = False
+    globs = []
+    for line in lines:
+        stripped = line.strip()
+        if re.match(r"^exclude\s*:\s*$", stripped):
+            in_exclude = True
+            continue
+        if in_exclude:
+            m = re.match(r"^-\s*[\"']?([^\"'#]+)[\"']?\s*(#.*)?$", stripped)
+            if m:
+                globs.append(m.group(1).strip())
+                continue
+            if stripped and not stripped.startswith("#"):
+                in_exclude = False
+    out = []
+    for g in globs:
+        parts, i = [], 0
+        while i < len(g):
+            if g[i:i + 2] == "**":
+                parts.append(".*"); i += 2
+            elif g[i] == "*":
+                parts.append("[^/]*"); i += 1
+            else:
+                parts.append(re.escape(g[i])); i += 1
+        out.append(re.compile("^" + "".join(parts) + "$"))
+    return out
+
+
+def git(root, *args):
+    """Run a git command in `root`; return stdout (stripped) or '' on failure."""
+    try:
+        p = subprocess.run(["git", "-C", root, *args], capture_output=True, text=True)
+        return p.stdout.strip() if p.returncode == 0 else ""
+    except Exception:
+        return ""
+
+
+def is_excluded(path, config_excludes):
+    if DEFAULT_EXCLUDE.search(path):
+        return True
+    return any(rx.match(path) for rx in config_excludes)
+
+
+def list_files(root, config_excludes):
+    """Repo-relative-to-`root` file list, honoring .gitignore via git ls-files."""
+    if git(root, "rev-parse", "--git-dir"):
+        raw = git(root, "ls-files")
+        files = raw.splitlines() if raw else []
+    else:
+        files = []
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = [d for d in dirnames if d != ".git"]
+            for fn in filenames:
+                rel = os.path.relpath(os.path.join(dirpath, fn), root)
+                files.append(rel.replace(os.sep, "/"))
+    return [f for f in files if f.strip() and not is_excluded(f, config_excludes)]
+
+
+def churn(root, config_excludes):
+    """Commit-count per file over the last HIST_COMMITS commits, scoped to the
+    scan subtree (paths made relative to `root` via --show-prefix)."""
+    if not git(root, "rev-parse", "--git-dir"):
+        return [], 0
+    prefix = git(root, "rev-parse", "--show-prefix")  # root's path under toplevel
+    raw = git(root, "log", "--no-merges", "-n", str(HIST_COMMITS),
+              "--pretty=format:", "--name-only", "--", ".")
+    counts = {}
+    for line in raw.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        rel = line[len(prefix):] if prefix and line.startswith(prefix) else line
+        if prefix and not line.startswith(prefix):
+            continue  # outside the scan subtree
+        if is_excluded(rel, config_excludes):
+            continue
+        counts[rel] = counts.get(rel, 0) + 1
+    ranked = sorted(counts.items(), key=lambda kv: kv[1], reverse=True)[:CHURN_TOP]
+    scanned = git(root, "rev-list", "--no-merges", "--count", "-n", str(HIST_COMMITS), "HEAD")
+    return [{"file": f, "commits": c} for f, c in ranked], int(scanned or 0)
+
+
+def recent_commits(root):
+    if not git(root, "rev-parse", "--git-dir"):
+        return []
+    raw = git(root, "log", "--no-merges", "-n", str(HIST_RECENT),
+              "--pretty=format:%h%x09%cI%x09%s", "--", ".")
+    out = []
+    for line in raw.splitlines():
+        parts = line.split("\t")
+        if len(parts) >= 3:
+            out.append({"sha": parts[0], "date": parts[1], "subject": "\t".join(parts[2:])})
+    return out
+
+
+def matching(files, rx):
+    return [f for f in files if rx.search(f)]
+
+
+def _entity_noun(path):
+    """Recover the domain noun from a file basename (role suffixes + a CQRS verb
+    prefix stripped): RegisterMedicinalProductCommandHandler -> MedicinalProduct.
+    Signal-grade; returns None for non-nouny names."""
+    base = os.path.splitext(os.path.basename(path))[0]
+    base = re.split(r"[._-]", base)[0]
+    prev = None
+    while prev != base:
+        prev = base
+        base = ROLE_SUFFIX_RE.sub("", base)
+    base = VERB_PREFIX_RE.sub("", base)
+    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.
+
+    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 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)]
+    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))
+                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)
+
+    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.
+        if not any(CODE_EXT_RE.search(f) for k in layers for f in c[k]):
+            continue
+        for k in layers:
+            c[k] = sorted(set(c[k]))[:CAP]
+        c["entities"] = sorted(c["entities"])[:CAP]
+        c["file_count"] = sum(len(c[k]) for k in layers)
+        c["evidence_count"] = c["file_count"]
+        sig.append(c)
+
+    # 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):
+            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["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)
+
+    sig.sort(key=lambda c: (c["evidence_count"], c["churn"]), reverse=True)
+    return sig
+
+
+# A UI file wears its role in its NAME, and the vocabulary is not the backend's:
+# ROLE_SUFFIX_RE knows Repository / Handler / Controller and none of List / Form /
+# Page. Kept as a separate list rather than merged into it — applying the UI roles to
+# backend names would eat `ProductService` down to `Product`, which is a different
+# claim than the backend clustering makes.
+UI_ROLE_TOKENS = (
+    "list", "table", "grid", "form", "page", "screen", "view", "details", "detail",
+    "card", "item", "row", "modal", "dialog", "drawer", "panel", "editor", "widget",
+    "container", "component", "layout", "section", "tab", "menu", "nav", "header",
+    "footer", "sidebar", "toolbar", "filter", "search", "picker", "selector",
+    "provider", "context", "store", "slice", "hook", "service", "client", "api",
+    "index", "styles", "style", "module", "spec", "test", "stories",
+)
+UI_ACTION_TOKENS = (
+    "register", "create", "add", "new", "edit", "update", "modify", "change",
+    "delete", "remove", "get", "list", "find", "fetch", "view", "show", "manage",
+)
+
+
+def _ui_norm(text):
+    """Bare lowercase alphanumerics — the one form every casing convention shares."""
+    return re.sub(r"[^a-z0-9]", "", text.lower())
+
+
+def _ui_stem(path):
+    """The concept a UI filename points at, its role suffix and action prefix removed:
+    medicinal-product-list.tsx, MedicinalProductForm.vue and EditMedicinalProduct.tsx
+    all reduce to `medicinalproduct`."""
+    stem = _ui_norm(os.path.splitext(os.path.basename(path))[0])
+    changed = True
+    while changed:
+        changed = False
+        for t in UI_ROLE_TOKENS:
+            if stem.endswith(t) and len(stem) > len(t) + 2:
+                stem, changed = stem[: -len(t)], True
+        for t in UI_ACTION_TOKENS:
+            if stem.startswith(t) and len(stem) > len(t) + 2:
+                stem, changed = stem[len(t):], True
+    return stem
+
+
+def _ui_name_tokens(name):
+    """The normalised forms an aggregate name wears in a UI tree. The folder is
+    usually plural where the aggregate name is singular, so both travel together."""
+    base = _ui_norm(name)
+    if not base:
+        return set()
+    out = {base, base + "s"}
+    if base.endswith("y"):
+        out.add(base[:-1] + "ies")
+    if base.endswith("s"):
+        out.add(base[:-1])
+    return out
+
+
+def attribute_ui_files(signals, fe_files, churn_map, ui_roots):
+    """Attribute each frontend file to the aggregate it serves.
+
+    WHY THIS EXISTS. scope_to_lanes splits the substrate so the backend and frontend
+    steps cannot see each other's files, which means aggregate_signals is built from
+    backend files ALONE — and a slice's OKF concept would list none of the UI that
+    serves it. adopt then reverses that slice with no UI source within reach, so the
+    frontend lane's design has nothing to be derived from.
+
+    The match is by NAME with both sides normalised: a DIRECTORY SEGMENT named for the
+    concept (the strong signal — a feature folder), or a filename whose concept stem
+    matches once its UI role suffix is stripped. Where several aggregates match, the
+    LONGEST name wins, so `MedicinalProduct` takes a file that `Product` would also
+    have claimed.
+
+    SIGNALS, not decisions — the same contract as every other function here. A file
+    matching no aggregate stays in `unattributed`, which is the honest answer for the
+    shell, layout and design-system files that serve no single feature and belong in
+    the architecture note instead of being forced into a slice.
+
+    SCOPED TO THE FRONTEND TREE, AND SKIPPED ENTIRELY WITHOUT ONE. `ui_roots` is the
+    lane's source path — the declared one, or the roots the scan actually found. Two
+    guards, because neither is sufficient alone: with no UI root declared scope_to_lanes
+    hands back the WHOLE REPO as the frontend list, and the file-shape regexes match
+    plenty of things a backend repo legitimately owns — a server-side email template, a
+    docs stylesheet, an `.html` test fixture. Matching on shape alone attributes those
+    to an aggregate as its "UI". So the search happens under the frontend roots only,
+    and where there is no frontend root there is no search.
+    """
+    roots = [r for r in (ui_roots or []) if r]
+    if not roots:
+        return {"attributed_file_count": 0, "aggregates_with_ui": 0,
+                "unattributed_count": 0, "unattributed": [], "search_roots": []}
+    # "./" is a UI that owns no subtree of its own (a flat repo, a server-rendered view
+    # tree): it narrows nothing, and it is only ever reached because a frontend WAS
+    # found there — the file-shape filter below carries that case alone.
+    prefixes = [] if any(r in ("./", "/") for r in roots) else roots
+    in_lane = fe_files if not prefixes else [
+        f for f in fe_files if any(f.startswith(p) for p in prefixes)]
+    ui_files = sorted(set(
+        matching(in_lane, UI_COMPONENT_RE) + matching(in_lane, UI_MARKUP_RE)
+        + matching(in_lane, UI_STYLE_RE) + matching(in_lane, UI_ROUTE_RE)
+        + matching(in_lane, UI_STORE_RE)
+    ))
+    if not ui_files:
+        return {"attributed_file_count": 0, "aggregates_with_ui": 0,
+                "unattributed_count": 0, "unattributed": [], "search_roots": roots}
+
+    # name tokens -> the candidate, longest name first so the most specific match wins
+    ranked = sorted(signals, key=lambda c: len(_ui_norm(c["name"])), reverse=True)
+    token_map = [(c, _ui_name_tokens(c["name"])) for c in ranked]
+    for c, _ in token_map:
+        c.setdefault("ui_files", [])
+
+    unattributed = []
+    for f in ui_files:
+        segments = {_ui_norm(p) for p in os.path.dirname(f).split("/") if p}
+        stem = _ui_stem(f)
+        for c, tokens in token_map:
+            if (segments & tokens) or (stem and stem in tokens):
+                c["ui_files"].append(f)
+                c["churn"] += churn_map.get(f, 0)
+                break
+        else:
+            unattributed.append(f)
+
+    attributed = 0
+    with_ui = 0
+    for c, _ in token_map:
+        c["ui_files"] = sorted(set(c["ui_files"]))[:CAP]
+        # ui_file_count is reported BESIDE file_count, never folded into it: the
+        # aggregate ranking is backend evidence and a UI-heavy slice must not
+        # outrank a domain-heavy one on component count.
+        c["ui_file_count"] = len(c["ui_files"])
+        attributed += c["ui_file_count"]
+        if c["ui_file_count"]:
+            with_ui += 1
+
+    return {"attributed_file_count": attributed, "aggregates_with_ui": with_ui,
+            "unattributed_count": len(unattributed),
+            "unattributed": sorted(unattributed)[:CAP], "search_roots": roots}
+
+
+def bundle_state(bundle_dir):
+    """How many concept .md files a candidate bundle already holds (the OKF
+    generate guard: a non-empty bundle means /appweaver inventory would
+    clobber curation — the workflow should stop unless --force)."""
+    if not os.path.isdir(bundle_dir):
+        return False, 0
+    count = 0
+    for dirpath, dirnames, filenames in os.walk(bundle_dir):
+        dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+        count += sum(1 for f in filenames if f.endswith(".md") and f not in ("index.md", "log.md"))
+    return count > 0, count
+
+
+def _lane_prefix(p):
+    """A declared source path as a '/'-terminated repo-relative prefix, or ''."""
+    s = (p or "").strip().replace("\\", "/").lstrip("./").lstrip("/")
+    if s and not s.endswith("/"):
+        s += "/"
+    return "" if s == "/" else s
+
+
+def scope_to_lanes(files, service_root, ui_root):
+    """Split the file list the way the project declared its lanes.
+
+    WHY THIS EXISTS. The substrate is inlined verbatim into every agent request the
+    onboarding run makes — six of them — so its size is paid six times, and its
+    CONTENT is paid in a subtler currency. Unscoped, the step deriving the service
+    lane's rules receives the whole frontend file list while its prompt tells it to
+    exclude those roots, and the steps deriving the UI lane's rules receive every
+    backend aggregate. Telling a model not to use what you have just put in front of
+    it is the weakest control available; not putting it there is the strongest.
+
+    So: backend signals come from everything OUTSIDE the UI lane's subtree (and
+    inside the service lane's, where one is declared), and frontend signals come
+    from the UI lane's subtree alone. Repo-wide categories are deliberately NOT
+    scoped — the CI config, the editorconfig and the root manifests describe the
+    whole repository, and scoping them would hide the very files that say how it is
+    built.
+
+    With neither root declared this returns the full list twice and the scan behaves
+    exactly as it did before lanes were declarable.
+    """
+    svc, ui = _lane_prefix(service_root), _lane_prefix(ui_root)
+    be = [f for f in files if not (ui and f.startswith(ui))]
+    if svc:
+        be = [f for f in be if f.startswith(svc)]
+    fe = [f for f in files if f.startswith(ui)] if ui else files
+    return be, fe, svc, ui
+
+
+def cmd_scan(args):
+    root = os.path.abspath(args.root or os.getcwd())
+    config_excludes = load_config_excludes(args.config)
+    out = os.path.abspath(args.out) if args.out else os.path.join(root, ".appweaver", "inventory", "inventory.json")
+    bundle_dir = os.path.abspath(args.bundle) if args.bundle else os.path.join(root, "knowledge")
+
+    files = list_files(root, config_excludes)
+    churn_list, commits_scanned = churn(root, config_excludes)
+    churn_map = {c["file"]: c["commits"] for c in churn_list}
+
+    def hist(s):
+        h = {}
+        for f in files:
+            _, dot, ext = f.rpartition(".")
+            if dot and ext:
+                h[ext] = h.get(ext, 0) + 1
+        return h
+
+    lang_hist = dict(sorted(hist(files).items(), key=lambda kv: kv[1], reverse=True)[:15])
+    topdirs = {}
+    for f in files:
+        if "/" in f:
+            top = f.split("/", 1)[0]
+            topdirs[top] = topdirs.get(top, 0) + 1
+    top_level_dirs = dict(sorted(topdirs.items(), key=lambda kv: kv[1], reverse=True)[:20])
+
+    def category(rx):
+        hits = matching(files, rx)
+        return {"items": hits[:CAP], "truncated": len(hits) > CAP}
+
+    cats = {
+        "dependency_manifests": category(MANIFESTS_RE),
+        "entrypoints": category(ENTRYPOINTS_RE),
+        "api_definitions": category(API_DEFS_RE),
+        "route_like_files": category(ROUTES_RE),
+        "data_layer_files": category(DB_FILES_RE),
+        "ops_files": category(OPS_FILES_RE),
+        "docs": category(DOCS_RE),
+        "config_files": category(CONFIGS_RE),
+        "adr_docs": category(ADR_RE),
+    }
+    be_files, fe_files, svc_prefix, ui_prefix = scope_to_lanes(
+        files, args.service_root, args.ui_root)
+    signals = aggregate_signals(be_files, churn_map)
+    fsig = frontend_signals(fe_files, churn_map)
+
+    # A DECLARED UI lane is a lane. The strength test below UI_STRONG_MIN exists to
+    # stop a scan INVENTING one from a wwwroot/ of loose scripts; it has no business
+    # overruling a person who declared the lane and named its source path. What the
+    # evidence still decides is what goes IN the governance — and a declared root
+    # holding no recognisable UI files is reported as exactly that, so onboard can
+    # say so rather than quietly authoring a UI half out of nothing.
+    if ui_prefix:
+        fsig["declared_root"] = ui_prefix
+        fsig["ui_evidence_found"] = bool(fsig.get("roots"))
+        fsig["present"] = True
+        fsig["separable"] = ui_prefix not in ("", "./") and not svc_prefix.startswith(ui_prefix)
+        if not fsig.get("roots"):
+            fsig["roots"] = [{"root": ui_prefix, "kind": "declared", "confidence": "declared",
+                              "counts": {"component": 0}, "framework_markers": [],
+                              "component_files": [], "style_files": [], "markup_files": [],
+                              "build_configs": [], "route_files": [], "store_files": []}]
+
+    # Give every aggregate candidate the UI that serves it — searching the FRONTEND
+    # SOURCE PATH and nothing else. The declared root is the authority; absent a
+    # declaration the roots the scan actually found stand in, which keeps a repo whose
+    # UI is server-rendered inside the service tree covered. With neither, this repo
+    # has no frontend and the pass does not run at all.
+    if ui_prefix:
+        ui_search_roots = [ui_prefix]
+    elif fsig.get("present"):
+        ui_search_roots = [r.get("root", "") for r in (fsig.get("roots") or [])]
+    else:
+        ui_search_roots = []
+    ui_attr = attribute_ui_files(signals, fe_files, churn_map, ui_search_roots)
+
+    present, md_count = bundle_state(bundle_dir)
+
+    inv = {
+        "root": root,
+        "git": {
+            "remote": git(root, "remote", "get-url", "origin"),
+            "branch": git(root, "symbolic-ref", "--short", "HEAD") or "main",
+            "head": git(root, "rev-parse", "--short", "HEAD"),
+            "history": {
+                "commits_scanned": commits_scanned,
+                "churn": churn_list,
+                "recent_commits": recent_commits(root),
+                "churn_truncated": len(churn_list) >= CHURN_TOP > 0,
+            },
+        },
+        "file_count": len(files),
+        "cap": CAP,
+        # The lane scoping this substrate was built under, so a reader can tell a
+        # repo with no backend aggregates from one whose backend was scoped away.
+        "declared_service_root": svc_prefix,
+        "declared_ui_root": ui_prefix,
+        "scoped_file_counts": {"backend": len(be_files), "frontend": len(fe_files),
+                               "repo": len(files)},
+        "language_histogram": lang_hist,
+        "top_level_dirs": top_level_dirs,
+        **{k: v["items"] for k, v in cats.items()},
+        "aggregate_signals": 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
+        # design-system surface, which belongs in the architecture note rather than in
+        # any one slice.
+        "ui_attribution": ui_attr,
+        "truncated": {k: True for k, v in cats.items() if v["truncated"]},
+    }
+    os.makedirs(os.path.dirname(out), exist_ok=True)
+    with open(out, "w", encoding="utf-8") as f:
+        json.dump(inv, f, indent=2)
+
+    # Human summary -> STDERR (must not pollute the JSON contract on stdout).
+    print(f"Inventory written to {out}", file=sys.stderr)
+    print(f"  files: {inv['file_count']}  head: {inv['git']['head'] or '-'}  "
+          f"branch: {inv['git']['branch']}", file=sys.stderr)
+    h = inv["git"]["history"]
+    print(f"  git history: {h['commits_scanned']} commits scanned, "
+          f"{len(h['churn'])} hot files, {len(h['recent_commits'])} recent subjects",
+          file=sys.stderr)
+    print(f"  candidate aggregates ({len(signals)}): "
+          f"{', '.join(s['name'] for s in signals[:12])}"
+          f"{' …' if len(signals) > 12 else ''}", file=sys.stderr)
+    if fsig["roots"]:
+        print(f"  frontend: {'lane present' if fsig['present'] else 'no lane (weak signals only)'}"
+              f" — {len(fsig['roots'])} candidate root(s), {fsig['ui_file_count']} UI file(s)",
+              file=sys.stderr)
+        for r in fsig["roots"][:6]:
+            print(f"    {r['root']}  {r['kind']}/{r['confidence']}"
+                  f"  components={r['counts']['component']}"
+                  f"  {', '.join(r['framework_markers'][:4]) or '-'}", file=sys.stderr)
+    for k in cats:
+        flag = " (truncated)" if k in inv["truncated"] else ""
+        print(f"  {k}: {len(inv[k])}{flag}", file=sys.stderr)
+    if present:
+        print(f"  NOTE: bundle {bundle_dir} already holds {md_count} concept file(s)",
+              file=sys.stderr)
+
+    # Machine contract -> LAST stdout line (bound by the orchestrator).
+    print(json.dumps({
+        "inventory_json": out,
+        "root": root,
+        "file_count": inv["file_count"],
+        "head": inv["git"]["head"],
+        "branch": inv["git"]["branch"],
+        "aggregate_count": len(signals),
+        # The frontend lane, as the CODE evidences it. Strings, because the engine
+        # compares variables as text. `frontend_roots` is the human line a workflow
+        # message or prompt quotes; the full evidence stays in the substrate file.
+        "frontend_present": "true" if fsig["present"] else "false",
+        "frontend_separable": "true" if fsig["separable"] else "false",
+        "frontend_root_count": len(fsig["roots"]),
+        # The PRIMARY lane root — the strongest candidate, and the single value a
+        # lane declaration needs. Empty when no root reached lane strength.
+        "frontend_root": next((r["root"] for r in fsig["roots"]
+                               if r["confidence"] == "strong"), ""),
+        "frontend_kind": next((r["kind"] for r in fsig["roots"]
+                               if r["confidence"] == "strong"), ""),
+        "frontend_stack": next(("/".join(r["framework_markers"][:3]) for r in fsig["roots"]
+                                if r["confidence"] == "strong" and r["framework_markers"]), ""),
+        "frontend_roots": ", ".join(
+            f"{r['root']} ({r['kind']}, {r['confidence']}"
+            + (f", {'/'.join(r['framework_markers'][:3])}" if r["framework_markers"] else "")
+            + ")"
+            for r in fsig["roots"][:6]
+        ),
+        # What the declaration scoped this run to, and whether the UI subtree it named
+        # actually held any UI. A declared lane stays a lane either way; this is how
+        # onboard tells "reverse-engineered from real UI source" from "declared, but
+        # there is nothing here to reverse".
+        "declared_service_root": svc_prefix,
+        "declared_ui_root": ui_prefix,
+        "ui_evidence_found": "true" if fsig.get("ui_evidence_found", bool(fsig["roots"])) else "false",
+        "backend_file_count": len(be_files),
+        "frontend_file_count": len(fe_files),
+        "bundle_dir": bundle_dir,
+        "bundle_present": "true" if present else "false",
+        "bundle_md_count": md_count,
+    }))
+    return 0
+
+
+def _slug(s):
+    return re.sub(r"-+", "-", re.sub(r"[^a-z0-9]+", "-", (s or "").lower())).strip("-")
+
+
+def _pascal(s):
+    """kebab/space/anything -> PascalCase, byte-compatible with the bash/ps
+    _pascal + set-feature normalizer (uppercase each word's first char, keep the
+    rest as-is so an existing PascalCase token like MedicinalProduct is preserved)."""
+    words = re.split(r"[^A-Za-z0-9]+", s or "")
+    return "".join(w[:1].upper() + w[1:] for w in words if w)
+
+
+def _read_frontmatter(path):
+    """Return the concept's frontmatter dict (title/type/source_files), best-effort
+    without a YAML dependency. Only the fields adopt needs."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            text = f.read()
+    except OSError:
+        return {}
+    if not text.startswith("---"):
+        return {}
+    lines = text.splitlines()
+    end = next((i for i in range(1, len(lines)) if lines[i].strip() == "---"), None)
+    if end is None:
+        return {}
+    data, key = {}, None
+    for ln in lines[1:end]:
+        m = re.match(r"^([A-Za-z0-9_]+):\s*(.*)$", ln)
+        if m:
+            key = m.group(1)
+            val = m.group(2).strip()
+            data[key] = val.strip("'\"") if val else []
+        elif key and re.match(r"^\s*-\s+", ln):  # a list item under the last key
+            if not isinstance(data.get(key), list):
+                data[key] = []
+            data[key].append(re.sub(r"^\s*-\s+", "", ln).strip().strip("'\""))
+    return data
+
+
+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 +
+    design.md FROM. Matches on title/filename slug; prefers an Aggregate type."""
+    bundle = os.path.abspath(args.bundle)
+    want = _slug(args.aggregate)
+    best = None
+    if os.path.isdir(bundle):
+        for dirpath, dirnames, filenames in os.walk(bundle):
+            dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+            for fn in filenames:
+                if not fn.endswith(".md") or fn in ("index.md", "log.md"):
+                    continue
+                path = os.path.join(dirpath, fn)
+                fm = _read_frontmatter(path)
+                title = fm.get("title") if isinstance(fm.get("title"), str) else ""
+                base = os.path.splitext(fn)[0]
+                is_match = want in (_slug(title), _slug(base)) or (
+                    want and title and want.replace("-", "") in _slug(title).replace("-", ""))
+                if not is_match:
+                    continue
+                typ = fm.get("type") if isinstance(fm.get("type"), str) else ""
+                sf = [s for s in (fm.get("source_files") or []) if isinstance(s, str) and s.strip()]
+                usf = [s for s in (fm.get("ui_source_files") or []) if isinstance(s, str) and s.strip()]
+                score = (2 if "aggregate" in typ.lower() else 0) + (1 if _slug(base) == want else 0)
+                cand = {"concept_path": os.path.relpath(path, os.getcwd()),
+                        "title": title or base, "type": typ, "source_files": sf,
+                        "ui_source_files": usf, "score": score}
+                if best is None or cand["score"] > best["score"]:
+                    best = cand
+    if not best:
+        print(json.dumps({"exists": "false", "aggregate": args.aggregate, "concept_path": "",
+                          "source_files": [], "ui_source_files": [], "ui_count": 0,
+                          "count": 0, "module_dir": ""}))
+        return 0
+    sf = best["source_files"]
+    usf = best.get("ui_source_files") or []
+    # Common directory prefix of the SERVICE source files = the aggregate's module dir.
+    # The UI half is deliberately excluded: a separable frontend shares no prefix with
+    # the service tree, so folding it in would collapse module_dir to the repo root.
+    module_dir = ""
+    if sf:
+        common = os.path.commonpath([s.replace("\\", "/") for s in sf]) if len(sf) > 1 else os.path.dirname(sf[0])
+        module_dir = common
+    print(f"Concept for {args.aggregate}: {best['concept_path']} "
+          f"({len(sf)} source file(s), {len(usf)} ui file(s), "
+          f"module {module_dir or '-'})", file=sys.stderr)
+    print(json.dumps({
+        "exists": "true", "aggregate": args.aggregate, "concept_path": best["concept_path"],
+        "title": best["title"], "type": best["type"],
+        "source_files": sf, "count": len(sf), "module_dir": module_dir,
+        # The slice's UI surface, listed apart so each lane's reverse step reads its
+        # own files. Empty on a backend-only slice.
+        "ui_source_files": usf, "ui_count": len(usf),
+    }))
+    return 0
+
+
+def cmd_list_aggregates(args):
+    """Enumerate the OKF bundle's Aggregate concepts — the brownfield FEATURE MAP.
+    This is the selectable feature list `select-feature` offers in a brownfield
+    repo (the discovered aggregates), as opposed to only the specs/ sub-folders.
+
+    Each aggregate → its candidate specs/<Feature> slice name (PascalCase, the id
+    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.
+    """
+    bundle = os.path.abspath(args.bundle)
+    present = os.path.isdir(bundle)
+    by_name = {}
+    if present:
+        for dirpath, dirnames, filenames in os.walk(bundle):
+            dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+            for fn in sorted(filenames):
+                if not fn.endswith(".md") or fn in ("index.md", "log.md"):
+                    continue
+                path = os.path.join(dirpath, fn)
+                fm = _read_frontmatter(path)
+                typ = fm.get("type") if isinstance(fm.get("type"), str) else ""
+                if "aggregate" not in typ.lower():
+                    continue
+                title = fm.get("title") if isinstance(fm.get("title"), str) else ""
+                base = os.path.splitext(fn)[0]
+                name = _pascal(title or base)
+                if not name:
+                    continue
+                sf = [s for s in (fm.get("source_files") or []) if isinstance(s, str) and s.strip()]
+                cand = {
+                    "name": name,
+                    "title": title or base,
+                    "slug": _slug(name),
+                    "concept_path": os.path.relpath(path, os.getcwd()),
+                    "type": typ,
+                    "source_file_count": len(sf),
+                }
+                # Dedup by the case-insensitive feature name; a filename-slug match
+                # to the wanted id, or a richer source set, wins the tie.
+                key = name.lower()
+                prev = by_name.get(key)
+                if prev is None or (
+                    (_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())
+    print(f"OKF aggregates in {args.bundle}: {len(aggs)} "
+          f"({', '.join(a['name'] for a in aggs) or '-'})", file=sys.stderr)
+    print(json.dumps({
+        "aggregates": aggs, "count": len(aggs),
+        "bundle": args.bundle, "bundle_present": "true" if present else "false",
+    }))
+    return 0
+
+
+def cmd_validate(args):
+    validator = os.path.join(HERE, "validate_okf.py")
+    if not os.path.isfile(validator):
+        print(json.dumps({"result": "ERROR", "conformant": "false",
+                          "errors": [f"validator not found: {validator}"], "warnings": [],
+                          "concepts": 0}))
+        return 1
+    if not os.path.isdir(args.bundle):
+        print(json.dumps({"result": "ERROR", "conformant": "false",
+                          "errors": [f"bundle dir not found: {args.bundle}"],
+                          "warnings": [], "concepts": 0}))
+        return 1
+    cmd = [sys.executable, validator, args.bundle, "--json"]
+    if args.repo_root:
+        cmd += ["--repo-root", args.repo_root]
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    try:
+        # validate_okf.py --json emits one pretty-printed (multi-line) object.
+        raw = proc.stdout.strip()
+        data = json.loads(raw[raw.index("{"):])
+    except Exception:
+        print(json.dumps({"result": "ERROR", "conformant": "false",
+                          "errors": [f"validator emitted no JSON: {proc.stdout[:300]} "
+                                     f"{proc.stderr[:300]}"], "warnings": [], "concepts": 0}))
+        return 1
+    # Mirror validate_okf's human report to stderr for the operator.
+    print(f"OKF validation of {args.bundle}: {data.get('result')} "
+          f"({data.get('concepts')} concepts, {len(data.get('errors', []))} errors, "
+          f"{len(data.get('warnings', []))} warnings)", file=sys.stderr)
+    for e in data.get("errors", []):
+        print(f"  ERROR   {e}", file=sys.stderr)
+    for w in data.get("warnings", []):
+        print(f"  WARNING {w}", file=sys.stderr)
+    data["conformant"] = "false" if data.get("errors") else "true"
+    print(json.dumps(data))
+    return 1 if data.get("errors") else 0
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Brownfield inventory scanner + OKF validator bridge.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    ps = sub.add_parser("scan", help="Scan a brownfield repo; emit the JSON inventory substrate.")
+    ps.add_argument("--root", help="Codebase to inventory (default: CWD; git history scoped to it).")
+    ps.add_argument("--out", help="Substrate JSON path (default: <root>/.appweaver/inventory/inventory.json).")
+    ps.add_argument("--bundle", help="OKF bundle dir to check for existing curation (default: <root>/knowledge).")
+    ps.add_argument("--config", help="okf-config.yml whose exclude: list is honored.")
+    ps.add_argument("--service-root", dest="service_root", default="",
+                    help="The service lane's declared source path. Backend signals are "
+                         "derived from this subtree only.")
+    ps.add_argument("--ui-root", dest="ui_root", default="",
+                    help="The UI lane's declared source path. Frontend signals are derived "
+                         "from this subtree only, and it is excluded from the backend's — "
+                         "so neither lane's substrate carries the other's files.")
+    ps.set_defaults(func=cmd_scan)
+
+    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).")
+    pc.set_defaults(func=cmd_concept)
+
+    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.set_defaults(func=cmd_list_aggregates)
+
+    pv = sub.add_parser("validate", help="Run the OKF v0.1 conformance checker on a bundle.")
+    pv.add_argument("--bundle", required=True, help="OKF bundle dir to validate.")
+    pv.add_argument("--repo-root", help="Repo root for resolving source_files (default: nearest .git).")
+    pv.set_defaults(func=cmd_validate)
+
+    args = ap.parse_args()
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())