super-ux 0.49.1 → 0.52.0

package/CHANGELOG.md

@@ -1,5 +1,154 @@
 # Changelog
 
+## 0.52.0 — the dash rule stops checking the glyph, humanization stops being a mode, and the pack learns to assemble a product
+
+- **`B062` judges the dash's role rather than its codepoint.** `DASH` was the single
+  character `—`, so a find-and-replace swapping it for `–` or for a hyphen with a space
+  each side cleared every finding and left the habit untouched. Measured in the wild on
+  trycomp.ai, 2026-08-30: twenty rhetorical dashes on one page and not one em dash among
+  them. `normalise_dash_spelling` now reduces every spelling to the canonical mark before
+  the three existing branches judge it, so the conjunction rule, the paired-dash rule,
+  the locale allowances and the range and direct-speech exemptions all apply unchanged to
+  all three spellings. The substitutions are length-preserving by construction and the
+  finding quotes the raw text, so a report shows the characters the author actually typed
+  rather than a mark they never used.
+- **A dash alone in a table cell is an empty string, and now the code agrees.** `AT-06`
+  has listed the no-value cell dash among the grammatical exemptions since it was
+  written, and nothing implemented it: in any strict locale `| landing | — |` was
+  reported. `TABLE_CELL_DASH_RE` blanks it before judgement. The doctrine is corrected in
+  the same change, because it opened "The em dash is banned where it is rhetorical" while
+  the rule it states is about the mark's role.
+- **`landing-pages.md`, a new reference in `copywriting`: how a landing page is
+  assembled, not how its sentences are edited.** Twenty rules with ids `LP-01..LP-20`
+  across five layers — the offer, awareness and the shape it demands, the proof ladder,
+  the action and the risk beside it, and the page as a machine — each carrying a verbatim
+  example from a page that shipped. It closes six gaps the pack had: no offer
+  architecture, no awareness-to-structure map, no proof ladder, no CTA or risk mechanics,
+  no answer for a category nobody searches for yet, and no readiness criterion. The file
+  ends in a runnable readiness check and says which of its rules no command can decide.
+- **`validate_landing_coverage` is the answer to "what would notice if this fell
+  behind?"** Table rows against sections in both directions, duplicate ids, a gap in the
+  sequence, an id the readiness check names that no section defines, and the
+  `copywriting/SKILL.md` link without which the reference ships to nobody. Four defects
+  planted, each caught by its own message and reverted. The validator grows 4174 → 4197
+  checks, `brand_lint_test.py` 89 → 93, and `test/floors.json` ratchets with both.
+- **The evidence is in the repository, not in a summary of it.** `docs/research/landings/`
+  carries the three teardowns the rules were extracted from — crowdreply.io, trycomp.ai
+  and zerorank.ai, read 2026-08-30 as raw markup, rendered text and in a browser. Three
+  independent pages committed the same four defects, and those four are the ones stated
+  as classes: answers absent from the markup, one action under several labels, numbers
+  that disagree with themselves, and the strongest proof filed one click behind the claim
+  it proves.
+
+## 0.50.0 — the templates ship where the texts say they are
+
+- **`templates/` now travels with everything that names it** (SUX-01, family audit
+  2026-08-29). Six shipped texts pointed at "the plugin's `templates/`" while the
+  marketplace ships `./plugins/super-ux` and the directory lived at the repo root only —
+  verified absent from all 13 cached installed versions, so `/brand-init`, `/brand`,
+  `/ux-rule` step 2 and the three seeding skills dead-ended at a path that resolves in
+  the one place users never run from: this repository's own checkout. The repo root stays
+  the single source (the hard rules and the installer CLI read it);
+  `test/sync_references.py` now mirrors the full tree into `plugins/super-ux/templates/`
+  and the named seeds into each seeding skill's own directory — a skill installed by the
+  skills CLI has no plugin root to reach up to — and the three skill texts say "this
+  skill's own `templates/…`" while the three command texts keep "the plugin's
+  `templates/…`", which is now true.
+- **The class is gated, not just the instance.** `validate_shipped_templates` refuses a
+  copy that drifts from its source and a copy with no source, in both homes;
+  `validate_shipped_paths` requires every backticked `templates/…` or `scripts/…` token
+  in a shipped text to resolve inside what actually ships — the plugin root for commands,
+  the skill's own directory for skill files. Six defects planted, each caught by its own
+  branch with its own message, each reverted; the sync verified idempotent across three
+  runs. The validator grows 4111 → 4174 checks and `test/floors.json` ratchets with it.
+- **`/ux-audit` admits its whole scope surface** (SUX-06). `copy` and
+  `benchmark:<competitor>` join the `argument-hint` and the step-1 enumeration — the body
+  has treated both as legal scopes since they shipped, while the two places an agent
+  reads first omitted them.
+- **Trigger hygiene in three descriptions** (SUX-07, SUX-08, SUX-11). `ux-scenarios`
+  defers the empty-project start up the chain — vision and ux-foundation own it — instead
+  of claiming "ANY new feature or project" unqualified; `copywriting` narrows "build a
+  landing page / сделай лендинг" to the copy for it, naming sheleg-design as the visual
+  half; `ux-flows` drops the bare "figma"/"фигма" claim and delegates the visual system
+  and Figma variables to sheleg-design, mirroring its own body. Every phrase the family
+  umbrella routes on remains a literal substring of its description — verified with the
+  umbrella's own `advertised_check.js` (43/43, and watched failing against a dropped
+  «мокап»).
+- **Humanization runs by default, in every mode that produces text.** It was a mode you
+  had to know to ask for, so the common path produced unswept drafts, and the one field
+  that touched the question -- `Humanization pass:` -- existed **only in the template**:
+  absent from `brand-contract.md`, absent from this pack's own `voice.md`, and read by no
+  code anywhere. Two fields now answer the two different questions the old one conflated.
+  `Humanization: on | off` is whether the pass runs, defaulting to `on` when absent;
+  `Humanization pass:` names which implementation, defaulting to `own`. Write, Edit and
+  Adapt each end in the sweep, positioned where it cannot be wasted: after the seven
+  sweeps in Edit, per surface in Adapt. `Humanize` survives as the standalone mode for
+  auditing text nobody is writing.
+- **The state is visible in four places, because a pass that runs invisibly is
+  indistinguishable from one that did not.** `voice.md` records it, every delivery of copy
+  prints a status line naming the pass and what it changed, `/ux` and `/brand` report it
+  in their status blocks, and `B064` refuses the three states that are defects: an absent
+  field warns that the default applies unrecorded, an out-of-enum value errors, and `off`
+  with no `Humanization declined:` reason errors. The enum joins
+  `validate_status_enums_match_contract` from the day it was written rather than after it
+  drifted, which required generalising `DOC_ENUM_DECL_RE` past the hardcoded `**Status**`
+  so the next document-level enum is compared too.
+- **`header_field` stops swallowing an aligned comment.** Standing instruction #3 fired on
+  the first enum field the templates seed with a literal value beside a comment: the
+  freshly seeded pack errored because the whole line, `# on | off; on is the default`
+  included, was the value. Two spaces or more before a `#` now ends the value; one space
+  does not, so a `Humanization declined: per ticket #431` keeps its reason.
+- **Three references give the pack the assembly layer above its 241 tactics.**
+  `onboarding.md` (`ON-01..ON-18`, in `ux-flows`) orders the path to the first value and
+  rests on that value being defined first. `internal-screens.md` (`IS-01..IS-18`, in
+  `ux-flows`) covers the screens nobody A/B tests, where the four states are one design
+  and a list is a working surface rather than a directory of links.
+  `product-frameworks.md` (`PF-01..PF-12`, in `ux-foundation`) carries the named decision
+  models the pack had **none** of -- measured: Hook, Fogg, Kano, opportunity solution
+  tree, AARRR, north star, time to value, value proposition canvas, forces of progress,
+  switch interview, service blueprint and double diamond all returned zero occurrences --
+  each with the failure mode that makes it worth knowing rather than worth quoting.
+- **One coverage gate over four id sets, not four copies of one.**
+  `validate_landing_coverage` became `validate_doctrine_set_coverage`, parameterised over
+  `LP`, `ON`, `IS` and `PF`: rows against sections both ways, duplicates, sequence gaps,
+  an id the readiness check names that no section defines, and the `SKILL.md` link without
+  which a reference ships to nobody. A fourth hand-written copy of one comparison is the
+  drift the gate exists to refuse.
+- **The board went to zero.** All eleven open rows closed with a mechanism and a watched
+  plant each, not with a status change. `B-029` got the decision it asked for rather than a
+  filter: `strings.md` gains `Kind: copy | layout`, so an aligned option table is registered
+  and exempt from the rules that would be judging typesetting, and `docs/brand/lint.py` now
+  prints `brand pack is clean` where it printed a permanent warning. `B-028`: a `Coverage:`
+  citation may name its subject (`path:start-end symbolName`) and `U078` resolves it, catching
+  the drift a range cannot report about itself. `B-023`: `B005` asks `git log -L` about the
+  cited entries rather than the whole file, so a jobs edit stops warning about personas.
+  `B-005`: `U076` says a vision is still the seeded template instead of passing until someone
+  self-declares `approved`. `B-001`: the seeded linter carries `VISION_RULE_TEXT`, `U077` warns
+  when a target project's installed rule differs, and `validate_vision_rule_embed` keeps that
+  third copy honest. `B-030` and `B-031` get contract-parity gates; `B-032` gets `test/evals/`
+  with four cases whose anchors must still resolve.
+- **Two of the eleven turned out not to be what the board said.** `B-021` asked for a
+  reachability arrow that had existed inside `validate_bp_index` since before the row was
+  filed; a duplicate check was written, caught by planting `BP-242`, and deleted rather than
+  shipped. What was genuinely missing ran the other way: a routing row pointing at a `BP-NNN`
+  the catalog does not define, invisible because every check in that function starts from the
+  catalog. `B-019` did not reproduce in four probes; it had been fixed by an uncredited
+  refactor, and the class is now mechanical — the report prints each distinct message once and
+  names any duplicate emission.
+- **The refreshed code graph asserted a number nobody computed.** `B-022`'s refresh ran
+  unattended (1149 nodes, 1801 edges, built from `6348b641`), and 58 label fields said
+  `82 tags, 206 practices` about a catalog of 241 and an index that states no counts at all —
+  cached across refreshes, and read with the authority of a machine. Corrected, and gated by
+  `validate_graph_claims`, narrowed to `label`/`norm_label` because a node summarising a past
+  defect legitimately quotes an old number, and one of them does.
+- **The bytecode cache could defeat a planted defect, which is this project's unit of
+  evidence.** CPython invalidates on `(mtime, size)`, so swapping `"B064"` for `"B999"` --
+  identical length -- and reverting inside the same second left a `.pyc` the interpreter
+  considered current: the revert ran the plant and the transcript reported a defect no
+  longer in the file. Observed live during this run's own plants. Both harnesses now set
+  `sys.dont_write_bytecode`, verified by plant-then-revert-in-second going red then green
+  with no cache clear.
+
 ## 0.49.1 — the skills handoff refuses the shadow it used to create
 
 - **The skills-menu item now consults the target home before delegating.** `npx skills add`

package/README.md

@@ -157,7 +157,7 @@ Commands: `/brand` (status → one recommended action), `/brand-init`,
 python3 docs/brand/lint.py
 ```
 
-39 deterministic checks (`B001`..`B073`): banned words, one action under two names, a figure
+41 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
@@ -248,7 +248,7 @@ to is a skill nobody runs.
 | `/vision` `/ux-init` `/ux-foundation` `/ux-flows` `/ux-update` `/ux-audit` `/ux-rule` `/ux-lint` `/ux-doctor` · `/brand` `/brand-init` `/brand-update` `/brand-lint` `/copy` | Direct controls for when you know exactly what you want; `/ux-rule` installs both hard rules and seeds `lint.py` + `doctor.py`; `/brand-init` seeds `docs/brand/` and its linter |
 | `docs/ux/lint.py` + `/ux-lint` | The deterministic half: missing Figma frames, unresolved SCR/story traces, orphans, built screens without coverage, index desync, ID gaps, broken links. Stdlib-only, exit 1 on problems, so wire it into CI and drift can't merge |
 | `cursor/rules/*.mdc` | The same methodology for Cursor: one always-on hard rule + seven agent-requested rules (vision, foundation, flows, scenarios, audit, brand voice, copywriting) |
-| `templates/` | Seeds for `docs/ux/`: the vision skeleton, foundation, flows, screens, scenario base, the folder README, and the audit-report skeleton. Both hard-rule snippets live here as their single source, `claude-rule.md` (scenario-first) and `vision-rule.md` (vision alignment), and the validator fails if a command's embedded copy drifts from them. Seeds for `docs/brand/`: voice, terminology, facts, channels, the string registry, a locale delta, and its folder README |
+| `templates/` | Seeds for `docs/ux/`: the vision skeleton, foundation, flows, screens, scenario base, the folder README, and the audit-report skeleton. Both hard-rule snippets live here as their single source, `claude-rule.md` (scenario-first) and `vision-rule.md` (vision alignment), and the validator fails if a command's embedded copy drifts from them. Seeds for `docs/brand/`: voice, terminology, facts, channels, the string registry, a locale delta, and its folder README. The tree is mirrored into `plugins/super-ux/templates/` (and the seeds each skill names into that skill's own directory) by `test/sync_references.py`, so installed channels carry the seeds their texts point at; the validator refuses drift between the copies |
 
 The contracts every skill reads:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-ux",
-  "version": "0.49.1",
+  "version": "0.52.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 && node test/installer_test.js"
   },

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

@@ -56,6 +56,24 @@ CONTRACT_VERSION = "v1"
 # out-of-enum value that is neither refused nor accepted, and invisible.
 VOICE_STATUSES = ("draft", "validated")
 
+# Whether the humanization pass runs at all, which is a different question from
+# `Humanization pass:`, which names WHICH implementation runs. `on` is the
+# pack's default and it is a default rather than a preference: an unswept draft
+# carries the markers `ai-tells.md` grades, and a reader registers them before
+# they can name why. Turning it off is a legitimate decision and it IS a
+# decision, so it leaves its reason in the file instead of a silence that reads
+# identically to never having been asked.
+HUMANIZATION_MODES = ("on", "off")
+
+# What a registry row IS, which decides which rules may judge it. `copy` is
+# language and every language rule applies. `layout` is a column-aligned table,
+# an ASCII frame, a banner: a string whose shape carries the meaning, where a
+# capitalisation or dash rule would be judging typesetting. It is registered
+# rather than exempted from registration, so `B022` still knows it exists and
+# nobody can hide a real string by calling it furniture. Absent, a row is
+# `copy`, because the safe default is to check.
+STRING_KINDS = ("copy", "layout")
+
 SEVERITY_ERROR = "error"
 SEVERITY_WARN = "warn"
 
@@ -122,10 +140,74 @@ def content_date(path: Path) -> str | None:
         return None
 
 
+# A trailing comment, aligned away from the value the way the seeded templates
+# write one. Two spaces or more, because one space is prose: a `Humanization
+# declined:` reason may legitimately say "per ticket #431", and truncating it
+# would read as no reason at all. Found by standing instruction #3 on the first
+# enum field the templates seeded with a literal value beside a comment.
+HEADER_COMMENT_RE = re.compile(r"[ \t]{2,}#.*$")
+
+
+def entry_line_span(text: str, ident: str) -> tuple[int, int] | None:
+    """The 1-based line span of `### <ident>:` up to the next entry or section."""
+    lines = text.split("\n")
+    start = next((i for i, l in enumerate(lines, 1)
+                  if l.startswith(f"### {ident}:")), None)
+    if start is None:
+        return None
+    for j in range(start, len(lines)):
+        if lines[j].startswith("### ") or lines[j].startswith("## "):
+            return start, j
+    return start, len(lines)
+
+
+def cited_entries_date(path: Path, idents: list[str]) -> tuple[str | None, bool]:
+    """When the CITED entries last changed, not when the file did.
+
+    `B-023`: `B005` asked whether `foundation.md` had moved since the voice was
+    calibrated, and every entry in it shares one file date, so editing the
+    monetization section raised a warning about personas nobody had touched.
+    Measured on SU-02: seven story entries changed, zero changed lines
+    mentioned any cited id, and the gate went red with a re-stamp as the only
+    way out. A warning that fires when nothing it protects moved is one people
+    learn to re-stamp past.
+
+    Returns `(date, exact)`. `exact` is False when the per-entry question could
+    not be answered -- no git, an untracked file, a renamed entry -- and the
+    whole-file date was used instead, which is the old behaviour. The caller
+    says which it got, because a narrowed check that silently widens is worse
+    than one that never narrowed.
+    """
+    text = read(path) or ""
+    spans = [entry_line_span(text, i) for i in idents]
+    if not spans or any(sp is None for sp in spans):
+        return content_date(path), False
+    import subprocess
+
+    dates: list[str] = []
+    for span in spans:
+        assert span is not None
+        try:
+            out = subprocess.run(
+                ["git", "log", "-L", f"{span[0]},{span[1]}:{path.name}",
+                 "--format=%cs", "-s", "-1"],
+                cwd=path.parent, capture_output=True, text=True, timeout=15,
+            )
+        except (OSError, subprocess.SubprocessError):
+            return content_date(path), False
+        stamp = out.stdout.strip().split("\n")[0].strip()
+        if out.returncode != 0 or not re.fullmatch(r"\d{4}-\d{2}-\d{2}", stamp):
+            return content_date(path), False
+        dates.append(stamp)
+    return (max(dates) if dates else None), True
+
+
 def header_field(text: str, key: str) -> str | None:
-    """A `Key: value` line from a file's header block."""
+    """A `Key: value` line from a file's header block, comment stripped."""
     match = re.search(rf"^{re.escape(key)}:\s*(.+?)\s*$", text, re.M)
-    return match.group(1) if match else None
+    if not match:
+        return None
+    return HEADER_COMMENT_RE.sub("", match.group(1)).strip() or None
 
 
 def table_rows(text: str) -> list[list[str]]:
@@ -218,8 +300,39 @@ def check_contract(brand_dir: Path) -> list[Finding]:
             f"check tests for the value instead of against `draft`",
         ))
 
+    # B064 -- the humanization pass: does it run, and was that decided.
+    # Three branches, one code, and each is reachable only in the state the
+    # others are not: absent, present-and-illegal, present-legal-and-off. A
+    # fixture for one therefore cannot be satisfied by another firing.
+    humanization = header_field(voice, "Humanization")
+    if humanization is None:
+        findings.append(Finding(
+            "B064", SEVERITY_WARN, "voice.md", 1,
+            f"no `Humanization:` field, so the pack default `on` applies and "
+            f"nobody has recorded whether that was chosen -- write "
+            f"`Humanization: on` to make the state readable, here and in every "
+            f"status this pack prints",
+        ))
+    elif not unfilled(humanization):
+        if humanization not in HUMANIZATION_MODES:
+            findings.append(Finding(
+                "B064", SEVERITY_ERROR, "voice.md", 1,
+                f"`Humanization: {humanization}` is not one of "
+                f"{' | '.join(HUMANIZATION_MODES)} -- an unrecognised value "
+                f"leaves the pass in neither state, and the copy modes read "
+                f"this field to decide whether to run",
+            ))
+        elif humanization == "off" and not header_field(voice, "Humanization declined"):
+            findings.append(Finding(
+                "B064", SEVERITY_ERROR, "voice.md", 1,
+                f"`Humanization: off` with no `Humanization declined:` line -- "
+                f"switching the pass off is a decision and it outlives whoever "
+                f"made it, so it carries the reason and the date rather than "
+                f"reading, later, as an oversight nobody can safely reverse",
+            ))
+
     strings = read(brand_dir / "strings.md") or ""
-    agreed = [r for r in table_rows(strings) if r and r[-1] == "agreed"]
+    agreed = [r for r in registry(brand_dir) if r["status"] == "agreed"]
     if status == "draft" and agreed:
         findings.append(Finding(
             "B003", SEVERITY_WARN, "voice.md", 1,
@@ -243,12 +356,19 @@ def check_contract(brand_dir: Path) -> list[Finding]:
         calibrated = header_field(voice, "Last calibrated")
         if foundation is not None and calibrated:
             try:
-                changed = content_date(brand_dir.parent / "ux" / "foundation.md")
+                changed, exact = cited_entries_date(
+                    brand_dir.parent / "ux" / "foundation.md", ids
+                )
                 if changed and changed > calibrated:
+                    what = (f"the entries this voice cites ({', '.join(ids)}) "
+                            f"changed" if exact else
+                            "foundation.md changed, and the per-entry question "
+                            "could not be answered here so the whole file was "
+                            "used")
                     findings.append(Finding(
                         "B005", SEVERITY_WARN, "voice.md", 1,
-                        f"foundation.md changed on {changed}, after the voice "
-                        f"was last calibrated on {calibrated}",
+                        f"{what} on {changed}, after the voice was last "
+                        f"calibrated on {calibrated}",
                     ))
             except OSError:
                 pass
@@ -303,6 +423,10 @@ def registry(brand_dir: Path) -> list[dict]:
         rows.append({
             "key": cells[0], "text": cells[1], "location": cells[2],
             "scenario": cells[3], "status": cells[4],
+            # Sixth column, appended so a five-column registry written before
+            # this existed keeps every index it had. Absent means `copy`.
+            "kind": (cells[5].strip() if len(cells) > 5 and cells[5].strip()
+                     else "copy"),
         })
     return rows
 
@@ -358,6 +482,16 @@ def check_terminology(brand_dir: Path) -> list[Finding]:
     findings: list[Finding] = []
     banned, terms, entities = dictionary(brand_dir)
     for row in registry(brand_dir):
+        if row["kind"] not in STRING_KINDS:
+            findings.append(Finding(
+                "B065", SEVERITY_ERROR, "strings.md", 0,
+                f"`{row['key']}` has `Kind: {row['kind']}`, which is not one of "
+                f"{' | '.join(STRING_KINDS)} -- an unrecognised kind is treated "
+                f"as `copy` and judged by every language rule, so the row is "
+                f"neither exempt nor knowingly checked",
+            ))
+        if row["kind"] == "layout":
+            continue
         text = row["text"]
         for word in banned:
             if _mentions(word, text):
@@ -575,6 +709,8 @@ def check_consistency(brand_dir: Path, sources: dict) -> list[Finding]:
     for row in rows:
         if not LABEL_KEY_RE.match(row["key"]):
             continue
+        if row["kind"] == "layout":
+            continue        # a terminal full stop inside a frame is not a title
         text = row["text"].rstrip()
         if not text.endswith(".") or text.endswith("..") or text.endswith("…"):
             continue
@@ -649,6 +785,8 @@ def check_consistency(brand_dir: Path, sources: dict) -> list[Finding]:
     for name in entity_words:
         proper.update(name.split())
     for row in rows:
+        if row["kind"] == "layout":
+            continue        # casing in a column-aligned table is typesetting
         # Escape sequences are not words: "\\n--- Skills for ..." begins with a
         # token whose only letter is the n of \\n.
         readable = re.sub(r"\\[nrt]|\\x[0-9a-fA-F]{2}\[[0-9;]*[A-Za-z]", " ",
@@ -1153,6 +1291,26 @@ EMOJI_RE = re.compile(
 # can actually be established without parsing the sentence.
 DASH = "—"
 
+# Every spelling of the same mark. The tell is the ROLE the dash plays, not
+# the codepoint it is written with: swapping "—" for "–", or for a hyphen
+# with a space each side, leaves the habit exactly where it was, and a check
+# bound to one codepoint cannot see that it happened. Measured on
+# trycomp.ai, 2026-08-30: twenty rhetorical dashes, zero em dashes, every
+# one of them written " - ". See `docs/research/landings/trycomp.md`.
+DASH_ALIASES = "–‒―"
+
+# A dash alone in a table cell stands for "no value": a glyph doing the job
+# of an empty string, not punctuation joining two clauses. AT-06 has said so
+# since it was written, and until the spellings were normalised nothing
+# implemented it, so a bare cell dash was reported in every strict locale.
+TABLE_CELL_DASH_RE = re.compile(rf"(?<=\|)([ \t]*)[{DASH}{DASH_ALIASES}-]([ \t]*)(?=\|)")
+
+# A hyphen with whitespace on both sides, mid-line. The lookbehind is what
+# keeps a markdown bullet out of it: a list item's hyphen opens its line, so
+# nothing non-space precedes the indent in front of it.
+DASH_HYPHEN_RE = re.compile(r"(?<=\S)([ \t]+)-([ \t]+)(?=\S)")
+DASH_ALIAS_RE = re.compile(rf"[{DASH_ALIASES}]")
+
 # Never a finding. A range is arithmetic and direct speech is a convention.
 DASH_RANGE_RE = re.compile(rf"\d\s*{DASH}\s*\d")
 DASH_SPEECH_RE = re.compile(rf"^\s*{DASH}\s")
@@ -1185,6 +1343,19 @@ def prose_only(text: str) -> str:
     return text
 
 
+def normalise_dash_spelling(text: str) -> str:
+    """Reduce every spelling of the rhetorical mark to the canonical dash.
+
+    Length-preserving by construction -- every substitution swaps a single
+    character for a single character -- so a finding can quote the author's
+    own characters while the branches below judge the normalised ones. A
+    quote showing a dash the author never typed sends them grepping for it.
+    """
+    text = TABLE_CELL_DASH_RE.sub(r"\1 \2", text)
+    text = DASH_HYPHEN_RE.sub(rf"\1{DASH}\2", text)
+    return DASH_ALIAS_RE.sub(DASH, text)
+
+
 def sentences(text: str) -> list[str]:
     """Crude split, sufficient to count dashes inside one sentence."""
     return [p for p in re.split(r"(?<=[.!?])\s+|\n\s*\n", text) if p.strip()]
@@ -1203,14 +1374,22 @@ def grammatical_dash_language(text: str, primary: str | None) -> bool:
     return bool(CYRILLIC_RE.search(text))
 
 
-def _around(sentence: str, width: int = 34) -> str:
-    """The dash with enough either side to find it and decide the fix."""
-    flat = " ".join(sentence.split())
-    at = flat.find(DASH)
+def _around(sentence: str, original: str | None = None, width: int = 34) -> str:
+    """The dash with enough either side to find it and decide the fix.
+
+    `sentence` is normalised and `original` is what the author wrote. The
+    position comes from the first and the characters from the second, which
+    is why the substitutions above are length-preserving: a quote is only
+    useful if it can be found in the file it came from.
+    """
+    source = sentence if original is None else original
+    at = sentence.find(DASH)
     if at < 0:
-        return flat[:width * 2]
-    start, end = max(0, at - width), min(len(flat), at + width)
-    return ("…" if start else "") + flat[start:end] + ("…" if end < len(flat) else "")
+        return " ".join(source.split())[:width * 2]
+    start, end = max(0, at - width), min(len(source), at + width)
+    return (("…" if start else "")
+            + " ".join(source[start:end].split())
+            + ("…" if end < len(source) else ""))
 
 
 def dash_findings(code: str, path: str, text: str, strict: bool) -> list[Finding]:
@@ -1222,7 +1401,8 @@ def dash_findings(code: str, path: str, text: str, strict: bool) -> list[Finding
     off rather than obeyed.
     """
     findings: list[Finding] = []
-    body = prose_only(text)
+    raw = prose_only(text)
+    body = normalise_dash_spelling(raw)
     if DASH not in body:
         return findings
 
@@ -1246,14 +1426,17 @@ def dash_findings(code: str, path: str, text: str, strict: bool) -> list[Finding
                 break
         return best
 
-    for sentence in sentences(body):
+    # `raw` and `body` are the same length and split at the same points --
+    # normalisation touches neither terminal punctuation nor newlines -- so
+    # the two sentence lists stay aligned and the quote comes from the raw.
+    for sentence, original in zip(sentences(body), sentences(raw)):
         if DASH not in sentence:
             continue
         if DASH_SPEECH_RE.match(sentence):
             continue
 
         line = line_of(sentence)
-        quoted = _around(sentence)
+        quoted = _around(sentence, original)
 
         conj = DASH_CONJ_RE.search(sentence)
         if conj:
@@ -1429,6 +1612,8 @@ def check_ai_tells(brand_dir: Path, sources: dict) -> list[Finding]:
             findings.extend(dash_findings("B062", path, body, strict))
 
     for row in registry(brand_dir):
+        if row["kind"] == "layout":
+            continue
         strict = not grammatical_dash_language(row["text"], primary)
         findings.extend(dash_findings("B062", row["location"], row["text"], strict))
 

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

@@ -141,6 +141,55 @@ def screen_blocks(text: str) -> dict[str, str]:
     return entry_blocks(text, "SCR")
 
 
+def coverage_subjects(cov: str, root: Path) -> list[tuple[str, str]]:
+    """Citations that name a subject, and whether the subject is still there.
+
+    `B-028`: a range proves its bounds and nothing else. `U071` resolves whether
+    the cited lines exist, which caught `bin/super-ux.js:99000-99999` in a
+    396-line file, and cannot catch `223-284` once `selectInteractive` has moved
+    to `235-296` -- the exact drift that was live in this pack's own
+    `screens.md` for a release. Bounds are all a range can prove about itself.
+
+    So a citation may name what it is about: `path:start-end symbolName`, the
+    symbol separated by a space inside the same backticks. When it does, this
+    resolves the symbol in the file and answers whether it is inside the span.
+
+    It proves the subject is WITHIN the range, not that the range is exactly the
+    subject, and that is the honest limit: matching a definition's full extent
+    needs a parser per language, and a check that claimed to do it would be
+    asserting what it has not measured. Returns `(citation, symbol)` pairs that
+    failed.
+    """
+    bad: list[tuple[str, str]] = []
+    for token in re.findall(r"`([^`]+)`", cov):
+        parts = token.split()
+        if len(parts) != 2:
+            continue
+        citation, symbol = parts
+        if not re.fullmatch(r"[A-Za-z_$][\w$]*", symbol):
+            continue
+        path, _, span = citation.partition(":")
+        match = re.fullmatch(r"(\d+)(?:-(\d+))?", span)
+        target = root / path
+        if not match or not target.exists():
+            continue
+        try:
+            lines = target.read_text(encoding="utf-8").splitlines()
+        except (OSError, UnicodeDecodeError):
+            continue
+        start = int(match.group(1))
+        stop = int(match.group(2)) if match.group(2) else start
+        word = re.compile(rf"\b{re.escape(symbol)}\b")
+        here = [i for i, l in enumerate(lines, 1)
+                if start <= i <= stop and word.search(l)]
+        if here:
+            continue
+        elsewhere = [i for i, l in enumerate(lines, 1) if word.search(l)]
+        bad.append((citation, symbol if not elsewhere
+                    else f"{symbol} (found at line {elsewhere[0]})"))
+    return bad
+
+
 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.
 
@@ -650,6 +699,33 @@ VISION_SECTIONS = [
 ]
 
 VISION_RULE_HEADING = "## Vision alignment — hard rule (super-ux)"
+
+# `B-001`: `validate_hard_rule_copies` compares the template against the copy
+# embedded in the `vision` skill, and both live in THIS repository. A target
+# project's `CLAUDE.md` carries a third copy, installed once and never compared
+# to anything again, so a rule softened by hand or left behind by an upgrade
+# reads exactly like a rule being obeyed. This linter is seeded into that
+# project, so it is the only thing there that can hold the canonical text.
+# `validate.py` gates this constant against `templates/vision-rule.md`, which
+# keeps the number of sources at one.
+VISION_RULE_TEXT = """\
+## Vision alignment — hard rule (super-ux)
+
+Before planning any new feature, capability or significant change, check it
+against `docs/ux/vision.md` — specifically the **anti-vision** and the
+**alignment test**.
+
+**Aligned** → proceed, and say in one line which part of the vision it serves.
+
+**Misaligned** → stop and say so before writing code:
+1. Name the conflict — which layer it contradicts, quoting that layer.
+2. Offer two paths: (a) reshape the feature to fit, with the specific change;
+   (b) amend the vision, saying which layer changes and what that costs.
+3. Wait for the decision. Do not pick one silently.
+
+**Do NOT trigger for:** bug fixes, refactors, dependency work, tests,
+documentation, or anything with no user-facing surface. A vision check on a
+typo fix is how a team learns to skip the check that matters."""
 INSTRUCTION_FILES = ("CLAUDE.md", "AGENTS.md", "GEMINI.md")
 
 
@@ -679,16 +755,59 @@ def check_vision(ux: Path, vision: str) -> None:
                     err(f"[U031] vision.md: approved but '## {section}' is empty — "
                         f"the section that settles arguments cannot be blank")
 
+    # `B-005`: the seeded template is nine headings above HTML comments, and
+    # `read()` strips comments, so a project that seeds it and writes nothing
+    # passes every check here until somebody self-declares `approved`. Silence
+    # then reads as a vision, and the alignment rule the `vision` skill
+    # installs starts arbitrating against a blank document. A warning rather
+    # than an error, because a new project legitimately starts here: the defect
+    # is not that it is empty, it is that nothing said so.
+    def _authored(section: str) -> bool:
+        parts = re.split(rf"^##\s+{re.escape(section)}\s*$", vision, maxsplit=1,
+                         flags=re.MULTILINE)
+        if len(parts) != 2:
+            return False
+        tail = re.split(r"^##\s", parts[1], maxsplit=1, flags=re.MULTILINE)[0]
+        # A `<placeholder>` is the template asking a question, not an answer,
+        # and `read()` strips only HTML comments. Section 9 ships three of them
+        # as a numbered list, which is why "is anything written here" cannot be
+        # answered by `.strip()` alone -- found by watching this check stay
+        # silent on the pristine seed it was written for.
+        tail = re.sub(r"<[^<>\n]{0,120}>", "", tail)
+        tail = re.sub(r"^\s*(?:[-*+]|\d+\.)\s*$", "", tail, flags=re.MULTILINE)
+        return bool(tail.strip())
+
+    written = [s for s in VISION_SECTIONS if _authored(s)]
+    if not approved and not written:
+        warn(f"[U076] vision.md is still the seeded template — all "
+             f"{len(VISION_SECTIONS)} sections are headings with nothing under "
+             f"them, so the alignment rule is arbitrating against a blank "
+             f"document. Write it, or delete the file until you do")
+
     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("[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):
+    carrying = [p for p in present if VISION_RULE_HEADING in read(p)]
+    if not carrying:
         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)")
+        return
+    for path in carrying:
+        text = read(path)
+        start = text.index(VISION_RULE_HEADING)
+        tail = text[start + len(VISION_RULE_HEADING):]
+        stop = re.search(r"^##\s", tail, re.MULTILINE)
+        installed = (VISION_RULE_HEADING
+                     + (tail[:stop.start()] if stop else tail)).strip()
+        if installed != VISION_RULE_TEXT.strip():
+            warn(f"[U077] {path.name}: the installed vision rule differs from the "
+                 f"one this version ships — a rule edited by hand or left behind "
+                 f"by an upgrade reads exactly like a rule being obeyed. Re-run "
+                 f"the `vision` skill's step 4, or keep the edit deliberately")
 
 
 def check_links(ux: Path) -> None:
@@ -849,6 +968,10 @@ def main() -> int:
                     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 citation, symbol in coverage_subjects(cov, screens_root):
+                    warn(f"[U078] screens.md: {sid} cites '{citation}' as covering "
+                         f"`{symbol}`, which is not inside those lines — the range "
+                         f"proves its bounds and the subject is what it is about")
                 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 "

package/templates/brand/voice.md

@@ -5,7 +5,8 @@ Locale parity threshold: 80%
 Derived-from: <P-NN, JTBD-NN from docs/ux/foundation.md — or `inferred`>
 Status: draft
 Last calibrated: <YYYY-MM-DD>
-Humanization pass: <own | humanizer | avoid-ai-writing | none>   # optional; absent = ask once
+Humanization: on                    # on | off; on is the default, off needs a reason below
+Humanization pass: <own | humanizer | avoid-ai-writing>   # optional; absent = own
 
 # Voice