aw-spec-cli 0.1.14 → 0.1.16

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

@@ -39,14 +39,19 @@ summary to STDERR so it never corrupts the JSON contract):
   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]
+  concept-upsert --aggregate X [--source-files a,b,c] [--lane backend|frontend] [--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}
+      -> create/update X's OWN concept (frontmatter type/title/file lists), PRESERVING
+         its body — never clobbers the Cross-References other slices wrote. --lane picks
+         WHICH list this run owns: backend -> `source_files`, frontend -> `ui_source_files`.
+         Both keys are always present (an absent one claims "never implemented", which is
+         not the same as empty). --merge UNIONs that lane's list instead of replacing it —
+         what one story's slice, or a CR delta, must do so a second run does not drop the
+         first's files. Each list is written FLAT, 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, lane, key, 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
@@ -63,6 +68,21 @@ summary to STDERR so it never corrupts the JSON contract):
          {aggregate, concept, found, paths[], count, csv, declared[], declared_count,
           missing[], missing_count, root}
 
+  concept-coverage --aggregate X | --feature-dir <dir> [--ids CSV] [--max-list N] [--root DIR] [--bundle knowledge]
+      -> READ-ONLY: what CODE EXISTS for one feature, split by LANE — `source_files`
+         (service) and `ui_source_files` (UI) as separate lists, plus the concept's
+         forward edges (Depends-On) and reverse edges (Cross-References, the blast
+         radius). The answer a STORY DESIGN needs, where concept-paths' one flat
+         backend list would hand a UI pass the service tree. `--ids` splits the
+         story's requirements into anchored/unanchored against the feature's
+         source-map.md where one exists; with no map every id is unanchored, which
+         is reported as "no index", never as "no code". `digest` is the rendered
+         block a design pass reads. Never stubs a concept.
+         {aggregate, concept, found, origin, backend_paths[]/_csv/_count,
+          frontend_paths[]/_csv/_count, has_backend_code, has_frontend_code,
+          backend_missing[], frontend_missing[], missing_count, depends_on[]/_csv,
+          used_by[]/_csv, source_map, anchored_csv, unanchored_csv, digest, 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
@@ -77,12 +97,15 @@ Only the standard library is used. Usage: aw-xref.py <sub> [options]
 """
 
 import argparse
+import contextlib
 import datetime
+import errno
 import json
 import os
 import re
 import subprocess
 import sys
+import time
 
 # ───────────────────────────── canonical shapes ────────────────────────────
 OVERVIEW_HEADING = "## Overview"
@@ -100,6 +123,17 @@ XREF_COMMENT = (
     "Each row written by the using slice's implement/adopt (reconcile-on-write). "
     "Reviewed at CR time. Do not hand-edit. -->"
 )
+ANCHOR_HEADING = "## Requirement Anchors"
+ANCHOR_HEADER = ["Requirement", "Slice", "Lane", "Artefacts", "Recorded"]
+ANCHOR_COMMENT = (
+    "<!-- WHICH CODE REALISES WHICH REQUIREMENT — written by implement / implement-ui as "
+    "each story generates, from the ids that story exercises and the files that run wrote. "
+    "The greenfield counterpart of a brownfield source-map.md: without it every id on a "
+    "greenfield feature comes back unanchored, and the trace pass has to read every file to "
+    "find out what implements what. Reconcile-on-write, keyed by slice + lane, so "
+    "re-implementing a story replaces its rows rather than doubling them. 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
@@ -229,10 +263,82 @@ def _read(path):
         return ""
 
 
+# ──────────────────────────── write serialisation ──────────────────────────
+# EVERY CONCEPT WRITE IS A READ-MODIFY-WRITE: read the whole file, splice one section,
+# write it back truncating. None of them was serialised, and the wave model exists so that
+# stories sharing a wave are implemented in parallel — so two implements, or implement and
+# implement-ui (which share a feature's ONE concept), reading before either writes is the
+# ordinary case, and the second write drops the first's rows with nothing to say so. Git
+# catches that across branches and never inside a single working tree.
+#
+# The lock is named for the FILE — <path>.aw-lock, the same convention aw-spec-actions'
+# log-append uses for interfaces.md and adr.md — so every writer of a file contends on one
+# lock whichever process, op or shell it came from. Re-entrant within a process, so an
+# outer read-modify-write can hold it while the _write inside re-acquires.
+_LOCK_TIMEOUT = 30.0
+_HELD = {}
+
+
+@contextlib.contextmanager
+def _lock(path):
+    key = os.path.abspath(path)
+    if _HELD.get(key):
+        _HELD[key] += 1
+        try:
+            yield
+        finally:
+            _HELD[key] -= 1
+        return
+    parent = os.path.dirname(key)
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+    lp = key + ".aw-lock"
+    start = time.time()
+    while True:
+        try:
+            h = os.open(lp, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+            os.write(h, ("%d\n" % os.getpid()).encode("utf-8"))
+            os.close(h)
+            break
+        except OSError as exc:
+            if exc.errno != errno.EEXIST:
+                raise
+            try:
+                age = time.time() - os.path.getmtime(lp)
+            except OSError:
+                age = 0.0
+            # A lock older than the timeout belonged to a run that died holding it.
+            # Breaking it is right: the alternative is a concept nobody can write again.
+            if age > _LOCK_TIMEOUT:
+                try:
+                    os.unlink(lp)
+                except OSError:
+                    pass
+                continue
+            if time.time() - start > _LOCK_TIMEOUT:
+                raise RuntimeError(
+                    "aw-xref: %s has been locked by another run for over %ds. If no other "
+                    "/appweaver command is running, delete %s and re-run."
+                    % (os.path.basename(key), int(_LOCK_TIMEOUT), lp))
+            time.sleep(0.05)
+    _HELD[key] = 1
+    try:
+        yield
+    finally:
+        _HELD.pop(key, None)
+        try:
+            os.unlink(lp)
+        except OSError:
+            pass
+
+
 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)
+    parent = os.path.dirname(path)
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+    with _lock(path):
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(text)
 
 
 def _today(arg_date):
@@ -478,13 +584,19 @@ def _resolve_concept(name, bundle_abs):
     return best
 
 
-def _skeleton_concept(name, origin, source_files, description):
+def _skeleton_concept(name, origin, source_files, description, lane="backend"):
+    """A new concept always carries BOTH lane keys — `source_files` for the service
+    tree and `ui_source_files` for the UI one — with the run's files in the lane it
+    generated and an empty list in the other. Whichever lane implements first, the
+    other's key is there for it to fill; the template's rule is to leave it empty on a
+    single-lane slice, never to delete it."""
     fm = {
         "type": "aggregate",
         "title": name,
         "description": description or f"{name} aggregate.",
         "origin": origin or "greenfield",
-        "source_files": list(source_files or []),
+        "source_files": list(source_files or []) if lane == "backend" else [],
+        "ui_source_files": list(source_files or []) if lane == "frontend" else [],
     }
     overview = f"[overview of the {name} aggregate]"
     body = (
@@ -653,15 +765,41 @@ def _git_head_short(root):
 
 
 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))
+    # The read is INSIDE the lock: splicing a section into a file another process is
+    # rewriting is what loses rows, and taking the lock only for the write would still
+    # splice into a copy that had gone stale between the read and the acquisition.
+    with _lock(path):
+        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))
+    with _lock(path):
+        text = _read(path)
+        body = _render_section(DEPS_HEADING, DEPS_COMMENT, DEPS_HEADER, rows)
+        _write(path, _replace_section(text, DEPS_HEADING, body))
+
+
+def _read_anchor_rows(path):
+    return _table_data_rows(_section_text(_read(path), ANCHOR_HEADING))
+
+
+def _write_anchor_rows(path, slice_id, lane, ids, artefacts, recorded):
+    """Requirement → artefact rows for ONE slice, reconciled on write. Every row this
+    slice+lane wrote before is dropped and its current ones re-added, so a story that
+    re-implements against a changed design replaces its claims instead of accumulating
+    them — the same rule the Cross-References rows follow, for the same reason."""
+    with _lock(path):
+        keep = [r for r in _read_anchor_rows(path)
+                if not (len(r) >= 3 and r[1].strip() == slice_id and r[2].strip() == lane)]
+        # Ordered by requirement so a person reading the section can find an id, and two
+        # runs writing the same rows produce the same file.
+        fresh = [[rid, slice_id, lane, artefacts, recorded] for rid in ids]
+        rows = sorted(keep + fresh, key=lambda r: (r[0], r[1] if len(r) > 1 else ""))
+        body = _render_section(ANCHOR_HEADING, ANCHOR_COMMENT, ANCHOR_HEADER, rows)
+        _write(path, _replace_section(_read(path), ANCHOR_HEADING, body))
+        return len(fresh)
 
 
 def _all_concepts(bundle_abs):
@@ -788,49 +926,89 @@ def cmd_concept_upsert(args):
         _emit({"error": "aggregate-required", "root": root})
         return 2
     source_files = _parse_source_files(args.source_files, root)
+    # WHICH LANE'S FILE LIST THIS RUN OWNS. A feature has ONE concept across both lanes,
+    # and the two trees live under different keys: `source_files` is the service lane's,
+    # `ui_source_files` is the UI lane's. Writing UI files into the service key would
+    # collapse the concept resolver's module_dir to the repo root and hand every later
+    # service reader a tree of components — which is exactly what concept-coverage's
+    # lane split exists to prevent.
+    lane = (args.lane or "backend").strip().lower()
+    if lane not in ("backend", "frontend"):
+        print("[xref] concept-upsert: --lane must be backend or frontend, not %r" % lane, file=sys.stderr)
+        _emit({"error": "bad-lane", "lane": lane, "root": root})
+        return 2
+    key = "source_files" if lane == "backend" else "ui_source_files"
 
     path = _resolve_concept(aggregate, bundle_abs)
     created = path is None
     if created:
         _ensure_bundle(bundle_abs)
         path = _canonical_concept_path(bundle_abs, aggregate)
-        _write(path, _skeleton_concept(aggregate, origin, source_files, args.description or ""))
+        _write(path, _skeleton_concept(aggregate, origin, source_files, args.description or "", lane))
         _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
+        # which holds the Cross-References other slices wrote. Read and write under one
+        # lock: --merge unions this run's files with what is already recorded, so two
+        # parallel stories reading before either writes both union against the same
+        # starting list and the second write loses the first's files.
+        with _lock(path):
+            fm, body = _read_fm(_read(path))
+            fm.setdefault("type", "aggregate")
+            fm["title"] = fm.get("title") or aggregate
+            if source_files:
+                if args.merge:
+                    # INCREMENTAL mode: {{files}} is only what THIS run wrote — one story's
+                    # slice, or a delta's changed files — so UNION with what the lane already
+                    # records, never replace. Replacing would drop every file the feature's
+                    # earlier stories generated the moment a second story implements.
+                    existing = fm.get(key) if isinstance(fm.get(key), list) else []
+                    merged = list(existing)
+                    for s in source_files:
+                        if s not in merged:
+                            merged.append(s)
+                    fm[key] = merged
+                else:
+                    fm[key] = source_files
+            # Both keys always present: an absent one reads as "this lane was never
+            # implemented" to every consumer, which is a different claim from "empty".
+            for k in ("source_files", "ui_source_files"):
+                if k not in fm:
+                    fm[k] = []
+            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)
 
+    # WHICH REQUIREMENT THIS SLICE'S FILES REALISE. The two halves have always been in this
+    # call and were thrown away: the ids the story exercises, and the files the run just
+    # generated. Persisted here so a greenfield feature has the anchor index only a
+    # brownfield source-map.md carried — without it every id comes back unanchored and the
+    # trace pass has to read the whole tree to find out what implements what.
+    anchor_ids = sorted({i for i in re.findall(r'\b[A-Z]{2}-\d+', args.ids or "")})
+    anchors_written = 0
+    if anchor_ids:
+        slice_id = (args.slice_id or "").strip() or "(unnamed slice)"
+        # The cell is table content: a path holding a pipe would silently split it.
+        cell = ", ".join(s.replace("|", r"\|") for s in source_files) or "(no files recorded)"
+        anchors_written = _write_anchor_rows(path, slice_id, lane, anchor_ids, cell,
+                                             _today(args.date))
+
     print(f"[xref] concept {aggregate}: {'created' if created else 'updated'} "
-          f"({len(source_files)} source file(s)) — {_rel(path, root)}", file=sys.stderr)
+          f"({len(source_files)} {lane} source file(s) into {key}"
+          + (f", {anchors_written} requirement anchor(s)" if anchors_written else "")
+          + f") — {_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})
+           "lane": lane, "key": key, "source_file_count": len(source_files),
+           "anchor_ids": anchor_ids, "anchor_ids_csv": ", ".join(anchor_ids),
+           "anchors_written": anchors_written, "root": root})
     return 0
 
 
@@ -935,6 +1113,197 @@ def cmd_concept_paths(args):
     return 0
 
 
+def cmd_concept_coverage(args):
+    """CODE COVERAGE for one feature, read from its OKF concept — what code EXISTS
+    today for the aggregate a story is about to design against, SPLIT BY LANE.
+
+    concept-paths answers "which files is this slice made of" for the executable
+    phases, as one flat backend list. A story design needs the same facts shaped
+    differently: the service design reads `source_files`, the frontend design reads
+    `ui_source_files`, and neither should be handed the other's tree — a UI pass
+    told to read twelve C# files designs around them. It also needs the two things
+    a path list drops: the aggregate's forward edges (Depends-On), and its REVERSE
+    edges (Cross-References) — the blast radius a slice inherits the moment it
+    changes a published surface.
+
+    COVERAGE, HONESTLY. A greenfield concept holds no requirement→file index: code
+    carries no FR ids. A feature that was ADOPTED does — the source map's `Spec ids`
+    column — so the ids given in --ids come back split into ANCHORED (some artefact
+    claims the id) and UNANCHORED. With no source map every id is unanchored, which
+    is the true answer, and it is NEVER reported as uncovered: absent evidence is not
+    evidence of absence, and a design pass told "FR-003 has no code" when the index
+    simply does not exist would re-plan work that already ships.
+
+    STRICTLY READ-ONLY, the same contract as concept-paths: a query never stubs a
+    concept, and a feature with no concept at all — greenfield, before the first
+    implement — is a legitimate EMPTY answer with `found: false`, not an error."""
+    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-coverage: --aggregate or --feature-dir required", file=sys.stderr)
+        _emit({"error": "aggregate-required", "root": root})
+        return 2
+
+    path = _resolve_concept(aggregate, bundle_abs)
+    fm = {}
+    if path:
+        fm, _ = _read_fm(_read(path))
+
+    def lane_files(key):
+        """One frontmatter key's paths, split into on-disk and declared-but-missing.
+        _read_fm gives a list for a block list and "" for an empty scalar; the
+        `# Layer` group headers are comments and are already skipped by it."""
+        raw = fm.get(key)
+        items = raw if isinstance(raw, list) else ([raw] if isinstance(raw, str) and raw else [])
+        seen, existing, missing = 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)
+            target = s if os.path.isabs(s) else os.path.join(root, s)
+            (existing if os.path.isfile(target) else missing).append(s)
+        return existing, missing
+
+    be, be_missing = lane_files("source_files")
+    fe, fe_missing = lane_files("ui_source_files")
+
+    # ---- requirement anchors, where an index exists ---------------------------
+    ids = [i for i in re.split(r'[,\s]+', (args.ids or "").strip()) if i]
+    smap = ""
+    anchors = {}
+    # TWO SOURCES, ONE INDEX. A brownfield feature's anchors come from adopt's
+    # source-map.md; a greenfield feature's come from the concept's own Requirement Anchors
+    # rows, which implement / implement-ui write as each story generates. Reading only the
+    # first meant every id on a greenfield feature came back "not anchored to any artefact"
+    # — advice to design it as new work, on a requirement that already had code.
+    if path:
+        for r in _read_anchor_rows(path):
+            if len(r) < 4:
+                continue
+            rid = r[0].strip()
+            if not re.match(r'^[A-Z]{2}-\d+$', rid):
+                continue
+            for art in (a.strip().replace(r"\|", "|") for a in r[3].split(",")):
+                if art and art != "(no files recorded)":
+                    anchors.setdefault(rid, [])
+                    if art not in anchors[rid]:
+                        anchors[rid].append(art)
+    concept_anchored = bool(anchors)
+    if args.feature_dir:
+        cand = os.path.join(args.feature_dir, "source-map.md")
+        if os.path.isfile(cand):
+            smap = _rel(cand, root)
+            text = _read(cand)
+            lines = text.splitlines()
+            start = next((i for i, ln in enumerate(lines) if ln.startswith("## Artefact")), None)
+            if start is not None:
+                end = next((j for j in range(start + 1, len(lines))
+                            if lines[j].startswith("## ")), len(lines))
+                for r in _table_data_rows("\n".join(lines[start:end])):
+                    # | # | Legacy artefact | Kind | Spec ids | Design element | ... |
+                    if len(r) < 4:
+                        continue
+                    artefact = r[1].strip().strip("`")
+                    for rid in re.findall(r'\b[A-Z]{2}-\d+', r[3]):
+                        anchors.setdefault(rid, [])
+                        if artefact and artefact not in anchors[rid]:
+                            anchors[rid].append(artefact)
+    anchored = [i for i in ids if anchors.get(i)]
+    unanchored = [i for i in ids if not anchors.get(i)]
+
+    deps = [r[0].strip() for r in (_read_deps_rows(path) if path else [])
+            if r and _IDENT_RE.match((r[0] or "").strip())]
+    users = sorted(set(_xref_users(aggregate, bundle_abs))) if path else []
+
+    # ---- the digest — the block a design pass reads --------------------------
+    cap = args.max_list if args.max_list and args.max_list > 0 else 60
+
+    def block(label, files, missing, empty_note):
+        if not files:
+            return ["%s: %s" % (label, empty_note)]
+        out = ["%s: %d file(s) on disk" % (label, len(files))]
+        shown = 0
+        for group, items in _group_source_files(files):
+            if shown >= cap:
+                break
+            out.append("  %s" % group)
+            for f in items:
+                if shown >= cap:
+                    break
+                out.append("    %s" % f)
+                shown += 1
+        if len(files) > shown:
+            out.append("    … and %d more (the full list is in the lane's csv)" % (len(files) - shown))
+        if missing:
+            out.append("  DRIFT — declared in the concept, not on disk (%d): %s"
+                       % (len(missing), ", ".join(missing[:12])
+                          + (" …" if len(missing) > 12 else "")))
+        return out
+
+    lines = []
+    if not path:
+        lines.append("No OKF concept for %s — nothing has been implemented for this feature yet. "
+                     "Every lane below is GREENFIELD: design from a clean slate." % aggregate)
+        lines.append("")
+    else:
+        lines.append("%s — code coverage from the OKF concept (%s, origin: %s)"
+                     % (aggregate, _rel(path, root), (fm.get("origin") or "unknown")))
+        lines.append("")
+    lines += block("BACKEND", be, be_missing,
+                   "no service code recorded for this aggregate — greenfield on this lane")
+    lines.append("")
+    lines += block("FRONTEND", fe, fe_missing,
+                   "no UI code recorded for this aggregate — greenfield on this lane")
+    lines.append("")
+    lines.append("DEPENDS ON (this aggregate reaches into): %s" % (", ".join(deps) or "nothing"))
+    lines.append("USED BY (change this aggregate's surface and these break): %s"
+                 % (", ".join(users) or "nothing recorded"))
+    if ids:
+        lines.append("")
+        if not smap and not concept_anchored:
+            lines.append("REQUIREMENT ANCHORS: none available — this feature has no source-map.md "
+                         "and no slice has recorded one in the concept, so no id can be traced to "
+                         "a file. Treat the files above as the whole of what exists and read them; "
+                         "do NOT read an id's absence here as proof that no code implements it.")
+        else:
+            src = " + ".join(filter(None, [smap, "the concept's Requirement Anchors"
+                                           if concept_anchored else ""]))
+            lines.append("REQUIREMENT ANCHORS (%s):" % src)
+            for i in anchored:
+                lines.append("  %-10s %s" % (i, ", ".join(anchors[i][:6])
+                                             + (" …" if len(anchors[i]) > 6 else "")))
+            if unanchored:
+                lines.append("  not anchored to any artefact: %s — the map claims no code for "
+                             "them, so design them as new work unless the files above say otherwise."
+                             % ", ".join(unanchored))
+    digest = "\n".join(lines)
+
+    print("[xref] concept-coverage %s: backend %d, frontend %d, drift %d, used-by %d"
+          % (aggregate, len(be), len(fe), len(be_missing) + len(fe_missing), len(users)),
+          file=sys.stderr)
+    _emit({"aggregate": aggregate, "concept": _rel(path, root) if path else "",
+           "found": bool(path), "origin": (fm.get("origin") or ""),
+           "backend_paths": be, "backend_csv": ",".join(be), "backend_count": len(be),
+           "frontend_paths": fe, "frontend_csv": ",".join(fe), "frontend_count": len(fe),
+           "has_backend_code": bool(be), "has_frontend_code": bool(fe),
+           "backend_missing": be_missing, "frontend_missing": fe_missing,
+           "missing_count": len(be_missing) + len(fe_missing),
+           # THE UNION, for a reader whose question spans both lanes. A gate that traces a
+           # requirement to code has to see the UI half of it: an FR- with a user-facing
+           # surface is realised in two trees, and `source_files` alone is the service one.
+           "all_paths": be + fe, "all_csv": ",".join(be + fe), "all_count": len(be) + len(fe),
+           "all_missing": be_missing + fe_missing,
+           "all_missing_csv": ", ".join(be_missing + fe_missing),
+           "depends_on": deps, "depends_on_csv": ", ".join(deps),
+           "used_by": users, "used_by_csv": ", ".join(users),
+           "source_map": smap, "anchored_csv": ", ".join(anchored),
+           "unanchored_csv": ", ".join(unanchored),
+           "digest": digest, "root": root})
+    return 0
+
+
 # ─────────────────────────────── validate ──────────────────────────────────
 def cmd_validate(args):
     """Cross-reference drift check (the safety net BEYOND reconcile-on-write). Pairs the
@@ -1273,7 +1642,11 @@ def main(argv):
     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("--merge", action="store_true", help="union the lane's file list with existing (one story's slice, a CR delta) instead of replacing")
+    c.add_argument("--lane", default="backend", help="backend -> source_files, frontend -> ui_source_files")
+    c.add_argument("--ids", default="", help="requirement ids this slice realises; records a Requirement Anchors row per id against the files just written")
+    c.add_argument("--slice", dest="slice_id", default="", help="the story id the anchor rows are keyed by (with --ids)")
+    c.add_argument("--date", default="")
     c.add_argument("--title", default="")
     c.add_argument("--description", default="")
     c.add_argument("--origin", default="greenfield")
@@ -1297,6 +1670,16 @@ def main(argv):
     cp.add_argument("--bundle", default="knowledge")
     cp.set_defaults(func=cmd_concept_paths)
 
+    cc = sub.add_parser("concept-coverage", help="read-only: lane-split code coverage for one feature (story design)")
+    cc.add_argument("--aggregate", default="")
+    cc.add_argument("--feature-dir", dest="feature_dir", default="")
+    cc.add_argument("--ids", default="", help="requirement ids to report anchors for (csv)")
+    cc.add_argument("--max-list", dest="max_list", type=int, default=60,
+                    help="cap on files listed per lane in the digest (the csv stays complete)")
+    cc.add_argument("--root", default="")
+    cc.add_argument("--bundle", default="knowledge")
+    cc.set_defaults(func=cmd_concept_coverage)
+
     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="")