aw-spec-cli 0.1.15 → 0.1.17

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

@@ -39,19 +39,14 @@ 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] [--lane backend|frontend] [--merge]
-          [--title T] [--description D]
+  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/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}
+      -> 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
@@ -68,21 +63,6 @@ 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
@@ -97,12 +77,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"
@@ -249,10 +232,98 @@ 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 implement / implement-ui
+# share a feature's ONE concept — so two runs 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 — 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"
+    # The token identifies THIS acquisition, not just this process: a pid alone can be
+    # reused, and the release below refuses to remove a lock it does not own.
+    token = "%d %s" % (os.getpid(), os.urandom(8).hex())
+    start = time.time()
+    while True:
+        try:
+            h = os.open(lp, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+            os.write(h, (token + "\n").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.
+            # Two waiters may break the same lock at once; only one of them then wins the
+            # O_EXCL create, so a break never yields two holders.
+            if age > _LOCK_TIMEOUT:
+                try:
+                    os.unlink(lp)
+                except OSError:
+                    pass
+                continue
+            # Reached only when the lock keeps being RE-taken by other runs — a lock held
+            # continuously past the timeout is broken above instead. Nothing to clean up
+            # by hand, so this says what it is: too much contention to make progress.
+            if time.time() - start > _LOCK_TIMEOUT:
+                raise RuntimeError(
+                    "aw-xref: could not get a write lock on %s within %ds — other "
+                    "/appweaver runs are writing it continuously. Re-run when they finish."
+                    % (os.path.basename(key), int(_LOCK_TIMEOUT)))
+            time.sleep(0.05)
+    _HELD[key] = 1
+    try:
+        yield
+    finally:
+        _HELD.pop(key, None)
+        # ONLY remove a lock this acquisition still owns. A run slow enough to have its
+        # lock broken above would otherwise delete the lock of whoever took it next, and
+        # a third writer would walk straight in while that one was mid-write — the very
+        # thing the lock is here to stop.
+        try:
+            with open(lp, encoding="utf-8") as fh:
+                mine = fh.read().strip() == token
+        except OSError:
+            mine = False
+        if mine:
+            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):
@@ -498,19 +569,13 @@ def _resolve_concept(name, bundle_abs):
     return best
 
 
-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."""
+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 []) if lane == "backend" else [],
-        "ui_source_files": list(source_files or []) if lane == "frontend" else [],
+        "source_files": list(source_files or []),
     }
     overview = f"[overview of the {name} aggregate]"
     body = (
@@ -679,15 +744,20 @@ 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 _all_concepts(bundle_abs):
@@ -730,22 +800,30 @@ def cmd_record(args):
     edges = _design_edges(_read(design_path), using, known)
 
     # RECONCILE-ON-WRITE, delete phase: strip every row this slice authored, anywhere.
+    # The ROWS are what this rewrites, so the lock has to span reading them and writing
+    # them back. _write_xref_rows locks its own splice, but the row list it is handed was
+    # computed from a read that happened before — two slices recording at once each
+    # filtered the same starting list and the second write dropped the first's row.
     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)
+        with _lock(cpath):
+            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).
+    # A concept is written by EVERY slice that references it, so this is the contended one:
+    # same lock, spanning the read and the write.
     wrote, stubbed = [], []
     for e in edges:
         ypath = _get_or_stub_concept(e["target"], bundle_abs, origin, stubbed)
-        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)
+        with _lock(ypath):
+            rows = _read_xref_rows(ypath)
+            rows = [r for r in rows if not (_slug(r[0]) == using_slug and (len(r) > 1 and r[1] == e["via"]))]
+            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.
@@ -814,67 +892,53 @@ 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 "", lane))
+        _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:
-                # 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
+        # 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 runs 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:
+                    # 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)} {lane} source file(s) into {key}) — {_rel(path, root)}",
-          file=sys.stderr)
+          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",
-           "lane": lane, "key": key, "source_file_count": len(source_files), "root": root})
+           "source_file_count": len(source_files), "root": root})
     return 0
 
 
@@ -911,7 +975,11 @@ def cmd_concept_overview(args):
         return 2
 
     body = f"{OVERVIEW_HEADING}\n\n{text}\n"
-    _write(path, _replace_section(_read(path), OVERVIEW_HEADING, body, before=DEPS_HEADING))
+    # Splicing one section into the concept is a read-modify-write like the two table
+    # writers': the read has to happen under the same lock as the write, or the Overview
+    # goes back onto a copy that another slice has already added its rows to.
+    with _lock(path):
+        _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})
@@ -979,177 +1047,6 @@ 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 = {}
-    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:
-            lines.append("REQUIREMENT ANCHORS: none available — this feature has no source-map.md, "
-                         "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:
-            lines.append("REQUIREMENT ANCHORS (%s):" % smap)
-            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
@@ -1210,10 +1107,11 @@ def cmd_validate(args):
                 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)
+            with _lock(cpath):
+                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
@@ -1245,10 +1143,16 @@ def cmd_log(args):
     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)
+    # log.md is the bundle's ONE journal, appended by every slice that touches the
+    # knowledge layer, which makes it the most contended file here — and an append is a
+    # read-modify-write like any other. Unserialised, ten concurrent appends landed two.
+    # The existence test belongs inside the lock too: two runs that both saw "no file"
+    # would otherwise each write a fresh header and the first entry would be gone.
+    with _lock(logp):
+        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})
@@ -1488,8 +1392,7 @@ 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 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("--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")
@@ -1513,16 +1416,6 @@ 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="")

package/assets/.appweaver/templates/constitution-ui-template.md

@@ -56,7 +56,7 @@
 [UI_LANE_DECLARATION]
 <!-- Form: one line naming the lane, its stack and the root directory it owns — all three
      taken from the mapped ui-constitution.md, which declares them, and never invented
-     here. The root is the subtree ui-implement may write; it must match
+     here. The root is the subtree implement's frontend lane may write; it must match
      .appweaver/stacks.json where that file exists, and a disagreement is a STACK-MISMATCH:
      failure, not a silent rewrite. -->