super-ux 0.43.0 → 0.45.0

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # Changelog
 
+## 0.45.0 — 2026-08-19
+
+**The requirement layer could not see a requirement with no observable.** The contract said
+one was unfinished without it; nothing read for one. `ux_lint.py` never opened a scenario or
+user-story body — no rule looked for `Expected result`, `Acceptance criteria` or a success
+metric — while the layer *below* it, screens, had carried that check since U055/U056.
+
+The dogfood is the argument: this pack's own 15 scenarios all read `Status: implemented`,
+**none cited any code**, no test touched `bin/super-ux.js`, and `npm test` exited 0 over all
+of it. A chain that demands the layers before code could not tell that its own chain closed
+on nothing.
+
+### U060–U065 — the requirement layer gets read
+
+A scenario or story with no observable is refused; a scenario claiming `implemented` must
+cite code that resolves. `U055/U056` and `U064/U065` now share one owner (`coverage_claim`),
+so two layers cannot answer the same question differently. All 15 own scenarios now cite
+implementing ranges in `bin/super-ux.js`, each read rather than recalled.
+
+### `Product:` — a shipped scenario stops counting as a validated one
+
+`unobserved | observed | contradicted`, distinct from `Status`, with **no floor and no
+target**: absence means `unobserved`, and neither `unobserved` nor `contradicted` fails
+anything. Outcome evidence often cannot exist yet, and saying so is not a defect.
+
+Four things stop an audit promoting it: `U068` refuses everything an audit produces as an
+outcome signal — a `file:line`, a PASS/FAIL verdict, a path into `docs/ux/audits/`; `U067`
+refuses `observed` with no signal; `U066` refuses an out-of-enum value outright, because an
+unrecognised value read as *no state* is how an enum drifts; and both homes of the
+after-a-run step carry **The audit never writes `Product:`**, with a gate that fails if
+either loses the sentence.
+
+**All 15 own scenarios now read `unobserved`.** Before this they read as fifteen validated
+bets, because `implemented` was the only state the chain had.
+
+### Found while there
+
+The screens status enum had **already** drifted: the contract declared five values and the
+linter matched four, so a `blocked` screen read as having *no* status and `U021` silently
+stopped applying. Fixed. Two further instances of the same class filed rather than hidden.
+
+The long spelling (`**Expected result:**`) is canonical; the short forms are still read, and
+`U069` warns rather than errors — failing a live project over a synonym is the false positive
+that gets a whole family switched off.
+
+## 0.44.0 — 2026-08-17
+
+**Three lint codes for the two layers whose claims nothing could check.** `U055`, `U056` and
+`U057`; the linter goes 43 → **54** fixtures, each code carrying the defect it must catch and
+the shapes it must **not**.
+
+### A `Coverage` claim is a claim about code (`U055`, `U056`) — closes #6
+
+Measured in a real project: five screens carried `partial` in the index while their entries
+named no file, and one said `none — no per-account memberships route exists` about a route a
+task had built the day before. **Two fields of one record contradicted each other for a day,
+and neither was checked against the other.**
+
+- `U055` (warn) — a `Coverage` value other than `none` that names no file. A claim about code
+  citing no code cannot be checked by a script *or* by a reader, who has nowhere to go to
+  disagree.
+- `U056` (error) — a cited path that does not exist. A stale citation is the same defect with
+  the means to notice.
+
+**The path pattern is deliberately narrow and that was the design decision, not a detail.** It
+requires a slash **and** an extension, so `src/routes/x.tsx:12` matches while *"partial —
+client/server split"* and *"the route is built"* do not. A wider pattern was tried first and
+flagged three correct prose entries — the false positive that gets a rule switched off inside a
+day, taking the real check with it.
+
+### A flow's verdict must be measurable, not inherited (`U057`) — closes #7
+
+The chain is foundation → flows → screens → scenarios, and audits in practice attach to the two
+**ends**. Flows sit between and are the only layer with no artefact of their own: a flow is a
+path across screens, so the cheap thing is to derive its verdict from theirs — and a derived
+verdict presented as a measured one is how one project's `flows.md` carried **no code verdict
+for 42 flows across three weeks**, its header delegating to an audit that had itself derived
+them, and a later scenario walk refuting that audit on every clause without touching flows.
+
+`U057` does not verdict a flow. It reports the flows for which **no verdict can be measured at
+all** — the state that was invisible. A flow naming no screen stays `U010`'s subject, not this
+one.
+
+Run against this repository's own chain: clean.
+
 ## 0.43.0 — 2026-08-17
 
 **`ux-flows` has told agents to sweep real products before inventing a flow since 0.35.0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-ux",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "scripts": {
     "test": "python3 test/validate.py && python3 test/brand_lint_test.py && python3 test/ux_lint_test.py && python3 docs/ux/lint.py && python3 docs/brand/lint.py"
   },

package/plugins/super-ux/scripts/ux_lint.py

@@ -102,11 +102,320 @@ def entry_blocks(text: str, prefix: str) -> dict[str, str]:
     return out
 
 
+# A cited path, deliberately narrow: it must carry a slash AND an extension, so
+# `src/routes/x.tsx:12` matches and prose like "partial — client/server split"
+# or "the route is built" does not. Widening this to any slash-bearing token was
+# tried and flagged three correct prose entries, which is the false positive that
+# gets a rule switched off.
+CITED_PATH = re.compile(r"\b([\w.-]+(?:/[\w.-]+)+\.[A-Za-z][\w]{0,4}(?::\d+)?)")
+
+
 def screen_blocks(text: str) -> dict[str, str]:
     """Map SCR-id -> its section body."""
     return entry_blocks(text, "SCR")
 
 
+def coverage_claim(cov: str, root: Path) -> tuple[bool, list[str]]:
+    """A `Coverage:` value read as the claim about code that it is.
+
+    Returns `(names_no_file, cited_paths_that_do_not_exist)`. One owner for two
+    layers: `screens.md` and the requirement layer above it ask the same two
+    questions of the same field, and an answer that differed between them would
+    be a second contract wearing one field's name.
+    """
+    cited = CITED_PATH.findall(cov)
+    missing = [rel for rel in cited if not (root / rel.split(":", 1)[0]).exists()]
+    return (not cited, missing)
+
+
+# --- The observable a requirement is unfinished without --------------------
+#
+# `Expected result` on a scenario and `Acceptance criteria` on a story are the
+# contract's names for the same thing: the thing a reader can watch happen and
+# disagree about. Until this block existed, no rule in this file opened a
+# scenario or a story body at all -- the contract asked for an observable and
+# nothing read for one, so a scenario could reach `implemented` having never
+# said what would be true if it worked.
+#
+# Field spelling is read tolerantly on purpose. `Expected:` and `Acceptance:`
+# are the short forms in live use (this pack's own chain writes both), and the
+# question these codes ask is whether an observable EXISTS. A rule that failed a
+# scenario for spelling its field the short way would be a different rule
+# wearing this one's number, and it would be the false positive that gets the
+# whole family switched off.
+SCENARIO_OBSERVABLE = re.compile(r"\*\*Expected(?:\s+result)?:\*\*[ \t]*(.*)")
+STORY_OBSERVABLE = re.compile(r"\*\*Acceptance(?:\s+criteria)?:\*\*[ \t]*(.*)")
+FIELD_START = re.compile(r"^\s*(?:[-*]\s+)?\*\*[^*]+:\*\*")
+PLACEHOLDER = re.compile(r"^(?:[-—–]+|<[^>]*>|tbd|todo|n/?a|\?+)$", re.IGNORECASE)
+
+# A scenario or story that declares itself unfinished is not a finding: it has
+# already said what these codes would say. `retired` and `dropped` are gone, and
+# `draft`/`proposed` are the states in which the observable is still being
+# written. Every other value -- including an unstated one -- is a claim to be
+# finished, and that claim is what gets checked.
+SCENARIO_UNFINISHED = ("draft", "retired")
+STORY_UNFINISHED = ("proposed", "dropped")
+
+
+def field_body(body: str, pattern: re.Pattern) -> str | None:
+    """A `**Field:**` value: the rest of its line plus the lines beneath it.
+
+    `None` when the field is absent, `""` when it carries nothing. Reading the
+    lines beneath is what makes `Acceptance criteria` legible at all -- the
+    contract puts its Given/When/Then bullets under the label, not after it.
+    """
+    m = pattern.search(body)
+    if m is None:
+        return None
+    out = [m.group(1).strip()]
+    for line in body[m.end():].splitlines():
+        if not line.strip():
+            continue
+        if FIELD_START.match(line) or line.lstrip().startswith("#"):
+            break
+        out.append(line.strip())
+    return "\n".join(part for part in out if part).strip()
+
+
+def stated(value: str | None) -> bool:
+    """Does this field say anything? A placeholder is not an answer."""
+    if value is None:
+        return False
+    for line in value.splitlines():
+        line = line.strip().lstrip("-*").strip()
+        if line and not PLACEHOLDER.match(line):
+            return True
+    return False
+
+
+def declared_status(body: str) -> str | None:
+    m = re.search(r"\*\*Status:\*\*\s*([A-Za-z-]+)", body)
+    return m.group(1).lower() if m else None
+
+
+def check_observables(scenarios: str, foundation: str, root: Path) -> None:
+    """A requirement with no observable is unfinished, and says so or is told.
+
+    The reason this is a gate and not advice: an observable added after the
+    implementation is read is not a test of the requirement, it is a
+    description of the code. By then the only honest thing left to measure is
+    whether the code does what the code does. So the observable is required at
+    the layer that DEFINES the requirement, where it is still cheap, and the
+    citation that connects it to code is required the moment the requirement
+    claims to be implemented.
+    """
+    for sid, body in sorted(entry_blocks(scenarios, "SCN").items()):
+        status = declared_status(body)
+        if status in SCENARIO_UNFINISHED:
+            continue
+        if not stated(field_body(body, SCENARIO_OBSERVABLE)):
+            err(f"[U060] scenarios.md: {sid} states no observable result — add "
+                f"**Expected result:**. A requirement with no observable cannot be "
+                f"connected to evidence later without inventing the test after "
+                f"reading the implementation")
+        cov_m = re.search(r"\*\*Coverage:\*\*\s*(.+)", body)
+        cov = cov_m.group(1).strip() if cov_m else ""
+        if status == "implemented" and (not cov or cov.lower().startswith("none")):
+            warn(f"[U063] scenarios.md: {sid} is 'implemented' and names no code — "
+                 f"the status claims an audit passed and nothing says against what")
+        if cov and not cov.lower().startswith("none"):
+            unfalsifiable, missing = coverage_claim(cov, root)
+            if unfalsifiable:
+                warn(f"[U064] scenarios.md: {sid} claims Coverage '{cov}' and names no file")
+            for rel in missing:
+                err(f"[U065] scenarios.md: {sid} cites '{rel}', which does not exist")
+
+    for sid, body in sorted(entry_blocks(foundation, "ST").items()):
+        status = declared_status(body)
+        if status in STORY_UNFINISHED:
+            continue
+        # `or ""` so the second question is never asked of None: the linter's
+        # promise is that malformed markdown is reported, not raised, and the
+        # only way to watch the first branch fail is to disable it.
+        criteria = field_body(body, STORY_OBSERVABLE) or ""
+        if not stated(criteria):
+            err(f"[U061] foundation.md: {sid} states no acceptance criteria — a story "
+                f"whose delivery nobody can witness is unfinished, whatever its status")
+        elif not re.search(r"\bthen\b", criteria, re.IGNORECASE):
+            warn(f"[U062] foundation.md: {sid} acceptance criteria name no outcome "
+                 f"(no 'then') — the contract's shape is Given/When/Then, and the "
+                 f"'then' is the only half an audit can check")
+
+
+# --- Delivery proof is not outcome proof -----------------------------------
+#
+# `Status` is the DELIVERY state: does the code do what the scenario said. An
+# audit PASS moves it, and that is the whole of what an audit can know.
+# `Product` is the OUTCOME state: did shipping it change anything for a user.
+# Only a signal from the world moves it.
+#
+# Until this block existed the pack had one state and the word `unobserved`
+# appeared in it nowhere, so a shipped scenario silently counted as a validated
+# one: `implemented` was read as "we were right about this", which is a claim
+# nothing in the chain could support. Manifesto M-21 names the state that was
+# missing rather than the check -- *some outcome evidence cannot exist until
+# after release, so `unobserved` is a legitimate product state; pretending
+# delivery proof is outcome proof is not.*
+#
+# So this field has NO FLOOR AND NO TARGET. Its absence means `unobserved` and
+# is never a finding; a scenario may hold `unobserved` for its whole life and
+# nothing here will fail. `contradicted` is not a failing gate either -- it is
+# the information the field exists to make recordable, and what to do about it is
+# a product decision no linter makes. Two things are refused, and both are
+# claims rather than states: an outcome claim that names no observation (U067),
+# and delivery proof handed in wearing an outcome label (U068). The two artefacts
+# an audit produces are a `file:line` and a verdict, and U068 refuses both AS A
+# SIGNAL -- which is what makes an audit PASS unable to promote this field in
+# code as well as in doctrine.
+PRODUCT_STATES = ("unobserved", "observed", "contradicted")
+# The two layers that carry a hypothesis: a scenario is the unit that ships and
+# a story is the unit that bets. A screen has a delivery state and no bet of its
+# own, so it carries no product state, and this tuple is what
+# `validate_status_enums_match_contract` reads rather than guessing from
+# `STATUS_ENUMS`.
+PRODUCT_LAYERS = ("SCN", "ST")
+PRODUCT_EVIDENCED = ("observed", "contradicted")
+PRODUCT_FIELD = re.compile(r"\*\*Product:\*\*[ \t]*(.*)")
+# What an audit hands back, in the two forms the contract gives it. The verdict
+# tokens are upper case and nothing else in these documents is, so they are safe
+# to key on: `PASS` is a verdict, `passed` is prose, and that sentence is the
+# negative fixture. The second is the audit report's own home, which the contract
+# fixes at `docs/ux/audits/` — a path into it is the audit speaking, whatever
+# prose is wrapped around it, and prose around a citation is how the first form
+# would otherwise be smuggled past. Kept as a tuple so deleting one pattern turns
+# exactly one fixture red.
+AUDIT_EVIDENCE = (
+    re.compile(r"\b(?:PASS|FAIL|PARTIAL)\b"),
+    re.compile(r"\bdocs/ux/audits/[\w.-]+"),
+)
+
+# A code citation as this layer actually writes one, RANGES INCLUDED. `CITED_PATH`
+# stops at the first line number on purpose -- it resolves a path, and the range
+# is B-004's open work -- so subtracting only what it matches left `-296` behind
+# and read it as prose. The plant caught that: `observed — bin/super-ux.js:235-296`
+# went clean on the first attempt, and the range form is exactly what this pack's
+# own chain writes. Used for the residue test below and nothing else.
+CITED_SPAN = re.compile(
+    r"`?\b[\w.-]+(?:/[\w.-]+)+\.[A-Za-z][\w]{0,4}(?::\d+(?:-\d+)?)?`?"
+)
+
+# Every enum this file matches on, in one table, because the drift it closes was
+# exactly a table kept twice. `scenario-format.md` has declared `blocked` for a
+# screen since the value was introduced -- with a paragraph of rules of its own
+# -- and the matcher here listed four of the five values, so a `blocked` screen
+# produced `status = None` and `U021` quietly stopped applying to it. An
+# out-of-enum value must be an error, because the alternative is that it means
+# nothing and nothing says so. `validate_status_enums_match_contract` compares
+# this table against the contract's declaration and fails when either side moves
+# alone.
+STATUS_ENUMS = {
+    "SCN": ("draft", "validated", "implemented", "retired"),
+    "ST": ("proposed", "validated", "delivered", "dropped"),
+    "SCR": ("designed", "blocked", "built", "drifted", "retired"),
+}
+
+# The canonical spelling of a field, and the short form in live use beside it.
+# `U060`/`U061` read both on purpose -- their question is whether an observable
+# EXISTS -- which left the vocabulary itself ungated: a project could spell a
+# required field any way it liked and no code said so. The long spelling is
+# canonical because it is what the contract declares and what both shipped
+# templates seed, so a fresh install already writes it and the migration cost
+# falls on nobody who followed the template. A warning, not an error: the
+# observable is present and unambiguous, and failing a project over a synonym is
+# the false positive that gets a whole family switched off.
+FIELD_ALIASES = (
+    ("SCN", "scenarios.md", "**Expected:**", "**Expected result:**"),
+    ("ST", "foundation.md", "**Acceptance:**", "**Acceptance criteria:**"),
+)
+
+
+def product_state(body: str) -> tuple[str | None, str]:
+    """The `Product:` value read as `(state, signal)`.
+
+    `(None, "")` when the field is absent, and absence is not a finding: it
+    means `unobserved`, the honest default. A field that is PRESENT and says
+    nothing is a different thing and is reported -- the same distinction
+    `field_body` draws between `None` and `""`.
+    """
+    m = PRODUCT_FIELD.search(body)
+    if m is None:
+        return (None, "")
+    m2 = re.match(r"\s*([A-Za-z][\w-]*)\s*[—–:-]?\s*(.*)$", m.group(1).strip(),
+                  re.DOTALL)
+    if m2 is None:
+        return ("", "")
+    return (m2.group(1).lower(), m2.group(2).strip())
+
+
+def check_product_state(scenarios: str, foundation: str) -> None:
+    """The outcome state, which nothing an audit can produce is allowed to move."""
+    layers = {"SCN": (scenarios, "scenarios.md"), "ST": (foundation, "foundation.md")}
+    for prefix in PRODUCT_LAYERS:
+        text, name = layers[prefix]
+        for sid, body in sorted(entry_blocks(text, prefix).items()):
+            state, signal = product_state(body)
+            if state is None:
+                continue  # absent == `unobserved`; no floor asks for the field
+            if state not in PRODUCT_STATES:
+                err(f"[U066] {name}: {sid} declares Product "
+                    f"'{state or '(nothing)'}', which is not one of "
+                    f"{' | '.join(PRODUCT_STATES)} — an unrecognised value reads "
+                    f"as no product state at all, which is how a shipped scenario "
+                    f"silently counts as a validated one")
+                continue
+            if state not in PRODUCT_EVIDENCED:
+                continue
+            # Three disjoint guards rather than an elif chain: each fixture must
+            # be able to fire ONE of them, so that disabling one turns exactly
+            # its own case red (standing instruction #5).
+            if not stated(signal):
+                err(f"[U067] {name}: {sid} claims Product '{state}' and names no "
+                    f"signal — an outcome state is a claim about the world, and it "
+                    f"has to say which observation supports it")
+            # Punctuation is dropped before the residue is judged: `stated()`
+            # reads a lone comma as content, so two citations separated by one
+            # went clean until the plant said otherwise.
+            residue = re.sub(r"[^\w]+", " ", CITED_SPAN.sub(" ", signal))
+            if stated(signal) and not stated(residue):
+                err(f"[U068] {name}: {sid} offers '{signal}' as an outcome signal, "
+                    f"and that is a code citation — delivery proof, which "
+                    f"`Status` and `Coverage` already carry. Pretending delivery "
+                    f"proof is outcome proof is the one thing this field exists "
+                    f"to prevent")
+            if stated(signal) and any(p.search(signal) for p in AUDIT_EVIDENCE):
+                err(f"[U068] {name}: {sid} offers an audit's own output as an "
+                    f"outcome signal — an audit reads code and cannot know whether "
+                    f"shipping this changed anything for a user")
+
+
+def check_field_vocabulary(scenarios: str, foundation: str) -> None:
+    """A required field is spelled the way the contract names it."""
+    layers = {"SCN": scenarios, "ST": foundation}
+    for prefix, name, alias, canonical in FIELD_ALIASES:
+        for sid, body in sorted(entry_blocks(layers[prefix], prefix).items()):
+            if alias in body:
+                warn(f"[U069] {name}: {sid} spells the field '{alias}'; the "
+                     f"contract's name is '{canonical}'. The observable is read "
+                     f"either way — this is the vocabulary, so a required field "
+                     f"cannot be spelled any way a project likes with nothing "
+                     f"saying so")
+
+
+def check_status_enums(scenarios: str, foundation: str, screens: str) -> None:
+    """A status outside its layer's enum is refused, not read as no status."""
+    for text, prefix, name in ((scenarios, "SCN", "scenarios.md"),
+                               (foundation, "ST", "foundation.md"),
+                               (screens, "SCR", "screens.md")):
+        allowed = STATUS_ENUMS[prefix]
+        for sid, body in sorted(entry_blocks(text, prefix).items()):
+            status = declared_status(body)
+            if status is None or status in allowed:
+                continue
+            err(f"[U070] {name}: {sid} declares Status '{status}', which is not "
+                f"one of {' | '.join(allowed)} — an unrecognised status reads as "
+                f"no status, and every rule keyed on one silently stops applying")
+
+
 WEB_SURFACE_FIELDS = ("Route", "Answers", "Indexable", "Without JS", "Entity")
 
 
@@ -253,6 +562,10 @@ def main() -> int:
     screens = read(ux / "screens.md")
     scenarios = read(ux / "scenarios.md")
 
+    # Cited paths are project-relative, so they resolve against the tree the
+    # ux directory sits in — the same derivation `check_links` already uses.
+    project_root = ux.parent.parent if ux.name == "ux" else ux.parent
+
     has_flows = bool(ids(flows, "FLW"))
     has_screens = bool(ids(screens, "SCR"))
     has_stories = bool(ids(foundation, "ST"))
@@ -289,6 +602,33 @@ def main() -> int:
         for orphan in sorted(screen_ids - used):
             warn(f"[U011] screens.md: {orphan} is used by no flow (orphan)")
 
+        # --- A flow's verdict must be measurable, not inherited -------------
+        #
+        # The layer order is foundation → flows → screens → scenarios, and audits
+        # in practice attach to the two ENDS. Flows sit between and are the only
+        # layer with no artefact of their own to measure: a flow is a path across
+        # screens, so the cheap thing is to derive its verdict from theirs — and a
+        # derived verdict presented as a measured one is what let one project's
+        # `flows.md` carry no code verdict for 42 flows across three weeks, its
+        # header delegating to an audit that had itself derived them.
+        #
+        # This does not verdict a flow. It reports the flows for which no verdict
+        # can be measured at all, which is the state that was invisible.
+        for fid, fbody in sorted(entry_blocks(flows, "FLW").items()):
+            mine = [b for b in screen_blocks(screens).values()
+                    if re.search(r"\*\*Used by:\*\*[^\n]*\b" + re.escape(fid) + r"\b", b)]
+            if not mine:
+                continue  # a flow naming no screen is U010's subject, not this one
+            cited_anywhere = False
+            for b in mine:
+                m = re.search(r"\*\*Coverage:\*\*\s*(.+)", b)
+                if m and CITED_PATH.search(m.group(1)):
+                    cited_anywhere = True
+                    break
+            if not cited_anywhere:
+                warn(f"[U057] flows.md: {fid} has no screen naming an implementing "
+                     f"file, so its coverage cannot be measured — only inherited")
+
     # --- Scenario traces resolve ---
     if ids(scenarios, "SCN"):
         story_ids = set(ids(foundation, "ST"))
@@ -317,9 +657,13 @@ def main() -> int:
     # --- Screen-level: Figma frames, coverage, drift status ---
     if has_screens:
         fig = figma_enabled(foundation)
+        screens_root = project_root
         for sid, body in screen_blocks(screens).items():
-            status_m = re.search(r"\*\*Status:\*\*\s*(designed|built|drifted|retired)", body)
-            status = status_m.group(1) if status_m else None
+            # Read by value, not matched against a copy of the enum: the copy
+            # was one value short of the contract for as long as `blocked`
+            # existed, and an unmatched status silently became no status.
+            # `check_status_enums` owns the enum for all three layers now.
+            status = declared_status(body)
             if status == "retired":
                 continue
             # every state row present in the States table
@@ -335,7 +679,26 @@ def main() -> int:
             cov = cov_m.group(1).strip() if cov_m else ""
             if status == "built" and (not cov or cov.lower().startswith("none")):
                 warn(f"[U021] screens.md: {sid} is 'built' but has no Coverage")
-
+            # A Coverage value other than `none` is a CLAIM ABOUT CODE, and a claim
+            # about code that names no code is unfalsifiable — not by a script and
+            # not by a reader, who has nowhere to go to disagree. Measured in a real
+            # project: five screens carried `partial` in the index while their
+            # entries named no file, and one of them said `none — no route exists`
+            # about a route a task had built the day before. Two fields of one
+            # record contradicting each other, neither checked against the other.
+            if cov and not cov.lower().startswith("none"):
+                # The line suffix is part of a citation, not of the path --
+                # `coverage_claim` owns that, for this layer and the one above.
+                unfalsifiable, missing = coverage_claim(cov, screens_root)
+                if unfalsifiable:
+                    warn(f"[U055] screens.md: {sid} claims Coverage '{cov}' and names no file")
+                for rel in missing:
+                    err(f"[U056] screens.md: {sid} cites '{rel}', which does not exist")
+
+    check_observables(scenarios, foundation, project_root)
+    check_product_state(scenarios, foundation)
+    check_field_vocabulary(scenarios, foundation)
+    check_status_enums(scenarios, foundation, screens)
     check_vision(ux, vision)
     check_web_surface(screens, flows)
     check_links(ux)

package/templates/foundation.md

@@ -67,4 +67,5 @@ this section just records the on/off choice and the file location.
 - **Priority:** must | should | could
 - **Kill criteria:** <metric below threshold by date -> drop | iterate, or omit>
 - **Status:** proposed
+- **Product:** unobserved
 -->

package/templates/scenarios.md

@@ -35,4 +35,5 @@ action per step paired with the observable system response:
 - **Telemetry:** <`object_action` event + params, or omit if none>
 - **Status:** draft
 - **Coverage:** none yet
+- **Product:** unobserved
 -->