aw-spec-cli 0.1.15 → 0.1.16

package/assets/.appweaver/scripts/powershell/aw-spec-actions.ps1

@@ -1053,9 +1053,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
@@ -1255,6 +1265,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.
@@ -1277,6 +1341,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,
@@ -1299,6 +1364,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),
 }))
 '@
 
@@ -1333,9 +1404,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):
@@ -1343,14 +1429,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(),
@@ -1358,17 +1448,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]
@@ -1386,9 +1484,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)"
 
@@ -1397,6 +1496,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),
@@ -1480,6 +1581,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
@@ -1523,7 +1636,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
@@ -1595,6 +1709,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)
 
@@ -1674,8 +1790,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,
@@ -2337,6 +2470,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:
@@ -2370,8 +2544,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()
@@ -2386,6 +2561,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)
 
@@ -2420,6 +2606,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"):
@@ -2432,8 +2634,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"),
@@ -2444,7 +2664,8 @@ print(json.dumps({"ok": True, "story": story, "path": path,
 function Invoke-StoryStamp {
     param([string[]]$Rest)
     $fdArg = ''; $story = ''; $ids = ''; $version = ''; $follows = ''; $idsGiven = ''; $title = ''
-    $deps = ''; $wave = ''
+    $deps = ''; $wave = ''; $consGiven = ''
+    $designed = ''; $designedGiven = ''; $dropped = ''; $droppedGiven = ''
     for ($i = 0; $i -lt $Rest.Count; $i++) {
         switch ($Rest[$i]) {
             '--feature-dir' { $fdArg = $Rest[++$i] }
@@ -2455,6 +2676,13 @@ function Invoke-StoryStamp {
             '--title'       { $title = $Rest[++$i] }
             '--depends-on'  { $deps = $Rest[++$i] }
             '--wave'        { $wave = $Rest[++$i] }
+            # 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' { $consGiven = '1' }
+            '--designed-lanes' { $designed = $Rest[++$i]; $designedGiven = '1' }
+            '--dropped-lanes'  { $dropped  = $Rest[++$i]; $droppedGiven  = '1' }
         }
     }
     if (-not $story) { Write-Error 'story-stamp: --story is required'; exit 1 }
@@ -2466,7 +2694,11 @@ function Invoke-StoryStamp {
     $env:AW_IDS_GIVEN = $idsGiven; $env:AW_VER = $version
     $env:AW_FOLLOWS = $follows; $env:AW_TITLE = $title
     $env:AW_DEPS = $deps; $env:AW_WAVE = $wave
+    $env:AW_CONSTRAINTS_GIVEN = $consGiven
+    $env:AW_DESIGNED = $designed; $env:AW_DESIGNED_GIVEN = $designedGiven
+    $env:AW_DROPPED = $dropped; $env:AW_DROPPED_GIVEN = $droppedGiven
     $PyStoryStamp | & $py -
+    Remove-Item Env:AW_CONSTRAINTS_GIVEN, Env:AW_DESIGNED, Env:AW_DESIGNED_GIVEN, Env:AW_DROPPED, Env:AW_DROPPED_GIVEN -ErrorAction SilentlyContinue
 }
 
 $PySpecCoverage = @'
@@ -2855,12 +3087,37 @@ function Get-ProjectMarkers {
     return $out
 }
 
+# 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.
+function Get-MarkerEcosystem {
+    param([string]$Marker)
+    switch -Wildcard (Split-Path -Leaf $Marker) {
+        '*.sln'             { return 'dotnet' }
+        '*.csproj'          { return 'dotnet' }
+        'package.json'      { return 'node' }
+        'pom.xml'           { return 'java' }
+        'build.gradle'      { return 'java' }
+        'build.gradle.kts'  { return 'java' }
+        'go.mod'            { return 'go' }
+        'Cargo.toml'        { return 'rust' }
+        'pyproject.toml'    { return 'python' }
+        default             { return '' }
+    }
+}
+
 function Invoke-DetectProject {
     param([string[]]$Rest)
-    $scopeRoot = ''
+    $scopeRoot = ''; $ecosystem = ''
     for ($i = 0; $i -lt $Rest.Count; $i++) {
         switch ($Rest[$i]) {
             { $_ -in '--root','--source-path','-Root' } { $scopeRoot = $Rest[++$i] }
+            # 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.
+            { $_ -in '--ecosystem','-Ecosystem' } { $ecosystem = $Rest[++$i] }
         }
     }
     $repo = Get-RepoRoot
@@ -2877,7 +3134,18 @@ function Invoke-DetectProject {
         $scope = 'repo'
         $markers = @(Get-ProjectMarkers -Repo $repo -Start $repo)
     }
-    Write-Json ([ordered]@{ scaffolded = ($markers.Count -gt 0); markers = @($markers); scope = $scope })
+    $scaffolded = ($markers.Count -gt 0)
+    # 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.
+    $match = $true
+    if ($ecosystem -and $scaffolded) {
+        $match = $false
+        foreach ($m in $markers) {
+            if ((Get-MarkerEcosystem -Marker $m) -eq $ecosystem) { $match = $true; break }
+        }
+    }
+    Write-Json ([ordered]@{ scaffolded = $scaffolded; markers = @($markers); scope = $scope
+                            ecosystem = $ecosystem; ecosystem_match = $match })
 }
 
 
@@ -3894,7 +4162,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
@@ -3914,6 +4183,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))
@@ -3924,8 +4200,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
@@ -4117,6 +4392,77 @@ function Invoke-GateResult {
     Remove-Item Env:AW_GATE, Env:AW_FD, Env:AW_OK, Env:AW_VERSION, Env:AW_STORY, Env:AW_REPORT, Env:AW_OUT, Env:AW_GAPS, Env:AW_REFS, Env:AW_NOTE, Env:AW_FIELDS -ErrorAction SilentlyContinue
 }
 
+# ──────────────────────────────── gate-read ────────────────────────────────
+# THE OTHER HALF OF gate-result. Twin of the bash action; the python payload is
+# byte-identical by contract.
+$PyGateRead = @'
+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))
+'@
+
+function Invoke-GateRead {
+    param([string[]]$Rest)
+    $fdArg = ''; $gate = ''; $report = ''; $file = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) { switch ($Rest[$i]) { { $_ -in '--feature-dir','-FeatureDir' } { $fdArg = $Rest[++$i] } { $_ -in '--gate','-Gate' } { $gate = $Rest[++$i] } { $_ -in '--report','-Report' } { $report = $Rest[++$i] } { $_ -in '--file','-File' } { $file = $Rest[++$i] } } }
+    if (-not $gate) { Write-Error 'gate-read: --gate required'; exit 1 }
+    $py = Get-Py; if (-not $py) { Write-Error 'gate-read: python3 required'; exit 1 }
+    $repo = Get-RepoRoot
+    $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error 'gate-read: no feature set and no --feature-dir'; exit 1 }
+    $env:AW_GATE = $gate; $env:AW_FD = $fd; $env:AW_REPORT = $report; $env:AW_FILE = $file
+    $PyGateRead | & $py -
+    Remove-Item Env:AW_GATE, Env:AW_FD, Env:AW_REPORT, Env:AW_FILE -ErrorAction SilentlyContinue
+}
+
 # ─────────────── story-plan-check / story-plan-doc / log-append ───────────────
 # The per-story execution design ("story design", one document per lane) + the
 # feature's append-only logs. Twins of the bash actions; the python payloads are
@@ -4164,7 +4510,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)",
@@ -4195,11 +4552,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)}
@@ -4237,12 +4601,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"]
@@ -4290,6 +4708,15 @@ 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))
 '@
 
@@ -4298,6 +4725,7 @@ 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)
 
@@ -4358,7 +4786,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)
@@ -4368,11 +4798,11 @@ 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}))
 '@
 
 $PyLogAppend = @'
-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 = {
@@ -4435,6 +4865,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])
@@ -4471,6 +4941,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),
@@ -4494,8 +4965,11 @@ function Invoke-StoryPlanCheck {
 
 function Invoke-StoryPlanDoc {
     param([string[]]$Rest)
-    $fdArg = ''; $story = ''; $passFile = ''; $specVersion = ''; $lane = 'backend'
-    for ($i = 0; $i -lt $Rest.Count; $i++) { switch ($Rest[$i]) { { $_ -in '--feature-dir','-FeatureDir' } { $fdArg = $Rest[++$i] } { $_ -in '--story','-Story' } { $story = $Rest[++$i] } { $_ -in '--lane','-Lane' } { $lane = $Rest[++$i] } { $_ -in '--pass-file','-PassFile' } { $passFile = $Rest[++$i] } { $_ -in '--spec-version','-SpecVersion' } { $specVersion = $Rest[++$i] } } }
+    $fdArg = ''; $story = ''; $passFile = ''; $specVersion = ''; $lane = 'backend'; $planHash = ''
+    # --plan-hash is 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.
+    for ($i = 0; $i -lt $Rest.Count; $i++) { switch ($Rest[$i]) { { $_ -in '--feature-dir','-FeatureDir' } { $fdArg = $Rest[++$i] } { $_ -in '--story','-Story' } { $story = $Rest[++$i] } { $_ -in '--lane','-Lane' } { $lane = $Rest[++$i] } { $_ -in '--pass-file','-PassFile' } { $passFile = $Rest[++$i] } { $_ -in '--spec-version','-SpecVersion' } { $specVersion = $Rest[++$i] } { $_ -in '--plan-hash','-PlanHash' } { $planHash = $Rest[++$i] } } }
     if (-not $story) { Write-Error 'story-plan-doc: --story is required'; exit 1 }
     if (-not $passFile) { Write-Error 'story-plan-doc: --pass-file is required'; exit 1 }
     $py = Get-Py; if (-not $py) { Write-Error 'story-plan-doc: python3 required'; exit 1 }
@@ -4503,8 +4977,9 @@ function Invoke-StoryPlanDoc {
     $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
     if (-not $fd) { Write-Error 'story-plan-doc: no feature set and no --feature-dir'; exit 1 }
     $env:AW_FD = $fd; $env:AW_STORY = $story; $env:AW_LANE = $lane; $env:AW_PASS = $passFile; $env:AW_VER = $specVersion
+    $env:AW_PLAN_HASH = $planHash
     $PyStoryPlanDoc | & $py -
-    Remove-Item Env:AW_FD, Env:AW_STORY, Env:AW_LANE, Env:AW_PASS, Env:AW_VER -ErrorAction SilentlyContinue
+    Remove-Item Env:AW_FD, Env:AW_STORY, Env:AW_LANE, Env:AW_PASS, Env:AW_VER, Env:AW_PLAN_HASH -ErrorAction SilentlyContinue
 }
 
 function Invoke-LogAppend {
@@ -4932,6 +5407,7 @@ switch ($sub) {
     'plan-check'       { Invoke-PlanCheck        -Rest $rest }
     'plan-stamp'       { Invoke-PlanStamp        -Rest $rest }
     'gate-result'      { Invoke-GateResult      -Rest $rest }
+    'gate-read'        { Invoke-GateRead        -Rest $rest }
     'build-compile'    { Invoke-BuildCompile     -Rest $rest }
     'test-run'         { Invoke-TestRun          -Rest $rest }
     'test-diff'        { Invoke-TestDiff        -Rest $rest }