aw-spec-cli 0.1.13 → 0.1.15

package/assets/.appweaver/scripts/powershell/aw-xref.ps1

@@ -6,9 +6,10 @@
 #
 #   aw-xref.ps1 record         --using X --design <design.md> [--origin ...] [--date YYYY-MM-DD] [--root DIR]
 #   aw-xref.ps1 list           --aggregate Y [--root DIR] [--bundle knowledge]
-#   aw-xref.ps1 concept-upsert   --aggregate X [--source-files a,b,c] [--description D] [--origin ...] [--root DIR]
+#   aw-xref.ps1 concept-upsert   --aggregate X [--source-files a,b,c] [--lane backend|frontend] [--merge] [--description D] [--origin ...] [--root DIR]
 #   aw-xref.ps1 concept-overview --aggregate X (--text PROSE | --text-file F) [--root DIR]
 #   aw-xref.ps1 concept-paths    --aggregate X | --feature-dir <dir> [--root DIR] [--bundle knowledge]
+#   aw-xref.ps1 concept-coverage --aggregate X | --feature-dir <dir> [--ids "FR-001,BR-002"] [--max-list N] [--root DIR] [--bundle knowledge]
 $ErrorActionPreference = "Stop"
 $core = Join-Path $PSScriptRoot "..\python\aw-xref.py"
 & python3 $core @args

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
@@ -478,13 +498,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 = (
@@ -788,13 +814,25 @@ 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,
@@ -804,18 +842,23 @@ def cmd_concept_upsert(args):
         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 []
+                # 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["source_files"] = merged
+                fm[key] = merged
             else:
-                fm["source_files"] = source_files
-        elif "source_files" not in fm:
-            fm["source_files"] = []
+                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:
@@ -828,9 +871,10 @@ def cmd_concept_upsert(args):
         _ensure_dir_index(path, aggregate)
 
     print(f"[xref] concept {aggregate}: {'created' if created else 'updated'} "
-          f"({len(source_files)} source file(s)) — {_rel(path, root)}", file=sys.stderr)
+          f"({len(source_files)} {lane} source file(s) into {key}) — {_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), "root": root})
     return 0
 
 
@@ -935,6 +979,177 @@ 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
@@ -1273,7 +1488,8 @@ 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("--title", default="")
     c.add_argument("--description", default="")
     c.add_argument("--origin", default="greenfield")
@@ -1297,6 +1513,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="")

package/assets/.appweaver/templates/design-template.md

@@ -2,40 +2,56 @@
 
 **Aggregate (feature)**: `[Aggregate]`  <!-- the feature = the aggregate, e.g. Order -->
 
-**Design home**: `specs/[Aggregate]/design.md`
+**Design home**: `specs/[Aggregate]/backend-plan.md`  <!-- the service lane; the frontend twin is frontend-plan.md, owned by /appweaver plan-ui -->
 
 **Source spec**: `specs/[Aggregate]/spec.md`
 
-**Version**: v1.0   <!-- moves in lockstep with the spec; every applied change request bumps this — see Change History -->
+**Version**: v1.0   <!-- SCRIPT-OWNED: plan-stamp sets this to the spec version this plan derives from. Never edit it by hand. -->
 
 **Status**: Draft
 
 <!--
   WHAT THIS DOCUMENT IS
   =====================
-  The single, living High-Level Design (HLD) for ONE aggregate. It is the
-  MEDIATOR between spec.md (WHAT/WHY, tech-agnostic) and the generated code
-  (HOW, tech-specific). It is NOT code: it carries structure, contracts,
-  behaviour, and decisions — enough for ANY capable LLM to generate correct,
-  spec-satisfying code on ANY target stack, but no complete method bodies.
+  The single, living High-Level Design (HLD) for ONE aggregate — the FEATURE-LEVEL
+  ARCHITECTURAL CONFIRMATION. It is the MEDIATOR between spec.md (WHAT/WHY,
+  tech-agnostic) and the generated code (HOW, tech-specific). It is NOT code: it
+  carries structure, contracts, behaviour, and decisions — enough for ANY capable LLM
+  to generate correct, spec-satisfying code on ANY target stack, but no complete
+  method bodies.
 
-    spec.md  ──▶  design.md  ──▶  code (+ tests)
-    behaviour     structure &       generated by `implement`
-    (FR/BR/US/SC) decisions (HLD)    (stack-bound at generation time)
+    spec.md  ──▶  backend-plan.md  ──▶  story-backend-plan.md  ──▶  code (+ tests)
+    behaviour     structure &          the story's slice          generated by `implement`
+    (FR/BR/CN/SC) decisions (HLD)      (concrete, ephemeral)
+
+  It is LONG-LIVED and moves FORWARD with the spec: /appweaver plan authors it, and
+  conforms it whenever the spec's Change History says something it realises has moved.
+  Story designs READ it and never write back — nothing merges into this document.
 
   ANCHORING RULES
-  - Every design element traces UP to a spec id (FR-/BR-/CN-/DC-/IC-/US-/SC-) and
-    the whole spec is covered DOWN here (see §6 Traceability). No design element
-    without a spec reason; no spec requirement without a design home.
+  - Every design element traces UP to a spec id (FR-/BR-/CN-/DC-/IC-/SC-) and the
+    whole spec is covered DOWN here (see §6 Traceability). No design element without
+    a spec reason; no spec requirement without a design home.
   - THE SPEC IS THE ONLY DOMAIN INPUT. Design reads the spec + the technical/
     architecture standards — NOT the domain rule files. The domain reached this doc
     only as spec ids: business invariants (BR-), domain-derived constraints (CN- —
     retention/immutability/audit/limits), data classification (DC-), and interop
     obligations (IC-). Realise each of those; invent no domain rule the spec omits
     (if one seems missing, record it as an Assumption in §7, never smuggle it in).
-  - Feature = aggregate. Commands (CreateOrder, UpdateOrder…) are USER STORIES,
-    not features. One aggregate = one design.md = one owning design for its code
-    files. A later requirement is a delta on THIS doc, never a new one.
+  - THE CODE IS THE WHAT-EXISTS INPUT, and it is a different authority from the spec.
+    Where code already realises this feature, the plan describes and ADJUSTS TO the
+    structure that is actually there rather than an idealised one, and names any
+    deliberate divergence as a §8 WA-n. The code never overrides the spec on
+    BEHAVIOUR, and it may not introduce a domain rule the spec omits — code that
+    contradicts the spec is a finding to report, not a design to bless.
+  - NO STORY IDS ANYWHERE IN THIS DOCUMENT. Stories live in stories/ and cite the
+    requirement ids they deliver; this design traces to FR-/BR-, which is what keeps
+    it stable while the backlog churns, is reprioritised and is re-raised.
+  - Feature = aggregate. Commands (CreateOrder, UpdateOrder…) are REQUIREMENTS
+    (FR-n) in the spec, not features and not stories. One aggregate = one
+    backend-plan.md = one owning design for its code files. A later requirement is
+    CONFORMED into this document by /appweaver plan's update mode — never a new
+    design doc, and never a delta document.
 
   WHAT LIVES ELSEWHERE (do NOT repeat it here — it is identical for every feature)
   - The clean-architecture layering + dependency rule (API → Application → Domain
@@ -47,6 +63,13 @@
   - Physical persistence (PKs/FKs, columns, indexes, JSON shapes, migration SQL)
     belongs to a technical-data-model. This doc states WHAT is stored and WHICH
     port persists it, not the schema.
+  - THE PUBLISHED SURFACE belongs to `interfaces.md`, this feature's APPEND-ONLY
+    interface log — the anchor the frontend lane designs against. /appweaver plan
+    publishes each entry there (the script assigns IF-nnn, the date and
+    status: proposed); /appweaver plan-ui and the FE story designs READ the latest
+    entry per id. §3 here is the INDEX that cites those ids, never a second copy of
+    the contract: two copies drift, and only the log has a lifecycle and a
+    supersedes: chain.
 
   TECHNOLOGY-AGNOSTIC (mandatory)
   - Express behaviour as SIGNATURES + pre/post/invariant/raises pseudocode and
@@ -128,7 +151,7 @@ trade-off. Layering follows the project architecture standard (constitution).]
 
 | Event | Raised by | Trigger | Key payload | Serves |
 |---|---|---|---|---|
-| `[EntityStateChanged]` | `[Root/Entity]` | [what causes it] | `[id, key fields]` | FR-00X · US-Y |
+| `[EntityStateChanged]` | `[Root/Entity]` | [what causes it] | `[id, key fields]` | FR-00X · BR-00Z |
 
 ### 1.3 Entities
 
@@ -162,7 +185,7 @@ trade-off. Layering follows the project architecture standard (constitution).]
   Invariant:      [what must hold — maps to a spec BR-nnn]
   Post-condition: [resulting state / outputs]
   Raises:         [DomainEvent]
-  Serves:         FR-00X · US-Y · BR-00Z
+  Serves:         FR-00X · BR-00Z
 ```
 
 **Invariants** *(always-true; each maps to a spec BR-nnn — do not add rules absent from the spec)*
@@ -182,13 +205,13 @@ trade-off. Layering follows the project architecture standard (constitution).]
   Purpose:  [why this can't live on one entity]
   Steps:    1. … 2. … 3. …
   Touches:  [aggregates/ports coordinated]
-  Serves:   FR-00X · US-Y
+  Serves:   FR-00X
 ```
 
 ## 2. Application Layer
 
 <!--
-  Use-cases: one command/query per user-story action, its handler's orchestration,
+  Use-cases: one command/query per requirement action (FR-n), its handler's orchestration,
   the ports it depends on, application-level rules (authorization, input validation,
   transaction + event publication), and the request/response DTO shapes. Consumes
   Domain types and the PORTS the Domain/Application defines; NEVER touches
@@ -206,9 +229,9 @@ trade-off. Layering follows the project architecture standard (constitution).]
 
 ### 2.2 Use-cases (commands / queries)
 
-<!-- One block per use-case = one user-story action. This is the LLM's unit of work. -->
+<!-- One block per use-case = one requirement action. This is the LLM's unit of work. -->
 
-#### `[Command/Query]` — Serves US-Y · FR-00X
+#### `[Command/Query]` — Serves FR-00X
 
 - **Type**: command (writes) | query (reads)
 - **Request (DTO)**: `{ [field]: [type], … }`
@@ -224,33 +247,41 @@ trade-off. Layering follows the project architecture standard (constitution).]
     4. [persist via port]  (single transaction boundary)
     5. [publish domain events]
     6. return [Response]
-    On failure: [which error → which API status in §3]
+    On failure: [which error → which published-interface status; the contract is the
+                 IF- entry cited in §3]
   ```
 - **Emits**: `[DomainEvent]` (from §1.2)
 
-## 3. API Layer
+## 3. API Layer — the published surface (INDEX; the wording lives in `interfaces.md`)
 
 <!--
-  The contract other systems couple to. Describe it at PROTOCOL level (REST assumed
-  per the constitution — adapt for gRPC/GraphQL/CLI if the stack differs), NOT as
-  controller code. Pin route, verb, auth, request/response shape, status codes, and
-  the error contract. Delegates to an Application use-case; no business logic here.
+  The contract other systems and the frontend couple to. Describe it at PROTOCOL level
+  (REST assumed per the constitution — adapt for gRPC/GraphQL/CLI if the stack differs),
+  NEVER as controller code. Delegates to an Application use-case; no business logic here.
+
+  WHERE IT LIVES. Each published interface is an entry in `specs/[Aggregate]/interfaces.md`,
+  the append-only interface log: route/verb, auth, request and response shapes, status
+  codes and the error contract. `plan` publishes those entries — the script assigns the
+  IF-nnn id, the date and status: proposed — and `plan-ui`, the FE story designs and any
+  consuming feature read the LATEST entry per id. This section is the INDEX only.
+
+  HOW TO FILL IT
+  - An interface that ALREADY has an entry in the log (it is in context on an update
+    run): cite its IF- id here, and describe nothing.
+  - An interface being published for the FIRST TIME in this run: describe it in the
+    "Interface" cell in one line and leave the IF- id cell as `(this run)` — the log
+    assigns the real id after this document is written, and the next update run cites
+    it. Never invent an IF- number: the script is the only id authority.
+  - CHANGING a published interface is a NEW entry that supersedes the old one, never
+    an edit to the existing entry and never a change to this table alone.
+  - Every row cites the spec ids it serves and the use-case that implements it, so
+    §6 Traceability and the analyze gate can follow the chain both ways.
 -->
 
-### `[VERB] [/route]` — [purpose] · Serves US-Y · FR-00X
-
-- **Auth**: [required role/scope]
-- **Request**: `[path/query params]` + body `{ [field]: [type], … }`
-- **Success**: `2xx` → `{ [response shape] }`
-- **Errors** *(the error contract)*:
-
-  | Status | When | Body shape |
-  |---|---|---|
-  | 400 | [validation failure] | `{ errors: [{ field, message }] }` |
-  | 403 | [unauthorized] | `{ error }` |
-  | 409 | [conflict / duplicate — maps to a BR] | `{ error }` |
-
-- **Maps to**: `[Command/Query]` (§2.2)
+| Interface | IF- id | Serves | Implemented by |
+|---|---|---|---|
+| `[VERB] [/route]` — [purpose] | IF-00n | FR-00X | `[Command/Query]` (§2.2) |
+| `[DomainEvent]` published outside this feature | (this run) | FR-00X · BR-00X | §2.2 emits, §1.2 |
 
 ## 4. Infrastructure Layer
 
@@ -316,7 +347,7 @@ trade-off. Layering follows the project architecture standard (constitution).]
 ## 6. Traceability (the spine)
 
 <!--
-  The two-way guarantee: every FR/BR/CN/DC/IC/US/SC has a design home, and every
+  The two-way guarantee: every FR/BR/CN/DC/IC/SC has a design home, and every
   design element has a spec reason. This is what makes impact analysis exact and lets
   the analyze gate verify coverage. Keep it complete — EVERY CN-/DC-/IC- in the spec
   MUST appear as a row here (that is how the analyze gate proves no lifted constraint
@@ -331,7 +362,6 @@ trade-off. Layering follows the project architecture standard (constitution).]
 | CN-001 | constraint | [where realised — §1 invariant / §4 persistence / §5 cross-cutting] | [layer] |
 | DC-001 | classification | [exposure enforcement — §2 projection / §5 data-protection] | App·Infra |
 | IC-001 | contract | [adapter/port realising it — §4.2] | Infra |
-| US-1 | story | [end-to-end elements realising it] | all |
 | SC-001 | success | [where it is met + how verified] | [layer] |
 
 ## 7. Assumptions (to clarify later)
@@ -369,15 +399,19 @@ trade-off. Layering follows the project architecture standard (constitution).]
 ## 9. Change History
 
 <!--
-  The living-truth ledger, in lockstep with spec.md. Every applied change request
-  appends a row here, carrying the version it ships as. finalize-delta writes the row
-  when it merges the delta; close-delta then archives the CR, bumps the minor version
-  in active_version.json and stamps that same number into this document's **Version**
-  header — one mechanism, one stage, so header, row and active_version.json never
-  disagree. A change to this aggregate is a DELTA on THIS document (delta-design:
-  ADDED / MODIFIED / REMOVED sections), never a new design doc. Newest last.
+  The living-truth ledger, in lockstep with spec.md — MANDATORY, and the one section
+  whose loss is refused rather than absorbed: plan-stamp writes no baseline at all if
+  this section went missing, so a dropped ledger can never be silently stamped over.
+
+  SCRIPT-OWNED. `plan-stamp` is the only writer: it appends one row per update naming
+  the requirement ids conformed, and moves the **Version** header to the spec version
+  this plan now derives from. The model writes NO version and NO row, ever — not here,
+  not in the header. Newest last.
+
+  Three columns, matching exactly what the stamp writes: the derived spec version, the
+  date, and what changed (the conformed ids are carried in that cell).
 -->
 
-| Version | Date | Change | User stories | CR |
-|---------|------|--------|--------------|-----|
-| v1.0 | [DATE] | Initial design | US-1 | — |
+| Version | Date | Change |
+|---------|------|--------|
+| v1.0 | [DATE] | Initial design |