aw-spec-cli 0.1.7 → 0.1.9

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

@@ -0,0 +1,1330 @@
+#!/usr/bin/env python3
+"""aw-xref.py — deterministic cross-reference (OKF dependency) substrate.
+
+Maintains the cross-slice dependency edges INSIDE the OKF knowledge bundle, so a
+change to one aggregate can see every other aggregate that uses it (its blast
+radius) without a central graph. Two mirrored tables live in each concept:
+
+  • Depends-On     (FORWARD)  in the USING aggregate's concept — its own deps + the
+                              prune index.
+  • Cross-References (REVERSE) in the USED aggregate's concept — its blast radius,
+                              reviewed at CR time.
+
+Edges are DERIVED deterministically from the using aggregate's design.md — the §1
+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
+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).
+
+RECONCILE-ON-WRITE: every `record` first strips ALL rows authored by the using
+slice from every concept, then re-adds its current edges — so a dropped
+dependency self-heals (no stale reverse edge). Rows are keyed by the using slice.
+
+Subcommands, each printing a single JSON object as the LAST stdout line (human
+summary to STDERR so it never corrupts the JSON contract):
+
+  deps    --design <design.md> --aggregate X [--root DIR] [--specs specs] [--bundle knowledge]
+      -> the internal edges X declares. {aggregate, edges[], edge_count, known[], root}
+
+  record  --using X --design <design.md> [--origin greenfield|reverse-engineered]
+          [--date YYYY-MM-DD] [--root DIR] [--specs specs] [--bundle knowledge]
+      -> reconcile X's edges across the bundle (stub used concepts if missing, prune
+         stale rows, upsert current rows, rewrite X's Depends-On).
+         {using, origin, edges[], edge_count, wrote[], stubbed[], pruned, concept, root}
+
+  list    --aggregate Y [--root DIR] [--bundle knowledge]
+      -> Y's blast radius (who uses Y). {aggregate, concept, users[], count, root}
+
+  concept-upsert --aggregate X [--source-files a,b,c] [--merge] [--title T] [--description D]
+          [--origin greenfield|reverse-engineered] [--root DIR] [--bundle knowledge]
+      -> create/update X's OWN concept (frontmatter type/title/source_files), PRESERVING
+         its body — never clobbers the Cross-References other slices wrote. --merge UNIONs
+         source_files (CR deltas) instead of replacing. source_files is written as a FLAT
+         list, path-grouped by the code's OWN folders via YAML comment headers (adaptive —
+         see _group_source_files), so the listing mirrors the real architecture.
+         {aggregate, concept, created, source_file_count, root}
+
+  concept-overview --aggregate X (--text PROSE | --text-file F) [--root DIR] [--bundle knowledge]
+      -> splice model-authored prose into X's `## Overview` ONLY (the one section a
+         deterministic script cannot write). Empty/placeholder text is a no-op.
+         Run AFTER concept-upsert. {aggregate, concept, written, root}
+
+  concept-paths --aggregate X [--root DIR] [--bundle knowledge]
+      -> READ-ONLY: the slice's source files, from its concept's `source_files`. The
+         answer the executable phases (build/run/analyze-slice) need for "which files is
+         this slice made of", replacing the retired `design-paths` fence scan. `paths` is
+         filtered to what EXISTS on disk (safe to feed build_context); `missing` reports
+         declared-but-absent files (real index drift). Never stubs a concept; no concept
+         is an empty answer, not an error.
+         {aggregate, concept, found, paths[], count, csv, declared[], declared_count,
+          missing[], missing_count, root}
+
+  validate [--prune] [--root DIR] [--bundle knowledge]
+      -> drift check beyond reconcile-on-write. reverse-orphan = a Cross-References row with
+         no backing Depends-On (stale; --prune removes it); forward-orphan = a Depends-On
+         row with no matching Cross-References (reported; fix by re-record).
+         {orphans[], orphan_count, reverse_orphans, forward_orphans, pruned, ok, root}
+
+  log [--note TEXT] [--date YYYY-MM-DD] [--root DIR] [--bundle knowledge]
+      -> append a commit-anchored entry to the bundle log.md (OKF §7 freshness journal).
+         No-op when there is no bundle or no git commit. {logged, commit, date, log, root}
+
+Only the standard library is used. Usage: aw-xref.py <sub> [options]
+"""
+
+import argparse
+import datetime
+import json
+import os
+import re
+import subprocess
+import sys
+
+# ───────────────────────────── canonical shapes ────────────────────────────
+OVERVIEW_HEADING = "## Overview"
+DEPS_HEADING = "## Depends-On"
+XREF_HEADING = "## Cross-References"
+DEPS_HEADER = ["Target", "Via", "Kind"]
+XREF_HEADER = ["Using slice", "Uses (via)", "Kind", "Origin", "Recorded"]
+DEPS_COMMENT = (
+    "<!-- FORWARD edges — sibling aggregates this one references, derived from "
+    "design.md §1 (the model section) + its External integrations table. Prune index; "
+    "regenerated every implement/adopt. Do not hand-edit. -->"
+)
+XREF_COMMENT = (
+    "<!-- REVERSE edges — sibling aggregates that USE this one (its blast radius). "
+    "Each row written by the using slice's implement/adopt (reconcile-on-write). "
+    "Reviewed at CR time. Do not hand-edit. -->"
+)
+RESERVED = {"index.md", "log.md"}
+
+# A Cross-References "Using slice" cell that is safe to hand to a VSTest --filter (and a
+# real aggregate name, not the "_(none observed…)_" placeholder or a malformed cell).
+_IDENT_RE = re.compile(r"^[A-Za-z][A-Za-z0-9._-]*$")
+
+# ─────────────────── source_files architecture grouping ────────────────────
+# `source_files` stays a FLAT YAML list — validate_okf (E2/W6), the aw-inventory
+# concept resolver and the source-map fidelity check all key on that shape, and
+# both lenient frontmatter parsers in the toolchain only understand scalars +
+# flat block lists. So the grouping is emitted as YAML comment headers, which
+# PyYAML and both lenient parsers skip: readable grouping, zero schema change, no
+# duplicated path list. Regenerated on every write (comments are lost on read and
+# re-derived deterministically), so it is idempotent.
+#
+# ADAPTIVE, PATH-DERIVED grouping. Each header is DERIVED FROM THE CODE'S OWN
+# FOLDERS, so the listing mirrors whatever architecture the code actually uses —
+# the layer folders of a vertical-slice module (Domain / Features / Persistence
+# …), the tier projects of an n-tier / layered app (DataAccess / BusinessLogic /
+# Web …), or a legacy layout as-is. Nothing is forced into a fixed
+# Domain/Application/UI taxonomy the code never had (this replaced the greenfield
+# LAYER_RULES). That keeps the knowledge bundle honest for BOTH pipelines —
+# brownfield especially, where the CODE, not a template, is the source of truth.
+#
+# HOW (see _group_source_files): take the longest common directory prefix across
+# the concept's own NON-test files; each file's group is the FIRST path segment
+# AFTER that shared prefix — i.e. what actually VARIES across the files, which is
+# the architectural axis (the layer folder in a vertical slice, the tier project
+# in an n-tier app). Test files are a cross-cutting concern → one `tests` bucket;
+# repo-root files (no shared structure to derive a group from) → `(root)`.
+
+# A source path is a test if it lives under a test root OR is a *Tests / *.spec /
+# *.test file — held out of the common-prefix so it never distorts the axis.
+_TEST_RE = re.compile(
+    r"(^|/)tests?/|(^|/)[^/]*Tests?\.(cs|ts|tsx|js|py)$|\.(spec|test)\.[jt]sx?$",
+    re.IGNORECASE,
+)
+_TESTS_GROUP = "tests"
+_ROOT_GROUP = "(root)"
+
+
+def _is_test(path):
+    return bool(_TEST_RE.search(path or ""))
+
+
+def _dir_parts(path):
+    """Directory segments of a repo-relative path ([] for a repo-root file)."""
+    d = os.path.dirname(path or "")
+    return [p for p in d.split("/") if p] if d else []
+
+
+def _common_prefix(parts_list):
+    """Longest shared leading run of path segments across every entry ([] if none)."""
+    if not parts_list:
+        return []
+    common = list(parts_list[0])
+    for parts in parts_list[1:]:
+        i = 0
+        while i < len(common) and i < len(parts) and common[i] == parts[i]:
+            i += 1
+        del common[i:]
+        if not common:
+            break
+    return common
+
+
+def _group_source_files(files):
+    """[(group, [path, …]), …] with each group DERIVED from the file's own path
+    (see the ADAPTIVE grouping note). Files are sorted for a stable, diff-friendly
+    listing; groups appear in first-seen order over that sorted list, with the
+    cross-cutting `tests` and `(root)` buckets pinned last. Empty groups never
+    appear."""
+    files = sorted(files)
+    prod = [f for f in files if not _is_test(f)]
+    # Common prefix over files that actually sit in a directory — a repo-root file
+    # (parts == []) is a cross-cutting outlier and must not collapse the shared
+    # prefix the real module files derive their groups from.
+    prefix = _common_prefix([p for p in (_dir_parts(f) for f in prod) if p])
+    n = len(prefix)
+
+    order, buckets = [], {}
+    for f in files:
+        if _is_test(f):
+            g = _TESTS_GROUP
+        else:
+            parts = _dir_parts(f)
+            if not parts:
+                g = _ROOT_GROUP                      # repo-root file, no shared axis
+            else:
+                rest = parts[n:]
+                # first segment past the shared prefix = the architectural axis;
+                # a file sitting directly in the shared folder → that folder's leaf
+                g = rest[0] if rest else (prefix[-1] if prefix else _ROOT_GROUP)
+        if g not in buckets:
+            buckets[g] = []
+            order.append(g)
+        buckets[g].append(f)
+
+    tail = [g for g in (_TESTS_GROUP, _ROOT_GROUP) if g in buckets]
+    head = [g for g in order if g not in tail]
+    return [(g, buckets[g]) for g in head + tail]
+
+
+# ───────────────────────────── small helpers ───────────────────────────────
+def _root(arg):
+    return os.path.abspath(arg) if arg else os.getcwd()
+
+
+def _rel(path, root):
+    return os.path.relpath(path, root).replace(os.sep, "/")
+
+
+def _emit(obj):
+    print(json.dumps(obj))
+
+
+def _slug(s):
+    s = re.sub(r"[^a-z0-9]+", "-", (s or "").lower())
+    return re.sub(r"-{2,}", "-", s).strip("-")
+
+
+def _read(path):
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            return fh.read()
+    except OSError:
+        return ""
+
+
+def _write(path, text):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(text)
+
+
+def _today(arg_date):
+    if arg_date and arg_date.strip():
+        return arg_date.strip()
+    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."""
+    return os.path.basename(os.path.normpath(fd)) if fd else ""
+
+
+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
+    absolute path to root and normalise to POSIX, so source_files stays repo-relative
+    (what validate_okf and the concept resolver expect)."""
+    raw = (raw or "").strip()
+    if not raw:
+        return []
+    items = []
+    if raw.startswith("["):
+        try:
+            data = json.loads(raw)
+            if isinstance(data, list):
+                for it in data:
+                    if isinstance(it, str):
+                        items.append(it)
+                    elif isinstance(it, dict):
+                        items.append(it.get("path") or it.get("file") or "")
+        except json.JSONDecodeError:
+            items = [s for s in raw.strip("[]").split(",")]
+    else:
+        items = raw.split(",")
+    out, seen = [], set()
+    for s in items:
+        s = (s or "").strip().strip('"').strip("'")
+        if not s:
+            continue
+        if os.path.isabs(s):
+            s = os.path.relpath(s, root)
+        s = s.replace(os.sep, "/")
+        if s not in seen:
+            seen.add(s)
+            out.append(s)
+    return out
+
+
+def _detect_origin(design_path):
+    """`--origin auto`: read the slice's provenance from its design.md head — adopt
+    stamps `origin: reverse-engineered` (a CR on a brownfield slice keeps that), else
+    greenfield. Lets finalize-delta refresh edges without knowing the pipeline."""
+    head = _read(design_path)[:2048]
+    m = re.search(r"origin:\s*(reverse-engineered|migrated|greenfield)", head, re.IGNORECASE)
+    if m:
+        return m.group(1).lower()
+    if re.search(r"reverse-engineered", head, re.IGNORECASE):
+        return "reverse-engineered"
+    return "greenfield"
+
+
+def _render_impact_md(aggregate, users):
+    """A human blast-radius report (cr writes it to changes/<cr>/impact.md for review)."""
+    lines = [
+        f"# Cross-Reference Impact — {aggregate}",
+        "",
+        f"Downstream slices that USE **{aggregate}** — its blast radius. A change to "
+        f"{aggregate} may ripple into these; review or re-verify each before finalizing.",
+        "",
+        "| Using slice | Uses (via) | Kind | Origin | Recorded |",
+        "| --- | --- | --- | --- | --- |",
+    ]
+    for u in users:
+        lines.append(f"| {u['using']} | {u['via']} | {u['kind']} | {u['origin']} | {u['recorded']} |")
+    if not users:
+        lines.append("| _(none — no slice references this aggregate)_ | | | | |")
+    return "\n".join(lines) + "\n"
+
+
+# ─────────────────────────── frontmatter I/O ───────────────────────────────
+def _read_fm(text):
+    """Return (frontmatter dict, body). Scalars are strings; block lists are lists.
+    Mirrors aw-inventory.py's lenient parser so the two agree without a YAML dep."""
+    if not text.startswith("---"):
+        return {}, text
+    lines = text.splitlines()
+    end = next((i for i in range(1, len(lines)) if lines[i].strip() == "---"), None)
+    if end is None:
+        return {}, text
+    fm, 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()
+            fm[key] = val.strip("'\"") if val else []
+        elif key and re.match(r"^\s*-\s+", ln):
+            if not isinstance(fm.get(key), list):
+                fm[key] = []
+            fm[key].append(re.sub(r"^\s*-\s+", "", ln).strip().strip("'\""))
+    return fm, "\n".join(lines[end + 1:])
+
+
+def _render_fm(fm):
+    order = ["type", "title", "description", "origin", "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:
+        v = fm[k]
+        if isinstance(v, list):
+            out.append(f"{k}:")
+            if k in ("source_files", "ui_source_files") and v:
+                # flat list, path-grouped by the code's own folders (see _group_source_files)
+                for layer, items in _group_source_files(v):
+                    out.append(f"  # {layer}")
+                    out.extend(f"  - {it}" for it in items)
+            else:
+                for it in v:
+                    out.append(f"  - {it}")
+        else:
+            out.append(f"{k}: {v}")
+    out.append("---")
+    return "\n".join(out)
+
+
+# ─────────────────────── markdown section / table I/O ───────────────────────
+def _render_table(header, rows):
+    out = ["| " + " | ".join(header) + " |",
+           "| " + " | ".join(["---"] * len(header)) + " |"]
+    for r in rows:
+        cells = (list(r) + [""] * len(header))[:len(header)]
+        out.append("| " + " | ".join(cells) + " |")
+    return "\n".join(out)
+
+
+def _render_section(heading, comment, header, rows):
+    return f"{heading}\n\n{comment}\n\n{_render_table(header, rows)}\n"
+
+
+def _section_text(text, heading):
+    """The lines from `heading` up to (not including) the next `## ` heading."""
+    lines = text.splitlines()
+    start = next((i for i, ln in enumerate(lines) if ln.strip() == heading), None)
+    if start is None:
+        return ""
+    end = len(lines)
+    for j in range(start + 1, len(lines)):
+        if lines[j].startswith("## "):
+            end = j
+            break
+    return "\n".join(lines[start:end])
+
+
+def _table_data_rows(section_text):
+    """Data rows (list of trimmed cell-lists) under a section: skips the header row,
+    the |---| separator, HTML comments (incl. commented example rows), and blanks."""
+    rows, in_comment, header_seen = [], False, False
+    for ln in section_text.splitlines():
+        s = ln.strip()
+        if in_comment:
+            if "-->" in s:
+                in_comment = False
+            continue
+        if s.startswith("<!--"):
+            if "-->" not in s:
+                in_comment = True
+            continue
+        if not s.startswith("|"):
+            continue
+        cells = [c.strip() for c in s.strip("|").split("|")]
+        joined = "".join(cells)
+        if not header_seen:
+            header_seen = True          # first pipe row = header
+            continue
+        if joined == "" or set(joined) <= set("-: "):
+            continue                    # separator or empty
+        rows.append(cells)
+    return rows
+
+
+def _replace_section(text, heading, new_body, before=None):
+    """Replace the `heading` section (heading→next `## `) with new_body. If the heading
+    is absent, insert it before the `before` heading when given, else append. Only the
+    machine sections are ever passed here, so human prose elsewhere is preserved."""
+    lines = text.splitlines()
+    start = next((i for i, ln in enumerate(lines) if ln.strip() == heading), None)
+    new_lines = new_body.rstrip("\n").splitlines()
+    if start is None:
+        anchor = (next((i for i, ln in enumerate(lines) if ln.strip() == before), None)
+                  if before else None)
+        if anchor is not None:
+            merged = lines[:anchor] + new_lines + [""] + lines[anchor:]
+            return "\n".join(merged).rstrip("\n") + "\n"
+        base = text.rstrip("\n")
+        return (base + "\n\n" + "\n".join(new_lines) + "\n") if base else ("\n".join(new_lines) + "\n")
+    end = len(lines)
+    for j in range(start + 1, len(lines)):
+        if lines[j].startswith("## "):
+            end = j
+            break
+    merged = lines[:start] + new_lines + [""] + lines[end:]
+    return "\n".join(merged).rstrip("\n") + "\n"
+
+
+# ───────────────────────── bundle / concept resolution ──────────────────────
+def _ensure_bundle(bundle_abs):
+    os.makedirs(bundle_abs, exist_ok=True)
+    idx = os.path.join(bundle_abs, "index.md")
+    if not os.path.isfile(idx):
+        _write(idx, "---\nokf_version: 0.1\n---\n\n# Knowledge Bundle\n\n"
+                    "OKF v0.1 knowledge bundle — one concept per aggregate.\n")
+
+
+def _canonical_concept_path(bundle_abs, name):
+    slug = _slug(name)
+    return os.path.join(bundle_abs, slug, slug + ".md")
+
+
+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)
+    best, best_score = None, -1
+    if not os.path.isdir(bundle_abs):
+        return None
+    for dirpath, dirnames, filenames in os.walk(bundle_abs):
+        dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+        for fn in filenames:
+            if not fn.endswith(".md") or fn in RESERVED:
+                continue
+            path = os.path.join(dirpath, fn)
+            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)):
+                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)
+            if score > best_score:
+                best, best_score = path, score
+    return best
+
+
+def _skeleton_concept(name, origin, source_files, description):
+    fm = {
+        "type": "aggregate",
+        "title": name,
+        "description": description or f"{name} aggregate.",
+        "origin": origin or "greenfield",
+        "source_files": list(source_files or []),
+    }
+    overview = f"[overview of the {name} aggregate]"
+    body = (
+        f"# {name}\n\n"
+        f"## Overview\n\n{overview}\n\n"
+        + _render_section(DEPS_HEADING, DEPS_COMMENT, DEPS_HEADER, []) + "\n"
+        + _render_section(XREF_HEADING, XREF_COMMENT, XREF_HEADER, [])
+    )
+    return _render_fm(fm) + "\n\n" + body.rstrip("\n") + "\n"
+
+
+def _ensure_dir_index(concept_path, name):
+    d = os.path.dirname(concept_path)
+    idx = os.path.join(d, "index.md")
+    if not os.path.isfile(idx):
+        base = os.path.splitext(os.path.basename(concept_path))[0]
+        _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."""
+    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, [], ""))
+    _ensure_dir_index(path, name)
+    stubbed.append(name)
+    return path
+
+
+# ──────────────────────────── design.md parsing ────────────────────────────
+def _section(text, start_pat, end_pat):
+    lines, out, started = text.splitlines(), [], False
+    for ln in lines:
+        if not started:
+            if re.match(start_pat, ln):
+                started, _ = True, out.append(ln)
+            continue
+        if re.match(end_pat, ln):
+            break
+        out.append(ln)
+    return "\n".join(out)
+
+
+def _known_aggregates(root, specs, bundle_abs):
+    """The project's aggregate registry: specs/<dir> names ∪ bundle concept titles/dirs.
+    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)
+    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(".")]
+            for fn in filenames:
+                if not fn.endswith(".md") or fn in RESERVED:
+                    continue
+                fm, _ = _read_fm(_read(os.path.join(dirpath, fn)))
+                title = fm.get("title") if isinstance(fm.get("title"), str) else ""
+                if title:
+                    known.setdefault(_slug(title), title)
+    return known
+
+
+def _design_edges(text, aggregate, known):
+    """Internal edges the aggregate declares. `known` = {slug: name}; self excluded."""
+    self_slug = _slug(aggregate)
+    edges, seen = [], set()
+
+    def add(target_name, via, kind):
+        tslug = _slug(target_name)
+        key = (tslug, via, kind)
+        if tslug == self_slug or tslug not in known or key in seen:
+            return
+        seen.add(key)
+        edges.append({"target": known[tslug], "via": via, "kind": kind})
+
+    # §1 (the MODEL section) — entity-ref edges: `<Name>Id` and id<Name> attribute
+    # types. Both the forward and brownfield design templates keep the domain/data
+    # model at "## 1." (a neutral, architecture-agnostic anchor), so this scan is
+    # structure-independent.
+    sec1 = _section(text, r"^##\s+1\.", r"^##\s+\d")
+    ref_names = set(re.findall(r"`([A-Z][A-Za-z0-9]*)Id`", sec1))
+    ref_names |= set(re.findall(r"id<\s*([A-Z][A-Za-z0-9]*)\s*>", sec1))
+    for name in sorted(ref_names):
+        add(name, name + "Id", "entity-ref")
+
+    # External integrations — contract edges: External-system cell names a known
+    # aggregate, keyed by the IC- ids in the Serves column. Located by HEADING
+    # KEYWORD (any `###` heading containing "integration"), not a fixed section
+    # number, so it matches both the forward design's "### 4.2 External integrations"
+    # and a brownfield design's code-derived "### 2.x External Integrations …".
+    sec42 = _section(text, r"(?i)^###\s+.*integration", r"^(###\s|##\s)")
+    for row in _table_data_rows(sec42):
+        if len(row) < 2:
+            continue
+        external = row[1]
+        serves = row[-1]
+        ics = re.findall(r"IC-\d+", serves)
+        for tslug, name in known.items():
+            if tslug == self_slug:
+                continue
+            if re.search(r"\b" + re.escape(name) + r"\b", external, re.IGNORECASE):
+                for ic in (ics or ["contract"]):
+                    add(name, ic, "contract")
+    return edges
+
+
+# ───────────────────────────── xref row I/O ────────────────────────────────
+def _read_xref_rows(path):
+    return _table_data_rows(_section_text(_read(path), XREF_HEADING))
+
+
+def _read_deps_rows(path):
+    return _table_data_rows(_section_text(_read(path), DEPS_HEADING))
+
+
+# ─────────────── reverse-edge closure — an aggregate's referrers ────────────
+def _xref_users(aggregate, bundle_abs):
+    """Direct 'who refers to me' — the first column (Using slice) of aggregate's
+    Cross-References rows, kept only when it is an identifier, so the placeholder
+    row and any malformed cell are dropped and the names are filter-safe."""
+    path = _resolve_concept(aggregate, bundle_abs)
+    if not path:
+        return []
+    return [r[0].strip() for r in _read_xref_rows(path)
+            if r and _IDENT_RE.match((r[0] or "").strip())]
+
+
+def _referrer_closure(aggregate, bundle_abs):
+    """Transitive 'who refers to me' blast radius: BFS over the reverse
+    (Cross-References) edges. self is excluded, cycles terminate via the seen set,
+    result sorted for a stable filter. Resolves each node's concept on demand —
+    O(nodes) walks, fine for a one-shot CLI even at hundreds of aggregates."""
+    seen, frontier = set(), [aggregate]
+    while frontier:
+        current = frontier.pop()
+        for user in _xref_users(current, bundle_abs):
+            if user in seen or user == aggregate:
+                continue
+            seen.add(user)
+            frontier.append(user)
+    return sorted(seen)
+
+
+def _concept_title(path):
+    fm, _ = _read_fm(_read(path))
+    t = fm.get("title") if isinstance(fm.get("title"), str) else ""
+    return t or os.path.splitext(os.path.basename(path))[0]
+
+
+def _git_head_short(root):
+    """Short HEAD sha for the OKF log.md commit anchor (OKF §7 / validate_okf E4);
+    empty when not a git repo or no commit yet (then log is skipped, never written broken)."""
+    try:
+        r = subprocess.run(["git", "-C", root, "rev-parse", "--short", "HEAD"],
+                           capture_output=True, text=True, timeout=5)
+        sha = r.stdout.strip()
+        return sha if r.returncode == 0 and re.fullmatch(r"[0-9a-fA-F]{7,40}", sha) else ""
+    except Exception:
+        return ""
+
+
+def _write_xref_rows(path, rows):
+    text = _read(path)
+    body = _render_section(XREF_HEADING, XREF_COMMENT, XREF_HEADER, rows)
+    _write(path, _replace_section(text, XREF_HEADING, body))
+
+
+def _write_deps_rows(path, rows):
+    text = _read(path)
+    body = _render_section(DEPS_HEADING, DEPS_COMMENT, DEPS_HEADER, rows)
+    _write(path, _replace_section(text, DEPS_HEADING, body))
+
+
+def _all_concepts(bundle_abs):
+    out = []
+    if not os.path.isdir(bundle_abs):
+        return out
+    for dirpath, dirnames, filenames in os.walk(bundle_abs):
+        dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+        for fn in filenames:
+            if fn.endswith(".md") and fn not in RESERVED:
+                out.append(os.path.join(dirpath, fn))
+    return out
+
+
+# ─────────────────────────────── 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:
+        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:
+        print("[xref] record: --design or --feature-dir required", file=sys.stderr)
+        _emit({"error": "design-required", "root": root})
+        return 2
+    design_path = design_arg if os.path.isabs(design_arg) else os.path.join(root, design_arg)
+
+    origin = args.origin or "greenfield"
+    if origin == "auto":
+        origin = _detect_origin(design_path)
+
+    known = _known_aggregates(root, args.specs, bundle_abs)
+    known.pop(using_slug, None)
+    edges = _design_edges(_read(design_path), using, known)
+
+    # RECONCILE-ON-WRITE, delete phase: strip every row this slice authored, anywhere.
+    pruned = 0
+    for cpath in _all_concepts(bundle_abs):
+        rows = _read_xref_rows(cpath)
+        kept = [r for r in rows if _slug(r[0]) != using_slug]
+        if len(kept) != len(rows):
+            pruned += len(rows) - len(kept)
+            _write_xref_rows(cpath, kept)
+
+    # Add phase: upsert this slice's current rows into each used concept (stub if missing).
+    wrote, stubbed = [], []
+    for e in edges:
+        ypath = _get_or_stub_concept(e["target"], bundle_abs, origin, stubbed)
+        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"]))]
+        rows.append([using, e["via"], e["kind"], origin, date])
+        _write_xref_rows(ypath, rows)
+        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)
+    _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
+
+
+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:
+        print("[xref] list: --aggregate or --feature-dir required", file=sys.stderr)
+        _emit({"error": "aggregate-required", "root": root})
+        return 2
+    path = _resolve_concept(aggregate, bundle_abs)
+    users = []
+    if path:
+        for r in _read_xref_rows(path):
+            users.append({
+                "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 "",
+            })
+    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))
+        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
+    # backward-compatible readers; the referrer_* fields are the clean, filter-ready set.
+    seen_d, direct = set(), []
+    for u in users:
+        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) "
+          f"— {', '.join(sorted({u['using'] for u in users})) or '(none)'}", file=sys.stderr)
+    _emit({"aggregate": aggregate, "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),
+           "referrer_count": len(direct), "referrer_closure_count": len(closure),
+           "indirect_count": max(0, len(closure) - len(direct))})
+    return 0
+
+
+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)
+    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)
+
+    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 ""))
+        _ensure_dir_index(path, aggregate)
+    else:
+        # Update frontmatter ONLY (source_files/description/origin); PRESERVE the body,
+        # which holds the Cross-References other slices wrote.
+        fm, body = _read_fm(_read(path))
+        fm.setdefault("type", "aggregate")
+        fm["title"] = fm.get("title") or aggregate
+        if source_files:
+            if args.merge:
+                # CR mode: {{files}} is only the delta's changed files — UNION with the
+                # slice's existing source_files, never replace (that would drop the rest).
+                existing = fm.get("source_files") if isinstance(fm.get("source_files"), list) else []
+                merged = list(existing)
+                for s in source_files:
+                    if s not in merged:
+                        merged.append(s)
+                fm["source_files"] = merged
+            else:
+                fm["source_files"] = source_files
+        elif "source_files" not in fm:
+            fm["source_files"] = []
+        if args.description:
+            fm["description"] = args.description
+        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
+        _ensure_bundle(bundle_abs)
+        _ensure_dir_index(path, aggregate)
+
+    print(f"[xref] concept {aggregate}: {'created' if created else 'updated'} "
+          f"({len(source_files)} source file(s)) — {_rel(path, root)}", file=sys.stderr)
+    _emit({"aggregate": aggregate, "concept": _rel(path, root), "created": "true" if created else "false",
+           "source_file_count": len(source_files), "root": root})
+    return 0
+
+
+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
+    the whole file, so the Cross-References rows other slices wrote can never be lost.
+    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)
+    if not aggregate:
+        print("[xref] concept-overview: --aggregate or --feature-dir required", file=sys.stderr)
+        _emit({"error": "aggregate-required", "root": root})
+        return 2
+
+    text = _read(args.text_file) if args.text_file else (args.text or "")
+    # Strip anything the model may have wrapped the prose in: a repeated heading,
+    # code fences, and the placeholder itself (an empty/placeholder answer = no-op).
+    text = re.sub(r"^\s*#{1,6}\s*Overview\s*$", "", text, flags=re.MULTILINE)
+    text = re.sub(r"^\s*```.*$", "", text, flags=re.MULTILINE).strip()
+    if not text or re.fullmatch(r"\[overview of the .*\]", text):
+        print(f"[xref] concept-overview {aggregate}: empty/placeholder text — left unchanged",
+              file=sys.stderr)
+        _emit({"aggregate": aggregate, "written": "false", "reason": "empty-or-placeholder",
+               "root": root})
+        return 0
+
+    path = _resolve_concept(aggregate, bundle_abs)
+    if path is None:
+        print(f"[xref] concept-overview: no concept for '{aggregate}' — run concept-upsert first",
+              file=sys.stderr)
+        _emit({"error": "concept-missing", "aggregate": aggregate, "root": root})
+        return 2
+
+    body = f"{OVERVIEW_HEADING}\n\n{text}\n"
+    _write(path, _replace_section(_read(path), OVERVIEW_HEADING, body, before=DEPS_HEADING))
+    print(f"[xref] concept-overview {aggregate}: written ({len(text)} chars) — {_rel(path, root)}",
+          file=sys.stderr)
+    _emit({"aggregate": aggregate, "concept": _rel(path, root), "written": "true", "root": root})
+    return 0
+
+
+# ──────────────────────── concept-paths (read-only) ────────────────────────
+def cmd_concept_paths(args):
+    """The slice's source files, read from its OKF concept — the REPLACEMENT for the
+    retired `design-paths` fence scan.
+
+    The executable phases (build / run / analyze-slice) all need the same answer: which
+    files is this slice made of, so a fix loop can be handed them. That answer used to be
+    parsed out of ```lang path=… fences in a four-document design — a convention the
+    tech-agnostic single design.md no longer carries (and whose glob never matched
+    design.md anyway). The concept's `source_files` is the maintained answer now:
+    implement / implement-delta / adopt write it, analyze-slice merges fix-loop files in.
+
+    STRICTLY READ-ONLY. Unlike record / concept-upsert this never stubs a missing concept:
+    a query must not mutate the bundle. No concept — greenfield before the first implement,
+    or no bundle at all — is a legitimate EMPTY answer, not an error. It exits 0 with
+    paths=[] so every caller soft-continues exactly as it did when the fence scan found
+    nothing, which is what keeps this greenfield-safe.
+
+    `paths` is filtered to files that exist on disk. It feeds build_context, which drops
+    missing entries silently anyway, so filtering here makes the reported count honest.
+    Declared-but-absent files are reported separately as `missing` — that is real index
+    drift (a file deleted or moved without re-running the owning slice), surfaced rather
+    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)
+    if not aggregate:
+        print("[xref] concept-paths: --aggregate or --feature-dir required", file=sys.stderr)
+        _emit({"error": "aggregate-required", "root": root})
+        return 2
+
+    path = _resolve_concept(aggregate, bundle_abs)
+    declared, existing, missing = [], [], []
+    if path:
+        fm, _ = _read_fm(_read(path))
+        raw = fm.get("source_files")
+        # _read_fm gives a list for a block list, "" for an empty scalar; the `# Layer`
+        # group headers _render_fm writes are comments and are already skipped by it.
+        items = raw if isinstance(raw, list) else ([raw] if isinstance(raw, str) and raw else [])
+        seen = set()
+        for s in items:
+            s = (s or "").strip().strip('"').strip("'").replace(os.sep, "/")
+            if not s or s in seen:
+                continue
+            seen.add(s)
+            declared.append(s)
+            target = s if os.path.isabs(s) else os.path.join(root, s)
+            (existing if os.path.isfile(target) else missing).append(s)
+
+    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)
+    _emit({"aggregate": aggregate, "concept": _rel(path, root) if path else "",
+           "found": bool(path), "paths": existing, "count": len(existing),
+           "csv": ",".join(existing), "declared": declared,
+           "declared_count": len(declared), "missing": missing,
+           "missing_count": len(missing), "root": root})
+    return 0
+
+
+# ─────────────────────────────── validate ──────────────────────────────────
+def cmd_validate(args):
+    """Cross-reference drift check (the safety net BEYOND reconcile-on-write). Pairs the
+    forward index (Depends-On) against the reverse index (Cross-References):
+      • reverse-orphan  — a Cross-References row (Y says "X uses me") with NO backing
+        Depends-On in X (X's concept gone, or X no longer declares the dep). Stale; safe
+        to prune (this is the user-facing orphan).
+      • forward-orphan  — a Depends-On row (X → Y) with NO matching Cross-References in Y
+        (a missing reverse edge). Reported only; the fix is `record --using X` (re-write
+        both), never deleting X's real declaration."""
+    root = _root(args.root)
+    bundle_abs = os.path.join(root, args.bundle)
+    info = {}
+    for cpath in _all_concepts(bundle_abs):
+        title = _concept_title(cpath)
+        info[cpath] = {
+            "title": title,
+            "slug": _slug(title),
+            "deps": [(d[0], d[1] if len(d) > 1 else "") for d in _read_deps_rows(cpath)],
+            "xrefs": [(x[0], x[1] if len(x) > 1 else "") for x in _read_xref_rows(cpath)],
+        }
+    slug_to_path = {}
+    for p, i in info.items():
+        slug_to_path.setdefault(i["slug"], p)
+
+    orphans = []
+    for ypath, yi in info.items():
+        for (using, via) in yi["xrefs"]:
+            xp = slug_to_path.get(_slug(using))
+            if xp is None:
+                orphans.append({"direction": "reverse", "concept": _rel(ypath, root),
+                                "aggregate": yi["title"], "using": using, "via": via,
+                                "reason": "using-slice has no concept"})
+            elif not any(_slug(t) == yi["slug"] and v == via for (t, v) in info[xp]["deps"]):
+                orphans.append({"direction": "reverse", "concept": _rel(ypath, root),
+                                "aggregate": yi["title"], "using": using, "via": via,
+                                "reason": "using-slice no longer declares this dependency"})
+    for xpath, xi in info.items():
+        for (target, via) in xi["deps"]:
+            yp = slug_to_path.get(_slug(target))
+            if yp is None:
+                orphans.append({"direction": "forward", "concept": _rel(xpath, root),
+                                "aggregate": xi["title"], "target": target, "via": via,
+                                "reason": "depends-on target has no concept"})
+            elif not any(_slug(u) == xi["slug"] and v == via for (u, v) in info[yp]["xrefs"]):
+                orphans.append({"direction": "forward", "concept": _rel(xpath, root),
+                                "aggregate": xi["title"], "target": target, "via": via,
+                                "reason": "used slice missing the reverse cross-reference"})
+
+    pruned = 0
+    if args.prune:
+        # Only reverse-orphans are safe to auto-remove (a stale reverse row). Forward-
+        # orphans mean a MISSING reverse edge — deleting X's real Depends-On would lose a
+        # true dependency; those are fixed by re-running record, not by prune.
+        rev = {}
+        for o in orphans:
+            if o["direction"] == "reverse":
+                rev.setdefault(o["concept"], set()).add((o["using"], o["via"]))
+        for crel, keys in rev.items():
+            cpath = os.path.join(root, crel)
+            rows = _read_xref_rows(cpath)
+            keep = [r for r in rows if (r[0], r[1] if len(r) > 1 else "") not in keys]
+            pruned += len(rows) - len(keep)
+            _write_xref_rows(cpath, keep)
+
+    rev_n = sum(1 for o in orphans if o["direction"] == "reverse")
+    fwd_n = len(orphans) - rev_n
+    print(f"[xref] validate: {len(orphans)} orphan(s) — {rev_n} reverse, {fwd_n} forward"
+          + (f"; pruned {pruned} reverse" if args.prune else ""), file=sys.stderr)
+    _emit({"orphans": orphans, "orphan_count": len(orphans), "reverse_orphans": rev_n,
+           "forward_orphans": fwd_n, "pruned": pruned,
+           "ok": "true" if not orphans else "false", "root": root})
+    return 0
+
+
+# ─────────────────────────────────── log ───────────────────────────────────
+def cmd_log(args):
+    """Append a commit-anchored entry to the bundle's log.md (OKF §7 change journal /
+    validate_okf E4 freshness). No-op when there is no bundle or no git commit to anchor —
+    never writes a block without a valid sha (that would make the bundle non-conformant)."""
+    root = _root(args.root)
+    bundle_abs = os.path.join(root, args.bundle)
+    if not os.path.isdir(bundle_abs):
+        print("[xref] log: no OKF bundle — skipped", file=sys.stderr)
+        _emit({"logged": "false", "reason": "no-bundle", "root": root})
+        return 0
+    sha = _git_head_short(root)
+    if not sha:
+        print("[xref] log: no git commit to anchor — skipped", file=sys.stderr)
+        _emit({"logged": "false", "reason": "no-commit", "root": root})
+        return 0
+    date = _today(args.date)
+    note = args.note or "OKF cross-references updated."
+    logp = os.path.join(bundle_abs, "log.md")
+    entry = f"## {date}\n\nCommit: `{sha}`\n\n- {note}\n"
+    if os.path.isfile(logp):
+        _write(logp, _read(logp).rstrip("\n") + "\n\n" + entry)
+    else:
+        _write(logp, "# Change Log\n\nOKF bundle change journal — commit-anchored (OKF §7).\n\n" + entry)
+    print(f"[xref] log: {date} @ {sha} — {note}", file=sys.stderr)
+    _emit({"logged": "true", "commit": sha, "date": date, "note": note,
+           "log": _rel(logp, root), "root": root})
+    return 0
+
+
+# ─────────────────────────────────── tree ───────────────────────────────────
+def cmd_tree(args):
+    """Build the global dependency hierarchy tree and topological migration wave plan
+    from OKF concept bundles (knowledge/) and specs/."""
+    root = _root(args.root)
+    bundle_abs = os.path.join(root, args.bundle)
+    specs_abs = os.path.join(root, args.specs)
+
+    concepts = _all_concepts(bundle_abs)
+    aggregates = {}
+
+    # 1. Parse knowledge bundle concept files
+    for cp in concepts:
+        agg_name = os.path.splitext(os.path.basename(cp))[0]
+        agg_slug = _slug(agg_name)
+        if agg_slug in RESERVED:
+            continue
+        title = _concept_title(cp)
+        deps_rows = _read_deps_rows(cp)
+        xref_rows = _read_xref_rows(cp)
+
+        dep_targets = []
+        for r in deps_rows:
+            if len(r) >= 1 and r[0].strip():
+                t = r[0].strip()
+                t_slug = _slug(t)
+                if t_slug and t_slug != agg_slug:
+                    dep_targets.append(t)
+
+        aggregates[agg_slug] = {
+            "name": title or agg_name,
+            "slug": agg_slug,
+            "concept_path": _rel(cp, root),
+            "deps": list(set(dep_targets)),
+            "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": []
+                        }
+
+    # 3. Fallback scan src/ directory if no aggregates in bundle/specs
+    if not aggregates:
+        src_abs = os.path.join(root, "src")
+        if os.path.isdir(src_abs):
+            for entry in os.listdir(src_abs):
+                ep = os.path.join(src_abs, entry)
+                if os.path.isdir(ep) and not entry.startswith("."):
+                    slug = _slug(entry)
+                    aggregates[slug] = {
+                        "name": entry,
+                        "slug": slug,
+                        "concept_path": _rel(ep, root),
+                        "deps": [],
+                        "xrefs": []
+                    }
+
+    # 4. Build Dependency Graph
+    all_slugs = set(aggregates.keys())
+    deps_graph = {}
+    for slug, info in aggregates.items():
+        internal_deps = sorted(list(set(_slug(d) for d in info["deps"] if _slug(d) in all_slugs and _slug(d) != slug)))
+        deps_graph[slug] = internal_deps
+
+    # 5. Topological Sort into Migration Waves
+    placed = set()
+    waves = []
+    has_cycles = False
+    cycles = []
+    remaining = set(all_slugs)
+
+    while remaining:
+        next_wave_nodes = []
+        for slug in sorted(list(remaining)):
+            reqs = deps_graph[slug]
+            if all(req in placed for req in reqs):
+                next_wave_nodes.append(slug)
+
+        if not next_wave_nodes:
+            has_cycles = True
+            cycle_nodes = list(remaining)
+            cycles.append(cycle_nodes)
+            waves.append({
+                "wave_id": len(waves),
+                "name": f"Wave {len(waves)} (Cycle Remediation Required)",
+                "aggregates": [aggregates[s]["name"] for s in cycle_nodes],
+                "slugs": cycle_nodes,
+                "is_cycle": True
+            })
+            break
+
+        wave_id = len(waves)
+        wave_name = "Wave 0 (Base / Leaf Aggregates)" if wave_id == 0 else f"Wave {wave_id}"
+        waves.append({
+            "wave_id": wave_id,
+            "name": wave_name,
+            "aggregates": [aggregates[s]["name"] for s in next_wave_nodes],
+            "slugs": next_wave_nodes,
+            "is_cycle": False
+        })
+
+        placed.update(next_wave_nodes)
+        remaining.difference_update(next_wave_nodes)
+
+    # 6. Format and Write Output Reports
+    out_md_path = os.path.join(root, args.out) if args.out else os.path.join(root, "specs", "migration-tree.md")
+    out_json_path = os.path.join(root, args.out_json) if getattr(args, "out_json", None) else os.path.join(root, "specs", "migration-sequence.json")
+
+    os.makedirs(os.path.dirname(out_md_path), exist_ok=True)
+    os.makedirs(os.path.dirname(out_json_path), exist_ok=True)
+
+    md_lines = [
+        "# Aggregates Dependency Hierarchy Tree & Migration Wave Plan",
+        "",
+        f"*Generated by `aw-xref.py tree` on {datetime.date.today().isoformat()}*",
+        "",
+        "## Topological Migration Waves",
+        "",
+        "| Wave | Aggregate / Feature | Dependencies (Internal) | Status / Seam Strategy |",
+        "|---|---|---|---|",
+    ]
+
+    for w in waves:
+        for slug in w["slugs"]:
+            info = aggregates[slug]
+            deps_str = ", ".join(deps_graph[slug]) if deps_graph[slug] else "*(None - Leaf)*"
+            seam_strat = "Cycle Remediation Required" if w.get("is_cycle") else ("Pure Service / Minimal Seam" if w["wave_id"] == 0 else f"Wave {w['wave_id']} Strangler Seam")
+            md_lines.append(f"| Wave {w['wave_id']} | `{info['name']}` | {deps_str} | {seam_strat} |")
+
+    if has_cycles:
+        md_lines.extend([
+            "",
+            "## ⚠️ Circular Dependency Warning",
+            "",
+            "The following aggregates contain circular dependencies and require seam refactoring before migration:",
+            ""
+        ])
+        for c in cycles:
+            md_lines.append(f"- `{' ↔ '.join([aggregates[s]['name'] for s in c])}`")
+
+    md_lines.extend([
+        "",
+        "## Dependency Hierarchy (DAG)",
+        "",
+        "```mermaid",
+        "flowchart TD"
+    ])
+
+    for slug, info in aggregates.items():
+        md_lines.append(f'    {slug}["{info["name"]}"]')
+        for dep_slug in deps_graph[slug]:
+            md_lines.append(f'    {dep_slug} --> {slug}')
+
+    md_lines.extend([
+        "```",
+        ""
+    ])
+
+    _write(out_md_path, "\n".join(md_lines) + "\n")
+
+    sequence_data = {
+        "generated_at": datetime.date.today().isoformat(),
+        "aggregate_count": len(aggregates),
+        "wave_count": len(waves),
+        "has_cycles": has_cycles,
+        "cycles": cycles,
+        "waves": waves,
+        "aggregates": aggregates
+    }
+    _write(out_json_path, json.dumps(sequence_data, indent=2) + "\n")
+
+    print(f"[xref] Generated Dependency Tree: {len(aggregates)} aggregate(s) sorted into {len(waves)} wave(s). Report: {_rel(out_md_path, root)}", file=sys.stderr)
+
+    _emit({
+        "aggregate_count": len(aggregates),
+        "wave_count": len(waves),
+        "has_cycles": has_cycles,
+        "cycles": cycles,
+        "tree_file": _rel(out_md_path, root),
+        "sequence_file": _rel(out_json_path, root),
+        "waves": waves,
+        "root": root
+    })
+    return 0
+
+
+# ─────────────────────────────── argparse ──────────────────────────────────
+def main(argv):
+    ap = argparse.ArgumentParser(prog="aw-xref.py", add_help=True)
+    sub = ap.add_subparsers(dest="cmd")
+
+    r = sub.add_parser("record", help="reconcile a using slice's edges across the bundle")
+    r.add_argument("--using", default="")
+    r.add_argument("--feature-dir", dest="feature_dir", default="")
+    r.add_argument("--design", default="")
+    r.add_argument("--origin", default="greenfield", help="greenfield | reverse-engineered | migrated | auto (detect from design.md)")
+    r.add_argument("--date", default="")
+    r.add_argument("--root", default="")
+    r.add_argument("--specs", default="specs")
+    r.add_argument("--bundle", default="knowledge")
+    r.set_defaults(func=cmd_record)
+
+    l = sub.add_parser("list", help="an aggregate's blast radius (who uses it)")
+    l.add_argument("--aggregate", default="")
+    l.add_argument("--feature-dir", dest="feature_dir", default="")
+    l.add_argument("--out", default="", help="also write a human blast-radius report to this path")
+    l.add_argument("--root", default="")
+    l.add_argument("--bundle", default="knowledge")
+    l.set_defaults(func=cmd_list)
+
+    c = sub.add_parser("concept-upsert", help="create/update an aggregate's own concept")
+    c.add_argument("--aggregate", default="")
+    c.add_argument("--feature-dir", dest="feature_dir", default="")
+    c.add_argument("--source-files", default="")
+    c.add_argument("--merge", action="store_true", help="union source_files with existing (CR delta) instead of replacing")
+    c.add_argument("--title", default="")
+    c.add_argument("--description", default="")
+    c.add_argument("--origin", default="greenfield")
+    c.add_argument("--root", default="")
+    c.add_argument("--bundle", default="knowledge")
+    c.set_defaults(func=cmd_concept_upsert)
+
+    co = sub.add_parser("concept-overview", help="splice model-authored prose into a concept's Overview")
+    co.add_argument("--aggregate", default="")
+    co.add_argument("--feature-dir", dest="feature_dir", default="")
+    co.add_argument("--text", default="", help="the overview prose (2-4 sentences)")
+    co.add_argument("--text-file", dest="text_file", default="", help="read the prose from this file instead")
+    co.add_argument("--root", default="")
+    co.add_argument("--bundle", default="knowledge")
+    co.set_defaults(func=cmd_concept_overview)
+
+    cp = sub.add_parser("concept-paths", help="read-only: the slice's source_files (replaces design-paths)")
+    cp.add_argument("--aggregate", default="")
+    cp.add_argument("--feature-dir", dest="feature_dir", default="")
+    cp.add_argument("--root", default="")
+    cp.add_argument("--bundle", default="knowledge")
+    cp.set_defaults(func=cmd_concept_paths)
+
+    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="")
+    vv.add_argument("--bundle", default="knowledge")
+    vv.set_defaults(func=cmd_validate)
+
+    lg = sub.add_parser("log", help="append a commit-anchored entry to the bundle log.md")
+    lg.add_argument("--note", default="")
+    lg.add_argument("--date", default="")
+    lg.add_argument("--root", default="")
+    lg.add_argument("--bundle", default="knowledge")
+    lg.set_defaults(func=cmd_log)
+
+    tr = sub.add_parser("tree", help="build dependency hierarchy tree & topological migration waves")
+    tr.add_argument("--out", default="", help="output markdown file (default: specs/migration-tree.md)")
+    tr.add_argument("--out-json", dest="out_json", default="", help="output json file (default: specs/migration-sequence.json)")
+    tr.add_argument("--root", default="")
+    tr.add_argument("--specs", default="specs")
+    tr.add_argument("--bundle", default="knowledge")
+    tr.set_defaults(func=cmd_tree)
+
+    args = ap.parse_args(argv)
+    if not getattr(args, "func", None):
+        ap.print_help(sys.stderr)
+        return 2
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
+