aw-spec-cli 0.1.15 → 0.1.16

package/assets/.appweaver/scripts/bash/aw-spec-actions.sh

@@ -1312,9 +1312,19 @@ if op == "check":
                    "document is behind its own ledger" % (doc_ver or "no version", recorded_ver))
     else:
         out["state"] = "unledgered_edit"
+        # BOTH ROUTES, BECAUSE NOT EVERY EDIT HAS AN ID TO NAME. Law 5 requires a version row
+        # to name at least one id, so an edit to Aggregate Boundary, Experience Scope or any
+        # other load-bearing prose has nothing legal to put in the cell — and being told to
+        # "add a row naming the ids you changed" sent that person round a loop with no exit.
+        # The protocol has always sanctioned re-baselining instead when the diff finds no id
+        # (SPEC-EDIT-PROTOCOL.md, "The short version" step 4 and the PR checklist); it was
+        # simply never named at the one place anybody reads it.
         out.update(ok=False, error="spec.md has changed since %s but no Change History row "
                    "was added. Every story citing an edited requirement is now silently "
-                   "stale. Add a row naming the ids you changed, then re-run."
+                   "stale. Add a row naming the ids you changed, then re-run — or, if this "
+                   "edit touched NO requirement (prose only: scope, boundary, wording that "
+                   "defines no id), re-run spec-stamp to re-baseline instead. Run spec-diff "
+                   "against the snapshot to see which of the two this is."
                    % recorded_ver)
 elif op == "stamp":
     # THE VERSION IS THE HIGHEST OF THE THREE PLACES ONE IS WRITTEN, and the document's
@@ -1483,9 +1493,24 @@ def parse_fm(text):
             fm[key] = (fm[key] + ", " + im.group(1).strip()) if fm[key] else im.group(1).strip()
     return fm
 
-def frontmatter(path):
-    try: return parse_fm(open(path, encoding="utf-8", errors="replace").read())
-    except Exception: return {}
+def read(path):
+    try: return open(path, encoding="utf-8", errors="replace").read()
+    except Exception: return ""
+
+def bound_ids(fm, text):
+    """The constraint ids this story is built to satisfy. Read from the `constraints:`
+    FRONTMATTER field, which story-stamp lifts from the spec — the body's `## Constraints`
+    section is model-authored prose, so an id the model left out of it would be invisible to
+    exactly the scan that exists to notice a bound moving under someone.
+
+    ABSENT IS NOT EMPTY. A story written before the field existed has no key at all and its
+    ids are still only in the body, so that case falls back to the section. An explicitly
+    empty `constraints: []` is an answer — this story is bound by nothing — and is taken as
+    one. The fallback goes when every live backlog has been re-stamped."""
+    if "constraints" in fm:
+        return sorted(set(re.findall(r'\b(?:CN|DC|IC|UX)-\d+', fm["constraints"])))
+    bm = re.search(r'^##\s+Constraints\s*$(.*?)(?=^##\s|\Z)', text, re.M | re.S)
+    return sorted(set(re.findall(r'\b(?:CN|DC|IC|UX)-\d+', bm.group(1)))) if bm else []
 
 stories = []
 if os.path.isdir(sdir):
@@ -1493,14 +1518,18 @@ if os.path.isdir(sdir):
         if not name.endswith(".md"): continue
         path = os.path.join(sdir, name)
         if not os.path.isfile(path): continue
-        fm = frontmatter(path)
+        text = read(path); fm = parse_fm(text)
         sid = fm.get("id") or name[:-3]
         # An unparseable story is reported as open rather than skipped: a story the scan
         # cannot read is exactly the one whose requirements must not move unannounced.
         status = (fm.get("status") or "open").strip().lower()
         cites = [c.strip() for c in re.findall(r'[A-Z]{2}-\d+', fm.get("exercises", ""))]
+        bounds = bound_ids(fm, text)
         stories.append({"id": sid, "status": status, "exercises": cites,
                         "cites_csv": ", ".join(cites),
+                        "constraints": bounds,
+                        "constraints_csv": ", ".join(bounds),
+                        "carried": sorted(set(cites) | set(bounds)),
                         "title": (fm.get("title") or "").strip().strip("[]"),
                         "spec_version": (fm.get("spec_version") or "").strip(),
                         "type": (fm.get("type") or "functional").strip().lower(),
@@ -1508,17 +1537,25 @@ if os.path.isdir(sdir):
                         "in_flight": os.path.isdir(os.path.join(sdir, sid))})
 
 open_stories = [s for s in stories if s["status"] == "open"]
+# TWO SETS, DELIBERATELY DIFFERENT. `covered` is the DELIVERY relation — what open stories
+# are delivering — and analyze-slice subtracts it from a feature-scoped run as "these have
+# open stories" (law 39). A constraint is met, never delivered, so folding one in here would
+# drop a bound the code must still satisfy out of the feature gate's scope.
+# `carried` is the wider question specify has to ask: what would an open story FEEL if this
+# ran moved it. That one has to include the bounds, or amending a CN-/DC-/IC-/UX- disturbs
+# stories built against it and nothing anywhere says so (law 15).
 covered = sorted({c for s in open_stories for c in s["exercises"]})
+carried = sorted({c for s in open_stories for c in s["carried"]})
 
 # ASKING ABOUT NOTHING IS NOT ASKING ABOUT EVERYTHING. `--ids ""` is a caller saying "this
 # run disturbed no requirement" — a pure addition — and the answer is an empty set. Only
 # the absence of the flag means "tell me about the whole backlog". Conflating the two made
 # an enhancement that touched nothing existing prompt about every requirement with a story.
-targets = queried if os.environ.get("AW_IDS_GIVEN") else covered
+targets = queried if os.environ.get("AW_IDS_GIVEN") else carried
 
 affected, aff_ids, aff_stories, inflight = [], [], [], []
 for rid in targets:
-    hit = [s for s in open_stories if rid in s["exercises"]]
+    hit = [s for s in open_stories if rid in s["carried"]]
     if not hit: continue
     aff_ids.append(rid)
     names = [s["id"] for s in hit]
@@ -1536,9 +1573,10 @@ unlinked = [rid for rid in targets if rid not in aff_ids]
 # is not something an author can answer about: what it cites and whether someone is already
 # implementing it are the whole basis of the decision.
 digest = "\n".join(
-    "  %-16s %-9s %-11s cites %s%s" % (
+    "  %-16s %-9s %-11s cites %s%s%s" % (
         s["id"], s["status"], "IN FLIGHT" if s["in_flight"] else "not started",
         s["cites_csv"] or "nothing",
+        ("  bound by " + s["constraints_csv"]) if s["constraints_csv"] else "",
         ("  @ " + s["spec_version"]) if s["spec_version"] else "")
     for s in open_stories) or "  (no open stories)"
 
@@ -1547,6 +1585,8 @@ print(json.dumps({
     "story_count": len(stories), "open_count": len(open_stories),
     "stories": stories, "digest": digest,
     "queried": queried, "covered": covered, "covered_csv": ", ".join(covered),
+    "carried": carried, "carried_csv": ", ".join(carried),
+    "carried_count": len(carried), "any_carried": bool(carried),
     "affected": affected, "affected_ids": aff_ids, "affected_csv": ", ".join(aff_ids),
     "unlinked": unlinked, "unlinked_csv": ", ".join(unlinked),
     "unlinked_count": len(unlinked), "any_unlinked": bool(unlinked),
@@ -1718,6 +1758,18 @@ def rids(s):
         if t not in seen: seen.add(t); out.append(t)
     return sorted(out, key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
 
+def nids(s):
+    """The classes a row can name that a STORY cannot be raised for: the bounds a slice is
+    built to satisfy and the outcomes the feature gate scores. Kept apart from rids()
+    rather than widening it, because the work set drives story creation and a story for a
+    success criterion is not a thing — but a row that moved one of these still has to be
+    said out loud, and until now it produced an empty work set and a run that stopped with
+    'the backlog is already in step'."""
+    seen, out = set(), []
+    for t in re.findall(r'\b(?:CN|DC|IC|UX|SC)-\d+', s or ""):
+        if t not in seen: seen.add(t); out.append(t)
+    return sorted(out, key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
+
 def parse_fm(text):
     """Frontmatter as a flat dict. A value may be inline (`exercises: [FR-001, BR-002]`) or
     a YAML block list under an empty key — both are valid YAML and a hand edit produces
@@ -1761,7 +1813,8 @@ for i in row_lines:
     # note somebody left in the table. It records no version, so it orders against nothing.
     if not re.match(r'^v\d', c[0]): continue
     rows.append({"version": c[0], "date": c[1], "change": c[2], "ids_cell": c[3],
-                 "stories": c[4], "requirements": rids(c[3])})
+                 "stories": c[4], "requirements": rids(c[3]),
+                 "non_story": nids(c[3])})
 rows.sort(key=lambda r: vtuple(r["version"]))
 
 # WHAT THE DOCUMENT STILL DECLARES. Read from the requirement's DEFINING line — the bolded
@@ -1833,6 +1886,8 @@ if not rows:
     # backlog against a document nobody has committed to.
     out.update(work_csv="", work_count=0, work_source="none", span_versions_csv="",
                gap=False, removed_csv="",
+               non_story_csv="", non_story_count=0, non_story_any=False,
+               work_kind="none",
                work_note="the Change History table carries no version row")
     print(json.dumps(out)); sys.exit(0)
 
@@ -1912,8 +1967,25 @@ for rid in candidates:
 removed = [i for i in work if i not in declared]
 work = [i for i in work if i in declared]
 
+# WHAT MOVED THAT NO STORY CAN BE RAISED FOR. Constraints and success criteria travel in
+# the same version rows as requirements and are read by the same downstream gates, but they
+# produce no work set — so a row naming only those left this run stopping at "the backlog is
+# already in step. Nothing was written." about the exact ids story-plan-check had just
+# reported as stale. Carried out separately so the caller can say so without the work gate
+# having to admit ids it must not slice.
+#
+# work_kind IS FOR THE LOG, NOT FOR THE BRANCH. A row naming FR-001 AND CN-001 is
+# `story` — the work set is real — and branching on the enum alone would print the
+# requirement path, sync the stories, and say nothing at all about the constraint. The
+# caller announces on non_story_csv being non-empty, whatever work_any says.
+non_story = sorted({i for r in span for i in r["non_story"]},
+                   key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
+work_kind = ("story" if work else ("non_story" if non_story else "none"))
+
 out.update(work_csv=", ".join(work), work_count=len(work), work_source=source,
            work_note=note, work_any=bool(work),
+           non_story_csv=", ".join(non_story), non_story_count=len(non_story),
+           non_story_any=bool(non_story), work_kind=work_kind,
            candidates_csv=", ".join(candidates), candidate_count=len(candidates),
            in_step_csv=", ".join(in_step), in_step_count=len(in_step),
            floor_source=floor_source,
@@ -2530,6 +2602,7 @@ PY
 # carrying a work_item or a depends_on must not lose it to a stamp.
 cmd_story_stamp() {
     local fd_arg="" story="" ids="" version="" follows="" ids_given="" title="" deps="" wave=""
+    local cons_given="" designed="" designed_given="" dropped="" dropped_given=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --feature-dir) fd_arg="$2"; shift 2 ;;
@@ -2540,7 +2613,14 @@ cmd_story_stamp() {
             --title)   title="$2";   shift 2 ;;
             --depends-on) deps="$2"; shift 2 ;;
             --wave)    wave="$2";    shift 2 ;;
-            --help|-h) echo "story-stamp --story <id> [--ids <csv>] [--version <v>] [--follows <id>] [--title <t>] [--depends-on <csv>] [--wave <n>] [--feature-dir <p>]"; return 0 ;;
+            # A BARE FLAG, NOT A CSV: the ids are lifted from the spec this op already has
+            # a --feature-dir for. Nothing upstream has to enumerate them, and the second
+            # caller (story-plan) can write the lane keys without re-lifting constraints
+            # from a spec that may have moved past this story's spec_version.
+            --constraints) cons_given=1; shift ;;
+            --designed-lanes) designed="$2"; designed_given=1; shift 2 ;;
+            --dropped-lanes)  dropped="$2";  dropped_given=1;  shift 2 ;;
+            --help|-h) echo "story-stamp --story <id> [--ids <csv>] [--version <v>] [--follows <id>] [--title <t>] [--depends-on <csv>] [--wave <n>] [--constraints] [--designed-lanes <csv>] [--dropped-lanes <csv>] [--feature-dir <p>]"; return 0 ;;
             *) echo "story-stamp: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -2549,7 +2629,9 @@ cmd_story_stamp() {
     local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "story-stamp: no feature set and no --feature-dir" >&2; return 1; }
     AW_FD="$fd" AW_STORY="$story" AW_IDS="$ids" AW_IDS_GIVEN="$ids_given" \
     AW_VER="$version" AW_FOLLOWS="$follows" AW_TITLE="$title" \
-    AW_DEPS="$deps" AW_WAVE="$wave" python3 - <<'PY'
+    AW_DEPS="$deps" AW_WAVE="$wave" AW_CONSTRAINTS_GIVEN="$cons_given" \
+    AW_DESIGNED="$designed" AW_DESIGNED_GIVEN="$designed_given" \
+    AW_DROPPED="$dropped" AW_DROPPED_GIVEN="$dropped_given" python3 - <<'PY'
 import json, os, re, sys, datetime
 fd = os.environ["AW_FD"]; story = os.environ["AW_STORY"].strip()
 path = os.path.join(fd, "stories", story + ".md")
@@ -2577,6 +2659,47 @@ def sids(s):
             seen.add(t); out.append(t)
     return out
 
+def cids(s):
+    """Constraint ids, deduped and ordered by class then number so two readers of the same
+    text always produce the same csv. SC- is NOT one of these: a success criterion is a
+    feature-level outcome analyze-slice scores, not a bound a slice is built to satisfy,
+    and putting one here would hand it to the generation prompt as a bound."""
+    seen, out = set(), []
+    for t in re.findall(r'\b(?:CN|DC|IC|UX)-\d+', s or ""):
+        if t not in seen: seen.add(t); out.append(t)
+    return sorted(out, key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
+
+def lanes(s):
+    """backend / frontend out of a csv or an inline list. Anything else is not a lane."""
+    out = []
+    for t in re.split(r'[,\s\[\]"\']+', (s or "").lower()):
+        if t in ("backend", "frontend") and t not in out: out.append(t)
+    return sorted(out)
+
+COV = re.compile(r'<!--\s*AW:COVERAGE:BEGIN\s*-->.*?<!--\s*AW:COVERAGE:END\s*-->', re.S)
+# An id keyed to the line that DEFINES it, in the two shapes the spec template uses:
+# a leading table cell (Data Classification) and a bold id opening a bullet (everything
+# else). The same two shapes spec-diff scores, for the same reason — a cross-reference
+# inside another requirement's prose defines nothing.
+DEF_CELL = re.compile(r'^\s*\|\s*((?:CN|DC|IC|UX)-\d+)\s*\|')
+DEF_BULL = re.compile(r'^\s*(?:[-*+]\s+)?\*\*((?:CN|DC|IC|UX)-\d+)\*\*')
+
+def spec_constraints():
+    """Every constraint id the spec DEFINES. Spec constraints are declared aggregate-wide —
+    "constraints that must ALWAYS hold for the aggregate, independent of any single
+    operation" — so there is no per-requirement relation to infer and no judgment to make:
+    the feature's whole constraint set binds every slice of it. Change History is cut away
+    first (its rows NAME ids without defining them), and so is the coverage block."""
+    sp = os.path.join(fd, "spec.md")
+    if not os.path.isfile(sp): return []
+    t = COV.sub("", open(sp, encoding="utf-8", errors="replace").read())
+    t = re.split(r'^##\s+Change History\s*$', t, maxsplit=1, flags=re.M)[0]
+    found = []
+    for line in t.split("\n"):
+        m = DEF_CELL.match(line) or DEF_BULL.match(line)
+        if m and m.group(1) not in found: found.append(m.group(1))
+    return sorted(found, key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
+
 text = open(path, encoding="utf-8", errors="replace").read()
 m = re.match(r'^---\s*\n(.*?)\n---\s*\n', text, re.S)
 if m:
@@ -2610,8 +2733,9 @@ def put(key, value):
     order.append([key, [line]])
     return "added"
 
-TEMPLATE_ORDER = ["id", "type", "status", "title", "exercises", "spec_version",
-                  "depends_on", "wave", "follows", "work_item", "created"]
+TEMPLATE_ORDER = ["id", "type", "status", "title", "exercises", "constraints",
+                  "spec_version", "depends_on", "wave", "follows",
+                  "designed_lanes", "dropped_lanes", "work_item", "created"]
 def get(key):
     for entry in order:
         if entry[0] == key: return entry[1][0].split(":", 1)[1].strip()
@@ -2626,6 +2750,17 @@ if os.environ.get("AW_IDS_GIVEN"):
 else:
     ids = rids(get("exercises"))
 
+# THE BOUNDS THIS SLICE MUST MEET, AS A FRONTMATTER FIELD THE KIT WRITES. Everything a gate
+# reads lives in frontmatter; the story's `## Constraints` section was the one exception,
+# and being model-authored it could omit an id with nothing able to notice — a missing bound
+# in a generation prompt that never opens the spec. Lifted here, so the gate surface is
+# complete by construction and the section keeps its per-slice prose.
+if os.environ.get("AW_CONSTRAINTS_GIVEN"):
+    cons = spec_constraints()
+    changed["constraints"] = put("constraints", "[" + ", ".join(cons) + "]")
+else:
+    cons = cids(get("constraints"))
+
 ver = (os.environ.get("AW_VER") or "").strip()
 if ver: changed["spec_version"] = put("spec_version", ver)
 
@@ -2660,6 +2795,22 @@ if wv.isdigit():
     changed["wave"] = put("wave", wv)
 elif not get("wave").isdigit():
     changed["wave"] = put("wave", "1")
+
+# WHICH LANES WERE DESIGNED, AND WHICH WERE DROPPED — two fields, because one of them cannot
+# say the difference. analyze-design STOPS on a lane whose plan is behind; story-plan DROPS
+# it and designs the other, so one command later "this slice has no user-facing surface" and
+# "the UI lane was out of scope when this was designed" are the same state on disk, and a
+# UX--bearing requirement can ship backend-only with a green story-scoped gate.
+# Designed ACCUMULATES across passes (a lane that has a design keeps having one); dropped is
+# whatever has been dropped and not since designed, so the two never both claim a lane.
+if os.environ.get("AW_DESIGNED_GIVEN") or os.environ.get("AW_DROPPED_GIVEN"):
+    designed = sorted(set(lanes(get("designed_lanes")))
+                      | set(lanes(os.environ.get("AW_DESIGNED", ""))))
+    dropped = sorted((set(lanes(get("dropped_lanes")))
+                      | set(lanes(os.environ.get("AW_DROPPED", "")))) - set(designed))
+    changed["designed_lanes"] = put("designed_lanes", "[" + ", ".join(designed) + "]")
+    changed["dropped_lanes"] = put("dropped_lanes", "[" + ", ".join(dropped) + "]")
+
 if not get("created") or get("created").startswith("["):
     changed["created"] = put("created", datetime.date.today().isoformat())
 for k in ("title", "follows", "work_item"):
@@ -2672,8 +2823,26 @@ order.sort(key=lambda e: rank.get(e[0], len(TEMPLATE_ORDER)))
 out_block = "\n".join(l for e in order for l in e[1])
 open(path, "w", encoding="utf-8").write("---\n" + out_block + "\n---\n\n" + body.lstrip("\n"))
 
+# THE STAMP OWNS THE ID SET; THE SECTION KEEPS ITS PROSE. `## Constraints` is not a list of
+# ids — each line says what THIS slice has to do about the bound it names, and that line is
+# the whole reason the section is worth reading. So the body is RECONCILED, never rewritten:
+# an id now in the frontmatter with no line in the section is reported for the caller to
+# announce, and a line naming an id the spec no longer defines is reported the same way.
+# Neither is silently written or silently deleted.
+bm = re.search(r'^##\s+Constraints\s*$(.*?)(?=^##\s|\Z)', body, re.M | re.S)
+body_ids = set(cids(bm.group(1))) if bm else set()
+unlined = [c for c in cons if c not in body_ids]
+orphan_lines = sorted(body_ids - set(cons),
+                      key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
+
 print(json.dumps({"ok": True, "story": story, "path": path,
                   "exercises": ids, "exercises_csv": ", ".join(ids),
+                  "constraints": cons, "constraints_csv": ", ".join(cons),
+                  "unlined_csv": ", ".join(unlined), "unlined_any": bool(unlined),
+                  "orphan_lines_csv": ", ".join(orphan_lines),
+                  "constraints_reconciled": not (unlined or orphan_lines),
+                  "designed_lanes": get("designed_lanes"),
+                  "dropped_lanes": get("dropped_lanes"),
                   "spec_version": get("spec_version"), "status": get("status"),
                   "depends_on": get("depends_on"), "wave": get("wave"),
                   "follows": get("follows"), "title": get("title"),
@@ -2893,6 +3062,60 @@ def scan(path):
     return out
 def ids(path):
     return {k: v[2] for k, v in scan(path).items()}
+# A DEFINITION THE SCAN CANNOT KEY IS A REQUIREMENT THAT CAN CHANGE WITH NO LEDGER RECORD OF
+# IT. The parser keys an id to the line that defines it and hashes the block under it; three
+# authoring forms fall outside that and each one is silent — the edit lands, change_count
+# stays 0, no row is appended, and spec-stamp re-baselines the new body as clean, for every
+# story citing that id. Reported rather than parsed around: widening the parser to accept
+# them would make the ledger's shapes whatever anyone happened to type, and the fix a person
+# wants here is to write the requirement in the form the template uses.
+LOOSE_DEF = re.compile(r'^\s*(?:[-*+]\s+)?([A-Z]{2}-\d+)\s*[:—–-]')
+def unkeyed_warnings(path, keyed):
+    warn = []
+    if not path or not os.path.isfile(path): return warn
+    raw = COV.sub("", open(path, encoding="utf-8", errors="replace").read())
+    hm = HIST.search(raw)
+    above, below = (raw[:hm.start()], raw[hm.end():]) if hm else (raw, "")
+    lines = above.split("\n")
+    plain = []
+    for line in lines:
+        m = LOOSE_DEF.match(line)
+        if m and m.group(1) not in keyed and m.group(1) not in plain: plain.append(m.group(1))
+    if plain:
+        warn.append("written without bold ids (`- %s: …` rather than `- **%s**: …`), so the "
+                    "diff cannot key them to a definition and an edit to one raises no "
+                    "ledger row: %s" % (plain[0], plain[0], ", ".join(sorted(plain))))
+    if hm:
+        low = []
+        for line in below.split("\n"):
+            m = DEF_CELL.match(line) or DEF_BULL.match(line) or LOOSE_DEF.match(line)
+            if m and m.group(1) not in keyed and m.group(1) not in low: low.append(m.group(1))
+        if low:
+            warn.append("defined BELOW the '## Change History' table, where the scan stops "
+                        "— the ledger reads nothing under its own table, so these are "
+                        "invisible to every version comparison: %s" % ", ".join(sorted(low)))
+    orphaned = []
+    for n, line in enumerate(lines):
+        m = DEF_CELL.match(line) or DEF_BULL.match(line) or DEF_OPEN.match(line)
+        if not m: continue
+        j = n + 1
+        while (j < len(lines) and lines[j].strip()
+               and not lines[j].lstrip().startswith("#") and not is_def(lines[j])):
+            j += 1
+        # j is the first line outside the hashed block. A BLANK there, followed by indented
+        # prose that opens no new definition, is a continuation the hash cannot see.
+        if j < len(lines) and not lines[j].strip():
+            k = j + 1
+            if (k < len(lines) and lines[k].strip()
+                    and (lines[k].startswith(" ") or lines[k].startswith("\t"))
+                    and not is_def(lines[k]) and not lines[k].lstrip().startswith("#")
+                    and m.group(1) not in orphaned):
+                orphaned.append(m.group(1))
+    if orphaned:
+        warn.append("carry continuation text below a BLANK line — the hashed block ends at "
+                    "the blank, so anything under it can be rewritten with no diff: %s"
+                    % ", ".join(sorted(orphaned)))
+    return warn
 # Ids the ledger has already spent. An id is PERMANENT: re-issuing one silently re-points
 # stories, designs and code that have already shipped. Read from the SNAPSHOT's history, so
 # it is what the ledger said before this run, and only meaningful when there is a snapshot.
@@ -2915,6 +3138,7 @@ reissued = sorted(set(added) & spent(snap))
 # requirements this run touched" asks it to raise a story for a success criterion.
 STORY_CLASS = ("FR-", "BR-")
 story_ids = [c for c in changed if c.startswith(STORY_CLASS)]
+warnings = unkeyed_warnings(spec, set(after))
 print(json.dumps({
     "ok": True, "had_snapshot": bool(snap and os.path.isfile(snap)),
     "added": added, "removed": removed, "modified": modified,
@@ -2937,6 +3161,12 @@ print(json.dumps({
     # changed, narrowed to the classes a story can cite — what sync-stories works from.
     "story_ids": story_ids, "story_ids_csv": ", ".join(story_ids),
     "story_id_count": len(story_ids),
+    # Ids the document states in a form the ledger cannot key to a definition. Not a
+    # verdict on this run's changes — a standing property of the document, reported every
+    # time because the requirement it describes can move silently until it is rewritten.
+    "warnings": warnings, "warning_count": len(warnings),
+    "any_warnings": bool(warnings),
+    "warnings_note": "  //  ".join(warnings),
 }))
 PY
     return 0
@@ -3136,12 +3366,33 @@ _project_markers() {
       | sed "s#^$repo_root/##" | LC_ALL=C sort | head -20
 }
 
+# Does a manifest belong to the ecosystem the caller asked about. The repo-scope fallback
+# below is deliberate — a .NET solution legitimately sits ABOVE the lane it scaffolds — but
+# it answers with whatever manifest it finds, so in a two-lane repo where only the frontend
+# is scaffolded the service lane's gate passes on the frontend's package.json. Knowing the
+# lane's ecosystem is what turns that hit back into a miss.
+_marker_ecosystem() {
+    case "${1##*/}" in
+        *.sln|*.csproj)                       printf 'dotnet' ;;
+        package.json)                         printf 'node' ;;
+        pom.xml|build.gradle|build.gradle.kts) printf 'java' ;;
+        go.mod)                               printf 'go' ;;
+        Cargo.toml)                           printf 'rust' ;;
+        pyproject.toml)                       printf 'python' ;;
+        *)                                    printf '' ;;
+    esac
+}
+
 cmd_detect_project() {
-    local scope_root=""
+    local scope_root="" ecosystem=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --root|--source-path) scope_root="$2"; shift 2 ;;
-            --help|-h) echo "detect-project [--root <dir>]  -> {scaffolded, markers[], scope}"; return 0 ;;
+            # The lane's ecosystem, passed in by the caller that already resolved it.
+            # NOT re-derived here: lane-gate binds it from stacks.json before this op runs,
+            # and a second guess is a second thing to keep in step with that file.
+            --ecosystem) ecosystem="$2"; shift 2 ;;
+            --help|-h) echo "detect-project [--root <dir>] [--ecosystem <name>]  -> {scaffolded, markers[], scope, ecosystem_match}"; return 0 ;;
             *) echo "detect-project: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -3161,7 +3412,18 @@ cmd_detect_project() {
     fi
     local scaffolded=false
     [ ${#markers[@]} -gt 0 ] && scaffolded=true
-    printf '{"scaffolded":%s,"markers":%s,"scope":"%s"}\n' "$scaffolded" "$(json_str_array "${markers[@]}")" "$scope"
+    # UNASKED IS NOT UNMATCHED. With no --ecosystem the caller has told us nothing to
+    # judge against, and answering false there would fail every existing call site.
+    local match=true m_eco
+    if [ -n "$ecosystem" ] && [ "$scaffolded" = true ]; then
+        match=false
+        for m in "${markers[@]}"; do
+            m_eco=$(_marker_ecosystem "$m")
+            [ "$m_eco" = "$ecosystem" ] && { match=true; break; }
+        done
+    fi
+    printf '{"scaffolded":%s,"markers":%s,"scope":"%s","ecosystem":"%s","ecosystem_match":%s}\n' \
+        "$scaffolded" "$(json_str_array "${markers[@]}")" "$scope" "$ecosystem" "$match"
 }
 
 
@@ -4744,7 +5006,8 @@ def vtuple(v):
     try: return tuple(int(x) for x in v.lstrip("vV").split("."))
     except Exception: return (0,)
 out = {"doc": doc, "doc_exists": os.path.isfile(doc), "state": "", "derived_version": "",
-       "current_version": "", "changed_csv": "", "changed_summary": "", "body_changed": False}
+       "current_version": "", "changed_csv": "", "changed_summary": "",
+       "body_changed": False, "body_sha256": ""}
 # Current version = the widest of the ledger's rows and the **Version** header — the
 # same widest-wins rule ledger-append uses, so a hand-moved header cannot hide a row.
 rows = []; cur = ""; idcol = -1
@@ -4764,6 +5027,13 @@ if os.path.isfile(spec):
 out["current_version"] = cur
 if not out["doc_exists"]:
     out["state"] = "fresh"; print(json.dumps(out)); sys.exit(0)
+# THE HASH ITSELF, not only the boolean it was reduced to. "Has this document moved since it
+# was stamped" answers the freshness question; WHICH shape it is now is what a gate verdict
+# has to record and a story pass has to name, or approved-then-changed-then-never-re-approved
+# has nothing to compare against. Taken before the untracked exit so a document with no
+# derivation record still reports what it is.
+body = open(doc, encoding="utf-8", errors="replace").read()
+out["body_sha256"] = hashlib.sha256(body.encode("utf-8")).hexdigest()
 try: track = json.load(open(track_path, encoding="utf-8"))
 except Exception: track = {}
 entry = track.get(os.path.basename(doc))
@@ -4774,8 +5044,7 @@ if not entry:
     out["state"] = "untracked"; print(json.dumps(out)); sys.exit(0)
 derived = entry.get("spec_version", "")
 out["derived_version"] = derived
-body = open(doc, encoding="utf-8", errors="replace").read()
-out["body_changed"] = hashlib.sha256(body.encode("utf-8")).hexdigest() != entry.get("sha256", "")
+out["body_changed"] = out["body_sha256"] != entry.get("sha256", "")
 moved = [r for r in rows if vtuple(r[0]) > vtuple(derived)]
 # Scrape ONLY the ledger's "Requirements changed" cell when it names one. The
 # Stories cell holds ids of the form <Aggregate>-nnn, which read as requirement ids
@@ -4967,6 +5236,91 @@ print(json.dumps({"ok": True, "result_file": out, "status": res["status"], "gap_
 PY
 }
 
+# ──────────────────────────────── gate-read ────────────────────────────────
+# THE OTHER HALF OF gate-result. Every gate has written a machine-readable verdict beside
+# its report for some time and nothing in the kit read one back, so "was this certified,
+# and against what" was a question only a human opening the JSON could answer — which is
+# why law 40 (approved, changed, never re-approved must not reach code) had no enforcement
+# anywhere: the record existed and had no reader.
+#
+# Always exits 0. A missing verdict is not an error here — it is the answer "never
+# certified", and the caller's verify_context owns the stop (the lane-verify convention).
+#
+# TWO ABSENCES THAT LOOK ALIKE AND ARE NOT. A gate that never ran leaves no file. A gate
+# that STARTED and aborted leaves the red gate_result_open writes before any analysis, whose
+# note says so. Both mean "nobody certified this"; neither means "certified and failed",
+# and routing them to 'go read the gaps' sends someone to a report with none in it. So
+# `certified` is reported apart from `status`, and `aborted` names the second case.
+cmd_gate_read() {
+    local fd_arg="" gate="" report="" file=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --gate)   gate="$2";   shift 2 ;;
+            --report) report="$2"; shift 2 ;;
+            --file)   file="$2";   shift 2 ;;
+            --help|-h) echo "gate-read --gate <name> [--report <path>] [--file <path>] [--feature-dir <p>]"; return 0 ;;
+            *) echo "gate-read: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$gate" ] || { echo "gate-read: --gate required" >&2; return 1; }
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "gate-read: no feature set and no --feature-dir" >&2; return 1; }
+    AW_GATE="$gate" AW_FD="$fd" AW_REPORT="$report" AW_FILE="$file" python3 - <<'PY'
+import json, os
+gate = (os.environ.get("AW_GATE", "") or "").strip()
+fd = os.environ.get("AW_FD", "")
+report = (os.environ.get("AW_REPORT", "") or "").strip()
+path = (os.environ.get("AW_FILE", "") or "").strip()
+# Resolved the same way gate-result names it, so the writer and the reader cannot drift:
+# beside the markdown report and named after it. The per-gate defaults are the report paths
+# those two workflows set; the dotfile is gate-result's own fallback.
+DEFAULT = {"analyze-design": "plan-analyze-report.json",
+           "analyze-slice": "slice-analyze-report.json"}
+if not path:
+    if report: path = os.path.splitext(report)[0] + ".json"
+    elif gate in DEFAULT: path = os.path.join(fd, DEFAULT[gate])
+    else: path = os.path.join(fd, ".aw-gate-%s.json" % gate)
+
+out = {"ok": True, "gate": gate, "result_file": path, "exists": os.path.isfile(path),
+       "status": "", "certified": False, "aborted": False, "note": "",
+       "spec_version": "", "story": "", "report": "", "generated_at": "",
+       "gap_count": 0, "gap_refs_csv": "",
+       "backend_sha256": "", "frontend_sha256": "",
+       "backend_in_scope": "", "frontend_in_scope": "", "fields": {}}
+res = {}
+if out["exists"]:
+    try: res = json.load(open(path, encoding="utf-8"))
+    except Exception: res = {}
+if not isinstance(res, dict) or not res:
+    out["note"] = ("no readable verdict at %s — this gate has not certified anything here"
+                   % path)
+    print(json.dumps(out)); raise SystemExit(0)
+
+fields = res.get("fields") or {}
+if not isinstance(fields, dict): fields = {}
+out.update(status=(res.get("status") or "").strip(),
+           note=(res.get("note") or "").strip(),
+           spec_version=(res.get("spec_version") or "").strip(),
+           story=(res.get("story") or "").strip(),
+           report=(res.get("report") or "").strip(),
+           generated_at=(res.get("generated_at") or "").strip(),
+           gap_count=res.get("gap_count") or 0,
+           gap_refs_csv=", ".join(res.get("gap_refs") or []),
+           fields=fields,
+           backend_sha256=(fields.get("backend_sha256") or "").strip(),
+           frontend_sha256=(fields.get("frontend_sha256") or "").strip(),
+           backend_in_scope=(fields.get("backend_in_scope") or "").strip(),
+           frontend_in_scope=(fields.get("frontend_in_scope") or "").strip())
+# A verdict written before any analysis ran carries no spec version, because the workflow
+# has not read one yet. That, and not the note's wording, is what separates the aborted red
+# from a real one — the note is prose and prose gets edited.
+out["aborted"] = out["status"] != "pass" and not out["spec_version"]
+out["certified"] = out["status"] == "pass"
+print(json.dumps(out))
+PY
+}
+
 # ─────────────── story-plan-check / story-plan-doc / log-append ───────────────
 # The per-story execution design ("story design") — SHORT-LIVED scaffolding, ONE
 # DOCUMENT PER LANE beside the story: stories/<ID>/story-backend-plan.md and
@@ -5053,7 +5407,18 @@ if os.path.isdir(sdir):
                         "title": (fm.get("title") or "").strip().strip("[]"),
                         "spec_version": (fm.get("spec_version") or "").strip(),
                         "cites": re.findall(r'\b(?:FR|BR)-\d+', fm.get("exercises", "")),
-                        "path": p, "text": text})
+                        "wave": (fm.get("wave") or "").strip(),
+                        "deps": [d for d in re.split(r'[,\s\[\]"\']+',
+                                                     fm.get("depends_on", "") or "")
+                                 if re.match(r'^[A-Za-z][\w.]*-\d+$', d)],
+                        "fm": fm, "path": p, "text": text})
+
+def lanes(s):
+    """backend / frontend out of a csv or an inline list; anything else is not a lane."""
+    out = []
+    for tok in re.split(r'[,\s\[\]"\']+', (s or "").lower()):
+        if tok in ("backend", "frontend") and tok not in out: out.append(tok)
+    return sorted(out)
 open_stories = [s for s in stories if s["status"] == "open"]
 open_ids = [s["id"] for s in open_stories]
 digest = "\n".join("  %-16s %s%s" % (s["id"], s["title"] or "(untitled)",
@@ -5084,11 +5449,18 @@ out = {"ok": True, "stories_dir": sdir, "stories_exist": os.path.isdir(sdir),
        "story_type": "", "is_technical": False,
        "status_msg": "", "story_title": "", "exercises_csv": "", "constraints_csv": "",
        "story_spec_version": "", "current_version": "", "stale_csv": "", "stale_note": "",
+       "story_wave": "", "depends_on_csv": "", "open_deps_csv": "",
+       "unresolved_deps_csv": "", "deps_note": "", "deps_clear": True,
+       "designed_lanes_csv": "", "dropped_lanes_csv": "", "lane_keys_present": False,
+       "be_lane_designed": False, "fe_lane_designed": False,
+       "be_lane_dropped": False, "fe_lane_dropped": False,
        "story_dir": "", "if_tmp": "", "legacy_doc": "", "legacy_doc_exists": False,
        "be_doc_path": "", "be_doc_exists": False, "be_next_pass": 1, "be_pass_tmp": "",
        "be_last_pass": 0, "be_doc_spec_version": "", "be_doc_stale": False,
+       "be_pass_plan_hash": "",
        "fe_doc_path": "", "fe_doc_exists": False, "fe_next_pass": 1, "fe_pass_tmp": "",
        "fe_last_pass": 0, "fe_doc_spec_version": "", "fe_doc_stale": False,
+       "fe_pass_plan_hash": "",
        "adr_path": os.path.join(fd, "adr.md"), "adr_exists": os.path.isfile(os.path.join(fd, "adr.md")),
        "if_path": os.path.join(fd, "interfaces.md"), "if_exists": os.path.isfile(os.path.join(fd, "interfaces.md")),
        "spec_exists": os.path.isfile(spec)}
@@ -5126,12 +5498,66 @@ if status != "open":
     out["status_msg"] = "Story %s %s." % (
         target["id"], verb.get(status, "has status '%s', not open" % status))
 
-# bound constraint ids come from the story BODY's ## Constraints section (they are
-# barred from exercises: by design — met, not delivered)
-cm = re.search(r'^##\s+Constraints\s*$(.*?)(?=^##\s|\Z)', target["text"], re.M | re.S)
-cons = sorted(set(re.findall(r'\b(?:CN|DC|IC|UX)-\d+', cm.group(1)))) if cm else []
+# THE BOUNDS COME FROM FRONTMATTER, which story-stamp lifts from the spec. They are barred
+# from exercises: by design — a constraint is met, not delivered — and they were read out of
+# the BODY's ## Constraints section until that section turned out to be the one gate surface
+# the kit did not write: a model that omitted an id dropped a bound out of the generation
+# prompt with nothing able to contradict it.
+#
+# ABSENT IS NOT EMPTY. A story stamped before the field existed carries its ids only in the
+# body, so a missing key falls back to the section; an explicit `constraints: []` is an
+# answer and is taken as one. The fallback goes once every live backlog is re-stamped.
+if "constraints" in target["fm"]:
+    cons = sorted(set(re.findall(r'\b(?:CN|DC|IC|UX)-\d+', target["fm"]["constraints"])))
+else:
+    cm = re.search(r'^##\s+Constraints\s*$(.*?)(?=^##\s|\Z)', target["text"], re.M | re.S)
+    cons = sorted(set(re.findall(r'\b(?:CN|DC|IC|UX)-\d+', cm.group(1)))) if cm else []
 out["constraints_csv"] = ", ".join(cons)
 
+# WHAT HAS TO LAND FIRST. sync-stories computes depends_on: and wave: and stamps both, and
+# until now nothing downstream read either — the ordering was recorded and never enforced.
+# Two different misses, kept apart: a dependency whose story is still OPEN here is work in
+# progress, and one with no story file in this feature is UNRESOLVED, which is the ordinary
+# shape of a cross-feature edge (Payment-004 from Order) and not the same as satisfied.
+#
+# The wave is surfaced and NOT gated. A story becomes startable when its own dependencies
+# land, not when the whole previous wave finishes, so warning on "an open story in a lower
+# wave" would serialise a wave that exists precisely to be unordered.
+# WHICH LANES THIS STORY WAS DESIGNED FOR, AND WHICH WERE DROPPED. story-plan stamps both,
+# because one of them cannot say the difference: a story with no UI design either has no
+# user-facing surface or had its UI lane dropped when it was designed, and those two states
+# are the same absence on disk. `lane_keys_present` is what keeps the distinction honest for
+# a story stamped before the fields existed — it has NEITHER key, and absent must never be
+# read as "no surface".
+des = lanes(target["fm"].get("designed_lanes", ""))
+drp = lanes(target["fm"].get("dropped_lanes", ""))
+out.update(designed_lanes_csv=", ".join(des), dropped_lanes_csv=", ".join(drp),
+           lane_keys_present=("designed_lanes" in target["fm"]
+                              or "dropped_lanes" in target["fm"]),
+           be_lane_designed=("backend" in des), fe_lane_designed=("frontend" in des),
+           be_lane_dropped=("backend" in drp), fe_lane_dropped=("frontend" in drp))
+
+deps = target["deps"]
+by_id = {s["id"]: s for s in stories}
+open_deps = [d for d in deps if d in by_id and by_id[d]["status"] == "open"]
+unresolved = [d for d in deps if d not in by_id]
+out.update(story_wave=target["wave"], depends_on_csv=", ".join(deps),
+           open_deps_csv=", ".join(open_deps),
+           unresolved_deps_csv=", ".join(unresolved),
+           deps_clear=not (open_deps or unresolved))
+if open_deps or unresolved:
+    parts = []
+    if open_deps:
+        parts.append("still open in this feature: %s" % ", ".join(open_deps))
+    if unresolved:
+        parts.append("no story file here — check the feature that owns them: %s"
+                     % ", ".join(unresolved))
+    out["deps_note"] = (
+        "ORDERING: %s declares depends_on: %s, and %s. This is a notice, not a refusal — "
+        "the dependency is about CODE ordering, and calling into work that has not landed "
+        "is where it starts to cost something."
+        % (target["id"], ", ".join(deps), "; ".join(parts)))
+
 # staleness: ledger rows ABOVE the story's stamp naming an id the story carries —
 # exercises: AND the Constraints section, so a moved bound is announced too
 sv = target["spec_version"]
@@ -5179,12 +5605,21 @@ for lane, stem in (("be", "backend"), ("fe", "frontend")):
         dv = (parse_fm(d).get("spec_version") or "").strip().strip('"')
         out[lane + "_doc_spec_version"] = dv
         out[lane + "_doc_stale"] = bool(dv and cur and vtuple(dv) < vtuple(cur))
+        # THE FEATURE PLAN THIS PASS WAS DESIGNED AGAINST, as analyze-design certified it.
+        # A story pass is written once and read forever, so comparing only the CURRENT plan
+        # against the CURRENT verdict leaves the case law 40 is actually about: a pass
+        # designed against plan H1 still generating after the plan was edited to H2 and
+        # re-gated. The hash is script-written into the pass header by story-plan-doc; the
+        # LAST pass is the one implement builds from, so it is the last one read here.
+        hs = re.findall(r'^##\s+Design pass\s+\d+\b[^\n]*?\(plan\s+([0-9a-f]{8,64})\)',
+                        d, re.M)
+        out[lane + "_pass_plan_hash"] = hs[-1] if hs else ""
 print(json.dumps(out))
 PY
 }
 
 cmd_story_plan_doc() {
-    local fd_arg="" story="" pass_file="" spec_version="" lane="backend"
+    local fd_arg="" story="" pass_file="" spec_version="" lane="backend" plan_hash=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --feature-dir)   fd_arg="$2"; shift 2 ;;
@@ -5192,7 +5627,11 @@ cmd_story_plan_doc() {
             --lane)          lane="$2"; shift 2 ;;
             --pass-file)     pass_file="$2"; shift 2 ;;
             --spec-version)  spec_version="$2"; shift 2 ;;
-            --help|-h) echo "story-plan-doc --story <id> --pass-file <path> [--lane backend|frontend] [--spec-version <v>] [--feature-dir <path>]"; return 0 ;;
+            # The CERTIFIED feature-plan hash — the one analyze-design recorded in its
+            # verdict, never a fresh one taken here. Stamped into the pass header so a pass
+            # keeps saying which plan shape it was designed against long after the plan moved.
+            --plan-hash)     plan_hash="$2"; shift 2 ;;
+            --help|-h) echo "story-plan-doc --story <id> --pass-file <path> [--lane backend|frontend] [--spec-version <v>] [--plan-hash <sha256>] [--feature-dir <path>]"; return 0 ;;
             *) echo "story-plan-doc: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -5200,11 +5639,13 @@ cmd_story_plan_doc() {
     [ -n "$pass_file" ] || { echo "story-plan-doc: --pass-file is required" >&2; return 1; }
     local repo_root; repo_root=$(get_repo_root)
     local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "story-plan-doc: no feature set and no --feature-dir" >&2; return 1; }
-    AW_FD="$fd" AW_STORY="$story" AW_LANE="$lane" AW_PASS="$pass_file" AW_VER="$spec_version" python3 - <<'PY'
+    AW_FD="$fd" AW_STORY="$story" AW_LANE="$lane" AW_PASS="$pass_file" AW_VER="$spec_version" \
+    AW_PLAN_HASH="$plan_hash" python3 - <<'PY'
 import json, os, re, sys, datetime
 fd = os.environ["AW_FD"]; story = os.environ["AW_STORY"].strip()
 pf = os.environ["AW_PASS"]; ver = (os.environ.get("AW_VER") or "").strip()
 lane = (os.environ.get("AW_LANE") or "backend").strip().lower()
+phash = re.sub(r'[^0-9a-f]', '', (os.environ.get("AW_PLAN_HASH") or "").strip().lower())
 sdir = os.path.join(fd, "stories", story)
 doc = os.path.join(sdir, "story-%s-plan.md" % lane)
 
@@ -5265,7 +5706,9 @@ spec_version: ""
 text = open(doc, encoding="utf-8", errors="replace").read()
 nums = [int(n) for n in re.findall(r'^##\s+Design pass\s+(\d+)', text, re.M)]
 n = (max(nums) + 1) if nums else 1
-header = "## Design pass %d — %s%s" % (n, today, (" (spec %s)" % ver) if ver else "")
+header = "## Design pass %d — %s%s%s" % (
+    n, today, (" (spec %s)" % ver) if ver else "",
+    (" (plan %s)" % phash) if phash else "")
 text = text.rstrip("\n") + "\n\n" + header + "\n\n" + content + "\n"
 # frontmatter stamps — first match only, which is the frontmatter by position
 text = re.sub(r'^(updated:).*$', r'\g<1> ' + today, text, count=1, flags=re.M)
@@ -5275,7 +5718,7 @@ if ver:
 open(doc, "w", encoding="utf-8").write(text)
 os.remove(pf)
 print(json.dumps({"ok": True, "doc": doc, "lane": lane, "pass": n, "created": created,
-                  "spec_version": ver, "story_dir": sdir}))
+                  "spec_version": ver, "plan_hash": phash, "story_dir": sdir}))
 PY
 }
 
@@ -5296,7 +5739,7 @@ cmd_log_append() {
     local repo_root; repo_root=$(get_repo_root)
     local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "log-append: no feature set and no --feature-dir" >&2; return 1; }
     AW_FD="$fd" AW_LOG="$log" AW_ENTRIES="$entries_file" AW_STATUS="$status" python3 - <<'PY'
-import json, os, re, sys, datetime
+import json, os, re, sys, time, errno, datetime
 fd = os.environ["AW_FD"]; log = os.environ["AW_LOG"]
 ef = os.environ["AW_ENTRIES"]; status = (os.environ.get("AW_STATUS") or "").strip()
 fname, prefix, default_status, title = {
@@ -5359,6 +5802,46 @@ SCAFFOLD = {
 
 # Architecture Decision Log
 """}
+# THE ID ASSIGNMENT AND THE WRITE ARE ONE OPERATION. `nxt = max(existing) + 1` is computed
+# from a whole-file read and the file is then written back truncating — so two runs that
+# read before either wrote both compute the same next id, and the second write drops the
+# first's entry entirely. The wave model exists to have same-wave stories designed in
+# parallel, and this is the artefact §0.3 calls the cross-lane contract anchor, so the race
+# is not hypothetical: two story-plan runs, or plan and story-plan, is the ordinary case.
+# Git catches a lost entry across branches and never within one working tree.
+#
+# The lock is named for the FILE, so every writer of interfaces.md contends on one lock
+# whichever op or shell it came from — aw-xref.py names its own the same way for the same
+# reason. A lock older than the timeout belonged to a run that died holding it; breaking it
+# is right, because the alternative is a wedged feature nobody can append to again.
+LOCK_TIMEOUT = 30.0
+def take_lock(target):
+    lp = target + ".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)
+            return lp
+        except OSError as e:
+            if e.errno != errno.EEXIST: raise
+            try: age = time.time() - os.path.getmtime(lp)
+            except OSError: age = 0.0
+            if age > LOCK_TIMEOUT:
+                try: os.unlink(lp)
+                except OSError: pass
+                continue
+            if time.time() - start > LOCK_TIMEOUT:
+                bail("log-append: %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(target), int(LOCK_TIMEOUT), lp))
+            time.sleep(0.05)
+
+def drop_lock(lp):
+    try: os.unlink(lp)
+    except OSError: pass
+
+lock = take_lock(path)
 created = not os.path.isfile(path)
 if created:
     open(path, "w", encoding="utf-8").write(SCAFFOLD[log])
@@ -5395,6 +5878,7 @@ for b in blocks:
 
 text = text.rstrip("\n") + "\n\n" + "\n\n".join(out_blocks) + "\n"
 open(path, "w", encoding="utf-8").write(text)
+drop_lock(lock)
 os.remove(ef)
 print(json.dumps({"ok": True, "log": path, "appended": len(assigned),
                   "ids_csv": ", ".join(assigned),
@@ -5444,6 +5928,7 @@ case "$sub" in
     plan-check)       cmd_plan_check "$@" ;;
     plan-stamp)       cmd_plan_stamp "$@" ;;
     gate-result)      cmd_gate_result "$@" ;;
+    gate-read)        cmd_gate_read "$@" ;;
     build-compile)    cmd_build_compile "$@" ;;
     test-run)         cmd_test_run "$@" ;;
     test-diff)        cmd_test_diff "$@" ;;