aw-spec-cli 0.1.15 → 0.1.16

package/assets/.appweaver/scripts/python/aw-payload-parity.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""aw-payload-parity.py — prove the two shells run the SAME python.
+
+Most of aw-spec-actions is one python program embedded twice: as a `<<'PY'` heredoc in
+aw-spec-actions.sh and as a `$PyName = @'…'@` here-string in aw-spec-actions.ps1. The
+contract is that each pair is BYTE-IDENTICAL, and nothing checked it — so a fix applied to
+one shell and forgotten in the other is a gate that behaves differently on Windows, in
+silence. Three of the ops with no twin at all are on the forward chain (resolve-hooks, with
+17 call sites across the nine workflows, and checklist-read / checklist-apply, which produce
+analyze-design's and analyze-slice's LIFT-FAILURE findings), and every one of them was read
+in bash when the workflows were reviewed.
+
+WHAT IT CHECKS
+  1. Every bash payload has a byte-identical PowerShell twin.
+  2. Every PowerShell payload has a byte-identical bash twin.
+Payloads with no twin are listed, not counted against a hard-coded number: the split is
+whatever the files say today, and pinning it would need editing on every legitimate change.
+
+DUAL-AUTHORED BY DECISION. The ops in ACCEPTED_BASH_ONLY are bash-only on purpose (their
+PowerShell path is written natively rather than shared) and are reported separately, so the
+exit code reacts only to a NEW divergence. Moving one out of that list means it gained a
+shared payload; adding one means the decision was taken to dual-author it — and either way
+the reviewer has to say so in the same commit.
+
+  exit 0  every payload is paired, or unpaired only by accepted decision
+  exit 1  a new unpaired payload, or a pair that has drifted apart
+
+Usage:  aw-payload-parity.py [--root DIR] [--verbose]
+"""
+
+import argparse
+import hashlib
+import os
+import re
+import sys
+
+SH_REL = ".appweaver/scripts/bash/aw-spec-actions.sh"
+PS_REL = ".appweaver/scripts/powershell/aw-spec-actions.ps1"
+
+# Bash payloads with no shared PowerShell twin BY DECISION, not by oversight. Each is
+# implemented natively on the PowerShell side and the two must be reviewed in pairs.
+ACCEPTED_BASH_ONLY = {
+    "cmd_resolve_hooks",
+    "cmd_list_features",
+    "cmd_checklist_read",
+    "cmd_checklist_apply",
+    "cmd_compose_constitution",
+    "cmd_constitution_verify",
+    "cmd_component_verify",
+    "cmd_cr_archive",
+    "cmd_version_stamp",
+}
+
+
+def bash_payloads(text):
+    """[(owning function, payload, first line, last line)] in file order."""
+    out, owner, lines, i = [], "(top level)", text.split("\n"), 0
+    while i < len(lines):
+        m = re.match(r"^([A-Za-z_][A-Za-z0-9_]*)\(\)\s*\{", lines[i])
+        if m:
+            owner = m.group(1)
+        if re.search(r"<<'PY'\s*$", lines[i]):
+            j, body = i + 1, []
+            while j < len(lines) and lines[j] != "PY":
+                body.append(lines[j])
+                j += 1
+            out.append((owner, "\n".join(body), i + 2, j))
+            i = j
+        i += 1
+    return out
+
+
+def ps_payloads(text):
+    """[(variable name, payload, first line, last line)] in file order."""
+    out, lines, i = [], text.split("\n"), 0
+    while i < len(lines):
+        m = re.match(r"^\$(Py[A-Za-z0-9_]*)\s*=\s*@'\s*$", lines[i])
+        if m:
+            j, body = i + 1, []
+            while j < len(lines) and lines[j] != "'@":
+                body.append(lines[j])
+                j += 1
+            out.append((m.group(1), "\n".join(body), i + 2, j))
+            i = j
+        i += 1
+    return out
+
+
+def digest(s):
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def main():
+    ap = argparse.ArgumentParser(description="check bash/PowerShell python-payload parity")
+    ap.add_argument("--root", default="", help="kit root (default: this script's kit)")
+    ap.add_argument("--verbose", action="store_true", help="list every matched pair too")
+    args = ap.parse_args()
+
+    root = args.root or os.path.normpath(
+        os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", ".."))
+    sh_path, ps_path = os.path.join(root, SH_REL), os.path.join(root, PS_REL)
+    for p in (sh_path, ps_path):
+        if not os.path.isfile(p):
+            print("aw-payload-parity: not found: %s" % p, file=sys.stderr)
+            return 2
+
+    sh = bash_payloads(open(sh_path, encoding="utf-8").read())
+    ps = ps_payloads(open(ps_path, encoding="utf-8").read())
+
+    ps_by_hash = {}
+    for name, body, a, b in ps:
+        ps_by_hash.setdefault(digest(body), []).append((name, a, b))
+    sh_by_hash = {}
+    for owner, body, a, b in sh:
+        sh_by_hash.setdefault(digest(body), []).append((owner, a, b))
+
+    paired, accepted, unpaired_sh, unpaired_ps = [], [], [], []
+    for owner, body, a, b in sh:
+        twin = ps_by_hash.get(digest(body))
+        if twin:
+            paired.append((owner, twin[0][0]))
+        elif owner in ACCEPTED_BASH_ONLY:
+            accepted.append((owner, a, b))
+        else:
+            unpaired_sh.append((owner, a, b))
+    for name, body, a, b in ps:
+        if not sh_by_hash.get(digest(body)):
+            unpaired_ps.append((name, a, b))
+
+    print("payload parity: %d bash, %d powershell, %d byte-identical pair(s)"
+          % (len(sh), len(ps), len(paired)))
+    if args.verbose:
+        for owner, name in paired:
+            print("  ok  %-34s == $%s" % (owner, name))
+    if accepted:
+        print("\ndual-authored by decision (%d) — PowerShell implements these natively, so a "
+              "change to one must be mirrored by hand:" % len(accepted))
+        for owner, a, b in accepted:
+            print("  --  %-34s %s:%d-%d" % (owner, os.path.basename(sh_path), a, b))
+
+    failed = bool(unpaired_sh or unpaired_ps)
+    if unpaired_sh:
+        print("\nFAIL — bash payloads with no byte-identical PowerShell twin:")
+        for owner, a, b in unpaired_sh:
+            print("  !!  %-34s %s:%d-%d" % (owner, os.path.basename(sh_path), a, b))
+    if unpaired_ps:
+        print("\nFAIL — PowerShell payloads with no byte-identical bash twin:")
+        for name, a, b in unpaired_ps:
+            print("  !!  $%-33s %s:%d-%d" % (name, os.path.basename(ps_path), a, b))
+    if failed:
+        print("\nA payload changed in one shell and not the other, or a new op shipped to one "
+              "shell only. Copy the payload verbatim into its twin — they are byte-identical "
+              "by contract — or, if the op is deliberately dual-authored, add its function to "
+              "ACCEPTED_BASH_ONLY in this file and say why in the commit.")
+    return 1 if failed else 0
+
+
+sys.exit(main())

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

@@ -97,12 +97,15 @@ Only the standard library is used. Usage: aw-xref.py <sub> [options]
 """
 
 import argparse
+import contextlib
 import datetime
+import errno
 import json
 import os
 import re
 import subprocess
 import sys
+import time
 
 # ───────────────────────────── canonical shapes ────────────────────────────
 OVERVIEW_HEADING = "## Overview"
@@ -120,6 +123,17 @@ XREF_COMMENT = (
     "Each row written by the using slice's implement/adopt (reconcile-on-write). "
     "Reviewed at CR time. Do not hand-edit. -->"
 )
+ANCHOR_HEADING = "## Requirement Anchors"
+ANCHOR_HEADER = ["Requirement", "Slice", "Lane", "Artefacts", "Recorded"]
+ANCHOR_COMMENT = (
+    "<!-- WHICH CODE REALISES WHICH REQUIREMENT — written by implement / implement-ui as "
+    "each story generates, from the ids that story exercises and the files that run wrote. "
+    "The greenfield counterpart of a brownfield source-map.md: without it every id on a "
+    "greenfield feature comes back unanchored, and the trace pass has to read every file to "
+    "find out what implements what. Reconcile-on-write, keyed by slice + lane, so "
+    "re-implementing a story replaces its rows rather than doubling them. Do not "
+    "hand-edit. -->"
+)
 RESERVED = {"index.md", "log.md"}
 
 # A Cross-References "Using slice" cell that is safe to hand to a VSTest --filter (and a
@@ -249,10 +263,82 @@ def _read(path):
         return ""
 
 
+# ──────────────────────────── write serialisation ──────────────────────────
+# EVERY CONCEPT WRITE IS A READ-MODIFY-WRITE: read the whole file, splice one section,
+# write it back truncating. None of them was serialised, and the wave model exists so that
+# stories sharing a wave are implemented in parallel — so two implements, or implement and
+# implement-ui (which share a feature's ONE concept), reading before either writes is the
+# ordinary case, and the second write drops the first's rows with nothing to say so. Git
+# catches that across branches and never inside a single working tree.
+#
+# The lock is named for the FILE — <path>.aw-lock, the same convention aw-spec-actions'
+# log-append uses for interfaces.md and adr.md — so every writer of a file contends on one
+# lock whichever process, op or shell it came from. Re-entrant within a process, so an
+# outer read-modify-write can hold it while the _write inside re-acquires.
+_LOCK_TIMEOUT = 30.0
+_HELD = {}
+
+
+@contextlib.contextmanager
+def _lock(path):
+    key = os.path.abspath(path)
+    if _HELD.get(key):
+        _HELD[key] += 1
+        try:
+            yield
+        finally:
+            _HELD[key] -= 1
+        return
+    parent = os.path.dirname(key)
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+    lp = key + ".aw-lock"
+    start = time.time()
+    while True:
+        try:
+            h = os.open(lp, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+            os.write(h, ("%d\n" % os.getpid()).encode("utf-8"))
+            os.close(h)
+            break
+        except OSError as exc:
+            if exc.errno != errno.EEXIST:
+                raise
+            try:
+                age = time.time() - os.path.getmtime(lp)
+            except OSError:
+                age = 0.0
+            # A lock older than the timeout belonged to a run that died holding it.
+            # Breaking it is right: the alternative is a concept nobody can write again.
+            if age > _LOCK_TIMEOUT:
+                try:
+                    os.unlink(lp)
+                except OSError:
+                    pass
+                continue
+            if time.time() - start > _LOCK_TIMEOUT:
+                raise RuntimeError(
+                    "aw-xref: %s has been locked by another run for over %ds. If no other "
+                    "/appweaver command is running, delete %s and re-run."
+                    % (os.path.basename(key), int(_LOCK_TIMEOUT), lp))
+            time.sleep(0.05)
+    _HELD[key] = 1
+    try:
+        yield
+    finally:
+        _HELD.pop(key, None)
+        try:
+            os.unlink(lp)
+        except OSError:
+            pass
+
+
 def _write(path, text):
-    os.makedirs(os.path.dirname(path), exist_ok=True)
-    with open(path, "w", encoding="utf-8") as fh:
-        fh.write(text)
+    parent = os.path.dirname(path)
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+    with _lock(path):
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(text)
 
 
 def _today(arg_date):
@@ -679,15 +765,41 @@ def _git_head_short(root):
 
 
 def _write_xref_rows(path, rows):
-    text = _read(path)
-    body = _render_section(XREF_HEADING, XREF_COMMENT, XREF_HEADER, rows)
-    _write(path, _replace_section(text, XREF_HEADING, body))
+    # The read is INSIDE the lock: splicing a section into a file another process is
+    # rewriting is what loses rows, and taking the lock only for the write would still
+    # splice into a copy that had gone stale between the read and the acquisition.
+    with _lock(path):
+        text = _read(path)
+        body = _render_section(XREF_HEADING, XREF_COMMENT, XREF_HEADER, rows)
+        _write(path, _replace_section(text, XREF_HEADING, body))
 
 
 def _write_deps_rows(path, rows):
-    text = _read(path)
-    body = _render_section(DEPS_HEADING, DEPS_COMMENT, DEPS_HEADER, rows)
-    _write(path, _replace_section(text, DEPS_HEADING, body))
+    with _lock(path):
+        text = _read(path)
+        body = _render_section(DEPS_HEADING, DEPS_COMMENT, DEPS_HEADER, rows)
+        _write(path, _replace_section(text, DEPS_HEADING, body))
+
+
+def _read_anchor_rows(path):
+    return _table_data_rows(_section_text(_read(path), ANCHOR_HEADING))
+
+
+def _write_anchor_rows(path, slice_id, lane, ids, artefacts, recorded):
+    """Requirement → artefact rows for ONE slice, reconciled on write. Every row this
+    slice+lane wrote before is dropped and its current ones re-added, so a story that
+    re-implements against a changed design replaces its claims instead of accumulating
+    them — the same rule the Cross-References rows follow, for the same reason."""
+    with _lock(path):
+        keep = [r for r in _read_anchor_rows(path)
+                if not (len(r) >= 3 and r[1].strip() == slice_id and r[2].strip() == lane)]
+        # Ordered by requirement so a person reading the section can find an id, and two
+        # runs writing the same rows produce the same file.
+        fresh = [[rid, slice_id, lane, artefacts, recorded] for rid in ids]
+        rows = sorted(keep + fresh, key=lambda r: (r[0], r[1] if len(r) > 1 else ""))
+        body = _render_section(ANCHOR_HEADING, ANCHOR_COMMENT, ANCHOR_HEADER, rows)
+        _write(path, _replace_section(_read(path), ANCHOR_HEADING, body))
+        return len(fresh)
 
 
 def _all_concepts(bundle_abs):
@@ -836,45 +948,67 @@ def cmd_concept_upsert(args):
         _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 stories reading before either writes both union against the same
+        # starting list and the second write loses the first's files.
+        with _lock(path):
+            fm, body = _read_fm(_read(path))
+            fm.setdefault("type", "aggregate")
+            fm["title"] = fm.get("title") or aggregate
+            if source_files:
+                if args.merge:
+                    # INCREMENTAL mode: {{files}} is only what THIS run wrote — one story's
+                    # slice, or a delta's changed files — so UNION with what the lane already
+                    # records, never replace. Replacing would drop every file the feature's
+                    # earlier stories generated the moment a second story implements.
+                    existing = fm.get(key) if isinstance(fm.get(key), list) else []
+                    merged = list(existing)
+                    for s in source_files:
+                        if s not in merged:
+                            merged.append(s)
+                    fm[key] = merged
+                else:
+                    fm[key] = source_files
+            # Both keys always present: an absent one reads as "this lane was never
+            # implemented" to every consumer, which is a different claim from "empty".
+            for k in ("source_files", "ui_source_files"):
+                if k not in fm:
+                    fm[k] = []
+            if args.description:
+                fm["description"] = args.description
+            elif "description" not in fm:
+                fm["description"] = f"{aggregate} aggregate."
+            fm.setdefault("origin", origin)
+            rebuilt = (_render_fm(fm) + "\n" + body if body.startswith("\n")
+                       else _render_fm(fm) + "\n\n" + body.lstrip("\n"))
+            _write(path, rebuilt.rstrip("\n") + "\n")   # _read_fm's split drops the final newline
         _ensure_bundle(bundle_abs)
         _ensure_dir_index(path, aggregate)
 
+    # WHICH REQUIREMENT THIS SLICE'S FILES REALISE. The two halves have always been in this
+    # call and were thrown away: the ids the story exercises, and the files the run just
+    # generated. Persisted here so a greenfield feature has the anchor index only a
+    # brownfield source-map.md carried — without it every id comes back unanchored and the
+    # trace pass has to read the whole tree to find out what implements what.
+    anchor_ids = sorted({i for i in re.findall(r'\b[A-Z]{2}-\d+', args.ids or "")})
+    anchors_written = 0
+    if anchor_ids:
+        slice_id = (args.slice_id or "").strip() or "(unnamed slice)"
+        # The cell is table content: a path holding a pipe would silently split it.
+        cell = ", ".join(s.replace("|", r"\|") for s in source_files) or "(no files recorded)"
+        anchors_written = _write_anchor_rows(path, slice_id, lane, anchor_ids, cell,
+                                             _today(args.date))
+
     print(f"[xref] concept {aggregate}: {'created' if created else 'updated'} "
-          f"({len(source_files)} {lane} source file(s) into {key}) — {_rel(path, root)}",
+          f"({len(source_files)} {lane} source file(s) into {key}"
+          + (f", {anchors_written} requirement anchor(s)" if anchors_written else "")
+          + f") — {_rel(path, root)}",
           file=sys.stderr)
     _emit({"aggregate": aggregate, "concept": _rel(path, root), "created": "true" if created else "false",
-           "lane": lane, "key": key, "source_file_count": len(source_files), "root": root})
+           "lane": lane, "key": key, "source_file_count": len(source_files),
+           "anchor_ids": anchor_ids, "anchor_ids_csv": ", ".join(anchor_ids),
+           "anchors_written": anchors_written, "root": root})
     return 0
 
 
@@ -1039,6 +1173,24 @@ def cmd_concept_coverage(args):
     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):
@@ -1110,13 +1262,15 @@ def cmd_concept_coverage(args):
                  % (", ".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.")
+        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:
-            lines.append("REQUIREMENT ANCHORS (%s):" % smap)
+            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 "")))
@@ -1490,6 +1644,9 @@ def main(argv):
     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("--title", default="")
     c.add_argument("--description", default="")
     c.add_argument("--origin", default="greenfield")

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

@@ -4,10 +4,13 @@ type: functional
 status: open
 title: [one line — the outcome this story delivers]
 exercises: []
+constraints: []
 spec_version: [vN.N]
 depends_on: []
 wave: 1
 follows:
+designed_lanes: []
+dropped_lanes: []
 work_item:
 created: [DATE]
 ---
@@ -23,7 +26,8 @@ created: [DATE]
 
   A story is a slice of work over a spec that is already written. It is NEVER a proposal
   to change the spec — nothing here merges back into spec.md. When a story genuinely
-  needs the contract to change, update-spec folds it back through specify's
+  needs the contract to change, sync-spec (⌛ not built yet — the hand route is
+  .appweaver/SPEC-EDIT-PROTOCOL.md) folds it back through specify's
   checklist -> clarify -> validate loop, and the spec's Change History gains a row.
 
   ONE STORY, ONE FEATURE. A story whose design touches a second feature is failed by
@@ -33,7 +37,7 @@ created: [DATE]
   directory scan rather than a markdown parse.
 
     id            Minted by the kit: the feature name plus the next free number in
-                  stories/. user-story refuses to write over an existing file, so a
+                  stories/. The writer refuses to overwrite an existing file, so a
                   collision is an add/add git conflict, never a silent overwrite.
                   change-story-id corrects it while it is still legal — see below.
 
@@ -57,9 +61,19 @@ created: [DATE]
                   id. A requirement is DELIVERED when it has NO OPEN STORIES — not when a
                   particular story closed, because a follow-on may carry the remainder.
 
+    constraints   The spec-level bounds this slice must satisfy: the CN-/DC-/IC-/UX- ids,
+                  lifted from spec.md by the kit and never typed by hand. Spec constraints
+                  are declared aggregate-wide, so the feature's WHOLE set binds every slice
+                  of it and there is nothing to choose. This field is the gate surface —
+                  implement, implement-ui and analyze-slice read it — and the "## Constraints"
+                  section below is where each id gets the line saying what THIS slice does
+                  about it. Stamped by sync-stories; a story written before this field
+                  existed has no key at all, and its readers fall back to the section.
+
     spec_version  The spec version this story last synced at. A row above this version
-                  naming an id in exercises means the story is stale; check-stories
-                  reports it and sync-stories acts on it. Restamped on every sync.
+                  naming an id in exercises OR constraints means the story is stale;
+                  check-stories reports it and sync-stories acts on it. Restamped on
+                  every sync.
 
     depends_on    Story ids that must land first, e.g. [Payment-004]. About CODE ordering,
                   not spec: implement warns on an open dependency, which is where calling
@@ -83,6 +97,16 @@ created: [DATE]
                   its own dependencies are done, whatever else shares its wave. A story
                   raised by hand floors at 1 — nothing is KNOWN to come first.
 
+    designed_lanes  Which lanes story-plan actually designed, e.g. [backend, frontend].
+    dropped_lanes   Which lanes it DROPPED, and why the pair exists: a story with no UI
+                  design either has no user-facing surface or had its UI lane dropped when
+                  it was designed — an undeclared frontend lane, or a frontend-plan.md
+                  missing or behind the spec — and one field cannot say which. Written by
+                  story-plan (never by sync-stories: stories are not designed there);
+                  designed accumulates across passes, dropped holds what has been dropped
+                  and not since designed. Both absent on a story that predates them, which
+                  implement-ui reports as exactly that rather than guessing.
+
     follows       On a follow-on only: the story id this one carries the remainder of.
                   When the spec moves under a story that already has a story plan,
                   sync-stories leaves that story untouched and mints a follow-on
@@ -126,10 +150,17 @@ As a [role], I want [capability], so that [outcome].
      a standard the product does not hold, and they are the half most often lost: they
      reach no UI phase except through the story.
 
+     THE IDS ARE STAMPED FOR YOU into `constraints:` above — the kit lifts every one the
+     spec declares, because spec constraints bind the aggregate rather than a single
+     operation. This section is where each gets its LINE. Write one per id saying what
+     this slice has to do about it, and where one genuinely does not apply, say so in its
+     line rather than dropping it: an omission used to be indistinguishable from a bound
+     nobody noticed, which is how a slice gets built without one.
+
      These are NOT in `exercises:`. That field is FR-/BR- only, because it is the
      delivery relation — what this story DELIVERS — and a constraint is not delivered,
      it is met. story-plan carries these ids into its design pass; analyze-slice
-     traces it. Write "None" for a class that does not touch this story. -->
+     traces it. -->
 
 - **[UX-00n]** — [what this slice must satisfy of it]
 
@@ -144,4 +175,4 @@ As a [role], I want [capability], so that [outcome].
 ## Notes
 
 <!-- Optional: sequencing, risks, what is deliberately out of this slice. Anything that
-     belongs to the CONTRACT belongs in spec.md via update-spec, not here. -->
+     belongs to the CONTRACT belongs in spec.md via sync-spec, not here. -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aw-spec-cli",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "AppWeaver Spec-Driven Development CLI - scaffolds projects with vertical slices, DDD, CQRS, and agent skills",
   "type": "module",
   "main": "dist/index.js",