aw-spec-cli 0.1.3 → 0.1.5

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

@@ -0,0 +1,683 @@
+#!/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 platform/AppWeaver.Component.Spec/Brownfield-Pipeline.my-ref.md).
+It scans an existing ("brownfield") codebase and emits a factual JSON substrate
+that the /aw-spec-orch 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.
+  * 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,
+              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|\.aw-spec|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)
+
+# 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 /aw-spec-orch 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
+
+
+def bundle_state(bundle_dir):
+    """How many concept .md files a candidate bundle already holds (the OKF
+    generate guard: a non-empty bundle means /aw-spec-orch 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 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, ".aw-spec", "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),
+    }
+    signals = aggregate_signals(files, churn_map)
+    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,
+        "language_histogram": lang_hist,
+        "top_level_dirs": top_level_dirs,
+        **{k: v["items"] for k, v in cats.items()},
+        "aggregate_signals": signals,
+        "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)
+    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),
+        "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()]
+                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, "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": [], "count": 0, "module_dir": ""}))
+        return 0
+    sf = best["source_files"]
+    # Common directory prefix of the source files = the aggregate's module dir.
+    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), 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,
+    }))
+    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>/.aw-spec/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.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())