super-ux 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # Changelog
 
+## 0.34.0 — 2026-08-10
+
+B-010 and B-002, and the gate that stops both coming back. The UX linter is
+older and more central than the brand one and had neither codes nor fixtures;
+this release gives it both, and then gates the fixtures so the harness cannot
+fall behind the linter the way the linter fell behind the contract.
+
+### Added
+
+- **Every UX linter rule has a code, `U001`..`U054`.** Twenty-one of them, in
+  the message itself, so a rule can be searched, cited in review and gated on.
+  The full table with severities is in `references/scenario-format.md` — the
+  contract, not the source, is where a rule's meaning lives.
+- **`test/ux_lint_test.py` covers all twenty-one.** 43 checks: every code with
+  its planted defect, and a clean twin wherever silence is the interesting
+  half. Three defects were planted in the linter itself to confirm the harness
+  bites — a duplicate-id check that never fires, a Figma-frame check short-
+  circuited, a coverage check keyed to a status that does not exist — and each
+  turned exactly one case red.
+- **`validate_ux_lint_coverage`** — every emitted code needs a fixture **and** a
+  contract row. It went red on all twenty-one on its first run, which is what a
+  coverage gate is supposed to do the day it is added.
+- **`validate_run_instructions`** — closes B-002 from the other side. The
+  existing gate asked *for each known destination, does a command seed it?*;
+  this one asks *for each path an instruction tells the reader to run, is it a
+  destination anything seeds?* That is the direction a rename breaks: an
+  instruction naming `docs/ux/linter.py` while commands seed `docs/ux/lint.py`
+  passed the old gate and failed the reader.
+
+### Changed
+
+- Linter output now carries the code before the message. Exit codes, severities
+  and behaviour are unchanged; anything keying off exit status is unaffected.
+
+## 0.33.0 — 2026-08-10
+
+The chain designed landing pages and had nowhere to record that a landing is a
+page a machine reads. This release gives that decision a home, teaches the
+router the words users actually bring, and adds the two copy checks that our
+own interface failed.
+
+### Added
+
+- **`Web surface:` — the second reader gets a field.** A screen that is a
+  public URL now carries five, and each is the design-time twin of a check an
+  audit runs on the live page later, so both ends speak one vocabulary:
+  `Route`, `Answers` (the ONE question this page answers — a second question is
+  a second page), `Indexable`, `Without JS`, `Entity`. `screens.md` answers
+  `Web surfaces: yes|no` once per project, because a declared absence is
+  countable and an unanswered question is not. Contract stays **v4**: the block
+  is optional and additive, nothing to migrate.
+  `ux-flows` asks at the moment it already asks about Figma and the style pack;
+  `ux-audit` checks a built screen against the record; **seo-aeo-audit** joins
+  `sheleg-design` and `task-pipeline` as the third companion, on the same
+  recommend-never-force contract. The reason it lives in the chain and not in
+  an audit: once a page is live its URL is in other people's links and its
+  structure is what an answer engine already quoted, so an audit then finds a
+  problem it can no longer fix.
+- **`test/ux_lint_test.py` — the UX linter gets a fixture harness.** The brand
+  linter has carried one per code since 0.30.0; the older and more central
+  linter had none. Fourteen cases, every rule with its planted defect and its
+  clean twin, wired into CI. The backfill for the checks that predate it is
+  **B-010** on the board — named rather than implied.
+- **B007 — a voice names one brand it admires and one it refuses.** The refused
+  half does the work: it is the only one that can be checked against a draft out
+  loud. Silent while the voice is `draft`, because the references are part of
+  calibrating it and a warning on a freshly seeded project is how a linter
+  teaches people to ignore it on day one.
+- **B026 — a label, button, menu item or title takes no full stop.** Scoped by
+  key prefix rather than by guessing at the text: a message may be a sentence
+  and should be. It found `Nothing selected.` in this project's own installer
+  on its first run.
+- **Four routing rows and the composite brief.** `/ux` now answers to
+  *воронка / funnel / pricing / checkout*, *дизайн / how should it look*,
+  *SEO / чтобы находилось*, and *мобильное приложение / which platform* — every
+  one of which had a capability behind it and no words in front of it. And a
+  brief that names three things is now mapped to three routes, ordered by chain
+  position, with the sequence stated before the first one runs.
+
+### Fixed
+
+- `menu.nothing` in `bin/super-ux.js` ended in a full stop, and the registry
+  agreed with it. Both corrected; B026 is what found it.
+- This project's own `screens.md` now answers the web-surface question (`no`,
+  with the reason), and its `voice.md` names its two references.
+
 ## 0.32.0 — 2026-08-10
 
 A structural audit of 0.31.0 found twenty-two defects that 3427 green checks

package/README.md

@@ -129,7 +129,7 @@ Commands: `/brand` (status → one recommended action), `/brand-init`,
 python3 docs/brand/lint.py
 ```
 
-33 deterministic checks (`B001`..`B073`) — banned words, one action under two names, a figure
+35 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 locale that lags without saying so. Exit 0 clean, 1 warnings, 2 errors.

package/bin/super-ux.js

@@ -322,7 +322,7 @@ async function menu() {
 
   if (picked.length === 0) {
     if (prompter) prompter.close();
-    console.log('Nothing selected.');
+    console.log('Nothing selected');
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-ux",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Scenario-driven UI development for AI agents (Claude Code, Cursor, 70+ agents): a versioned design chain in docs/ux/, a scenario-first hard rule, a deterministic drift linter, and evidence-backed UX audits. This package is the installer CLI.",
   "bin": {
     "super-ux": "bin/super-ux.js"

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

@@ -201,6 +201,34 @@ def check_contract(brand_dir: Path) -> list[Finding]:
             "report",
         ))
 
+    # B007 -- a voice defined only by what it is drifts toward the average of
+    # everything. Naming one brand you admire and one you refuse gives the
+    # writer two fixed points, and the refused one does most of the work: it
+    # is the only field that can be checked against a draft out loud.
+    # A `draft` voice has not been calibrated yet and the references are part
+    # of calibrating it, so firing here would put a warning on every freshly
+    # seeded project -- which is how a linter teaches people to ignore it on
+    # day one. The check begins the moment someone claims the voice is done.
+    if voice and status and status != "draft":
+        section = re.search(
+            r"^##\s+Voice references\s*$(.*?)(?=^##\s|\Z)",
+            voice, re.MULTILINE | re.DOTALL,
+        )
+        body = section.group(1) if section else ""
+        admired = re.search(r"\*\*Admired:\*\*\s*(\S.*)", body)
+        refused = re.search(r"\*\*Refused:\*\*\s*(\S.*)", body)
+        missing = [
+            name for name, m in (("Admired", admired), ("Refused", refused))
+            if not m or unfilled(m.group(1))
+        ]
+        if missing:
+            findings.append(Finding(
+                "B007", SEVERITY_WARN, "voice.md", 1,
+                f"`## Voice references` is missing {', '.join(missing)} -- "
+                f"a voice with no brand it refuses to sound like has no edge "
+                f"to be checked against",
+            ))
+
     return findings
 
 
@@ -348,6 +376,12 @@ def _looks_like_copy(literal: str) -> bool:
 DIRECTIVES = {"use strict", "use client", "use server"}
 
 
+LABEL_KEY_RE = re.compile(
+    r"^(button|cta|label|title|heading|header|menu|tab|nav|placeholder"
+    r"|action|link|toggle|chip|badge)\b", re.IGNORECASE
+)
+
+
 def check_consistency(brand_dir: Path, sources: dict) -> list[Finding]:
     """B020-B025 -- the registry, the code and the casing agree."""
     findings: list[Finding] = []
@@ -369,6 +403,24 @@ def check_consistency(brand_dir: Path, sources: dict) -> list[Finding]:
                 f"keeps one name across the whole flow",
             ))
 
+    # B026 -- a label is a name, not a statement, so it ends with nothing.
+    # Scoped by key prefix rather than by guessing at the text: a message may
+    # be a sentence and should be, while a button that ends in a full stop is
+    # the single most common tell that prose leaked into a control.
+    for row in rows:
+        if not LABEL_KEY_RE.match(row["key"]):
+            continue
+        text = row["text"].rstrip()
+        if not text.endswith(".") or text.endswith("..") or text.endswith("…"):
+            continue
+        if ". " in text:      # genuinely several sentences -- a different defect
+            continue
+        findings.append(Finding(
+            "B026", SEVERITY_WARN, "strings.md", 0,
+            f"`{row['key']}` ends in a full stop: \"{text}\". A label, button, "
+            f"menu item or title is a name and takes no terminal punctuation",
+        ))
+
     for row in rows:
         location = row["location"]
         file_part = location.split(":")[0]

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

@@ -73,12 +73,12 @@ def check_unique_and_gaps(entry_ids: list[str], label: str) -> None:
         seen[i] = seen.get(i, 0) + 1
     for i, n in seen.items():
         if n > 1:
-            err(f"{label}: duplicate id {i} ({n} entries)")
+            err(f"[U001] {label}: duplicate id {i} ({n} entries)")
     nums = sorted(int(i.split("-")[1]) for i in seen)
     if nums:
         missing = [n for n in range(1, max(nums) + 1) if n not in nums]
         if missing:
-            warn(f"{label}: id gaps (retired entries should stay): {missing}")
+            warn(f"[U002] {label}: id gaps (retired entries should stay): {missing}")
 
 
 def figma_enabled(foundation: str) -> bool | None:
@@ -89,10 +89,10 @@ def figma_enabled(foundation: str) -> bool | None:
     return m.group(1).lower() == "enabled"
 
 
-def screen_blocks(text: str) -> dict[str, str]:
-    """Map SCR-id -> its section body (from its header to the next ### / ##)."""
+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(r"^###\s+(SCR-\d+):", text, flags=re.MULTILINE)
+    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]
@@ -102,6 +102,77 @@ def screen_blocks(text: str) -> dict[str, str]:
     return out
 
 
+def screen_blocks(text: str) -> dict[str, str]:
+    """Map SCR-id -> its section body."""
+    return entry_blocks(text, "SCR")
+
+
+WEB_SURFACE_FIELDS = ("Route", "Answers", "Indexable", "Without JS", "Entity")
+
+
+def web_surfaces_declared(screens: str) -> bool | None:
+    """True/False from the project-level declaration; None if unstated."""
+    m = re.search(r"\*\*Web surfaces:\*\*\s*(yes|no)\b", screens, re.IGNORECASE)
+    if not m:
+        return None
+    return m.group(1).lower() == "yes"
+
+
+def check_web_surface(screens: str, flows: str) -> None:
+    """A screen a crawler will read is designed as one, or declared not to be.
+
+    The rule this enforces is decided at design time and cannot be recovered
+    by an audit: by the time a landing is live, its URL is in other people's
+    links and its structure is what an answer engine already quoted. So the
+    chain records the five things a later audit checks -- and a project with
+    no public page says so once, because a declared absence is countable and
+    an unanswered question is not.
+    """
+    declared = web_surfaces_declared(screens)
+    blocks = {
+        sid: body for sid, body in screen_blocks(screens).items()
+        if "**Web surface:**" in body
+    }
+
+    if declared is None:
+        warn(
+            "[U050] screens.md: no **Web surfaces:** declaration — answer yes or no once "
+            "(a public page a search or answer engine reads?). An unanswered "
+            "question reads as no, and this one cannot be fixed after launch"
+        )
+    elif declared is False and blocks:
+        for sid in sorted(blocks):
+            err(
+                f"[U051] screens.md: declares no web surfaces but {sid} carries a "
+                f"**Web surface:** block — one of the two is wrong"
+            )
+    elif declared is True and not blocks:
+        warn(
+            "[U052] screens.md: declares web surfaces but no screen carries a "
+            "**Web surface:** block"
+        )
+
+    for sid, body in sorted(blocks.items()):
+        for field in WEB_SURFACE_FIELDS:
+            if f"**{field}:**" not in body:
+                err(f"[U053] screens.md: {sid} web surface block is missing **{field}:**")
+
+    # A declaration of "no" is silence, so it must not be able to hide a flow
+    # that plainly starts on the web. This is the one contradiction the
+    # declaration cannot absorb.
+    if declared is False:
+        for fid, body in sorted(entry_blocks(flows, "FLW").items()):
+            m = re.search(r"\*\*Entry point:\*\*\s*(.+)", body)
+            if not m:
+                continue
+            entry = m.group(1).strip()
+            if re.match(r"https?://|/\S", entry):
+                warn(
+                    f"[U054] flows.md: {fid} starts at a URL ({entry.split()[0]}) while "
+                    f"screens.md declares no web surfaces — one of the two is wrong"
+                )
+
+
 VISION_SECTIONS = [
     "1. Essence",
     "2. Core idea",
@@ -129,7 +200,7 @@ def check_vision(ux: Path, vision: str) -> None:
         return
     for section in VISION_SECTIONS:
         if not re.search(rf"^##\s+{re.escape(section)}\s*$", vision, re.MULTILINE):
-            err(f"vision.md: missing section '## {section}'")
+            err(f"[U030] vision.md: missing section '## {section}'")
     # Emptiness is a defect only once the document claims to be finished.
     # A freshly seeded template is all headings and no content by design, and
     # a linter that fails on its own seed teaches people to skip the linter.
@@ -141,17 +212,17 @@ def check_vision(ux: Path, vision: str) -> None:
             if len(body) == 2:
                 tail = re.split(r"^##\s", body[1], maxsplit=1, flags=re.MULTILINE)[0]
                 if not tail.strip():
-                    err(f"vision.md: approved but '## {section}' is empty — "
+                    err(f"[U031] vision.md: approved but '## {section}' is empty — "
                         f"the section that settles arguments cannot be blank")
 
     root = ux.parent.parent if ux.name == "ux" else ux.parent
     present = [root / n for n in INSTRUCTION_FILES if (root / n).is_file()]
     if not present:
-        warn("vision.md exists but the project has no CLAUDE.md / AGENTS.md / "
+        warn("[U032] vision.md exists but the project has no CLAUDE.md / AGENTS.md / "
              "GEMINI.md — the alignment rule has nowhere to live")
         return
     if not any(VISION_RULE_HEADING in read(p) for p in present):
-        warn(f"vision.md exists but no '{VISION_RULE_HEADING}' block in "
+        warn(f"[U033] vision.md exists but no '{VISION_RULE_HEADING}' block in "
              f"{', '.join(p.name for p in present)} — nothing ever reads the vision "
              f"(run the `vision` skill's step 4)")
 
@@ -165,7 +236,7 @@ def check_links(ux: Path) -> None:
                 continue
             resolved = (md.parent / target.split("#", 1)[0]).resolve()
             if not resolved.exists():
-                warn(f"{md.name}: broken link -> {target}")
+                warn(f"[U040] {md.name}: broken link -> {target}")
 
 
 def main() -> int:
@@ -205,18 +276,18 @@ def main() -> int:
             continue
         idx = index_ids(text, pref)
         for missing in sorted(entries - idx):
-            warn(f"{name}: {missing} has no index row")
+            warn(f"[U003] {name}: {missing} has no index row")
         for ghost in sorted(idx - entries):
-            err(f"{name}: index lists {ghost} but no entry exists")
+            err(f"[U004] {name}: index lists {ghost} but no entry exists")
 
     # --- Flows reference existing screens ---
     if has_flows and has_screens:
         screen_ids = set(ids(screens, "SCR"))
         used = refs(flows, "SCR")
         for miss in sorted(used - screen_ids):
-            err(f"flows.md references {miss} but screens.md has no such screen")
+            err(f"[U010] flows.md references {miss} but screens.md has no such screen")
         for orphan in sorted(screen_ids - used):
-            warn(f"screens.md: {orphan} is used by no flow (orphan)")
+            warn(f"[U011] screens.md: {orphan} is used by no flow (orphan)")
 
     # --- Scenario traces resolve ---
     if ids(scenarios, "SCN"):
@@ -226,10 +297,10 @@ def main() -> int:
         traced_flw = refs(scenarios, "FLW")
         if has_stories:
             for miss in sorted(traced_st - story_ids):
-                warn(f"scenarios.md: traces to {miss} which is not in foundation.md")
+                warn(f"[U012] scenarios.md: traces to {miss} which is not in foundation.md")
         if has_flows:
             for miss in sorted(traced_flw - flow_ids):
-                warn(f"scenarios.md: traces to {miss} which is not in flows.md")
+                warn(f"[U013] scenarios.md: traces to {miss} which is not in flows.md")
 
     # --- must/should stories have a scenario ---
     if has_stories and ids(scenarios, "SCN"):
@@ -241,7 +312,7 @@ def main() -> int:
             tail = re.split(r"^#{2,3}\s", foundation[m.end():], maxsplit=1, flags=re.MULTILINE)[0]
             if re.search(r"\*\*Priority:\*\*\s*(must|should)", tail, re.IGNORECASE):
                 if sid not in traced:
-                    warn(f"foundation.md: {sid} (must/should) has no scenario tracing to it")
+                    warn(f"[U014] foundation.md: {sid} (must/should) has no scenario tracing to it")
 
     # --- Screen-level: Figma frames, coverage, drift status ---
     if has_screens:
@@ -259,13 +330,14 @@ def main() -> int:
                     cells = [c.strip() for c in rest.split("|")]
                     frame = cells[1] if len(cells) >= 2 else ""
                     if not frame or frame in ("-", "—", "<frame deep-link>", "<frame link>"):
-                        err(f"screens.md: {sid} state '{state}' has no Figma frame link")
+                        err(f"[U020] screens.md: {sid} state '{state}' has no Figma frame link")
             cov_m = re.search(r"\*\*Coverage:\*\*\s*(.+)", body)
             cov = cov_m.group(1).strip() if cov_m else ""
             if status == "built" and (not cov or cov.lower().startswith("none")):
-                warn(f"screens.md: {sid} is 'built' but has no Coverage")
+                warn(f"[U021] screens.md: {sid} is 'built' but has no Coverage")
 
     check_vision(ux, vision)
+    check_web_surface(screens, flows)
     check_links(ux)
 
     # --- Report ---

package/templates/brand/voice.md

@@ -56,3 +56,11 @@ Conventions rather than character. Each is decided again in
 Copied from the pack, kept here so the audit can look for it by name.
 
 <the degenerate form this voice collapses into when overdone>
+
+## Voice references
+
+<!-- Two fixed points. The refused one does most of the work: it is the only
+half that can be checked against a draft out loud ("this is the thing we said
+we would never sound like"). Required once Status leaves `draft`. -->
+- **Admired:** <brand or product, and the ONE thing it does that you want>
+- **Refused:** <brand or product, and the ONE thing it does that you refuse>

package/templates/screens.md

@@ -23,6 +23,17 @@ contract) before drawing anything; record its token file below. -->
 - **Component source:** <shared UI components dir, e.g. src/components/>
 - **Assets:** <icons/illustrations location>
 
+## Web surfaces
+
+<!-- Does this product have pages a search engine or an AI answer engine will
+read — a landing, pricing, docs, blog? Answer once, here. "no" silences the
+check; flip it to "yes" the moment a public page is designed, and give every
+public screen the **Web surface:** block shown below. This is decided at design
+time on purpose: once a page is live its URL is in other people's links and its
+structure is what an answer engine already quoted, so an audit afterwards finds
+the problem it can no longer fix. -->
+- **Web surfaces:** no
+
 ## Screens
 
 <!-- One entry per screen (see ux-contract v4 for field rules):
@@ -38,6 +49,12 @@ contract) before drawing anything; record its token file below. -->
   | empty | <trigger> | <frame deep-link> | <prompt to act> |
   | error | <trigger> | <frame deep-link> | <message + recovery> |
   | loading | <trigger> | <frame deep-link> | <skeleton/progress> |
+- **Web surface:** (only when this screen is a public URL; all five required)
+  - **Route:** </pricing — the path, readable and stable>
+  - **Answers:** <the ONE question this page answers; a second question is a second page>
+  - **Indexable:** <yes | no + why | canonical → /other-path>
+  - **Without JS:** <what a reader gets with no JS executed — the answer, or nothing>
+  - **Entity:** <schema.org type + the thing it describes, matched to visible content>
 - **Wireframe:** wireframes/SCR-01.md (optional)
 - **Coverage:** <file:line, or "none yet">
 - **Scenarios:** <SCN-… touching this screen>