super-ux 0.45.0 → 0.46.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 0.46.0 — 2026-08-20
+
+**The check that decides whether a public number is real accepted any substring of the
+others.** `B030` built its corpus as `" ".join(values)` and then asked whether the figure
+was *in* that string with the spaces removed — so the eight facts became the character
+sequence `7158215243770+`, and every substring of it was "sourced". Watched: appending
+*"super-ux is used by 58 teams and ships 1582 checks."* to `README.md` — a declared public
+surface — left `docs/brand/lint.py` printing `brand pack is clean`, exit 0. This is the one
+check the brand hard rule exists to enforce. Values are normalised and compared one at a
+time now, against a set.
+
+Twelve more, each reproduced before it was fixed and each new guard watched failing:
+
+- **`facts.md` had no duplicate-key rule**, and a second `| skills shipped | 99 |` row not
+  only stood beside the first but widened the sourced corpus, making `99` quotable in
+  public copy. `B033`.
+- **"every row names a command that recomputes it" ran nothing.** Two rows named no
+  command, and `repo validator checks` read 3500 against a measured 3539. Each `Source` is
+  executed now; the self-referential row runs the validator as a count-neutral child, and
+  the row that cannot be recomputed here is marked and **disclosed** rather than skipped.
+- **`Coverage:` line ranges were never resolved** — `bin/super-ux.js:99000-99999` in a
+  396-line file passed. `U071`/`U072`, and the fourteen live citations that had drifted are
+  rewritten.
+- **The job layer was invisible to every rule.** `ids()` required `### PREFIX-NN: <name>`
+  and this repo's jobs carry no name, so two identical `JTBD-01` ids passed. Entries are
+  matched by id now (`U073`, `U074`), and the three jobs carry the five fields the contract
+  requires.
+- **Nine `Status:` values sat on layers no enum covered**, and `voice.md` read `approved`
+  where the contract declares `draft|validated` — it worked only because the linter
+  compared `== "draft"`. Enums are declared per layer and parity-checked; the two layers
+  that legitimately have no status say so (`U075`, `B034`).
+- **The Cursor umbrella shipped a three-release-old system**: four workflows named of eight
+  rules shipped, with `vision`, `brand-voice` and `copywriting` at zero mentions. It must
+  name every shipped skill now.
+- **The `AT-` marker set had ids and no gate**: deleting a whole section while leaving its
+  table row kept the validator at `OK (3539 checks)`, exit 0. Covered both directions.
+- **The board reused ids** — `B-011`–`B-013` in two tables with different content — and
+  nothing read the board at all.
+- **The hard rule had four payload homes and `HARD_RULES` paired two** (320/2102 words and
+  chars against 349/2284 and 348/2204). Anchor parity now, derived from the template, with
+  the one legitimate exemption as data.
+- **The front-matter budget measured the wrong thing**: the whole block against 1024
+  instead of `name` ≤ 64 and `description` ≤ 1024 separately. No live violation; both
+  directions planted.
+- **One pack, two opposite exit policies.** `brand_lint.py` returned 1 on warnings-only
+  while `ux_lint.py` returned 0 unless `--strict`, so thirteen of thirty-seven codes turned
+  `npm test` red while printing `0 error(s)`. `--strict` added, warnings non-blocking by
+  default, and the three homes of that rule reworded in the same change.
+- **The literal extractor could not cross a newline**, so `usage()` — the most-read UI
+  surface the pack has — was invisible to the string registry. Sixteen findings came out of
+  it on the first run.
+
+Checks: `validate.py` 3539 → **3667**, `brand_lint_test.py` 77 → **89**, `ux_lint_test.py`
+106 → **133**, with `test/floors.json` raised to the measured per-block delta.
+
+Two findings came out of planting rather than reading: per-line template extraction
+produced six mid-sentence fragments no registry row can hold, and a reworded README line
+tripped the pack's own AI-tell check.
+
+
 ## 0.45.0 — 2026-08-19
 
 **The requirement layer could not see a requirement with no observable.** The contract said

package/README.md

@@ -129,11 +129,11 @@ Commands: `/brand` (status → one recommended action), `/brand-init`,
 python3 docs/brand/lint.py
 ```
 
-37 deterministic checks (`B001`..`B073`): banned words, one action under two names, a figure
+39 deterministic checks (`B001`..`B073`): banned words, one action under two names, a figure
 with no sourced fact, a field over its limit with the locale coefficient
 applied, blocked AI crawlers, keyword stuffing, humor on a billing screen,
 a rhetorical dash, a title that ends in a full stop, a locale that lags
-without saying so. Exit 0 clean, 1 warnings, 2 errors.
+without saying so. Exit 0 clean **or warnings only**, 1 warnings under `--strict`, 2 any error. That is the policy `docs/ux/lint.py` has always had, and one pack cannot hold two opposite meanings for a warning: this linter returned 1 on warnings alone until 2026-08-20, so 13 of its 39 codes turned a build red while printing `0 error(s), 1 warning(s)`.
 
 Clean means *checkable*, not *good*: tone drift, unproven claims and a voice
 that has overshot its own failure mode are judged by `/ux-audit copy`.

package/cursor/rules/brand-voice.mdc

@@ -33,5 +33,5 @@ this layer removes.
 python3 docs/brand/lint.py
 ```
 
-Exit 0 clean, 1 warnings, 2 errors. Clean means checkable, not good — the
+Exit 0 clean **or warnings only**, 1 warnings under `--strict`, 2 any error. That is the policy `docs/ux/lint.py` has always had, and one pack cannot hold two opposite meanings for a warning: this linter returned 1 on warnings alone until 2026-08-20, so 13 of its 39 codes turned a build red while printing `0 error(s), 1 warning(s)`. Clean means checkable, not good — the
 judgement half is `/ux-audit copy`.

package/cursor/rules/copywriting.mdc

@@ -60,6 +60,6 @@ lags the primary says so rather than pretending to be current.
 python3 docs/brand/lint.py
 ```
 
-Exit 0 clean, 1 warnings, 2 errors. Clean means *checkable*, not *good* —
+Exit 0 clean **or warnings only**, 1 warnings under `--strict`, 2 any error. That is the policy `docs/ux/lint.py` has always had, and one pack cannot hold two opposite meanings for a warning: this linter returned 1 on warnings alone until 2026-08-20, so 13 of its 39 codes turned a build red while printing `0 error(s), 1 warning(s)`. Clean means *checkable*, not *good* —
 tone drift, unproven claims and a voice that overshot its declared failure
 mode are judged by `/ux-audit copy`.

package/cursor/rules/super-ux.mdc

@@ -6,36 +6,61 @@ alwaysApply: true
 # UX scenarios — hard rule (super-ux)
 
 - `docs/ux/scenarios.md` is the source of truth for all user-facing behavior;
-  `docs/ux/foundation.md` (personas, JTBD, journeys, user stories) is the WHY
-  layer scenarios trace to.
-- `docs/ux/screens.md` is the UI map: every screen + state with its wireframe
-  and (Figma on) its frame link. A screen that changes in code changes here in
-  the SAME change.
-- Run the linter after any UX change and before calling work done:
-  `python3 docs/ux/lint.py`. It must pass — drift must not merge; wire it
-  into CI/pre-commit.
-- Run `python3 docs/ux/doctor.py` when picking this base up after a while.
-  The linter checks the chain against itself and stays silent when the whole
-  base is written to an old contract; the doctor is what notices. Fix a
-  mixed or stale contract before designing on top of it.
-- Any change that touches user-facing behavior MUST update
-  `docs/ux/scenarios.md` in the same change (add/adjust scenarios, statuses,
-  coverage). New user-facing behavior with no scenario is a blocker, not a
-  warning.
+  `docs/ux/foundation.md` (personas, JTBD, journeys, stories) and
+  `docs/ux/flows.md` (user flows) are the WHY and HOW layers scenarios trace
+  to. Above all three sits `docs/ux/vision.md` — what the product is and
+  refuses to become — when the project has written one.
+- Any change that touches user-facing behavior or interface MUST update, in
+  the same change: `docs/ux/scenarios.md`; affected flows; the affected
+  screens in `docs/ux/screens.md` (the UI map — states, elements, coverage);
+  and, when Figma is enabled, the Figma frame(s) plus their links in
+  `screens.md`. A screen whose code diverges from its record, or a stale
+  Figma link, is drift — the exact thing this system prevents.
+- A `Coverage:` citation is a claim about code and is resolved as one: the
+  path must exist and the line range must be inside the file. Seven of this
+  pack's own citations were pre-shift ranges nothing re-resolved.
 - Any new feature or project STARTS with the chain: which job does it serve,
   which journey stage, which story — then flows and scenarios, validated
-  against the existing base (conflicts, overlaps, gaps), approved. An idea
-  serving no job is challenged, not silently accepted.
-- Do NOT write interface code until the UX workflow is done first: the
+  against the existing base, approved. An idea serving no job is challenged,
+  not silently accepted.
+- **Do NOT write interface code until the UX workflow is done first:** the
   foundation → flows → screens → scenarios chain is designed and approved,
   and — when Figma is enabled (default) — the UI is mocked up in Figma with
   every screen linked to its frame. Building UI before this is the exact
   mistake super-ux exists to prevent.
-- Visual identity is one locked style pack, recorded once in `screens.md` →
-  Design system and used by every frame and every built screen — picked with
-  the **sheleg-design** companion skill (`npx sheleg-design-skill`) when the
-  project has no design system of its own. Recommended, never forced; a
-  palette invented per screen is visual drift.
-- Workflows: `ux-foundation` rule (WHY), `ux-flows` rule (flows + Figma
-  mockups + style pack), `ux-scenarios` rule (scenario base), `ux-audit` rule
-  (evidence-backed audits).
+- Visual identity is ONE locked style pack, recorded in `docs/ux/screens.md`
+  → Design system and obeyed by every Figma frame and every built screen —
+  picked with the **sheleg-design** companion skill when the project has no
+  design system of its own (recommended, not required). Inventing a palette,
+  type pairing, or motion per screen is visual drift.
+- After any UX change and before calling the work done, run the linter
+  `python3 docs/ux/lint.py` — it must pass (errors are drift/broken
+  structure; wire it into CI/pre-commit). Run `python3 docs/ux/doctor.py`
+  when picking this base up after a while: the linter checks the chain
+  against itself and stays silent when the whole base is written to an old
+  contract, and the doctor is what notices.
+- Text a user reads is governed too. `docs/brand/` holds the voice, the
+  terminology, the string registry and `facts.md` — the only source of any
+  public figure — and `python3 docs/brand/lint.py` must pass beside the UX
+  linter. Never quote a number that has no row in `facts.md`.
+
+### Which rule owns which question
+
+Eight rules ship in `.cursor/rules/`, and this one routes to the other seven.
+A rule nobody names is a rule nobody loads.
+
+| Rule | Owns |
+|---|---|
+| `vision` | what the product is and refuses to become — the layer above the chain |
+| `ux-foundation` | the WHY layer: personas, jobs (`JTBD-NN`, each with a success metric), journeys, stories |
+| `ux-flows` | flows, Figma mockups and the locked style pack |
+| `ux-scenarios` | the scenario base and its maintenance |
+| `ux-audit` | evidence-backed audits: `file:line` or it did not happen |
+| `brand-voice` | how the product sounds — voice, terminology, facts, per-surface register |
+| `copywriting` | the text itself: interface strings, landing, pricing, changelog, posts |
+
+The chain runs `vision` → `ux-foundation` → `ux-flows` → `ux-scenarios`, with
+`ux-audit` checking the result against the code. `brand-voice` and
+`copywriting` read the same scenarios and do not wait on each other — but
+where both land on one screen, compare them before shipping: a label the
+layout has no room for is right in each and wrong on the screen.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-ux",
-  "version": "0.45.0",
+  "version": "0.46.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/brand_lint.py

@@ -18,8 +18,16 @@ Read-only by default. `--fix` applies only the changes that cannot be wrong.
     python3 brand_lint.py [path] --fix     # apply the safe subset
     python3 brand_lint.py [path] --brief   # one line, for sweeping projects
     python3 brand_lint.py [path] --json    # machine-readable findings
+    python3 brand_lint.py [path] --strict  # warnings block too
 
-Exit codes: 0 clean, 1 warnings only, 2 any error.
+Exit codes: 0 clean or warnings only, 1 warnings under `--strict`, 2 any error.
+
+One pack, one policy: `ux_lint.py` has always blocked on errors and needed
+`--strict` before a warning could fail a build, and this file returned 1 for
+warnings alone -- so 13 of the 37 codes turned `npm test` red while printing
+`0 error(s), 1 warning(s)`. A gate whose two halves disagree about what a
+warning means gets the noisier half switched off, and the half switched off
+here is the one that guards public figures.
 """
 
 from __future__ import annotations
@@ -34,6 +42,20 @@ from pathlib import Path
 CONTRACT = "brand-contract"
 CONTRACT_VERSION = "v1"
 
+# The one enum this file matches on, kept as a module literal so
+# `validate_status_enums_match_contract` can read it out of the source and
+# compare it against `brand-contract.md`'s declaration -- the mechanism the UX
+# linter has carried since SU-02, applied to the layer that was left out of it.
+#
+# The defect it closes was live in this repository's own pack and worked by
+# accident: `brand-contract.md` declares `draft | validated`, `docs/brand/voice.md`
+# said `Status: approved`, and nothing caught it because every read here asked
+# `== "draft"` or `!= "draft"`. So `approved` behaved like `validated` today and
+# would have read as NOT validated the first time any check tested for the value
+# instead of against `draft`. Same class as the screens enum SU-02 closed: an
+# out-of-enum value that is neither refused nor accepted, and invisible.
+VOICE_STATUSES = ("draft", "validated")
+
 SEVERITY_ERROR = "error"
 SEVERITY_WARN = "warn"
 
@@ -184,6 +206,18 @@ def check_contract(brand_dir: Path) -> list[Finding]:
 
     voice = read(brand_dir / "voice.md") or ""
     status = header_field(voice, "Status")
+    # B034 -- an out-of-enum `Status` is refused rather than read as no status.
+    if status is not None and not unfilled(status) \
+            and status not in VOICE_STATUSES:
+        findings.append(Finding(
+            "B034", SEVERITY_ERROR, "voice.md", 1,
+            f"`Status: {status}` is not one of "
+            f"{' | '.join(VOICE_STATUSES)} -- every read in this file asks "
+            f"whether the status is `draft`, so an unrecognised value behaves "
+            f"like `validated` today and reads as not-validated the moment a "
+            f"check tests for the value instead of against `draft`",
+        ))
+
     strings = read(brand_dir / "strings.md") or ""
     agreed = [r for r in table_rows(strings) if r and r[-1] == "agreed"]
     if status == "draft" and agreed:
@@ -363,6 +397,41 @@ WEAK_LABELS = {
 
 LITERAL_RE = re.compile(r"""(["'`])((?:(?!\1)[^\n]){3,200})\1""")
 
+# A `'` or `"` literal cannot cross a newline in JS or TS, so `[^\n]` above is
+# right for those. A TEMPLATE literal can, and `usage()` in this pack's own
+# installer is twenty lines of exactly one -- the most-read UI surface the pack
+# has, invisible to the registry since B022 existed. `strings.md` recorded it as
+# needing "a per-language extractor"; it needed a second pattern.
+#
+# A multi-line template is split into PARAGRAPHS, not lines and not left whole.
+# Whole is useless: one 1800-character blob is a document, and nobody agrees or
+# retires a document. Per line is worse than it looks -- it was tried first, and
+# it turned wrapped prose into six findings no registry row could sensibly hold
+# ("docs/ux skeleton, the docs/brand pack, and all three linters" is half a
+# sentence). A blank-line-separated block is the unit a reader actually sees: a
+# title, a usage list, an explanation. The 4000-char ceiling guards against an
+# unbalanced backtick swallowing a file; it is not a claim about copy.
+TEMPLATE_RE = re.compile(r"`((?:[^`\\]|\\.){3,4000})`", re.DOTALL)
+
+
+def code_literals(text: str) -> list[str]:
+    """Every string literal in source, one entry per unit a reader would see.
+
+    Comments must already be stripped by the caller -- `_strip_comments` leaves
+    literals untouched, which is what makes both patterns below safe to run.
+    """
+    out: list[str] = [lit for _quote, lit in LITERAL_RE.findall(text)]
+    for block in TEMPLATE_RE.findall(text):
+        if "\n" not in block:
+            continue          # single-line backticks are already in `out`
+        for para in re.split(r"\n\s*\n", block):
+            joined = " ".join(
+                line.strip() for line in para.splitlines() if line.strip()
+            )
+            if len(joined) >= 3:
+                out.append(joined)
+    return out
+
 # A template literal's interpolations split it into pieces, and the pieces are
 # not strings: `${a} : ${b}` yielded a literal " : ". Running this check over
 # super-ux's own installer produced 598 such fragments and buried the four real
@@ -530,7 +599,8 @@ def check_consistency(brand_dir: Path, sources: dict) -> list[Finding]:
 
         body = read(target) or ""
         literals = [
-            lit for _q, lit in LITERAL_RE.findall(body) if _looks_like_copy(lit)
+            lit for lit in code_literals(_strip_comments(body, target.suffix))
+            if _looks_like_copy(lit)
         ]
         if literals:
             # The registry records what a reader sees, so the built page is the
@@ -544,7 +614,19 @@ def check_consistency(brand_dir: Path, sources: dict) -> list[Finding]:
                         f"`{row['key']}` is \"{row['text']}\" in the registry, "
                         f"but that text is not on the rendered page",
                     ))
-            elif row["text"] not in body and row["text"].strip() not in body:
+            # Byte-exact first, and that stays the invariant `strings.md`
+            # documents: escape sequences included, so a row holding `\n---`
+            # is compared as the three characters the source carries.
+            #
+            # The wrap-tolerant form is a FALLBACK, not a loosening, and it
+            # exists because without it a wrapped block is unregisterable by
+            # construction -- B022 would demand a row for `usage()` that B021
+            # would then refuse, which is a check with no passing answer. It
+            # compares the same wording across a newline the reader never sees,
+            # which is exactly what the rendered-page branch above already does.
+            elif row["text"] not in body \
+                    and row["text"].strip() not in body \
+                    and normalise(row["text"]) not in normalise(body):
                 findings.append(Finding(
                     "B021", SEVERITY_ERROR, location, 0,
                     f"`{row['key']}` is \"{row['text']}\" in the registry, "
@@ -737,7 +819,7 @@ def _strip_comments(text: str, suffix: str) -> str:
 def _copy_in_code(text: str, suffix: str = ".ts") -> str:
     """The user-visible strings in a source file, joined as prose."""
     out = []
-    for _quote, literal in LITERAL_RE.findall(_strip_comments(text, suffix)):
+    for literal in code_literals(_strip_comments(text, suffix)):
         candidate = re.sub(r"\s{2,}", " ", INTERPOLATION_RE.sub(" ", literal)).strip()
         # A literal with no space is an import path, an identifier or a one-word
         # label. None of them can carry a rhetorical dash or stuff a keyword, and
@@ -843,11 +925,59 @@ def _today() -> str:
     return datetime.date.today().isoformat()
 
 
+def _fact_figures(value: str) -> set[str]:
+    """Every figure ONE fact's `Value` sources, normalised the way copy is read.
+
+    B030 compares a figure in public copy against this set exactly. Until
+    2026-08-20 it compared against every value joined into a single string and
+    asked `compact not in known.replace(" ", "")` -- so the corpus was one
+    character sequence and every SUBSTRING of it counted as sourced. With this
+    pack's own seven public rows the corpus was `7158215243770+`, which sourced
+    the invented `1582` in "super-ux ... ships 1582 checks": the linter printed
+    `brand pack is clean` and exited 0. An invented public number passing the
+    check whose entire purpose is to refuse one is the worst failure this file
+    can have, because it is indistinguishable from working.
+
+    Three forms are accepted, and each is the same claim written differently:
+    the value with its whitespace removed; the same with a bound marker stripped,
+    so a row of `500+` sources the `500` a sentence writes; and whatever the
+    figure regex reads INSIDE the value, so `$3.10` and a thousands separator are
+    matched in the form copy uses. Nothing else -- a figure not written in the
+    table is not in the table.
+    """
+    compact = re.sub(r"\s+", "", value)
+    figures = {compact, compact.strip("+~><≈").strip()}
+    figures.update(m.replace(" ", "") for m in NUMBER_RE.findall(value))
+    return {f for f in figures if f}
+
+
 def check_facts(brand_dir: Path, sources: dict) -> list[Finding]:
-    """B030-B032 -- every figure traces to a row, every row to a source."""
+    """B030-B033 -- every figure traces to a row, every row to a source."""
     findings: list[Finding] = []
     rows = facts(brand_dir)
-    known = " ".join(r["value"] for r in rows if r["public"].lower() != "no")
+    known: set[str] = set()
+    for row in rows:
+        if row["public"].lower() != "no":
+            known |= _fact_figures(row["value"])
+
+    # B033 -- `Fact` is the key a figure is cited by, and a table with two rows
+    # under one key has no answer to "what is that number". Watched: a second
+    # `| skills shipped | 99 |` row left the pack clean AND put `99` into the
+    # sourced corpus, so the duplicate did not merely go unreported -- it
+    # licensed a wrong figure in public copy. An error, not a warning: the two
+    # rows disagree by construction and no reader can tell which one is meant.
+    by_key: dict[str, int] = {}
+    for row in rows:
+        key = normalise(row["fact"]).lower()
+        by_key[key] = by_key.get(key, 0) + 1
+    for key, count in sorted(by_key.items()):
+        if count > 1:
+            findings.append(Finding(
+                "B033", SEVERITY_ERROR, "facts.md", 0,
+                f"`{key}` has {count} rows -- a fact is cited by its name, and "
+                f"two rows under one name make every figure quoting it "
+                f"ambiguous. Retire one or rename both",
+            ))
 
     for row in rows:
         if unfilled(row["source"]):
@@ -868,7 +998,7 @@ def check_facts(brand_dir: Path, sources: dict) -> list[Finding]:
             compact = number.replace(" ", "")
             if YEAR_RE.match(compact):
                 continue
-            if compact not in known.replace(" ", ""):
+            if compact not in known:
                 findings.append(Finding(
                     "B030", SEVERITY_ERROR, path, 0,
                     f"`{number}` appears in public copy with no row in "
@@ -1539,6 +1669,10 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--fix", action="store_true")
     parser.add_argument("--brief", action="store_true")
     parser.add_argument("--json", action="store_true")
+    parser.add_argument(
+        "--strict", action="store_true",
+        help="let warnings fail the run too (same meaning as ux_lint.py --strict)",
+    )
     args = parser.parse_args(argv)
 
     brand_dir = Path(args.path)
@@ -1555,7 +1689,10 @@ def main(argv: list[str] | None = None) -> int:
 
     if any(f.severity == SEVERITY_ERROR for f in findings):
         return 2
-    return 1 if findings else 0
+    # A warning is advice about a judgement a person still has to make -- an
+    # unregistered string, a fact past review, a label naming no outcome. It
+    # blocks only when the caller asks, which is what `--strict` is for.
+    return 1 if (args.strict and findings) else 0
 
 
 if __name__ == "__main__":

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

@@ -52,9 +52,32 @@ def find_ux_dir(arg: str | None) -> Path | None:
     return None
 
 
+# An entry header, matched by its ID and not by the shape of the rest of it.
+#
+# Requiring the colon is how a whole layer became invisible. This pack's own
+# three jobs are written `### JTBD-01` with no `: <name>`, so `ids()` and
+# `entry_blocks()` matched zero of them and NOT ONE rule in this file applied to
+# the layer -- not id uniqueness, not the gap warning, not a required field.
+# Watched: two identical `### JTBD-01` headers passed the whole gate, exit 0.
+# The contract has asked for `### JTBD-NN: <short job name>` since the layer
+# existed, and asking for it in the MATCHER meant a malformed entry was not
+# refused but erased, which is the same class as an out-of-enum status reading
+# as no status. So the header is matched loosely and its shape is then checked
+# (`U073`) -- an entry nobody can see cannot be told it is malformed.
+def _entry_header_re(prefix: str) -> re.Pattern:
+    return re.compile(rf"^###[ \t]+({prefix}-\d+)\b[ \t]*(:?)[ \t]*([^\n]*)$",
+                      re.MULTILINE)
+
+
 def ids(text: str, prefix: str) -> list[str]:
-    """All '### PREFIX-NN:' entry ids, in order."""
-    return re.findall(rf"^###\s+({prefix}-\d+):", text, re.MULTILINE)
+    """All '### PREFIX-NN' entry ids, in order, named or not."""
+    return [m.group(1) for m in _entry_header_re(prefix).finditer(text)]
+
+
+def entry_names(text: str, prefix: str) -> list[tuple[str, str, str]]:
+    """(id, colon, name) per entry header — what `U073` reads to check the shape."""
+    return [(m.group(1), m.group(2), m.group(3).strip())
+            for m in _entry_header_re(prefix).finditer(text)]
 
 
 def index_ids(text: str, prefix: str) -> set[str]:
@@ -92,13 +115,12 @@ def figma_enabled(foundation: str) -> bool | None:
 def entry_blocks(text: str, prefix: str) -> dict[str, str]:
     """Map PREFIX-id -> its section body (from its header to the next ### / ##)."""
     out: dict[str, str] = {}
-    parts = re.split(rf"^###\s+({prefix}-\d+):", text, flags=re.MULTILINE)
-    # parts = [pre, id1, body1, id2, body2, ...]
-    for i in range(1, len(parts), 2):
-        sid = parts[i]
-        body = parts[i + 1] if i + 1 < len(parts) else ""
+    headers = list(_entry_header_re(prefix).finditer(text))
+    for i, match in enumerate(headers):
+        stop = headers[i + 1].start() if i + 1 < len(headers) else len(text)
+        body = text[match.end():stop]
         body = re.split(r"^##\s", body, maxsplit=1, flags=re.MULTILINE)[0]
-        out[sid] = body
+        out[match.group(1)] = body
     return out
 
 
@@ -107,7 +129,11 @@ def entry_blocks(text: str, prefix: str) -> dict[str, str]:
 # 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+)?)")
+# The line suffix now includes a RANGE, because a range is what this layer
+# writes and stopping at the first number is what let one drift for a release.
+CITED_PATH = re.compile(
+    r"\b([\w.-]+(?:/[\w.-]+)+\.[A-Za-z][\w]{0,4}(?::\d+(?:-\d+)?)?)"
+)
 
 
 def screen_blocks(text: str) -> dict[str, str]:
@@ -115,17 +141,44 @@ def screen_blocks(text: str) -> dict[str, str]:
     return entry_blocks(text, "SCR")
 
 
-def coverage_claim(cov: str, root: Path) -> tuple[bool, list[str]]:
+def coverage_claim(cov: str, root: Path) -> tuple[bool, list[str], 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.
+    Returns `(names_no_file, paths_that_do_not_exist, spans_the_file_does_not
+    have)`. One owner for three layers: `screens.md` and the requirement layer
+    above it ask the same questions of the same field, and an answer that
+    differed between them would be a second contract wearing one field's name.
+
+    The third answer is the one B-004 was open for. Until 2026-08-20 a citation
+    was split on `:` and only its path was resolved, so a LINE NUMBER was
+    decoration: `bin/super-ux.js:99000-99999` passed against a 396-line file,
+    and seven live citations in this pack's own `screens.md` were pre-shift
+    ranges the gate could not see -- `SCR-01` pointed at 223-284 while
+    `selectInteractive` had moved to 235-296, and `scenarios.md` had the same
+    function right. A coverage claim whose numbers nobody resolves is a claim
+    about a file, not about code, and code is what it says it is about.
     """
     cited = CITED_PATH.findall(cov)
-    missing = [rel for rel in cited if not (root / rel.split(":", 1)[0]).exists()]
-    return (not cited, missing)
+    missing, beyond = [], []
+    for rel in cited:
+        path, _, span = rel.partition(":")
+        target = root / path
+        if not target.exists():
+            missing.append(rel)
+            continue
+        if not span:
+            continue
+        try:
+            total = len(target.read_text(encoding="utf-8").splitlines())
+        except (OSError, UnicodeDecodeError):
+            # A binary or unreadable target is not a citation defect. The path
+            # resolved; refusing it here would be a rule about file encodings.
+            continue
+        start, _, end = span.partition("-")
+        first, last = int(start), int(end or start)
+        if first < 1 or last < first or last > total:
+            beyond.append(f"{rel} ({path} has {total} lines)")
+    return (not cited, missing, beyond)
 
 
 # --- The observable a requirement is unfinished without --------------------
@@ -219,11 +272,15 @@ def check_observables(scenarios: str, foundation: str, root: Path) -> 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)
+            unfalsifiable, missing, beyond = 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 rel in beyond:
+                err(f"[U072] scenarios.md: {sid} cites '{rel}' — the file resolves "
+                    f"and those lines do not, so the citation points at code that "
+                    f"is not there")
 
     for sid, body in sorted(entry_blocks(foundation, "ST").items()):
         status = declared_status(body)
@@ -312,8 +369,36 @@ STATUS_ENUMS = {
     "SCN": ("draft", "validated", "implemented", "retired"),
     "ST": ("proposed", "validated", "delivered", "dropped"),
     "SCR": ("designed", "blocked", "built", "drifted", "retired"),
+    # The two foundation layers that carry a state of their own. A persona and a
+    # job are either an assumption or something an observation has confirmed, and
+    # `proposed -> confirmed` is the only claim either layer can make about
+    # itself. Both were carrying `confirmed` in this pack's own foundation with
+    # no enum anywhere covering them: nine `**Status:**` values across three
+    # layers sat outside every table, unrefused and unaccepted.
+    "P": ("proposed", "confirmed", "retired"),
+    "JTBD": ("proposed", "confirmed", "retired"),
+}
+
+# A layer whose state lives on the DOCUMENT rather than on an entry. `vision.md`
+# has declared `draft | approved` since the layer shipped -- inside a fenced
+# example, not in the enum home -- and `check_vision` matched the single word
+# `approved` and nothing said what else was legal.
+DOC_STATUS_ENUMS = {
+    "vision.md": ("draft", "approved"),
 }
 
+# Layers the contract gives NO status, checked so that saying nothing about a
+# state is not the same as accepting any word for it. A flow's delivery state is
+# MEASURED through the screens it traverses -- that is what `U057` exists for --
+# so a declared `Status:` on a flow is the inherited verdict U057 refuses,
+# written into the record. This pack's own four flows each carried one.
+STATUSLESS_LAYERS = (
+    ("FLW", "flows.md", "a flow's coverage is measured through its screens (U057), "
+                        "never declared on the flow"),
+    ("JRN", "foundation.md", "a journey is a map of what happens, and a map has "
+                             "no delivery state of its own"),
+)
+
 # 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
@@ -401,11 +486,14 @@ def check_field_vocabulary(scenarios: str, foundation: str) -> None:
                      f"saying so")
 
 
-def check_status_enums(scenarios: str, foundation: str, screens: str) -> None:
+def check_status_enums(scenarios: str, foundation: str, screens: str,
+                       flows: str = "", vision: 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")):
+                               (screens, "SCR", "screens.md"),
+                               (foundation, "P", "foundation.md"),
+                               (foundation, "JTBD", "foundation.md")):
         allowed = STATUS_ENUMS[prefix]
         for sid, body in sorted(entry_blocks(text, prefix).items()):
             status = declared_status(body)
@@ -415,6 +503,73 @@ def check_status_enums(scenarios: str, foundation: str, screens: str) -> None:
                 f"one of {' | '.join(allowed)} — an unrecognised status reads as "
                 f"no status, and every rule keyed on one silently stops applying")
 
+    # A layer the contract gives no status must not carry one. Silence about a
+    # state is not permission to invent a vocabulary for it: an undeclared value
+    # is outside every table, so no rule can key on it and no reader can be wrong
+    # about it out loud.
+    layers = {"FLW": flows, "JRN": foundation}
+    for prefix, name, why in STATUSLESS_LAYERS:
+        for sid, body in sorted(entry_blocks(layers[prefix], prefix).items()):
+            status = declared_status(body)
+            if status is None:
+                continue
+            err(f"[U075] {name}: {sid} declares Status '{status}' on a layer the "
+                f"contract gives no status — {why}")
+
+    for filename, allowed in sorted(DOC_STATUS_ENUMS.items()):
+        text = vision if filename == "vision.md" else ""
+        if not text.strip():
+            continue
+        status = declared_status(text)
+        if status is None or status in allowed:
+            continue
+        err(f"[U070] {filename}: declares Status '{status}', which is not one of "
+            f"{' | '.join(allowed)} — an unrecognised status reads as no status")
+
+
+# What the contract requires of a job, in the contract's own field names. The
+# `Success metric` is the M-17 observable one layer above a story: without it a
+# job is a sentence about a feeling, and no later evidence can be connected to it
+# without inventing the measure after seeing what shipped. None of this pack's
+# own three jobs carried one, and no rule could have said so -- the layer was
+# invisible (see `_entry_header_re`), which is why two defects hid each other.
+JOB_FIELDS = ("Statement", "Personas", "Type", "Forces", "Success metric")
+
+
+def check_jobs(foundation: str, scenarios: str = "", flows: str = "",
+               screens: str = "") -> None:
+    """The job layer: a named header, and the fields the contract asks for.
+
+    The header check covers EVERY entry layer, not only the one it was written
+    for. The invisibility was never specific to jobs -- any layer whose entries
+    drop the `: <name>` disappears from `ids()` and `entry_blocks()` the same
+    way, and it happened to be the job layer that did.
+    """
+    layers = (("P", "foundation.md", "persona", foundation),
+              ("JTBD", "foundation.md", "job", foundation),
+              ("JRN", "foundation.md", "journey", foundation),
+              ("ST", "foundation.md", "story", foundation),
+              ("SCN", "scenarios.md", "scenario", scenarios),
+              ("FLW", "flows.md", "flow", flows),
+              ("SCR", "screens.md", "screen", screens))
+    for prefix, name, label, text in layers:
+        for sid, colon, title in entry_names(text, prefix):
+            if colon and title:
+                continue
+            err(f"[U073] {name}: `### {sid}` carries no name — the contract's "
+                f"header is `### {sid}: <short {label} name>`, and an entry with "
+                f"no name is how this layer stayed invisible to every rule in "
+                f"this file for three releases")
+
+    for sid, body in sorted(entry_blocks(foundation, "JTBD").items()):
+        if declared_status(body) == "retired":
+            continue
+        for field in JOB_FIELDS:
+            if not re.search(rf"\*\*{re.escape(field)}:\*\*", body):
+                err(f"[U074] foundation.md: {sid} is missing **{field}:** — the "
+                    f"contract asks a job for all of "
+                    f"{', '.join(JOB_FIELDS)}")
+
 
 WEB_SURFACE_FIELDS = ("Route", "Answers", "Indexable", "Without JS", "Entity")
 
@@ -689,16 +844,21 @@ def main() -> int:
             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)
+                unfalsifiable, missing, beyond = 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")
+                for rel in beyond:
+                    err(f"[U071] screens.md: {sid} cites '{rel}' — the file resolves "
+                        f"and those lines do not, so the citation points at code "
+                        f"that is not there")
 
     check_observables(scenarios, foundation, project_root)
     check_product_state(scenarios, foundation)
     check_field_vocabulary(scenarios, foundation)
-    check_status_enums(scenarios, foundation, screens)
+    check_status_enums(scenarios, foundation, screens, flows, vision)
+    check_jobs(foundation, scenarios, flows, screens)
     check_vision(ux, vision)
     check_web_surface(screens, flows)
     check_links(ux)

package/templates/claude-rule.md

@@ -57,5 +57,7 @@
   relationships and find-and-replace picks the wrong one. `B062` and `B063`
   catch what a machine can prove; the rest is in the skill's `ai-tells.md`.
 - Run `python3 docs/brand/lint.py` after any text change and before calling
-  work done. It must exit clean; wire it into CI or pre-commit alongside the
-  UX linter so copy drift cannot merge.
+  work done. It must exit 0 — an error blocks and a warning is advice, which
+  is the same policy the UX linter has; `--strict` makes warnings block too.
+  Wire it into CI or pre-commit alongside the UX linter so copy drift cannot
+  merge.