aw-spec-cli 0.1.16 → 0.1.18

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
@@ -123,17 +103,6 @@ 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
@@ -265,15 +234,13 @@ def _read(path):
 
 # ──────────────────────────── 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
+# 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, 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
+# 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 = {}
@@ -293,11 +260,14 @@ def _lock(path):
     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, ("%d\n" % os.getpid()).encode("utf-8"))
+            os.write(h, (token + "\n").encode("utf-8"))
             os.close(h)
             break
         except OSError as exc:
@@ -309,27 +279,42 @@ def _lock(path):
                 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: %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))
+                    "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:
-            os.unlink(lp)
+            with open(lp, encoding="utf-8") as fh:
+                mine = fh.read().strip() == token
         except OSError:
-            pass
+            mine = False
+        if mine:
+            try:
+                os.unlink(lp)
+            except OSError:
+                pass
 
 
 def _write(path, text):
@@ -584,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 = (
@@ -781,27 +760,6 @@ def _write_deps_rows(path, 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):
     out = []
     if not os.path.isdir(bundle_abs):
@@ -842,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.
@@ -926,31 +892,19 @@ 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. 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
+        # 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))
@@ -958,23 +912,18 @@ def cmd_concept_upsert(args):
             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 []
+                    # 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[key] = merged
+                    fm["source_files"] = 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] = []
+                    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:
@@ -986,29 +935,10 @@ def cmd_concept_upsert(args):
         _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)} {lane} source file(s) into {key}"
-          + (f", {anchors_written} requirement anchor(s)" if anchors_written else "")
-          + f") — {_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),
-           "anchor_ids": anchor_ids, "anchor_ids_csv": ", ".join(anchor_ids),
-           "anchors_written": anchors_written, "root": root})
+           "source_file_count": len(source_files), "root": root})
     return 0
 
 
@@ -1045,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})
@@ -1113,197 +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 = {}
-    # 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
@@ -1364,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
@@ -1399,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})
@@ -1642,11 +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("--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("--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")
@@ -1670,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. -->