super-ux 0.40.0 → 0.41.3

package/CHANGELOG.md

@@ -1,5 +1,121 @@
 # Changelog
 
+## 0.41.3 — 2026-08-16
+
+**`facts.md` is a document, not only a facts table.** `facts()` took any
+six-column row anywhere in the file, and a project that keeps a product ledger
+there has one whose columns mean something else entirely:
+`Product | App Store name | id | Released | Sold | Publisher today`. Its **Sold**
+year landed in `Review`, so three completed sales produced "was due for review
+on 2022" warnings, and the ledger's own header row became a fact called
+`Product`. Four phantom rows in a registry of 43.
+
+Scoped by header now — a table qualifies when its first column says `Fact`,
+which is the only thing in a markdown table that declares what its columns
+mean. A `tables()` helper groups rows per table beside the existing
+`table_rows()`, which flattens every table in a file and is right for a caller
+that wants every row.
+
+Found on `sshlg.me` and fixed there first, in that project's copy of the linter,
+where it would have been overwritten by the next sync — a plugin-owned file
+edited in a downstream project serves that project until the day it silently
+does not. Ported up with its fixture, which was watched failing.
+
+## 0.41.2 — 2026-08-16
+
+**A source file is not prose, and the prose rules were reading all of it.** On
+`sshlg.me`, whose `Sources:` block points `marketing` at `src/data/*.ts`, that
+produced 20 rhetorical-dash errors inside `//` comments and 7 keyword-stuffing
+errors on `const`, `string`, `name` and `category`. Twenty-seven standing errors
+that no edit to the copy could clear, sitting in a report meant to be read. The
+failure is the same one 0.40.1 fixed from the other direction: a check nobody
+can act on gets ignored, and then it is not a check.
+
+For a file with a code suffix the body is now its **copy** — the string literals
+`_looks_like_copy` already accepts, which is the definition `B022` sweeps with.
+A comment is addressed to a maintainer and an identifier is not a word.
+
+Three things this had to get right, and the first two were found by getting them
+wrong:
+
+- **Comments are stripped by a scanner, not a regex.** `"https://x"` contains
+  `//`. The first attempt used a pattern and immediately reported a rhetorical
+  dash inside a comment that quoted a phrase — in the very change meant to stop
+  reading comments.
+- **`${...}` is substituted, not dropped.** `CODE_FRAGMENT_RE` rejects any
+  literal carrying an interpolation, so without this every interpolated string
+  would fail `_looks_like_copy`. On the site that would have silently dropped the
+  whole biography. It turns out interpolated copy was **not** covered before
+  either: the fixture for it fails against 0.40.1, so this widens coverage rather
+  than preserving it.
+- **A literal with no space is skipped.** `"@/data/site"` counted as copy would
+  put `data` into the density figures.
+
+Ten fixtures, five end-to-end and five on the scanner directly. Four were watched
+failing before the fix went in; the fifth end-to-end case is the boundary that
+must not move — a rhetorical dash in a rendered string is still an error.
+
+**And the same sentence has a second half: a source file is not a *document*
+either.** `B051` measures keyword density, which is a property of the page a
+reader meets. A project that keeps its copy in `src/data/*.ts` splits one page
+across seven files, so measuring each file separately measures the split. On
+`sshlg.me` that produced six errors — `co-founder` at 2.0% of
+`track-record.ts`, `account` at 1.2% of `site.ts` — while the rendered page
+carried **nothing above 1%** and those two words sat at 0.07% and 0.04%.
+
+Code files are pooled into one document for that check; markdown sources are
+not, because there one file really is one page. A pooled finding names the set
+rather than a file, since no single file is the defect. The fixture that proves
+it has a twin that must keep firing: a word genuinely dense across the whole
+pool is still an error.
+
+Measured on `sshlg.me`: **32 errors to 5**, and the five that remain are one
+class — `B021` on registry rows whose text carries an interpolated count or an
+inline link, which needs a linter that reads `dist/` rather than `src/`. One
+real finding surfaced on the way: a rhetorical dash in live copy that had been
+buried under twenty false ones.
+
+## 0.41.1 — 2026-08-16
+
+**`B024` fined the writer for meeting a threshold this pack sets.** The
+sentence-case check reads any capitalised word inside a sentence as Title Case,
+and a contraction of the first person survived every exemption it had: `I'm` is
+not upper-case, is in no entity table, and starts with a capital. So it fired.
+
+That is not a cosmetic false positive. `formats.md` asks for **4 to 8
+contractions per 1000 words** on a published surface and names their absence as
+"the single loudest reason our prose reads as assembled" — and the first-person
+contractions are the loudest ones available. The check and the threshold were
+pulling in opposite directions, and the only repair available to a writer was to
+delete the contraction the pack had just asked for. Found on `sshlg.me`, where
+three registry rows tripped it on 2026-08-15 and none of them was miscased.
+
+`I'm`, `I'll`, `I've` and `I'd` are now exempt, with either apostrophe. Nothing
+else is: `We're` and `They'd` inside a sentence really are miscased, and the
+capital is grammar only for the first person. Both halves are fixtures, so the
+exemption cannot widen without a test saying so.
+
+## 0.41.0 — 2026-08-16
+
+### Added
+
+- **`ux-audit` checks its batches against each other before the report reads as one
+  answer.** The batches run independently — in a large scope, in parallel subagents that
+  never see one another — and the summary then turns them into a single verdict. That is a
+  convergence, and a convergence trusts its inputs because they arrived.
+
+  Four things to look for: one root cause wearing several finding ids, which splits its own
+  priority across three rows; two batches that contradict on one screen, PASS in one and
+  FAIL in the other; a batch that returned nothing where its scenarios touch a screen
+  another batch flagged, since an empty result and an unrun batch look identical in a
+  summary; and a verdict whose evidence is weaker than its neighbour's, presented at equal
+  weight.
+
+  `Cross-batch: clean` is the answer most audits write, and writing it is the point. The
+  scenario base already had the same mechanism one layer up — `ux-scenarios` step 4,
+  *scenarios that contradict each other* — and this is it applied to the audit's own
+  outputs rather than to its inputs.
+
 ## 0.40.0 — 2026-08-14
 
 A 42-page practitioner guide on building web2app funnels was read against the
@@ -236,7 +352,6 @@ developer landing page (`zernio.com`, 2026-08-12) rather than from a survey.
 - `test/floors.json`: `validate.py` 3160 → 3236 — four entries, their field and
   tag checks, and three routing rows.
 
-
 ## 0.37.0 — 2026-08-12
 
 The last five findings from the R-14 run — the ones that needed a **decision**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-ux",
-  "version": "0.40.0",
+  "version": "0.41.3",
   "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

@@ -351,6 +351,11 @@ def check_terminology(brand_dir: Path) -> list[Finding]:
     return findings
 
 
+# `I'm`, `I'll`, `I've`, `I'd`, with either apostrophe. Nothing else: `We're`
+# and `They'd` mid-sentence really are miscased, and only the first person has a
+# capital that is grammar rather than a choice.
+CONTRACTED_I = re.compile(r"^I['\u2019](m|ll|ve|d)$")
+
 WEAK_LABELS = {
     "ok", "yes", "no", "submit", "done", "go", "click here",
     "learn more", "get started", "continue",
@@ -373,6 +378,71 @@ CODE_FRAGMENT_RE = re.compile(
 )
 
 
+# Where a build puts the page a reader actually gets. Checked in this order and
+# the first one that exists wins; a project with none of them is checked against
+# its source, exactly as before.
+RENDER_DIRS = ("dist", "build", "out", "_site")
+
+_ENTITIES = {"&amp;": "&", "&lt;": "<", "&gt;": ">", "&quot;": '"',
+             "&#39;": "'", "&apos;": "'", "&nbsp;": " ", "&#8217;": "\u2019",
+             "&#8216;": "\u2018", "&#8212;": "\u2014", "&#8211;": "\u2013"}
+
+_rendered_cache: dict = {}
+
+
+def normalise(text: str) -> str:
+    """Collapse whitespace so an 80-column wrap and a rendered line agree.
+
+    Punctuation spacing is normalised too, and that is not cosmetic tidying.
+    Stripping `<strong>people</strong>,` leaves `people ,` once the tag becomes
+    a space, so an inline span inside a sentence would fail the comparison over
+    a space no reader can see. Applied to both sides, so the check still
+    compares wording and no longer compares markup.
+    """
+    text = re.sub(r"\s+", " ", text).strip()
+    text = re.sub(r"\s+([,.;:!?%)\]}\u00bb\u201d\u2019])", r"\1", text)
+    return re.sub(r"([(\[{\u00ab\u201c])\s+", r"\1", text)
+
+
+def rendered_text(root: Path) -> str | None:
+    """All built HTML as one normalised string, or None if nothing is built.
+
+    B021 asks whether the registry's string is what a reader sees, and used to
+    look for it in the component source. Two things make that unanswerable
+    there: an interpolated value never appears literally -- `{years} years,
+    installable.` cannot contain `13 years, installable.` -- and an inline
+    `<strong>` or `<a>` splits a sentence the registry stores whole. On one site
+    that was five errors nobody could fix, and both honest repairs were bad:
+    hardcode the number and lose the guarantee that it is derived, or delete the
+    rows and lose the check.
+
+    The text a reader gets exists, just not in `src/`. Tags come out, entities
+    come back, whitespace collapses, and the same comparison then answers the
+    question it was always asking.
+    """
+    if root in _rendered_cache:
+        return _rendered_cache[root]
+    out = None
+    for name in RENDER_DIRS:
+        built = root / name
+        if not built.is_dir():
+            continue
+        chunks = []
+        for page in sorted(built.rglob("*.html")):
+            html = read(page) or ""
+            html = re.sub(r"<(script|style)\b.*?</\1>", " ", html, flags=re.S | re.I)
+            html = re.sub(r"<[^>]+>", " ", html)
+            for ent, ch in _ENTITIES.items():
+                html = html.replace(ent, ch)
+            html = re.sub(r"&#(\d+);", lambda m: chr(int(m.group(1))), html)
+            chunks.append(html)
+        if chunks:
+            out = normalise(" ".join(chunks))
+            break
+    _rendered_cache[root] = out
+    return out
+
+
 def _looks_like_copy(literal: str) -> bool:
     """A quoted literal that could plausibly be user-visible text."""
     if not literal or literal[0].islower() and " " not in literal:
@@ -463,11 +533,23 @@ def check_consistency(brand_dir: Path, sources: dict) -> list[Finding]:
             lit for _q, lit in LITERAL_RE.findall(body) if _looks_like_copy(lit)
         ]
         if literals:
-            if row["text"] not in body and row["text"].strip() not in body:
+            # The registry records what a reader sees, so the built page is the
+            # authority whenever there is one. Source is the fallback and stays
+            # byte-exact for projects that do not build.
+            built = rendered_text(root)
+            if built is not None:
+                if normalise(row["text"]) not in built:
+                    findings.append(Finding(
+                        "B021", SEVERITY_ERROR, location, 0,
+                        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:
                 findings.append(Finding(
                     "B021", SEVERITY_ERROR, location, 0,
                     f"`{row['key']}` is \"{row['text']}\" in the registry, "
-                    f"but that text is not in {file_part}",
+                    f"but that text is not in {file_part} (no build found; "
+                    f"checked the source)",
                 ))
             if file_part not in swept:
                 swept.add(file_part)
@@ -507,6 +589,14 @@ def check_consistency(brand_dir: Path, sources: dict) -> list[Finding]:
                 continue
             if bare.isupper() and len(bare) <= 4:
                 continue
+            # A contraction of "I" is not Title Case, and flagging it fought a
+            # threshold this pack sets on purpose: formats.md asks for 4-8
+            # contractions per 1000 words and the first-person ones are the
+            # loudest available. Three registry rows on sshlg.me tripped this on
+            # 2026-08-15 and none of them was miscased; the writer's only repair
+            # was to delete the contraction the pack had asked for.
+            if CONTRACTED_I.match(bare):
+                continue
             if bare[0].isupper():
                 findings.append(Finding(
                     "B024", SEVERITY_ERROR, row["location"], 0,
@@ -563,6 +653,103 @@ def _front_matter(text: str) -> tuple[dict, str]:
     return fields, text[match.end():]
 
 
+# A source file is not prose, and the prose rules were reading all of it. On
+# sshlg.me that produced 20 rhetorical-dash errors inside `//` comments and 7
+# keyword-stuffing errors on `const`, `string` and `name` -- 27 standing errors
+# that no edit to the copy could clear, in a report meant to be read. A report
+# nobody can act on is a report nobody reads, which is the same failure as a
+# rule that contradicts a threshold.
+#
+# For a code file the body is its copy: the string literals `_looks_like_copy`
+# accepts, which is the definition `B022` already sweeps with. A comment is
+# addressed to a maintainer and an identifier is not a word; a brand pack has no
+# opinion about either.
+CODE_SUFFIXES = {
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+    ".py", ".go", ".rb", ".rs", ".java", ".kt", ".swift", ".php",
+}
+
+# `${...}` in a template literal is a value, not a word.
+#
+# Replaced by a space rather than dropped, so `founder of ${n} products` does not
+# collapse into one word. Substituted rather than left in place, because
+# `CODE_FRAGMENT_RE` rejects any literal carrying an interpolation -- so without
+# this line every interpolated string would fail `_looks_like_copy` and
+# interpolated copy would lose its coverage entirely. That would be a worse bug
+# than the one this fixes: on sshlg.me the whole biography is interpolated.
+INTERPOLATION_RE = re.compile(r"\$\{[^{}]*\}")
+
+
+# Languages whose line comment is `#` rather than `//`.
+HASH_COMMENT_SUFFIXES = {".py", ".rb"}
+
+
+def _strip_comments(text: str, suffix: str) -> str:
+    """Remove comments, leaving string literals untouched.
+
+    A regex cannot do this and the first version of this fix tried: `"https://x"`
+    contains `//`, and a comment can quote a phrase, which is how
+    `// "AI integrations" named nothing checkable -- and "AI" is the medium` came
+    back as a rhetorical-dash error in copy on the first run of the very change
+    that was supposed to stop reading comments.
+
+    The scanner is small because it only has to know one thing at a time:
+    whether it is currently inside a quote.
+    """
+    hashed = suffix in HASH_COMMENT_SUFFIXES
+    out: list[str] = []
+    quote = None
+    i, n = 0, len(text)
+    while i < n:
+        ch = text[i]
+        if quote:
+            out.append(ch)
+            if ch == "\\" and i + 1 < n:      # an escaped quote is not the end
+                out.append(text[i + 1])
+                i += 2
+                continue
+            if ch == quote:
+                quote = None
+            i += 1
+            continue
+        if ch in "\"'`":
+            quote = ch
+            out.append(ch)
+            i += 1
+            continue
+        if hashed and ch == "#":
+            while i < n and text[i] != "\n":
+                i += 1
+            continue
+        if not hashed and text.startswith("//", i):
+            while i < n and text[i] != "\n":
+                i += 1
+            continue
+        if not hashed and text.startswith("/*", i):
+            end = text.find("*/", i + 2)
+            i = n if end == -1 else end + 2
+            continue
+        out.append(ch)
+        i += 1
+    return "".join(out)
+
+
+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)):
+        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
+        # `"@/data/site"` counted as copy would put `data` into the density
+        # figures. B022 still sees them; these checks do not need to.
+        if " " not in candidate:
+            continue
+        if _looks_like_copy(candidate):
+            out.append(candidate)
+    return "\n\n".join(out)
+
+
 def documents(brand_dir: Path, sources: dict, key: str) -> list[tuple]:
     """(relative path, front matter, body) for one declared source key."""
     root = brand_dir.parent.parent
@@ -572,6 +759,8 @@ def documents(brand_dir: Path, sources: dict, key: str) -> list[tuple]:
             if not path.is_file():
                 continue
             fields, body = _front_matter(read(path) or "")
+            if path.suffix in CODE_SUFFIXES:
+                body = _copy_in_code(body, path.suffix)
             out.append((path.relative_to(root).as_posix(), fields, body))
     return out
 
@@ -590,17 +779,61 @@ def surfaces(brand_dir: Path) -> dict[str, dict]:
     return out
 
 
+def tables(text: str) -> list[tuple[list[str], list[list[str]]]]:
+    """The same rows, but grouped per table as (header, data rows).
+
+    `table_rows` flattens every table in a file into one list, which is right
+    for a caller that wants every row and wrong for one that wants the rows of
+    a particular table. `facts()` was the second kind and used the first: it
+    took any six-column row anywhere in facts.md, so the App Store table --
+    `Product | App Store name | id | Released | Sold | Publisher today` -- was
+    read as six fact fields. Its **Sold** year landed in `Review`, which
+    produced three "was due for review on 2022" warnings about sales that
+    completed on schedule, and its own header row became a fact called
+    `Product`. Four phantom rows in a registry of 43.
+
+    What it did **not** do, checked before this comment was written: the App
+    Store ids were already registered properly, by the `Sold-app store ids` row,
+    so the B030 corpus was never widened by the bug. Only the product names
+    entered it, and B030 only reads numbers.
+
+    A table is identified by its header, because that is the only thing in a
+    markdown table that says what its columns mean.
+    """
+    blocks, current = [], []
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("|") and stripped.endswith("|"):
+            current.append(line)
+        elif current:
+            rows = table_rows("\n".join(current))
+            if rows:
+                blocks.append((rows[0], rows[1:]))
+            current = []
+    if current:
+        rows = table_rows("\n".join(current))
+        if rows:
+            blocks.append((rows[0], rows[1:]))
+    return blocks
+
+
 def facts(brand_dir: Path) -> list[dict]:
     rows = []
-    for cells in table_rows(read(brand_dir / "facts.md") or ""):
-        if len(cells) < 6 or cells[0].strip().lower() == "fact":
+    for header, body in tables(read(brand_dir / "facts.md") or ""):
+        # Scoped by header rather than by column count -- see tables(). Any
+        # six-column table in this file used to qualify, and one of them is a
+        # product ledger whose columns mean something else entirely.
+        if len(header) < 6 or header[0].strip().lower() != "fact":
             continue
-        if unfilled(cells[0]) or unfilled(cells[1]):
-            continue
-        rows.append({
-            "fact": cells[0], "value": cells[1], "source": cells[2],
-            "checked": cells[3], "review": cells[4], "public": cells[5],
-        })
+        for cells in body:
+            if len(cells) < 6:
+                continue
+            if unfilled(cells[0]) or unfilled(cells[1]):
+                continue
+            rows.append({
+                "fact": cells[0], "value": cells[1], "source": cells[2],
+                "checked": cells[3], "review": cells[4], "public": cells[5],
+            })
     return rows
 
 
@@ -962,7 +1195,26 @@ def check_bot_safety(brand_dir: Path, sources: dict) -> list[Finding]:
                 ))
 
     records = surfaces(brand_dir)
-    for path, fields, body in documents(brand_dir, sources, "marketing"):
+    marketing = documents(brand_dir, sources, "marketing")
+
+    # Density is a property of the DOCUMENT a reader meets, and a code file is
+    # not one. A project that keeps its copy in `src/data/*.ts` splits one page
+    # across seven files, and measuring each file separately measures the split:
+    # on sshlg.me that produced six errors -- `co-founder` at 2.0% of
+    # `track-record.ts`, `account` at 1.2% of `site.ts` -- while the rendered
+    # page carried nothing above 1% and those two words sat at 0.07% and 0.04%.
+    #
+    # So the code files are pooled into one document and the markdown ones are
+    # not, because there one file really is one page. The pooled finding names
+    # the set rather than a file, since no single file is the defect.
+    pooled = [d for d in marketing if Path(d[0]).suffix in CODE_SUFFIXES]
+    per_file = [d for d in marketing if Path(d[0]).suffix not in CODE_SUFFIXES]
+    if pooled:
+        label = (f"{len(pooled)} source file(s) pooled"
+                 if len(pooled) > 1 else pooled[0][0])
+        per_file.append((label, {}, "\n\n".join(d[2] for d in pooled)))
+
+    for path, fields, body in per_file:
         words = [w.lower().strip(".,:;!?()\"'") for w in body.split()]
         real = [w for w in words if len(w) > 3 and w not in STOPWORDS]
         if len(real) >= 40:
@@ -979,6 +1231,8 @@ def check_bot_safety(brand_dir: Path, sources: dict) -> list[Finding]:
                     ))
                     break
 
+    for path, fields, body in marketing:
+
         opening = body.strip().lower()[:120]
         for filler in FILLER_OPENERS:
             if opening.startswith(filler) or f"\n{filler}" in opening: